# Declarative configuration

LLMS index: [llms.txt](/llms.txt)

---

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.

## Convert your existing configuration

<div class="dc-converter card p-3 my-4" data-source="spring" data-getting-started="# otel-getting-started.yaml is a good 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/.
#
# For schema documentation, including required properties, semantics, default behavior, etc,
# see: https://github.com/open-telemetry/opentelemetry-configuration/blob/main/schema-docs.md

file_format: &amp;#34;1.0&amp;#34;

resource:
  # Read resource attributes from the OTEL_RESOURCE_ATTRIBUTES environment variable.
  # This aligns well with the OpenTelemetry Operator and other deployment methods.
  attributes_list: ${OTEL_RESOURCE_ATTRIBUTES}
  detection/development: # /development properties may not be supported in all SDKs
    detectors:
      - service: # will add &amp;#34;service.instance.id&amp;#34; and &amp;#34;service.name&amp;#34; from the OTEL_SERVICE_NAME env var
      - host:
      - process:
      - container:

propagator:
  composite:
    - tracecontext:
    - baggage:

# Read backend endpoint from the OTEL_EXPORTER_OTLP_ENDPOINT environment variable.
# This aligns well with the OpenTelemetry Operator and other deployment methods.

tracer_provider:
  sampler:
    parent_based:
      root:
        always_on:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}/v1/traces

meter_provider:
  readers:
    - periodic:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}/v1/metrics

logger_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}/v1/logs
">
  <p class="text-body-secondary mb-3">
    Paste your existing configuration below to generate the equivalent
    declarative configuration YAML. You can fill in any combination of inputs.
  </p>

  <div class="row mb-3">
    <div class="col-md-6 mb-3 mb-md-0">
      <label for="dc-input-props" class="form-label">System properties / application.properties</label>
      <textarea id="dc-input-props" class="form-control font-monospace" rows="6"
        placeholder="otel.instrumentation.jdbc.enabled=false&#10;otel.instrumentation.kafka.experimental-span-attributes=true"></textarea>
    </div>
    <div class="col-md-6">
      <label for="dc-input-env" class="form-label">Environment variables</label>
      <textarea id="dc-input-env" class="form-control font-monospace" rows="6"
        placeholder="OTEL_INSTRUMENTATION_JDBC_ENABLED=false&#10;OTEL_SERVICE_NAME=my-app"></textarea>
    </div>
  </div>

  <div class="mb-3">
    <label for="dc-input-yaml" class="form-label">application.yaml</label>
    <textarea id="dc-input-yaml" class="form-control font-monospace" rows="6"
      placeholder="otel:&#10;  instrumentation:&#10;    jdbc:&#10;      enabled: false"></textarea>
  </div>
  <div class="mb-3">
    <label for="dc-output" class="form-label">Declarative Configuration output</label>
    <textarea id="dc-output" class="form-control font-monospace" rows="12" readonly></textarea>
    <button id="dc-copy" class="btn btn-sm btn-outline-secondary mt-2">
      Copy to clipboard
    </button>
  </div>

  <div id="dc-warnings" class="alert alert-warning d-none mb-0"></div>
</div>

<script src="/js/dcConverter.js"></script>

## 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.