Interoperabilidad de variables de entorno de OpenTelemetry

Documentos > OpenTelemetry en Datadog > Configuración de OpenTelemetry > Interoperabilidad de variables de entorno de OpenTelemetry

Los SDKs de Datadog implementan las APIs de OpenTelemetry para trazas, métricas y logs. Esto te permite utilizar variables de entorno estándar de OpenTelemetry para configurar tu aplicación mientras recibes telemetría adicional de Datadog con cambios mínimos en tu configuración existente.

Este página describe las variables de entorno de Datadog compatibles para la interoperabilidad de OpenTelemetry.

Las reglas de precedencia en esta página describen cómo los SDKs de Datadog resuelven la configuración en atributos de recursos de OpenTelemetry (por ejemplo, service.name, deployment.environment.name, service.version).

Para evitar que aparezcan valores duplicados en Datadog para la misma clave de etiqueta, no configures las variables de entorno de Datadog (DD_*) y OpenTelemetry (OTEL_*) para el mismo concepto. Elige una convención.
Consulta la página de configuración de SDK pertinente para los valores predeterminados y más información.

Requisitos de la red

When using the Datadog SDK with OpenTelemetry API support, telemetry is routed to different components depending on the signal source. Ensure the following ports are accessible on your Datadog Agent or Collector:

Signal Source	Protocol	Port	Destination Component
OTel Metrics and Logs API	OTLP (gRPC/HTTP)	4317 / 4318	Datadog Agent OTLP Receiver or DDOT Collector
Datadog Tracing	Datadog trace intake	8126 (TCP)	Datadog Trace Agent
Runtime Metrics	DogStatsD	8125 (UDP)	DogStatsD Server

Nota: Incluso cuando DD_METRICS_OTEL_ENABLED=true, las métricas de tiempo de ejecución estándar se siguen emitiendo a través de DogStatsD.

Configuración del SDK de Datadog

Estas variables de entorno permiten al SDK de Datadog ingerir datos de la API de métricas y logs de OpenTelemetry. Para obtener guías sobre cómo instrumentar tu aplicación, consulta la documentación de instrumentación específica del lenguaje.

DD_TRACE_OTEL_ENABLED: Descripción: habilita la interoperabilidad de OpenTelemetry del SDK de Datadog para trazas.
Por defecto: false
Notas: El valor por defecto es true en el SDK de Java.
DD_METRICS_OTEL_ENABLED: Descripción: habilita los componentes de instrumentación automática del SDK de Datadog para recopilar y emitir métricas generadas por la API de métricas de OpenTelemetry.
Predeterminado: false
DD_LOGS_OTEL_ENABLED: Descripción: habilita el SDK de Datadog para recopilar y exportar logs en el formato OpenTelemetry Protocol.
Notas: Para la mayoría de los lenguajes, esto habilita la compatibilidad con la API de logs de OpenTelemetry. Para .NET, permite interceptar los registradores integrados.
Por defecto: false

Configuración general de SDK

Los SDK de Datadog admiten las siguientes opciones generales de SDK de OpenTelemetry. Para obtener más información, consulta la documentación de OpenTelemetry relacionada.

OTEL_SERVICE_NAME

Convención de Datadog: DD_SERVICE
Establece el atributo de recurso service.name
Notas: Al determinar el atributo de recurso service.name final, el kit de desarrollo de software (SDK) utiliza esta variable como entrada para determinar el service.name final. Consulta las notas de service.name en OTEL_RESOURCE_ATTRIBUTES para conocer el orden de precedencia completo.

OTEL_LOG_LEVEL

Convención de Datadog: DD_LOG_LEVEL
Nivel de log utilizado por el SDK registrador
Notas: Un nivel de log de depuración también se asigna a DD_TRACE_DEBUG=true
En los SDKs de Node.js y PHP se asigna a DD_TRACE_LOG_LEVEL
En el SDK de Go solo se admiten valores asignados entre OTEL_LOG_LEVEL y DD_TRACE_DEBUG:

info|false
debug|true
**No compatible con los SDK de Python.NET, Ruby, y Go

OTEL_PROPAGATORS

