Add InstrumentationDefaults helper to declarative-config-bridge

declarative-config-bridge/README.md

@@ -82,3 +82,52 @@ public class InferredSpansComponentProvider implements ComponentProvider {
   }
 }
 ```
+
+## InstrumentationDefaults
+
+`InstrumentationDefaults` lets distribution authors define instrumentation property defaults once
+and have them work in both configuration modes — traditional auto-configuration and declarative
+configuration.
+
+### Usage
+
+```java
+InstrumentationDefaults defaults = new InstrumentationDefaults();
+defaults.setDefault("micrometer", "base_time_unit", "s");
+defaults.setDefault("log4j_appender", "experimental_log_attributes", "true");
+```
+
+Keys use underscore notation (matching the declarative config model). They are translated to
+hyphen notation (`otel.instrumentation.<name>.<key>`) when producing system property keys.
+
+### Auto-configuration (traditional)
+
+Register the defaults as a properties supplier:
+
+```java
+@AutoService(AutoConfigurationCustomizerProvider.class)
+public class MyDistroAutoConfig implements AutoConfigurationCustomizerProvider {
+  @Override
+  public void customize(AutoConfigurationCustomizer autoConfiguration) {
+    autoConfiguration.addPropertiesSupplier(defaults::toConfigProperties);
+  }
+}
+```
+
+### Declarative configuration
+
+Register the defaults as a model customizer:
+
+```java
+@AutoService(DeclarativeConfigurationCustomizerProvider.class)
+public class MyDistroDeclarativeConfig implements DeclarativeConfigurationCustomizerProvider {
+  @Override
+  public void customize(DeclarativeConfigurationCustomizer customizer) {
+    customizer.addModelCustomizer(model -> defaults.applyToModel(model));
+  }
+}
+```
+
+Defaults are injected under `instrumentation/development.java` in the model. Explicit user
+configuration always takes precedence — defaults are only applied for properties not already
+present.

declarative-config-bridge/build.gradle.kts

@@ -8,6 +8,7 @@ group = "io.opentelemetry.instrumentation"
 
 dependencies {
   compileOnly("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure")
+  compileOnly("io.opentelemetry:opentelemetry-sdk-extension-incubator")
   implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure-spi")
   implementation("io.opentelemetry:opentelemetry-api-incubator")
 

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

@@ -0,0 +1,111 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.config.bridge;
+
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
+import io.opentelemetry.sdk.extension.incubator.fileconfig.internal.model.ExperimentalInstrumentationModel;
+import io.opentelemetry.sdk.extension.incubator.fileconfig.internal.model.ExperimentalLanguageSpecificInstrumentationModel;
+import io.opentelemetry.sdk.extension.incubator.fileconfig.internal.model.ExperimentalLanguageSpecificInstrumentationPropertyModel;
+import io.opentelemetry.sdk.extension.incubator.fileconfig.internal.model.OpenTelemetryConfigurationModel;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * Defines instrumentation defaults that work with both traditional property-based configuration and
+ * declarative configuration.
+ *
+ * <p>Usage:
+ *
+ * <pre>{@code
+ * InstrumentationDefaults defaults = new InstrumentationDefaults();
+ * defaults.setDefault("micrometer", "base_time_unit", "s");
+ * defaults.setDefault("log4j_appender", "experimental_log_attributes", "true");
+ *
+ * // Declarative config mode: inject into model
+ * customizer.addModelCustomizer(model -> defaults.applyToModel(model));
+ *
+ * // Traditional mode: translate to ConfigProperties
+ * autoConfiguration.addPropertiesSupplier(defaults::toConfigProperties);
+ * }</pre>
+ */
+public final class InstrumentationDefaults {
+
+  private final Map<String, Map<String, String>> instrumentations = new LinkedHashMap<>();
+
+  /**
+   * Sets a default value for an instrumentation property. Keys use underscore notation (e.g. {@code
+   * base_time_unit}); they are translated to hyphen notation when producing property keys.
+   *
+   * @return {@code this} for chaining
+   */
+  @CanIgnoreReturnValue
+  public InstrumentationDefaults setDefault(String instrumentation, String key, String value) {
+    instrumentations.computeIfAbsent(instrumentation, k -> new LinkedHashMap<>()).put(key, value);
+    return this;
+  }
+
+  /** Translates defaults to {@code otel.instrumentation.*} keys for auto-configuration. */
+  public Map<String, String> toConfigProperties() {
+    HashMap<String, String> map = new HashMap<>();
+    instrumentations.forEach(
+        (instrumentation, properties) ->
+            properties.forEach(
+                (key, value) ->
+                    map.put(
+                        "otel.instrumentation."
+                            + instrumentation.replace('_', '-')
+                            + "."
+                            + key.replace('_', '-'),
+                        value)));
+    return map;
+  }
+
+  /**
+   * Applies defaults to the declarative configuration model under {@code
+   * instrumentation/development.java}. Existing values in the model take precedence; defaults are
+   * only set for properties not already present.
+   */
+  @CanIgnoreReturnValue
+  public OpenTelemetryConfigurationModel applyToModel(OpenTelemetryConfigurationModel model) {
+    if (instrumentations.isEmpty()) {
+      return model;
+    }
+
+    ExperimentalInstrumentationModel instrumentation = model.getInstrumentationDevelopment();
+    if (instrumentation == null) {
+      instrumentation = new ExperimentalInstrumentationModel();
+      model.withInstrumentationDevelopment(instrumentation);
+    }
+    ExperimentalLanguageSpecificInstrumentationModel java = instrumentation.getJava();
+    if (java == null) {
+      java = new ExperimentalLanguageSpecificInstrumentationModel();
+      instrumentation.withJava(java);
+    }
+
+    Map<String, ExperimentalLanguageSpecificInstrumentationPropertyModel> props =
+        java.getAdditionalProperties();
+
+    for (Map.Entry<String, Map<String, String>> entry : instrumentations.entrySet()) {
+      String name = entry.getKey();
+      Map<String, String> defaults = entry.getValue();
+
+      ExperimentalLanguageSpecificInstrumentationPropertyModel propModel = props.get(name);
+      if (propModel == null) {
+        propModel = new ExperimentalLanguageSpecificInstrumentationPropertyModel();
+        props.put(name, propModel);
+      }
+
+      for (Map.Entry<String, String> defaultEntry : defaults.entrySet()) {
+        propModel
+            .getAdditionalProperties()
+            .putIfAbsent(defaultEntry.getKey(), defaultEntry.getValue());
+      }
+    }
+
+    return model;
+  }
+}

declarative-config-bridge/src/test/java/io/opentelemetry/instrumentation/config/bridge/InstrumentationDefaultsTest.java

@@ -0,0 +1,71 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.config.bridge;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import io.opentelemetry.sdk.extension.incubator.fileconfig.internal.model.OpenTelemetryConfigurationModel;
+import java.util.Map;
+import org.junit.jupiter.api.Test;
+
+class InstrumentationDefaultsTest {
+
+  @Test
+  void toConfigProperties() {
+    InstrumentationDefaults defaults = new InstrumentationDefaults();
+    defaults.setDefault("micrometer", "base_time_unit", "s");
+    defaults.setDefault("log4j_appender", "experimental_log_attributes", "true");
+
+    Map<String, String> props = defaults.toConfigProperties();
+
+    assertThat(props)
+        .containsEntry("otel.instrumentation.micrometer.base-time-unit", "s")
+        .containsEntry("otel.instrumentation.log4j-appender.experimental-log-attributes", "true")
+        .hasSize(2);
+  }
+
+  @Test
+  void applyToModel() {
+    InstrumentationDefaults defaults = new InstrumentationDefaults();
+    defaults.setDefault("micrometer", "base_time_unit", "s");
+
+    OpenTelemetryConfigurationModel model = new OpenTelemetryConfigurationModel();
+    defaults.applyToModel(model);
+
+    assertThat(
+            model
+                .getInstrumentationDevelopment()
+                .getJava()
+                .getAdditionalProperties()
+                .get("micrometer")
+                .getAdditionalProperties())
+        .containsEntry("base_time_unit", "s");
+  }
+
+  @Test
+  void applyToModelDoesNotOverrideExisting() {
+    InstrumentationDefaults defaults = new InstrumentationDefaults();
+    defaults.setDefault("micrometer", "base_time_unit", "s");
+
+    // Pre-populate model with a different value
+    OpenTelemetryConfigurationModel model = new OpenTelemetryConfigurationModel();
+    new InstrumentationDefaults()
+        .setDefault("micrometer", "base_time_unit", "ms")
+        .applyToModel(model);
+
+    // Apply defaults — should not override
+    defaults.applyToModel(model);
+
+    assertThat(
+            model
+                .getInstrumentationDevelopment()
+                .getJava()
+                .getAdditionalProperties()
+                .get("micrometer")
+                .getAdditionalProperties())
+        .containsEntry("base_time_unit", "ms");
+  }
+}