Add contrib-facing helpers to the declarative config bridge

declarative-config-bridge/README.md

@@ -9,45 +9,47 @@
 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 flat `ConfigProperties` through the declarative configuration API,
+including custom property mappings and custom declarative/flat prefixes.
 
 ## 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
-
 @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 =
+              ConfigPropertiesBackedConfigProvider.builder()
+                  .setAccessPath("", "otel.inferred.spans.")
+                  .build(properties)
+                  .getInstrumentationConfig();
+          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 +58,30 @@ 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";
+  public SpanProcessor create(DeclarativeConfigProperties properties) {
+    return InferredSpansConfig.createSpanProcessor(properties);
   }
+}
+```
 
-  @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));
-  }
+For duration properties, contrib's `span-stacktrace` and `inferred-spans` use
+`DeclarativeConfigPropertiesDurationUtil.parseDuration(...)`:
 
-  @Override
-  public Class<SpanProcessor> getType() {
-    return SpanProcessor.class;
-  }
-}
+```java
+Duration minDuration =
+    DeclarativeConfigPropertiesDurationUtil.parseDuration(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

@@ -5,9 +5,12 @@
 
 package io.opentelemetry.instrumentation.config.bridge;
 
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import io.opentelemetry.api.incubator.config.ConfigProvider;
 import io.opentelemetry.api.incubator.config.DeclarativeConfigProperties;
 import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
+import java.util.HashMap;
+import java.util.Map;
 
 /**
  * A {@link ConfigProvider} implementation backed by {@link ConfigProperties}.
@@ -20,13 +23,62 @@ public final class ConfigPropertiesBackedConfigProvider implements ConfigProvide
   private final DeclarativeConfigProperties instrumentationConfig;
 
   public static ConfigProvider create(ConfigProperties configProperties) {
-    return new ConfigPropertiesBackedConfigProvider(configProperties);
+    return new ConfigPropertiesBackedConfigProvider(
+        ConfigPropertiesBackedDeclarativeConfigProperties.createInstrumentationConfig(
+            configProperties));
   }
 
-  private ConfigPropertiesBackedConfigProvider(ConfigProperties configProperties) {
-    this.instrumentationConfig =
-        ConfigPropertiesBackedDeclarativeConfigProperties.createInstrumentationConfig(
-            configProperties);
+  public static Builder builder() {
+    return new Builder();
+  }
+
+  private ConfigPropertiesBackedConfigProvider(DeclarativeConfigProperties instrumentationConfig) {
+    this.instrumentationConfig = instrumentationConfig;
+  }
+
+  public static final class Builder {
+    private final Map<String, String> mappings = new HashMap<>();
+    private String accessRoot =
+        ConfigPropertiesBackedDeclarativeConfigProperties.DEFAULT_ACCESS_ROOT;
+    private String resultPrefix =
+        ConfigPropertiesBackedDeclarativeConfigProperties.DEFAULT_RESULT_PREFIX;
+
+    private Builder() {}
+
+    /**
+     * Adds a mapping from a declarative property path to a flat {@link ConfigProperties} key.
+     *
+     * <p>This is useful when a component is configured under a custom declarative path but still
+     * wants to read an existing flat property name. For example, contrib's inferred spans component
+     * uses declarative keys like {@code backup_diagnostic_files} while reading {@code
+     * otel.inferred.spans.backup.diagnostic.files} from flat config.
+     */
+    @CanIgnoreReturnValue
+    public Builder addMapping(String declarativeProperty, String configProperty) {
+      mappings.put(declarativeProperty, configProperty);
+      return this;
+    }
+
+    /**
+     * Sets the declarative path prefix that this bridge reads from and the flat-property prefix it
+     * resolves to.
+     *
+     * <p>This lets callers bridge a subtree directly instead of always starting from {@code java.}
+     * -> {@code otel.instrumentation.}. For example, contrib's inferred spans autoconfigure path
+     * reads the component root directly and resolves it against {@code otel.inferred.spans.}.
+     */
+    @CanIgnoreReturnValue
+    public Builder setAccessPath(String accessRoot, String resultPrefix) {
+      this.accessRoot = accessRoot;
+      this.resultPrefix = resultPrefix;
+      return this;
+    }
+
+    public ConfigProvider build(ConfigProperties configProperties) {
+      return new ConfigPropertiesBackedConfigProvider(
+          ConfigPropertiesBackedDeclarativeConfigProperties.createInstrumentationConfig(
+              configProperties, mappings, accessRoot, resultPrefix));
+    }
   }
 
   @Override

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

@@ -6,6 +6,7 @@
 package io.opentelemetry.instrumentation.config.bridge;
 
 import static java.util.Collections.emptyList;
