Add contrib-facing helpers to the declarative config bridge

CHANGELOG.md

@@ -4,9 +4,11 @@
 
 ### 🚫 Deprecations
 
+- Deprecate `ConfigPropertiesBackedConfigProvider` in favor of `DeclarativeConfigBridge`. It will be
+  removed in 2.31.0.
 - Deprecate `DeclarativeConfigPropertiesBridgeBuilder`. Read declarative component configuration
   through `DeclarativeConfigProperties` directly. To expose `ConfigProperties` through the
-  declarative configuration API, use `ConfigPropertiesBackedConfigProvider`.
+  declarative configuration API, use `DeclarativeConfigBridge`.
 
 ### 📈 Enhancements
 

declarative-config-bridge/README.md

@@ -4,50 +4,53 @@
 > `DeclarativeConfigPropertiesBridgeBuilder` is deprecated and will be removed in 3.0. Read
 > declarative component configuration through `DeclarativeConfigProperties` directly. To expose
 > `ConfigProperties` through the declarative configuration API, use
-> `ConfigPropertiesBackedConfigProvider`.
+> `DeclarativeConfigBridge`.
 
 Declarative Config Bridge allows instrumentation authors to access configuration in a uniform way,
 regardless of the configuration source.
 
-The bridge allows you to read configuration using the system property style when dealing with
-declarative configuration.
+The bridge lets callers expose either the complete flat instrumentation configuration or a
+component's flat property namespace through the declarative configuration API.
 
 ## Example
 
-As an example, let's look at the inferred spans configuration.
-First, there is a configuration method that reads the properties and is unaware of the source of the
-configuration:
+As an example, let's look at the contrib inferred spans configuration.
+It reads declarative keys such as `backup_diagnostic_files`, while preserving flat property support
+for `otel.inferred.spans.backup.diagnostic.files`.
 
 ```java
 class InferredSpansConfig {
-  static SpanProcessor create(ConfigProperties properties) {
-    // read properties here
-    boolean backupDiagnosticFiles =
-        properties.getBoolean("otel.inferred.spans.backup.diagnostic.files", false);
+  static SpanProcessor createSpanProcessor(DeclarativeConfigProperties properties) {
+    boolean backupDiagnosticFiles = properties.getBoolean("backup_diagnostic_files", false);
   }
 }
 ```
 
-The auto configuration **without declarative config** passes the provided properties directly:
+The auto configuration path can bridge flat config into that declarative view:
 
-```java
+`createComponentProperties(...)` returns the same root-relative configuration shape that
+`ComponentProvider.create(...)` receives for native declarative configuration.
 
+```java
 @AutoService(AutoConfigurationCustomizerProvider.class)
 public class InferredSpansAutoConfig implements AutoConfigurationCustomizerProvider {
 
   @Override
   public void customize(AutoConfigurationCustomizer config) {
     config.addTracerProviderCustomizer(
         (providerBuilder, properties) -> {
-          providerBuilder.addSpanProcessor(InferredSpansConfig.create(properties));
+          DeclarativeConfigProperties declarativeProperties =
+              DeclarativeConfigBridge.createComponentProperties(
+                properties, "otel.inferred.spans.");
+          providerBuilder.addSpanProcessor(
+              InferredSpansConfig.createSpanProcessor(declarativeProperties));
           return providerBuilder;
         });
   }
 }
 ```
 
-The auto configuration **with declarative config** uses the Declarative Config Bridge to be able to
-use common configuration method:
+The declarative component provider can use the same config method directly:
 
 Let's first look at the yaml file that is used to configure the inferred spans processor:
 
@@ -56,35 +59,40 @@ file_format: 1.1
 tracer_provider:
   processors:
     - inferred_spans:
-        backup:
-          diagnostic:
-            files: true
+        backup_diagnostic_files: true
 ```
 
