Empezando con OpenTelemetry en Datadog

Información general

OpenTelemetry es un marco de observabilidad de código abierto que proporciona a los equipos de TI protocolos y herramientas estandarizados para recopilar y enrutar datos de observabilidad de aplicaciones de software. OpenTelemetry proporciona un formato coherente para instrumentar, generar, recopilar y exportar datos de observabilidad de aplicaciones —a saber, métricas, logs y trazas (traces)— a plataformas de monitorización para el análisis y entendimiento.

Esta guía demuestra cómo configurar un ejemplo de aplicación OpenTelemetry para enviar datos de observabilidad a Datadog utilizando el SDK de OpenTelemetry, OpenTelemetry Collector, y Datadog Exporter. Esta guía también muestra cómo explorar estos datos en la interfaz de usuario Datadog.

Sigue esta guía para:

  1. Instrumentar la aplicación con la API OpenTelemetry.
  2. Configurar la aplicación para enviar datos de observabilidad a Datadog.
  3. Correlacionar datos de observabilidad con servicio unificado etiquetado.
  4. Ejecutar la aplicación para generar datos de observabilidad.
  5. Explorar datos de observabilidad en la interfaz de usuario Datadog.

Requisitos previos

Para completar esta guía, necesitas lo siguiente:

  1. Crea una cuenta en Datadog si aún no lo has hecho.
  2. Configura tu clave de API de Datadog: a. Busca o crea tu clave de API de Datadog.
    b. Exporta tu clave de API de Datadog a una variable entorno:
    exportar DD_API_KEY=<Tu clave de API>
  3. Obtén la aplicación Calendario de muestra.
    a. Clona el repositorio opentelemetry-examples en tu dispositivo:
    git clone https://github.com/DataDog/opentelemetry-examples.git
    b. Navega hasta el directorio /calendar:
    cd opentelemetry-examples/apps/rest-services/java/calendar
  4. Instalar Docker Compose.
  5. (Opcional) Utiliza Linux para enviar métricas de infraestructura.

La aplicación Calendario utiliza herramientas de OpenTelemetry para generar y recopilar métricas, logs, y trazas (traces). Los siguientes pasos explican cómo obtener estos datos de observabilidad en Datadog.

Instrumentación de la aplicación

La aplicación de muestra de Calendario ya está parcialmente instrumentada:

  1. Ve al archivo principal CalendarController.java ubicado en: ./src/main/java/com/otel/controller/CalendarController.java.

  2. El siguiente código instrumenta getDate() utilizando la API de OpenTelemetry:

    CalendarController.java

    Cadena privada getDate() {
      tramo (span) tramo (span) = GlobalOpenTelemetry.getTracer("calendar").spanBuilder("getDate").startSpan();
      Prueba (contexto contexto = tramo (span).makeCurrent()) {
       ...
      } finalmente {
        tramo (span).end();
      }
    }

Cuando se ejecuta la aplicación Calendario, la llamada a getDate() genera trazas (traces) y tramos (spans).

Configurar la aplicación

Receptor de OTLP

La aplicación Calendario ya está configurada para enviar datos desde el SDK de OpenTelemetry al Receptor del Protocolo de OpenTelemetry (OTLP) en OpenTelemetry Collector.

  1. Vaya al archivo de configuración de Collector situado en: ./src/main/resources/otelcol-config.yaml.

  2. Las siguientes líneas configuran el receptor de OTLP para recibir métricas, trazas (traces) y logs:

    otelcol-config.yaml

    receptores:
      otlp:
        protocolos:
          grpc:
            endpoint: 0.0.0.0:4317
          http:
            endpoint: 0.0.0.0:4318
    ...
    servicio:
      tuberías:
        trazas (traces):
          receptores: [otlp]
        métricas:
          receptores: [otlp]
        logs:
          receptores: [otlp]

Datadog Exporter

