Todos los artículos

Infra12 min de lectura

Datadog desde cero: cómo integrarlo y cómo leer el panel

Guía de Datadog para principiantes: el Agent, dd-trace en una API Node.js, tags de servicio, logs ligados a los traces, cómo leer la latencia p95, traces y monitores.

También en Português, English, Français

Tuve que estudiar Datadog, y la primera vez que abrí el panel me asusté: gráficos de todo tipo, siglas por todas partes y ninguna idea de por dónde empezar.

Este post es la guía que me habría gustado leer aquel día. Cubre las dos mitades del trabajo: meter los datos (el Agent y la librería en tu aplicación) y entender lo que aparece en pantalla (latencia, errores, traces, logs y alertas).

Un aviso honesto: los ejemplos de código siguen la documentación oficial de Datadog, enlazada en cada parte, y no los ejecuté contra una cuenta. Las imágenes de las pantallas son ilustraciones que dibujé para explicar cada parte, no capturas de Datadog. El producto cambia de aspecto a menudo, pero los conceptos son los mismos.

TL;DR#

  • Datadog junta tres tipos de dato: métricas (números a lo largo del tiempo), logs (eventos en texto) y traces (el camino de una petición). Lo que une a los tres son las tags.
  • El Agent corre al lado de tu aplicación (en un contenedor, por ejemplo), recibe los datos y los manda a Datadog. Tu aplicación habla con el Agent, no con internet.
  • En una API Node.js, el APM entra con dd-trace, cargado antes que todo lo demás: node --require dd-trace/init app.js.
  • Tres tags valen oro: env, service y version. Con ellas puedes filtrar todo por entorno y comparar un deploy con el anterior.
  • En el panel de un servicio, lee tres números: peticiones, errores y latencia. Y la latencia se lee en p95 y p99, no en promedio.
  • Un trace muestra dónde se fue el tiempo. El span más ancho es el primer sospechoso.
  • Cuidado con el costo: demasiados logs, tags con muchos valores (como un id de usuario) en métricas personalizadas y traces sin muestreo salen caros.

Las tres piezas: métricas, logs y traces#

Antes de cualquier configuración, conviene separar qué es cada cosa:

  • Métricas son números a lo largo del tiempo: uso de CPU, peticiones por segundo, tamaño de cola. Son baratas de guardar y buenas para gráficos y alertas.
  • Logs son eventos en texto (mejor en JSON) que escribe tu aplicación: "pedido 123 creado", "fallo al llamar a la pasarela de pago".
  • Traces cuentan la historia de una petición: entró al endpoint, consultó la base de datos, llamó a otra API, respondió. Cada etapa es un span, con inicio, fin y duración.

Lo que hace que Datadog valga la pena es la conexión entre los tres. Ves un pico de latencia en el gráfico, haces clic, caes en los traces de ese momento, abres un trace lento y, desde dentro, ves los logs que escribió esa petición. Esto solo funciona si los tres llegan con las mismas tags.

La arquitectura: tu aplicación habla con el Agent#

El Datadog Agent es un programa que corre cerca de tu aplicación: en el mismo servidor, como contenedor junto a los tuyos o como DaemonSet en Kubernetes. Él:

  • recoge métricas del host y de los contenedores;
  • recibe los traces que envía tu aplicación (puerto 8126, TCP);
  • recibe métricas personalizadas por el protocolo DogStatsD (puerto 8125, UDP);
  • lee los logs de los contenedores;
  • y lo manda todo a Datadog, con tu API key.
La aplicación no habla con internet: lo manda todo al Agent, y el Agent lo manda a Datadog

Dos configuraciones aparecen en todas partes:

  • DD_API_KEY: la clave de tu organización. Va solo en el Agent, nunca en el código de la aplicación.
  • DD_SITE: en qué región está tu cuenta (datadoghq.com, datadoghq.eu, us5.datadoghq.com y otras). Si el site está mal, los datos simplemente no aparecen.

Integrando una API Node.js#

1. El Agent en un contenedor#

Con Docker Compose, el Agent queda al lado de la API. Las variables de abajo activan el APM, la recolección de logs de los contenedores y DogStatsD:

docker-compose.yml
services:
  datadog-agent:
    image: registry.datadoghq.com/agent:7
    environment:
      - DD_API_KEY=${DD_API_KEY}
      - DD_SITE=datadoghq.com
      - DD_APM_ENABLED=true
      - DD_APM_NON_LOCAL_TRAFFIC=true        # accept traces from other containers
      - DD_LOGS_ENABLED=true
      - DD_LOGS_CONFIG_CONTAINER_COLLECT_ALL=true
      - DD_DOGSTATSD_NON_LOCAL_TRAFFIC=true  # accept custom metrics from other containers
      - DD_CONTAINER_EXCLUDE=name:datadog-agent
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /var/lib/docker/containers:/var/lib/docker/containers:ro
      - /proc/:/host/proc/:ro
      - /sys/fs/cgroup/:/host/sys/fs/cgroup:ro
 
  api:
    build: .
    environment:
      - DD_AGENT_HOST=datadog-agent          # where to send traces and metrics
      - DD_ENV=staging
      - DD_SERVICE=orders-api
      - DD_VERSION=1.4.2
      - DD_LOGS_INJECTION=true
    depends_on:
      - datadog-agent

