Formations — 1 037 leçons en français

Accueil › Node.js › Déboguer un programme Node

Déboguer un programme Node

Démarrer avec Nodedebutant

L'inspecteur

node --inspect serveur.js          # port 9229
node --inspect-brk serveur.js      # s'arrête à la première ligne

Puis chrome://inspect, ou le débogueur de l'éditeur. Points d'arrêt, pile, variables — comme côté navigateur.

--inspect-brk est celui qu'il faut pour déboguer le démarrage, puisque l'autre arrive trop tard.

Enrichir une erreur sans la perdre

try {
  await base.query(sql, [id]);
} catch (e) {
  throw new Error(`Échec de la mise à jour du client ${id}`, { cause: e });
}
Error: Échec de la mise à jour du client 42
    at majClient (src/clients.js:18:11)
  [cause]: Error: connect ECONNREFUSED 10.0.0.5:5432

Le message dit ce que le programme tentait de faire, la cause dit ce qui a échoué. Concaténer les messages aurait perdu la trace et le type.

Le journal structuré

journal.info({ requeteId, clientId: 42, duree: 128 }, "client mis à jour");
{"level":30,"time":1763000000,"requeteId":"a3f9","clientId":42,"duree":128,"msg":"client mis à jour"}

Avec trois instances et mille requêtes par minute, la question devient « que s'est-il passé pour cette requête » — et seule une recherche sur un champ y répond.

L'identifiant de corrélation

app.use((req, res, next) => {
  req.id = req.headers["x-request-id"] ?? crypto.randomUUID();
  res.setHeader("x-request-id", req.id);
  next();
});

Le client peut citer l'identifiant, et tous les journaux de la requête se retrouvent d'un coup. C'est le meilleur rapport entre dix lignes de code et du temps de diagnostic économisé.

Ne jamais journaliser

Mot de passe, jeton, en-tête d'autorisation, numéro de carte, corps de requête complet. Un journal est lu par plus de monde qu'on ne croit, et conservé plus longtemps qu'on ne croit.

Les termes à connaître

Inspecteur

node --inspect ouvre un port de débogage auquel se branchent les outils de développement du navigateur ou l'éditeur. Points d'arrêt, pile, variables.

Trace d'appel

La pile des appels au moment de l'erreur. En asynchrone, elle s'arrête souvent à la frontière de l'attente — d'où l'intérêt de la cause chaînée.

Cause chaînée

new Error("…", { cause: e }) conserve l'erreur d'origine. C'est ce qui permet d'ajouter du contexte sans perdre la cause.

Journal structuré

Une ligne de JSON par événement, avec des champs interrogeables. Indispensable dès qu'il y a plus d'une instance.

Identifiant de corrélation

Un identifiant par requête, propagé dans tous les journaux et renvoyé au client. Il transforme une plainte vague en diagnostic.

Fuite d'écouteurs

L'avertissement « MaxListenersExceededWarning ». Il signale presque toujours un abonnement posé dans un gestionnaire de requête et jamais retiré.

Lire l'explication détaillée et faire le quiz →

Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.