@nodefony/http 10.0.0-beta.4 → 10.0.0-beta.5

package/docs/diagnostics-channel.md

@@ -0,0 +1,303 @@
+---
+title: "Canal de diagnostic — le cycle de chaque requête publié sur diagnostics_channel"
+navTitle: Canal de diagnostic
+lang: fr
+module: "@nodefony/http"
+topic: diagnostics-channel
+section: "Cœur runtime"
+audience: [developer, devops]
+tags:
+  [
+    observabilite,
+    diagnostics_channel,
+    tracingchannel,
+    opentelemetry,
+    apm,
+    trace,
+    requestId,
+    websocket,
+  ]
+version: "doc"
+status: stable
+updated: 2026-10-24
+source: "src/packages/@nodefony/http/docs/diagnostics-channel.md"
+coverageModule: http
+coverageFiles: requestTrace.ts
+---
+
+# Canal de diagnostic — le cycle de chaque requête publié sur `diagnostics_channel`
+
+> 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](../../../../../docs/index.md) › [@nodefony/http](index.md) › **Canal de diagnostic**
+
+## Schéma général
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant N as Nodefony (pipeline)
+    participant A as Abonné (agent APM)
+    C->>N: GET /users/42
+    N->>A: start — requestId, méthode, URL
+    N->>A: end — la partie synchrone a rendu la main
+    N->>C: 200 (dernier octet remis)
+    N->>A: asyncStart puis asyncEnd — route, gabarit, module, statut, durée
+```
+
+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
+
+| Terme                     | Sens                                                                                                                                                      |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `diagnostics_channel`     | Module natif de Node (`node:diagnostics_channel`) : un bus de publication NOMMÉ, interne au process, fait pour que des outils observent une bibliothèque. |
+| Canal                     | Un nom (`tracing:nodefony.http.request:start`) ; publieur et abonné le retrouvent par ce nom, sans s'importer l'un l'autre.                               |
+| `TracingChannel`          | La forme « trace » du bus : cinq sous-canaux (`start`, `end`, `asyncStart`, `asyncEnd`, `error`) qui encadrent UNE opération, avec un objet partagé.      |
+| `runStores` / `bindStore` | Un abonné lie un `AsyncLocalStorage` au canal (`bindStore`) ; le publieur entre dans ce store pour la durée de l'opération (`runStores`).                 |
+| APM                       | _Application Performance Monitoring_ : agent (Datadog, New Relic, Elastic…) qui mesure et trace une application en production.                            |
+| OTel                      | _OpenTelemetry_ : standard ouvert de traces, métriques et journaux, et ses conventions de nommage d'attributs (« semconv »).                              |
+| Span                      | Une opération chronométrée d'une trace distribuée — ici, une requête serveur.                                                                             |
+| Gabarit de route          | Le chemin déclaré (`/users/{id}`), pas l'URL reçue (`/users/42`) : faible cardinalité, donc agrégeable. C'est l'attribut `http.route` d'OTel.             |
+| `requestId`               | Identifiant de corrélation de la requête (`X-Request-Id`), voir [Observabilité HTTP](observabilite.md).                                                   |
+
+## 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 :
+
+```ts
+// 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 :
+
+```bash
+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 :
+
+```text
+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é.
+
+| Champ        | Posé à  | Contenu                                                                                                                  |
+| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `requestId`  | `start` | identifiant de corrélation (celui de `X-Request-Id` entrant, sinon généré)                                               |
+| `protocol`   | `start` | `"http"` pour une requête, `"websocket"` pour un handshake                                                               |
+| `method`     | `start` | méthode de la requête (`"WEBSOCKET"` pour un handshake)                                                                  |
+| `scheme`     | `start` | `http`, `https`, `ws`, `wss` — tel que vu par le client, proxy de confiance compris                                      |
+| `url`        | `start` | URL complète, **chaîne de requête comprise**                                                                             |
+| `route`      | fin     | nom de la route qui a répondu, `null` sans route (fichier statique, 404)                                                 |
+| `routePath`  | fin     | gabarit de la route, préfixe compris (`/users/{id}`) ; la racine vaut `/` ; `null` sans route                            |
+| `module`     | fin     | module qui a signé la réponse — le même que celui de la ligne d'accès                                                    |
+| `statusCode` | fin     | statut rendu : celui de l'amont pour une requête relayée, `101` pour un handshake accepté, `null` si le client est parti |
+| `durationMs` | fin     | construction du contexte → dernier octet remis (fin du handshake en WebSocket) ; `null` si `timing.enabled: false`       |
+| `error`      | `error` | l'exception attrapée par le pipeline, `null` sinon                                                                       |
+
+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) :
+
+| Attribut OTel                  | Champ                                                          |
+| ------------------------------ | -------------------------------------------------------------- |
+| `http.request.method`          | `method`                                                       |
+| `url.scheme`                   | `scheme`                                                       |
+| `url.path` / `url.query`       | découpés de `url` par l'abonné (`new URL(trace.url)`)          |
+| `http.route`                   | `routePath` — jamais `route`, qui est un nom et pas un gabarit |
+| `http.response.status_code`    | `statusCode`                                                   |
+| `error.type`                   | dérivé de `error` (nom de la classe d'erreur)                  |
+| `http.server.request.duration` | `durationMs / 1000` (la métrique OTel est en secondes)         |
+
+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
+
+| Situation                               | Événements publiés                                    | `statusCode`         |
+| --------------------------------------- | ----------------------------------------------------- | -------------------- |
+| HTTP servi                              | `start` · `end` · `asyncStart` · `asyncEnd`           | statut de la réponse |
+| HTTP dont le pipeline lève              | `start` · `end` · `error` · `asyncStart` · `asyncEnd` | statut de l'erreur   |
+| Handshake WebSocket accepté             | `start` · `end` · `asyncStart` · `asyncEnd`           | `101`                |
+| Handshake refusé (origine, pare-feu, …) | `start` · `end` · `error` · `asyncStart` · `asyncEnd` | statut du refus      |
+| Client parti pendant la décision        | `start` · `end` · `asyncStart` · `asyncEnd`           | `null`               |
+
+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
+
+```mermaid
+flowchart TD
+    E["contexte construit"] --> G{"quelqu'un écoute ?"}
+    G -->|non| P["pipeline, rien d'alloué"]
+    G -->|oui| O["message créé, pipeline sous runStores"]
+    O --> F["démontage : error, asyncStart, asyncEnd"]
+```
+
+- **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) :
+
+| Chemin                        | Coût par requête                                                                      |
+| ----------------------------- | ------------------------------------------------------------------------------------- |
+| Personne n'écoute (le défaut) | une lecture de `hasSubscribers` (~1,6 ns), un champ `null` sur le contexte (8 octets) |
+| Un abonné                     | un objet de message, l'appel des abonnés, l'entrée dans les stores liés               |
+
+`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
+
+| Symptôme                                                    | Cause                                                            | Correction                                                              |
+| ----------------------------------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| L'abonné ne reçoit rien des premières requêtes              | il s'est abonné après leur début — règle des `TracingChannel`    | s'abonner AVANT l'application (`--import`)                              |
+| `route`, `statusCode` à `null` dans le gestionnaire `start` | ils ne sont connus qu'à la fin                                   | les lire dans `asyncEnd`                                                |
+| Le tableau de bord explose en cardinalité                   | l'opération est nommée d'après `url` (`/users/42`, `/users/43`…) | nommer par `routePath` (`/users/{id}`)                                  |
+| Le serveur tombe sur une exception venue de l'agent         | un abonné a levé : Node la relance en exception non capturée     | `try`/`catch` dans chaque gestionnaire de l'abonné                      |
+| Un 404 apparaît en erreur dans l'APM                        | l'abonné classe sur l'événement `error` sans regarder le statut  | classer par `statusCode` ; `error` signale une exception, pas un statut |
+| `durationMs` toujours `null`                                | `timing.enabled: false` dans la configuration de l'application   | rétablir le défaut — la durée est mesurée partout, production comprise  |
+
+## Tests & couverture
+
+| Type                      | Où                                                                                                                                                                                      |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Intégration — abonné réel | `integration/request-trace-channel.test.ts` — séquences HTTP servi / en erreur, handshake accepté / refusé, abonné tardif sans fin orpheline, désabonnement, même objet de bout en bout |
+| Mémoire                   | `http/memory.test.ts` — le gate, rejoué sans abonné (le défaut) et avec la sonde armée                                                                                                  |
+
+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](index.md) · [Toute la documentation](../../../../../docs/index.md)
+- 🧭 **Pages sœurs** : [Observabilité HTTP](observabilite.md) · [Serveurs](servers.md)
+- La durée d'une requête et sa définition → [Observabilité HTTP](observabilite.md)
+- Le trajet complet d'une requête → [pipeline-requete](../../../../../docs/architecture/pipeline-requete.md)
+- Le proxy inverse (statut de l'amont) → [Proxy inverse](reverse-proxy.md)
+- Les lignes du journal, sur le canal `nodefony.syslog.log` → [Journalisation](../../../../nodefony/docs/syslog.md#observer-le-journal-depuis-un-outil-tiers)

package/docs/index.md

@@ -43,7 +43,8 @@ Trois parcours selon ce que tu viens faire. L'ordre compte : chaque étape suppo
 3. [Pipeline de requête](../../../../../docs/architecture/pipeline-requete.md) — où se branchent
    rate-limit, en-têtes et firewall.
 4. [Rate-limit](rate-limit.md) — plafonner le débit par client avant que la charge n'atteigne le contrôleur.
-5. [Observabilité](observabilite.md) — corréler les logs par `requestId` pour diagnostiquer à chaud.
+5. [Observabilité](observabilite.md) — corréler les logs par `requestId` pour diagnostiquer à chaud ;
+   [Canal de diagnostic](diagnostics-channel.md) pour brancher un outil de traçage.
 6. [Sécurité](../../security/docs/index.md) — le pare-feu applicatif se pose par-dessus ce module.
 
 **Je fais du temps réel** — WebSocket dans le même contexte que le web.
@@ -66,6 +67,7 @@ Le tableau pour choisir vite ; les cards en dessous pour savoir ce qu'on y trouv
 | [Upload & corps](upload.md) | parser le corps et recevoir des fichiers | formulaires, imports multipart, API JSON |
 | [Rate-limit](rate-limit.md) | plafonner le débit par client (429) | protéger une API d'un flood ou d'un abus |
 | [Observabilité](observabilite.md) | tracer et journaliser chaque requête | débugger en prod, corréler des logs |
+| [Canal de diagnostic](diagnostics-channel.md) | publier le cycle de chaque requête à un outil de traçage, sans monkey-patch | brancher OpenTelemetry, Datadog ou Sentry |
 | [Proxy inverse](reverse-proxy.md) | relayer un préfixe d'URL vers un autre serveur, sur la même origine | servir Vite en dev, adosser un service interne sans CORS |
 | [Pipeline de requête](../../../../../docs/architecture/pipeline-requete.md) | l'ordre exact des étapes, HTTP comme WS | tu débugges « pourquoi ça passe / ça bloque ici » |
 
@@ -89,6 +91,9 @@ Le tableau pour choisir vite ; les cards en dessous pour savoir ce qu'on y trouv
   { "icon": "📈", "title": "observabilite", "href": "observabilite.md",
     "desc": "Observer les requêtes : lignes de log (pretty ou JSON), requestId de corrélation, W3C Trace Context, trace des frames WebSocket, redaction et sampling d'audit. Où partent les logs est traité par la page Syslog du cœur.",
     "meta": "débugger en prod, corréler les logs par requête" },
+  { "icon": "📡", "title": "diagnostics-channel", "href": "diagnostics-channel.md",
+    "desc": "Le TracingChannel nodefony.http.request : chaque requête HTTP et chaque handshake WebSocket publiés avec route, gabarit, module, requestId, statut réel et durée. Zéro coût sans abonné ; correspondance avec les attributs OpenTelemetry.",
+    "meta": "brancher un APM sans patcher le framework" },
   { "icon": "↪️", "title": "reverse-proxy", "href": "reverse-proxy.md",
     "desc": "Relayer un préfixe d'URL vers un autre serveur sans quitter l'origine de la page : HTTP et WebSocket, en-têtes de connexion jamais transmis, X-Forwarded-* et Via posés, barrière d'hôte appliquée avant le relais. C'est par lui que Vite est servi en développement.",
     "meta": "une origine, un certificat — pas de CORS ni de contenu mixte" },

package/docs/observabilite.md

@@ -265,6 +265,58 @@ de bilan, au teardown, via `Context.logRequest()` (`Context.ts#Context.logReques
 - `shouldSample?(context, error?)` — **portillon** évalué AVANT le rendu : `false` = ligne sautée sans
   aucune allocation ni `JSON.stringify` (levier perf du logger d'audit).
 
+### La durée d'une requête — une horloge, mesurée partout
+
+`durationMs` est **une seule valeur**, que lisent la ligne d'accès JSON, la ligne lisible du
+développement, le profil du Studio et la trace verbose. Elle vient d'une horloge propre à chaque
+requête (`Context.ts#Context.stopClock`) :
+
+- **elle démarre** à la construction du contexte, dès que la requête atteint le noyau ;
+- **elle s'arrête** au démontage, sur l'événement `close` de la réponse : le dernier octet vient
+  d'être remis au système, ou le client est parti (`http-kernel.ts#HttpKernel.teardownHttp`).
+
+Aucun lecteur ne relit l'horloge pour son compte : le journal et le Studio affichent la même durée
+pour la même requête.
+
+| Compté dans la durée                                   | Hors de la durée                                                           |
+| ------------------------------------------------------ | -------------------------------------------------------------------------- |
+| routage, pare-feu, session, action, rendu              | l'acceptation TCP et la négociation TLS                                    |
+| l'écriture de la réponse, jusqu'au dernier octet remis | la lecture des en-têtes par Node, avant que la requête n'atteigne le noyau |
+| l'attente d'un client lent qui lit la réponse          | ce qui suit le `close` : hooks `onAfterResponse` et `onFinish`             |
+
+> [!NOTE]
+> **Pourquoi jusqu'au dernier octet, et pas jusqu'à la fin de l'action ?** Parce que c'est la
+> définition des outils qui liront cette ligne. OpenTelemetry ferme le span serveur sur `close`, et
+> la métrique `http.server.request.duration` doit valoir la durée de ce span. nginx mesure
+> `$request_time` jusqu'à l'écriture du journal, une fois les derniers octets envoyés. Un p99 de
+> l'application se compare ainsi directement à celui du proxy placé devant elle. Le travail du
+> serveur seul, hors réseau, se lit dans les **phases**.
+
+Trois cas à connaître :
+
+- **Un flux** (SSE, téléchargement long) dure ce que dure le flux, comme chez nginx.
+- **Un client parti avant la fin** (statut `499`) : la durée court jusqu'à son départ.
+- **WebSocket** : la ligne d'accès d'un handshake porte la durée du handshake, pas celle de la
+  connexion. Chaque invocation du pont RPC a sa propre horloge, dans son profil
+  (`FrameProfile.ts#FrameProfile.stopClock`).
+
+#### Deux niveaux de mesure : la durée, puis les phases
+
+| `timing.enabled` | Durée (`durationMs`)         | Phases (waterfall) | Pour quoi                                               |
+| ---------------- | ---------------------------- | ------------------ | ------------------------------------------------------- |
+| `null` (défaut)  | partout, production comprise | hors production    | le cas courant                                          |
+| `true`           | partout                      | partout            | un diagnostic à chaud en production                     |
+| `false`          | nulle part                   | nulle part         | un banc qui veut le coût du pipeline sans aucune mesure |
+
+La règle a une seule implémentation (`timingMode.ts#resolveTimingMode`). La durée coûte deux lectures
+d'horloge par requête ; les phases, une lecture par borne, un tableau et un index par requête. C'est
+pourquoi seules les phases restent coupées en production.
+
+La trace verbose (`timing.verbose`) nomme les deux grandeurs côte à côte :
+`TRACE phases [total 15.25ms · Σ 12.80ms] parse=0.50ms · action=12.30ms`. Le total est la durée de la
+requête, Σ la somme des phases : l'écart montre le temps passé hors de toute phase, envoi au client
+compris.
+
 ### La trace des frames WebSocket
 
 Chaque frame WS (RECEIVE / SEND / BROADCAST) peut être tracée pour le Suivi de requête (Studio). Le
@@ -281,11 +333,16 @@ chaîne quand l'env est `production` (`WebsocketContext.ts#WebsocketContext.broa
 
 ## ⚙️ Configuration
 
-Un seul réglage d'app, côté cœur (bloc `log`), pilote le format des lignes.
+Deux réglages d'app, côté cœur : le format des lignes (bloc `log`) et ce que le chronométrage mesure
+(bloc `timing`).
 
-| Option              | Type                                      | Défaut | Effet                                                                                          |
-| ------------------- | ----------------------------------------- | ------ | ---------------------------------------------------------------------------------------------- |
-| `log.requestFormat` | `auto` \| `default` \| `pretty` \| `json` | `auto` | Format de la ligne de bilan. `auto` = pretty en dev / json en prod (`schema.ts#serverSchema`). |
+| Option              | Type                                      | Défaut | Effet                                                                                                                                                                          |
+| ------------------- | ----------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `log.requestFormat` | `auto` \| `default` \| `pretty` \| `json` | `auto` | Format de la ligne de bilan. `auto` = pretty en dev / json en prod (`schema.ts#serverSchema`).                                                                                 |
+| `timing.enabled`    | `boolean` \| `null`                       | `null` | `null` : durée partout, phases hors production. `true` : phases aussi en production. `false` : ni durée ni phases. Surchargeable sans redéployer : `NF__APP__TIMING__ENABLED`. |
+
+Une clé inconnue sous `timing` (`timing: { enable: false }`) arrête le démarrage en la nommant : retirée
+en silence, elle laisserait l'horloge allumée chez qui croit l'avoir coupée.
 
 `auto` est résolu au boot selon l'environnement (`applyRequestLoggerFromConfig`, `http-kernel.ts#HttpKernel.applyRequestLoggerFromConfig`) :
 
@@ -315,8 +372,9 @@ Choisir en cinq secondes :
 
 Le plus grand gain en dev : `méthode statut url durée remote [id]`, avec couleur du statut (vert 2xx,
 jaune 4xx, rouge 5xx — `colorizeStatus()`, `pretty-request-logger.ts#colorizeStatus`) et `requestId` tronqué aux 8
-premiers caractères (`shortId()`, `pretty-request-logger.ts#shortId`). La durée est dérivée des phases de
-timing (`pretty-request-logger.ts#shortId`).
+premiers caractères (`shortId()`, `pretty-request-logger.ts#shortId`). La durée est celle de l'horloge de
+la requête, la même que dans la ligne JSON (`pretty-request-logger.ts#formatDuration`) ; `---` quand
+`timing.enabled` vaut `false`.
 
 ### `JsonAuditLogger` — un PDU par requête, pour la machine
 
@@ -328,6 +386,16 @@ timing (`pretty-request-logger.ts#shortId`).
   drapeaux `hasAuthorization`/`hasCookie` le sont (`audit-logger.ts#AuditLogEntry.hasCookie`).
 - **Sampling déterministe** : `shouldSample()` (`audit-logger.ts#JsonAuditLogger.shouldSample`) garde 1 requête nominale sur N mais
   **jamais** une erreur ni un `status >= 400` — on ne perd aucun échec ; compteur, pas de RNG.
+- **Durée présente en production** : `durationMs` est la durée de la requête, de son arrivée au
+  dernier octet de la réponse, en millisecondes. C'est la même valeur que dans le Studio (voir
+  [La durée d'une requête](#la-durée-dune-requête--une-horloge-mesurée-partout)). Le détail par phase
+  (`phases`) reste réservé au développement, ou à `timing.enabled: true`.
+
+Destinée à une machine, cette ligne se lit dans un outil d'observabilité : une application générée
+livre deux **tableaux de bord d'exemple** (Grafana sur Loki, OpenSearch Dashboards) sous
+`docker/examples/dashboards/`, à importer. Côté OpenSearch, le transport range la ligne sous
+`http.*` (statut, famille, chemin, durée) par un pipeline d'ingestion — la page Syslog du cœur le
+détaille.
 
 ### `DefaultRequestLogger` — le format legacy
 
@@ -371,6 +439,11 @@ Les choix visibles dans le code :
   `toISOString`, 0 `JSON.stringify`, 0 `Pdu` au ring (`audit-logger.ts#JsonAuditLogger.shouldSample`).
 - **Audit nominal coupable** — l'option `nominal` coupe le log des 2xx/3xx si le sink texte est `null`
   (l'entrée n'atteindrait aucune destination) — ~5,9 % du profil CPU récupérés (`audit-logger.ts#JsonAuditLoggerOptions.sampleRate`).
+- **Durée : deux lectures d'horloge, rien d'autre** — `performance.now()` à l'entrée et au `close`,
+  quelques dizaines de nanosecondes chacune, deux nombres sur le contexte, aucune structure allouée
+  (`Context.ts#Context.stopClock`). C'est un ordre de grandeur de moins que la date et la sérialisation
+  JSON de la ligne d'accès qu'elle complète, et c'est trop petit pour qu'un banc de débit le distingue
+  de son bruit. Les phases, elles, restent coupées en production.
 - **Trace des frames WS gatée en prod** — `logMessageContent()` court-circuite avant toute construction
   de chaîne hors dev (`WebsocketContext.ts#WebsocketContext.logMessageContent`) ; les events lifecycle ne créent aucun `Pdu` en production, et ne sont que DEBUG hors production (`Context.ts#lifecycleEventLogging`).
 
@@ -408,6 +481,7 @@ instancié **qu'en dev** (fuite d'info + coût en prod).
 | En-têtes trop volumineux / borne | anti-abus (log flooding) | `MAX_REQUEST_ID_LENGTH` (`requestId.ts#MAX_REQUEST_ID_LENGTH`) |
 | Log structuré (PDU, sévérités) | RFC 5424 | `Pdu` + `requestId`/`pid` (`Pdu.ts#Pdu.requestId`) |
 | Sévérité dérivée du statut HTTP | RFC 9110 (catégories) | `severityFromStatus()` (`audit-logger.ts#severityFromStatus`) |
+| Durée d'une requête serveur | OpenTelemetry, conventions sémantiques HTTP (`http.server.request.duration`, stable) | fin sur le `close` de la réponse (`Context.ts#Context.stopClock`) |
 | Non-journalisation des secrets | OWASP (logging) | redaction présence-only (`audit-logger.ts#JsonAuditLogger.renderHttp`) |
 
 > `X-Request-Id` n'est **pas** un en-tête normalisé (convention de-facto) ; c'est la **valeur** qu'il
@@ -415,16 +489,19 @@ instancié **qu'en dev** (fuite d'info + coût en prod).
 
 ## ⚠️ Pièges (symptôme → cause → correction)
 