DD_APM_NON_LOCAL_TRAFFIC=true es el detalle que más gente tumba: por defecto, el Agent solo acepta traces de su propia máquina. Con la API en otro contenedor y sin esta variable, los traces nunca llegan.

2. dd-trace en la aplicación#

El APM de Node.js es la librería dd-trace:

npm install dd-trace

Funciona interceptando los require de la aplicación para instrumentar Express, pg, http y otras librerías por su cuenta. Por eso tiene que cargarse antes que todo. La forma más segura es por línea de comandos, sin tocar el código:

node --require dd-trace/init app.js

Si la aplicación usa ES modules, la documentación indica --import:

node --import dd-trace/initialize.mjs app.js

Con eso, cada petición HTTP ya se convierte en un trace, con spans de las consultas a la base de datos y de las llamadas a otras APIs, sin una sola línea de código de instrumentación.

3. Las tres tags que lo unen todo#

Datadog lo llama unified service tagging: tres tags reservadas, iguales en métricas, logs y traces.

  • env: el entorno (production, staging).
  • service: el nombre del servicio (orders-api).
  • version: la versión del código. Debe cambiar en cada deploy: con ella Datadog compara la versión nueva con la anterior y muestra si el deploy empeoró la latencia o los errores.

En la aplicación, vienen de las variables DD_ENV, DD_SERVICE y DD_VERSION, como en el docker-compose.yml de arriba. Una buena práctica es usar el hash del commit o la tag del release como versión.

4. Logs ligados a los traces#

Con DD_LOGS_INJECTION=true, dd-trace añade el id del trace y del span en cada línea de log. Así, desde un trace ves los logs de esa petición, y desde un log abres el trace.

Dos cuidados:

  • Solo funciona con logs en JSON. Usa un logger como Winston, Pino o Bunyan configurado para JSON.
  • dd-trace tiene que cargarse antes que el logger, otra vez.

Una línea de log queda con este formato (el de la documentación, con los nombres de nuestro ejemplo):

{"dd":{"service":"orders-api","trace_id":"68c2114800000000669b6b6b2aaf59c9","span_id":"8985025821692657638","version":"1.4.2"},"level":"info","message":"order created"}

5. Métricas personalizadas (con cuidado)#

Para contar cosas de tu negocio, como pedidos creados, puedes mandar métricas por DogStatsD, que el Agent recibe en el puerto 8125:

orders.js
const tracer = require('dd-trace')
 
function onOrderCreated(order) {
  // Counts orders. Tags with few possible values only: never an order or user id.
  tracer.dogstatsd.increment('orders.created', 1, { payment_method: order.paymentMethod })
}

El comentario del código es lo más importante: cada combinación de valores de tag se convierte en una serie aparte, y las métricas personalizadas se cobran por serie. Una tag payment_method con tres valores genera tres series. Una tag user_id con 100 mil usuarios genera 100 mil.

Leyendo el panel de un servicio#

Con los datos llegando, la primera pantalla que hay que abrir es la del servicio (en APM, Services, haz clic en el tuyo). Parece llena, pero lo esencial cabe en tres gráficos, el famoso RED: Requests, Errors y Duration.

Ilustración, no es una captura: lo esencial de la página de un servicio son tres gráficos y la lista de endpoints

Peticiones#

Cuántas peticiones por segundo recibe el servicio. Solo, este gráfico dice poco. Sirve de contexto para los otros dos: ¿la latencia subió junto con el tráfico? Entonces puede ser falta de capacidad. ¿Subió con el tráfico quieto? Entonces algo cambió en el código o en una dependencia.

Errores#

El número de errores y, más útil, la tasa de error: el porcentaje de peticiones que fallaron. 50 errores por minuto en un servicio con 10 mil peticiones es el 0,5%. En un servicio con 100 peticiones, es la mitad de todo.

Latencia: por qué p95 y no el promedio#

La latencia aparece en percentiles: p50, p75, p90, p95, p99 y el máximo. Un ejemplo para entenderlo (números inventados):

  • 100 peticiones: 95 tardan 80 ms, 5 tardan 3 segundos.
  • El promedio da unos 230 ms. Parece solo "un poco lento", y no describe a nadie: ninguna petición tardó 230 ms.
  • El p50 (la mediana) es 80 ms: la petición típica va genial.
  • El p99 es 3 segundos: hay gente esperando tres segundos.

