# Java SDK Setup with Declarative Configuration

Configure the OpenTelemetry SDK in Java via declarative YAML configuration. Three setup
paths exist. The Javaagent and manual autoconfigure both read an external file via
the `otel.config.file` system property or `OTEL_CONFIG_FILE` environment variable. The Spring Boot
Starter is different: it embeds the declarative config inline under the `otel:` key in
`application.yaml`/`application.properties`, opting in via the `otel.file_format` property — it
does not read an external `otel.config.file` (see Key API Facts).

For the YAML configuration schema, load the `otel-declarative-config` skill.

## Sources of Truth

For YAML schema details, fetch the upstream sources listed in the `otel-declarative-config`
skill. For Java-specific facts:

| Fact | Fetch |
|---|---|
| Latest BOM (`opentelemetry-bom`) | `gh api repos/open-telemetry/opentelemetry-java/releases/latest -q '.tag_name'` |
| Latest Javaagent | `gh api repos/open-telemetry/opentelemetry-java-instrumentation/releases/latest -q '.tag_name'` |
| SDK declarative-config accepted and preferred `file_format` for a selected BOM tag | `WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-java/<selected-sdk-tag>/sdk-extensions/declarative-config/src/main/java/io/opentelemetry/sdk/autoconfigure/declarativeconfig/OpenTelemetryConfigurationFactory.java` |
| Javaagent declarative-config docs (current activation flag, supported `file_format`) | `WebFetch https://opentelemetry.io/docs/zero-code/java/agent/declarative-configuration/` |
| Javaagent declarative-config smoke fixture (parser truth for selected agent tag) | `WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-java-instrumentation/<selected-agent-tag>/smoke-tests/src/test/resources/declarative-config.yaml` |
| Javaagent CHANGELOG (when each schema rc landed) | `WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-java-instrumentation/<selected-agent-tag>/CHANGELOG.md` |
| Generated Java instrumentation config reference (names, types, defaults, deprecations) | `WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-java-instrumentation/<selected-agent-tag>/docs/declarative-configuration-example.yaml` |
| Spring Boot Starter declarative-config fixture (selected starter tag) | `WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-java-instrumentation/<selected-agent-tag>/smoke-tests-otel-starter/spring-boot-2/src/testDeclarativeConfig/resources/application.yaml` |
| Spring Boot starter docs | `WebFetch https://opentelemetry.io/docs/zero-code/java/spring-boot-starter/` |

## Javaagent Download

The Javaagent JAR has no compile dependencies for auto-instrumentation. Download the latest
release directly:

```bash
curl -L -o opentelemetry-javaagent.jar \
  https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
```

## Activation

```bash
java -javaagent:opentelemetry-javaagent.jar \
     -Dotel.config.file=configs/otel.yaml \
     -jar myservice.jar
```

Declarative config has been supported since Javaagent 2.9.0; the property is now the stable
`otel.config.file` (the experimental `otel.experimental.config.file` alias was removed in the
SDK 1.63.0 bundled with Javaagent 2.29.0). Newer agent versions track newer schema versions.
Confirm both the accepted range and preferred `file_format` from the tag-matched parser, then use
the preferred value from that release's fixture to avoid compatibility warnings for experimental
properties. Verified 2026-10-15: SDK BOM 1.67.0 prefers `"1.2"`, while Javaagent/Spring Boot
Starter 2.32.0 embeds SDK 1.66.0 and prefers `"1.1"` (other notes in this file were last checked
against 2.31.1); per-runtime table in the
`otel-declarative-config` skill's `references/runtime-compatibility.md`. Keep the selected distribution's
embedded SDK distinct from the independently released BOM, and do not infer either from `main` or
the generic language support matrix alone.

When `otel.config.file` / `OTEL_CONFIG_FILE` is set, all other SDK autoconfigure properties are
ignored except agent-only properties (see Key API Facts).

The same property and environment-variable forms work for the autoconfigure SDK extension without
the Javaagent.

## YAML Config

