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

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

@@ -111,19 +111,19 @@ Le différenciateur — **HTTP et WebSocket dans le même pipeline** — se retr
 un `requestId`, un `traceparent` et un contrat de logger **uniques** couvrent les deux transports.
 
 **Le `requestId` est un citoyen du contexte, pas un décor.** Il naît dans le constructeur de base
-`Context.requestId = randomUUID()` (`Context.ts:244`), voyage dans l'ALS via `RequestContext.run(...)`
-(`http-kernel.ts:519` pour HTTP, `http-kernel.ts:1960` pour WS), et se lit de n'importe où avec
+`Context.requestId = randomUUID()` (`Context.ts#Context.csrfProtect`), voyage dans l'ALS via `RequestContext.run(...)`
+(`http-kernel.ts#HttpKernel.configureRateLimit` pour HTTP, `http-kernel.ts#HttpKernel.finishWebsocket` pour WS), et se lit de n'importe où avec
 `RequestContext.getRequestId()` — un controller, un service, un adapter ORM, sans jamais le threader.
 
 **La ligne de bilan est branchable.** Le kernel ne code pas un format en dur : il consulte un
-`IRequestLogger` (`IRequestLogger.ts:25`) résolu au boot depuis la config (`applyRequestLoggerFromConfig`,
-`http-kernel.ts:756`), remplaçable à chaud par `httpKernel.setRequestLogger(...)` (`http-kernel.ts:986`).
+`IRequestLogger` (`IRequestLogger.ts#IRequestLogger`) résolu au boot depuis la config (`applyRequestLoggerFromConfig`,
+`http-kernel.ts#HttpKernel.applyRequestLoggerFromConfig`), remplaçable à chaud par `httpKernel.setRequestLogger(...)` (`http-kernel.ts#HttpKernel.setRequestLogger`).
 Trois formateurs sont livrés ; un quatrième maison s'écrit en implémentant l'interface.
 
 **Zero Trust sur l'entrée cliente.** Un `X-Request-Id` fourni par le client finit réfléchi en réponse,
 écrit dans les logs et propagé en ALS — donc une valeur non assainie ouvrirait log-injection (CR/LF) et
 throw natif de `setHeader`. Nodefony **valide puis adopte, ou rejette** (`sanitizeRequestId`,
-`requestId.ts:38`) : jamais nettoyer (masquerait l'abus), toujours retomber sur l'UUID serveur.
+`requestId.ts#sanitizeRequestId`) : jamais nettoyer (masquerait l'abus), toujours retomber sur l'UUID serveur.
 
 ## 🚀 Démarrage rapide
 
@@ -222,84 +222,141 @@ GET  200 /trace/whoami 3.1ms 127.0.0.1                   [demo-abc]
 
 ### Le `requestId` — génération, adoption, réflexion
 
-| Étape               | Où                                                                  | Comportement                                                                                                                                                                            |
-| ------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Génération          | `Context.requestId = randomUUID()` (`Context.ts:244`)               | UUID v4 posé dans le constructeur de base — HTTP **et** WS.                                                                                                                             |
-| Adoption HTTP       | `sanitizeRequestId(headers["x-request-id"])` (`HttpContext.ts:158`) | Remplace l'UUID **si** la valeur cliente est sûre, sinon on garde l'UUID.                                                                                                               |
-| Adoption WS         | `sanitizeRequestId(...)` au handshake (`WebsocketContext.ts:162`)   | Même validation, stable sur toute la durée de la socket (handshake → close).                                                                                                            |
-| Réflexion HTTP/1.1  | `Response.setHeader("x-request-id", …)` (`Response.ts:248`)         | Écrit dans `writeHead()`, sur **chaque** réponse.                                                                                                                                       |
-| Réflexion HTTP/2    | `this.headers["x-request-id"] = requestId` (`http2/Response.ts:71`) | Sinon les réponses du port 5152 sortiraient sans corrélation.                                                                                                                           |
-| ALS (HTTP)          | `RequestContext.run({ requestId, … })` (`http-kernel.ts:519`)       | Ouvre la bulle → tout `Pdu` créé dedans est tagué.                                                                                                                                      |
-| ALS (WS)            | `RequestContext.run({ requestId, … })` (`http-kernel.ts:519`)       | Handshake **et** messages : la bulle ouverte à la connexion est reliée à chaque message par `AsyncResource.bind`, sinon l'identité résolue au handshake se perdrait au premier message. |
-| Capture dans le log | `Pdu.requestId = Pdu.requestIdProvider?.()` (`Pdu.ts:262`)          | Provider injectable branché sur l'ALS côté Node — 0 lecture côté navigateur.                                                                                                            |
+| Étape               | Où                                                                                         | Comportement                                                                                                                                                                            |
+| ------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Génération          | `Context.requestId = randomUUID()` (`Context.ts#Context.csrfProtect`)                      | UUID v4 posé dans le constructeur de base — HTTP **et** WS.                                                                                                                             |
+| Adoption HTTP       | `sanitizeRequestId(headers["x-request-id"])` (`HttpContext.ts#HttpContext.response`)       | Remplace l'UUID **si** la valeur cliente est sûre, sinon on garde l'UUID.                                                                                                               |
+| Adoption WS         | `sanitizeRequestId(...)` au handshake (`WebsocketContext.ts#WebsocketContext.constructor`) | Même validation, stable sur toute la durée de la socket (handshake → close).                                                                                                            |
+| Réflexion HTTP/1.1  | `Response.setHeader("x-request-id", …)` (`Response.ts#HttpResponse.setHeader`)             | Écrit dans `writeHead()`, sur **chaque** réponse.                                                                                                                                       |
+| Réflexion HTTP/2    | `this.headers["x-request-id"] = requestId` (`http2/Response.ts#Http2Response.writeHead`)   | Sinon les réponses du port 5152 sortiraient sans corrélation.                                                                                                                           |
+| ALS (HTTP)          | `RequestContext.run({ requestId, … })` (`http-kernel.ts#HttpKernel.configureRateLimit`)    | Ouvre la bulle → tout `Pdu` créé dedans est tagué.                                                                                                                                      |
+| ALS (WS)            | `RequestContext.run({ requestId, … })` (`http-kernel.ts#HttpKernel.configureRateLimit`)    | Handshake **et** messages : la bulle ouverte à la connexion est reliée à chaque message par `AsyncResource.bind`, sinon l'identité résolue au handshake se perdrait au premier message. |
+| Capture dans le log | `Pdu.requestId = Pdu.requestIdProvider?.()` (`Pdu.ts#Pdu.sysLogSeverity`)                  | Provider injectable branché sur l'ALS côté Node — 0 lecture côté navigateur.                                                                                                            |
 
 > [!IMPORTANT]
 > Les logs de **fin** de requête (bilan `req`, `onClose`) sont émis **hors** de la bulle ALS (déjà
-> refermée). L'override `Context.log()` (`Context.ts:545`) rouvre alors une micro-bulle depuis
+> refermée). L'override `Context.log()` (`Context.ts#Context.log`) rouvre alors une micro-bulle depuis
 > `this.requestId` pour que le `Pdu` capture quand même la corrélation — sinon la ligne d'entrée d'une
 > trace serait la seule à ne PAS porter son `requestId`.
 
 ### La trace W3C — `traceparent`
 
