Configuration

OpenTelemetry PHP Distro supports standard OpenTelemetry SDK configuration and distro-specific options.

Configuration method

Configure via environment variables available to PHP processes:

• OTEL_* for OpenTelemetry standard options
• OTEL_PHP_* for distro-specific options

Example:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://your-endpoint:443/"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <token>"
export OTEL_PHP_LOG_LEVEL_STDERR="INFO"

OpenTelemetry options

The distro supports standard OpenTelemetry PHP SDK options.

Distro-specific options (OTEL_PHP_*)

All OTEL_PHP_* options can be set as environment variables or in php.ini.

For php.ini, use the opentelemetry_distro. prefix and lowercase option names.

Example:

export OTEL_PHP_ENABLED=true

opentelemetry_distro.enabled=true

General configuration

Asynchronous data sending

Logging

Transaction span

Attribute-based instrumentation

Scoped dependencies bridge

Inferred spans

Central configuration (OpAMP)

Supportability

Notes

• Background transfer works with OTLP HTTP/protobuf mode.
• OTEL_PHP_AUTOLOAD_ENABLED is enforced as enabled by the distro runtime.
• The distro package includes multiple dependencies (OpenTelemetry SDK, various auto-instrumentation packages, and their transitive dependencies). To prevent namespace conflicts with the application’s own dependencies, the distro uses scoped (namespace-prefixed) dependencies by default. To fall back to unscoped dependencies, set OTEL_PHP_SCOPED_DEPS_ENABLED=false.

Scoped dependencies bridge interop

By default the distro’s OpenTelemetry runtime is scoped: its classes live under a unique namespace prefix, separate from the standard OpenTelemetry\* classes an application would install via Composer. As a result, the application’s own OpenTelemetry usage runs against a separate runtime and its spans are neither exported nor connected to the distro’s traces.

Setting OTEL_PHP_SCOPED_DEPS_BRIDGE_ENABLED=true bridges the two: before the application’s Composer autoloader runs, the distro registers class aliases mapping the unscoped OpenTelemetry\* API onto its scoped implementation. The application’s own OpenTelemetry usage then transparently uses the distro’s tracer provider and context, so its spans are exported and correctly parented within the distro’s traces.

This option has no effect when scoping is disabled (OTEL_PHP_SCOPED_DEPS_ENABLED=false): without scoping the distro already uses the unscoped OpenTelemetry\* classes, so sharing happens without any bridging.

File-based configuration (declarative)

As an alternative to environment variables, you can configure the SDK using a YAML configuration file by setting the OTEL_CONFIG_FILE environment variable:

export OTEL_CONFIG_FILE=/path/to/otel-config.yaml

When OTEL_CONFIG_FILE is set:

• The SDK reads all configuration from the YAML file instead of individual OTEL_* environment variables.
• Environment variable substitution (${MY_VAR:-default}) is supported within the YAML file.
• Central configuration (OpAMP) is automatically disabled — file-based and remote configuration are mutually exclusive.
• Distro-specific options (OTEL_PHP_*) continue to work as they are native extension options, independent of the SDK.

Distro resource detector

The distro provides a distro resource detector that adds telemetry.distro.name and telemetry.distro.version resource attributes. To activate it in file-based configuration, add it to the resource.detection/development.detectors section:

file_format: '1.0-rc.2'

resource:
  attributes:
    - name: service.name
      value: my-service
  detection/development:
    detectors:
      - distro: {}

propagator:
  composite:
    - tracecontext:
    - baggage:

tracer_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: http://localhost:4318/v1/traces

meter_provider:
  readers:
    - periodic:
        exporter:
          otlp_http:
            endpoint: http://localhost:4318/v1/metrics

logger_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: http://localhost:4318/v1/logs

For the full YAML schema, see the OpenTelemetry Configuration Schema.

Limitations

• Central configuration (OpAMP) is not available when file-based configuration is active.
• Resource detectors registered via Registry::registerResourceDetector() (for example, cloud provider detectors from opentelemetry-php-contrib) are not automatically active. They must provide a ComponentProvider and be explicitly listed in the YAML resource.detection/development.detectors section.