opentelemetry-java This Week: Stable Declarative Config API and a Jaeger Sampler Fix
Opentelemetry-java, the Java SDK and API for OpenTelemetry, had a busy week. Seven commits landed, touching 472 files, and the headline work is clear: three declarative config classes moved to stable API, config parsing became pluggable, and the Jaeger remote sampler got a real bug fix. Everything below comes from the main branch activity of the last seven days on open-telemetry/opentelemetry-java.
Declarative config classes are now stable
The biggest change of the week is the promotion of DeclarativeConfigProperties, DeclarativeConfigException and ComponentProvider to stable. These classes live in the sdk-extensions/declarative-config module and back the file based configuration model, where you describe exporters, samplers and propagators in YAML instead of code.
What stable API means in practice: you can now depend on these classes from your own code with a reasonable expectation that they will not break in the next minor release. The commit also updated the declarative config README, so the documentation should match the new status.
If you have been holding off on declarative config because the classes were experimental, this is the week to take another look.
Config parsing is now pluggable
Alongside the stability work, the parsing and mapping layer became pluggable. Previously the SDK assumed YAML parsing for declarative configuration. After this change the parser is an extension point, so other formats can be wired in without touching the SDK core.
The change is visible in the changed files: YamlDeclarativeConfigProperties, DeclarativeConfigContext, and factory classes like PropagatorFactory and ComposableRuleBasedSamplerFactory all moved, and [DeclarativeConfiguration](https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/declarative-config/src/main/java/io/opentelemetry/sdk/autoconfigure/declarativeconfig/DeclarativeConfiguration.java) grew new entry points.
For most users nothing changes on the surface. For anyone building tooling around configuration files, the seam is now there. Expect follow up work that uses it.
Jaeger remote sampler keeps its state
A fix worth noticing if you run the Jaeger remote sampler: the sampler now keeps the current sampler when the Jaeger strategy response is unchanged. The full fix landed in commit 4ce8c01.
Before the fix, the sampler polled the Jaeger backend, got back the same strategy, and still rebuilt the internal sampler on every poll. For stateful samplers like RateLimitingSampler that meant the token bucket reset on each poll cycle, which quietly distorted rate limiting behaviour. The new code stores the last response under a lock, compares it with equals, and skips the rebuild when nothing changed. The strategy response classes got proper equals and hashCode implementations to make that comparison reliable.
If you set maxTracesPerSecond through the Jaeger backend and wondered why your rate limit behaved loosely, this fix addresses it.
A prototype for context scoped attributes
An early prototype landed for context scoped attributes in commit f646d4b. The idea is that attributes can be attached to the context and flow to spans created inside it, instead of being passed explicitly to every span builder.
This is a prototype, not a supported feature. Do not build on it yet. It is worth knowing about because context scoped attributes are a long running discussion in the OpenTelemetry specification space, and this is the Java SDK starting to explore the design in code.
Dependency bumps and housekeeping
The rest of the week is routine maintenance, and that is fine:
- Patch and minor versions updated across the repo
- Spotless formatting packages moved to v8.11.0
- The weekly update file refreshed
What to watch
Three things to keep an eye on:
- The stable promotion of
DeclarativeConfigPropertiesmeans downstream SDK extensions can start using it. Watch for exporters adding declarative config support,OtlpDeclarativeConfigUtilis already one of the touched files. - The pluggable parsing seam will probably get non YAML format proposals soon.
- The context scoped attributes prototype will need spec alignment before it stabilizes. Do not depend on those APIs yet.
Where to read more: the opentelemetry-java repository and the README in the sdk-extensions/declarative-config module.