Skip to content

Clarify SDK precedence and warn against using OTel and DD settings. #33570

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
brett0000FF merged 2 commits into from
Dec 24, 2025
Merged

Clarify SDK precedence and warn against using OTel and DD settings. #33570

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6a64901
Clarify SDK precedence and warn against using OTel and DD settings.
brett0000FF Dec 23, 2025
3af9f7d
Extra cleanup.
brett0000FF Dec 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 20 additions & 13 deletions content/en/opentelemetry/config/environment_variable_support.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,13 @@ Datadog SDKs implement the OpenTelemetry APIs for traces, metrics, and logs. Thi

This page describes the environment variables Datadog supports for OpenTelemetry interoperability.

<div class="alert alert-info">If both Datadog and OpenTelemetry environment variables are set, Datadog takes precedence. Datadog defaults also override OpenTelemetry defaults. See the relevant <a href="/tracing/trace_collection/library_config/">SDK Configuration page</a> for default values and more information.</div>
The precedence rules on this page describe how *Datadog SDKs* resolve configuration into OpenTelemetry resource attributes (for example, `service.name`, `deployment.environment.name`, `service.version`).

<div class="alert alert-danger">
To avoid duplicate values appearing in Datadog for the same tag key, don't set both Datadog (<code>DD_*</code>) and OpenTelemetry (<code>OTEL_*</code>) environment variables for the same concept. Choose one convention.
<br>
See the relevant <a href="/tracing/trace_collection/library_config/">SDK Configuration page</a> for default values and more information.
</div>

## Datadog SDK configuration
These environment variables enable the Datadog SDK to ingest OpenTelemetry Metrics and Logs API data. For guides on how to instrument your application, see the [language-specific instrumentation documentation][14].
Expand All @@ -47,10 +53,6 @@ These environment variables enable the Datadog SDK to ingest OpenTelemetry Metri
: **Description**: Enables the automatic instrumentation components of the Datadog SDK to collect and emit metrics generated by the OTel Metrics API. <br>
**Default**: `false`

`DD_LOGS_OTEL_ENABLED`
: **Description**: Enables the Datadog SDK's native OpenTelemetry Logs API implementation, allowing logs to be collected and exported in OTLP format. <br>
**Default**: `false`

`DD_LOGS_OTEL_ENABLED`
: **Description**: Enables the Datadog SDK to collect and export logs in the OTLP format. <br>
**Notes**: For most languages, this enables support for the OTel Logs API. For .NET, this enables interception of built-in loggers. <br>
Expand All @@ -62,7 +64,7 @@ Datadog SDKs support the following general OpenTelemetry SDK options. For more i
`OTEL_SERVICE_NAME`
: **Datadog convention**: `DD_SERVICE`<br>
Sets the `service.name` resource attribute<br>
**Notes**: This variable is one of several used to determine the final service name. See the `service.name` notes under `OTEL_RESOURCE_ATTRIBUTES` for the complete precedence order.<br>
**Notes**: When determining the final `service.name` resource attribute, the SDK uses this variable as an input to determine the final `service.name`. See the `service.name` notes under `OTEL_RESOURCE_ATTRIBUTES` for the complete precedence order.<br>

`OTEL_LOG_LEVEL`
: **Datadog convention**: `DD_LOG_LEVEL`<br>
Expand Down Expand Up @@ -104,27 +106,32 @@ Trace exporter to be used<br>

`OTEL_RESOURCE_ATTRIBUTES`
: **Datadog convention**: `DD_TAGS` <br>
**Description**: Key-value pairs to be used as resource attributes. <br>
**Notes**: Datadog-defined configurations take precedence.
- `service.name` (maps to `DD_SERVICE`): Resolved with the following precedence: <br>
**Description**: Key-value pairs to be used as OpenTelemetry resource attributes. <br>
**Notes**: The SDK resolves overlapping settings using Datadog (`DD_*`) configuration first.
- `service.name` (maps to `DD_SERVICE`): The SDK resolves the value with the following precedence: <br>
1. Value of `DD_SERVICE` <br>
2. Value of `service` key in `DD_TAGS` <br>
3. Value of `OTEL_SERVICE_NAME` <br>
4. Value of `service.name` key in `OTEL_RESOURCE_ATTRIBUTES`
- `deployment.environment.name` (maps to `DD_ENV`): Resolved with the following precedence: <br>
- `deployment.environment.name` (maps to `DD_ENV`): The SDK resolves the value with the following precedence: <br>
1. Value of `DD_ENV` <br>
2. Value of `env` key in `DD_TAGS` <br>
3. Value of `deployment.environment.name` key in `OTEL_RESOURCE_ATTRIBUTES` <br>
4. Value of `deployment.environment` in `OTEL_RESOURCE_ATTRIBUTES`
- `service.version` (maps to `DD_VERSION`): Resolved with the following precedence: <br>
- `service.version` (maps to `DD_VERSION`): The SDK resolves the value with the following precedence: <br>
1. Value of `DD_VERSION` <br>
2. Value of `version` key in `DD_TAGS` <br>
3. Value of `service.version` key in `OTEL_RESOURCE_ATTRIBUTES`
- **Additional Attributes**: May be added through the `DD_TAGS` configuration, or `OTEL_RESOURCE_ATTRIBUTES` if `DD_TAGS` is not set.

<div class="alert alert-danger">
Although the SDK resolves these settings internally for emitted telemetry, the Datadog Agent collects tags from all configured sources without overriding. Configuring service/environment/version using multiple inputs (for example, both <code>DD_ENV</code> and <code>OTEL_RESOURCE_ATTRIBUTES</code>) can result in multiple values appearing in Datadog (for example, <code>env:prod</code> and <code>env:dev</code>).
To avoid duplicates, configure each concept using only one convention.
</div>

`OTEL_SDK_DISABLED`
: **Description**: Disables the Datadog SDK's OpenTelemetry interoperability for all signals. <br>
**Notes**: **Notes**: When set to `true`, this effectively sets `DD_TRACE_OTEL_ENABLED=false`, `DD_LOGS_OTEL_ENABLED=false`, and `DD_METRICS_OTEL_ENABLED=false`.<br>
**Notes**: When set to `true`, this effectively sets `DD_TRACE_OTEL_ENABLED=false`, `DD_LOGS_OTEL_ENABLED=false`, and `DD_METRICS_OTEL_ENABLED=false`.<br>
**Ruby & Go SDKs**: The OpenTelemetry SDK activates automatically upon import and configuration, so this setting is not applicable.

## OTLP Exporter configuration
Expand Down Expand Up @@ -298,4 +305,4 @@ A comma-separated list of paths to extension jar files, or folders containing ja
[13]: https://opentelemetry.io/docs/specs/otel/protocol/exporter/
[14]: /opentelemetry/instrument/api_support/
[15]: https://opentelemetry.io/docs/specs/otel/metrics/sdk_exporters/otlp/#additional-environment-variable-configuration
[16]: /opentelemetry/guide/otlp_delta_temporality/
[16]: /opentelemetry/guide/otlp_delta_temporality/
Loading