Canal de diagnostic — le cycle de chaque requête publié sur diagnostics_channel

stable@nodefony/httpmis à jour 2026-10-24

Nodefony annonce le début et la fin de chaque requête HTTP et de chaque handshake WebSocket sur un canal natif de Node, nodefony.http.request. Un outil d’observation installé dans le même process — OpenTelemetry, Datadog, Sentry, ou votre propre code — s’y abonne et reçoit, sans monkey-patch, ce que Nodefony est seul à connaître : la route qui a répondu, son gabarit, le module signataire, le requestId, le statut réel et la durée. Personne n’écoute ? Le canal coûte une lecture de booléen par requête, et rien n’est alloué.

📍 Documentation › @nodefony/http › Canal de diagnostic

Schéma général#

Le même objet voyage de start à asyncEnd : l’abonné y lit à la fin ce qui n’était pas encore connu au début.

Lexique#

Qu’est-ce que c’est ?#

Un haut-parleur interne au process. Nodefony annonce « une requête commence », puis « elle est finie, voici son bilan ». Quiconque s’est mis à l’écoute de ce canal, dans le même process, reçoit l’annonce — immédiatement, sur le même fil, avec le même objet : pas de copie, pas de réseau, pas de fichier. Rien ne sort du process par lui-même : c’est l’abonné qui décide d’exporter, avec son propre transport (OTLP vers un collecteur, agent Datadog, Sentry).

Le problème qu’il résout : sans lui, un outil de traçage ne voit d’une application Nodefony que ce que node:http publie — une requête brute, sans route, sans module, sans requestId. Pour en savoir plus, il devrait patcher les classes du framework à l’exécution, ce qui casse à chaque version. Node publie bien ses propres canaux serveur (http.server.request.start, http.server.response.finish), mais ils ne portent que la requête et la réponse brutes : ce que Nodefony a décidé — quelle route, quel module, quel statut réel derrière un proxy — n’y figure pas.

La vision Nodefony#

