Esta guía explica cómo crear una imagen del Datadog Agent con componentes adicionales de OpenTelemetry no incluidos en la imagen por defecto del Datadog Agent. Para ver una lista de los componentes ya incluidos en el Agent por defecto, consulta Componentes incluidos.

Requisitos previos

Para completar esta guía, necesitas lo siguiente:

• Docker
• GitHub y acceso al código fuente del Datadog Agent .
• Los componentes de OpenTelemetry que quieres incluir en el Agent deben ser compatibles con la versión del recopilador de OpenTelemetry integrado.

Recomendado:

• Conocimientos sobre la creación de un recopilador personalizado y OpenTelemetry Collector Builder (OCB).
• Conocimientos básicos del proceso de compilación Go y de los módulos Go.

Descargar el archivo Docker

Descargue la plantilla del archivo Docker:

1. Ve a tu localización de archivos preferida en un terminal. Ejecuta los siguientes comandos para crear una nueva carpeta (por ejemplo, llamada agent-with-otel) y cd en ella.

   mkdir -p agent-with-otel
   cd agent-with-otel
   

2. Descargar el archivo Docker

   curl -o Dockerfile https://raw.githubusercontent.com/DataDog/datadog-agent/refs/tags/7.62.2/Dockerfiles/agent-ot/Dockerfile.agent-otel
   

El archivo Docker:

• Crea una compilación multietapa con Ubuntu 24.04 y datadog/agent:7.62.2-ot-beta-jmx.
• Instala Go, Python y las dependencias necesarias.
• Descarga y descomprime el código fuente del Datadog Agent.
• Crea un entorno virtual e instala los paquetes Python necesarios.
• Crea el Agent OpenTelemetry y copia el binario resultante en la imagen final.

Crear un manifiesto de OpenTelemetry Collector Builder

Crea y personaliza un archivo del manifiesto de OpenTelemetry Collector Builder (OCB), que defina los componentes que se incluirán en tu Datadog Agent personalizado.

1. Descarga el manifiesto por defecto de Datadog:

   curl -o manifest.yaml https://raw.githubusercontent.com/DataDog/datadog-agent/refs/tags/7.62.2/comp/otelcol/collector-contrib/impl/manifest.yaml
   

2. Abre el archivo manifest.yaml y añade los componentes adicionales de OpenTelemetry a las secciones correspondientes (extensiones, exportadores, procesadores, receptores o conectores). La línea resaltada en este ejemplo añade un procesador de transformación de métricas:

   dist:
     módulo: github.com/DataDog/comp/otelcol/collector-contrib
     nombre: otelcol-contrib
     descripción: Datadog OpenTelemetry Collector
     versión: 0.115.0
     output_path: ./comp/otelcol/collector-contrib/impl
     otelcol_version: 0.115.0
   
   extensions:
   # Verás una lista de extensiones ya incluidas por Datadog
   # Añadir aquí las extensiones elegidas
   
   exporters:
   # Verá una lista de exportadores ya incluidos por Datadog
   # Añadir aquí los exportadores elegidos
   
   procesadores:
   # añadir el procesador de transformación de métricas para modificar métricas
     - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/metricstransformprocessor v0.115.0
   
   receivers:
     - gomod: go.opentelemetry.io/collector/receiver/nopreceiver v0.115.0
     - gomod: go.opentelemetry.io/collector/receiver/otlpreceiver v0.115.0
     - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/receiver/filelogreceiver v0.115.0
     - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/receiver/fluentforwardreceiver v0.115.0
     - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/receiver/hostmetricsreceiver v0.115.0
     - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/receiver/jaegerreceiver v0.115.0
     - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/receiver/prometheusreceiver v0.115.0
     - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/receiver/receivercreator v0.115.0
     - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/receiver/zipkinreceiver v0.115.0
   
   conectores:
   # Verás una lista de conectores ya incluidos por Datadog
   # Añadir aquí los conectores elegidos

3. Guarda los cambios en el archivo del manifiesto.

Crear y enviar la imagen del Agent

Crea tu imagen personalizada del Datadog Agent y envíala a un registro de contenedor.

1. Crea la imagen con Docker:

   docker build . -t agent-otel --no-cache \
     --build-arg AGENT_VERSION="7.62.2-ot-beta-jmx" \
     --build-arg AGENT_BRANCH="7.62.x"
   

2. Etiquetar y enviar la imagen:

   docker tag agent-otel <IMAGE-NAME>/<IMAGE-TAG>
   docker push <IMAGE-NAME>/<IMAGE-TAG>
   

   Sustituye <IMAGE-NAME> y <IMAGE-TAG> por el nombre y la etiqueta de tu imagen. Si el repositorio de destino no es Docker Hub, tendrás que incluir el nombre del repositorio.
3. Para instalar una tabla de Helm, establece la etiqueta de la imagen en tu archivo de valores:

   datadog-values.yaml

   Copy

   agents:
     image:
       repository: <YOUR-REPO>
       tag: <IMAGE-TAG>
       doNotCheckTag: true
      

   Sustituye <YOUR-REPO> y <IMAGE-TAG> por el nombre de tu repositorio y la imagen deseada etiquetar.

