Full YAML Configuration Reference

All configuration is optional — the bundle works out of the box with zero YAML. When you need to customise behaviour, create config/packages/open_telemetry.yaml and add only the keys you want to change; every option shown below is already applied as a default.

Annotated full configuration

The block below lists every accepted key with its default value and an inline comment explaining what it does.

open_telemetry:
    traces:
        enabled: true
        tracer_name: 'opentelemetry-symfony'

        # URL path prefixes excluded from HTTP request tracing
        excluded_paths: []
        record_client_ip: true             # disable for GDPR compliance
        error_status_threshold: 500        # range 400–599; responses >= this are marked ERROR

        console:
            enabled: true
            excluded_commands: [messenger:consume, messenger:consume-messages]

        http_client:
            enabled: true
            excluded_hosts: []             # OTLP endpoint host is auto-excluded

        messenger:
            enabled: true
            root_spans: false              # true = standalone root span per consumed message

        scheduler:
            enabled: true                  # suppresses duplicate Messenger spans for scheduled tasks

        mailer:
            enabled: true
            record_subject: false          # subjects can contain personal data (PII)

        doctrine:
            enabled: true
            record_statements: true        # false = hide SQL text from spans

        cache:
            enabled: true
            excluded_pools: []             # service IDs to skip, e.g. cache.system

        propagator: w3c                    # w3c | xray | w3c+xray
        id_generator: default              # default | xray

        twig:
            enabled: true
            excluded_templates: []

    metrics:
        enabled: false                     # master switch; must be true for any subsystem metric
        meter_name: 'opentelemetry-symfony'

        messenger:
            enabled: false
            excluded_queues: []            # receiver names to skip

        doctrine:
            enabled: false

        http_server:
            enabled: false
            excluded_paths: []             # same prefix-match rules as traces.excluded_paths

        http_client:
            enabled: false
            excluded_hosts: []             # OTLP endpoint is auto-excluded

        mailer:
            enabled: false

    logs:
        correlation:
            enabled: true                  # inject trace_id / span_id into Monolog records

        export:
            enabled: false                 # requires symfony/monolog-bundle
            level: debug                   # minimum Monolog level to export
            capture_code_attributes: false # resolve file/line via debug_backtrace (small cost)
            unprefixed_attributes: true    # flat context/extra attributes (matches Java/.NET/JS/Python)

    sdk:
        enabled: false                     # implicitly true when any other sdk.* key is set
        autoload_enabled: false            # set OTEL_PHP_AUTOLOAD_ENABLED before Dotenv runs
        use_putenv: false                  # also write via putenv() — not thread-safe
        resource_attributes: {}            # merged into OTEL_RESOURCE_ATTRIBUTES; bundle wins
        exporter_otlp_headers: {}          # merged into OTEL_EXPORTER_OTLP_HEADERS; bundle wins

`traces` section

The traces section controls HTTP request tracing and every built-in instrumentation plugin.

Key	Type	Default	Description
`enabled`	bool	`true`	Enable HTTP request tracing via `OpenTelemetrySubscriber`. Each subsystem has its own toggle.
`tracer_name`	string	`opentelemetry-symfony`	Instrumentation library name reported to the OTel backend.
`excluded_paths`	string[]	`[]`	URL path prefixes to exclude from tracing. Paths without a leading `/` are normalised automatically.
`record_client_ip`	bool	`true`	Record the client IP address as a span attribute. Disable for GDPR compliance.
`error_status_threshold`	int	`500`	HTTP responses with a status code ≥ this value are marked as errors when no exception was thrown. Accepted range: 400–599.
`propagator`	string	`w3c`	Context propagation format. See propagator below.
`id_generator`	string	`default`	Trace ID generation format. See id_generator below.

`traces.console`

Key	Type	Default	Description
`enabled`	bool	`true`	Create spans for Symfony Console commands.
`excluded_commands`	string[]	`[messenger:consume, messenger:consume-messages]`	Command names to skip. Long-lived consume commands are excluded by default because per-message tracing is handled by the Messenger middleware.

`traces.http_client`

Key	Type	Default	Description
`enabled`	bool	`true`	Instrument outgoing HTTP requests with `CLIENT` spans and inject propagation headers.
`excluded_hosts`	string[]	`[]`	Hostnames to skip. The host of `OTEL_EXPORTER_OTLP_ENDPOINT` is always excluded automatically to prevent infinite trace loops.

`traces.messenger`