-And now the component provider that uses the Declarative Config Bridge:
+And now the component provider:
 
 ```java
-
 @AutoService(ComponentProvider.class)
-public class InferredSpansComponentProvider implements ComponentProvider {
+public class InferredSpansSpanProcessorProvider implements ComponentProvider {
 
   @Override
   public String getName() {
     return "inferred_spans";
   }
 
   @Override
-  public SpanProcessor create(DeclarativeConfigProperties config) {
-    return InferredSpansConfig.create(
-        new DeclarativeConfigPropertiesBridgeBuilder()
-            // crop the prefix, because the properties are under the "inferred_spans" processor
-            .addMapping("otel.inferred.spans.", "")
-            .build(config));
+  public Class<SpanProcessor> getType() {
+    return SpanProcessor.class;
   }
 
   @Override
-  public Class<SpanProcessor> getType() {
-    return SpanProcessor.class;
+  public SpanProcessor create(DeclarativeConfigProperties properties) {
+    return InferredSpansConfig.createSpanProcessor(properties);
   }
 }
 ```
+
+For duration properties, contrib's `span-stacktrace` and `inferred-spans` use
+`DeclarativeConfigDurationUtil.getDuration(...)`:
+
+```java
+Duration minDuration =
+    DeclarativeConfigDurationUtil.getDuration(properties, "min_duration");
+```
+
+String duration values such as `42ms` are supported when the declarative config is backed by flat
+`ConfigProperties`. For other declarative-config implementations, durations must already be
+normalized to integer milliseconds.

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

@@ -12,25 +12,30 @@
 /**
  * A {@link ConfigProvider} implementation backed by {@link ConfigProperties}.
  *
- * <p>This allows instrumentations to always use {@code ExtendedOpenTelemetry.getConfigProvider()}
- * regardless of whether the user started with system properties or YAML.
+ * @deprecated Use {@link DeclarativeConfigBridge#createInstrumentationConfig(ConfigProperties)}.
+ *     This class will be removed in 2.31.0.
  */