+import static java.util.Collections.emptyMap;
 import static java.util.Collections.emptySet;
 
 import io.opentelemetry.api.incubator.config.DeclarativeConfigProperties;
@@ -28,6 +29,8 @@
 final class ConfigPropertiesBackedDeclarativeConfigProperties
     implements DeclarativeConfigProperties {
 
+  static final String DEFAULT_ACCESS_ROOT = "java.";
+  static final String DEFAULT_RESULT_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 +97,44 @@ final class ConfigPropertiesBackedDeclarativeConfigProperties
 
   private final ConfigProperties configProperties;
   private final List<String> path;
+  private final Map<String, String> mappings;
+  private final String accessRoot;
+  private final String resultPrefix;
 
   static DeclarativeConfigProperties createInstrumentationConfig(
       ConfigProperties configProperties) {
-    return new ConfigPropertiesBackedDeclarativeConfigProperties(configProperties, emptyList());
+    return createInstrumentationConfig(
+        configProperties, emptyMap(), DEFAULT_ACCESS_ROOT, DEFAULT_RESULT_PREFIX);
+  }
+
+  static DeclarativeConfigProperties createInstrumentationConfig(
+      ConfigProperties configProperties,
+      Map<String, String> mappings,
+      String accessRoot,
+      String resultPrefix) {
+    for (String mapping : mappings.keySet()) {
+      if (SPECIAL_MAPPINGS.containsKey(mapping)) {
+        throw new IllegalArgumentException(
+            "Custom mapping must not override built-in mapping: " + mapping);
+      }
+    }
+    Map<String, String> mergedMappings = new HashMap<>(SPECIAL_MAPPINGS);
+    mergedMappings.putAll(mappings);
+    return new ConfigPropertiesBackedDeclarativeConfigProperties(
+        configProperties, emptyList(), mergedMappings, accessRoot, resultPrefix);
   }
 
   private ConfigPropertiesBackedDeclarativeConfigProperties(
-      ConfigProperties configProperties, List<String> path) {
+      ConfigProperties configProperties,
+      List<String> path,
+      Map<String, String> mappings,
+      String accessRoot,
+      String resultPrefix) {
     this.configProperties = configProperties;
     this.path = path;
+    this.mappings = mappings;
+    this.accessRoot = accessRoot;
+    this.resultPrefix = resultPrefix;
   }
 
   @Nullable
@@ -162,7 +193,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, mappings, accessRoot, resultPrefix);
   }
 
   @Nullable
@@ -208,17 +240,16 @@ private String resolvePropertyKey(String name) {
     String fullPath = pathWithName(name);
 
     // Check explicit property mappings first
-    String mappedKey = SPECIAL_MAPPINGS.get(fullPath);
+    String mappedKey = mappings.get(fullPath);
     if (mappedKey != null) {
       return mappedKey;
     }
 
-    if (!fullPath.startsWith("java.")) {
+    if (!accessRoot.isEmpty() && !fullPath.startsWith(accessRoot)) {
       return "";
     }
 
-    // Remove "java." prefix and translate the remaining path
-    String[] segments = fullPath.substring(5).split("\\.");
+    String[] segments = fullPath.substring(accessRoot.length()).split("\\.");
     StringBuilder translatedPath = new StringBuilder();
 
     for (int i = 0; i < segments.length; i++) {
@@ -228,7 +259,7 @@ private String resolvePropertyKey(String name) {
       translatedPath.append(translateName(segments[i]));
     }
 
-    return "otel.instrumentation." + translatedPath;
+    return resultPrefix + translatedPath;
   }
 
   private String pathWithName(String name) {

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

@@ -0,0 +1,53 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.config.bridge;
+
+import static java.util.Collections.singletonMap;
+
+import io.opentelemetry.api.incubator.config.DeclarativeConfigProperties;
+import io.opentelemetry.sdk.autoconfigure.spi.internal.DefaultConfigProperties;
+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 DeclarativeConfigPropertiesDurationUtil {
+
+  private DeclarativeConfigPropertiesDurationUtil() {}
+
+  /**
+   * 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 parseDuration(DeclarativeConfigProperties properties, String key) {
+    if (properties instanceof ConfigPropertiesBackedDeclarativeConfigProperties) {
+      String rawValue = properties.getString(key);
+      if (rawValue == null || rawValue.isEmpty()) {
+        return null;
+      }
+      return DefaultConfigProperties.createFromMap(singletonMap(key, rawValue)).getDuration(key);
+    }
+
+    Long rawLongValue = properties.getLong(key);
+    if (rawLongValue == null) {
+      return null;
+    }
+    return Duration.ofMillis(rawLongValue);
+  }
+}