Convención de Datadog: DD_TRACE_PROPAGATION_STYLE
Los propagadores deben utilizarse como una lista separada por comas.
Notas: Los únicos valores compatibles con la mayoría de los SDK de Datadog son tracecontext, b3, b3multi, none, datadog. xray también es compatible con el SDK de Java.
Los valores deben ser deduplicados para registrar un Propagator solo una vez

OTEL_TRACES_SAMPLER & OTEL_TRACES_SAMPLER_ARG

Convención de Datadog: DD_TRACE_SAMPLE_RATE
OTEL_TRACES_SAMPLER: muestreador a utilizar para trazas y OTEL_TRACES_SAMPLER_ARG: Valor de cadena a utilizar como argumento del muestreador.
Notas: El valor especificado solo se utiliza si OTEL_TRACES_SAMPLER está configurado. Cada tipo de muestreador define su propia entrada esperada, si la hay. Las entradas no válidas o no reconocidas DEBEN registrarse y, por lo demás, DEBEN ignorarse. En tales casos, la aplicación DEBE comportarse como si OTEL_TRACES_SAMPLER_ARG no estuviera activado.
Valores asignados entre OTEL_TRACES_SAMPLER y DD_TRACE_SAMPLE_RATE:

parentbased_always_on|1.0
parentbased_always_off|0.0
parentbased_traceidratio|${OTEL_TRACES_SAMPLER_ARG}
always_on|1.0
always_off|0.0
traceidratio|${OTEL_TRACES_SAMPLER_ARG}

OTEL_TRACES_EXPORTER

Convención de Datadog: DD_TRACE_ENABLED=false
Exportador de trazas a utilizar
Notas: Solo se acepta el valor none

OTEL_METRICS_EXPORTER

Descripción: especifica el exportador de métricas a utilizar.
Notas: Los únicos valores aceptados son OpenTelemetry Protocol y none. Un valor de none deshabilita la emisión de métricas de OpenTelemetry, así como las métricas de tiempo de ejecución de APM (equivalente a DD_RUNTIME_METRICS_ENABLED=false).
Por defecto: OpenTelemetry Protocol

OTEL_RESOURCE_ATTRIBUTES

Convención de Datadog: DD_TAGS
Descripción: pares clave-valor que se utilizarán como atributos del recurso de OpenTelemetry.
Notas: El kit de desarrollo de software (SDK) resuelve las configuraciones solapadas utilizando primero la configuración de Datadog (DD_*).

service.name (corresponde a DD_SERVICE): el kit de desarrollo de software (SDK) resuelve el valor con la siguiente precedencia:
1. Valor de DD_SERVICE
2. Valor de la clave service en DD_TAGS
3. Valor de OTEL_SERVICE_NAME
4. Valor de la clave service.name en OTEL_RESOURCE_ATTRIBUTES
deployment.environment.name (se asigna a DD_ENV): el kit de desarrollo de software (SDK) resuelve el valor con la siguiente precedencia:
1. Valor de DD_ENV
2. Valor de la clave env en DD_TAGS
3. Valor de la clave deployment.environment.name en OTEL_RESOURCE_ATTRIBUTES
4. Valor de deployment.environment en OTEL_RESOURCE_ATTRIBUTES
service.version (se asigna a DD_VERSION): el kit de desarrollo de software (SDK) resuelve el valor con la siguiente precedencia:
1. Valor de DD_VERSION
2. Valor de la clave version en DD_TAGS
3. Valor de la clave service.version en OTEL_RESOURCE_ATTRIBUTES
Atributos adicionales: pueden añadirse a través de la configuración de DD_TAGS, o de OTEL_RESOURCE_ATTRIBUTES si DD_TAGS no está configurado.

Aunque el kit de desarrollo de software (SDK) resuelve estos ajustes internamente para la telemetría emitida, el Datadog Agent recopila etiquetas de todas las fuentes configuradas sin anularlas. Configurar el servicio/entorno/versión utilizando múltiples entradas (por ejemplo, tanto DD_ENV como OTEL_RESOURCE_ATTRIBUTES) puede dar lugar a que aparezcan múltiples valores en Datadog (por ejemplo, env:prod y env:dev). Para evitar valores duplicados, configura cada concepto utilizando una sola convención.

