Ingesta de OTLP por parte del Datadog Agent

Documentos > OpenTelemetry en Datadog > Enviar datos de OpenTelemetry a Datadog > Ingesta de OTLP por parte del Datadog Agent

La ingesta de OTLP en el Agent es una forma de enviar datos de telemetría directamente desde aplicaciones instrumentadas con OpenTelemetry SDKs al Datadog Agent. Desde las versiones 6.32.0 y 7.32.0, el Datadog Agent puede ingerir trazas OTLP y métricas OTLP a través de gRPC o HTTP. Desde las versiones 6.48.0 y 7.48.0, el Datadog Agent puede ingerir registros OTLP a través de gRPC o HTTP.

La ingesta de OTLP en el Agent le permite utilizar funciones de observabilidad en el Datadog Agent. Los datos de aplicaciones instrumentadas con OpenTelemetry SDK no pueden utilizarse en algunos productos propietarios de Datadog, como App and API Protection, Continuous Profiler e Ingestion Rules. Las métricas de tiempo de ejecución de OpenTelemetry son compatibles con algunos lenguajes.

Diagrama: El SDK de OpenTelemetry envía datos a través del protocolo OTLP a un Collector con Datadog Exporter, el cual los reenvía a la plataforma de Datadog.

Para ver qué funciones de Datadog son compatibles con esta configuración, consulte la tabla de compatibilidad de funciones en OTel to Datadog Agent (OTLP).

Configuración inicial

Para comenzar, primero instrumente su aplicación con los SDK de OpenTelemetry. Luego, exporte los datos de telemetría en formato OTLP al Datadog Agent. La configuración de esto varía según el tipo de infraestructura en la que esté implementado su servicio, como se describe en la página a continuación. Aunque el objetivo es ser compatible con la versión más reciente de OTLP, la ingesta de OTLP en el Agent no es compatible con todas las versiones de OTLP. Las versiones de OTLP que son compatibles con el Datadog Agent son aquellas que también son compatibles con el receptor OTLP en el OpenTelemetry Collector. Para verificar las versiones exactas admitidas, verifique la versión go.opentelemetry.io/collector en el archivo go.mod del Agent.

Lea la documentación de instrumentación de OpenTelemetry para comprender cómo apuntar su instrumentación al Agent. La sección receiver descrita a continuación sigue el esquema de configuración del receptor OTLP de OpenTelemetry Collector.

La configuración admitida es un Agent de ingesta implementado en cada servidor que genera datos de OpenTelemetry. No puede enviar telemetría de OpenTelemetry desde colectores o aplicaciones instrumentadas que se ejecutan en un servidor a un Agent en un servidor diferente. Pero, siempre que el Agent sea local para el colector o la aplicación instrumentada con SDK, puede configurar múltiples pipelines.

Habilitación de la ingesta de OTLP en el Datadog Agent

La ingesta de OTLP está desactivada de forma predeterminada, y puede activarla actualizando la configuración de su archivo datadog.yaml o estableciendo variables de entorno. Las siguientes configuraciones de datadog.yaml habilitan los puntos de conexión en los puertos predeterminados. Cuando está habilitada, la ingesta de métricas y trazas está activada de forma predeterminada. La ingesta de registros está deshabilitada de forma predeterminada para evitar una facturación inesperada de registros.

The following examples use 0.0.0.0 as the endpoint address for convenience. This allows connections from any network interface. For enhanced security, especially in local deployments, consider using localhost instead. For more information on secure endpoint configuration, see the OpenTelemetry security documentation.

Para gRPC, puerto predeterminado 4317:

otlp_config:
  receiver:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
  logs:
    enabled: false

Para HTTP, puerto predeterminado 4318:

otlp_config:
  receiver:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
  logs:
    enabled: false

Alternativamente, configure los puntos de conexión proporcionando el puerto a través de las variables de entorno:

Para gRPC (localhost:4317): DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_GRPC_ENDPOINT
Para HTTP (localhost:4318): DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_HTTP_ENDPOINT

Estos deben pasarse tanto al proceso del Agent principal como al proceso del Agent de trazas. Si se ejecuta en un entorno de contenedor, utilice 0.0.0.0 en lugar de localhost para asegurarse de que el servidor esté disponible en interfaces no locales.