-Nodefony implémente **W3C Trace Context** (le code s'y réfère explicitement, `trace.ts:1`). À l'entrée :
+Nodefony implémente **W3C Trace Context** (le code s'y réfère explicitement, `trace.ts`). À l'entrée :
 
 - Un `traceparent` entrant **valide** est prolongé : on garde `version`/`traceId`/`flags` et on frappe
-  un nouveau `spanId` (on est un maillon enfant) — `resolveTraceparent()` (`trace.ts:83`).
+  un nouveau `spanId` (on est un maillon enfant) — `resolveTraceparent()` (`trace.ts#resolveTraceparent`).
 - Absent ou malformé → on **forge** une trace neuve (`00-<traceId>-<spanId>-01`, échantillonnée).
 - La validation refuse `version=ff` et un `traceId`/`spanId` tout-à-zéro — `parseTraceparent()`
-  (`trace.ts:38`), conforme à la spec (le récepteur NE DOIT PAS propager ces valeurs).
+  (`trace.ts#parseTraceparent`), conforme à la spec (le récepteur NE DOIT PAS propager ces valeurs).
 
-Le `traceparent` résolu est propagé en ALS **et** réfléchi sur la réponse HTTP (`context/http/Response.ts:572`). Côté
+Le `traceparent` résolu est propagé en ALS **et** réfléchi sur la réponse HTTP (`context/http/Response.ts#HttpResponse.writeHead`). Côté
 **WebSocket**, il est propagé en ALS mais **pas** réfléchi dans la réponse de handshake — la bibliothèque
-`ws` n'expose pas proprement ce chemin (`http-kernel.ts:1450`) ; la corrélation reste visible côté serveur.
+`ws` n'expose pas proprement ce chemin (`http-kernel.ts#HttpKernel.finishTeardownHttp`) ; la corrélation reste visible côté serveur.
 
 ### Le contrat de logger — `IRequestLogger`
 
-Le kernel tient un `IRequestLogger` singleton (`http-kernel.ts:334`) et lui délègue le rendu de la ligne
-de bilan, au teardown, via `Context.logRequest()` (`Context.ts:640`) côté HTTP et
-`WebsocketContext.logRequest()` (`WebsocketContext.ts:233`) côté WS. Le contrat a trois méthodes
-(`IRequestLogger.ts:25`) :
+Le kernel tient un `IRequestLogger` singleton (`http-kernel.ts#HttpKernel.secContentTypeOptions`) et lui délègue le rendu de la ligne
+de bilan, au teardown, via `Context.logRequest()` (`Context.ts#Context.logRequest`) côté HTTP et
+`WebsocketContext.logRequest()` (`WebsocketContext.ts#WebsocketContext.logRequest`) côté WS. Le contrat a trois méthodes
+(`IRequestLogger.ts#IRequestLogger`) :
 
 - `renderHttp(context, error?)` → `{ text, severity, msgid }` remis à `context.log()`.
 - `renderWebsocket(context, error?, acceptedProtocol?)` → idem pour le WS.
 - `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
-formatage du contenu est **pur** et **borné** — `formatWsLogContent()` (`wsLogContent.ts:55`), appelé par
-`WebsocketContext.logMessageContent()` (`WebsocketContext.ts:393`) :
+formatage du contenu est **pur** et **borné** — `formatWsLogContent()` (`wsLogContent.ts#formatWsLogContent`), appelé par
+`WebsocketContext.logMessageContent()` (`WebsocketContext.ts#WebsocketContext.logMessageContent`) :
 
-- `string` → tronquée à `WS_LOG_CONTENT_CAP` (4096, `wsLogContent.ts:15`) + ellipse.
+- `string` → tronquée à `WS_LOG_CONTENT_CAP` (4096, `wsLogContent.ts#WS_LOG_CONTENT_CAP`) + ellipse.
 - **binaire** (Buffer, ArrayBuffer, TypedArray, Blob, `Buffer[]`) → résumé `[binary N B]`, **jamais**
-  sérialisé (`binaryByteLength()`, `wsLogContent.ts:27`) — un dump `{"0":..,"1":..}` serait énorme et faux.
+  sérialisé (`binaryByteLength()`, `wsLogContent.ts#binaryByteLength`) — un dump `{"0":..,"1":..}` serait énorme et faux.
 - objet « JSON » → `JSON.stringify` compact tronqué, repli `String(...)` sur cycle/`bigint`.
 
 Le tout est **gaté hors production** : `logMessageContent` court-circuite avant toute construction de
-chaîne quand l'env est `production` (`WebsocketContext.ts:401`) → 0 surcoût sur le hot path WS.
+chaîne quand l'env est `production` (`WebsocketContext.ts#WebsocketContext.broadcast`) → 0 surcoût sur le hot path WS.
 
 ## ⚙️ 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:39`). |
+| 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`. |
 
-`auto` est résolu au boot selon l'environnement (`applyRequestLoggerFromConfig`, `http-kernel.ts:756`) :
+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.
 
-| Valeur    | Formateur              | Rendu                                                                                     |
-| --------- | ---------------------- | ----------------------------------------------------------------------------------------- |
-| `pretty`  | `PrettyRequestLogger`  | 1 ligne colorée `GET 200 /x 12.3ms 127.0.0.1 [a1b2c3d4]` (`pretty-request-logger.ts:34`). |
-| `json`    | `JsonAuditLogger`      | 1 objet JSON canonique par requête (`audit-logger.ts:136`).                               |
-| `default` | `DefaultRequestLogger` | Format legacy verbeux `URL : … FROM : … ID : <uuid>` (`request-logger.ts:21`).            |
+`auto` est résolu au boot selon l'environnement (`applyRequestLoggerFromConfig`, `http-kernel.ts#HttpKernel.applyRequestLoggerFromConfig`) :
+
+| Valeur    | Formateur              | Rendu                                                                                                                 |
+| --------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `pretty`  | `PrettyRequestLogger`  | 1 ligne colorée `GET 200 /x 12.3ms 127.0.0.1 [a1b2c3d4]` (`pretty-request-logger.ts#PrettyRequestLogger.renderHttp`). |
+| `json`    | `JsonAuditLogger`      | 1 objet JSON canonique par requête (`audit-logger.ts#JsonAuditLogger`).                                               |
+| `default` | `DefaultRequestLogger` | Format legacy verbeux `URL : … FROM : … ID : <uuid>` (`request-logger.ts#DefaultRequestLogger.renderHttp`).           |
 
 > [!NOTE]
 > Le **réglage fin** du logger JSON (`sampleRate`, `includeStack`, `maxCauseDepth`, `nominal`) n'est pas
 > un champ déclaré du schéma d'app : il se pose **programmatiquement**, en construisant le logger et en
 > l'injectant — `httpKernel.setRequestLogger(new JsonAuditLogger({ sampleRate: 10 }))` (options :
-> `JsonAuditLoggerOptions`, `audit-logger.ts:92`). L'override programmatique gagne toujours sur la config.
+> `JsonAuditLoggerOptions`, `audit-logger.ts#JsonAuditLoggerOptions`). L'override programmatique gagne toujours sur la config.
 
 ## 🧰 Les trois formateurs (et le contrat)
 
