Infra11 min de leitura
Datadog do zero: como integrar e como ler o painel
Guia de Datadog pra quem está começando: o Agent, o dd-trace numa API Node.js, tags de serviço, logs ligados aos traces, como ler latência p95, traces e monitores.

Precisei estudar Datadog, e a primeira vez que abri o painel foi um susto: gráfico de tudo que é jeito, siglas por todo lado, e nenhuma ideia de por onde começar.
Este post é o guia que eu queria ter lido naquele dia. Ele cobre as duas metades do trabalho: colocar os dados lá dentro (o Agent e a biblioteca na sua aplicação) e entender o que aparece na tela (latência, erros, traces, logs e alertas).
Um aviso honesto: os exemplos de código seguem a documentação oficial do Datadog, linkada em cada parte, e eu não rodei eles contra uma conta. As imagens das telas são ilustrações que eu desenhei pra explicar cada parte, não prints do Datadog. O produto muda de visual com frequência, mas os conceitos são os mesmos.
TL;DR#
- Datadog junta três tipos de dado: métricas (números ao longo do tempo), logs (eventos em texto) e traces (o caminho de uma requisição). O que liga os três são as tags.
- O Agent roda do lado da sua aplicação (num container, por exemplo), recebe os dados e manda pro Datadog. Sua aplicação fala com o Agent, não com a internet.
- Numa API Node.js, o APM entra com o
dd-trace, carregado antes de todo o resto:node --require dd-trace/init app.js. - Três tags valem ouro:
env,serviceeversion. Com elas, dá pra filtrar tudo por ambiente e comparar um deploy com o anterior. - No painel de um serviço, leia três números: requisições, erros e latência. E latência se lê em p95 e p99, não em média.
- Um trace mostra onde o tempo foi gasto. O span mais largo é o primeiro suspeito.
- Cuidado com o custo: log demais, tag com muitos valores (como id de usuário) em métrica customizada e trace sem amostragem saem caro.
As três peças: métricas, logs e traces#
Antes de qualquer configuração, vale separar o que é cada coisa:
- Métricas são números ao longo do tempo: uso de CPU, requisições por segundo, tamanho de fila. São baratas de guardar e boas pra gráfico e alerta.
- Logs são eventos em texto (de preferência JSON) que a sua aplicação escreve: "pedido 123 criado", "falha ao chamar o gateway de pagamento".
- Traces contam a história de uma requisição: entrou no endpoint, consultou o banco, chamou outra API, respondeu. Cada etapa é um span, com início, fim e duração.
O que faz o Datadog valer a pena é a ligação entre os três. Você vê um pico de latência no gráfico, clica, cai nos traces daquele momento, abre um trace lento e, de dentro dele, vê os logs que aquela requisição escreveu. Isso só funciona se os três chegarem com as mesmas tags.
A arquitetura: sua aplicação fala com o Agent#
O Datadog Agent é um programa que roda perto da sua aplicação: no mesmo servidor, como container ao lado dos seus ou como DaemonSet no Kubernetes. Ele:
- coleta métricas do host e dos containers;
- recebe os traces que a sua aplicação envia (porta 8126, TCP);
- recebe métricas customizadas pelo protocolo DogStatsD (porta 8125, UDP);
- lê os logs dos containers;
- e manda tudo pro Datadog, com a sua API key.
Duas configurações aparecem em todo lugar:
DD_API_KEY: a chave da sua organização. Ela fica só no Agent, nunca no código da aplicação.DD_SITE: em qual região está a sua conta (datadoghq.com,datadoghq.eu,us5.datadoghq.come outras). Se o site estiver errado, os dados simplesmente não aparecem.
Integrando uma API Node.js#
1. O Agent num container#
Com Docker Compose, o Agent fica ao lado da API. As variáveis abaixo ligam o APM, a coleta de logs dos containers e o 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-agentO DD_APM_NON_LOCAL_TRAFFIC=true é o detalhe que mais derruba gente: por padrão, o Agent só aceita traces da própria máquina. Com a API em outro container, sem essa variável, os traces nunca chegam.
2. O dd-trace na aplicação#
O APM do Node.js é a biblioteca dd-trace:
npm install dd-traceEla funciona interceptando os require da aplicação pra instrumentar Express, pg, http e outras bibliotecas sozinha. Por isso, ela precisa carregar antes de tudo. O jeito mais seguro é pela linha de comando, sem mexer no código:
node --require dd-trace/init app.jsSe a aplicação usa ES modules, a documentação indica o --import:
node --import dd-trace/initialize.mjs app.jsCom isso, toda requisição HTTP já vira um trace, com spans das consultas ao banco e das chamadas a outras APIs, sem nenhuma linha de código de instrumentação.
3. As três tags que ligam tudo#
O Datadog chama isso de unified service tagging: três tags reservadas, iguais em métricas, logs e traces.
env: o ambiente (production,staging).service: o nome do serviço (orders-api).version: a versão do código. Ela deve mudar a cada deploy: é com ela que o Datadog compara a versão nova com a anterior e mostra se o deploy piorou a latência ou os erros.
Na aplicação, elas vêm das variáveis DD_ENV, DD_SERVICE e DD_VERSION, como no docker-compose.yml acima. Uma boa prática é usar o hash do commit ou a tag do release como versão.
4. Logs ligados aos traces#
Com DD_LOGS_INJECTION=true, o dd-trace acrescenta o id do trace e do span em cada linha de log. Assim, de dentro de um trace, você vê os logs daquela requisição, e de um log você abre o trace.
Dois cuidados:
- Só funciona com log em JSON. Use um logger como Winston, Pino ou Bunyan configurado pra JSON.
- O
dd-traceprecisa ser carregado antes do logger, de novo.
Uma linha de log fica neste formato (o da documentação, com os nomes do nosso exemplo):
{"dd":{"service":"orders-api","trace_id":"68c2114800000000669b6b6b2aaf59c9","span_id":"8985025821692657638","version":"1.4.2"},"level":"info","message":"order created"}5. Métricas customizadas (com cuidado)#
Pra contar coisas do seu negócio, como pedidos criados, dá pra mandar métricas pelo DogStatsD, que o Agent recebe na porta 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 })
}O comentário no código é o ponto mais importante: cada combinação de valores de tag vira uma série separada, e métricas customizadas são cobradas por série. Uma tag payment_method com três valores gera três séries. Uma tag user_id com 100 mil usuários gera 100 mil.
Lendo o painel de um serviço#
Com os dados chegando, a primeira tela pra abrir é a do serviço (em APM, Services, clique no seu). Ela parece cheia, mas o essencial cabe em três gráficos, o famoso RED: Requests, Errors e Duration.
Requisições#
Quantas requisições por segundo o serviço recebe. Sozinho, esse gráfico diz pouco. Ele serve de contexto pros outros dois: a latência subiu junto com o tráfego? Então pode ser falta de capacidade. Subiu com o tráfego parado? Então algo mudou no código ou numa dependência.
Erros#
A contagem de erros e, mais útil, a taxa de erro: a porcentagem das requisições que falharam. 50 erros por minuto num serviço com 10 mil requisições é 0,5%. Num serviço com 100 requisições, é metade de tudo.
Latência: por que p95 e não a média#
A latência aparece em percentis: p50, p75, p90, p95, p99 e o máximo. Um exemplo pra entender (números inventados):
- 100 requisições: 95 levam 80 ms, 5 levam 3 segundos.
- A média dá uns 230 ms. Parece só "um pouco lento", e não descreve ninguém: nenhuma requisição levou 230 ms.
- O p50 (a mediana) é 80 ms: a requisição típica está ótima.
- O p99 é 3 segundos: tem gente esperando três segundos.
A média esconde exatamente quem está sofrendo. Por isso:
- p50 mostra a experiência típica;
- p95 e p99 mostram a cauda, os usuários que mais esperam (e muitas vezes são os mais importantes, como quem tem o carrinho maior);
- alertas de latência costumam usar p95 ou p99.
A lista de recursos#
Embaixo dos gráficos fica a lista de recursos: cada endpoint (GET /orders/:id, POST /orders) com suas próprias requisições, latência e taxa de erro. É ali que você descobre qual endpoint puxou o gráfico pra cima. Ordene pela latência p95 ou pela taxa de erro e comece pelo topo.
Lendo um trace#
Clicando num ponto do gráfico ou num recurso, você chega nos traces. Abra um dos lentos. Ele aparece como um flame graph: barras horizontais, uma por span, com a largura proporcional ao tempo.
Como ler:
- A barra de cima é a requisição inteira. A duração dela é o que o usuário sentiu.
- Procure o span mais largo. No exemplo, a chamada pro gateway de pagamento leva 1,6 dos 1,8 segundo. Otimizar a consulta ao banco, de 40 ms, não ia mudar quase nada.
- Spans em sequência que poderiam ser paralelos são outro sinal clássico: três chamadas independentes, uma depois da outra.
- Muitos spans iguais e curtos (centenas de
SELECTparecidos) indicam o problema de N+1: uma consulta por item, em vez de uma consulta pra todos. - Abra as abas do span: os logs da requisição (se a injeção estiver ligada), as tags e, nos spans com erro, a mensagem e a stack.
Buscando nos logs#
O Log Explorer tem uma sintaxe própria de busca. As que eu mais 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- Sem
@você busca por tag (service,env,status,host). - Com
@você busca por um atributo do JSON do log (@http.status_code,@order.id). - Entre aspas é busca pelo texto da mensagem.
- O
-na frente exclui.
Uma dica: a busca por atributo diferencia maiúsculas de minúsculas. A busca pelo texto, não.
Monitores: ser avisado antes do usuário#
Um monitor é um alerta. O mais útil pra começar é um por serviço, olhando os mesmos sinais da página do serviço:
- taxa de erro acima de um limite (por exemplo, 2% por 5 minutos);
- latência p95 ou p99 acima do que o usuário tolera;
- ausência de dados: o serviço parou de mandar requisições. Às vezes ele caiu de um jeito que não gera erro nenhum, só silêncio.
Cada monitor tem um nível de aviso (warning) e um de alerta, e uma mensagem com o destino da notificação, como um canal do Slack. Escreva a mensagem pensando em quem vai ler às três da manhã: o que quebrou, o link pro painel e o primeiro passo pra investigar.
Comece com poucos. Alerta que dispara toda hora vira ruído, e ruído é ignorado justamente no dia em que importa.
Cuidados com o custo#
O Datadog cobra por várias coisas diferentes, e é fácil se assustar com a fatura. Os três vilões clássicos:
- Logs: cobrados pelo volume que entra e pelo que fica indexado. Log de debug em produção, ou um log por item num laço, explode o volume. Dá pra filtrar no Agent ou em pipelines antes de indexar.
- Métricas customizadas com muitos valores de tag: como no exemplo do
user_id, cada combinação vira uma série cobrada. - Traces: em serviço com muito tráfego, guardar 100% dos traces custa caro e raramente é necessário. Configure a amostragem.
Os preços mudam e dependem do contrato, então confira a página de preços do Datadog em vez de confiar em número de blog.
Checklist#
- Agent rodando com
DD_API_KEYe oDD_SITEcerto. DD_APM_NON_LOCAL_TRAFFIC=truese a aplicação estiver em outro container.dd-tracecarregado antes de tudo (node --require dd-trace/init).DD_ENV,DD_SERVICEeDD_VERSIONem todo serviço, com a versão mudando a cada deploy.- Logs em JSON com
DD_LOGS_INJECTION=true. - Métrica customizada só com tags de poucos valores.
- Página do serviço: requisições, taxa de erro, p95 e p99, e a lista de recursos.
- Trace: comece pelo span mais largo.
- Monitores de taxa de erro, latência e ausência de dados, com mensagem útil.
- Um olho na fatura: volume de log, séries de métrica e amostragem de trace.
Referências#
Leia também

Infra15 min de leitura
Como economizar tokens no Claude Code com rtk e graphify

Infra13 min de leitura
Arquivo apagado não some: antes de vender seu HD ou SSD

Infra8 min de leitura
Não subestime o lock file: npm ci, conflitos e segurança