Demosntrate declarative config 0.3 with otel java agent (#492)

javaagent/Dockerfile

@@ -2,5 +2,6 @@ FROM eclipse-temurin:11-jre
 
 ADD build/libs/app.jar /app.jar
 ADD build/agent/opentelemetry-javaagent.jar /opentelemetry-javaagent.jar
+ADD build/agent/opentelemetry-javaagent-extension.jar /opentelemetry-javaagent-extension.jar
 
-ENTRYPOINT java -jar -javaagent:/opentelemetry-javaagent.jar /app.jar
+ENTRYPOINT java -javaagent:/opentelemetry-javaagent.jar -Dotel.javaagent.extensions=/opentelemetry-javaagent-extension.jar -jar /app.jar

javaagent/README.md

@@ -47,12 +47,15 @@ Watch for spans, metrics, and logs in the collector log output
 
 ## File Configuration
 
-By default, this example uses the [environment variable configuration schema](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md) to configure the SDK. However, it also includes [sdk-config.yaml](./sdk-config.yaml) which demonstrates how the file configuration scheme can be used instead. `sdk-config.yaml` demonstrates view configuration to disable a metric, something which is not available in the environment variable configuration scheme.
+By default, this example uses the [environment variable configuration schema](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md) to configure the SDK. However, it also includes [sdk-config.yaml](./sdk-config.yaml) which demonstrates how the file configuration scheme can be used instead. `sdk-config.yaml` extends the [opentelemetry-configuration sdk-config.yaml](https://github.com/open-telemetry/opentelemetry-configuration/blob/v0.3.0/examples/sdk-config.yaml) template, demonstrating:
+
+- Configuration of instrumentation (see `.instrumentation.java`) 
+- Configuration of [rule based routing sampler](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/samplers) (see `.tracer_provider.sampler.parent_based.root`)
 
 To use file configuration instead of the environment variable scheme, add the following before starting the application and collector:
 
 ```shell
-export OTEL_CONFIG_FILE=/sdk-config.yaml
+export OTEL_EXPERIMENTAL_CONFIG_FILE=/sdk-config.yaml
 ```
 
-Note that toggling file configuration causes the environment variable configuration scheme to be ignored completely. However, there is support for environment variable substitution within configuration files.
+Note: toggling declarative configuration causes the env var configuration scheme to be ignored completely. However, there is support for [env var substitution](https://opentelemetry.io/docs/specs/otel/configuration/data-model/#environment-variable-substitution) within configuration files.

javaagent/build.gradle.kts

@@ -16,15 +16,20 @@ java {
 }
 
 val agent = configurations.create("agent")
+val extension = configurations.create("extension")
 
 dependencies {
     implementation(platform(SpringBootPlugin.BOM_COORDINATES))
     implementation("io.opentelemetry:opentelemetry-api")
 
     //spring modules
     implementation("org.springframework.boot:spring-boot-starter-web")
+    implementation("org.springframework.boot:spring-boot-starter-actuator")
 
     agent("io.opentelemetry.javaagent:opentelemetry-javaagent:2.9.0")
+    extension("io.opentelemetry.contrib:opentelemetry-samplers:1.40.0-alpha") {
+        isTransitive = false
+    }
 }
 
 val copyAgent = tasks.register<Copy>("copyAgent") {
@@ -33,9 +38,15 @@ val copyAgent = tasks.register<Copy>("copyAgent") {
     rename("opentelemetry-javaagent-.*\\.jar", "opentelemetry-javaagent.jar")
 }
 
+val copyExtension = tasks.register<Copy>("copyExtension") {
+    from(extension.singleFile)
+    into(layout.buildDirectory.dir("agent"))
+    rename(".*\\.jar", "opentelemetry-javaagent-extension.jar")
+}
 
 tasks.named<BootJar>("bootJar") {
     dependsOn(copyAgent)
+    dependsOn(copyExtension)
 
     archiveFileName = "app.jar"
 }

javaagent/docker-compose.yml

@@ -4,12 +4,14 @@ services:
     build: ./
     environment:
       OTEL_SERVICE_NAME: "agent-example-app"
-      OTEL_EXPORTER_OTLP_ENDPOINT: "http://collector:4318"
+      OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: "http://collector:4318/v1/traces"
+      OTEL_EXPORTER_OTLP_METRICS_ENDPOINT: "http://collector:4318/v1/metrics"
+      OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: "http://collector:4318/v1/logs"
       # Logs are disabled by default
       OTEL_LOGS_EXPORTER: "otlp"
       # Optional specify file configuration instead of using environment variable scheme
-      # To use, call "export OTEL_CONFIG_FILE=/sdk-config.yaml" before calling docker compose up
-      OTEL_CONFIG_FILE:
+      # To use, call "export OTEL_EXPERIMENTAL_CONFIG_FILE=/sdk-config.yaml" before calling docker compose up
+      OTEL_EXPERIMENTAL_CONFIG_FILE:
     ports:
       - "8080:8080"
     volumes:

javaagent/sdk-config.yaml

@@ -1,38 +1,247 @@
+# Copy of https://github.com/open-telemetry/opentelemetry-configuration/blob/v0.3.0/examples/sdk-config.yaml
+# with the following changes:
+# - OpenTelemetry Java Agent properties added at .instrumentation.java.
+# - OTLP exporter endpoints modified to point to http://collector:4318/v1/{path} to export to collector from docker-compose.yml
+# - .tracer_provider.sampler.parent_based.root set to rule_based_routing sampler to demonstrate turning off sampling for spring boot actuator endpoints.
+
+#
+# sdk-config.yaml is a typical starting point for configuring the SDK, including exporting to
+# localhost via OTLP.
+
+# NOTE: With the exception of env var substitution syntax (i.e. ${MY_ENV}), SDKs ignore
+# environment variables when interpreting config files. This including ignoring all env
+# vars defined in https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/.
+
+# The file format version.
+# TODO: the current support file format is 0.3, but the opentelemetry-java errantly checks that it is 0.1. This will be fixed in 1.44.0.
 file_format: "0.1"
 
+# Configure if the SDK is disabled or not. This is not required to be provided to ensure the SDK isn't disabled, the default value when this is not provided is for the SDK to be enabled.
+disabled: false
+
+# Configure resource for all signals.
 resource:
+  # Configure resource attributes. Entries have higher priority than entries from .resource.attributes_list.
+  # Entries must contain .name nand .value, and may optionally include .type, which defaults ot "string" if not set. The value must match the type. Values for .type include: string, bool, int, double, string_array, bool_array, int_array, double_array.
   attributes:
-    service.name: agent-example-app
+    - name: service.name
+      value: unknown_service
 
-logger_provider:
-  processors:
-    - batch:
-        exporter:
-          otlp:
-            endpoint: http://collector:4318
-            protocol: http/protobuf
+# Configure general attribute limits. See also tracer_provider.limits, logger_provider.limits.
+attribute_limits:
+  # Configure max attribute value size.
+  attribute_value_length_limit:
+  # Configure max attribute count.
+  attribute_count_limit: 128
 
+# Configure text map context propagators.
+propagator:
+  # Configure the set of propagators to include in the composite text map propagator.
+  composite: [ tracecontext, baggage ]
+
+# Configure tracer provider.
 tracer_provider:
+  # Configure span processors.
   processors:
-    - batch:
+    - # Configure a batch span processor.
+      batch:
+        # Configure delay interval (in milliseconds) between two consecutive exports.
+        schedule_delay: 5000
+        # Configure maximum allowed time (in milliseconds) to export data.
+        export_timeout: 30000
+        # Configure maximum queue size.
+        max_queue_size: 2048
+        # Configure maximum batch size.
+        max_export_batch_size: 512
+        # Configure exporter.
         exporter:
+          # Configure exporter to be OTLP.
           otlp:
-            endpoint: http://collector:4318
+            # Configure protocol.
             protocol: http/protobuf
+            # Configure endpoint.
+            endpoint: http://collector:4318/v1/traces
+            # Configure certificate.
+            certificate:
+            # Configure mTLS private client key.
+            client_key:
+            # Configure mTLS client certificate.
+            client_certificate:
+            # Configure compression.
+            compression: gzip
+            # Configure max time (in milliseconds) to wait for each export.
+            timeout: 10000
+            # Configure headers. Entries have higher priority than entries from .headers_list.
+            headers: []
+  # Configure span limits. See also attribute_limits.
+  limits:
+    # Configure max attribute value size. Overrides .attribute_limits.attribute_value_length_limit.
+    attribute_value_length_limit: # Configure max span attribute count. Overrides attribute_limits.attribute_count_limit.
+    # Configure max attribute count. Overrides .attribute_limits.attribute_count_limit.
+    attribute_count_limit: 128
+    # Configure max span event count.
+    event_count_limit: 128
+    # Configure max span link count.
+    link_count_limit: 128
+    # Configure max attributes per span event.
+    event_attribute_count_limit: 128
+    # Configure max attributes per span link.
+    link_attribute_count_limit: 128
+  # Configure the sampler.
+  sampler:
+    # Configure sampler to be parent_based.
+    parent_based:
+      # Configure the parent_based sampler's root sampler to be rule_based_routing sampler from https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/samplers.
+      root:
+        rule_based_routing:
+          # Fallback to the always_on sampler if the criteria is not met.
+          fallback_sampler:
+            always_on:
+          # Only apply to SERVER spans.
+          span_kind: SERVER
+          rules:
+            # Drop spans where url.path matches the regex /actuator.* (i.e. spring boot actuator endpoints).
+            - action: DROP
+              attribute: url.path
+              pattern: /actuator.*
+      # Configure remote_parent_sampled sampler.
+      remote_parent_sampled:
+        # Configure sampler to be always_on.
+        always_on: {}
+      # Configure remote_parent_not_sampled sampler.
+      remote_parent_not_sampled:
+        # Configure sampler to be always_off.
+        always_off: {}
+      # Configure local_parent_sampled sampler.
+      local_parent_sampled:
+        # Configure sampler to be always_on.
+        always_on: {}
+      # Configure local_parent_not_sampled sampler.
+      local_parent_not_sampled:
+        # Configure sampler to be always_off.
+        always_off: {}
 
+# Configure meter provider.
 meter_provider:
+  # Configure metric readers.
   readers:
-    - periodic:
+    - # Configure a periodic metric reader.
+      periodic:
+        # Configure delay interval (in milliseconds) between start of two consecutive exports.
+        interval: 60000
+        # Configure maximum allowed time (in milliseconds) to export data.
+        timeout: 30000
+        # Configure exporter.
         exporter:
+          # Configure exporter to be OTLP.
           otlp:
-            endpoint: http://collector:4318
+            # Configure protocol.
             protocol: http/protobuf
-  # Example of how to use view to drop a metric which isn't needed.
-  # This configuration is not available with the environment variable configuration scheme.
-  # NOTE: most users will want jvm.memory.limit metric and should remove this view.
-  views:
-    - selector:
-        instrument_name: jvm.memory.limit
-      stream:
-        aggregation:
-          drop:
+            # Configure endpoint.
+            endpoint: http://collector:4318/v1/metrics
+            # Configure certificate.
+            certificate:
+            # Configure mTLS private client key.
+            client_key:
+            # Configure mTLS client certificate.
+            client_certificate:
+            # Configure compression.
+            compression: gzip
+            # Configure max time (in milliseconds) to wait for each export.
+            timeout: 10000
+            # Configure headers. Entries have higher priority than entries from .headers_list.
+            headers: []
+            # Configure temporality preference.
+            temporality_preference: cumulative
+            # Configure default histogram aggregation.
+            default_histogram_aggregation: explicit_bucket_histogram
+
+# Configure logger provider.
+logger_provider:
+  # Configure log record processors.
+  processors:
+    - # Configure a batch log record processor.
+      batch:
+        # Configure delay interval (in milliseconds) between two consecutive exports.
+        schedule_delay: 1000
+        # Configure maximum allowed time (in milliseconds) to export data.
+        export_timeout: 30000
+        # Configure maximum queue size.
+        max_queue_size: 2048
+        # Configure maximum batch size.
+        max_export_batch_size: 512
+        # Configure exporter.
+        exporter:
+          # Configure exporter to be OTLP.
+          otlp:
+            # Configure protocol.
+            protocol: http/protobuf
+            # Configure endpoint.
+            endpoint: http://collector:4318/v1/logs
+            # Configure certificate.
+            certificate:
+            # Configure mTLS private client key.
+            client_key:
+            # Configure mTLS client certificate.
+            client_certificate:
+            # Configure compression.
+            compression: gzip
+            # Configure max time (in milliseconds) to wait for each export.
+            timeout: 10000
+            # Configure headers. Entries have higher priority than entries from .headers_list.
+            headers: []
+  # Configure log record limits. See also attribute_limits.
+  limits:
+    # Configure max attribute value size. Overrides .attribute_limits.attribute_value_length_limit.
+    attribute_value_length_limit: # Configure max log record attribute count. Overrides attribute_limits.attribute_count_limit.
+    # Configure max attribute count. Overrides .attribute_limits.attribute_count_limit.
+    attribute_count_limit: 128
+
+
+# Configure instrumentation.
+instrumentation:
+  # Configure OpenTelemetry Java Agent. A standard translation process is applied to convert the
+  # flat system properties / env var configuration scheme from https://opentelemetry.io/docs/zero-code/java/agent/
+  # to the structured scheme used by declarative configuration:
+  #
+  # - Resolve properties starting with "otel.instrumentation."
+  # - Strip the "otel.instrumentation." prefix.
+  # - Split the remaining property string on "." character to break into segments
+  # - Starting at .instrumentation.java, follow N-1 segments to resolve the leaf node to read the property from
+  # - Read segment N from the resolved leaf node
+  #
+  # For example, the property "otel.instrumentation.common.default-enabled" is resolved by
+  # reading: .instrumentation.java.common.default-enabled
+  #
+  # Some system properties / env vars cannot be configured via declarative configuration, normally
+  # because they are resolved in the application lifecycle before declarative configuration is
+  # available. The set of unsupported properties includes:
+  # - otel.javaagent.enabled
+  # - otel.javaagent.configuration-file
+  # - otel.javaagent.extensions
+  # - otel.javaagent.logging
+  # - otel.resource.providers.[provider].enabled
+  #
+  # A sample set of OpenTelemetry Java Agent are shown below, with env var substitution references
+  # reflecting agent defaults. For properties that are not referenced, consult the translation
+  # steps discussed above.
+  java:
+    common:
+      default-enabled: true
+    # Configuration logback-appender instrumentation. Properties adapted from:
+    # https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/java-util-logging/javaagent
+    java-util-logging:
+      enabled: true
+      experimental-log-attributes: false
+    # Configuration logback-appender instrumentation. Properties adapted from:
+    # https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/logback/logback-appender-1.0/javaagent
+    logback-appender:
+      enabled: true
+      experimental-log-attributes: false
+      experimental:
+        capture-code-attributes: false
+        capture-marker-attributes: false
+        capture-key-value-pair-attributes: false
+        capture-logger-context-attributes: false
+        capture-arguments: false
+        capture-mdc-attributes: false