-| Symptôme                                            | Cause                                                               | Correction                                                                                |
-| --------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| Le `X-Request-Id` que j'envoie n'est pas réfléchi   | Valeur non conforme (espace, CR/LF, non-ASCII, > 128) → **rejetée** | Utiliser `[A-Za-z0-9._-]{1,128}` (UUID/nanoid/traceparent OK) — sinon UUID serveur        |
-| Les logs de fin de requête n'ont pas de `requestId` | Ils sont émis hors bulle ALS                                        | Déjà géré : l'override `log()` rouvre une micro-bulle (`Context.ts#Context.log`)          |
-| Réponse HTTP/2 sans `x-request-id`                  | Chemin de réponse h2 distinct du 1.1                                | Déjà géré (`http2/Response.ts#Http2Response.writeHead`) — le port 5152 réfléchit aussi    |
-| Pas de `traceparent` renvoyé sur un WebSocket       | `ws` n'expose pas l'écriture d'en-tête au handshake                 | Attendu — la trace WS reste propagée en ALS (`http-kernel.ts#HttpKernel.handleWebsocket`) |
-| Frame WS binaire loggée en `{"0":..,"1":..}`        | Sérialisation naïve d'un Buffer                                     | Déjà géré : résumé `[binary N B]` (`wsLogContent.ts#formatWsLogContent`)                  |
-| Le format de log ne change pas malgré la config     | Un `setRequestLogger(...)` programmatique gagne sur la config       | L'override est volontaire (last setter wins) — retirer l'appel, ou le régler              |
-| Logs d'audit trop volumineux en prod                | `stack` sérialisée, ou 100 % des 2xx audités                        | `includeStack:false` (défaut prod) + `sampleRate` via `setRequestLogger`                  |
-| `Authorization`/`Cookie` attendus dans le log JSON  | Redaction : jamais sérialisés                                       | Par conception — lire les drapeaux `hasAuthorization`/`hasCookie`                         |
+| Symptôme                                            | Cause                                                                              | Correction                                                                                        |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| Le `X-Request-Id` que j'envoie n'est pas réfléchi   | Valeur non conforme (espace, CR/LF, non-ASCII, > 128) → **rejetée**                | Utiliser `[A-Za-z0-9._-]{1,128}` (UUID/nanoid/traceparent OK) — sinon UUID serveur                |
+| Les logs de fin de requête n'ont pas de `requestId` | Ils sont émis hors bulle ALS                                                       | Déjà géré : l'override `log()` rouvre une micro-bulle (`Context.ts#Context.log`)                  |
+| Réponse HTTP/2 sans `x-request-id`                  | Chemin de réponse h2 distinct du 1.1                                               | Déjà géré (`http2/Response.ts#Http2Response.writeHead`) — le port 5152 réfléchit aussi            |
+| `durationMs: null` dans chaque ligne d'accès        | L'application a posé `timing.enabled: false` (ou `NF__APP__TIMING__ENABLED=false`) | Retirer ce réglage : la durée est mesurée par défaut, production comprise                         |
+| La durée dépasse largement la somme des phases      | Temps passé hors de toute phase : envoi à un client lent, flux encore ouvert       | Attendu — la durée va jusqu'au dernier octet remis ; le travail du serveur se lit dans les phases |
+| `phases` absent des lignes de production            | Les phases sont réservées au développement (coût par borne)                        | `NF__APP__TIMING__ENABLED=true` le temps d'un diagnostic, puis le retirer                         |
+| Pas de `traceparent` renvoyé sur un WebSocket       | `ws` n'expose pas l'écriture d'en-tête au handshake                                | Attendu — la trace WS reste propagée en ALS (`http-kernel.ts#HttpKernel.handleWebsocket`)         |
+| Frame WS binaire loggée en `{"0":..,"1":..}`        | Sérialisation naïve d'un Buffer                                                    | Déjà géré : résumé `[binary N B]` (`wsLogContent.ts#formatWsLogContent`)                          |
+| Le format de log ne change pas malgré la config     | Un `setRequestLogger(...)` programmatique gagne sur la config                      | L'override est volontaire (last setter wins) — retirer l'appel, ou le régler                      |
+| Logs d'audit trop volumineux en prod                | `stack` sérialisée, ou 100 % des 2xx audités                                       | `includeStack:false` (défaut prod) + `sampleRate` via `setRequestLogger`                          |
+| `Authorization`/`Cookie` attendus dans le log JSON  | Redaction : jamais sérialisés                                                      | Par conception — lire les drapeaux `hasAuthorization`/`hasCookie`                                 |
 
 ## 🧪 Tests & couverture
 
