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 SDK with the file-configuration extra (it pulls in pyyaml and jsonschema), the auto-instrumentation entry point, and the OTLP/HTTP exporter:

pip install "opentelemetry-sdk[file-configuration]" \
    opentelemetry-distro \
    opentelemetry-exporter-otlp-proto-http

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.

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