El OpenTelemetry Collector es un proceso del Agent de proveedor agnóstico para recopilar y exportar datos de telemetría emitidos por muchos procesos. El Exportador de Datadog para OpenTelemetry Collector te permite reenviar trazas (traces), métricas y datos de logs de SDKs de OpenTelemetry a Datadog (sin el Datadog Agent). Funciona con todos los lenguajes compatibles y puedes conectar esos datos de traza de OpenTelemetry con logs de aplicación.

Biblioteca instrumentada de aplicaciones, integraciones en la nube y otras soluciones de monitorización (por ejemplo, Prometheus) -> Exportador de Datadog dentro de OpenTelemetry Collector -> Datadog

Configuración de OpenTelemetry Collector con el exportador de Datadog

Para ejecutar OpenTelemetry Collector junto con el exportador de Datadog:

Paso 1: Descargar OpenTelemetry Collector

Descarga la última versión de la distribución OpenTelemetry Collector Contrib, desde el repositorio del proyecto.

Paso 2: Configurar el exportador de Datadog

Para utilizar el exportador de Datadog, añádelo a tu configuración de OpenTelemetry Collector. Crea un archivo de configuración y nómbralo collector.yaml. Utiliza el archivo de ejemplo que proporciona una configuración básica que está listo para usar después de establecer tu clave de API de Datadog como la variable de entorno DD_API_KEY:

collector.yaml