@@ -314,31 +371,42 @@ Choisir en cinq secondes :
 ### `PrettyRequestLogger` — une ligne pour l'humain
 
 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:100`) et `requestId` tronqué aux 8
-premiers caractères (`shortId()`, `pretty-request-logger.ts:116`). La durée est dérivée des phases de
-timing (`pretty-request-logger.ts:116`).
+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 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
 
-Émet un `AuditLogEntry` canonique (`audit-logger.ts:28`) : `ts`, `requestId`, `userIdentifier` (appelant authentifié, posé par le pare-feu sur `context.userIdentifier`), `type`, `method`,
+Émet un `AuditLogEntry` canonique (`audit-logger.ts#AuditLogEntry.ts`) : `ts`, `requestId`, `userIdentifier` (appelant authentifié, posé par le pare-feu sur `context.userIdentifier`), `type`, `method`,
 `url`, `status`, `durationMs`, `remoteAddress`, `host`, `userAgent`, phases, erreur enrichie (nom, code,
 `errorType`, `cause` bornée à 5, stack **dev seulement**). Deux propriétés majeures :
 
 - **Redaction par construction** : `Authorization` et `Cookie` ne sont **jamais** sérialisés — seuls des
-  drapeaux `hasAuthorization`/`hasCookie` le sont (`audit-logger.ts:226`).
-- **Sampling déterministe** : `shouldSample()` (`audit-logger.ts:156`) garde 1 requête nominale sur N mais
+  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
 