Configure gRPC o HTTP para esta función. Aquí tiene una aplicación de ejemplo que muestra la configuración para ambos.

Siga la configuración del Agente de Datadog para Docker.
Para el contenedor del Agente de Datadog, establezca las siguientes variables de entorno de punto de conexión y exponga el puerto correspondiente:
- Para gRPC: Establezca DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_GRPC_ENDPOINT en 0.0.0.0:4317 y exponga el puerto 4317.
- Para HTTP: Establezca DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_HTTP_ENDPOINT en 0.0.0.0:4318 y exponga el puerto 4318.

Problema conocido: A partir de la versión 7.61.0 del Agente, las pipelines de ingesta de OTLP pueden fallar al iniciarse en entornos Docker, mostrando el error: Error running the OTLP ingest pipeline: failed to register process metrics: process does not exist.

Si está utilizando una versión afectada, puede usar una de estas soluciones alternativas:

1. Establezca la variable de entorno HOST_PROC a /proc en su contenedor Docker del Agente.
2. Elimine /proc/:/host/proc/:ro de volumes en su contenedor Docker del Agente.
3. Establezca pid a host en su contenedor Docker del Agente.

Estas configuraciones se pueden aplicar a través de docker comando o archivo Docker compose.

Siga la configuración del Agente de Kubernetes para la instalación base.

Habilite el protocolo preferido gRPC o HTTP en el manifiesto datadog-agent.yaml de su Operator:

Para gRPC:

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  # (...)
  features:
    otlp:
      receiver:
        protocols:
          grpc:
            enabled: true

For HTTP:

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  # (...)
  features:
    otlp:
      receiver:
        protocols:
          http:
            enabled: true

After making your changes, apply the new configuration by using the following command:

kubectl apply -n $DD_NAMESPACE -f datadog-agent.yaml

Esto habilita cada protocolo en el puerto predeterminado (4317 para OTLP/gRPC y 4318 para OTLP/HTTP). Las métricas y las trazas están habilitadas de forma predeterminada.

Siga la configuración del Agente de Kubernetes para la instalación base.

Habilite el protocolo preferido gRPC o HTTP en su archivo datadog-values.yaml de Helm:

Para gRPC:

datadog:
  # (...)
  otlp:
    receiver:
      protocols:
        grpc:
          enabled: true

For HTTP:

datadog:
  # (...)
  otlp:
    receiver:
      protocols:
        http:
          enabled: true

After making your changes, upgrade your Datadog Helm chart using the following command:

helm upgrade -f datadog-values.yaml <RELEASE NAME> datadog/datadog

Esto habilita cada protocolo en el puerto predeterminado (4317 para OTLP/gRPC y 4318 para OTLP/HTTP). Las métricas y las trazas están habilitadas de forma predeterminada.

Siga la guía de instalación manual de Kubernetes para la instalación base.

Configure las siguientes variables de entorno tanto en el contenedor trace-agent como en el contenedor agent principal:

Para gRPC:

name: DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_GRPC_ENDPOINT # enables gRPC receiver on port 4317
value: "0.0.0.0:4317"

For HTTP:

name: DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_HTTP_ENDPOINT # enables HTTP receiver on port 4318
value: "0.0.0.0:4318"

Asigne los puertos de contenedor 4317 o 4318 al puerto del servidor para el contenedor agent principal:

Para gRPC:

ports:
  - containerPort: 4317
    hostPort: 4317
    name: traceportgrpc
    protocol: TCP

For HTTP

ports:
  - containerPort: 4318
    hostPort: 4318
    name: traceporthttp
    protocol: TCP

Para obtener instrucciones detalladas sobre el uso de OpenTelemetry con AWS Lambda y Datadog, incluyendo:

Instrumentación de sus funciones Lambda con OpenTelemetry
Uso de la compatibilidad con la API de OpenTelemetry en los SDK de Datadog
Envío de trazas de OpenTelemetry a Datadog Lambda Extension

Consulte la documentación de Serverless para AWS Lambda y OpenTelemetry.

Habilitación de la ingesta de registros de OTLP

La ingesta de registros de OTLP está deshabilitada de forma predeterminada para evitar facturación inesperada. Para habilitarla, debe activar explícitamente tanto la recopilación de registros como la ingesta de registros de OTLP.

