Make snakeyaml-engine and jackson-databind optional at runtime

[zeitlinger]

Summary

This PR does two things:

1. Split YAML parsing out of DeclarativeConfiguration

DeclarativeConfiguration is split into two classes to make YAML dependencies optional at runtime:

• DeclarativeConfiguration — create(model) methods only. No dependency on snakeyaml-engine or jackson-databind at runtime.
• DeclarativeConfigurationParser — all YAML parsing: MAPPER static block, parse(), loadYaml(), parseAndCreate(), toConfigProperties(), env-var substitution.

The MAPPER field in the original class is a static final with a static initializer. Loading the class to call create(model) triggered that static block, failing with NoClassDefFoundError if jackson-databind was absent. Moving the static block to DeclarativeConfigurationParser breaks the link — the JVM only loads it when parser methods are actually called.

2. Move all declarative config (fileconfig) from incubator into autoconfigure

All ~45 fileconfig source files are moved from sdk-extensions/incubator to sdk-extensions/autoconfigure. This is the direction suggested in #8265 — the YAML dep concern is resolved by the class split above.

A new sdk-extensions/autoconfigure-config convenience module bundles autoconfigure + snakeyaml-engine + jackson-databind for users who want everything in one dependency (Spring Boot starter style).

Dependency graph

graph TD
    config["autoconfigure-config\n(convenience bundle)"]
    autoconfigure["autoconfigure\n(fileconfig included)"]
    incubator["incubator\n(ViewConfig, SPI extensions)"]
    api-incubator["api:incubator"]
    snakeyaml["snakeyaml-engine"]
    jackson["jackson-databind"]
    jackson-ann["jackson-annotations"]

    config -->|api| autoconfigure
    config -->|runtimeOnly| snakeyaml
    config -->|runtimeOnly| jackson

    autoconfigure -->|api| jackson-ann
    autoconfigure -.->|"compileOnly (YAML parsing)"| snakeyaml
    autoconfigure -.->|"compileOnly (YAML parsing)"| jackson
    autoconfigure -.->|"compileOnly (fileconfig)"| api-incubator
    autoconfigure -.->|"compileOnly (optional SPI)"| incubator

    incubator -->|api| api-incubator

Loading

Dashed arrows = compileOnly / optional at runtime. YAML file config requires snakeyaml + jackson + api:incubator at runtime; autoconfigure-config provides all three.

What changes for users

Use case	Before	After
AutoConfiguredOpenTelemetrySdk (env/props only)	autoconfigure	autoconfigure (unchanged)
YAML file config (otel.config.file)	autoconfigure + incubator + snakeyaml + jackson	autoconfigure-config
Programmatic DeclarativeConfiguration.create(model)	incubator + snakeyaml + jackson (YAML deps leaked)	autoconfigure only
SPI-based declarative config	autoconfigure + incubator + api:incubator	same

Related to / supersedes the direction in #8265.

[codecov]

Codecov Report

❌ Patch coverage is 89.47368% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.27%. Comparing base (2525caa) to head (e3ee579).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
...incubator/fileconfig/DeclarativeConfiguration.java	86.48%	4 Missing and 1 partial ⚠️
...nfigure/AutoConfiguredOpenTelemetrySdkBuilder.java	87.50%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #8270      +/-   ##
============================================
- Coverage     90.27%   90.27%   -0.01%     
- Complexity     7684     7685       +1     
============================================
  Files           850      851       +1     
  Lines         23186    23196      +10     
  Branches       2352     2352              
============================================
+ Hits          20931    20940       +9     
  Misses         1530     1530              
- Partials        725      726       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jack-berg]

I don't think we're ready to stabilize these APIs quite yet. Since autoconfigure is a stable artifact, these would need to be in an internal package for the time being.

One benefit of #8265 is since its publishing to a new alpha artifact opentelemetry-sdk-extension-declarative-config, it can keep the code in a non-internal package. Later, when we're comfortable stabilizing the APIs, we can choose to either:

• Stabilize opentelemetry-sdk-extension-declarative-config
• OR, merge opentelemetry-sdk-extension-declarative-config into opentelemetry-sdk-extension-autoconfigure, keeping the package identical.

I like the sound of the second option. It lands us in the same place as this PR, but minimizes churn for users.

[zeitlinger]

I don't think we're ready to stabilize these APIs quite yet.

OK - I thought this was what we're trying to do now - as you said we want to find a "permanent home".

But even if not - I think it's valuable to discuss the target picture - or are we in a rush to do this refactor in any way?

[jack-berg]

OK - I thought this was what we're trying to do now

Permanent home yes, public API - I was thinking no since there are so many moving pieces just to extract that it'll be hard to focus on scrutinizing the API design as well.

But even if not - I think it's valuable to discuss the target picture

Yes definitely. Especially considering that a multi stage move (1. extract from SDK incubator 2. promote APIs to public) exposes users to more churn than one big move. Reducing the churn is why I like the second option.

[zeitlinger]

I think the same strategy could also be applied to this PR - I'd just move the files to internal in the first go.

It really boils down to: "Is it a good feature to let users skip jackson and snakeyaml".

[jack-berg]

I'd just move the files to internal in the first go.

That's different. With #8265, we can start with a separate module opentelemetry-sdk-extension-declarative-config, and keep the code in a package in that module io.opentelemetry.sdk.autoconfigure.declarativeconfig, such that we could later merge the new module into opentelemetry-sdk-extension-autoconfigure without any change to the package.

Not *.internal.declarativeconfig -> *.declarativeconfig transition required for users. Just change dependency from opentelemetry-sdk-extension-declarative-config to opentelemetry-sdk-extension-autoconfigure.

It really boils down to: "Is it a good feature to let users skip jackson and snakeyaml".

I do think its a good idea. I would go with a pluggable design with SPI defining the contract for parsing YAML, and snakeyaml + jackson just one implementation.

[zeitlinger]

got it - so we keep this PR as a follow up then (even if we re-create it then)

[jack-berg]

In #8265 description I proposed followup work to make YAML parsing pluggable:

Consider making YAML parsing pluggable. Right now we use org.snakeyaml:snakeyaml-engine for parse input YAML string to Object, then we use jackson to convert Object to OpenTelemetryConfigurationModel. If org.snakeyaml.snakeyaml-engine had unsolved vulnerabilities or if breaking changes caused runtime errors from the diamond dependency problem, then users would have no recourse. We could make these functions pluggable via SPI and try to provide at least one other implementation.

User facing difference between this and #8265: With this, users depend on opentelemetry-sdk-extension-autoconfigure, but practically speaking, need to depend on opentelemetry-sdk-extension-autoconfigure-config <- Heh autoconfigure-config is a funny artifact name. With #8265, users depend on opentelemetry-sdk-extension-autoconfigure, but practically speaking need to depend on opentelemetry-sdk-extension-declarative-config.