• Un contrat, pas un crochet : le canal et la forme de son message (IRequestTrace) sont une API publique de @nodefony/http. Un plugin d’APM s’écrit contre eux, et non contre l’intérieur du pipeline. C’est un contrat neuf : les agents existants ne le lisent pas d’office, un plugin doit le consommer (comme Fastify publie tracing:fastify.request.handler pour les siens).
• Zéro coût sans abonné : la garde (requestTrace.ts#hasRequestTraceSubscribers) est lue UNE fois, au début de la requête. Faux → aucun message n’est construit, la fin ne lit qu’un champ null (Context.ts#Context.requestTrace). Pas d’option de configuration : « éteint » veut dire « personne n’écoute ».
• Une seule horloge : la durée publiée est celle de la ligne d’accès (Context.ts#Context.stopClock), jamais une mesure propre au canal.
• La séquence de Node, à la main : start sous runStores à l’entrée, end quand la partie synchrone rend la main (requestTrace.ts#runTraced), puis error, asyncStart et asyncEnd au démontage, quand le dernier octet est remis (requestTrace.ts#closeRequestTrace). C’est l’ordre de TracingChannel.tracePromise, que les abonnés génériques attendent ; la publication est manuelle parce que la fin d’une requête arrive sur l’événement close de la réponse, hors de toute fonction qu’on pourrait envelopper.
• Les stores des abonnés sont honorés : un agent qui lie son AsyncLocalStorage au canal (bindStore) voit son contexte actif pendant tout le traitement — les requêtes SQL et les appels sortants d’une route deviennent des enfants de son span.

Démarrage rapide#

Un abonné de dix lignes, dans un fichier chargé AVANT l’application — c’est ainsi que se chargent les agents d’APM :

// tracing.ts — chargé par `--import`, avant l'application
import diagnosticsChannel from "node:diagnostics_channel";
import { REQUEST_TRACE_CHANNEL } from "@nodefony/http";
import type { IRequestTrace } from "@nodefony/http";

const channel = diagnosticsChannel.tracingChannel<IRequestTrace>(
  REQUEST_TRACE_CHANNEL,
);

channel.subscribe({
  start: () => {},
  end: () => {},
  asyncStart: () => {},
  asyncEnd: (trace) => {
    console.log(
      `${trace.requestId} ${trace.method} ${trace.routePath ?? "-"} → ${trace.statusCode} en ${trace.durationMs?.toFixed(3)} ms (${trace.module})`,
    );
  },
  error: (trace) => {
    console.error(trace.requestId, trace.error);
  },
});

On le charge par NODE_OPTIONS, que les process lancés par la commande de développement héritent :

NODE_OPTIONS="--import ./tracing.ts" npx nodefony development
curl -k https://127.0.0.1:5152/

Ce qu’on observe, une ligne par requête servie — ici la page d’accueil d’une application générée :

6f1c…-9e2a GET / → 200 en 3.528 ms (app)

Importer REQUEST_TRACE_CHANNEL plutôt que recopier la chaîne : le nom vit en un seul endroit.

Le message — IRequestTrace#

Déclaré dans IRequestTrace.ts#IRequestTrace, exporté par @nodefony/http. Tout est en lecture seule pour l’abonné.

Les champs « fin » valent null à start et end : c’est normal, la route et le statut ne sont pas encore connus. On les lit sur asyncEnd.

Correspondance avec OpenTelemetry#

Pour qui écrit un plugin OTel, la table des attributs du span serveur (conventions sémantiques HTTP) :

Un 4xx sans exception ne publie pas error : pour un span serveur, OTel demande de laisser le statut d’un 4xx non renseigné. C’est à l’abonné de classer un statut ; statusCode est là pour ça.

La séquence, sortie par sortie#

La trace d’un WebSocket couvre le handshake, pas la vie de la connexion : elle se ferme au 101. Les messages qui suivent ne sont pas publiés sur ce canal.

Architecture interne#

• Entrée HTTP — http-kernel.ts#HttpKernel.handleHttp : juste après la construction du contexte, la garde ; avec abonné, le message est créé (requestTrace.ts#openRequestTrace, seule allocation du canal) et le pipeline tourne sous start.runStores (http-kernel.ts#HttpKernel.dispatchHttpContext).
• Fin HTTP — http-kernel.ts#HttpKernel.teardownHttp, sur l’événement close de la réponse, APRÈS la ligne d’accès : celle-ci a déjà recopié le statut de l’amont d’une requête relayée (HttpContext.ts#HttpContext.logRequest).
• Handshake WebSocket — http-kernel.ts#HttpKernel.handleWebsocket ouvre la trace ; elle se ferme à l’acceptation (WebsocketContext.ts#WebsocketContext.connect, au même point que la ligne d’accès), au refus (WebsocketContext.ts#WebsocketContext.refuseHandshake, seul endroit où le statut du refus est connu), ou en échec (http-kernel.ts#HttpKernel.closeFailedWebsocketTrace).
• Idempotence — closeRequestTrace remet Context.requestTrace à null avant de publier : un handshake a plusieurs sorties, la première ferme la trace, les suivantes ne font rien.

Configuration#

Aucune, à dessein. Lire un réglage à chaque requête coûterait autant que lire la garde elle-même, pour un résultat identique : sans abonné, rien n’est publié. Pour couper le canal, on ne s’y abonne pas — ou on se désabonne (channel.unsubscribe(subscribers)).

Normes appliquées#

• Documentation de node:diagnostics_channel — nommage des canaux de trace en tracing:module.function:start (d’où nodefony.http.request) ; et la règle « les événements ne sont publiés que si l’abonné était présent avant le début de la trace » : un abonné qui arrive en cours de requête ne reçoit rien de cette requête, pas même sa fin.
• Conventions sémantiques HTTP d’OpenTelemetry — http.route exige un gabarit de faible cardinalité, d’où routePath ; la durée de http.server.request.duration doit égaler celle du span serveur, d’où une seule horloge.

Sécurité#

• L’URL complète part chez l’abonné, chaîne de requête comprise — un jeton passé en ?token= y figure. L’abonné est du code que l’exploitant a choisi d’installer, et les canaux natifs de node:http exposent déjà la requête entière ; mais un agent qui EXPORTE l’URL doit en retirer les paramètres sensibles. Préférer routePath pour nommer une opération.
• Une exception levée par un abonné fait tomber le process : Node la relance par process.nextTick en exception non capturée, hors de la pile de Nodefony. Un abonné se protège lui-même (try/catch).
• Un abonné lent ralentit chaque requête : il est appelé de façon synchrone, sur le fil du serveur.

Performance & mémoire#

Mesuré au micro-banc (Node 26, médiane de 7 passages) :

diagnostics_channel.hasSubscribers("nom") coûterait ~41 ns : la garde lit donc le TracingChannel gardé en mémoire de module, jamais une recherche par nom. Le gate mémoire (npm run test:memory) est vert sans abonné et avec un abonné armé : le message ne retient ni contexte ni scope.

Pièges#

Tests & couverture#

L’abonné vit dans le process du serveur : la sonde TraceChannelController du module test (/nodefony/test/trace-channel/{arm,disarm,events}) s’abonne à la demande. Ce qui manque : pas de banc unitaire isolé de requestTrace.ts (exercé de bout en bout par le banc d’intégration), et pas de cas « client parti pendant la décision » au banc (sortie couverte par lecture du code).

Suites : npm run test:integration (serveur requis), npm run test:memory. Skills associés : nodefony-check-memory-health, nodefony-load-test.

Pour aller plus loin#

• ⬆️ Retour au hub : @nodefony/http — vue du module · Toute la documentation
• 🧭 Pages sœurs : Observabilité HTTP · Serveurs
• La durée d’une requête et sa définition → Observabilité HTTP
• Le trajet complet d’une requête → pipeline-requete
• Le proxy inverse (statut de l’amont) → Proxy inverse
• Les lignes du journal, sur le canal nodefony.syslog.log → Journalisation