Infra12 min de lecture
Datadog de zéro : l'intégrer et lire le tableau de bord
Guide Datadog pour débuter : l'Agent, dd-trace dans une API Node.js, les tags de service, les logs liés aux traces, lire la latence p95, les traces et les monitors.

J'ai dû étudier Datadog, et la première fois que j'ai ouvert le tableau de bord, ça m'a fait un choc : des graphiques dans tous les sens, des sigles partout, et aucune idée de par où commencer.
Cet article est le guide que j'aurais aimé lire ce jour-là. Il couvre les deux moitiés du travail : faire entrer les données (l'Agent et la bibliothèque dans ton application) et comprendre ce qui s'affiche à l'écran (latence, erreurs, traces, logs et alertes).
Un avertissement honnête : les exemples de code suivent la documentation officielle de Datadog, en lien dans chaque partie, et je ne les ai pas lancés sur un vrai compte. Les images des écrans sont des illustrations que j'ai dessinées pour expliquer chaque partie, pas des captures de Datadog. Le produit change souvent d'apparence, mais les concepts restent les mêmes.
TL;DR#
- Datadog réunit trois types de données : les métriques (des nombres dans le temps), les logs (des événements en texte) et les traces (le chemin d'une requête). Ce qui relie les trois, ce sont les tags.
- L'Agent tourne à côté de ton application (dans un conteneur, par exemple), reçoit les données et les envoie à Datadog. Ton application parle à l'Agent, pas à internet.
- Dans une API Node.js, l'APM arrive avec
dd-trace, chargé avant tout le reste :node --require dd-trace/init app.js. - Trois tags valent de l'or :
env,serviceetversion. Avec eux, tu peux tout filtrer par environnement et comparer un déploiement avec le précédent. - Sur le tableau de bord d'un service, lis trois chiffres : requêtes, erreurs et latence. Et la latence se lit en p95 et p99, pas en moyenne.
- Une trace montre où le temps est passé. Le span le plus large est le premier suspect.
- Attention au coût : trop de logs, des tags avec beaucoup de valeurs (comme un id d'utilisateur) sur des métriques personnalisées et des traces sans échantillonnage coûtent cher.
Les trois pièces : métriques, logs et traces#
Avant toute configuration, il vaut mieux séparer ce qu'est chaque chose :
- Les métriques sont des nombres dans le temps : usage CPU, requêtes par seconde, taille d'une file. Elles coûtent peu à stocker et sont parfaites pour les graphiques et les alertes.
- Les logs sont des événements en texte (de préférence en JSON) que ton application écrit : « commande 123 créée », « échec de l'appel à la passerelle de paiement ».
- Les traces racontent l'histoire d'une requête : elle est arrivée sur l'endpoint, a interrogé la base, a appelé une autre API, a répondu. Chaque étape est un span, avec un début, une fin et une durée.
Ce qui rend Datadog intéressant, c'est le lien entre les trois. Tu vois un pic de latence sur le graphique, tu cliques, tu tombes sur les traces de ce moment-là, tu ouvres une trace lente et, depuis l'intérieur, tu vois les logs que cette requête a écrits. Ça ne marche que si les trois arrivent avec les mêmes tags.
L'architecture : ton application parle à l'Agent#
Le Datadog Agent est un programme qui tourne près de ton application : sur le même serveur, comme conteneur à côté des tiens ou comme DaemonSet dans Kubernetes. Il :
- collecte les métriques de l'hôte et des conteneurs ;
- reçoit les traces que ton application envoie (port 8126, TCP) ;
- reçoit les métriques personnalisées via le protocole DogStatsD (port 8125, UDP) ;
- lit les logs des conteneurs ;
- et envoie tout à Datadog, avec ta clé d'API.
Deux réglages reviennent partout :
DD_API_KEY: la clé de ton organisation. Elle reste uniquement dans l'Agent, jamais dans le code de l'application.DD_SITE: la région de ton compte (datadoghq.com,datadoghq.eu,us5.datadoghq.comet d'autres). Si le site est mauvais, les données n'apparaissent tout simplement pas.
Intégrer une API Node.js#
1. L'Agent dans un conteneur#
Avec Docker Compose, l'Agent se place à côté de l'API. Les variables ci-dessous activent l'APM, la collecte des logs des conteneurs et 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, c'est le détail qui piège le plus de monde : par défaut, l'Agent n'accepte que les traces de sa propre machine. Avec l'API dans un autre conteneur et sans cette variable, les traces n'arrivent jamais.
2. dd-trace dans l'application#
L'APM de Node.js, c'est la bibliothèque dd-trace :
npm install dd-traceElle fonctionne en interceptant les require de l'application pour instrumenter Express, pg, http et d'autres bibliothèques toute seule. C'est pour ça qu'elle doit être chargée avant tout le reste. Le plus sûr, c'est de passer par la ligne de commande, sans toucher au code :
node --require dd-trace/init app.jsSi l'application utilise les ES modules, la documentation indique --import :
node --import dd-trace/initialize.mjs app.jsAvec ça, chaque requête HTTP devient déjà une trace, avec des spans pour les requêtes à la base et les appels aux autres API, sans une seule ligne de code d'instrumentation.
3. Les trois tags qui relient tout#
Datadog appelle ça le unified service tagging : trois tags réservés, identiques dans les métriques, les logs et les traces.
env: l'environnement (production,staging).service: le nom du service (orders-api).version: la version du code. Elle doit changer à chaque déploiement : c'est grâce à elle que Datadog compare la nouvelle version avec la précédente et montre si le déploiement a dégradé la latence ou les erreurs.
Dans l'application, ils viennent des variables DD_ENV, DD_SERVICE et DD_VERSION, comme dans le docker-compose.yml ci-dessus. Une bonne pratique : utiliser le hash du commit ou le tag de la release comme version.
4. Des logs liés aux traces#
Avec DD_LOGS_INJECTION=true, dd-trace ajoute l'id de la trace et du span à chaque ligne de log. Comme ça, depuis une trace, tu vois les logs de cette requête, et depuis un log, tu ouvres la trace.
Deux précautions :
- Ça ne marche qu'avec des logs en JSON. Utilise un logger comme Winston, Pino ou Bunyan configuré en JSON.
dd-tracedoit être chargé avant le logger, encore une fois.
Une ligne de log ressemble à ça (le format de la documentation, avec les noms de notre exemple) :
{"dd":{"service":"orders-api","trace_id":"68c2114800000000669b6b6b2aaf59c9","span_id":"8985025821692657638","version":"1.4.2"},"level":"info","message":"order created"}5. Des métriques personnalisées (avec prudence)#
Pour compter des choses de ton métier, comme les commandes créées, tu peux envoyer des métriques via DogStatsD, que l'Agent reçoit sur le port 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 })
}Le commentaire dans le code est le point le plus important : chaque combinaison de valeurs de tags devient une série à part, et les métriques personnalisées sont facturées par série. Un tag payment_method avec trois valeurs crée trois séries. Un tag user_id avec 100 000 utilisateurs en crée 100 000.
Lire le tableau de bord d'un service#
Une fois les données arrivées, le premier écran à ouvrir, c'est celui du service (dans APM, Services, clique sur le tien). Il a l'air chargé, mais l'essentiel tient en trois graphiques, le fameux RED : Requests, Errors et Duration.
Requêtes#
Combien de requêtes par seconde le service reçoit. Tout seul, ce graphique dit peu de choses. Il sert de contexte aux deux autres : la latence a monté en même temps que le trafic ? Alors ça peut être un manque de capacité. Elle a monté avec un trafic stable ? Alors quelque chose a changé dans le code ou dans une dépendance.
Erreurs#
Le nombre d'erreurs et, plus utile, le taux d'erreur : le pourcentage de requêtes qui ont échoué. 50 erreurs par minute sur un service à 10 000 requêtes, c'est 0,5 %. Sur un service à 100 requêtes, c'est la moitié de tout.
Latence : pourquoi p95 et pas la moyenne#
La latence s'affiche en percentiles : p50, p75, p90, p95, p99 et le maximum. Un exemple pour comprendre (chiffres inventés) :
- 100 requêtes : 95 prennent 80 ms, 5 prennent 3 secondes.
- La moyenne donne environ 230 ms. Ça a l'air juste « un peu lent », et ça ne décrit personne : aucune requête n'a pris 230 ms.
- Le p50 (la médiane) est de 80 ms : la requête typique va très bien.
- Le p99 est de 3 secondes : des gens attendent trois secondes.
La moyenne cache justement ceux qui souffrent. C'est pour ça que :
- p50 montre l'expérience typique ;
- p95 et p99 montrent la queue, les utilisateurs qui attendent le plus (et ce sont souvent les plus importants, comme celui qui a le plus gros panier) ;
- les alertes de latence utilisent en général p95 ou p99.
La liste des ressources#
Sous les graphiques, il y a la liste des ressources : chaque endpoint (GET /orders/:id, POST /orders) avec ses propres requêtes, sa latence et son taux d'erreur. C'est là que tu découvres quel endpoint a fait grimper le graphique. Trie par latence p95 ou par taux d'erreur et commence par le haut.
Lire une trace#
En cliquant sur un point du graphique ou sur une ressource, tu arrives aux traces. Ouvre une des plus lentes. Elle s'affiche sous forme de flame graph : des barres horizontales, une par span, dont la largeur est proportionnelle au temps.
Comment la lire :
- La barre du haut, c'est la requête entière. Sa durée, c'est ce que l'utilisateur a ressenti.
- Cherche le span le plus large. Dans l'exemple, l'appel à la passerelle de paiement prend 1,6 des 1,8 seconde. Optimiser la requête à la base, de 40 ms, ne changerait presque rien.
- Des spans en séquence qui pourraient tourner en parallèle, c'est un autre signe classique : trois appels indépendants, l'un après l'autre.
- Beaucoup de spans identiques et courts (des centaines de
SELECTsemblables) signalent le problème N+1 : une requête par élément, au lieu d'une requête pour tous. - Ouvre les onglets du span : les logs de la requête (si l'injection est activée), les tags et, sur les spans en erreur, le message et la stack.
Chercher dans les logs#
Le Log Explorer a sa propre syntaxe de recherche. Celles que j'utilise le plus :
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- Sans
@, tu cherches par tag (service,env,status,host). - Avec
@, tu cherches par un attribut du JSON du log (@http.status_code,@order.id). - Entre guillemets, c'est une recherche sur le texte du message.
- Le
-devant exclut.
Une astuce : la recherche par attribut est sensible à la casse. La recherche sur le texte, non.
Les monitors : être prévenu avant l'utilisateur#
Un monitor, c'est une alerte. Le plus utile pour commencer, c'est un par service, qui surveille les mêmes signaux que la page du service :
- le taux d'erreur au-dessus d'un seuil (par exemple, 2 % pendant 5 minutes) ;
- la latence p95 ou p99 au-dessus de ce que l'utilisateur tolère ;
- l'absence de données : le service a arrêté d'envoyer des requêtes. Parfois, il est tombé d'une façon qui ne génère aucune erreur, juste du silence.
Chaque monitor a un niveau d'avertissement (warning) et un niveau d'alerte, et un message avec la destination de la notification, comme un canal Slack. Écris le message en pensant à la personne qui va le lire à trois heures du matin : ce qui a cassé, le lien vers le tableau de bord et la première étape pour enquêter.
Commence avec peu de monitors. Une alerte qui se déclenche tout le temps devient du bruit, et le bruit est ignoré justement le jour où ça compte.
Attention au coût#
Datadog facture plusieurs choses différentes, et c'est facile de prendre peur devant la facture. Les trois méchants classiques :
- Les logs : facturés selon le volume qui entre et ce qui reste indexé. Des logs de debug en production, ou un log par élément dans une boucle, font exploser le volume. Tu peux filtrer dans l'Agent ou dans des pipelines avant l'indexation.
- Les métriques personnalisées avec beaucoup de valeurs de tags : comme dans l'exemple du
user_id, chaque combinaison devient une série facturée. - Les traces : sur un service à fort trafic, garder 100 % des traces coûte cher et sert rarement. Configure l'échantillonnage.
Les prix changent et dépendent du contrat, alors consulte la page des tarifs de Datadog au lieu de te fier au chiffre d'un blog.
Checklist#
- Agent qui tourne avec
DD_API_KEYet le bonDD_SITE. DD_APM_NON_LOCAL_TRAFFIC=truesi l'application est dans un autre conteneur.dd-tracechargé avant tout le reste (node --require dd-trace/init).DD_ENV,DD_SERVICEetDD_VERSIONsur chaque service, avec une version qui change à chaque déploiement.- Logs en JSON avec
DD_LOGS_INJECTION=true. - Métriques personnalisées uniquement avec des tags à peu de valeurs.
- Page du service : requêtes, taux d'erreur, p95 et p99, et la liste des ressources.
- Trace : commence par le span le plus large.
- Monitors sur le taux d'erreur, la latence et l'absence de données, avec un message utile.
- Un œil sur la facture : volume de logs, séries de métriques et échantillonnage des traces.
Références#
À lire aussi

Infra16 min de lecture
Économiser des tokens dans Claude Code avec rtk et graphify

Infra13 min de lecture
Comment effacer un disque dur ou SSD avant de le vendre

Infra9 min de lecture
Ne sous-estime pas le lock file : npm ci, conflits, sécurité