--- title: "Référence d'API — @nodefony/http — profiler" source: docs/api/http/profiler.md url: https://nodefony.github.io/nodefony-core/docs/api/http/profiler/ --- [Documentation](../../../) › [Référence d'API](../../) › [`@nodefony/http`](../) › profiler > Générée depuis les déclarations de types publiées de `@nodefony/http` **10.0.0-beta.5** : exactement ce que reçoit une application qui l'installe. Cette page n'existe dans aucun dépôt — pour la corriger, on corrige le TSDoc du code. ## `@nodefony/http` `import { … } from "@nodefony/http"` — 22 symboles. ### Classes (2) #### `FrameProfile` ```ts class FrameProfile ``` Profil d'**une invocation** du pont RPC (une frame `api.request`), et non de la connexion qui la porte. - `readonly requestId: string` - `readonly type: ProtocolName` - `readonly scheme: string` - `readonly method: string` - `readonly url: string` - `readonly remoteAddress: string | null` - `readonly traceparent: string | null` - `readonly security: ProfiledArea | null` - `readonly securityTrace: ISecurityTrace | null` - `readonly phases: PhaseTiming[]` — Phases de CETTE frame (vide si le timing est éteint). - `readonly profilerQueries: IProfilerQuery[] | null` — Buffer ORM de CETTE frame — `null` hors profiling. - `get profiled(): boolean` — Ce profil sera-t-il gardé par le Profiler ? - `resolver: ProfiledResolver | null` — Resolver de la frame — porte route / controller / action. - `response: { statusCode: number; } | null` — Statut HTTP-équivalent de l'invocation (200, 403, 404…). - `error: { message: string; } | null` - `constructor(init: FrameProfileInit)` - `stopClock(): number | null` — Arrête l'horloge de la frame (au premier appel) et rend sa durée en ms ; `null` si le timing est éteint. - `phaseStart(name: PhaseName): void` — Ouvre une phase. - `phaseEnd(name: PhaseName): void` — Ferme la DERNIÈRE phase ouverte de ce nom (idempotent). - `finish(status: number, error?: unknown): void` — Fige l'issue de l'invocation (statut + erreur éventuelle) avant collecte. #### `Profiler` ```ts class Profiler implements IProfilerReader ``` Collecteur des profils de requête, en un anneau par provenance (`profileLane`) : l'application, l'outillage, les assets relayés. Chacun évince ses propres profils — ouvrir la console ne chasse plus celui qu'on y consulte. - `constructor(cap?: number, sideCap?: number)` - `collect(ctx: ProfilableContext): void` — Snapshot un `Context` en fin de requête. - `get(requestId: string): ProfileEntry` — Profil complet d'une requête, ou `undefined` si évincé/inconnu. - `recent(limit?: number, connection?: string): ProfileSummary[]` — Résumés des requêtes les plus récentes (récent → ancien), capés à `limit`. - `get cursor(): number` — Dernier numéro d'ordre attribué : le point de départ d'une lecture suivie. - `since(cursor: number): IProfileBatch` — Profils collectés après `cursor`, tous anneaux confondus, dans l'ordre des numéros. - `get size(): number` — Nombre de profils en mémoire. - `clear(): void` — Vide les anneaux. ### Fonctions (4) #### `aggregateProfiles` ```ts function aggregateProfiles(entries: Iterable, options?: IProfileAggregatorOptions): IProfileReport ``` Agrège une liste de profils en une fois. #### `createProfileAggregator` ```ts function createProfileAggregator(options?: IProfileAggregatorOptions): IProfileAggregator ``` Crée un accumulateur de profils. #### `isFailedProfile` ```ts function isFailedProfile(entry: Pick): boolean ``` Une requête en ERREUR du serveur : statut ≥ 500, ou exception levée sans verdict client. Règle unique — le rapport, ses exemples et la lecture de leurs journaux en dépendent. #### `sqlShape` ```ts function sqlShape(sql: string): string ``` Réduit une requête SQL (ou le descripteur d'une commande NoSQL) à sa FORME : valeurs remplacées par `?`, listes de valeurs repliées, blancs compactés. ### Constantes (4) #### `ACTION_SELF_PHASE` ```ts const ACTION_SELF_PHASE = "action.self" ``` Pseudo-phase : le temps de l'action hors phases imbriquées et hors SQL. #### `NO_ROUTE` ```ts const NO_ROUTE = "(aucune route)" ``` Groupe des requêtes qu'aucune route n'a servies (404, statique, sondes). #### `N_PLUS_ONE_MIN_REPEATS` ```ts const N_PLUS_ONE_MIN_REPEATS = 5 ``` Répétitions d'une même forme SQL, dans UNE requête, à partir desquelles on signale un N+1. En dessous, ce sont des boucles courtes légitimes (quelques lectures de configuration, une pagination) qu'on signalerait à tort. #### `TOOLING_URL_PREFIX` > ⚠️ **Déprécié** — Ne dit pas ce qui est de l'outillage : une connexion d'utilisateur (`/nodefony/security/api/auth/…`) ou une route d'application (`/nodefony/test/index`) passent sous ce préfixe. La règle est `isConsolePath` (`nodefony`), que `profileLane` appelle. ```ts const TOOLING_URL_PREFIX = "/nodefony/" ``` Préfixe de l'espace réservé au framework. ### Interfaces (7) #### `FrameProfileInit` ```ts interface FrameProfileInit ``` Descripteur d'ouverture d'une invocation (ce que le pont connaît d'entrée). - `requestId: string` — Identifiant du profil — `.`. - `type: ProtocolName` — Famille du contexte porteur (`context.type` : `websocket`). - `scheme: string` - `method: string` — Méthode LOGIQUE de l'invocation (`GET`, `POST`…), pas le transport. - `url: string` — Chemin invoqué par la frame (avec sa query), pas l'URL de la connexion. - `remoteAddress: string | null` - `traceparent: string | null` - `security: ProfiledArea | null` — Zone firewall de la connexion (l'identité de la frame en découle). - `securityTrace: ISecurityTrace | null` — Décision du firewall au handshake — l'identité que la frame rejoue. - `timing: boolean` — Mesurer les phases ? - `queries: boolean` — Collecter le SQL ? #### `IProfileAggregator` ```ts interface IProfileAggregator ``` Accumulateur : on lui donne les profils un à un, il rend le rapport. - `add(entry: ProfileEntry): boolean` — Ajoute un profil ; `false` s'il a été écarté (outillage). - `result(): IProfileReport` — Le rapport à cet instant ; l'accumulateur continue d'accepter des profils. #### `IProfileAggregatorOptions` ```ts interface IProfileAggregatorOptions ``` Réglages d'une agrégation. - `nPlusOneMinRepeats?: number` — Répétitions à partir desquelles une forme SQL est un N+1. - `includeTooling?: boolean` — Agréger aussi les requêtes de l'outillage (`/nodefony/…`, `/_vite/…`). - `random?: () => number` — Source d'aléa de l'échantillonnage — injectée par les tests. #### `IProfileBatch` ```ts interface IProfileBatch ``` Les profils collectés depuis un curseur. - `entries: ProfileEntry[]` — Profils de numéro supérieur au curseur, du plus ancien au plus récent. - `cursor: number` — Curseur à repasser au prochain appel : le dernier numéro attribué. - `lost: number` — Profils collectés depuis le curseur mais disparus avant d'être lus — évincés par le tampon, ou écrasés par un identifiant réutilisé. #### `IProfilerReader` ```ts interface IProfilerReader ``` Ce qu'un lecteur extérieur (outil de l'agent de code, banc) attend du profileur : suivre les profils au fil de l'eau, ou en retrouver un par son identifiant. Contrat structurel — on le résout par NOM dans le conteneur (`"profiler"`), sans dépendre de la classe. - `readonly cursor: number` — Curseur courant : le passer à `since` pour ne lire que la suite. - `since(cursor: number): IProfileBatch` — Profils collectés depuis `cursor`, et le compte de ceux qui ont été perdus. - `get(requestId: string): ProfileEntry` — Profil complet d'une requête, ou `undefined` si évincé/inconnu. #### `ProfiledArea` ```ts interface ProfiledArea ``` Zone firewall capturée sur le contexte (`SecuredArea`, lue en structurel : `@nodefony/http` ne peut pas importer `@nodefony/security`). - `name?: string` - `security?: boolean` - `mode?: string` - `authenticators?: readonly string[]` #### `ProfiledResolver` ```ts interface ProfiledResolver ``` Ce que le Profiler lit d'un Resolver (route/controller/action) — dérivé de `IRouteResolver`, en lecture seule : tout résolveur du contrat s'y range sans conversion, et les deux types ne peuvent plus diverger. - `readonly route?: Pick | null` - `readonly controller?: IRouteResolver["controller"]` - `readonly actionName?: string` ### Types (5) #### `ProfileEntry` ```ts type ProfileEntry = IProfileEntry ``` #### `ProfilePhase` ```ts type ProfilePhase = IProfilePhase ``` #### `ProfileQuery` ```ts type ProfileQuery = IProfileQuery ``` #### `ProfileSecurity` ```ts type ProfileSecurity = IProfileSecurity ``` #### `ProfileSummary` ```ts type ProfileSummary = IProfileSummary ``` --- [← Toutes les références d'API](../../)