@@ -453,6 +530,7 @@ Skills associés : `nodefony-check-memory-health`, `nodefony-load-test`, `nodefo
 
 - ⬆️ **Retour au hub** : [@nodefony/http — vue du module](index.md) · [Toute la documentation](../../../../../docs/index.md)
 - 🧭 **Pages sœurs** : [Serveurs](servers.md) · [Sessions](session.md)
+- Brancher un outil de traçage (OpenTelemetry, Datadog) sur le cycle de chaque requête → [Canal de diagnostic](diagnostics-channel.md)
 - Où partent les logs (stdout, fichier, Loki, OpenSearch) + format RFC 5424 → [Journalisation (Syslog)](../../../../nodefony/docs/syslog.md)
 - Le trajet complet d'une requête (où s'insèrent corrélation et trace) → [pipeline-requete](../../../../../docs/architecture/pipeline-requete.md)
 - Sondes de santé et arrêt gracieux → [Serveurs](servers.md)

package/docs/reverse-proxy.md

@@ -228,16 +228,17 @@ démarrage en la nommant (`proxySchema`, `config.ts#proxySchema`).
 
 Chaque montage (`proxyMountSchema`, `config.ts#proxyMountSchema`) :
 
-| Option         | Type       | Défaut            | Effet                                                                                                                        |
-| -------------- | ---------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `target`       | `string`   | — (requis)        | Origine de l'amont, `http(s)://hôte[:port]`, **sans chemin**.                                                                |
-| `methods`      | `string[]` | toutes            | Méthodes relayées ; une autre méthode suit le routage de l'application.                                                      |
-| `websocket`    | `boolean`  | `false`           | Relaie aussi l'upgrade WebSocket du préfixe.                                                                                 |
-| `stripPrefix`  | `boolean`  | `false`           | Retire le préfixe du chemin transmis ; `Location` est alors ramené sous le préfixe.                                          |
-| `preserveHost` | `boolean`  | `false`           | Transmet le `Host` du client au lieu de celui de la cible.                                                                   |
-| `stripHeaders` | `string[]` | `[]`              | En-têtes de requête à ne pas transmettre (`cookie`, `authorization`…).                                                       |
-| `timeoutMs`    | entier     | `proxy.timeoutMs` | Délai d'inactivité propre au montage, handshake WebSocket compris (jusqu'au `101`). Ne s'applique pas à un WebSocket établi. |
-| `secure`       | `boolean`  | `true`            | Vérifie le certificat d'une cible `https`. `false` n'est accepté que vers la boucle locale.                                  |
+| Option         | Type                  | Défaut            | Effet                                                                                                                        |
+| -------------- | --------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `target`       | `string`              | — (requis)        | Origine de l'amont, `http(s)://hôte[:port]`, **sans chemin**.                                                                |
+| `methods`      | `string[]`            | toutes            | Méthodes relayées ; une autre méthode suit le routage de l'application.                                                      |
+| `websocket`    | `boolean`             | `false`           | Relaie aussi l'upgrade WebSocket du préfixe.                                                                                 |
+| `stripPrefix`  | `boolean`             | `false`           | Retire le préfixe du chemin transmis ; `Location` est alors ramené sous le préfixe.                                          |
+| `preserveHost` | `boolean`             | `false`           | Transmet le `Host` du client au lieu de celui de la cible.                                                                   |
+| `stripHeaders` | `string[]`            | `[]`              | En-têtes de requête à ne pas transmettre (`cookie`, `authorization`…).                                                       |
+| `timeoutMs`    | entier                | `proxy.timeoutMs` | Délai d'inactivité propre au montage, handshake WebSocket compris (jusqu'au `101`). Ne s'applique pas à un WebSocket établi. |
+| `secure`       | `boolean`             | `true`            | Vérifie le certificat d'une cible `https`. `false` n'est accepté que vers la boucle locale.                                  |
+| `accessLog`    | `"all"` \| `"errors"` | `"all"`           | Ligne d'accès des requêtes relayées : toutes, ou seulement celles en échec (statut ≥ 400), avec le statut rendu par l'amont. |
 
 **Refusés au démarrage**, avec le motif (`proxyMountProblems()`, `rules.ts#proxyMountProblems`) :
 
