Rebrand file configuration to declarative configuration in documentat…

…ion (#6812)
open-telemetry · Oct 22, 2024 · f52554b · f52554b
1 parent 8793935
commit f52554b
Show file tree

Hide file tree

Showing 22 changed files with 41 additions and 31 deletions.
diff --git a/...try/exporter/logging/otlp/internal/logs/OtlpStdoutLogRecordExporterComponentProvider.java b/...try/exporter/logging/otlp/internal/logs/OtlpStdoutLogRecordExporterComponentProvider.java
@@ -11,7 +11,7 @@
 import io.opentelemetry.sdk.logs.export.LogRecordExporter;
 
 /**
- * File configuration SPI implementation for {@link OtlpStdoutLogRecordExporter}.
+ * Declarative configuration SPI implementation for {@link OtlpStdoutLogRecordExporter}.
  *
  * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
  * at any time.

diff --git a/...try/exporter/logging/otlp/internal/metrics/OtlpStdoutMetricExporterComponentProvider.java b/...try/exporter/logging/otlp/internal/metrics/OtlpStdoutMetricExporterComponentProvider.java
@@ -11,7 +11,7 @@
 import io.opentelemetry.sdk.metrics.export.MetricExporter;
 
 /**
- * File configuration SPI implementation for {@link OtlpStdoutMetricExporter}.
+ * Declarative configuration SPI implementation for {@link OtlpStdoutMetricExporter}.
  *
  * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
  * at any time.

diff --git a/...emetry/exporter/logging/otlp/internal/traces/OtlpStdoutSpanExporterComponentProvider.java b/...emetry/exporter/logging/otlp/internal/traces/OtlpStdoutSpanExporterComponentProvider.java
@@ -11,7 +11,7 @@
 import io.opentelemetry.sdk.trace.export.SpanExporter;
 
 /**
- * File configuration SPI implementation for {@link OtlpStdoutSpanExporter}.
+ * Declarative configuration SPI implementation for {@link OtlpStdoutSpanExporter}.
  *
  * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
  * at any time.

diff --git a/...io/opentelemetry/exporter/logging/internal/ConsoleLogRecordExporterComponentProvider.java b/...io/opentelemetry/exporter/logging/internal/ConsoleLogRecordExporterComponentProvider.java
@@ -11,7 +11,7 @@
 import io.opentelemetry.sdk.logs.export.LogRecordExporter;
 
 /**
- * File configuration SPI implementation for {@link SystemOutLogRecordExporter}.
+ * Declarative configuration SPI implementation for {@link SystemOutLogRecordExporter}.
  *
  * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
  * at any time.

diff --git a/...va/io/opentelemetry/exporter/logging/internal/ConsoleMetricExporterComponentProvider.java b/...va/io/opentelemetry/exporter/logging/internal/ConsoleMetricExporterComponentProvider.java
@@ -11,7 +11,7 @@
 import io.opentelemetry.sdk.metrics.export.MetricExporter;
 
 /**
- * File configuration SPI implementation for {@link LoggingMetricExporter}.
+ * Declarative configuration SPI implementation for {@link LoggingMetricExporter}.
  *
  * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
  * at any time.

diff --git a/...java/io/opentelemetry/exporter/logging/internal/ConsoleSpanExporterComponentProvider.java b/...java/io/opentelemetry/exporter/logging/internal/ConsoleSpanExporterComponentProvider.java
@@ -11,7 +11,7 @@
 import io.opentelemetry.sdk.trace.export.SpanExporter;
 
 /**
- * File configuration SPI implementation for {@link LoggingSpanExporter}.
+ * Declarative configuration SPI implementation for {@link LoggingSpanExporter}.
  *
  * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
  * at any time.

diff --git a/.../java/io/opentelemetry/exporter/otlp/internal/OtlpLogRecordExporterComponentProvider.java b/.../java/io/opentelemetry/exporter/otlp/internal/OtlpLogRecordExporterComponentProvider.java
@@ -19,7 +19,7 @@
 import io.opentelemetry.sdk.logs.export.LogRecordExporter;
 
 /**
- * File configuration SPI implementation for {@link OtlpHttpLogRecordExporter} and {@link
+ * Declarative configuration SPI implementation for {@link OtlpHttpLogRecordExporter} and {@link
  * OtlpGrpcLogRecordExporter}.
  *
  * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change

diff --git a/...ain/java/io/opentelemetry/exporter/otlp/internal/OtlpMetricExporterComponentProvider.java b/...ain/java/io/opentelemetry/exporter/otlp/internal/OtlpMetricExporterComponentProvider.java
@@ -20,7 +20,7 @@
 import io.opentelemetry.sdk.metrics.export.MetricExporter;
 
 /**
- * File configuration SPI implementation for {@link OtlpHttpMetricExporter} and {@link
+ * Declarative configuration SPI implementation for {@link OtlpHttpMetricExporter} and {@link
  * OtlpGrpcMetricExporter}.
  *
  * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change

diff --git a/.../main/java/io/opentelemetry/exporter/otlp/internal/OtlpSpanExporterComponentProvider.java b/.../main/java/io/opentelemetry/exporter/otlp/internal/OtlpSpanExporterComponentProvider.java
@@ -19,7 +19,7 @@
 import io.opentelemetry.sdk.trace.export.SpanExporter;
 
 /**
- * File configuration SPI implementation for {@link OtlpHttpSpanExporter} and {@link
+ * Declarative configuration SPI implementation for {@link OtlpHttpSpanExporter} and {@link
  * OtlpGrpcSpanExporter}.
  *
  * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change

diff --git a/.../main/java/io/opentelemetry/exporter/prometheus/internal/PrometheusComponentProvider.java b/.../main/java/io/opentelemetry/exporter/prometheus/internal/PrometheusComponentProvider.java
@@ -12,7 +12,7 @@
 import io.opentelemetry.sdk.metrics.export.MetricReader;
 
 /**
- * File configuration SPI implementation for {@link PrometheusHttpServer}.
+ * Declarative configuration SPI implementation for {@link PrometheusHttpServer}.
  *
  * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
  * at any time.

diff --git a/...n/java/io/opentelemetry/exporter/zipkin/internal/ZipkinSpanExporterComponentProvider.java b/...n/java/io/opentelemetry/exporter/zipkin/internal/ZipkinSpanExporterComponentProvider.java
@@ -13,7 +13,7 @@
 import java.time.Duration;
 
 /**
- * File configuration SPI implementation for {@link ZipkinSpanExporter}.
+ * Declarative configuration SPI implementation for {@link ZipkinSpanExporter}.
  *
  * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
  * at any time.

diff --git a/.../main/java/io/opentelemetry/extension/trace/propagation/internal/B3ComponentProvider.java b/.../main/java/io/opentelemetry/extension/trace/propagation/internal/B3ComponentProvider.java
@@ -11,8 +11,8 @@
 import io.opentelemetry.sdk.autoconfigure.spi.internal.StructuredConfigProperties;
 
 /**
- * File configuration SPI implementation for {@link B3Propagator} which allows enables the {@link
- * B3Propagator#injectingSingleHeader()}.
+ * Declarative configuration SPI implementation for {@link B3Propagator} which allows enables the
+ * {@link B3Propagator#injectingSingleHeader()}.
  *
  * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
  * at any time.

diff --git a/.../java/io/opentelemetry/extension/trace/propagation/internal/B3MultiComponentProvider.java b/.../java/io/opentelemetry/extension/trace/propagation/internal/B3MultiComponentProvider.java
@@ -11,8 +11,8 @@
 import io.opentelemetry.sdk.autoconfigure.spi.internal.StructuredConfigProperties;
 
 /**
- * File configuration SPI implementation for {@link B3Propagator} which allows enables the {@link
- * B3Propagator#injectingMultiHeaders()}.
+ * Declarative configuration SPI implementation for {@link B3Propagator} which allows enables the
+ * {@link B3Propagator#injectingMultiHeaders()}.
  *
  * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
  * at any time.

diff --git a/...n/java/io/opentelemetry/extension/trace/propagation/internal/JaegerComponentProvider.java b/...n/java/io/opentelemetry/extension/trace/propagation/internal/JaegerComponentProvider.java
@@ -11,7 +11,7 @@
 import io.opentelemetry.sdk.autoconfigure.spi.internal.StructuredConfigProperties;
 
 /**
- * File configuration SPI implementation for {@link JaegerPropagator}.
+ * Declarative configuration SPI implementation for {@link JaegerPropagator}.
  *
  * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
  * at any time.

diff --git a/.../java/io/opentelemetry/extension/trace/propagation/internal/OtTraceComponentProvider.java b/.../java/io/opentelemetry/extension/trace/propagation/internal/OtTraceComponentProvider.java
@@ -12,7 +12,7 @@
 import io.opentelemetry.sdk.autoconfigure.spi.internal.StructuredConfigProperties;
 
 /**
- * File configuration SPI implementation for {@link B3Propagator}.
+ * Declarative configuration SPI implementation for {@link B3Propagator}.
  *
  * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
  * at any time.

diff --git a/...-spi/src/main/java/io/opentelemetry/sdk/autoconfigure/spi/internal/ComponentProvider.java b/...-spi/src/main/java/io/opentelemetry/sdk/autoconfigure/spi/internal/ComponentProvider.java
@@ -16,7 +16,7 @@
 
 /**
  * Provides configured instances of SDK extension components. {@link ComponentProvider} allows SDK
- * extension components which are not part of the core SDK to be referenced in file based
+ * extension components which are not part of the core SDK to be referenced in declarative based
  * configuration.
  *
  * <p>NOTE: when {@link #getType()} is {@link Resource}, the {@link #getName()} is not (currently)

diff --git a/...gure/src/main/java/io/opentelemetry/sdk/autoconfigure/AutoConfiguredOpenTelemetrySdk.java b/...gure/src/main/java/io/opentelemetry/sdk/autoconfigure/AutoConfiguredOpenTelemetrySdk.java
@@ -67,8 +67,8 @@ static AutoConfiguredOpenTelemetrySdk create(
   abstract Resource getResource();
 
   /**
-   * Returns the {@link ConfigProperties} used for auto-configuration, or {@code null} if file
-   * configuration was used.
+   * Returns the {@link ConfigProperties} used for auto-configuration, or {@code null} if
+   * declarative configuration was used.
    *
    * @see #getStructuredConfig()
    */
@@ -77,7 +77,7 @@ static AutoConfiguredOpenTelemetrySdk create(
 
   /**
    * Returns the {@link StructuredConfigProperties} used for auto-configuration, or {@code null} if
-   * file configuration was not used.
+   * declarative configuration was not used.
    *
    * @see #getConfig()
    */

diff --git a/...c/main/java/io/opentelemetry/sdk/autoconfigure/AutoConfiguredOpenTelemetrySdkBuilder.java b/...c/main/java/io/opentelemetry/sdk/autoconfigure/AutoConfiguredOpenTelemetrySdkBuilder.java
@@ -563,7 +563,7 @@ private static AutoConfiguredOpenTelemetrySdk maybeConfigureFromFile(
           configurationFactory.getMethod("toConfigProperties", openTelemetryConfiguration);
       StructuredConfigProperties structuredConfigProperties =
           (StructuredConfigProperties) toConfigProperties.invoke(null, model);
-      // Note: can't access file configuration resource without reflection so setting a dummy
+      // Note: can't access declarative configuration resource without reflection so setting a dummy
       // resource
       return AutoConfiguredOpenTelemetrySdk.create(
           sdk, Resource.getDefault(), null, structuredConfigProperties);

diff --git a/sdk-extensions/incubator/README.md b/sdk-extensions/incubator/README.md
@@ -2,9 +2,9 @@
 
 This artifact contains experimental code related to the trace and metric SDKs.
 
-## File Configuration
+## Declarative Configuration
 
-Allows for YAML based file configuration of `OpenTelemetrySdk` as defined in the [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/data-model.md#file-based-configuration-model).
+The [declarative configuration interface](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/README.md#declarative-configuration) allows for YAML based file configuration of `OpenTelemetrySdk`.
 
 Usage:
 
@@ -19,8 +19,17 @@ try (FileInputStream yamlConfigFileInputStream = new FileInputStream("/path/to/c
 
 Notes:
 * Environment variable substitution is supported as [defined in the spec](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/data-model.md#environment-variable-substitution)
-* Currently, there is no support for the SPIs defined in [opentelemetry-sdk-extension-autoconfigure-spi](../autoconfigure-spi). Only built in samplers, processors, exporters, etc can be configured.
-* You can use file configuration with [autoconfigure](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure#file-configuration) to specify a configuration file via environment variable, e.g. `OTEL_EXPERIMENTAL_CONFIG_FILE=/path/to/config.yaml`.
+* Currently, there is no support for the customization (i.e. `AutoConfigurationCustomizerProvider`) SPIs defined in [opentelemetry-sdk-extension-autoconfigure-spi](../autoconfigure-spi).
+* Custom SDK extension components which reference the [ComponentProvider](https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/autoconfigure-spi/src/main/java/io/opentelemetry/sdk/autoconfigure/spi/internal/ComponentProvider.java) SPI can be referenced in declarative configuration. Supported types include:
+  * `Resource`
+  * `SpanExporter`
+  * `MetricExporter`
+  * `LogRecordExporter`
+  * `SpanProcessor`
+  * `LogRecordProcessor`
+  * `TextMapPropagator`
+  * `Sampler`
+* You can use declarative configuration with [autoconfigure](https://opentelemetry.io/docs/languages/java/configuration/#declarative-configuration) to specify a configuration file via environment variable, e.g. `OTEL_EXPERIMENTAL_CONFIG_FILE=/path/to/config.yaml`.
 
 ## View File Configuration
 

diff --git a/...or/src/main/java/io/opentelemetry/sdk/extension/incubator/fileconfig/ResourceFactory.java b/...or/src/main/java/io/opentelemetry/sdk/extension/incubator/fileconfig/ResourceFactory.java
@@ -88,7 +88,7 @@ public Resource create(
   /**
    * Load resources from resource detectors, in order of lowest priority to highest priority.
    *
-   * <p>In file configuration, a resource detector is a {@link ComponentProvider} with {@link
+   * <p>In declarative configuration, a resource detector is a {@link ComponentProvider} with {@link
    * ComponentProvider#getType()} set to {@link Resource}. Unlike other {@link ComponentProvider}s,
    * the resource detector version does not use {@link ComponentProvider#getName()} (except for
    * debug messages), and {@link ComponentProvider#create(StructuredConfigProperties)} is called

diff --git a/...a/io/opentelemetry/sdk/extension/incubator/fileconfig/YamlStructuredConfigProperties.java b/...a/io/opentelemetry/sdk/extension/incubator/fileconfig/YamlStructuredConfigProperties.java
@@ -24,12 +24,13 @@
 import javax.annotation.Nullable;
 
 /**
- * Implementation of {@link StructuredConfigProperties} which uses a file configuration model as a
- * source.
+ * Implementation of {@link StructuredConfigProperties} which uses a declarative configuration model
+ * as a source.
  *
  * @see #getStructured(String) Accessing nested maps
  * @see #getStructuredList(String) Accessing lists of maps
- * @see FileConfiguration#toConfigProperties(Object) Converting configuration model to properties
+ * @see FileConfiguration#toConfigProperties(Object, ComponentLoader) Converting configuration model
+ *     to properties
  */
 final class YamlStructuredConfigProperties implements StructuredConfigProperties {
 

diff --git a/.../opentelemetry/sdk/extension/incubator/fileconfig/YamlStructuredConfigPropertiesTest.java b/.../opentelemetry/sdk/extension/incubator/fileconfig/YamlStructuredConfigPropertiesTest.java
@@ -68,7 +68,7 @@ void setup() {
 
   @Test
   void configurationSchema() {
-    // Validate can read file configuration schema properties
+    // Validate can read declarative configuration schema properties
     assertThat(structuredConfigProps.getString("file_format")).isEqualTo("0.3");
     StructuredConfigProperties resourceProps = structuredConfigProps.getStructured("resource");
     assertThat(resourceProps).isNotNull();