Introduce ConfigProvider API

api/incubator/build.gradle.kts

@@ -14,6 +14,11 @@ dependencies {
 
   annotationProcessor("com.google.auto.value:auto-value")
 
+  // To use parsed config file as input for YamlStructuredConfigPropertiesTest
+  testImplementation(project(":sdk-extensions:incubator"))
+  // TODO (jack-berg): Why is this dependency not brought in as transitive dependency of :sdk-extensions:incubator?
+  testImplementation("com.fasterxml.jackson.core:jackson-databind")
+
   testImplementation(project(":sdk:testing"))
 
   testImplementation("io.opentelemetry.semconv:opentelemetry-semconv-incubating")

api/incubator/src/main/java/io/opentelemetry/api/incubator/config/ConfigProvider.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.incubator.config;
+
+import javax.annotation.Nullable;
+import javax.annotation.concurrent.ThreadSafe;
+
+/**
+ * A registry for accessing configuration.
+ *
+ * <p>The name <i>Provider</i> is for consistency with other languages and it is <b>NOT</b> loaded
+ * using reflection.
+ *
+ * <p>See {@link InstrumentationConfigUtil} for convenience methods for extracting config from
+ * {@link ConfigProvider}.
+ */
+@ThreadSafe
+public interface ConfigProvider {
+
+  /**
+   * Returns the {@link StructuredConfigProperties} corresponding to <a
+   * href="https://github.com/open-telemetry/opentelemetry-configuration/blob/main/schema/instrumentation.json">instrumentation
+   * config</a>, or {@code null} if file configuration is not used.
+   *
+   * @return the instrumentation {@link StructuredConfigProperties}
+   */
+  @Nullable
+  StructuredConfigProperties getInstrumentationConfig();
+
+  /** Returns a no-op {@link ConfigProvider}. */
+  static ConfigProvider noop() {
+    return () -> null;
+  }
+}

api/incubator/src/main/java/io/opentelemetry/api/incubator/config/GlobalConfigProvider.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.incubator.config;
+
+import io.opentelemetry.api.GlobalOpenTelemetry;
+import java.util.concurrent.atomic.AtomicReference;
+import javax.annotation.Nullable;
+
+/**
+ * This class provides a temporary global accessor for {@link ConfigProvider} until the config API
+ * is marked stable. It will eventually be merged into {@link GlobalOpenTelemetry}.
+ */
+// We intentionally assign to be used for error reporting.
+@SuppressWarnings("StaticAssignmentOfThrowable")
+public final class GlobalConfigProvider {
+
+  private static final AtomicReference<ConfigProvider> instance =
+      new AtomicReference<>(ConfigProvider.noop());
+
+  @SuppressWarnings("NonFinalStaticField")
+  @Nullable
+  private static volatile Throwable setInstanceCaller;
+
+  private GlobalConfigProvider() {}
+
+  /** Returns the globally registered {@link ConfigProvider}. */
+  // instance cannot be set to null
+  @SuppressWarnings("NullAway")
+  public static ConfigProvider get() {
+    return instance.get();
+  }
+
+  /**
+   * Sets the global {@link ConfigProvider}. Future calls to {@link #get()} will return the provided
+   * {@link ConfigProvider} instance. This should be called once as early as possible in your
+   * application initialization logic.
+   */
+  public static void set(ConfigProvider configProvider) {
+    boolean changed = instance.compareAndSet(ConfigProvider.noop(), configProvider);
+    if (!changed && (configProvider != ConfigProvider.noop())) {
+      throw new IllegalStateException(
+          "GlobalConfigProvider.set has already been called. GlobalConfigProvider.set "
+              + "must be called only once before any calls to GlobalConfigProvider.get. "
+              + "Previous invocation set to cause of this exception.",
+          setInstanceCaller);
+    }
+    setInstanceCaller = new Throwable();
+  }
+
+  /**
+   * Unsets the global {@link ConfigProvider}. This is only meant to be used from tests which need
+   * to reconfigure {@link ConfigProvider}.
+   */
+  public static void resetForTest() {
+    instance.set(ConfigProvider.noop());
+  }
+}

api/incubator/src/main/java/io/opentelemetry/api/incubator/config/InstrumentationConfigUtil.java

@@ -0,0 +1,117 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.incubator.config;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import javax.annotation.Nullable;
+
+/**
+ * A collection of convenience methods to extract instrumentation config from {@link
+ * ConfigProvider#getInstrumentationConfig()}.
+ */
+public class InstrumentationConfigUtil {
+
+  // TODO (jack-berg): add helper function to access nested structures with dot notation
+
+  /**
+   * Return a map representation of the peer service map entries in {@code
+   * .instrumentation.general.peer.service_mapping}, or null if none is configured.
+   */
+  @Nullable
+  public static Map<String, String> peerServiceMapping(ConfigProvider configProvider) {
+    Optional<List<StructuredConfigProperties>> optServiceMappingList =
+        Optional.ofNullable(configProvider.getInstrumentationConfig())
+            .map(instrumentationConfig -> instrumentationConfig.getStructured("general"))
+            .map(generalConfig -> generalConfig.getStructured("peer"))
+            .map(httpConfig -> httpConfig.getStructuredList("service_mapping"));
+    if (!optServiceMappingList.isPresent()) {
+      return null;
+    }
+    Map<String, String> serviceMapping = new HashMap<>();
+    optServiceMappingList
+        .get()
+        .forEach(
+            entry -> {
+              String peer = entry.getString("peer");
+              String service = entry.getString("service");
+              if (peer != null && service != null) {
+                serviceMapping.put(peer, service);
+              }
+            });
+    return serviceMapping;
+  }
+
+  /**
+   * Return {@code .instrumentation.general.http.client.request_captured_headers}, or null if none
+   * is configured.
+   */
+  @Nullable
+  public static List<String> httpClientRequestCapturedHeaders(ConfigProvider configProvider) {
+    return Optional.ofNullable(configProvider.getInstrumentationConfig())
+        .map(instrumentationConfig -> instrumentationConfig.getStructured("general"))
+        .map(generalConfig -> generalConfig.getStructured("http"))
+        .map(httpConfig -> httpConfig.getStructured("client"))
+        .map(clientConfig -> clientConfig.getScalarList("request_captured_headers", String.class))
+        .orElse(null);
+  }
+
+  /**
+   * Return {@code .instrumentation.general.http.client.response_captured_headers}, or null if none
+   * is configured.
+   */
+  @Nullable
+  public static List<String> httpClientResponseCapturedHeaders(ConfigProvider configProvider) {
+    return Optional.ofNullable(configProvider.getInstrumentationConfig())
+        .map(instrumentationConfig -> instrumentationConfig.getStructured("general"))
+        .map(generalConfig -> generalConfig.getStructured("http"))
+        .map(httpConfig -> httpConfig.getStructured("client"))
+        .map(clientConfig -> clientConfig.getScalarList("response_captured_headers", String.class))
+        .orElse(null);
+  }
+
+  /**
+   * Return {@code .instrumentation.general.http.server.request_captured_headers}, or null if none
+   * is configured.
+   */
+  @Nullable
+  public static List<String> httpServerRequestCapturedHeaders(ConfigProvider configProvider) {
+    return Optional.ofNullable(configProvider.getInstrumentationConfig())
+        .map(instrumentationConfig -> instrumentationConfig.getStructured("general"))
+        .map(generalConfig -> generalConfig.getStructured("http"))
+        .map(httpConfig -> httpConfig.getStructured("server"))
+        .map(clientConfig -> clientConfig.getScalarList("request_captured_headers", String.class))
+        .orElse(null);
+  }
+
+  /**
+   * Return {@code .instrumentation.general.http.server.response_captured_headers}, or null if none
+   * is configured.
+   */
+  @Nullable
+  public static List<String> httpSeverResponseCapturedHeaders(ConfigProvider configProvider) {
+    return Optional.ofNullable(configProvider.getInstrumentationConfig())
+        .map(instrumentationConfig -> instrumentationConfig.getStructured("general"))
+        .map(generalConfig -> generalConfig.getStructured("http"))
+        .map(httpConfig -> httpConfig.getStructured("server"))
+        .map(clientConfig -> clientConfig.getScalarList("response_captured_headers", String.class))
+        .orElse(null);
+  }
+
+  /** Return {@code .instrumentation.java.<instrumentationName>}, or null if none is configured. */
+  @Nullable
+  public static StructuredConfigProperties javaInstrumentationConfig(
+      ConfigProvider configProvider, String instrumentationName) {
+    return Optional.ofNullable(configProvider.getInstrumentationConfig())
+        .map(instrumentationConfig -> instrumentationConfig.getStructured("java"))
+        .map(generalConfig -> generalConfig.getStructured(instrumentationName))
+        .orElse(null);
+  }
+
+  private InstrumentationConfigUtil() {}
+}

api/incubator/src/main/java/io/opentelemetry/api/incubator/config/StructuredConfigException.java

@@ -0,0 +1,22 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.incubator.config;
+
+/** An exception that is thrown if the user-provided file configuration is invalid. */
+public final class StructuredConfigException extends RuntimeException {
+
+  private static final long serialVersionUID = 3036584181551130522L;
+
+  /** Create a new configuration exception with specified {@code message} and without a cause. */
+  public StructuredConfigException(String message) {
+    super(message);
+  }
+
+  /** Create a new configuration exception with specified {@code message} and {@code cause}. */
+  public StructuredConfigException(String message, Throwable cause) {
+    super(message, cause);
+  }
+}

sdk-extensions/autoconfigure-spi/src/main/java/io/opentelemetry/sdk/autoconfigure/spi/internal/StructuredConfigProperties.java → api/incubator/src/main/java/io/opentelemetry/api/incubator/config/StructuredConfigProperties.java

@@ -3,12 +3,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.sdk.autoconfigure.spi.internal;
+package io.opentelemetry.api.incubator.config;
 
 import static io.opentelemetry.api.internal.ConfigUtil.defaultIfNull;
 
-import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
-import io.opentelemetry.sdk.autoconfigure.spi.ConfigurationException;
 import java.util.List;
 import java.util.Set;
 import javax.annotation.Nullable;
@@ -28,7 +26,7 @@ public interface StructuredConfigProperties {
    * Returns a {@link String} configuration property.
    *
    * @return null if the property has not been configured
-   * @throws ConfigurationException if the property is not a valid scalar string
+   * @throws StructuredConfigException if the property is not a valid scalar string
    */
   @Nullable
   String getString(String name);
@@ -38,7 +36,7 @@ public interface StructuredConfigProperties {
    *
    * @return a {@link String} configuration property or {@code defaultValue} if a property with
    *     {@code name} has not been configured
-   * @throws ConfigurationException if the property is not a valid scalar string
+   * @throws StructuredConfigException if the property is not a valid scalar string
    */
   default String getString(String name, String defaultValue) {
     return defaultIfNull(getString(name), defaultValue);
@@ -49,7 +47,7 @@ default String getString(String name, String defaultValue) {
    * {@link Boolean#parseBoolean(String)} for handling the values.
    *
    * @return null if the property has not been configured
-   * @throws ConfigurationException if the property is not a valid scalar boolean
+   * @throws StructuredConfigException if the property is not a valid scalar boolean
    */
   @Nullable
   Boolean getBoolean(String name);
@@ -59,7 +57,7 @@ default String getString(String name, String defaultValue) {
    *
    * @return a {@link Boolean} configuration property or {@code defaultValue} if a property with
    *     {@code name} has not been configured
-   * @throws ConfigurationException if the property is not a valid scalar boolean
+   * @throws StructuredConfigException if the property is not a valid scalar boolean
    */
   default boolean getBoolean(String name, boolean defaultValue) {
     return defaultIfNull(getBoolean(name), defaultValue);
@@ -72,7 +70,7 @@ default boolean getBoolean(String name, boolean defaultValue) {
    * {@link Long#intValue()} which may result in loss of precision.
    *
    * @return null if the property has not been configured
-   * @throws ConfigurationException if the property is not a valid scalar integer
+   * @throws StructuredConfigException if the property is not a valid scalar integer
    */
   @Nullable
   Integer getInt(String name);
@@ -85,7 +83,7 @@ default boolean getBoolean(String name, boolean defaultValue) {
    *
    * @return a {@link Integer} configuration property or {@code defaultValue} if a property with
    *     {@code name} has not been configured
-   * @throws ConfigurationException if the property is not a valid scalar integer
+   * @throws StructuredConfigException if the property is not a valid scalar integer
    */
   default int getInt(String name, int defaultValue) {
     return defaultIfNull(getInt(name), defaultValue);
@@ -95,7 +93,7 @@ default int getInt(String name, int defaultValue) {
    * Returns a {@link Long} configuration property.
    *
    * @return null if the property has not been configured
-   * @throws ConfigurationException if the property is not a valid scalar long
+   * @throws StructuredConfigException if the property is not a valid scalar long
    */
   @Nullable
   Long getLong(String name);
@@ -105,7 +103,7 @@ default int getInt(String name, int defaultValue) {
    *
    * @return a {@link Long} configuration property or {@code defaultValue} if a property with {@code
    *     name} has not been configured
-   * @throws ConfigurationException if the property is not a valid scalar long
+   * @throws StructuredConfigException if the property is not a valid scalar long
    */
   default long getLong(String name, long defaultValue) {
     return defaultIfNull(getLong(name), defaultValue);
@@ -115,7 +113,7 @@ default long getLong(String name, long defaultValue) {
    * Returns a {@link Double} configuration property.
    *
    * @return null if the property has not been configured
-   * @throws ConfigurationException if the property is not a valid scalar double
+   * @throws StructuredConfigException if the property is not a valid scalar double
    */
   @Nullable
   Double getDouble(String name);
@@ -125,7 +123,7 @@ default long getLong(String name, long defaultValue) {
    *
    * @return a {@link Double} configuration property or {@code defaultValue} if a property with
    *     {@code name} has not been configured
-   * @throws ConfigurationException if the property is not a valid scalar double
+   * @throws StructuredConfigException if the property is not a valid scalar double
    */
   default double getDouble(String name, double defaultValue) {
     return defaultIfNull(getDouble(name), defaultValue);
@@ -139,8 +137,8 @@ default double getDouble(String name, double defaultValue) {
    * @param scalarType the scalar type, one of {@link String}, {@link Boolean}, {@link Long} or
    *     {@link Double}
    * @return a {@link List} configuration property, or null if the property has not been configured
-   * @throws ConfigurationException if the property is not a valid sequence of scalars, or if {@code
-   *     scalarType} is not supported
+   * @throws StructuredConfigException if the property is not a valid sequence of scalars, or if
+   *     {@code scalarType} is not supported
    */
   @Nullable
   <T> List<T> getScalarList(String name, Class<T> scalarType);
@@ -149,10 +147,12 @@ default double getDouble(String name, double defaultValue) {
    * Returns a {@link List} configuration property. Entries which are not strings are converted to
    * their string representation.
    *
-   * @see ConfigProperties#getList(String name)
+   * @param name the property name
+   * @param scalarType the scalar type, one of {@link String}, {@link Boolean}, {@link Long} or
+   *     {@link Double}
    * @return a {@link List} configuration property or {@code defaultValue} if a property with {@code
    *     name} has not been configured
-   * @throws ConfigurationException if the property is not a valid sequence of scalars
+   * @throws StructuredConfigException if the property is not a valid sequence of scalars
    */
   default <T> List<T> getScalarList(String name, Class<T> scalarType, List<T> defaultValue) {
     return defaultIfNull(getScalarList(name, scalarType), defaultValue);
@@ -163,7 +163,7 @@ default <T> List<T> getScalarList(String name, Class<T> scalarType, List<T> defa
    *
    * @return a map-valued configuration property, or {@code null} if {@code name} has not been
    *     configured
-   * @throws ConfigurationException if the property is not a mapping
+   * @throws StructuredConfigException if the property is not a mapping
    */
   @Nullable
   StructuredConfigProperties getStructured(String name);
@@ -173,7 +173,7 @@ default <T> List<T> getScalarList(String name, Class<T> scalarType, List<T> defa
    *
    * @return a list of map-valued configuration property, or {@code null} if {@code name} has not
    *     been configured
-   * @throws ConfigurationException if the property is not a sequence of mappings
+   * @throws StructuredConfigException if the property is not a sequence of mappings
    */
   @Nullable
   List<StructuredConfigProperties> getStructuredList(String name);