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.

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,serviceyversion. 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.
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.comy 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:
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-agentDD_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-traceFunciona 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.jsSi la aplicación usa ES modules, la documentación indica --import:
node --import dd-trace/initialize.mjs app.jsCon 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-tracetiene 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:
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.
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.
Cómo leerlo:
- La barra de arriba es la petición entera. Su duración es lo que sintió el usuario.
- 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.
- Spans en secuencia que podrían ir en paralelo son otra señal clásica: tres llamadas independientes, una detrás de otra.
- Muchos spans iguales y cortos (cientos de
SELECTparecidos) indican el problema N+1: una consulta por ítem, en lugar de una consulta para todos. - 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_KEYy elDD_SITEcorrecto. DD_APM_NON_LOCAL_TRAFFIC=truesi la aplicación está en otro contenedor.dd-tracecargado antes que todo (node --require dd-trace/init).DD_ENV,DD_SERVICEyDD_VERSIONen 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#
Sigue leyendo

Infra15 min de lectura
Cómo ahorrar tokens en Claude Code con rtk y graphify

Infra13 min de lectura
Cómo borrar un disco duro o SSD antes de venderlo

Infra8 min de lectura
No subestimes el lock file: npm ci, conflictos y seguridad