use DeclarativeConfigUtil for library config usage by zeitlinger · Pull Request #15656 · open-telemetry/opentelemetry-java-instrumentation

zeitlinger · 2025-12-16T07:57:01Z

Replaces #15339

Note: This PR takes into account open-telemetry/opentelemetry-java#7927 for method naming.

Copilot

Pull request overview

This PR refactors library configuration access to use DeclarativeConfigUtil instead of directly using ConfigPropertiesUtil, enabling support for declarative configuration. The changes include introducing new utility classes for declarative config support, renaming the otel.experimental.javascript-snippet property to otel.instrumentation.servlet.experimental.javascript-snippet for naming convention consistency, and updating multiple instrumentations (servlet, log4j, kafka, jdbc, aws-sdk) to use the new configuration approach.

Key Changes

Introduces DeclarativeConfigUtil and SystemPropertiesBackedDeclarativeConfigProperties to enable declarative config support with fallback to system properties
Renames JavaScript snippet property from otel.experimental.javascript-snippet to otel.instrumentation.servlet.experimental.javascript-snippet with backward compatibility
Refactors AWS SDK v2.2 configuration by consolidating factory logic into AwsSdkTelemetryFactory and removing the abstract base class

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/config/internal/DeclarativeConfigUtil.java	New utility class providing main API for accessing declarative config with fallback support
instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/config/internal/SystemPropertiesBackedDeclarativeConfigProperties.java	New implementation of DeclarativeConfigProperties backed by system properties and environment variables
instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/internal/ConfigUtil.java	New low-level config utilities copied from SDK for safe property access
instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/internal/ConfigPropertiesUtil.java	Refactored to use ConfigUtil and added deprecation notices recommending DeclarativeConfig
instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/InstrumenterBuilder.java	Added declarative config support check and moved span suppression strategy resolution to instance method
instrumentation/servlet/servlet-common/bootstrap/src/main/java/io/opentelemetry/javaagent/bootstrap/servlet/ExperimentalSnippetHolder.java	Updated to use DeclarativeConfigUtil and added deprecation warning for old property name
instrumentation/log4j/log4j-context-data/log4j-context-data-2.17/library-autoconfigure/src/main/java/io/opentelemetry/instrumentation/log4j/contextdata/v2_17/internal/ContextDataKeys.java	Migrated to DeclarativeConfigUtil for logging configuration keys
instrumentation/kafka/kafka-clients/kafka-clients-2.6/library/src/main/java/io/opentelemetry/instrumentation/kafkaclients/v2_6/TracingProducerInterceptor.java	Migrated to DeclarativeConfigUtil for capture headers configuration
instrumentation/kafka/kafka-clients/kafka-clients-2.6/library/src/main/java/io/opentelemetry/instrumentation/kafkaclients/v2_6/TracingConsumerInterceptor.java	Migrated to DeclarativeConfigUtil for receive telemetry and capture headers configuration
instrumentation/jdbc/library/src/main/java/io/opentelemetry/instrumentation/jdbc/internal/JdbcInstrumenterFactory.java	Updated to use DeclarativeConfigUtil and accept OpenTelemetry parameter for config access
instrumentation/jdbc/library/src/main/java/io/opentelemetry/instrumentation/jdbc/OpenTelemetryDriver.java	Migrated SQL commenter configuration to DeclarativeConfigUtil with fallback logic
instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/io/opentelemetry/instrumentation/awssdk/v2_2/internal/AwsSdkTelemetryFactory.java	New factory class consolidating AWS SDK v2.2 telemetry configuration using DeclarativeConfigUtil
instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/io/opentelemetry/instrumentation/awssdk/v2_2/internal/AbstractAwsSdkTelemetryFactory.java	Removed abstract factory class, replaced by concrete AwsSdkTelemetryFactory
instrumentation/aws-sdk/aws-sdk-2.2/library-autoconfigure/src/main/java/io/opentelemetry/instrumentation/awssdk/v2_2/autoconfigure/AwsSdkSingletons.java	Simplified to use new AwsSdkTelemetryFactory
instrumentation/aws-sdk/aws-sdk-2.2/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/awssdk/v2_2/AwsSdkSingletons.java	Simplified to use new AwsSdkTelemetryFactory
instrumentation/aws-sdk/aws-sdk-1.11/library-autoconfigure/src/main/java/io/opentelemetry/instrumentation/awssdk/v1_11/autoconfigure/TracingRequestHandler.java	Migrated to DeclarativeConfigUtil for AWS SDK v1.11 configuration
instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/config/internal/SystemPropertiesBackedDeclarativeConfigPropertiesTest.java	New comprehensive test coverage for SystemPropertiesBackedDeclarativeConfigProperties
instrumentation-api/src/test/java/io/opentelemetry/instrumentation/api/internal/ConfigPropertiesUtilTest.java	Updated tests to use correct otel.instrumentation prefix
instrumentation-api-incubator/build.gradle.kts	Added junit-pioneer dependency and JVM args for Java 17 compatibility
instrumentation/servlet/servlet-common/bootstrap/build.gradle.kts	Added compileOnly dependency on instrumentation-api-incubator
docs/advanced-configuration-options.md	Updated documentation with new JavaScript snippet property name
CHANGELOG.md	Added breaking change entry for JavaScript snippet property rename
docs/apidiffs/current_vs_latest/opentelemetry-instrumentation-api.txt	Documents new public isDeclarativeConfig method in InstrumenterBuilder
smoke-tests/src/main/java/io/opentelemetry/smoketest/AbstractTestContainerManager.java	Updated smoke tests to use new JavaScript snippet property name

