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 sdk: configuration section lets you control OpenTelemetry SDK environment variables through Symfony’s own configuration system — DotEnv, container parameters, and Symfony Secrets — rather than relying on shell environment variables set outside the application. Values written by this section are applied at bundle boot time, before the Symfony container is fully used, giving you fine-grained control that raw shell env cannot provide.

​
Why this matters: the OTEL_PHP_AUTOLOAD_ENABLED timing problem

The OpenTelemetry PHP SDK initialises itself through a Composer autoload hook in vendor/open-telemetry/sdk/_autoload.php. That hook only fires when OTEL_PHP_AUTOLOAD_ENABLED=true is already present in the environment at the time Composer’s autoloader runs — which happens before Symfony’s kernel boots. Symfony’s DotEnv component parses .env files and populates $_SERVER / $_ENV during the kernel boot sequence — too late for the SDK autoloader to see the variable. Setting OTEL_PHP_AUTOLOAD_ENABLED in .env therefore has no effect on the autoloader. sdk.autoload_enabled: true solves this by re-running the SDK autoload file from inside the bundle’s boot() method, after the container is compiled and container parameters (including Secrets) are resolved, but still early enough in the request lifecycle for all instrumentation to work correctly.

​
Full sdk: YAML example

open_telemetry:
    sdk:
        enabled: true                    # implicit when any sub-key is set
        autoload_enabled: true           # re-run SDK autoload at bundle boot

        use_putenv: false                # also write via putenv() — not thread-safe

        resource_attributes:
            service.version: '%env(APP_VERSION)%'
            deployment.environment: '%env(APP_ENV)%'
            host.name: '%env(HOSTNAME)%'

        exporter_otlp_headers:
            Authorization: 'Bearer %env(OTEL_API_BEARER_TOKEN)%'
Setting any sdk.* sub-key implicitly enables the section (sdk.enabled is treated as true). Use sdk.enabled: false to explicitly disable the section even when other keys are present in the file — for example to temporarily disable SDK config without removing your values.

​
sdk.autoload_enabled

open_telemetry:
    sdk:
        autoload_enabled: true
When true, the bundle:
  1. Checks whether OTEL_PHP_AUTOLOAD_ENABLED is already true in the current process (via the OTel SDK’s own Configuration::getBoolean() helper).
  2. If it is not already set, writes OTEL_PHP_AUTOLOAD_ENABLED=true into $_SERVER and $_ENV.
  3. Re-requires the SDK’s _autoload.php file. Because the autoloader was previously a no-op (the env var was absent), this correctly initialises the SDK for the first time.
This means you do not need to set OTEL_PHP_AUTOLOAD_ENABLED in your system environment or Docker entrypoint at all — the bundle handles it at the right moment.
This is the recommended way to enable the OTel SDK in a standard Symfony application. It keeps the toggle inside Symfony config where it can be controlled per environment (config/packages/dev/open_telemetry.yaml, config/packages/prod/open_telemetry.yaml, etc.).

​
sdk.resource_attributes

open_telemetry:
    sdk:
        resource_attributes:
            service.version: '%env(APP_VERSION)%'
            deployment.environment: '%env(APP_ENV)%'
            team: 'platform'
Resource attributes describe the entity producing telemetry — your service, its version, the environment it runs in. The bundle merges the map you provide into OTEL_RESOURCE_ATTRIBUTES at boot time. Bundle-provided values win over any values already present in the environment variable, so this config always takes precedence over shell env. The values support Symfony’s full parameter syntax, including:
  • Container parameters: %kernel.environment%
  • Environment variables: %env(APP_VERSION)%
  • Symfony Secrets: %env(resolve:MY_SECRET)% (resolved at container compile time)
The resulting OTEL_RESOURCE_ATTRIBUTES is a comma-separated key=value string, built by array_replace-ing existing entries with your provided map so no existing attributes are lost.
This is semantically different from setting OTEL_RESOURCE_ATTRIBUTES in your .env file. The bundle merges rather than replaces, and your config file values always win the merge. DotEnv values set before boot are treated as the existing baseline.

​
sdk.exporter_otlp_headers

open_telemetry:
    sdk:
        exporter_otlp_headers:
            Authorization: 'Bearer %env(OTEL_API_BEARER_TOKEN)%'
            X-Tenant-ID: '%env(TENANT_ID)%'
OTLP exporters support sending arbitrary HTTP headers — commonly used for authentication tokens when sending data directly to a managed observability backend without a local collector. sdk.exporter_otlp_headers merges the map you provide into OTEL_EXPORTER_OTLP_HEADERS using the same win-over-existing logic as resource_attributes. This is the correct place to configure Bearer tokens or API keys because:
  • The value can reference a Symfony Secret (%env(resolve:OTEL_API_BEARER_TOKEN)%), keeping the secret out of your codebase and shell history.
  • The merge happens at bundle boot, after the Symfony container (including Secrets) is resolved.
  • The token is never written to the filesystem or logged by the container compiler.
Do not commit real tokens to config/packages/open_telemetry.yaml. Use %env(MY_SECRET_TOKEN)% and store the value in Symfony Secrets or your hosting platform’s secret manager.

​
sdk.use_putenv

open_telemetry:
    sdk:
        use_putenv: false   # default
By default the bundle writes env variable values only into $_SERVER and $_ENV. When use_putenv: true is set, it also calls putenv() so the values are visible to C extensions and other code that reads the process environment directly.
putenv() is not thread-safe. In PHP-FPM (process-per-request), this is generally safe because each request runs in its own process. In threaded SAPIs or runtimes (e.g. Swoole, ReactPHP, RoadRunner), putenv() can cause race conditions and should be left disabled. The default is false for this reason.

​
How this differs from .env variables

.env / shell environmentsdk: bundle config
Resolved bySymfony DotEnv / OSSymfony container (parameters + Secrets)
TimingBefore autoloader (shell) or after kernel boot (DotEnv)At bundle boot() — after container is compiled
Symfony Secrets supportNo (DotEnv only)Yes
Per-environment overrideVia .env.prod, .env.dev, etc.Via config/packages/{env}/open_telemetry.yaml
Merge behaviourReplaces entire variableMerges; bundle values win
Fixes autoload timingOnly if set in shell before PHP startsYes — sdk.autoload_enabled: true
In most Symfony applications, the right approach is:
  • Use shell environment variables (or Docker/Kubernetes secrets) for OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_SERVICE_NAME — values that are infrastructure-level concerns.
  • Use sdk: bundle config for autoload_enabled, resource_attributes, and exporter_otlp_headers — values that belong to application config and may reference Symfony Secrets or container parameters.

Build docs developers (and LLMs) love

Get started for freeTalk to us