@@ -295,12 +296,13 @@ modules, ses images et le WebSocket du rechargement à chaud partagent alors l'o
 l'application — une IP de réseau local, un téléphone ou un conteneur fonctionnent en HTTPS sans
 réglage.
 
-| Ce qui est fixé par `@nodefony/frontend`        | Pourquoi                                                   |
-| ----------------------------------------------- | ---------------------------------------------------------- |
-| `methods: ["GET", "HEAD"]`                      | un serveur de sources ne sert que des lectures             |
-| `websocket: true`                               | le rechargement à chaud passe par un WebSocket             |
-| `stripHeaders: ["cookie", "authorization"]`     | Vite n'a pas à voir la session de l'application            |
-| cible = le Vite de CETTE application, s'il sert | un port repris par une autre application n'est jamais visé |
+| Ce qui est fixé par `@nodefony/frontend`        | Pourquoi                                                                                  |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `methods: ["GET", "HEAD"]`                      | un serveur de sources ne sert que des lectures                                            |
+| `websocket: true`                               | le rechargement à chaud passe par un WebSocket                                            |
+| `stripHeaders: ["cookie", "authorization"]`     | Vite n'a pas à voir la session de l'application                                           |
+| `accessLog: "errors"`                           | une page charge des centaines de modules ; seuls les échecs méritent une ligne au journal |
+| cible = le Vite de CETTE application, s'il sert | un port repris par une autre application n'est jamais visé                                |
 
 Ce qui se règle reste côté frontend, dans `use("@nodefony/frontend", { … })` : `devHost` (défaut
 `127.0.0.1`, à garder — le navigateur ne joint jamais Vite directement) et `devPort` (défaut `5173`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/http",
-  "version": "10.0.0-beta.4",
+  "version": "10.0.0-beta.5",
   "description": "Serveurs HTTP, HTTPS, HTTP/2 et WebSocket natifs pour Nodefony : sessions, contextes de requête, certificats TLS",
   "author": "Christophe CAMENSULI <ccamensuli@gmail.com>",
   "main": "./dist/index.js",
@@ -72,7 +72,7 @@
     "@types/ws": "8.18.2",
     "@types/xml2js": "0.4.14",
     "@vitest/coverage-v8": "5.0.5",
-    "nodefony": "^10.0.0-beta.4",
+    "nodefony": "^10.0.0-beta.5",
     "tsx": "4.23.15",
     "vitest": "5.0.5"
   },
@@ -80,7 +80,7 @@
   "readmeFilename": "README.md",
   "contributors": [],
   "peerDependencies": {
-    "nodefony": "^10.0.0-beta.4",
+    "nodefony": "^10.0.0-beta.5",
     "zod": "^4.6.7"
   },
   "files": [