otel-declarative-config

OpenTelemetry Declarative Configuration

Declarative configuration replaces scattered OTEL_* environment variables and language-specific programmatic SDK setup with a single YAML file. One file configures all SDK components: tracer provider, meter provider, logger provider, propagators, and resource.

For the current per-language SDK status, fetch the SDK compatibility matrix (see Sources of Truth). Use it to understand implementation coverage, not as the only source for YAML literals.

Sources of Truth

This skill teaches concepts. The schema itself, valid file_format strings, field names, and SDK compatibility evolve per release — fetch from upstream rather than relying on embedded copies. Cache results for the conversation; refetch only on schema-related errors.

Fact	Fetch
Latest schema release tag	gh release view --repo open-telemetry/opentelemetry-configuration --json tagName,publishedAt
SDK ↔ schema compatibility matrix (coverage advisory, not authoritative for literal file_format)	WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-configuration/main/language-support-status.md
Field-by-field schema docs	WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-configuration/main/schema-docs.md
Compiled JSON Schema (validate generated YAML against this)	WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-configuration/main/opentelemetry_configuration.json
Canonical full example	WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-configuration/main/examples/otel-sdk-config.yaml
Migration template (every option, with comments)	WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-configuration/main/examples/otel-sdk-migration-config.yaml
Schema CHANGELOG (breaking-change history with migration steps)	WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-configuration/main/CHANGELOG.md

Workflow when generating YAML:

1. Identify the exact runtime/package/agent version that will parse the file.
2. Fetch that runtime/package source, docs, or test fixtures and confirm the accepted file_format literal. If this conflicts with language-support-status.md, the runtime/package wins.
3. Fetch examples/otel-sdk-config.yaml → use as the structural template only after adapting the file_format and fields to the selected runtime/package.
4. Overlay the user's specific values (service name, endpoint, sampling, headers).
5. If validation matters, fetch opentelemetry_configuration.json and validate the result, then still verify against the selected runtime/package because SDK implementations may lag or differ from the schema repository.

The latestSupportedFileFormat values in language-support-status.md are schema/version coverage metadata. Do not mechanically copy values like 1.0.0-rc.3 into YAML unless the target SDK parser, agent docs, or package fixtures prove that exact literal is accepted.

Terminology trap: schema coverage identifiers and YAML file_format literals are related, but not interchangeable. A matrix entry may use a semver-shaped value such as 1.0.0-rc.3, while an SDK parser may accept a config literal such as 1.0-rc.3 or 1.0. Generated YAML must use the parser-accepted literal.

For language-specific package versions and SDK API surface, see the Sources of Truth section in each language's otel-<lang> skill (otel-go, otel-java, otel-js, otel-python). otel-dotnet is listed in Cross-References below but does not support declarative YAML config yet — see the .NET note.

Python note: declarative config is supported via the experimental, private opentelemetry.sdk._configuration.file module (install opentelemetry-sdk[file-configuration]). Activation is programmatic — there is no OTEL_CONFIG_FILE CLI wiring like Go/JS; you must call the loader in code at startup. See the otel-python skill and its declarative-setup.md reference.

.NET note: declarative YAML config is not yet implemented in OpenTelemetry .NET (tracked by open-telemetry/opentelemetry-dotnet#6380). .NET configures via the DI/builder API, OTEL_* env vars, and IConfiguration. Do not use OTEL_CONFIG_FILE with .NET runtimes. See the otel-dotnet skill and its setup.md reference.

Activation

The standard environment variable is OTEL_CONFIG_FILE:

export OTEL_CONFIG_FILE=/app/configs/otel.yaml

When set, the SDK reads this file at startup. All other OTEL_* env vars are ignored except those referenced via ${env:VAR} substitution inside the config file.

Language-specific activation varies — see the language sdk-setup skills for details.

Environment Variable Substitution

Syntax	Behavior
${VAR}	Substitute with value of VAR
${env:VAR}	Same as ${VAR} (explicit prefix)
${VAR:-default}	Use default if VAR is unset or empty
$$	Escape sequence, resolves to literal $

Rules:

• Substitution applies only to scalar values, not mapping keys
• Type coercion happens after substitution (${BOOL} where BOOL=true becomes boolean)
• No recursive substitution
• Invalid references produce a parse error

Configuration Precedence

Programmatic API  >  Environment Variables  >  Configuration File
   (highest)                                      (lowest)

Cross-References

• Language-specific setup: otel-go, otel-java, otel-js, otel-python (each loads its own references/declarative-setup.md); otel-dotnet (declarative YAML config not yet supported — see .NET note above).