Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tracewayapp/opentelemetry-symfony-bundle/llms.txt

Use this file to discover all available pages before exploring further.

The bundle ships native AWS X-Ray support through two optional configuration keys — propagator: xray and id_generator: xray — that replace the default W3C propagation and ID generation with their AWS equivalents. Both options require the open-telemetry/contrib-aws Composer package, and a clear LogicException is thrown at container boot if that package is absent when either key is set.

​
Prerequisites

Install the AWS contrib package before enabling either X-Ray option: 
composer require open-telemetry/contrib-aws

​
Setup

1

Install the contrib-aws package

The open-telemetry/contrib-aws package provides both the X-Amzn-Trace-Id propagator and the epoch-prefixed ID generator used by the X-Ray UI. It is an optional dependency of the bundle and is not installed by default.
composer require open-telemetry/contrib-aws
2

Configure propagator and id_generator

Add the two X-Ray keys to your config/packages/open_telemetry.yaml. Both keys are independent — you can use just the propagator, just the ID generator, or both together.
# config/packages/open_telemetry.yaml
open_telemetry:
    traces:
        propagator: xray       # inject/extract X-Amzn-Trace-Id headers
        id_generator: xray     # epoch-prefixed trace IDs for X-Ray's timeline UI
3

Point the OTLP exporter at your ADOT Collector

The AWS Distro for OpenTelemetry (ADOT) Collector is the recommended receiver when running on AWS. Set the endpoint and protocol via environment variables — no bundle config change is needed.
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317   # ADOT Collector address
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
Running ADOT as a sidecar on the same host lets you use localhost:4317 for near-zero network overhead. Swap for http/protobuf if you prefer to avoid the gRPC extension.

​
Propagator modes

The propagator key controls which HTTP headers carry trace context between services. Choose the mode that matches your deployment.
ValueHeader written / readUse when
w3c (default)traceparent / tracestateAll non-X-Ray backends
xrayX-Amzn-Trace-IdFull X-Ray setup — all services speak X-Ray
w3c+xrayBothMigrating from W3C to X-Ray; services that accept either format
w3c+xray is implemented as a MultiTextMapPropagator wrapping both TraceContextPropagator and the X-Ray propagator, so every outgoing request and incoming extraction writes and reads both header formats simultaneously.
All context propagation in the bundle — outgoing HttpClient requests, Messenger stamps, and incoming request extraction — reads from Globals::propagator(). Switching the propagator key is therefore automatic and complete across every instrumented component; no per-integration changes are needed.

​
X-Ray ID generator

Setting id_generator: xray makes the bundle build a TracerProvider using the standard SDK env-var auto-configuration (OTEL_TRACES_EXPORTER, OTEL_TRACES_SAMPLER, OTEL_PHP_TRACES_PROCESSOR) and substitutes in the X-Ray ID generator. The X-Ray ID generator produces 32-character hex trace IDs whose first 8 characters encode the Unix timestamp of the root span. X-Ray’s UI uses this epoch prefix to render request times in its trace list without fetching the full trace body — which means timestamps appear instantly in the console even on high-cardinality services.
id_generator: xray makes the bundle own the TracerProvider. If you also bootstrap your own TracerProvider in code, initialise it before the Symfony kernel boots so the bundle’s initializer, which registers later via Globals::registerInitializer(), can take precedence. For setups that rely only on OTEL_* environment variables this ordering is handled automatically.

​
Error handling

If open-telemetry/contrib-aws is not installed and you set propagator: xray, propagator: w3c+xray, or id_generator: xray, the XRayBootstrapper service will throw a \LogicException at container boot with the message:
X-Ray support requires "open-telemetry/contrib-aws". Run: composer require open-telemetry/contrib-aws
This happens at construction time so the error is caught early during bin/console cache:warmup rather than at the first request.

Build docs developers (and LLMs) love

Get started for freeTalk to us