Declarative Configuration

Note

Declarative configuration support is new in this release and may still have rough edges. If you hit a problem, please open an issue on the opentelemetry-python tracker.

This example configures the OpenTelemetry SDK from a single YAML file using declarative configuration instead of environment variables or hand-written provider setup.

The source files of this example are available here.

Install the declarative-config package, the auto-instrumentation entry point, the OTLP/HTTP exporter, and the requests instrumentation used by this example:

pip install opentelemetry-configuration \
    opentelemetry-distro \
    opentelemetry-exporter-otlp-proto-http \
    opentelemetry-instrumentation-requests

Start an OTLP-capable backend locally so there is somewhere to send data. Write the following file:

# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

exporters:
  debug:
    verbosity: detailed

service:
    pipelines:
        traces:
            receivers: [otlp]
            exporters: [debug]
        metrics:
            receivers: [otlp]
            exporters: [debug]
        logs:
            receivers: [otlp]
            exporters: [debug]

Then start the Collector:

docker run \
    -p 4318:4318 \
    -v $(pwd)/otel-collector-config.yaml:/etc/otel-collector-config.yaml \
    otel/opentelemetry-collector:latest \
    --config=/etc/otel-collector-config.yaml

Run the example

Point the SDK at otel-config.yaml with OTEL_CONFIG_FILE and let auto-instrumentation apply it. No configuration code lives in app.py:

export OTEL_CONFIG_FILE=$(pwd)/otel-config.yaml
opentelemetry-instrument python app.py

You should see the exported span in the Collector’s debug output. The instrumentation/development.python section in otel-config.yaml activates the requests instrumentation so outgoing HTTP calls made by app.py are automatically traced without any code changes.

Environment variable substitution

otel-config.yaml uses ${DEPLOYMENT_ENVIRONMENT:-development} to read the deployment environment from the environment, defaulting to development. Set it before running to override:

export DEPLOYMENT_ENVIRONMENT=staging