Otel.Configuration (otel v0.2.0)

Declarative configuration for the OpenTelemetry Elixir SDK (OTEL_CONFIG_FILE).

Implements the spec-defined declarative configuration mechanism (opentelemetry-specification/specification/configuration/sdk.md, Status: Stable as of v1.55.0) — load a YAML file, validate it against the v1.0.0 JSON Schema published in references/opentelemetry-configuration/, and produce the same per-pillar provider config maps that Otel.SDK.Config produces from env vars.

Configuration is opt-in: set OTEL_CONFIG_FILE=/path/to/config.yaml before booting the application. Otel.SDK.Application.start/2 detects the env var and routes through load!/0 automatically; otherwise the SDK falls back to the env-var path (Otel.SDK.Config).

Spec compliance scope

Only Stable schema types are honored. Properties marked */development (per the schema's versioning policy) emit a warning and are ignored — matches our project policy (CLAUDE.md / .claude/rules/workflow.md) of not adopting Development-status spec features.

Stable interfaces implemented:

Parse (configuration/sdk.md §SDK operations) — YAML → in-memory model
Create (configuration/sdk.md §SDK operations) — in-memory model → SDK provider configs
Env var substitution (configuration/data-model.md §Environment variable substitution) — ${VAR} and ${VAR:-default}
Kill switch (sdk-environment-variables.md L332-L337) — when OTEL_CONFIG_FILE is set, all other OTEL_* env vars MUST be ignored except those used in substitution

Not implemented (spec Status: Development):

ConfigProvider interface (runtime introspection of in-memory model)
PluginComponentProvider extension mechanism
Programmatic customization of Create output

Public API

Function	Role
`config_file_set?/0`	SDK (wiring) — `OTEL_CONFIG_FILE` set + non-empty?
`load!/0`	SDK (wiring) — run the full Parse + Create pipeline

References

Spec: opentelemetry-specification/specification/configuration/sdk.md
Schema: opentelemetry-configuration/opentelemetry_configuration.json (pinned at v1.0.0)
Examples: references/opentelemetry-configuration/examples/

Summary

Functions

config_file_set?()

Returns true when OTEL_CONFIG_FILE is set and non-empty.

load!()

Reads the file path in OTEL_CONFIG_FILE and runs the full declarative-config pipeline

Functions

config_file_set?()

@spec config_file_set?() :: boolean()

Returns true when OTEL_CONFIG_FILE is set and non-empty.

Used by Otel.SDK.Application.start/2 to decide whether to route through the declarative-config pipeline or fall back to the env-var path (Otel.SDK.Config).

load!()

@spec load!() :: %{
  trace: map(),
  metrics: map(),
  logs: map(),
  propagator: module() | {module(), [module()]}
}

Reads the file path in OTEL_CONFIG_FILE and runs the full declarative-config pipeline:

File.read!(path)
|> Otel.Configuration.Substitution.substitute!()
|> Otel.Configuration.Parser.parse_string!()
|> Otel.Configuration.Schema.validate!()
|> Otel.Configuration.Composer.compose!()

Returns the per-pillar config map shape that Otel.SDK.Config.{trace,metrics,logs}/0 produces, so the wiring layer can hand the result straight to provider start_link/1.

Raises if OTEL_CONFIG_FILE is unset, the file is missing / unreadable, the YAML is malformed, the model fails schema validation, or composition encounters an unsupported feature (e.g. pull MetricReader, otlp_grpc).