For the canonical structure, fetch `examples/otel-sdk-config.yaml` (see the
`otel-declarative-config` skill's Sources of Truth). For the correct `file_format` string,
use the selected Javaagent parser/docs/fixtures. The generic language support matrix is
coverage metadata and may not be the exact YAML literal accepted by the Javaagent.

```yaml
# file_format: use the preferred literal for the selected Javaagent version
resource:
  attributes:
    - name: service.name
      value: "${SERVICE_NAME:-myservice}"
    - name: deployment.environment.name
      value: "${DEPLOY_ENV:-development}"

# Tracer/meter/logger provider blocks: structure per the canonical example.
# Java-specific quirk: all duration values must be in milliseconds (e.g., 5000, not "5s").
```

## Adding Manual Instrumentation

The Javaagent registers `GlobalOpenTelemetry` automatically. Use it to get tracers/meters:

```java
import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.api.metrics.Meter;

Tracer tracer = GlobalOpenTelemetry.getTracer("mycompany.com/myservice");
Meter meter = GlobalOpenTelemetry.getMeter("mycompany.com/myservice");
```

For autoconfigure setups (no Javaagent):

```java
import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;

// Reads -Dotel.config.file or OTEL_CONFIG_FILE, falls back to env vars
AutoConfiguredOpenTelemetrySdk sdk =
    AutoConfiguredOpenTelemetrySdk.builder().setResultAsGlobal().build();
```

## Key API Facts

- **Spring Boot Starter activation**: unlike the Javaagent/autoconfigure, the starter does
  not load an external file. Embed the declarative config inline under the `otel:` key in
  `application.yaml` (or as `otel.*` properties in `application.properties`) and opt in by
  setting `otel.file_format` (for example, `file_format: "1.1"` for starter 2.31.1; verify the
  selected release fixture). The presence of `otel.file_format` is what switches the starter into
  declarative-config mode.
- **Shutdown hook**: The Javaagent and autoconfigure both register a JVM shutdown hook automatically — no manual `sdk.close()` needed.
- **Zipkin exporter removal**: SDK/BOM 1.65.0 no longer publishes
  `opentelemetry-exporter-zipkin`. It was previously deprecated; migrate direct Zipkin export to
  OTLP or send OTLP to a Collector with a Zipkin-compatible exporter before upgrading. Javaagent
  2.31.1 still accepts `otel.traces.exporter=zipkin` and `otel.exporter.zipkin.endpoint`, but both
  are deprecated in favor of OTLP configuration.
- **Declarative-config model builders**: SDK/BOM 1.66.0 renamed the generated declarative-config
  model POJO setters from `with<Prop>` to `set<Prop>` (breaking). Code that builds the config model
  programmatically must be updated; YAML files are unaffected.
- **Agent-only properties**: `otel.javaagent.extensions`, `otel.javaagent.enabled`, and
  `otel.javaagent.debug` cannot be set via declarative config. Set them as system properties or
  their corresponding environment variables instead.
- **Semantic-convention selection**: In 2.31.1 declarative config, prefer
  `instrumentation/development.general.stability_opt_in_list`, a comma-separated string such as
  `database,code,messaging` or `<group>/dup` for dual emission. The older
  `general.semconv_stability.opt_in` field is deprecated. Check the tag-matched generated config
  and instrumentation metadata because support differs by domain and instrumentation.
- **Starter thread details**: Starter 2.31.1 can add experimental `thread.id` and `thread.name`
  to spans with `distribution.spring_starter.thread_details_enabled: true`. This path is
  Starter-only; the Javaagent uses the separate
  `distribution.javaagent.thread_details_enabled` path.

# Sensitive-data capture in Java HTTP instrumentation

What the Javaagent and Spring Boot Starter capture from HTTP traffic by default, and every
knob that changes it. Applies to both distribution channels — they share the same
instrumentation config properties (env-var form: upper-case, dots/dashes → underscores).

## What is captured by default

| Data | Attribute | Default |
|---|---|---|
| URL path | `url.path` (server) / inside `url.full` (client) | **captured** |
| URL query string | `url.query` (server) / inside `url.full` (client) | **captured**, with only the sensitive-parameter list below redacted |
| Request/response headers | `http.request.header.<name>` / `http.response.header.<name>` | not captured (opt-in) |
| Servlet request parameters (form/query) | `servlet.request.parameter.<name>` | not captured (opt-in, experimental) |
| SQL query text / parameter values | `db.statement` by default; `db.query.text` with stable database semconv; `db.query.parameter.<key>` only when opted in | query text captured but sanitized; parameter values off |

The asymmetry matters: headers, request parameters, and SQL values are **off** by default,
but the raw query string is **on** — any user data in a query string
(`GET /owners?lastName=Smith`, search terms, tokens in links) is exported verbatim unless
its parameter name is in the redaction list.

## Query-parameter redaction

Values of listed parameter names are replaced with `REDACTED` in `url.query` and `url.full`
(parameter names themselves are preserved, per semconv):

```properties
# default list — credential parameters only
otel.instrumentation.sanitization.url.experimental.sensitive-query-parameters=\
  AWSAccessKeyId,Signature,X-Amz-Signature,X-Amz-Credential,\
  X-Amz-Security-Token,sig,X-Goog-Signature
```

- Type: list of case-sensitive parameter names. Setting it **replaces** the default list
  (full override, not additive) — re-list the credential defaults when extending it.
- In Javaagent and Spring Boot Starter **v2.31.1**, the equivalent declarative field is
  `instrumentation/development.general.sanitization.url.sensitive_query_parameters`. It also
  replaces the default list, so include every default that must remain active.
- History: replaces `otel.instrumentation.http.client.experimental.redact-query-parameters`
  (client-only; deprecated, then removed in 2026 releases —
  [#18229](https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/18229)).

**There is no property that drops the query string entirely.** To export URLs without query
strings, delete/rewrite the attributes in a Collector processor (`transform`/`redaction`), or
customize the HTTP instrumentation's attribute extraction. A `SpanProcessor` cannot reliably
remove them: its end callback receives a read-only span after HTTP attributes have been recorded.

## Opt-in capture knobs (off by default)

```properties
otel.instrumentation.http.server.capture-request-headers=<list>
otel.instrumentation.http.server.capture-response-headers=<list>
otel.instrumentation.http.client.capture-request-headers=<list>
otel.instrumentation.http.client.capture-response-headers=<list>
otel.instrumentation.servlet.experimental.request-parameters.included=<list-of-globs>
otel.instrumentation.servlet.experimental.request-parameters.excluded=<list-of-globs>
# High risk: captures JDBC parameter values and disables query sanitization
otel.instrumentation.jdbc.experimental.capture-query-parameters=true
```

Captured headers land as `http.request.header.<lowercase-name>` /
`http.response.header.<lowercase-name>` (list-valued); servlet parameters as
`servlet.request.parameter.<name>`. Enabling any of these captures the raw values — there
is no per-header/per-parameter value redaction. Servlet selectors are case-sensitive; exclusions
take precedence. With both lists empty, nothing is captured. An exclude-only selector captures
every available parameter not excluded, so prefer an explicit include list. The old
`otel.instrumentation.servlet.experimental.capture-request-parameters` include-only property is
deprecated in 2.31.1 and does not support globs.

Those flat properties apply to normal property-based configuration. When declarative config is
active, flat instrumentation properties are not an overlay; use the corresponding YAML paths:

```yaml
instrumentation/development:
  general:
    http:
      client:
        request_captured_headers: [x-request-id]
        response_captured_headers: [x-request-id]
      server:
        request_captured_headers: [x-request-id]
        response_captured_headers: [x-request-id]
  java:
    servlet:
      request_parameters/development:
        included: [customer-*]
        excluded: [customer-password]
    jdbc:
      # High risk: captures values and disables query sanitization
      capture_query_parameters/development: true
```

## SQL sanitization

SQL literal/parameter sanitization (values → `?`) is on by default; the current toggle is
`java.common.db.query_sanitization.enabled` under `instrumentation/development` in declarative
config, or
`otel.instrumentation.common.db.query-sanitization.enabled` as a system property/environment
variable. Per-instrumentation toggles can take precedence. Older property spellings
(`otel.instrumentation.common.db-statement-sanitizer.enabled` and per-instrumentation
`*-statement-sanitizer.enabled` variants) are deprecated and, when
`instrumentation/development.java.common.v3_preview: true` in Javaagent/Starter 2.30.0, ignored.
Use the `db.query_sanitization.enabled` forms above. Do not turn sanitization off on request paths.

JDBC's parameter-capture switch shown above is a separate opt-in. It emits raw values as
`db.query.parameter.<key>` and disables sanitization even if the sanitization toggle is `true`.

## Sources of truth

| Fact | Fetch |
|---|---|
| HTTP capture properties (headers, servlet params, known-methods) | `WebFetch https://opentelemetry.io/docs/zero-code/java/agent/instrumentation/http/` |
| Current property names/defaults incl. `sensitive-query-parameters` | `WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-java-instrumentation/<selected-agent-tag>/instrumentation-docs/src/main/resources/shared-config-definitions.yaml`; per-instrumentation `metadata.yaml` files reference these shared definitions |
| Generated declarative names, defaults, and deprecations | `WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-java-instrumentation/<selected-agent-tag>/docs/declarative-configuration-example.yaml` |
| Renames/removals of capture & sanitization properties | `WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-java-instrumentation/<selected-agent-tag>/CHANGELOG.md` |
| Semconv redaction rules for `url.query`/`url.full` | `WebFetch https://opentelemetry.io/docs/specs/semconv/http/http-spans/` |