-Singleton sans état, 0 allocation par requête (`request-logger.ts:21`). Conserve le format historique
+Singleton sans état, 0 allocation par requête (`request-logger.ts#DefaultRequestLogger.renderHttp`). Conserve le format historique
 `URL : … FROM : … ORIGIN : … ID : <uuid>`, avec `Accept-Protocol` en plus côté WebSocket.
 
 ### Écrire son propre formateur
 
-Implémenter `IRequestLogger` (`IRequestLogger.ts:25`) et l'injecter — NCSA Common Log Format, syslog RFC
-5424 texte, OpenTelemetry logs… `httpKernel.setRequestLogger(monLogger)` (`http-kernel.ts:986`). Les trois
-formateurs et le type sont exportés depuis `@nodefony/http` (`index.ts:221`).
+Implémenter `IRequestLogger` (`IRequestLogger.ts#IRequestLogger`) et l'injecter — NCSA Common Log Format, syslog RFC
+5424 texte, OpenTelemetry logs… `httpKernel.setRequestLogger(monLogger)` (`http-kernel.ts#HttpKernel.setRequestLogger`). Les trois
+formateurs et le type sont exportés depuis `@nodefony/http` (`index.ts`).
 
 ## 🔐 Sécurité
 
@@ -348,15 +416,15 @@ sensibles à la fois — d'où une validation stricte.
 <!-- prettier-ignore -->
 | Menace | Vecteur | Défense |
 | --- | --- | --- |