Testear y validar

Crea un archivo de configuración de ejemplo y ejecuta tu Agent personalizado para asegurarte de que todo funciona correctamente.

1. Crea un archivo de configuración de ejemplo de OpenTelemetry con los componentes adicionales. El siguiente ejemplo configura un procesador de transformación de métricas adicional:

   receivers:
     otlp:
       protocols:
         http:
           endpoint: "0.0.0.0:4318"
         grpc:
           endpoint: "0.0.0.0:4317"
   
   processors:
     batch:
       send_batch_max_size: 1000
       send_batch_size: 100
       timeout: 10s
     # Rename system.cpu.usage to system.cpu.usage_time
     metricstransform:
       transforms:
         - include: system.cpu.usage
           action: update
           new_name: system.cpu.usage_time
   
   exporters:
     datadog:
       api:
         site: ${env:DD_SITE}
         key: ${env:DD_API_KEY}
   
   connectors:
       datadog/connector:
           traces:
             compute_top_level_by_span_kind: true
             peer_tags_aggregation: true
             compute_stats_by_span_kind: true
   
   service:
     pipelines:
       metrics:
         receivers: [otlp, datadog/connector]
         processors: [metricstransform, batch]
         exporters: [datadog]
       traces:
         receivers: [otlp]
         processors: [batch]
         exporters: [datadog/connector]
       traces/2:
         receivers: [datadog/connector]
         processors: [batch]
         exporters: [datadog]
       logs:
         receivers: [otlp]
         processors: [batch]
         exporters: [datadog]
   

2. Ejecuta el Agent con el siguiente comando de Docker.

   docker run -it \
     -e DD_API_KEY=XX \
     -e DD_SITE=datadoghq.com \
     -e DD_HOSTNAME=datadog \
     -v $(pwd)/config.yaml:/config.yaml \
     -p 4317:4317 \
     -p 4318:4318 \
     --entrypoint otel-agent \
     agent-otel --config /config.yaml
   

3. El inicio del Agent indica que el proceso de compilación fue correcto.

Ahora puedes utilizar esta nueva imagen para instalar el Agent. Esto activa las capacidades de monitorización de Datadog junto con los componentes adicionales de OpenTelemetry que añadiste.

Para obtener instrucciones detalladas sobre la instalación y configuración del Agent con componentes de OpenTelemetry añadidos, consulta la guía Instalar el Datadog Agent con el OpenTelemetry Collector integrado.

Resolución de problemas

En esta sección, se tratan algunos de los problemas más comunes que pueden surgir durante la compilación y ejecución del Datadog Agent, junto con sus soluciones:

Problemas de compatibilidad con awscontainerinsightreceiver

Problema: es posible que se produzcan errores relacionados con awscontainerinsightreceiver durante la compilación:

#0 0.879 go: downloading github.com/tidwall/gjson v1.17.1
#0 0.889 go: downloading code.cloudfoundry.org/go-diodes v0.0.0-20240604201846-c756bfed2ed3
#0 0.916 go: downloading github.com/hashicorp/go-retryablehttp v0.7.5
#0 0.940 go: downloading github.com/tidwall/pretty v1.2.1
#0 88.24 # github.com/opencontainers/runc/libcontainer/cgroups/ebpf
#0 88.24 /go/pkg/mod/github.com/opencontainers/runc@v1.1.12/libcontainer/cgroups/ebpf/ebpf_linux.go:190:3: unknown field Replace in struct literal of type link.RawAttachProgramOptions
#0 89.14 # github.com/open-telemetry/opentelemetry-collector-contrib/receiver/awscontainerinsightreceiver/internal/k8sapiserver
#0 89.14 /go/pkg/mod/github.com/open-telemetry/opentelemetry-collector-contrib/receiver/awscontainerinsightreceiver@v0.115.0/internal/k8sapiserver/k8sapiserver.go:47:68: undefined: record.EventRecorderLogger
------

Solución: elimina awscontainerinsightreceiver del archivo manifest.yaml. Este receptor tiene bibliotecas incompatibles y no se puede incluir en la compilación.

Errores en el proceso de compilación

Problema: recibes el siguiente error:

ERROR: failed to solve: process "/bin/sh -c . venv/bin/activate && invoke otel-agent.build" did not complete successfully: chown /var/lib/docker/overlay2/r75bx8o94uz6t7yr3ae6gop0b/work/work: no such file or directory

Solución: vuelve a ejecutar el comando de compilación:

docker build . -t agent-otel --no-cache

Espacio en disco insuficiente

Problema: Puedes encontrarte con errores relacionados con la insuficiencia de espacio en el disco, como:

no space left on device

Solución: Libera espacio de Docker:

docker system prune -a

Referencias adicionales

Más enlaces, artículos y documentación útiles:

Uso de componentes personalizados de OpenTelemetry con el Datadog AgentDOCUMENTATION