# 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.

Declarative configuration lets you configure the OpenTelemetry SDK from a single YAML (or JSON) file instead of setting many individual `OTEL_*` environment variables or writing provider-construction code by hand. The file format is defined by the OpenTelemetry configuration specification.

A single file describes your resource, providers, processors, exporters, samplers, and propagators. The SDK reads the file, validates it against the configuration schema, and applies it globally.

## Installing

File configuration relies on optional dependencies (`pyyaml` and `jsonschema`). Install them with the `file-configuration` extra:

    pip install "opentelemetry-sdk[file-configuration]"

## Enabling with an environment variable

Point the SDK at a file with the `OTEL_CONFIG_FILE` environment variable. When it is set, the file is the sole source of SDK construction. Spec-defined `OTEL_*` variables with schema equivalents are ignored. Environment variables can still be read via `${env:VAR}` substitution inside the file (see Environment variable substitution).

    export OTEL_CONFIG_FILE=/etc/otel/otel-config.yaml
    opentelemetry-instrument python app.py

## Example configuration

The following file configures traces, metrics, and logs to be exported over OTLP/HTTP. The source is available here.

    file_format: "1.0"

    resource:
      attributes:
        - name: service.name
          value: my-service
        - name: deployment.environment.name
          value: ${DEPLOYMENT_ENVIRONMENT:-development}

    tracer_provider:
      processors:
        - batch:
            exporter:
              otlp_http:
                endpoint: https://example.com:4318/v1/traces
                headers:
                  - name: api-key
                    value: ${OTLP_API_KEY}
      sampler:
        parent_based:
          root:
            always_on: {}

    meter_provider:
      readers:
        - periodic:
            interval: 60000
            exporter:
              otlp_http:
                endpoint: https://example.com:4318/v1/metrics
                headers:
                  - name: api-key
                    value: ${OTLP_API_KEY}

    logger_provider:
      processors:
        - batch:
            exporter:
              otlp_http:
                endpoint: https://example.com:4318/v1/logs
                headers:
                  - name: api-key
                    value: ${OTLP_API_KEY}

## Environment variable substitution

Values in the file may reference environment variables, which keeps secrets such as API keys out of the file itself. Substitution happens before the file is parsed.

- `${VAR}`: replaced with the value of `VAR`. If `VAR` is unset, loading fails with an error.

- `${VAR:-default}`: replaced with `VAR` if set, otherwise `default`.

- `$$`: a literal `$`.

In the example above, `${OTLP_API_KEY}` is required, while `${DEPLOYMENT_ENVIRONMENT:-development}` falls back to `development` when unset.

## Behavior notes

- When `OTEL_CONFIG_FILE` is set, the file is authoritative for SDK construction; spec-defined `OTEL_*` variables with schema equivalents are not consulted. Environment variables can still be read indirectly by components the file enables (for example resource detectors) and via `${env:VAR}` substitution.

- Sections omitted from the file leave the corresponding global provider unset (a no-op provider), per the specification.

- Setting `disabled: true` at the top level turns the SDK into a no-op.

## See also

- OpenTelemetry configuration specification

- opentelemetry.sdk.environment_variables: the environment-variable configuration path