receivers:
  otlp:
    protocols:
      http:
      grpc:
  # El receptor de métricas de host es necesario para obtener las métricas de infraestructura correctas en Datadog.
  hostmetrics:
    collection_interval: 10s
    scrapers:
      paging:
        metrics:
          system.paging.utilization:
            enabled: true
      cpu:
        metrics:
          system.cpu.utilization:
            enabled: true
      disk:
      filesystem:
        metrics:
          system.filesystem.utilization:
            enabled: true
      load:
      memory:
      network:
      processes:
  # El receptor de prometheus extrae las métricas necesarias para el dashboard de OpenTelemetry Collector.
  prometheus:
    config:
      scrape_configs:
      - job_name: 'otelcol'
        scrape_interval: 10s
        static_configs:
        - targets: ['0.0.0.0:8888']

  filelog:
    include_file_path: true
    poll_interval: 500ms
    include:
      - /var/log/**/*example*/*.log

processors:
  batch:
    send_batch_max_size: 100
    send_batch_size: 10
    timeout: 10s

exporters:
  datadog:
    api:
      site: <DD_SITE>
      key: ${env:DD_API_KEY}

service:
  pipelines:
    metrics:
      receivers: [hostmetrics, prometheus, otlp]
      processors: [batch]
      exporters: [datadog]
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [datadog]
    logs:
      receivers: [otlp, filelog]
      processors: [batch]
      exporters: [datadog]

Donde <DD_SITE> es tu sitio, .

La configuración anterior permite la recepción de datos OTLP de las bibliotecas de instrumentación de OpenTelemetry a través de HTTP y gRPC, y configura un procesador por lotes, que es obligatorio para cualquier entorno que no sea de desarrollo. Ten en cuenta que pueden producirse errores en 413 - Request Entity Too Large si almacenas demasiados datos telemétricos en el procesador por lotes.

La configuración exacta del procesador por lotes depende de tu carga de trabajo específica, así como de los tipos de señales. La ingesta de Datadog tiene diferentes límites de tamaño de carga útil para los 3 tipos de señales:

Configuración avanzada

Este archivo de ejemplo de configuración completamente registrado ilustra todas las opciones posibles de configuración para el Exportador de Datadog. Puede haber otras opciones relevantes para tu despliegue, como api::site o las de la sección host_metadata.

Paso 3 - Configurar tu solicitud

Para obtener mejores metadatos para trazas y para simplificar la integración con Datadog:

  • Utiliza detectores de recursos: si los proporciona el SDK del lenguaje, adjunta información de contenedor como atributos de recurso. Por ejemplo, en Go, utiliza la opción de recurso WithContainer().

  • Aplica etiquetado de servicios unificado: asegúrate de haber configurado tu aplicación con los atributos de recursos apropiados para el etiquetado de servicios unificado. Esto vincula la telemetría de Datadog con etiquetas para nombre de servicio, entorno de despliegue y versión de servicio. La aplicación debe establecer estas etiquetas utilizando las convenciones semánticas de OpenTelemetry: service.name, deployment.environment y service.version.

Paso 4 - Configurar el registrador para tu aplicación

Un diagrama con el host, contenedor o aplicación que envía datos al receptor de log de archivo en el Collector y el Exportador de Datadog en el recopilador que envía los datos al backend de Datadog

Dado que la funcionalidad de registro de los SDKs de OpenTelemetry no es totalmente compatible (consulta tu lenguaje específico en la documentación de OpenTelemetry para más información), Datadog recomienda el uso de una biblioteca de registro estándar para tu aplicación. Sigue la documentación de recopilación de log específica del lenguaje para configurar el registrador adecuado en tu aplicación. Datadog recomienda encarecidamente la configuración de tu biblioteca de registro para la salida de logs en JSON para evitar la necesidad de reglas de parseo personalizadas.

Configurar el receptor de log de archivo

Configura el receptor de log de archivo utilizando operadores. Por ejemplo, si hay un servicio checkoutservice que está escribiendo logs en /var/log/pods/services/checkout/0.log, un ejemplo de log podría tener este aspecto:

{"level":"info","message":"order confirmation email sent to \"jack@example.com\"","service":"checkoutservice","span_id":"197492ff2b4e1c65","timestamp":"2022-10-10T22:17:14.841359661Z","trace_id":"e12c408e028299900d48a9dd29b0dc4c"}

Ejemplo de configuración de log de archivo:

filelog:
   include:
     - /var/log/pods/**/*checkout*/*.log
   start_at: end
   poll_interval: 500ms
   operators:
     - id: parse_log
       type: json_parser
       parse_from: body
     - id: trace
       type: trace_parser
       trace_id:
         parse_from: attributes.trace_id
       span_id:
         parse_from: attributes.span_id
   attributes:
     ddtags: env:staging
  • include: la lista de archivos que el receptor pone en cola
  • start_at: end: indica que se lea el nuevo contenido que se está escribiendo
  • poll_internal: establece la frecuencia de sondeo
  • Operadores:
    • json_parser: analiza los logs JSON. Por defecto, el receptor de log de archivos convierte cada línea de log en un registro de log, que es el body del modelo de datos de logs. A continuación, el json_parser convierte el cuerpo JSON en atributos del modelo de datos.
    • trace_parser: extraiga trace_id y span_id del log para correlacionar logs y trazas en Datadog.

Reasignar el atributo service.name de OTel a service para logs

Para las versiones 0.83.0 y posteriores del Exportador de Datadog, el campo service de logs de OTel se rellena como la convención semántica de OTel service.name. Sin embargo, service.name no es uno de los atributos de servicio predeterminados en el preprocesamiento de logs de Datadog.

Para que el campo service se rellene correctamente en tus logs, puedes especificar que service.name sea la fuente de un servicio de log estableciendo un procesador de reasignación de servicio de log.

Opcional: uso de Kubernetes

Hay varias maneras de desplegar el OpenTelemetry Collector y el Exportador de Datadog en una infraestructura de Kubernetes. Para que el receptor de log de archivo funcione, el despliegue del Agent/DaemonSet es el método de despliegue recomendado.

En entornos contenedorizados, las aplicaciones escriben logs en stdout o stderr. Kubernetes recopila los logs y los escribe en una localización estándar. Es necesario montar la localización en el nodo de host en el Collector para el receptor de log de archivo. A continuación, se muestra un ejemplo de extensión con los montajes necesarios para enviar logs.

apiVersion: apps/v1
metadata:
  name: otel-agent
  labels:
    app: opentelemetry
    component: otel-collector
spec:
  template:
    metadata:
      labels:
        app: opentelemetry
        component: otel-collector
    spec:
      containers:
        - name: collector
          command:
            - "/otelcol-contrib"
            - "--config=/conf/otel-agent-config.yaml"
          image: otel/opentelemetry-collector-contrib:0.71.0
          env:
            - name: POD_IP
              valueFrom:
                fieldRef:
                  fieldPath: status.podIP
            # La k8s.pod.ip se utiliza para asociar pods para k8sattributes
            - name: OTEL_RESOURCE_ATTRIBUTES
              value: "k8s.pod.ip=$(POD_IP)"
          ports:
            - containerPort: 4318 # default port for OpenTelemetry HTTP receiver.
              hostPort: 4318
            - containerPort: 4317 # default port for OpenTelemetry gRPC receiver.
              hostPort: 4317
            - containerPort: 8888 # Default endpoint for querying metrics.
          volumeMounts:
            - name: otel-agent-config-vol
              mountPath: /conf
            - name: varlogpods
              mountPath: /var/log/pods
              readOnly: true
            - name: varlibdockercontainers
              mountPath: /var/lib/docker/containers
              readOnly: true
      volumes:
        - name: otel-agent-config-vol
          configMap:
            name: otel-agent-conf
            items:
              - key: otel-agent-config
                path: otel-agent-config.yaml
        # Montar nodos en la localización de archivos de log.
        - name: varlogpods
          hostPath:
            path: /var/log/pods
        - name: varlibdockercontainers
          hostPath:
            path: /var/lib/docker/containers

Paso 5: Ejecutar el Collector

Ejecuta el Collector, especificando el archivo de configuración mediante el parámetro --config:

otelcontribcol_linux_amd64 --config collector.yaml

Para ejecutar el OpenTelemetry Collector como una imagen de Docker y recibir trazas del mismo host:

  1. Elige una imagen de Docker publicada, como otel/opentelemetry-collector-contrib.

  2. Determina qué puertos abrir en tu contenedor para que las trazas de OpenTelemetry se envíen al OpenTelemetry Collector. Por defecto, las trazas se envían a través de gRPC en el puerto 4317. Si no utilizas gRPC, utiliza el puerto 4318.

  3. Ejecuta el contenedor y expone el puerto necesario, con el archivo collector.yaml previamente definido. Por ejemplo, si estás utilizando el puerto 4317:

    $ docker run \
        -p 4317:4317 \
        --hostname $(hostname) \
        -v $(pwd)/otel_collector_config.yaml:/etc/otelcol-contrib/config.yaml \
        otel/opentelemetry-collector-contrib
    

Para ejecutar el OpenTelemetry Collector como una imagen de Docker y recibir trazas de otros contenedores:

  1. Crea una red de Docker:

    docker network create <NETWORK_NAME>
    
  2. Ejecuta el OpenTelemetry Collector y contenedores de aplicaciones como parte de la misma red.

    # Run the OpenTelemetry Collector
    docker run -d --name opentelemetry-collector \
        --network <NETWORK_NAME> \
        --hostname $(hostname) \
        -v $(pwd)/otel_collector_config.yaml:/etc/otelcol-contrib/config.yaml \
        otel/opentelemetry-collector-contrib
    

    Al ejecutar la aplicación de contenedor, asegúrate de que la variable de entorno OTEL_EXPORTER_OTLP_ENDPOINT está configurada para utilizar el nombre de host apropiado para el OpenTelemetry Collector. En el ejemplo siguiente, se trata de opentelemetry-collector.

    # Run the application container
    docker run -d --name app \
        --network <NETWORK_NAME> \
        --hostname $(hostname) \
        -e OTEL_EXPORTER_OTLP_ENDPOINT=http://opentelemetry-collector:4317 \
        company/app:latest
    

El uso de un DaemonSet es la forma más común y recomendada de configurar la recopilación de OpenTelemetry en un entorno de Kubernetes. Para desplegar el OpenTelemetry Collector y el Exportador de Datadog en una infraestructura de Kubernetes:

  1. Utiliza este ejemplo completo de configuración de OpenTelemetry Collector con el Exportador de Datadog como DaemonSet, incluyendo el ejemplo de configuración de la aplicación.

    Considera algunas opciones esenciales de configuración en el ejemplo, que aseguran que los puertos esenciales del DaemonSet están expuestos y accesibles a tu aplicación:

    # ...
            ports:
            - containerPort: 4318 # default port for OpenTelemetry HTTP receiver.
              hostPort: 4318
            - containerPort: 4317 # default port for OpenTelemetry gRPC receiver.
              hostPort: 4317
            - containerPort: 8888  # Default endpoint for querying Collector observability metrics.
    # ...
    

    Si no necesitas los puertos HTTP estándar y gRPC para tu aplicación, puedes eliminarlos.

  2. Recopila valiosos atributos de Kubernetes, que se utilizan para el etiquetado del contenedor de Datadog, informa la IP del pod como atributo de recurso, como se muestra en el ejemplo:

    # ...
            env:
            - name: POD_IP
              valueFrom:
                fieldRef:
                  fieldPath: status.podIP
            # The k8s.pod.ip is used to associate pods for k8sattributes
            - name: OTEL_RESOURCE_ATTRIBUTES
              value: "k8s.pod.ip=$(POD_IP)"
    # ...
    

    Esto asegura que Kubernetes Attributes Processor que se utiliza en el mapa de configuración es capaz de extraer los metadatos necesarios para adjuntar a trazas. Hay roles adicionales que deben configurarse para permitir el acceso a estos metadatos. El ejemplo está completo, listo para usar, y tiene los roles correctos configurados.

  3. Proporciona tu contenedor de aplicación. Para configurar tu contenedor de aplicación, asegúrate de que se utiliza el nombre de host correcto del endpoint OTLP. El OpenTelemetry Collector se ejecuta como un DaemonSet, por lo que el actual host necesita ser dirigido. Establece tu variable de entorno OTEL_EXPORTER_OTLP_ENDPOINT del contenedor de aplicación correctamente, como en el gráfico de ejemplo:

    # ...
            env:
            - name: HOST_IP
              valueFrom:
                fieldRef:
                  fieldPath: status.hostIP
              # The application SDK must use this environment variable in order to successfully
              # connect to the DaemonSet's collector.
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
              value: "http://$(HOST_IP):4318"
    # ...
    

Para desplegar OpenTelemetry Collector y el Exportador de Datadog en un despliegue de Kubernetes Gateway:

  1. Utiliza este ejemplo completo de configuración de OpenTelemetry Collector con el Exportador de Datadog como DaemonSet, incluyendo el ejemplo de configuración de la aplicación.

    Considera algunas opciones esenciales de configuración en el ejemplo, que aseguran que los puertos esenciales del DaemonSet están expuestos y accesibles a tu aplicación:

    # ...
            ports:
            - containerPort: 4318 # default port for OpenTelemetry HTTP receiver.
              hostPort: 4318
            - containerPort: 4317 # default port for OpenTelemetry gRPC receiver.
              hostPort: 4317
            - containerPort: 8888  # Default endpoint for querying Collector observability metrics.
    # ...
    

    Si no necesitas los puertos HTTP estándar y gRPC para tu aplicación, puedes eliminarlos.

  2. Recopila valiosos atributos de Kubernetes, que se utilizan para el etiquetado del contenedor de Datadog, informa la IP del pod como atributo de recurso, como se muestra en el ejemplo:

    # ...
            env:
            - name: POD_IP
              valueFrom:
                fieldRef:
                  fieldPath: status.podIP
            # The k8s.pod.ip is used to associate pods for k8sattributes
            - name: OTEL_RESOURCE_ATTRIBUTES
              value: "k8s.pod.ip=$(POD_IP)"
    # ...
    

    Esto asegura que Kubernetes Attributes Processor que se utiliza en el mapa de configuración es capaz de extraer los metadatos necesarios para adjuntar a trazas. Hay roles adicionales que deben configurarse para permitir el acceso a estos metadatos. El ejemplo está completo, listo para usar, y tiene los roles correctos configurados.

  3. Proporciona tu contenedor de aplicación. Para configurar tu contenedor de aplicación, asegúrate de que se utiliza el nombre de host correcto del endpoint OTLP. El OpenTelemetry Collector se ejecuta como un DaemonSet, por lo que el actual host necesita ser dirigido. Establece tu variable de entorno OTEL_EXPORTER_OTLP_ENDPOINT del contenedor de aplicación correctamente, como en el gráfico de ejemplo:

    # ...
            env:
            - name: HOST_IP
              valueFrom:
                fieldRef:
                  fieldPath: status.hostIP
              # The application SDK must use this environment variable in order to successfully
              # connect to the DaemonSet's collector.
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
              value: "http://$(HOST_IP):4318"
    # ...
    
  4. Cambia el DaemonSet para incluir un exportador OTLP en lugar del Exportador de Datadog actualmente en su lugar:

    # ...
    exporters:
      otlp:
        endpoint: "<GATEWAY_HOSTNAME>:4317"
    # ...
    
  5. Asegúrate de que los pipelines de servicio utilizan este exportador, en lugar del de Datadog que está en el ejemplo:

    # ...
        service:
          pipelines:
            metrics:
              receivers: [hostmetrics, otlp]
              processors: [resourcedetection, k8sattributes, batch]
              exporters: [otlp]
            traces:
              receivers: [otlp]
              processors: [resourcedetection, k8sattributes, batch]
              exporters: [otlp]
    # ...
    

    Esto garantiza que cada Agent reenvíe sus datos a través del protocolo OTLP a la gateway de Collector.

  6. Sustituye GATEWAY_HOSTNAME por la dirección de tu gateway de OpenTelemetry Collector.

  7. Para garantizar que los metadatos de Kubernetes sigan aplicándose a trazas, indica al procesadork8sattributes que reenvíe la IP del pod a la gateway de Collector para que pueda obtener los metadatos:

    # ...
    k8sattributes:
      passthrough: true
    # ...
    

    Para más información sobre la opción passthrough, lee su documentación.

  8. Asegúrate de que la configuración de la gateway de Collector utiliza la misma configuración del exportador de Datadog que ha sido sustituida por el exportador OTLP en el Agent. Por ejemplo (donde <DD_SITE> es tu sitio, ):

    # ...
    exporters:
      datadog:
        api:
          site: <DD_SITE>
          key: ${env:DD_API_KEY}
    # ...
    

Para utilizar el OpenTelemetry Operator:

  1. Sigue la documentación oficial para desplegar el OpenTelemetry Operator. Como se describe allí, despliega el gestor de certificados, además del Operator.

  2. Configura el Operator utilizando una de las configuraciones estándar de Kubernetes en OpenTelemetry Collector:

    Por ejemplo:

    apiVersion: opentelemetry.io/v1alpha1
    kind: OpenTelemetryCollector
    metadata:
      name: opentelemetry-example
    spec:
      mode: daemonset
      hostNetwork: true
      image: otel/opentelemetry-collector-contrib
      env:
        - name: DD_API_KEY
          valueFrom:
            secretKeyRef:
              key:  datadog_api_key
              name: opentelemetry-example-otelcol-dd-secret
      config:
        receivers:
          otlp:
            protocols:
              grpc:
              http:
        hostmetrics:
          collection_interval: 10s
          scrapers:
            paging:
              metrics:
                system.paging.utilization:
                  enabled: true
            cpu:
              metrics:
                system.cpu.utilization:
                  enabled: true
            disk:
            filesystem:
              metrics:
                system.filesystem.utilization:
                  enabled: true
            load:
            memory:
            network:
        processors:
          k8sattributes:
          batch:
            send_batch_max_size: 100
            send_batch_size: 10
            timeout: 10s
        exporters:
          datadog:
            api:
              key: ${env:DD_API_KEY}
        service:
          pipelines:
            metrics:
              receivers: [hostmetrics, otlp]
              processors: [k8sattributes, batch]
              exporters: [datadog]
            traces:
              receivers: [otlp]
              processors: [k8sattributes, batch]
              exporters: [datadog]
    

Correlación de logs y trazas

Si utilizas el Exportador de Datadog para enviar también trazas de OpenTelemetry a Datadog, utiliza el operador trace_parser para extraer el trace_id de cada traza y añadirlo a los logs asociados. Datadog correlaciona automáticamente los logs y trazas relacionados. Consulta Conectar trazas y logs de OpenTelemetry para obtener más información.

El panel de traza que muestra una lista de logs correlacionados con la traza

Resolución de nombres de host

Consulta Asignación de convenciones semánticas de OpenTelemetry a nombres de host para entender cómo se resuelve el nombre de host.

Limitaciones basadas en el despliegue

El OpenTelemetry Collector tiene dos métodos principales de despliegue: Agent y Gateway. Según tu método de despliegue, algunos componentes no están disponibles.

Modo de despliegueMétricas de hostMétricas de orquestación de KubernetesTrazasAutoingesta de logs
como Gateway
como Agent

Dashboards predefinidos

Datadog proporciona dashboards ‘predefinidos’ que puedes copiar y personalizar. Para utilizar dashboards de OpenTelemetry predefinidos de Datadog:

  1. Instala la integración de OpenTelemetry.

  2. Ve a Dashboards > Dashboards list (Dashboards > Lista de dashboards) y busca opentelemetry:

    La Lista de dashboards, que muestra dos dashboards predefinidos de OpenTelemetry: métricas de host y métricas de Collector.

El dashboard Métricas de host es para los datos recopilados del receptor de métricas de host. El dashboard Métricas de Collector es para cualquier otro tipo de métricas recopiladas, dependiendo de qué receptor de métricas elijas habilitar.

Dashboard de información general de contenedores

El dashboard de Información general de contenedores está en fase beta privada. Rellena este formulario para probarlo.
Esta característica se ve afectada por la obsolescencia de Docker en Kubernetes y es posible que no puedas utilizar dockerstatsreceiver para OpenTelemetry con Kubernetes versión 1.24+.

El receptor de Docker Stats genera métricas de contenedor para OpenTelemetry Collector. El exportador de Datadog traduce las métricas de contenedor a sus homólogos de Datadog.

Utiliza la siguiente configuración para habilitar atributos adicionales en el receptor de Docker Stats que rellena el dashboard de información general de contenedores:

  docker_stats:
    metrics:
      container.network.io.usage.rx_packets:
        enabled: true
      container.network.io.usage.tx_packets:
        enabled: true
      container.cpu.usage.system:
        enabled: true
      container.memory.rss:
        enabled: true
      container.blockio.io_serviced_recursive:
        enabled: true
      container.uptime:
        enabled: true
      container.memory.hierarchical_memory_limit:
        enabled: true

La versión mínima requerida de OpenTelemetry Collector que admite esta función es la v0.78.0.

Referencias adicionales