Habilite la recopilación de logs siguiendo la Host Agent Log collection setup:
```
logs_enabled: true
```
Establezca otlp_config.logs.enabled en true:
```
otlp_config:
  logs:
    enabled: true
```

Configure las siguientes variables de entorno en el contenedor del Datadog Agent:

DD_LOGS_ENABLED=true
DD_OTLP_CONFIG_LOGS_ENABLED=true

En su archivo datadog-agent.yaml

spec:
  # (...)
  features:
    otlp:
      #(... enable gRPC or HTTP ingestion...)
    logCollection:
      enabled: true
  override:
    nodeAgent:
      containers:
        agent:
          env:
            - name: DD_OTLP_CONFIG_LOGS_ENABLED
              value: "true"

After making your changes, apply the new configuration by using the following command:

kubectl apply -n $DD_NAMESPACE -f datadog-agent.yaml

En su archivo datadog-values.yaml:

datadog:
  # (...)
  otlp:
    #(... enable gRPC or HTTP ingestion...)
    logs:
      enabled: true
  logs:
    enabled: true

After making your changes, upgrade your Datadog Helm chart using the following command:

helm upgrade -f datadog-values.yaml <RELEASE NAME> datadog/datadog

Configure las siguientes variables de entorno en el contenedor del Agente principal:

- name: DD_LOGS_ENABLED
  value: "true"
- name: DD_OTLP_CONFIG_LOGS_ENABLED
  value: "true"

Para obtener más información, consulte recopilación de registros con su DaemonSet.

Existen muchas otras variables de entorno y configuraciones compatibles en el Agente de Datadog. Para obtener una descripción general, consulte Agent configuration files.

Envío de trazas, métricas y registros de OpenTelemetry al Datadog Agent

Después de habilitar la ingesta de OTLP en el Datadog Agent, configure su aplicación instrumentada con OpenTelemetry para exportar datos de telemetría al punto de conexión OTLP del Datadog Agent. Configure la variable de entorno OTEL_EXPORTER_OTLP_ENDPOINT en el entorno de su aplicación para dirigir los datos al Agent. Sin esta configuración, su aplicación no envía datos de telemetría al Agent, incluso si el receptor OTLP del Agent está habilitado.

Configure la variable de entorno OTEL_EXPORTER_OTLP_ENDPOINT en el entorno de su aplicación:

Para gRPC:

export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"

Para HTTP:

export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"

Para el contenedor de la aplicación, establezca la variable de entorno OTEL_EXPORTER_OTLP_ENDPOINT para que apunte al contenedor del Datadog Agent. Por ejemplo:
```
OTEL_EXPORTER_OTLP_ENDPOINT=http://<datadog-agent>:4318
```
Ambos contenedores deben estar definidos en la misma red bridge, lo cual se maneja automáticamente si utiliza Docker Compose. De lo contrario, siga el ejemplo de Docker en Tracing Docker Applications para configurar una red bridge con los puertos correctos.

En el archivo de despliegue de la aplicación, configure el punto de conexión al que el cliente de OpenTelemetry envía las trazas con la variable de entorno OTEL_EXPORTER_OTLP_ENDPOINT.

Para gRPC:

env:
 - name: HOST_IP
   valueFrom:
     fieldRef:
       fieldPath: status.hostIP
 - name: OTEL_EXPORTER_OTLP_ENDPOINT
   value: "http://$(HOST_IP):4317" # sends to gRPC receiver on port 4317

Para HTTP:

env:
 - name: HOST_IP
   valueFrom:
     fieldRef:
       fieldPath: status.hostIP
 - name: OTEL_EXPORTER_OTLP_ENDPOINT
   value: "http://$(HOST_IP):4318" # sends to HTTP receiver on port 4318

Nota: Para enriquecer las etiquetas de contenedor para métricas personalizadas, establezca los atributos de recurso apropiados en el código de la aplicación donde se generan sus métricas OTLP. Por ejemplo, establezca el atributo de recurso container.id utilizando un detector de recursos de contenedor.

Al configurar el punto de conexión para enviar trazas, asegúrese de utilizar la ruta correcta requerida por su biblioteca OTLP. Algunas bibliotecas esperan que las trazas se envíen a la /v1/traces ruta, mientras que otras utilizan la ruta raíz /.