DeclarativeConfiguredOpenTelemetrySdk introduced

[onurkybsi]

Hi all! As promised in the issue, I'm creating this draft PR to give you an overview about the customizable declarative SDK configuration I have been working on, so we can discuss about the final solution.

I tried to provide all the capabilities that AutoConfiguredOpenTelemetrySdkBuilder has so far. However there are still some missing customization options as I mentioned below. The plan is to add them one by one in another PRs.

• As part of SdkMeterProvider configuration:
  • There is no metricReaderCustomizer support yet, it can be added by refactoring MeterProviderFactory.
  • There is no metricExporterCustomizer support yet, it can be added by refactoring MeterProviderFactory and MetricReaderFactory.
• As part of SdkTracerProvider configuration:
  • There is no spanExporterCustomizer **support yet, it can be added by refactoring TracerProviderFactory and SpanProcessorFactory.
  • There is no spanProcessorCustomizer support yet, It can be added by refactoring TracerProviderFactory.
  • There is no spanSamplerCustomizer support yet, it can be added by refactoring TracerProviderFactory.
• As part of SdkLoggerProvider configuration:
  • There is no logRecordExporterCustomizer support yet, it can be added by refactoring LoggerProviderFactory and LogRecordProcessorFactory.
  • There is no logRecordProcessorCustomizer support yet, it can be added by refactoring LoggerProviderFactory and LogRecordProcessorFactory.

[codecov]

Codecov Report

Attention: Patch coverage is 43.75000% with 90 lines in your changes missing coverage. Please review.

Project coverage is 89.56%. Comparing base (d511a28) to head (ce2ddb8).
Report is 41 commits behind head on main.

Files with missing lines	Patch %	Lines
.../DeclarativeConfiguredOpenTelemetrySdkBuilder.java	42.67%	78 Missing and 12 partials ⚠️

❌ Your patch status has failed because the patch coverage (43.75%) is below the target coverage (80.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #7191      +/-   ##
============================================
- Coverage     89.92%   89.56%   -0.36%     
- Complexity     6662     6682      +20     
============================================
  Files           750      752       +2     
  Lines         20126    20286     +160     
  Branches       1973     1983      +10     
============================================
+ Hits          18098    18170      +72     
- Misses         1434     1510      +76     
- Partials        594      606      +12     

☔ 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]

Hey have you seen #7118? Its related to this, but starts by adding a single customizer for OpenTelemetryConfigurationModel, which is the declarative config analog of customizing ConfigProperties for env var / system property configuration.

Wondering if you can talk about your use case for these programmatic customizers. Ideally, we wouldn't need them because declarative config would have properties for all the things you might want to configure. I understand that in reality, there will be differences in what you can do programmatically and what you can express in YAML, but I'm still curious at what those things are so we can try to bridge the gap.

[onurkybsi]

Hey have you seen #7118? Its related to this, but starts by adding a single customizer for OpenTelemetryConfigurationModel, which is the declarative config analog of customizing ConfigProperties for env var / system property configuration.

Wondering if you can talk about your use case for these programmatic customizers. Ideally, we wouldn't need them because declarative config would have properties for all the things you might want to configure. I understand that in reality, there will be differences in what you can do programmatically and what you can express in YAML, but I'm still curious at what those things are so we can try to bridge the gap.

Heyy, no I didn't see it since there is no mentioning of the issue in the PR. I actually don't have a use case, this PR is just an attempt to solve the issue.

However, to me, programmatic customizers should not mutate the file configuration model(OpenTelemetryConfigurationModel). File configuration model should be built based on the configuration file and it should be immutable. Additionally, isn't it an internal class that the clients are not supposed to integrate with directly? The thing that we need to allow for customization should be the SDK builder not the file configuration model. So, in my opinion, allowing to mutate builders rather than the file configuration model is a neater way to do this. What do you think?

[jack-berg]

However, to me, programmatic customizers should not mutate the file configuration model(OpenTelemetryConfigurationModel). File configuration model should be built based on the configuration file and it should be immutable.

Curious why you think programmatic customization is preferable to customizing the model? IMO, customizing the model is more elegant, as long as the user has the ability to see what changes are made to their specified configuration model (i.e. via logging) and has the ability to opt-out.

Additionally, isn't it an internal class that the clients are not supposed to integrate with directly?

For now, but the goal is have all the model classes part of the public API. However, we first need the schema in opentelemetry-configuration to stabilize so we can stabilize our APIs without risk of breaking changes in the upstream schema.

In terms of the scope of the customizers, we talked in the 3/27/25 java SIG and decided:

• We want to promote standardization of all common configuration tasks in the opentelemetry-configuration schema
• That means that most distro customization tasks should be achievable by customizing the model instead of the SDK builders
• Still, there will always be edge cases - things that are unique to java or which are planned to be added to opentelemetry-configuration but not yet available
• So we'd like to adopt a "wait and see" approach to programmatic customization, where we start with a relatively small set of customization options and expand in response to user requests. This will incentivize users to share the configuration requirements and increase the change of landing properties upstream in the opentelemetry-configuration schema

I think a good place to start is with the SpanExporter, MetricExporter, LogRecordExporter customizers. I know for a fact that its not yet possible to accomplish common configuration scenarios with declarative configuration such as dynamic header authentication. Let's start there and see what users ask for!

[onurkybsi]

Curious why you think programmatic customization is preferable to customizing the model? IMO, customizing the model is more elegant, as long as the user has the ability to see what changes are made to their specified configuration model (i.e. via logging) and has the ability to opt-out.

As I mentioned, from my perspective, the thing that needs customization is the SDK, not the file configuration so, in my opinion, it still doesn't make sense to mutate the model which represents the file configuration given by user. However, let's close this and see what's gonna happen as you said 🙂