.../java/io/opentelemetry/instrumentation/awssdk/v1_11/autoconfigure/TracingRequestHandler.java

...ntation/api/incubator/config/internal/SystemPropertiesBackedDeclarativeConfigProperties.java

CHANGELOG.md

...n/java/io/opentelemetry/instrumentation/api/incubator/config/internal/LibraryConfigUtil.java

...api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/InstrumenterBuilder.java

instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/internal/ConfigUtil.java

...on/jdbc/library/src/main/java/io/opentelemetry/instrumentation/jdbc/OpenTelemetryDriver.java

...main/java/io/opentelemetry/instrumentation/kafkaclients/v2_6/TracingConsumerInterceptor.java

smoke-tests/src/main/java/io/opentelemetry/smoketest/AbstractTestContainerManager.java

...ap/src/main/java/io/opentelemetry/javaagent/bootstrap/servlet/ExperimentalSnippetHolder.java

.../java/io/opentelemetry/instrumentation/log4j/contextdata/v2_17/internal/ContextDataKeys.java

...ry/src/main/java/io/opentelemetry/instrumentation/jdbc/internal/JdbcInstrumenterFactory.java

...on/jdbc/library/src/main/java/io/opentelemetry/instrumentation/jdbc/OpenTelemetryDriver.java

.../main/java/io/opentelemetry/instrumentation/awssdk/v2_2/internal/AwsSdkTelemetryFactory.java

.../java/io/opentelemetry/instrumentation/awssdk/v1_11/autoconfigure/TracingRequestHandler.java

trask · 2025-12-23T03:46:13Z

...api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/InstrumenterBuilder.java

