Référence d'API — @nodefony/http — profiler

stable

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#

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#

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#

function aggregateProfiles(entries: Iterable<ProfileEntry>, options?: IProfileAggregatorOptions): IProfileReport

Agrège une liste de profils en une fois.

createProfileAggregator#

function createProfileAggregator(options?: IProfileAggregatorOptions): IProfileAggregator

Crée un accumulateur de profils.

isFailedProfile#

function isFailedProfile(entry: Pick<ProfileEntry, "status" | "error">): 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#

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#

const ACTION_SELF_PHASE = "action.self"

Pseudo-phase : le temps de l’action hors phases imbriquées et hors SQL.

NO_ROUTE#

const NO_ROUTE = "(aucune route)"

Groupe des requêtes qu’aucune route n’a servies (404, statique, sondes).

N_PLUS_ONE_MIN_REPEATS#

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.

const TOOLING_URL_PREFIX = "/nodefony/"

Préfixe de l’espace réservé au framework.

Interfaces (7)#

FrameProfileInit#

interface FrameProfileInit

Descripteur d’ouverture d’une invocation (ce que le pont connaît d’entrée).

• requestId: string — Identifiant du profil — <requestId de la connexion>.<n° de frame>.
• 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#

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#

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#

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#

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#

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#

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<IResolvedRoute, "name"> | null
• readonly controller?: IRouteResolver["controller"]
• readonly actionName?: string

Types (5)#

ProfileEntry#

type ProfileEntry = IProfileEntry

ProfilePhase#

type ProfilePhase = IProfilePhase

ProfileQuery#

type ProfileQuery = IProfileQuery

ProfileSecurity#

type ProfileSecurity = IProfileSecurity

ProfileSummary#

type ProfileSummary = IProfileSummary

← Toutes les références d’API