make declarative config bridge usable by spring starter and contrib (#14497)

Co-authored-by: otelbot <[email protected]>

Author: zeitlinger

instrumentation-api-incubator/README.md

@@ -0,0 +1,91 @@
+# OpenTelemetry Instrumentation API Incubator
+
+Instrumentation API Incubator is a collection of libraries that provide additional functionality
+for OpenTelemetry instrumentation and auto-configuration. It is intended to be used by
+instrumentation authors and auto-configuration providers to enhance their capabilities and provide a
+more consistent experience when working with OpenTelemetry.
+
+## Declarative Config Bridge
+
+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.
+
+### 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:
+
+```java
+class InferredSpansConfig {
+  static SpanProcessor create(ConfigProperties properties) {
+    // read properties here
+    boolean backupDiagnosticFiles =
+        properties.getBoolean("otel.inferred.spans.backup.diagnostic.files", false);
+  }
+}
+```
+
+The auto configuration **without declarative config** passes the provided properties directly:
+
+```java
+
+@AutoService(AutoConfigurationCustomizerProvider.class)
+public class InferredSpansAutoConfig implements AutoConfigurationCustomizerProvider {
+
+  @Override
+  public void customize(AutoConfigurationCustomizer config) {
+    config.addTracerProviderCustomizer(
+        (providerBuilder, properties) -> {
+          providerBuilder.addSpanProcessor(InferredSpansConfig.create(properties));
+          return providerBuilder;
+        });
+  }
+}
+```
+
+The auto configuration **with declarative config** uses the Declarative Config Bridge to be able to
+use common configuration method:
+
+Let's first look at the yaml file that is used to configure the inferred spans processor:
+
+```yaml
+file_format: 1.0-rc.1
+tracer_provider:
+  processors:
+    - inferred_spans:
+        backup:
+          diagnostic:
+            files: true
+```
+
+And now the component provider that uses the Declarative Config Bridge:
+
+```java
+
+@AutoService(ComponentProvider.class)
+public class InferredSpansComponentProvider implements ComponentProvider<SpanProcessor> {
+
+  @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));
+  }
+
+  @Override
+  public Class<SpanProcessor> getType() {
+    return SpanProcessor.class;
+  }
+}
+```

instrumentation-api-incubator/build.gradle.kts

@@ -14,6 +14,8 @@ dependencies {
   api("io.opentelemetry.semconv:opentelemetry-semconv")
   api(project(":instrumentation-api"))
   api("io.opentelemetry:opentelemetry-api-incubator")
+  compileOnly("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure")
+  compileOnly("io.opentelemetry:opentelemetry-sdk-extension-incubator")
 
   compileOnly("com.google.auto.value:auto-value-annotations")
   annotationProcessor("com.google.auto.value:auto-value")
@@ -22,6 +24,8 @@ dependencies {
   testImplementation("io.opentelemetry:opentelemetry-sdk")
   testImplementation("io.opentelemetry:opentelemetry-sdk-testing")
   testImplementation("io.opentelemetry.semconv:opentelemetry-semconv-incubating")
+  testImplementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure")
+  testImplementation("io.opentelemetry:opentelemetry-sdk-extension-incubator")
 }
 
 tasks {

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/sdk/config/bridge/ConfigPropertiesUtil.java

@@ -0,0 +1,23 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.incubator.sdk.config.bridge;
+
+public final class ConfigPropertiesUtil {
+  private ConfigPropertiesUtil() {}
+
+  public static String propertyYamlPath(String propertyName) {
+    return yamlPath(propertyName);
+  }
+
+  static String yamlPath(String property) {
+    String[] segments = DeclarativeConfigPropertiesBridge.getSegments(property);
+    if (segments.length == 0) {
+      throw new IllegalArgumentException("Invalid property: " + property);
+    }
+
+    return "'instrumentation/development' / 'java' / '" + String.join("' / '", segments) + "'";
+  }
+}

javaagent-extension-api/src/main/java/io/opentelemetry/javaagent/extension/internal/DeclarativeConfigPropertiesBridge.java renamed to instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/sdk/config/bridge/DeclarativeConfigPropertiesBridge.java

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.javaagent.extension.internal;
+package io.opentelemetry.instrumentation.api.incubator.sdk.config.bridge;
 
 import static io.opentelemetry.api.incubator.config.DeclarativeConfigProperties.empty;
 
@@ -169,7 +169,7 @@ private <T> T getPropertyValue(
     return extractor.apply(target, lastPart);
   }
 
-  private static String[] getSegments(String property) {
+  static String[] getSegments(String property) {
     if (property.startsWith(OTEL_INSTRUMENTATION_PREFIX)) {
       property = property.substring(OTEL_INSTRUMENTATION_PREFIX.length());
     }

javaagent-extension-api/src/main/java/io/opentelemetry/javaagent/extension/internal/DeclarativeConfigPropertiesBridgeBuilder.java renamed to instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/sdk/config/bridge/DeclarativeConfigPropertiesBridgeBuilder.java

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.javaagent.extension.internal;
+package io.opentelemetry.instrumentation.api.incubator.sdk.config.bridge;
 
 import static io.opentelemetry.api.incubator.config.DeclarativeConfigProperties.empty;
 
@@ -21,9 +21,6 @@
 /**
  * A builder for {@link DeclarativeConfigPropertiesBridge} that allows adding translations and fixed
  * values for properties.
- *
- * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
- * at any time.
  */
 public class DeclarativeConfigPropertiesBridgeBuilder {
   /**
@@ -82,6 +79,17 @@ public ConfigProperties build(AutoConfiguredOpenTelemetrySdk autoConfiguredOpenT
         "AutoConfiguredOpenTelemetrySdk does not have ConfigProperties or DeclarativeConfigProperties. This is likely a programming error in opentelemetry-java");
   }
 
+  /**
+   * Build {@link ConfigProperties} from the provided {@link DeclarativeConfigProperties} node.
+   *
+   * @param node the declarative config properties to build from
+   * @return a new instance of {@link ConfigProperties}
+   */
+  public ConfigProperties build(@Nullable DeclarativeConfigProperties node) {
+    return new DeclarativeConfigPropertiesBridge(
+        node == null ? empty() : node, mappings, overrideValues);
+  }
+
   /**
    * Build {@link ConfigProperties} from the {@link DeclarativeConfigProperties} provided by the
    * instrumentation configuration.
@@ -94,12 +102,7 @@ public ConfigProperties build(AutoConfiguredOpenTelemetrySdk autoConfiguredOpenT
    */
   public ConfigProperties buildFromInstrumentationConfig(
       @Nullable DeclarativeConfigProperties instrumentationConfig) {
-    // leave the name "build" for a future method that builds from a DeclarativeConfigProperties
-    // instance that doesn't come from the top-level instrumentation config
-    if (instrumentationConfig == null) {
-      instrumentationConfig = DeclarativeConfigProperties.empty();
-    }
-    return new DeclarativeConfigPropertiesBridge(
-        instrumentationConfig.getStructured("java", empty()), mappings, overrideValues);
+    return build(
+        instrumentationConfig == null ? null : instrumentationConfig.getStructured("java"));
   }
 }

instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/sdk/config/bridge/ConfigPropertiesUtilTest.java

@@ -0,0 +1,19 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.incubator.sdk.config.bridge;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.junit.jupiter.api.Test;
+
+class ConfigPropertiesUtilTest {
+  @Test
+  void propertyYamlPath() {
+    assertThat(ConfigPropertiesUtil.propertyYamlPath("google.otel.auth.target.signals"))
+        .isEqualTo(
+            "'instrumentation/development' / 'java' / 'google' / 'otel' / 'auth' / 'target' / 'signals'");
+  }
+}

javaagent-extension-api/src/test/java/io/opentelemetry/javaagent/extension/internal/DeclarativeConfigPropertiesBridgeBuilderTest.java renamed to instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/sdk/config/bridge/DeclarativeConfigPropertiesBridgeBuilderTest.java

@@ -3,10 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.javaagent.extension.internal;
+package io.opentelemetry.instrumentation.api.incubator.sdk.config.bridge;
 
 import static org.assertj.core.api.Assertions.assertThat;
-import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.when;
@@ -47,7 +46,7 @@ void shouldUseConfigProviderForDeclarativeConfiguration() {
     when(javaNodeMock.getString(propertyName)).thenReturn(expectedValue);
 
     DeclarativeConfigProperties instrumentationConfigMock = mock(DeclarativeConfigProperties.class);
-    when(instrumentationConfigMock.getStructured(eq("java"), any())).thenReturn(javaNodeMock);
+    when(instrumentationConfigMock.getStructured(eq("java"))).thenReturn(javaNodeMock);
 
     ConfigProvider configProviderMock = mock(ConfigProvider.class);
     when(configProviderMock.getInstrumentationConfig()).thenReturn(instrumentationConfigMock);

javaagent-extension-api/src/test/java/io/opentelemetry/javaagent/extension/internal/DeclarativeConfigPropertiesBridgeTest.java renamed to instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/sdk/config/bridge/DeclarativeConfigPropertiesBridgeTest.java

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.javaagent.extension.internal;
+package io.opentelemetry.instrumentation.api.incubator.sdk.config.bridge;
 
 import static org.assertj.core.api.Assertions.assertThat;
 

javaagent-extension-api/src/test/resources/config.yaml renamed to instrumentation-api-incubator/src/test/resources/config.yaml

@@ -1,4 +1,4 @@
-file_format: 0.4
+file_format: 1.0-rc.1
 instrumentation/development:
   java:
     acme:

javaagent-tooling/build.gradle.kts

@@ -20,6 +20,7 @@ dependencies {
 
   implementation("io.opentelemetry:opentelemetry-api")
   implementation("io.opentelemetry:opentelemetry-sdk")
+  implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure-spi")
   implementation("io.opentelemetry:opentelemetry-extension-kotlin")
   implementation("io.opentelemetry:opentelemetry-extension-trace-propagators")
   // the incubator's ViewConfigCustomizer is used to support loading yaml-based metric views