-| Log injection (CR/LF) | `X-Request-Id: a\r\nFAKE LINE` écrit tel quel dans les logs | Allowlist `[A-Za-z0-9._-]{1,128}` (`requestId.ts:26`) — CR/LF exclus. |
-| Response splitting / DoS | Caractère de contrôle / non-ASCII → throw `setHeader` natif (500) | Même allowlist ; valeur non conforme **rejetée**, pas nettoyée — `sanitizeRequestId()` (`requestId.ts:38`). |
-| Log flooding | `X-Request-Id` géant | Borne `MAX_REQUEST_ID_LENGTH = 128` (`requestId.ts:18`). |
-| Fuite de secret dans l'audit | `Authorization` / `Cookie` sérialisés dans le log JSON | Drapeaux de présence seuls — valeurs jamais écrites (`audit-logger.ts:211`). |
-| Fuite de stack en prod | `error.stack` dans les logs d'audit publics | `includeStack` par défaut `false` en production (`audit-logger.ts:133`). |
+| Log injection (CR/LF) | `X-Request-Id: a\r\nFAKE LINE` écrit tel quel dans les logs | Allowlist `[A-Za-z0-9._-]{1,128}` (`requestId.ts#SAFE_REQUEST_ID`) — CR/LF exclus. |
+| Response splitting / DoS | Caractère de contrôle / non-ASCII → throw `setHeader` natif (500) | Même allowlist ; valeur non conforme **rejetée**, pas nettoyée — `sanitizeRequestId()` (`requestId.ts#sanitizeRequestId`). |
+| Log flooding | `X-Request-Id` géant | Borne `MAX_REQUEST_ID_LENGTH = 128` (`requestId.ts#MAX_REQUEST_ID_LENGTH`). |
+| Fuite de secret dans l'audit | `Authorization` / `Cookie` sérialisés dans le log JSON | Drapeaux de présence seuls — valeurs jamais écrites (`audit-logger.ts#JsonAuditLogger.renderHttp`). |
+| Fuite de stack en prod | `error.stack` dans les logs d'audit publics | `includeStack` par défaut `false` en production (`audit-logger.ts#JsonAuditLogger`). |
 
 > [!WARNING]
 > On **rejette** plutôt que d'assainir un `requestId` invalide : nettoyer donnerait au client un faux
-> contrôle sur l'identifiant et masquerait la tentative d'abus (`requestId.ts:31`).
+> contrôle sur l'identifiant et masquerait la tentative d'abus (`requestId.ts#sanitizeRequestId`).
 
 ## ⚡ Performance & mémoire
 
@@ -364,15 +432,20 @@ La ligne de bilan et la corrélation sont sur le **chemin chaud** : leur coût e
 Les choix visibles dans le code :
 
 - **`requestId` gratuit à l'entropie** — `randomUUID()` de Node met en cache l'entropie (128 UUID/appel
-  système) ; les ids W3C amortissent de même via un pool de 4096 o (`randomHex()`, `trace.ts:66`).
+  système) ; les ids W3C amortissent de même via un pool de 4096 o (`randomHex()`, `trace.ts#randomHex`).
 - **Provider ALS lu paresseusement** — un `Pdu` hors bulle ne paie que 1 test de référence ; le provider