OTEL_SDK_DISABLED

Descripción: desactiva la interoperabilidad de OpenTelemetry del SDK de Datadog para todas las señales.
Notas: Cuando se establece en true, esto establece efectivamente DD_TRACE_OTEL_ENABLED=false, DD_LOGS_OTEL_ENABLED=false y DD_METRICS_OTEL_ENABLED=false.
SDKs de Ruby y Go: el SDK de OpenTelemetry se activa automáticamente en la importación y configuración, por lo que este ajuste no es aplicable.

Configuración del exportador de OpenTelemetry Protocol

Los SDK de Datadog admiten las siguientes opciones del Exportador de OpenTelemetry Protocol.

Las variables específicas de una señal (como OTEL_EXPORTER_OTLP_METRICS_PROTOCOL) siempre tienen prioridad sobre sus variables homólogas generales (como OTEL_EXPORTER_OTLP_PROTOCOL).

Configuración general de OpenTelemetry Protocol

OTEL_EXPORTER_OTLP_PROTOCOL: Descripción: especifica el protocolo de transporte a utilizar para todas las señales a menos que se anule.
Valores aceptados: grpc, http/protobuf, http/json.
Predeterminado: dependiente del kit de desarrollo de software (SDK). El SDK de Datadog pretende coincidir con el protocolo por defecto del SDK de OpenTelemetry oficial correspondiente para ese lenguaje.
OTEL_EXPORTER_OTLP_ENDPOINT: Descripción: especifica la URL base para el envío de datos de OpenTelemetry Protocol a todas las señales a menos que se anule.
Por defecto (gRPC): http://localhost:4317.
Por defecto (HTTP): http://localhost:4318.
OTEL_EXPORTER_OTLP_HEADERS: Descripción: especifica una lista separada por comas de pares clave-valor que se utilizarán como encabezados en todas las solicitudes salientes de OpenTelemetry Protocol (por ejemplo, api-key=key,other-config=value).
OTEL_EXPORTER_OTLP_TIMEOUT: Descripción: especifica el tiempo de espera (en milisegundos) para todas las solicitudes salientes de OpenTelemetry Protocol a menos que se anule.
Predeterminado: 10000 (10s).

Configuración de OpenTelemetry Protocol específica para métricas

Para más detalles sobre la especificación oficial de estas variables, consulta la documentación del Exportador de métricas de OpenTelemetry Protocol.

OTEL_EXPORTER_OTLP_METRICS_PROTOCOL: Descripción: especifica el protocolo de transporte de OpenTelemetry Protocol a utilizar para los datos de métricas. Tiene prioridad sobre el protocolo general OTEL_EXPORTER_OTLP_PROTOCOL.
Valores aceptados: grpc, http/protobuf, http/json.
Por defecto: dependiente del kit de desarrollo de software (SDK). El SDK de Datadog pretende coincidir con el protocolo por defecto del SDK de OpenTelemetry oficial correspondiente para ese lenguaje.
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT: Descripción: especifica la URL para el envío de datos de métricas de OpenTelemetry Protocol. Tiene prioridad sobre el OTEL_EXPORTER_OTLP_ENDPOINT general.
Por defecto (gRPC): http://localhost:4317.
Por defecto (HTTP): http://localhost:4318/v1/metrics.
Notas: Para protocolos HTTP, el kit de desarrollo de software (SDK) añadirá automáticamente /v1/metrics si se utiliza OTEL_EXPORTER_OTLP_ENDPOINT como alternativa.
OTEL_EXPORTER_OTLP_METRICS_HEADERS: Descripción: especifica una lista separada por comas de pares clave-valor que se utilizarán como encabezado en las solicitudes salientes de métricas de OpenTelemetry Protocol (por ejemplo, api-key=key,other-config=value). Tiene precedencia sobre el campo general OTEL_EXPORTER_OTLP_HEADERS.
OTEL_EXPORTER_OTLP_METRICS_TIMEOUT: Descripción: especifica el tiempo de espera (en milisegundos) para una única solicitud saliente de métricas de OpenTelemetry Protocol. Tiene prioridad sobre el OTEL_EXPORTER_OTLP_TIMEOUT general.
Predeterminado: 10000 (10s).