Key	Type	Default	Description
`enabled`	bool	`true`	Instrument Symfony Messenger dispatch and consume paths.
`root_spans`	bool	`false`	When `false` (default), consumed-message spans are linked to the dispatching trace. When `true`, each consumed message starts a new root span — useful for task-oriented backends such as Traceway or Sentry that model work units as independent traces.

`traces.scheduler`

Key	Type	Default	Description
`enabled`	bool	`true`	Emit a `CONSUMER` span per scheduled-task run with trigger metadata. Requires `symfony/scheduler`. When enabled, the Messenger middleware automatically skips envelopes carrying Symfony’s `ScheduledStamp` so the richer scheduler span owns the work unit without producing duplicate producer/consumer spans.

`traces.mailer`

Key	Type	Default	Description
`enabled`	bool	`true`	Add a `PRODUCER` span around `MailerInterface::send` and a `CLIENT` span around the transport send.
`record_subject`	bool	`false`	Record the email subject as the `email.subject` attribute on the `PRODUCER` span. Disabled by default because subjects can contain personal data.

`traces.doctrine`

Key	Type	Default	Description
`enabled`	bool	`true`	Instrument Doctrine DBAL with `CLIENT` spans for every database query. Supports `doctrine/dbal` ^3.6 and ^4.0.
`record_statements`	bool	`true`	Attach the SQL statement to spans. Prepared statements use `?` placeholders; `query()`/`exec()` calls record raw SQL which may contain literal values. Disable if raw SQL might contain sensitive data.

`traces.cache`

Key	Type	Default	Description
`enabled`	bool	`true`	Instrument Symfony Cache with `INTERNAL` spans for get/delete operations.
`excluded_pools`	string[]	`[]`	Cache pool service IDs to exclude from tracing, e.g. `cache.system`, `cache.validator`, `cache.serializer`.

`traces.twig`

Key	Type	Default	Description
`enabled`	bool	`true`	Instrument Twig with `INTERNAL` spans for every template render.
`excluded_templates`	string[]	`[]`	Template name prefixes to skip, e.g. `@WebProfiler/`, `@Debug/`.

`propagator`

Controls which context propagation format is used for distributed tracing headers.

Value	Description
`w3c`	(default) Injects and extracts `traceparent` / `tracestate` headers (W3C Trace Context).
`xray`	Injects and extracts `X-Amzn-Trace-Id` (AWS X-Ray format). Requires `open-telemetry/contrib-aws`.
`w3c+xray`	Injects and extracts both header formats simultaneously. Requires `open-telemetry/contrib-aws`.

`id_generator`

Controls the format of generated trace IDs.

Value	Description
`default`	Random hex trace IDs (standard OTel format).
`xray`	Epoch-prefixed X-Ray trace IDs. Requires `open-telemetry/contrib-aws`. When selected, the bundle builds and registers a `TracerProvider` using `OTEL_*` env vars plus the X-Ray ID generator.

Using propagator: xray, propagator: w3c+xray, or id_generator: xray requires the open-telemetry/contrib-aws package. The bundle throws a LogicException at container compile time if that package is absent.

`metrics` section

The metrics section is off by default. The top-level metrics.enabled: true flag is the master switch that registers the MeterRegistry service for manual instrumentation; every subsystem listed below also requires it to be true.

Enabling any subsystem metric (e.g. metrics.messenger.enabled: true) while metrics.enabled is false is a configuration error — the bundle will throw an InvalidConfigurationException at container compile time.

Key	Type	Default	Description
`enabled`	bool	`false`	Master switch. Registers `MeterRegistry` and enables the metrics pipeline.
`meter_name`	string	`opentelemetry-symfony`	Instrumentation library name reported with all emitted metrics. Shared across built-in metric subscribers.

`metrics.messenger`

Key	Type	Default	Description
`enabled`	bool	`false`	Emit `messaging.process.duration` (histogram) and `messaging.client.consumed.messages` (counter) on the consume path. Requires `symfony/messenger`.
`excluded_queues`	string[]	`[]`	Receiver names to skip when emitting messenger metrics.

`metrics.doctrine`

Key	Type	Default	Description
`enabled`	bool	`false`	Emit `db.client.operation.duration` (histogram) for every DBAL query, exec, prepared statement execution, and transaction control. Requires `doctrine/dbal`.

`metrics.http_server`

Key	Type	Default	Description
`enabled`	bool	`false`	Emit `http.server.request.duration` (histogram), `http.server.active_requests` (up/down counter), `http.server.request.body.size`, and `http.server.response.body.size` (histograms).
`excluded_paths`	string[]	`[]`	URL path prefixes to skip, using the same prefix-match rules as `traces.excluded_paths`.

`metrics.http_client`