-  reste `null` côté navigateur/debugbar (`Pdu.ts:169`) → 0 lecture, 0 allocation.
+  reste `null` côté navigateur/debugbar (`Pdu.ts#guid`) → 0 lecture, 0 allocation.
 - **Sampling avant rendu** — `shouldSample()` saute la requête **avant** `renderHttp` : 0 objet, 0
-  `toISOString`, 0 `JSON.stringify`, 0 `Pdu` au ring (`audit-logger.ts:156`).
+  `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:104`).
+  (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:393`) ; les events lifecycle ne créent aucun `Pdu` en production (`Context.ts:67`).
+  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`).
 
 Gate mémoire avant tout commit touchant le pipeline : `npm run test:memory` (skill
 `nodefony-check-memory-health`). Rejouer les chiffres de charge : skill `nodefony-load-test`.
@@ -387,10 +460,10 @@ Le `requestId` est la **clé de jointure** de l'admin Studio (dev). Les écrans
 | **Suivi de requête** (`TraceView`) | `/nodefony/syslog/api/logs/search?requestId=…&order=asc` | Toutes les lignes corrélées + le profil serveur (phases, requêtes SQL). |
 | **Logs** (stream) | data plane syslog | Le flux de logs live, filtrable. |
 | **Audit** | écran Audit | Les événements d'audit persistés. |
-| **Profiler** (dev) | `/nodefony/profiler/api/{requestId}` (`ProfilerAdminApi.ts:23`) | Le profil complet (waterfall des phases) d'une requête donnée. |
+| **Profiler** (dev) | `/nodefony/profiler/api/{requestId}` (`ProfilerAdminApi.ts#createProfilerAdminApi`) | Le profil complet (waterfall des phases) d'une requête donnée. |
 
-Le profiler indexe ses instantanés par `requestId` (`Profiler.ts:214`) ; la debug bar lit le
-`X-Request-Id` de son propre appel AJAX et va chercher le profil (`Profiler.ts:14`). Le profiler n'est
+Le profiler indexe ses instantanés par `requestId` (`Profiler.ts#Profiler.collect`) ; la debug bar lit le
+`X-Request-Id` de son propre appel AJAX et va chercher le profil (`Profiler.ts#ProfilePhase`). Le profiler n'est
 instancié **qu'en dev** (fuite d'info + coût en prod).
 
 > [!NOTE]
@@ -403,28 +476,32 @@ instancié **qu'en dev** (fuite d'info + coût en prod).
 <!-- prettier-ignore -->
 | Domaine | Norme | Ancrage |
 | --- | --- | --- |
-| W3C Trace Context (`traceparent`) | W3C Trace Context | `resolveTraceparent()` (`trace.ts:83`), `parseTraceparent()` (`trace.ts:38`) |
-| Sûreté des valeurs d'en-tête (field-value) | RFC 9110 §5.5 | `sanitizeRequestId()` allowlist (`requestId.ts:38`) |
-| En-têtes trop volumineux / borne | anti-abus (log flooding) | `MAX_REQUEST_ID_LENGTH` (`requestId.ts:18`) |
-| Log structuré (PDU, sévérités) | RFC 5424 | `Pdu` + `requestId`/`pid` (`Pdu.ts:184`) |
-| Sévérité dérivée du statut HTTP | RFC 9110 (catégories) | `severityFromStatus()` (`audit-logger.ts:85`) |
-| Non-journalisation des secrets | OWASP (logging) | redaction présence-only (`audit-logger.ts:211`) |
+| W3C Trace Context (`traceparent`) | W3C Trace Context | `resolveTraceparent()` (`trace.ts#resolveTraceparent`), `parseTraceparent()` (`trace.ts#parseTraceparent`) |
+| Sûreté des valeurs d'en-tête (field-value) | RFC 9110 §5.5 | `sanitizeRequestId()` allowlist (`requestId.ts#sanitizeRequestId`) |
+| 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
 > transporte qui est soumise à la sûreté RFC 9110 §5.5.
 
 ## ⚠️ 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:545`)           |
-| Réponse HTTP/2 sans `x-request-id`                  | Chemin de réponse h2 distinct du 1.1                                | Déjà géré (`http2/Response.ts:106`) — 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:1990`)                |
-| 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:63`)                           |
-| 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)