+@Deprecated // will be removed in 2.31.0
 public final class ConfigPropertiesBackedConfigProvider implements ConfigProvider {
 
-  private final DeclarativeConfigProperties instrumentationConfig;
+  private final ConfigProvider delegate;
 
+  /**
+   * @deprecated Use {@link DeclarativeConfigBridge#createInstrumentationConfig(ConfigProperties)}.
+   *     This method will be removed in 2.31.0.
+   */
+  @Deprecated // will be removed in 2.31.0
   public static ConfigProvider create(ConfigProperties configProperties) {
-    return new ConfigPropertiesBackedConfigProvider(configProperties);
+    return new ConfigPropertiesBackedConfigProvider(
+        DeclarativeConfigBridge.createInstrumentationConfig(configProperties));
   }
 
-  private ConfigPropertiesBackedConfigProvider(ConfigProperties configProperties) {
-    this.instrumentationConfig =
-        ConfigPropertiesBackedDeclarativeConfigProperties.createInstrumentationConfig(
-            configProperties);
+  private ConfigPropertiesBackedConfigProvider(ConfigProvider delegate) {
+    this.delegate = delegate;
   }
 
   @Override
   public DeclarativeConfigProperties getInstrumentationConfig() {
-    return instrumentationConfig;
+    return delegate.getInstrumentationConfig();
   }
 }

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

@@ -28,6 +28,8 @@
 final class ConfigPropertiesBackedDeclarativeConfigProperties
     implements DeclarativeConfigProperties {
 
+  private static final String JAVA_DECLARATIVE_PREFIX = "java.";
+  private static final String INSTRUMENTATION_PROPERTY_PREFIX = "otel.instrumentation.";
   private static final String JAVA_COMMON_SERVICE_PEER_MAPPING = "java.common.service_peer_mapping";
 
   private static final Map<String, String> SPECIAL_MAPPINGS;
@@ -94,16 +96,30 @@ final class ConfigPropertiesBackedDeclarativeConfigProperties
 
   private final ConfigProperties configProperties;
   private final List<String> path;
+  private final String declarativePrefix;
+  private final String configPropertyPrefix;
 
   static DeclarativeConfigProperties createInstrumentationConfig(
       ConfigProperties configProperties) {
-    return new ConfigPropertiesBackedDeclarativeConfigProperties(configProperties, emptyList());
+    return new ConfigPropertiesBackedDeclarativeConfigProperties(
+        configProperties, emptyList(), JAVA_DECLARATIVE_PREFIX, INSTRUMENTATION_PROPERTY_PREFIX);
+  }
+
+  static DeclarativeConfigProperties createComponentProperties(
+      ConfigProperties configProperties, String configPropertyPrefix) {
+    return new ConfigPropertiesBackedDeclarativeConfigProperties(
+        configProperties, emptyList(), "", configPropertyPrefix);
   }
 
   private ConfigPropertiesBackedDeclarativeConfigProperties(
-      ConfigProperties configProperties, List<String> path) {
+      ConfigProperties configProperties,
+      List<String> path,
+      String declarativePrefix,
+      String configPropertyPrefix) {
     this.configProperties = configProperties;
     this.path = path;
+    this.declarativePrefix = declarativePrefix;
+    this.configPropertyPrefix = configPropertyPrefix;
   }
 
   @Nullable
@@ -146,6 +162,11 @@ public Long getLong(String name) {
     return configProperties.getLong(resolvePropertyKey(name));
   }
 
+  @Nullable
+  Duration getDuration(String name) {
+    return configProperties.getDuration(resolvePropertyKey(name));
+  }
+
   @Nullable
   @Override
   public Double getDouble(String name) {
@@ -162,7 +183,8 @@ public Double getDouble(String name) {
   public DeclarativeConfigProperties getStructured(String name) {
     List<String> newPath = new ArrayList<>(path);
     newPath.add(name);
-    return new ConfigPropertiesBackedDeclarativeConfigProperties(configProperties, newPath);
+    return new ConfigPropertiesBackedDeclarativeConfigProperties(
+        configProperties, newPath, declarativePrefix, configPropertyPrefix);
   }
 
   @Nullable
@@ -213,12 +235,11 @@ private String resolvePropertyKey(String name) {
       return mappedKey;
     }
 
-    if (!fullPath.startsWith("java.")) {
+    if (!declarativePrefix.isEmpty() && !fullPath.startsWith(declarativePrefix)) {
       return "";
     }
 
-    // Remove "java." prefix and translate the remaining path
-    String[] segments = fullPath.substring(5).split("\\.");
+    String[] segments = fullPath.substring(declarativePrefix.length()).split("\\.");
     StringBuilder translatedPath = new StringBuilder();
 
     for (int i = 0; i < segments.length; i++) {
@@ -228,7 +249,7 @@ private String resolvePropertyKey(String name) {
       translatedPath.append(translateName(segments[i]));
     }
 
-    return "otel.instrumentation." + translatedPath;
+    return configPropertyPrefix + translatedPath;
   }
 
   private String pathWithName(String name) {

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

@@ -0,0 +1,56 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.config.bridge;
+
+import io.opentelemetry.api.incubator.config.ConfigProvider;
+import io.opentelemetry.api.incubator.config.DeclarativeConfigProperties;
+import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
+
+/** Exposes flat {@link ConfigProperties} through the declarative configuration APIs. */
+public final class DeclarativeConfigBridge {
+
+  /**
+   * Creates the complete declarative instrumentation configuration backed by flat {@link
+   * ConfigProperties}.
+   */
+  public static ConfigProvider createInstrumentationConfig(ConfigProperties configProperties) {
+    return createConfigProvider(
+        ConfigPropertiesBackedDeclarativeConfigProperties.createInstrumentationConfig(
+            configProperties));
+  }
+
+  /**
+   * Creates component-local declarative properties backed by flat {@link ConfigProperties}.
+   *
+   * <p>The returned properties have the same root-relative shape as the properties passed to a
+   * declarative {@code ComponentProvider}. For example, a component can read {@code enabled} while
+   * the bridge resolves the value from {@code configPropertyPrefix + "enabled"}.
+   */
+  public static DeclarativeConfigProperties createComponentProperties(
+      ConfigProperties configProperties, String configPropertyPrefix) {
+    return ConfigPropertiesBackedDeclarativeConfigProperties.createComponentProperties(
+        configProperties, configPropertyPrefix);
+  }
+
+  static ConfigProvider createConfigProvider(DeclarativeConfigProperties instrumentationConfig) {
+    return new BridgedConfigProvider(instrumentationConfig);
+  }
+
+  private DeclarativeConfigBridge() {}
+
+  private static final class BridgedConfigProvider implements ConfigProvider {
+    private final DeclarativeConfigProperties instrumentationConfig;
+
+    private BridgedConfigProvider(DeclarativeConfigProperties instrumentationConfig) {
+      this.instrumentationConfig = instrumentationConfig;
+    }
+
+    @Override
+    public DeclarativeConfigProperties getInstrumentationConfig() {
+      return instrumentationConfig;
+    }
+  }
+}

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

@@ -0,0 +1,46 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.config.bridge;
+
+import io.opentelemetry.api.incubator.config.DeclarativeConfigProperties;
+import java.time.Duration;
+import javax.annotation.Nullable;
+
+/**
+ * Helpers for reading duration values from {@link DeclarativeConfigProperties}.
+ *
+ * <p>When the config is backed by flat {@link
+ * io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties}, duration strings such as {@code 42ms}
+ * are supported by delegating to the SDK's standard duration parser.
+ *
+ * <p>For other declarative-config implementations, this utility expects duration values to already
+ * be normalized to integer milliseconds, which means string durations in declarative YAML are not
+ * accepted.
+ */
+public final class DeclarativeConfigDurationUtil {
+
+  /**
+   * Reads a duration from declarative config.
+   *
+   * <p>String duration values are only supported when {@code properties} is a {@link
+   * ConfigPropertiesBackedDeclarativeConfigProperties}. Other implementations must provide integer
+   * milliseconds for the same key.
+   */
+  @Nullable
+  public static Duration getDuration(DeclarativeConfigProperties properties, String key) {
+    if (properties instanceof ConfigPropertiesBackedDeclarativeConfigProperties) {
+      return ((ConfigPropertiesBackedDeclarativeConfigProperties) properties).getDuration(key);
+    }
+
+    Long rawLongValue = properties.getLong(key);
+    if (rawLongValue == null) {
+      return null;
+    }
+    return Duration.ofMillis(rawLongValue);
+  }
+
+  private DeclarativeConfigDurationUtil() {}
+}

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

@@ -51,8 +51,8 @@
  *
  * @deprecated Migrate code that reads declarative component configuration to use {@link
  *     DeclarativeConfigProperties} directly. To expose {@link ConfigProperties} through the
- *     declarative configuration API, use {@link ConfigPropertiesBackedConfigProvider}. This class
- *     will be removed in 3.0.
+ *     declarative configuration API, use {@link DeclarativeConfigBridge}. This class will be
+ *     removed in 3.0.
  */
 @Deprecated // will be removed in 3.0
 final class DeclarativeConfigPropertiesBridge implements ConfigProperties {

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

@@ -24,7 +24,7 @@
  * values for properties.
  *
  * @deprecated Use {@link DeclarativeConfigProperties} directly when reading declarative component
- *     configuration, or use {@link ConfigPropertiesBackedConfigProvider} when exposing a {@link
+ *     configuration, or use {@link DeclarativeConfigBridge} when exposing a {@link
  *     io.opentelemetry.api.incubator.config.ConfigProvider} backed by {@link ConfigProperties}.
  *     This class will be removed in 3.0.
  */