+      DeclarativeConfigProperties instrumentationConfig =
+          ((ExtendedOpenTelemetry) openTelemetry).getConfigProvider().getInstrumentationConfig();
+      if (instrumentationConfig == null) {
+        return null;


Once getConfigProvider() is moved out of ExtendedOpenTelemetry to OpenTelemetry, I think we'll need to check the sys prop here? If so, may be good to do that now, could be easy to forget when refactoring later

I added a mapping to check for the old value

opentelemetry-java-instrumentation/declarative-config-bridge/src/main/java/io/opentelemetry/instrumentation/config/bridge/ConfigPropertiesBackedDeclarativeConfigProperties.java

Lines 73 to 75 in c6ff8bd

SPECIAL_MAPPINGS.put(

"java.common.span_suppression_strategy/development",

"otel.instrumentation.experimental.span-suppression-strategy");

.../java/io/opentelemetry/instrumentation/awssdk/v1_11/autoconfigure/TracingRequestHandler.java

.../main/java/io/opentelemetry/instrumentation/awssdk/v2_2/internal/AwsSdkTelemetryFactory.java

...on/jdbc/library/src/main/java/io/opentelemetry/instrumentation/jdbc/OpenTelemetryDriver.java

...on-api/src/main/java/io/opentelemetry/instrumentation/api/internal/ConfigPropertiesUtil.java

trask · 2025-12-23T22:30:46Z

...ap/src/main/java/io/opentelemetry/javaagent/bootstrap/servlet/ExperimentalSnippetHolder.java

+            // use ConfigPropertiesUtil only to prevent that the deprecated property is used in
+            // declarative config


i'm not sure what this comment is trying to say

realized that I can just use SPECIAL_MAPPINGS instead

trask · 2025-12-23T22:36:07Z

...on/jdbc/library/src/main/java/io/opentelemetry/instrumentation/jdbc/OpenTelemetryDriver.java

+    boolean enabled =
+        DeclarativeConfigUtil.getInstrumentationConfig(openTelemetry, "jdbc")
+            .get("sqlcommenter/development")
+            .getBoolean("enabled", false);
+    if (!enabled) {
+      enabled =
+          ConfigPropertiesUtil.getBoolean(
+              "otel.instrumentation.jdbc.experimental.sqlcommenter.enabled", false);
+    }
+    if (!enabled) {
+      enabled =
+          DeclarativeConfigUtil.getInstrumentationConfig(openTelemetry, "common")
+              .get("database")
+              .get("sqlcommenter/development")
+              .getBoolean("enabled", false);
+    }
+    if (!enabled) {
+      enabled =
+          ConfigPropertiesUtil.getBoolean(
+              "otel.instrumentation.common.experimental.db-sqlcommenter.enabled", false);
+    }


I think the fallback shouldn't happen if there's an explicit false

I think you need to use the @nullable Boolean returning version and check for null return

trask · 2025-12-23T22:41:43Z

.../main/java/io/opentelemetry/instrumentation/awssdk/v2_2/internal/AwsSdkTelemetryFactory.java

+    return AwsSdkTelemetry.builder(openTelemetry)
+        .setCapturedHeaders(
+            messaging.getScalarList(
+                "capture_headers/development",
+                String.class,
+                ConfigPropertiesUtil.getList(
+                    "otel.instrumentation.messaging.experimental.capture-headers", emptyList())))


thinking more about this, mayb we should keep the two subclasses in order to avoid exposing the javaagent instrumentation to direct system property access

right - I found a solution without subclassing

zeitlinger self-assigned this Dec 16, 2025

zeitlinger requested a review from a team as a code owner December 16, 2025 07:57

zeitlinger added the breaking change label Dec 16, 2025

zeitlinger requested a review from Copilot December 16, 2025 07:57

github-actions bot added the test native This label can be applied to PRs to trigger them to run native tests label Dec 16, 2025

Copilot started reviewing on behalf of zeitlinger December 16, 2025 07:57 View session

Copilot AI reviewed Dec 16, 2025

View reviewed changes

This was referenced Dec 16, 2025

Add system properties bridge #15339

Closed

Config Provider Bridge #15622

Closed

zeitlinger force-pushed the use-bridge-instread-of-config-property-util branch from ba28a2d to 5995f89 Compare December 16, 2025 09:00

zeitlinger mentioned this pull request Dec 16, 2025

Rename span-suppression-strategy configuration with backward compatibility #15612

Closed

zeitlinger added this to Declarative Configuration: Java Dec 16, 2025

zeitlinger mentioned this pull request Dec 16, 2025

Remove AgentInstrumentationConfig usages: AWS #15651

Closed

zeitlinger moved this to In Progress in Declarative Configuration: Java Dec 16, 2025

zeitlinger force-pushed the use-bridge-instread-of-config-property-util branch 2 times, most recently from 0abf936 to 9bbac6f Compare December 20, 2025 08:39

trask reviewed Dec 20, 2025

View reviewed changes

...n/java/io/opentelemetry/instrumentation/api/incubator/config/internal/LibraryConfigUtil.java Outdated Show resolved Hide resolved

zeitlinger requested a review from trask December 20, 2025 23:10

trask reviewed Dec 22, 2025

View reviewed changes

...api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/InstrumenterBuilder.java Outdated Show resolved Hide resolved

trask reviewed Dec 22, 2025

View reviewed changes

instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/internal/ConfigUtil.java Outdated Show resolved Hide resolved

trask reviewed Dec 22, 2025

View reviewed changes

...on/jdbc/library/src/main/java/io/opentelemetry/instrumentation/jdbc/OpenTelemetryDriver.java Outdated Show resolved Hide resolved

zeitlinger force-pushed the use-bridge-instread-of-config-property-util branch 2 times, most recently from 90ffe39 to ef0cae6 Compare December 22, 2025 07:00

zeitlinger removed the breaking change label Dec 22, 2025

trask reviewed Dec 22, 2025

View reviewed changes

zeitlinger force-pushed the use-bridge-instread-of-config-property-util branch from 2391693 to 90865dd Compare December 22, 2025 19:01

open-telemetry deleted a comment from github-actions bot Dec 22, 2025

trask reviewed Dec 23, 2025

View reviewed changes

Apply spotless formatting and finalize span-suppression-strategy rename

d847267

zeitlinger added 21 commits December 24, 2025 12:14

pr review

42a7af9

no breaking change anymore

a2d115c

fix

f0566aa

fix

b7f9fb7

fix

ec4a9df

fix

4633dd6

pr review

946a126

pr review

695a6d7

pr review

cee626f

pr review

e3bd901

pr review

de1ef5d

pr review

3f8fdfc

pr review

da7325b

pr review

80905ad

pr review

33c917f

pr review

8f3c3df

pr review

a138626

no sys props in agent

494711e

allow to set false

745240a

no sys props in agent

9749c18

use special_mapping

b436af2

zeitlinger force-pushed the use-bridge-instread-of-config-property-util branch from 39f7544 to b436af2 Compare December 24, 2025 11:59

zeitlinger added 2 commits December 24, 2025 13:30

fix

2ee1181

fix

77fa4cb

trask approved these changes Dec 24, 2025

View reviewed changes

trask merged commit f542b30 into open-telemetry:main Dec 24, 2025
87 checks passed

github-project-automation bot moved this from In Progress to Done in Declarative Configuration: Java Dec 24, 2025

trask mentioned this pull request Dec 24, 2025

Simplify InstrumenterBuilder config #15727

Merged

zeitlinger deleted the use-bridge-instread-of-config-property-util branch January 5, 2026 09:59

zeitlinger mentioned this pull request Jan 9, 2026

Allow JdbcTelemetry to rely on java opts #13870

Closed

	SPECIAL_MAPPINGS.put(
	"java.common.span_suppression_strategy/development",
	"otel.instrumentation.experimental.span-suppression-strategy");

		// use ConfigPropertiesUtil only to prevent that the deprecated property is used in
		// declarative config

Conversation

zeitlinger commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Key Changes

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

trask Dec 23, 2025

Choose a reason for hiding this comment

Uh oh!

zeitlinger Dec 23, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

trask Dec 23, 2025

Choose a reason for hiding this comment

Uh oh!

zeitlinger Dec 24, 2025

Choose a reason for hiding this comment

Uh oh!

trask Dec 23, 2025

Choose a reason for hiding this comment

Uh oh!

trask Dec 23, 2025

Choose a reason for hiding this comment

Uh oh!

zeitlinger Dec 24, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

zeitlinger commented Dec 16, 2025 •

edited

Loading