add Spring declarative config example

.github/renovate.json5

@@ -40,6 +40,15 @@
       "matchUpdateTypes": ["major"],
       "enabled": false
     },
+    {
+      // Spring starter doesn't support Spring Boot 4 yet
+      "matchPackageNames": ["org.springframework.boot"],
+      "matchFilePatterns": [
+        "spring-declarative-configuration/build.gradle.kts"
+      ],
+      "matchUpdateTypes": ["major"],
+      "enabled": false
+    },
     {
       // Skip locally built dice image used in logging-k8s-stdout-otlp-json
       "matchManagers": ["kubernetes"],

.github/workflows/oats-tests.yml

@@ -10,6 +10,7 @@ on:
       - .mise/tasks/oats-tests.sh
       - 'logging-k8s-stdout-otlp-json/**'
       - 'javaagent-declarative-configuration/**'
+      - 'spring-declarative-configuration/**'
       - 'doc-snippets/extensions-minimal/**'
   workflow_dispatch:
 

.mise/tasks/oats-tests.sh

@@ -11,5 +11,10 @@ pushd javaagent-declarative-configuration
 ../gradlew clean bootJar
 popd
 
+pushd spring-declarative-configuration
+../gradlew clean bootJar
+popd
+
 oats -timeout 5m logging-k8s-stdout-otlp-json/
 oats -timeout 5m javaagent-declarative-configuration/oats/
+oats -timeout 5m spring-declarative-configuration/oats/

README.md

@@ -86,6 +86,16 @@ To build the all of examples, run:
       OpenTelemetry SDK to use a Zipkin exporter and send spans to a
       Zipkin backend using the OpenTelemetry API.
     - Note: This example requires Docker to be installed.
+- [Declarative Configuration with the OpenTelemetry Java Agent](javaagent-declarative-configuration)
+    - This module demonstrates how to use declarative configuration with the
+      OpenTelemetry Java Agent to configure tracing behavior, including
+      excluding specific endpoints from tracing.
+    - Note: This example requires Java 17 or higher.
+- [Declarative Configuration with the OpenTelemetry Spring Boot Starter](spring-declarative-configuration)
+    - This module demonstrates how to use declarative configuration with the
+      OpenTelemetry Spring Boot Starter to configure tracing behavior,
+      including excluding specific endpoints from tracing.
+    - Note: This example requires Java 17 or higher.
 
 ## Contributing
 

settings.gradle.kts

@@ -71,6 +71,7 @@ include(
     ":opentelemetry-examples-telemetry-testing",
     ":opentelemetry-examples-zipkin",
     ":opentelemetry-examples-spring-native",
+    ":opentelemetry-examples-spring-declarative-configuration",
     ":opentelemetry-examples-kotlin-extension",
     ":opentelemetry-examples-grpc",
     ":opentelemetry-examples-resource-detection-gcp",

spring-declarative-configuration/README.md

@@ -0,0 +1 @@
+TODO

spring-declarative-configuration/build.gradle.kts

@@ -0,0 +1,29 @@
+import org.gradle.kotlin.dsl.named
+import org.springframework.boot.gradle.plugin.SpringBootPlugin
+import org.springframework.boot.gradle.tasks.bundling.BootJar
+
+plugins {
+    id("java")
+    id("org.springframework.boot") version "3.5.7"
+}
+
+description = "OpenTelemetry Example for Spring Boot with Declarative Configuration"
+
+java {
+    toolchain {
+        languageVersion.set(JavaLanguageVersion.of(17))
+    }
+}
+
+dependencies {
+    implementation(platform(SpringBootPlugin.BOM_COORDINATES))
+    implementation(platform("io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom:2.22.0"))
+    implementation("org.springframework.boot:spring-boot-starter-actuator")
+    implementation("org.springframework.boot:spring-boot-starter-web")
+    implementation("io.opentelemetry.instrumentation:opentelemetry-spring-boot-starter")
+}
+
+tasks.named<BootJar>("bootJar") {
+    archiveFileName = "spring-declarative-configuration.jar"
+}
+

spring-declarative-configuration/oats/Dockerfile

@@ -0,0 +1,8 @@
+FROM eclipse-temurin:21.0.9_10-jre@sha256:4332b7939ba5b7fabde48f4da21ebe45a4f8943d5b3319720c321ac577e65fb1
+
+WORKDIR /usr/src/app/
+
+ADD ./build/libs/spring-declarative-configuration.jar ./app.jar
+
+EXPOSE 8080
+ENTRYPOINT [ "java", "-jar", "./app.jar" ]

spring-declarative-configuration/oats/docker-compose.yml

@@ -0,0 +1,17 @@
+version: '3'
+services:
+  app:
+    build:
+      context: ../
+      dockerfile: oats/Dockerfile
+    environment:
+      OTEL_TRACER_PROVIDER_PROCESSORS_0_BATCH_EXPORTER_OTLP_HTTP_ENDPOINT: http://lgtm:4318/v1/traces
+      OTEL_METER_PROVIDER_READERS_0_PERIODIC_EXPORTER_OTLP_HTTP_ENDPOINT: http://lgtm:4318/v1/metrics
+      OTEL_LOGGER_PROVIDER_PROCESSORS_0_BATCH_EXPORTER_OTLP_HTTP_ENDPOINT: http://lgtm:4318/v1/logs
+    ports:
+      - "8080:8080"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/actuator/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 3

spring-declarative-configuration/oats/oats.yaml

@@ -0,0 +1,26 @@
+# OATS is an acceptance testing framework for OpenTelemetry - https://github.com/grafana/oats
+
+docker-compose:
+  files:
+    - ./docker-compose.yml
+  app-service: app
+  app-docker-tag: javaagent-declarative-config:latest
+  app-docker-port: 8080
+
+input:
+  # This endpoint should be traced normally
+  - path: /api/example
+  # This endpoint should NOT be traced (excluded by declarative config)
+  # We send the request but don't assert spans for it - the absence of spans
+  # for /actuator/health demonstrates the sampling rule is working
+  - path: /actuator/health
+
+expected:
+  traces:
+    # Verify that /api/example creates a trace with SERVER span
+    - traceql: '{ span.http.route = "/api/example" }'
+      spans:
+        - name: "GET /api/example"
+          attributes:
+            http.request.method: "GET"
+            http.route: "/api/example"

spring-declarative-configuration/src/main/java/io/opentelemetry/examples/fileconfig/ApiController.java

@@ -0,0 +1,21 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.examples.fileconfig;
+
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping("/api")
+public class ApiController {
+
+  @GetMapping("/example")
+  public ResponseEntity<String> example() {
+    return ResponseEntity.ok("Hello from OpenTelemetry example API!");
+  }
+}

spring-declarative-configuration/src/main/java/io/opentelemetry/examples/fileconfig/Application.java

@@ -0,0 +1,17 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.examples.fileconfig;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+@SpringBootApplication
+public class Application {
+
+  public static void main(String[] args) {
+    SpringApplication.run(Application.class, args);
+  }
+}

spring-declarative-configuration/src/main/resources/application.yaml

@@ -0,0 +1,59 @@
+otel:
+  # IMPORTANT:
+  # 1. The auto-suggested properties are not correct, because they are based on the non-declarative config schema.
+  # 2. Use https://github.com/open-telemetry/opentelemetry-configuration for details on schema and examples, but
+  #    indent all examples by two spaces to fit under the "otel:" root node (for Spring Boot declarative config).
+
+  file_format: "1.0-rc.2"
+
+  resource:
+    attributes:
+      - name: service.name
+        value: spring-boot-declarative-config-example
+
+  propagator:
+    composite:
+      - tracecontext:
+      - baggage:
+
+  tracer_provider:
+    processors:
+      - batch:
+          exporter:
+            otlp_http:
+              endpoint: http://localhost:4318/v1/traces
+
+      # Configure a console exporter for exploring without a collector/backend
+      - batch:
+          exporter:
+            console:
+
+    # Configure sampling to exclude health check endpoints
+    sampler:
+      rule_based_routing:
+        fallback_sampler:
+          always_on:
+        # Filter to spans of this span_kind. Must be one of: SERVER, CLIENT, INTERNAL, CONSUMER, PRODUCER.
+        span_kind: SERVER   # only apply to server spans
+        # List of rules describing spans to drop. Spans are dropped if they match one of the rules.
+        rules:
+          # The action to take when the rule is matches. Must be of: DROP, RECORD_AND_SAMPLE.
+          - action: DROP
+            # The span attribute to match against.
+            attribute: url.path
+            # The pattern to compare the span attribute to.
+            pattern: /actuator.*
+
+  meter_provider:
+    readers:
+      - periodic:
+          exporter:
+            otlp_http:
+              endpoint: http://localhost:4318/v1/metrics
+
+  logger_provider:
+    processors:
+      - batch:
+          exporter:
+            otlp_http:
+              endpoint: http://localhost:4318/v1/logs