use DeclarativeConfigUtil for library config usage #15656

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

…aller

…ename

…eConfigUtil

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

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

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

Abhilash-Garapati and others added 5 commits December 22, 2025 18:45

Apply spotless formatting and finalize span-suppression-strategy rename

676df31

Apply backward-compatible span suppression config rename in AgentInst…

ddaf2ec

…aller

Apply spotless formatting

c6323d2

Add DeprecatedConfigProperties and apply backward-compatible config r…

dad8c40

…ename

use DeclarativeConfigUtil for library config usage

e8eb3f9

zeitlinger added 20 commits December 22, 2025 18:45

fix

bcc2fcc

fix

0eb2ed3

fix

32959be

fix

00fd91c

rename to LibraryConfigUtil to make a clear distinction to Declarativ…

7f4ae19

…eConfigUtil

fix

386dc2d

fix

dc426e6

pr review

cc48c2c

use explicit fallback instead of LegacyLibraryConfigUtil.java

f8922cf

pr review

8a11792

no breaking change anymore

0aab145

fix

5a701d2

fix

6835ab2

fix

398d3d6

fix

c6ff8bd

pr review

bbbb766

pr review

aaca897

pr review

42108cb

pr review

b182a71

pr review

90865dd

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

pr review

d8c7c7c

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

trask reviewed Dec 23, 2025

View reviewed changes

zeitlinger added 5 commits December 23, 2025 08:50

pr review

aceb6b7

pr review

a0279a6

pr review

d02778a

pr review

f5d466d

pr review

39f7544

trask reviewed Dec 23, 2025

View reviewed changes

	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

use DeclarativeConfigUtil for library config usage #15656

Are you sure you want to change the base?

use DeclarativeConfigUtil for library config usage #15656

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

zeitlinger commented Dec 16, 2025 •

edited

Loading