El promedio esconde justo a quien está sufriendo. Por eso:

  • p50 muestra la experiencia típica;
  • p95 y p99 muestran la cola, los usuarios que más esperan (y muchas veces son los más importantes, como quien tiene el carrito más grande);
  • las alertas de latencia suelen usar p95 o p99.

La lista de recursos#

Debajo de los gráficos está la lista de recursos: cada endpoint (GET /orders/:id, POST /orders) con sus propias peticiones, latencia y tasa de error. Ahí descubres qué endpoint tiró del gráfico hacia arriba. Ordena por latencia p95 o por tasa de error y empieza por arriba.

Leyendo un trace#

Haciendo clic en un punto del gráfico o en un recurso, llegas a los traces. Abre uno de los lentos. Aparece como un flame graph: barras horizontales, una por span, con el ancho proporcional al tiempo.

Ilustración: el span más ancho muestra a dónde se fue el tiempo

Cómo leerlo:

  1. La barra de arriba es la petición entera. Su duración es lo que sintió el usuario.
  2. Busca el span más ancho. En el ejemplo, la llamada a la pasarela de pago tarda 1,6 de los 1,8 segundos. Optimizar la consulta a la base de datos, de 40 ms, casi no cambiaría nada.
  3. Spans en secuencia que podrían ir en paralelo son otra señal clásica: tres llamadas independientes, una detrás de otra.
  4. Muchos spans iguales y cortos (cientos de SELECT parecidos) indican el problema N+1: una consulta por ítem, en lugar de una consulta para todos.
  5. Abre las pestañas del span: los logs de la petición (si la inyección está activa), las tags y, en los spans con error, el mensaje y el stack.

Buscando en los logs#

El Log Explorer tiene su propia sintaxis de búsqueda. Las que más uso:

service:orders-api status:error
service:orders-api @http.status_code:[500 TO 599]
env:production "payment declined"
service:orders-api -@http.status_code:404
  • Sin @ buscas por tag (service, env, status, host).
  • Con @ buscas por un atributo del JSON del log (@http.status_code, @order.id).
  • Entre comillas es una búsqueda por el texto del mensaje.
  • El - delante excluye.

Un consejo: la búsqueda por atributo distingue mayúsculas de minúsculas. La búsqueda por texto, no.

Monitores: enterarte antes que el usuario#

Un monitor es una alerta. El más útil para empezar es uno por servicio, mirando las mismas señales de la página del servicio:

  • tasa de error por encima de un límite (por ejemplo, 2% durante 5 minutos);
  • latencia p95 o p99 por encima de lo que el usuario tolera;
  • ausencia de datos: el servicio dejó de mandar peticiones. A veces se cayó de una forma que no genera ningún error, solo silencio.

Cada monitor tiene un nivel de aviso (warning) y uno de alerta, y un mensaje con el destino de la notificación, como un canal de Slack. Escribe el mensaje pensando en quien lo va a leer a las tres de la mañana: qué se rompió, el enlace al panel y el primer paso para investigar.

Empieza con pocos. Una alerta que salta a cada rato se vuelve ruido, y el ruido se ignora justo el día en que importa.

Cuidado con el costo#

Datadog cobra por varias cosas distintas, y es fácil asustarse con la factura. Los tres villanos clásicos:

  • Logs: se cobran por el volumen que entra y por lo que queda indexado. Logs de debug en producción, o un log por ítem dentro de un bucle, disparan el volumen. Puedes filtrar en el Agent o en pipelines antes de indexar.
  • Métricas personalizadas con muchos valores de tag: como en el ejemplo de user_id, cada combinación se convierte en una serie cobrada.
  • Traces: en un servicio con mucho tráfico, guardar el 100% de los traces sale caro y casi nunca hace falta. Configura el muestreo.

Los precios cambian y dependen del contrato, así que revisa la página de precios de Datadog en lugar de fiarte de un número de blog.

Checklist#

  • Agent corriendo con DD_API_KEY y el DD_SITE correcto.
  • DD_APM_NON_LOCAL_TRAFFIC=true si la aplicación está en otro contenedor.
  • dd-trace cargado antes que todo (node --require dd-trace/init).
  • DD_ENV, DD_SERVICE y DD_VERSION en cada servicio, con la versión cambiando en cada deploy.
  • Logs en JSON con DD_LOGS_INJECTION=true.
  • Métricas personalizadas solo con tags de pocos valores.
  • Página del servicio: peticiones, tasa de error, p95 y p99, y la lista de recursos.
  • Trace: empieza por el span más ancho.
  • Monitores de tasa de error, latencia y ausencia de datos, con un mensaje útil.
  • Un ojo en la factura: volumen de logs, series de métricas y muestreo de traces.

Referencias#

  • Infra
  • datadog
  • observabilidad
  • apm
  • node.js
  • docker
  • logs

Escrito por

Ingeniera de software y diseñadora. Escribo sobre lo que encuentro construyendo apps, APIs y productos.