El Datadog Exporter envía los datos recogidos por el receptor de OTLP al backend de Datadog.

  1. Ve al archivo otelcol-config.yaml.

  2. Las siguientes líneas configuran el Datadog Exporter para enviar datos de observabilidad a Datadog:

    otelcol-config.yaml

    exportadores:
      Datadog:
        trazas (traces):
          span_name_as_resource_name: verdadero
          trace_buffer: 500
        nombre de host: "otelcol-Docker"
        api:
          clave: ${DD_API_KEY}
          sitio: datadoghq.com
    
    conectores:
       Datadog/conector:
    
    servicio:
      tuberías:
        métricas:
          receptores: [otlp, Datadog/connector] # <- actualizar esta línea
          exportadores: [Datadog]
       trazas (traces):
          exportadores: [Datadog, Datadog/conector]
       logs:
          exportadores: [Datadog]
  3. Establece exporters.datadog.api.site en tu sitio de Datadog. De lo contrario, por defecto es US1.

Esta configuración permite a Datadog Exporter enviar métricas, trazas (traces), y logs de tiempo de ejecución a Datadog. Sin embargo, el envío de métricas de infraestructura requiere configuración adicional.

OpenTelemetry Collector

En este ejemplo, configura tu OpenTelemetry Collector para enviar métricas de infraestructura .

Para enviar métricas de infraestructura desde OpenTelemetry Collector a Datadog, debes utilizar Linux. Se trata de una limitación del receptor Docker Stats.

Para recopilar métricas de contenedor, configura el Docker receptor de estadísticas en tu Datadog Exportador:

  1. Añade un bloque de docker_stats a la sección receivers de otel-config.yaml:

    otelcol-config.yaml

    receptores:
          otlp:
            protocolos:
              grpc:
                endpoint: 0.0.0.0:4317
              http:
                endpoint: 0.0.0.0:4318
          # añadir el siguiente bloque
          docker_stats: 
            endpoint: unix:///var/run/Docker.sock # por defecto; si esta no es la ruta del socket Docker, actualiza a la ruta correcta.
           métricas:
             container.network.io.usage.rx_packets:
                habilitado: verdadero
             container.network.io.usage.tx_packets:
                habilitado: verdadero
             container.cpu.usage.system:
                habilitado: verdadero
             container.memory.rss
                habilitado: verdadero
             container.blockio.io_serviced_recursive
                habilitado: verdadero
             container.uptime
                habilitado: verdadero
             container.memory.hierarchical_memory_limit
                habilitado: verdadero
  2. Actualiza service.pipelines.metrics.receivers para incluir docker_stats:

    otelcol-config.yaml

    servicio:
      tuberías:
        métricas:
          receptores: [otlp, Datadog/connector, docker_stats] # <- actualiza esta línea

Esta configuración permite a la aplicación Calendario enviar las métricas del contenedor a Datadog para que lo explores en Datadog.

Envío de datos de observabilidad con OTLP

La aplicación Calendario utiliza el exportador de registro OpenTelemetry en su configuración de Logback para enviar logs con OpenTelemetry Layer Processor (OTLP).

  1. Ve al archivo de configuración Logback XML de la aplicación Calendario en /src/main/resources/logback.xml.

  2. Las siguientes líneas definen el appender OpenTelemetry:

    logback.xml

    <appender name="OpenTelemetry" class="io.opentelemetry.instrumentation.logback.appender.v1_0.OpenTelemetryAppender">
        <immediateFlush>verdadero</immediateFlush>
        <captureExperimentalAttributes>verdadero</captureExperimentalAttributes>
        <captureKeyValuePairAttributes>verdadero</captureKeyValuePairAttributes>
      </appender>
  3. La línea <appender-ref ref="OpenTelemetry"/> hace referencia al appender OpenTelemetry en la configuración de nivel de raíz:

    logback.xml

    <root level="INFO">
      <appender-ref ref="console"/>
      <appender-ref ref="OpenTelemetry"/>
    </root>

Además, las variables del entorno configuran el entorno de OpenTelemetry para exportar logs, métricas, y trazas (traces):

  1. Ve al archivo Docker Compose de la aplicación Calendario en ./deploys/docker/docker-compose-otel.yml.
  2. La configuración OTEL_LOGS_EXPORTER=otlp permite enviar los logs con OTLP.
  3. La configuración OTEL_EXPORTER_OTLP_ENDPOINT=http://otelcol:4317 permite enviar las métricas y trazas (traces) con OTLP.

Correlación de los datos de observabilidad

Etiquetado de servicio unificado vincula los datos de observabilidad en Datadog para que puedas navegar por métricas, trazas (traces) y logs con etiquetas (tags) coherentes.

La aplicación Calendario ya está configurada con etiquetado de servicio unificado:

  1. Ve al archivo Docker Compose de la aplicación Calendario en ./deploys/docker/docker-compose-otel.yml.

  2. Las siguientes líneas permiten la correlación entre las trazas (traces) de la aplicación y otros datos de observabilidad:

    docker-compose-otel.yml

    entorno:
      - OTEL_SERVICE_NAME=calendar-otel
      - OTEL_RESOURCE_ATTRIBUTES=deployment.environment=docker,host.name=otelcol-docker

Ejecutar la aplicación

Para empezar a generar y enviar datos de observabilidad a Datadog, es necesario ejecutar la aplicación Calendario con el SDK de OpenTelemetry:

  1. Ejecuta la aplicación desde la carpeta calendar/:

    docker compose -f deploys/docker/docker-compose-otel.yml up
    Este comando crea un contenedor de Docker con el OpenTelemetry Collector y el servicio de Calendario.

  2. Para probar que la aplicación Calendario se ejecuta correctamente, ejecuta el siguiente comando desde otra ventana de terminal:

    curl localhost:9090/calendar 
  3. Comprueba que recibes una respuesta tal como:

    {"date":"2022-12-30"}
  4. Ejecuta el comando curl varias veces para asegurarte de que al menos una traza (trace) exporta al backend de Datadog.

    La aplicación Calendario utiliza el procesador de muestreo probabilístico, por lo que solo el 30 % de las trazas (traces) enviadas a través de la aplicación llegan al backend de destino.

Cada llamada a la aplicación Calendario resulta en métricas, trazas (traces) y logs que son reenviados al OpenTelemetry Collector, luego al Datadog Exporter y finalmente al backend de Datadog.

Exploración de los datos de observabilidad en Datadog

Utiliza la interfaz de usuario de Datadog para explorar los datos de observabilidad de la aplicación Calendario.

Nota: Los datos de tu traza (trace) pueden tardar unos minutos en aparecer.

Tiempo de ejecución y métricas de infraestructura

Ve el tiempo de ejecución y métricas de infraestructura para visualizar, monitorear, y medir el rendimiento de tus aplicaciones, hosts, contenedores y procesos.

  1. Ve a APM > Catálogo de servicio.

  2. Pasa el ratón por encima del servicio calendar-otel y selecciona Página completa.

  3. Desplázate hasta el panel inferior y selecciona:

    • **Métricas de infraestructura ** para ver tus métricas de contenedor de Docker, como el uso de CPU y memoria.
    • Métricas JVM para ver las métricas del tiempo de ejecución, como el uso de heap y el recuento de hilos.
    Ver las métricas de infraestructura y del tiempo de ejecución de JVM para la aplicación Calendario

Google

Consulta los logs para monitorear y solucionar problemas de funcionamiento de la aplicación y el sistema.

  1. Ve a logs.
  2. Si tienes otros logs en la lista, añade @service.name:calendar-otel al campo Buscar para para ver solo los logs desde la aplicación Calendario.
  3. Selecciona un log desde la lista para ver más detalles.
Ver logs para la aplicación Calendario

Trazas (traces)

Consulta las trazas (traces) y los tramos (spans) para observar el estado y el rendimiento de las solicitudes que tu aplicación procesó.

  1. Ve a APM > trazas (traces).

  2. Busca la sección servicio en el menú de filtros y selecciona la faceta calendar-otel para visualizar todas las trazas (traces) calendar-otel:

    Ver las trazas (traces) para la aplicación Calendario
  3. Explora tus trazas (traces) de calendar-otel.

    Para empezar, haz clic en una traza (trace) para abrir el panel lateral de la traza (trace) y encontrar más detalles sobre la traza (trace) y sus tramos (spans). Por ejemplo, el Gráfico de llamas captura cuánto tiempo se empleó en cada componente de la ruta de ejecución del Calendario:

    Ver el Gráfico de llamas para una traza (trace) de la aplicación Calendario
  4. Observa que puedes seleccionar infraestructura, métricas o logs en el panel inferior para correlacionar tu traza (trace) con otros datos de observabilidad.

    Correlacionar una traza (trace) de la aplicación Calendario con logs

Leer más