open-telemetry · zeitlinger · Nov 17, 2025 · Nov 17, 2025 · Nov 17, 2025 · Nov 18, 2025
@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+### ⚠️ Breaking Changes
+
+- Rename `otel.experimental.javascript-snippet` to
+  `otel.instrumentation.servlet.experimental.javascript-snippet` to follow naming conventions
+  ([#15339](https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/15339))
+
 ## Version 2.22.0 (2025-11-20)
 
 ### ⚠️ Breaking Changes

@@ -45,9 +45,9 @@ This feature is designed for integrating client-side monitoring.
 We plan to integrate OpenTelemetry's own client-side monitoring solution by default once it's available
 (see the [browser instrumentation proposal](https://github.com/open-telemetry/community/blob/main/projects/browser-phase-1.md)).
 
-| System property                      | Environment variable                 | Purpose                                                                                                                                                                                                                                                                                      |
-|--------------------------------------|--------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| otel.experimental.javascript-snippet | OTEL_EXPERIMENTAL_JAVASCRIPT_SNIPPET | Experimental setting to inject a JavaScript snippet into HTML responses after the opening `<head>` tag. The value should be a complete JavaScript snippet including `<script>` tags if needed, e.g. `-Dotel.experimental.javascript-snippet="<script>console.log('Hello world!');</script>"` |
+| System property                                                | Environment variable                                           | Purpose                                                                                                                                                                                                                                                                                                              |
+|----------------------------------------------------------------|----------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `otel.instrumentation.servlet.experimental.javascript-snippet` | `OTEL_INSTRUMENTATION_SERVLET_EXPERIMENTAL_JAVASCRIPT_SNIPPET` | Experimental setting to inject a JavaScript snippet into HTML responses after the opening `<head>` tag. The value should be a complete JavaScript snippet including `<script>` tags if needed, e.g. `-Dotel.instrumentation.servlet.experimental.javascript-snippet="<script>console.log('Hello world!');</script>"` |
 
 **Important notes:**
 

@@ -132,7 +132,7 @@ default List<String> getList(String name) {
   /**
    * Returns the {@link ConfigProvider} if declarative configuration is used.
    *
-   * @return the {@link ConfigProvider} or {@code null} if no provider is available
+   * @return the {@link ConfigProvider} or {@code null} if declarative configuration is not used
    */
   @Nullable
   ConfigProvider getConfigProvider();

@@ -22,6 +22,7 @@ dependencies {
   testImplementation("io.opentelemetry.javaagent:opentelemetry-testing-common")
   testImplementation("io.opentelemetry:opentelemetry-sdk-testing")
   testImplementation("io.opentelemetry:opentelemetry-exporter-common")
+  testImplementation("io.opentelemetry:opentelemetry-sdk-extension-incubator")
   testImplementation("org.junit-pioneer:junit-pioneer")
 
   jmhImplementation(project(":instrumentation-api-incubator"))

@@ -49,11 +49,6 @@ public final class InstrumenterBuilder<REQUEST, RESPONSE> {
 
   private static final Logger logger = Logger.getLogger(InstrumenterBuilder.class.getName());
 
-  private static final SpanSuppressionStrategy spanSuppressionStrategy =
-      SpanSuppressionStrategy.fromConfig(
-          ConfigPropertiesUtil.getString(
-              "otel.instrumentation.experimental.span-suppression-strategy"));
-
   final OpenTelemetry openTelemetry;
   final String instrumentationName;
   SpanNameExtractor<? super REQUEST> spanNameExtractor;
@@ -373,8 +368,17 @@ private String getSchemaUrl() {
   }
 
   SpanSuppressor buildSpanSuppressor() {
+    // otel.instrumentation.experimental.* doesn't fit the usual pattern of configuration properties
+    // for instrumentations, so we need to handle both declarative and non-declarative configs here
+    String value =
+        ConfigPropertiesUtil.isDeclarativeConfig(openTelemetry)
+            ? ConfigPropertiesUtil.getString(
+                    openTelemetry, "common", "span_suppression_strategy/development")
+                .orElse(null)
+            : ConfigPropertiesUtil.getString(
+                "otel.instrumentation.experimental.span-suppression-strategy");
     return new SpanSuppressors.ByContextKey(
-        spanSuppressionStrategy.create(getSpanKeysFromAttributesExtractors()));
+        SpanSuppressionStrategy.fromConfig(value).create(getSpanKeysFromAttributesExtractors()));
   }
 
   private Set<SpanKey> getSpanKeysFromAttributesExtractors() {

@@ -5,9 +5,21 @@
 
 package io.opentelemetry.instrumentation.api.internal;
 
+import static io.opentelemetry.api.incubator.config.DeclarativeConfigProperties.empty;
+import static java.util.Collections.emptyList;
+
+import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.api.incubator.ExtendedOpenTelemetry;
+import io.opentelemetry.api.incubator.config.ConfigProvider;
+import io.opentelemetry.api.incubator.config.DeclarativeConfigProperties;
 import java.util.Arrays;
+import java.util.ConcurrentModificationException;
+import java.util.HashMap;
 import java.util.List;
 import java.util.Locale;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Properties;
 import java.util.stream.Collectors;
 import javax.annotation.Nullable;
 
@@ -17,11 +29,70 @@
  */
 public final class ConfigPropertiesUtil {
 
+  private static final boolean supportsDeclarativeConfig = supportsDeclarativeConfig();
+
+  private static final Map<String, String> config = load();
+
+  public static Map<String, String> load() {
+    Map<String, String> config = new HashMap<>();
+    for (Map.Entry<String, String> entry : System.getenv().entrySet()) {
+      config.put(normalizeEnvironmentVariableKey(entry.getKey()), entry.getValue());
+    }
+    for (Map.Entry<Object, Object> entry : safeSystemProperties().entrySet()) {
+      config.put(normalizePropertyKey(entry.getKey().toString()), entry.getValue().toString());
+    }
+    return config;
+  }
+
+  /** Resets the cached config for testing purposes. */
+  public static void resetForTest() {
+    config.clear();
+    config.putAll(load());
+  }
+
+  private static boolean supportsDeclarativeConfig() {
+    try {
+      Class.forName("io.opentelemetry.api.incubator.ExtendedOpenTelemetry");
+      return true;
+    } catch (ClassNotFoundException e) {
+      // The incubator module is not available.
+      // This only happens in OpenTelemetry API instrumentation tests, where an older version of
+      // OpenTelemetry API is used that does not have ExtendedOpenTelemetry.
+      // Having the incubator module without ExtendedOpenTelemetry class should still return false
+      // for those tests to avoid a ClassNotFoundException.
+      return false;
+    }
+  }
+
+  /**
+   * Returns the boolean value of the given property name from system properties and environment
+   * variables.
+   *
+   * <p>It's recommended to use {@link #getBoolean(OpenTelemetry, String...)} instead to support
+   * Declarative Config.
+   */
   public static boolean getBoolean(String propertyName, boolean defaultValue) {
     String strValue = getString(propertyName);
     return strValue == null ? defaultValue : Boolean.parseBoolean(strValue);
   }
 
+  /**
+   * Returns the boolean value of the given property name from Declarative Config if available,
+   * otherwise falls back to system properties and environment variables.
+   */
+  public static Optional<Boolean> getBoolean(OpenTelemetry openTelemetry, String... propertyName) {
+    DeclarativeConfigProperties node = getDeclarativeConfigNode(openTelemetry, propertyName);
+    if (node != null) {
+      return Optional.ofNullable(node.getBoolean(leaf(propertyName)));
+    }
+    String strValue = getString(toSystemProperty(propertyName));
+    return strValue == null ? Optional.empty() : Optional.of(Boolean.parseBoolean(strValue));
+  }
+
+  /**
+   * Returns the int value of the given property name from system properties and environment
+   * variables.
+   */
   public static int getInt(String propertyName, int defaultValue) {
     String strValue = getString(propertyName);
     if (strValue == null) {
@@ -34,26 +105,47 @@ public static int getInt(String propertyName, int defaultValue) {
     }
   }
 
+  /**
+   * Returns the string value of the given property name from system properties and environment
+   * variables.
+   *
+   * <p>It's recommended to use {@link #getString(OpenTelemetry, String...)} instead to support
+   * Declarative Config.
+   */
   @Nullable
   public static String getString(String propertyName) {
-    String value = System.getProperty(propertyName);
-    if (value != null) {
-      return value;
-    }
-    return System.getenv(toEnvVarName(propertyName));
+    return config.get(normalizePropertyKey(propertyName));
   }
 
-  public static String getString(String propertyName, String defaultValue) {
-    String strValue = getString(propertyName);
-    return strValue == null ? defaultValue : strValue;
+  /**
+   * Returns the string value of the given property name from Declarative Config if available,
+   * otherwise falls back to system properties and environment variables.
+   */
+  public static Optional<String> getString(OpenTelemetry openTelemetry, String... propertyName) {
+    DeclarativeConfigProperties node = getDeclarativeConfigNode(openTelemetry, propertyName);
+    if (node != null) {
+      return Optional.ofNullable(node.getString(leaf(propertyName)));
+    }
+    return Optional.ofNullable(getString(toSystemProperty(propertyName)));
   }
 
-  public static List<String> getList(String propertyName, List<String> defaultValue) {
-    String value = getString(propertyName);
-    if (value == null) {
-      return defaultValue;
+  /**
+   * Returns the list of strings value of the given property name from Declarative Config if
+   * available, otherwise falls back to system properties and environment variables.
+   */
+  public static List<String> getList(OpenTelemetry openTelemetry, String... propertyName) {
+    DeclarativeConfigProperties node = getDeclarativeConfigNode(openTelemetry, propertyName);
+    if (node != null) {
+      return node.getScalarList(leaf(propertyName), String.class, emptyList());
     }
-    return filterBlanksAndNulls(value.split(","));
+    return Optional.ofNullable(getString(toSystemProperty(propertyName)))
+        .map(value -> filterBlanksAndNulls(value.split(",")))
+        .orElse(emptyList());
+  }
+
+  /** Returns true if the given OpenTelemetry instance supports Declarative Config. */
+  public static boolean isDeclarativeConfig(OpenTelemetry openTelemetry) {
+    return supportsDeclarativeConfig && openTelemetry instanceof ExtendedOpenTelemetry;
   }
 
   private static List<String> filterBlanksAndNulls(String[] values) {
@@ -63,8 +155,67 @@ private static List<String> filterBlanksAndNulls(String[] values) {
         .collect(Collectors.toList());
   }
 
-  private static String toEnvVarName(String propertyName) {
-    return propertyName.toUpperCase(Locale.ROOT).replace('-', '_').replace('.', '_');
+  private static String leaf(String[] propertyName) {
+    return propertyName[propertyName.length - 1];
+  }
+
+  @Nullable
+  private static DeclarativeConfigProperties getDeclarativeConfigNode(
+      OpenTelemetry openTelemetry, String... propertyName) {
+    if (isDeclarativeConfig(openTelemetry)) {
+      ExtendedOpenTelemetry extendedOpenTelemetry = (ExtendedOpenTelemetry) openTelemetry;
+      ConfigProvider configProvider = extendedOpenTelemetry.getConfigProvider();
+      return getConfigProperties(configProvider, propertyName);
+    }
+    return null;
+  }
+
+  /** Returns the DeclarativeConfigProperties node for the given property name parts. */
+  public static DeclarativeConfigProperties getConfigProperties(
+      ConfigProvider configProvider, String[] propertyName) {
+    DeclarativeConfigProperties instrumentationConfig = configProvider.getInstrumentationConfig();
+    if (instrumentationConfig == null) {
+      return empty();
+    }
+    DeclarativeConfigProperties node = instrumentationConfig.getStructured("java", empty());
+    // last part is the leaf property
+    for (int i = 0; i < propertyName.length - 1; i++) {
+      node = node.getStructured(propertyName[i], empty());
+    }
+    return node;
+  }
+
+  public static String toSystemProperty(String[] propertyName) {
+    for (int i = 0; i < propertyName.length; i++) {
+      if (propertyName[i].endsWith("/development")) {
+        propertyName[i] =
+            "experimental." + propertyName[i].substring(0, propertyName[i].length() - 12);
+      }
+    }
+    return "otel.instrumentation." + String.join(".", propertyName).replace('_', '-');
+  }
+
+  /**
+   * Normalize an environment variable key by converting to lower case and replacing "_" with ".".
+   */
+  public static String normalizeEnvironmentVariableKey(String key) {
+    return key.toLowerCase(Locale.ROOT).replace("_", ".");
+  }
+
+  /** Normalize a property key by converting to lower case and replacing "-" with ".". */
+  public static String normalizePropertyKey(String key) {
+    return key.toLowerCase(Locale.ROOT).replace("-", ".");
+  }
+
+  /**
+   * Returns a copy of system properties which is safe to iterate over.
+   *
+   * <p>In java 8 and android environments, iterating through system properties may trigger {@link
+   * ConcurrentModificationException}. This method ensures callers can iterate safely without risk
+   * of exception. See https://github.com/open-telemetry/opentelemetry-java/issues/6732 for details.
+   */
+  public static Properties safeSystemProperties() {
+    return (Properties) System.getProperties().clone();
   }
 
   private ConfigPropertiesUtil() {}