support inferred spans use case

Author: zeitlinger

instrumentation-api-incubator/README.md

@@ -0,0 +1,92 @@
+# 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/src/main/java/io/opentelemetry/instrumentation/api/incubator/config/bridge/DeclarativeConfigPropertiesBridgeBuilder.java

@@ -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/config/bridge/DeclarativeConfigPropertiesBridgeBuilderTest.java

@@ -6,7 +6,6 @@
 package io.opentelemetry.instrumentation.api.incubator.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);

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: