Add declarative configuration docs for Spring Boot starter (#9448)

zeitlinger · web-flow · commit 2d89b60b2e09 · 2026-04-23T08:45:42.000-04:00
diff --git a/content/en/blog/2024/spring-starter-stable/index.md b/content/en/blog/2024/spring-starter-stable/index.md
@@ -43,7 +43,7 @@ Here are some scenarios where you might want to use the Spring Starter:
   doesn't work with the OpenTelemetry Java agent
 - **Programmatic configuration** of the OpenTelemetry Spring Boot starter, such
   as
-  [dynamic auth headers](/docs/zero-code/java/spring-boot-starter/sdk-configuration/#configure-the-exporter-programmatically),
+  [dynamic auth headers](/docs/zero-code/java/spring-boot-starter/programmatic-configuration/#configure-the-exporter-programmatically),
   using Spring beans (the OpenTelemetry Java agent requires an
   [extension](/docs/zero-code/java/agent/extensions/) for this)
 - **Uses code dependencies**: You don't need to add any JVM options (e.g. in
diff --git a/content/en/docs/zero-code/java/_index.md b/content/en/docs/zero-code/java/_index.md
@@ -8,6 +8,7 @@ cascade:
   vers:
     instrumentation: 2.27.0
     otel: 1.61.0
+    contrib: 1.54.0
 ---
 
 Common options for zero-code instrumentation with Java are the Java agent JAR,
diff --git a/content/en/docs/zero-code/java/agent/declarative-configuration.md b/content/en/docs/zero-code/java/agent/declarative-configuration.md
@@ -76,6 +76,8 @@ getting started guide for declarative configuration.
 
 This page focuses on specifics for the
 [OpenTelemetry Java agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation).
+For the Spring Boot starter, see
+[Spring Boot starter declarative configuration](/docs/zero-code/java/spring-boot-starter/declarative-configuration/).
 
 ## Mapping of configuration options
 
@@ -222,14 +224,6 @@ Contrib features that are not yet supported by declarative configuration:
 - [GCP authentication](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/gcp-auth-extension)
 - [Inferred Spans](https://github.com/open-telemetry/opentelemetry-java-contrib/blob/main/inferred-spans)
 
-### Spring Boot starter limitations
-
-Lastly, the [Spring Boot starter](/docs/zero-code/java/spring-boot-starter) does
-not yet support declarative configuration:
-
-- however, you can already use `application.yaml` to configure the OpenTelemetry
-  Spring Boot starter
-
 ## Extension API
 
 Extensions use a new declarative configuration API.
diff --git a/content/en/docs/zero-code/java/spring-boot-starter/_index.md b/content/en/docs/zero-code/java/spring-boot-starter/_index.md
@@ -24,3 +24,5 @@ OpenTelemetry.
    - **Spring Boot configuration files** (`application.properties`,
      `application.yml`) to configure the OpenTelemetry Spring Boot starter which
      doesn't work with the OpenTelemetry Java agent
+   - **[Declarative configuration](declarative-configuration/)** using a
+     structured YAML format inside `application.yaml`
diff --git a/content/en/docs/zero-code/java/spring-boot-starter/additional-instrumentations.md b/content/en/docs/zero-code/java/spring-boot-starter/additional-instrumentations.md
@@ -29,9 +29,33 @@ You can find more configuration options for the OpenTelemetry appender in the
 [Log4j](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/log4j/log4j-appender-2.17/library/README.md)
 instrumentation library.
 
-| System property                               | Type    | Default | Description                                                                                     |
-| --------------------------------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------- |
-| `otel.instrumentation.log4j-appender.enabled` | Boolean | true    | Enables the configuration of the Log4j OpenTelemetry appender with an `OpenTelemetry` instance. |
+{{< tabpane text=true >}} {{% tab "Properties" %}}
+
+Enables the configuration of the Log4j OpenTelemetry appender with an
+`OpenTelemetry` instance:
+
+```yaml
+otel:
+  instrumentation:
+    log4j-appender:
+      enabled: true # default: true
+```
+
+{{% /tab %}} {{% tab "Declarative Configuration" %}}
+
+In [declarative configuration](../declarative-configuration/), use the
+centralized instrumentation lists to enable or disable Log4j:
+
+```yaml
+otel:
+  distribution:
+    spring_starter:
+      instrumentation:
+        disabled:
+          - log4j_appender
+```
+
+{{% /tab %}} {{< /tabpane >}}
 
 ## Instrumentation libraries
 
diff --git a/content/en/docs/zero-code/java/spring-boot-starter/annotations.md b/content/en/docs/zero-code/java/spring-boot-starter/annotations.md
@@ -116,6 +116,18 @@ dependencies {
 You can disable the OpenTelemetry annotations by setting the
 `otel.instrumentation.annotations.enabled` property to `false`.
 
+In [declarative configuration](../declarative-configuration/), use the
+centralized instrumentation lists instead:
+
+```yaml
+otel:
+  distribution:
+    spring_starter:
+      instrumentation:
+        disabled:
+          - annotations
+```
+
 You can customize the span by using the elements of the `WithSpan` annotation:
 
 | Name    | Type       | Description           | Default Value       |
diff --git a/content/en/docs/zero-code/java/spring-boot-starter/declarative-configuration.md b/content/en/docs/zero-code/java/spring-boot-starter/declarative-configuration.md
@@ -0,0 +1,200 @@
+---
+title: Declarative configuration
+weight: 25
+cSpell:ignore: Customizer Dotel
+---
+
+Declarative configuration uses the
+[OpenTelemetry declarative configuration schema](/docs/languages/sdk-configuration/declarative-configuration/)
+inside your `application.yaml`.
+
+This approach is useful when:
+
+- You have many configuration options to set
+- You want to use configuration options that are not available with
+  `application.properties` or `application.yaml`
+- You want to use the same configuration format as the
+  [Java agent](/docs/zero-code/java/agent/declarative-configuration/)
+
+> [!WARNING]
+>
+> Declarative configuration is experimental.
+
+## Supported versions
+
+Declarative configuration is supported in the **OpenTelemetry Spring Boot
+starter version 2.26.0 and later**.
+
+## Getting started
+
+Add `otel.file_format: "1.0"` (or the current or desired version) to your
+`application.yaml` to opt in to declarative configuration:
+
+```yaml
+otel:
+  file_format: '1.0'
+
+  resource:
+    detection/development:
+      detectors:
+        - service:
+    attributes:
+      - name: service.name
+        value: my-spring-app
+
+  propagator:
+    composite:
+      - tracecontext:
+      - baggage:
+
+  tracer_provider:
+    processors:
+      - batch:
+          exporter:
+            otlp_http:
+              endpoint: ${OTEL_EXPORTER_OTLP_TRACES_ENDPOINT:http://localhost:4318/v1/traces}
+
+  meter_provider:
+    readers:
+      - periodic:
+          exporter:
+            otlp_http:
+              endpoint: ${OTEL_EXPORTER_OTLP_METRICS_ENDPOINT:http://localhost:4318/v1/metrics}
+
+  logger_provider:
+    processors:
+      - batch:
+          exporter:
+            otlp_http:
+              endpoint: ${OTEL_EXPORTER_OTLP_LOGS_ENDPOINT:http://localhost:4318/v1/logs}
+```
+
+Note that `${VAR:default}` uses a single colon (Spring syntax), not the
+`${VAR:-default}` syntax used in the agent's standalone YAML file.
+
+## Mapping of configuration options
+
+The following rules describe how `application.properties` / `application.yaml`
+configuration options map to their declarative configuration equivalents:
+
+### Instrumentation enable/disable
+
+In declarative configuration, instrumentation enable/disable uses centralized
+lists instead of individual properties. The instrumentation name uses `_`
+(snake_case), not `-` (kebab-case).
+
+| Properties                                            | Declarative Configuration                                                       |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `otel.instrumentation.jdbc.enabled=true`              | `otel.distribution.spring_starter.instrumentation.enabled: [jdbc]`              |
+| `otel.instrumentation.logback-appender.enabled=false` | `otel.distribution.spring_starter.instrumentation.disabled: [logback_appender]` |
+| `otel.instrumentation.common.default-enabled=false`   | `otel.distribution.spring_starter.instrumentation.default_enabled: false`       |
+
+Example:
+
+```yaml
+otel:
+  distribution:
+    spring_starter:
+      instrumentation:
+        default_enabled: false
+        enabled:
+          - jdbc
+          - spring_web
+        disabled:
+          - logback_appender
+```
+
+### Instrumentation configuration
+
+Configuration options under `otel.instrumentation.*` (other than enable/disable)
+map to `otel.instrumentation/development.java.*`:
+
+1. Strip the `otel.instrumentation.` prefix
+2. Per segment: replace `-` with `_`
+3. Place under `otel.instrumentation/development.java.`
+4. A `/development` suffix on a key indicates an experimental feature (see the
+   `translateName` method in `ConfigPropertiesBackedDeclarativeConfigProperties`
+   for the reverse mapping)
+
+For example:
+
+| Properties                                                          | Declarative Configuration                                                                        |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `otel.instrumentation.logback-appender.experimental-log-attributes` | `otel.instrumentation/development.java.logback_appender.experimental_log_attributes/development` |
+
+Some options have special mappings that don't follow the default algorithm:
+
+| Properties                                                              | Declarative Configuration                                                                          |
+| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `otel.instrumentation.common.db-statement-sanitizer.enabled`            | `otel.instrumentation/development.java.common.database.statement_sanitizer.enabled`                |
+| `otel.instrumentation.http.client.capture-request-headers`              | `otel.instrumentation/development.general.http.client.request_captured_headers`                    |
+| `otel.instrumentation.http.client.capture-response-headers`             | `otel.instrumentation/development.general.http.client.response_captured_headers`                   |
+| `otel.instrumentation.http.server.capture-request-headers`              | `otel.instrumentation/development.general.http.server.request_captured_headers`                    |
+| `otel.instrumentation.http.server.capture-response-headers`             | `otel.instrumentation/development.general.http.server.response_captured_headers`                   |
+| `otel.instrumentation.http.client.emit-experimental-telemetry`          | `otel.instrumentation/development.java.common.http.client.emit_experimental_telemetry/development` |
+| `otel.instrumentation.http.server.emit-experimental-telemetry`          | `otel.instrumentation/development.java.common.http.server.emit_experimental_telemetry/development` |
+| `otel.instrumentation.http.known-methods`                               | `otel.instrumentation/development.java.common.http.known_methods`                                  |
+| `otel.instrumentation.messaging.experimental.receive-telemetry.enabled` | `otel.instrumentation/development.java.common.messaging.receive_telemetry/development.enabled`     |
+| `otel.jmx.enabled`                                                      | `otel.instrumentation/development.java.jmx.enabled`                                                |
+
+The `instrumentation/development` section has two top-level groups:
+
+- `general.*` — Cross-language configuration (HTTP headers, semantic convention
+  stability)
+- `java.*` — Java-specific instrumentation configuration
+
+### Disable the SDK
+
+| Properties               | Declarative Configuration |
+| ------------------------ | ------------------------- |
+| `otel.sdk.disabled=true` | `otel.disabled: true`     |
+
+### SDK configuration
+
+SDK-level configuration (exporters, propagators, resources) follows the standard
+[declarative configuration schema](/docs/languages/sdk-configuration/declarative-configuration/)
+directly under `otel:`, as shown in the [Getting started](#getting-started)
+example.
+
+## Differences from agent declarative configuration
+
+| Aspect          | Agent                                                    | Spring Boot starter                                           |
+| --------------- | -------------------------------------------------------- | ------------------------------------------------------------- |
+| Config location | Separate file (`-Dotel.config.file=...`)                 | Inside `application.yaml`                                     |
+| Variable syntax | `${VAR:-default}` (double-colon)                         | `${VAR:default}` (single colon, Spring)                       |
+| Profiles        | Not supported                                            | Spring profiles work normally                                 |
+| Enable/disable  | `distribution.javaagent.instrumentation.*`               | `distribution.spring_starter.instrumentation.*`               |
+| Default-enabled | `distribution.javaagent.instrumentation.default_enabled` | `distribution.spring_starter.instrumentation.default_enabled` |
+
+## Environment variable overrides
+
+Spring's relaxed binding lets you override any part of the declarative
+configuration YAML via environment variables:
+
+```shell
+# Override a scalar under instrumentation/development
+OTEL_INSTRUMENTATION/DEVELOPMENT_JAVA_FOO_STRING_KEY=new_value
+
+# Override an indexed list element (e.g. exporter endpoint)
+OTEL_TRACER_PROVIDER_PROCESSORS_0_BATCH_EXPORTER_OTLP_HTTP_ENDPOINT=http://custom:4318/v1/traces
+```
+
+Rules: uppercase, replace `.` with `_`, keep `/` as-is (e.g.
+`INSTRUMENTATION/DEVELOPMENT`), use `_0_`, `_1_` for list indices.
+
+This is a standard Spring feature — it works for any key in `application.yaml`.
+
+## Duration format
+
+Declarative configuration **only supports durations in milliseconds** (e.g.
+`5000` for 5 seconds). You will get an error if you use a duration string like
+`5s`.
+
+## Programmatic configuration
+
+With declarative configuration, `AutoConfigurationCustomizerProvider` (see
+[Programmatic configuration](../programmatic-configuration/)) is replaced by
+`DeclarativeConfigurationCustomizerProvider`. Components such as span exporters
+use the `ComponentProvider` API. See the
+[agent Extension API section](/docs/zero-code/java/agent/declarative-configuration/)
+for details and examples — the same APIs apply to the Spring Boot starter.
diff --git a/content/en/docs/zero-code/java/spring-boot-starter/other-spring-autoconfig.md b/content/en/docs/zero-code/java/spring-boot-starter/other-spring-autoconfig.md
@@ -50,6 +50,32 @@ dependencies {
 
 ### Configurations
 
-| Property                       | Default Value | ConditionalOnClass   |
-| ------------------------------ | ------------- | -------------------- |
-| `otel.exporter.zipkin.enabled` | true          | `ZipkinSpanExporter` |
+{{< tabpane text=true >}} {{% tab "Properties" %}}
+
+Enables the Zipkin exporter (requires `ZipkinSpanExporter` on the classpath):
+
+```yaml
+otel:
+  exporter:
+    zipkin:
+      enabled: true # default: true
+```
+
+{{% /tab %}} {{% tab "Declarative Configuration" %}}
+
+With [declarative configuration](../declarative-configuration/), the Zipkin
+exporter is configured as part of the standard
+[declarative configuration schema](/docs/languages/sdk-configuration/declarative-configuration/)
+under `tracer_provider.processors`:
+
+```yaml
+otel:
+  tracer_provider:
+    processors:
+      - batch:
+          exporter:
+            zipkin:
+              endpoint: http://localhost:9411/api/v2/spans
+```
+
+{{% /tab %}} {{< /tabpane >}}
diff --git a/content/en/docs/zero-code/java/spring-boot-starter/out-of-the-box-instrumentation.md b/content/en/docs/zero-code/java/spring-boot-starter/out-of-the-box-instrumentation.md
diff --git a/content/en/docs/zero-code/java/spring-boot-starter/programmatic-configuration.md b/content/en/docs/zero-code/java/spring-boot-starter/programmatic-configuration.md
diff --git a/content/en/docs/zero-code/java/spring-boot-starter/sdk-configuration.md b/content/en/docs/zero-code/java/spring-boot-starter/sdk-configuration.md