Configuración de OpenTelemetry Protocol específica para logs

OTEL_EXPORTER_OTLP_LOGS_PROTOCOL: Descripción: especifica el protocolo de transporte de OpenTelemetry Protocol para los logs. Tiene prioridad sobre OTEL_EXPORTER_OTLP_PROTOCOL.; Valores aceptados: grpc, http/protobuf, http/json; Por defecto: dependiente del kit de desarrollo de software (SDK). El SDK de Datadog pretende coincidir con el protocolo por defecto del SDK de OpenTelemetry oficial correspondiente para ese lenguaje
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: Descripción: especifica la URL de envío de los logs de OpenTelemetry Protocol. Tiene prioridad sobre OTEL_EXPORTER_OTLP_ENDPOINT.; Por defecto (gRPC): http://localhost:4317; Por defecto (HTTP): http://localhost:4318/v1/logs
OTEL_EXPORTER_OTLP_LOGS_HEADERS: Descripción: especifica una lista separada por comas de pares clave-valor que se utilizarán como encabezado en las solicitudes salientes de logs de OpenTelemetry Protocol. Prevalece sobre la opción general OTEL_EXPORTER_OTLP_HEADERS.
OTEL_EXPORTER_OTLP_LOGS_TIMEOUT: Descripción: especifica el tiempo de espera (en milisegundos) para una única solicitud saliente de logs de OpenTelemetry Protocol. Tiene prioridad sobre el OTEL_EXPORTER_OTLP_TIMEOUT general.
Predeterminado: 10000 (10s).

Configuración del SDK de métricas de OpenTelemetry

Los SDK de Datadog admiten las siguientes opciones del SDK de métricas de OpenTelemetry.

OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE: Descripción: especifica la agregación temporality a utilizar para cada tipo de instrumento.
Valores aceptados: Cumulative, Delta, LowMemory. Para más detalles, consulta la especificación de OpenTelemetry.
Por defecto: delta
Notas: Este valor por defecto delta es la configuración recomendada de Datadog y difiere del valor por defecto de la especificación de OpenTelemetry.
OTEL_METRIC_EXPORT_INTERVAL: Descripción: especifica el intervalo de tiempo (en milisegundos) entre los intentos de exportación de métricas.
Predeterminado: 10000 (10s)
Notas: Este valor predeterminado es la configuración recomendada de Datadog y difiere del valor predeterminado de 60000ms de la especificación de OpenTelemetry.
OTEL_METRIC_EXPORT_TIMEOUT: Descripción: especifica el tiempo máximo permitido (en milisegundos) para recopilar y exportar métricas.
Predeterminado: 7500 (7.5s)
Notas: Este valor predeterminado es la configuración recomendada por Datadog y difiere del valor predeterminado de 30000ms de la especificación de OpenTelemetry.

Configuración del SDK de logs de OpenTelemetry

Los SDK de Datadog admiten las siguientes opciones del SDK de logs de OpenTelemetry.

OTEL_LOGS_EXPORTER: Descripción: especifica el exportador de logs a utilizar.
Valores aceptados: OpenTelemetry Protocol, none. Un valor de none desactiva la emisión de logs de OpenTelemetry.
Por defecto: OpenTelemetry Protocol
OTEL_BLRP_MAX_QUEUE_SIZE: Descripción: el número máximo de registros de log a mantener en memoria. Los nuevos registros se eliminan cuando se alcanza el límite.
Por defecto: 2048
OTEL_BLRP_SCHEDULE_DELAY: Descripción: el intervalo de tiempo (en milisegundos) entre dos operaciones de exportación consecutivas.
Predeterminado: 1000 (1s)
OTEL_BLRP_EXPORT_TIMEOUT: Descripción: la duración máxima (en milisegundos) permitida para una sola exportación antes de la cancelación.
Predeterminado: 30000 (30s)
OTEL_BLRP_MAX_EXPORT_BATCH_SIZE: Descripción: el número máximo de registros de log en una sola carga útil de OpenTelemetry Protocol.
Por defecto: 512