Key	Type	Default	Description
`enabled`	bool	`false`	Emit `http.client.request.duration`, `http.client.request.body.size`, and `http.client.response.body.size` (histograms) on outgoing requests. Requires `symfony/http-client`.
`excluded_hosts`	string[]	`[]`	Hostnames to skip. The OTLP endpoint host is auto-excluded.

`metrics.mailer`

Key	Type	Default	Description
`enabled`	bool	`false`	Emit `messaging.client.operation.duration` (histogram) and `messaging.client.sent.messages` (counter) on outbound transport sends. Requires `symfony/mailer`.

`logs` section

The logs section controls two independent features: trace-correlation injection into Monolog records, and native OTel log export.

`logs.correlation`

Key	Type	Default	Description
`enabled`	bool	`true`	Inject `trace_id` and `span_id` into every Monolog log record via a Monolog processor. Requires `monolog/monolog`.

`logs.export`

Log export requires both a configured OTel LoggerProvider (e.g. via OTEL_LOGS_EXPORTER) and symfony/monolog-bundle. The bundle throws a LogicException at container compile time if monolog-bundle is absent while this feature is enabled.

Key	Type	Default	Description
`enabled`	bool	`false`	Export Monolog log records via the OTel Logs API.
`level`	string	`debug`	Minimum Monolog level to export. Accepted values: `debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, `emergency`.
`capture_code_attributes`	bool	`false`	Resolve `code.file.path`, `code.line.number`, and `code.function.name` via `debug_backtrace()` when Monolog’s `IntrospectionProcessor` is not installed. Has a small per-log performance cost; prefer installing `IntrospectionProcessor` instead.
`unprefixed_attributes`	bool	`true`	Emit Monolog `context` and `extra` fields as flat OTel attributes instead of namespacing them under `monolog.context.` / `monolog.extra.`. The flat shape matches the cross-ecosystem convention used by Java, Python, .NET, and JavaScript OTel libraries.

`sdk` section

The sdk section lets you set OTel SDK environment variables through Symfony’s configuration system, giving you access to DotEnv, container parameters, and Symfony Secrets. See the SDK Setup guide for a full walkthrough.

Key	Type	Default	Description
`enabled`	bool	`false`	Implicitly `true` when any other `sdk.*` key is set. Set explicitly to `false` to suppress the section even if keys are present.
`autoload_enabled`	bool	`false`	Set `OTEL_PHP_AUTOLOAD_ENABLED=true` at bundle boot time and re-run the SDK autoloader. Solves the Symfony DotEnv timing problem.
`use_putenv`	bool	`false`	Also write env variables via `putenv()`. Not thread-safe; off by default.
`resource_attributes`	map	`{}`	Key-value pairs merged into `OTEL_RESOURCE_ATTRIBUTES`. Bundle-set values win over existing ones. Supports Symfony parameter syntax.
`exporter_otlp_headers`	map	`{}`	Key-value pairs merged into `OTEL_EXPORTER_OTLP_HEADERS`. Bundle-set values win over existing ones. Supports Symfony Secrets.

Get Started

Instrumentation

Configuration

Integrations

Operations

Annotated full configuration

`traces` section

`traces.console`

`traces.http_client`

`traces.messenger`

`traces.scheduler`

`traces.mailer`

`traces.doctrine`

`traces.cache`

`traces.twig`

`propagator`

`id_generator`

`metrics` section

`metrics.messenger`

`metrics.doctrine`

`metrics.http_server`

`metrics.http_client`

`metrics.mailer`

`logs` section

`logs.correlation`

`logs.export`

`sdk` section

Build docs developers (and LLMs) love

Get Started

Instrumentation

Configuration

Integrations

Operations

Documentation Index

​Annotated full configuration

​traces section

​traces.console

​traces.http_client

​traces.messenger

​traces.scheduler

​traces.mailer

​traces.doctrine

​traces.cache

​traces.twig

​propagator

​id_generator

​metrics section

​metrics.messenger

​metrics.doctrine

​metrics.http_server

​metrics.http_client

​metrics.mailer

​logs section

​logs.correlation

​logs.export

​sdk section

Build docs developers (and LLMs) love

Annotated full configuration

`traces` section

`traces.console`

`traces.http_client`

`traces.messenger`

`traces.scheduler`

`traces.mailer`

`traces.doctrine`

`traces.cache`

`traces.twig`

`propagator`

`id_generator`

`metrics` section

`metrics.messenger`

`metrics.doctrine`

`metrics.http_server`

`metrics.http_client`

`metrics.mailer`

`logs` section

`logs.correlation`

`logs.export`

`sdk` section