Java-específico Configuración

Los SDK de Datadog admiten las siguientes opciones de configuración de OpenTelemetry específicas de Java. Para obtener más información, consulta la documentación de OpenTelemetry sobre la configuración del Agent Java.

OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED

Convención de Datadog: !DD_INTEGRATIONS_ENABLED
Establézcalo en false para desactivar toda la instrumentación en el Agent
Notas: Valores asignados entre OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED y DD_INTEGRATIONS_ENABLED:

true|false
false|true

OTEL_INSTRUMENTATION_[NAME]_ENABLED

Descripción: Activa/desactiva la instrumentación drop-in OTel nombrada.

OTEL_JAVAAGENT_CONFIGURATION_FILE

Convención de Datadog: DD_TRACE_CONFIG
Ruta al archivo de propiedades de Java válido que contiene la configuración del agent.
Notas: Cuando OTEL_JAVAAGENT_CONFIGURATION_FILE y DD_TRACE_CONFIG están ambos definidos se aplica la configuración de ambos archivos. Esta es una excepción a la regla habitual según la cual la configuración de Datadog prevalece sobre la de OpenTelemetry.

OTEL_INSTRUMENTATION_HTTP_CLIENT_CAPTURE_REQUEST_HEADERS

Convención de Datadog: DD_TRACE_REQUEST_HEADER_TAGS
Una lista separada por comas de nombres de encabezado HTTP. Las instrumentaciones de cliente HTTP capturan los valores de encabezado de solicitud HTTP para todos los nombres de encabezado configurados
Notas: El etiquetado de encabezados configurado mediante variables de entorno de OpenTelemetry sigue la convención de nombres de etiquetas de OpenTelemetry de http.request.header.<header-name> en lugar de la convención de Datadog de http.request.headers.<header-name>

OTEL_INSTRUMENTATION_HTTP_CLIENT_CAPTURE_RESPONSE_HEADERS

Convención de Datadog: DD_TRACE_RESPONSE_HEADER_TAGS
Una lista separada por comas de nombres de encabezado HTTP. Las instrumentaciones de cliente HTTP capturan los valores de encabezado de respuesta HTTP para todos los nombres de encabezado configurados
Notas: El etiquetado de encabezados configurado mediante variables de entorno de OpenTelemetry sigue la convención de nombres de etiquetas de OpenTelemetry de http.response.header.<header-name> en lugar de la convención de Datadog de http.response.headers.<header-name>

OTEL_INSTRUMENTATION_HTTP_SERVER_CAPTURE_REQUEST_HEADERS

Convención de Datadog: DD_TRACE_REQUEST_HEADER_TAGS
Una lista separada por comas de nombres de encabezado HTTP. Las instrumentaciones del servidor HTTP capturan los valores de los encabezados de solicitud HTTP para todos los nombres de encabezados configurados
Notas: El etiquetado de encabezados configurado mediante variables de entorno de OpenTelemetry sigue la convención de nombres de etiquetas de OpenTelemetry de http.request.header.<header-name> en lugar de la convención de Datadog de http.request.headers.<header-name>

OTEL_INSTRUMENTATION_HTTP_SERVER_CAPTURE_RESPONSE_HEADERS

Convención de Datadog: DD_TRACE_RESPONSE_HEADER_TAGS
Una lista separada por comas de nombres de encabezado HTTP. Las instrumentaciones del servidor HTTP capturan los valores de los encabezados de respuesta HTTP para todos los nombres de encabezado configurados.
Notas: El etiquetado de encabezados configurado mediante variables de entorno de OpenTelemetry sigue la convención de nombres de etiquetas de OpenTelemetry de http.response.header.<header-name> en lugar de la convención de Datadog de http.response.headers.<header-name>

OTEL_JAVAAGENT_EXTENSIONS

Convención de Datadog: DD_TRACE_EXTENSIONS_PATH
Una lista separada por comas de rutas a archivos jar de extensión, o carpetas que contienen archivos jar. Si apunta a una carpeta, cada archivo jar en esa carpeta se trata como una extensión separada e independiente.