--- title: "Référence d'API — nodefony — syslog" source: docs/api/core/syslog.md url: https://nodefony.github.io/nodefony-core/docs/api/core/syslog/ --- [Documentation](../../../) › [Référence d'API](../../) › [`nodefony`](../) › syslog > Générée depuis les déclarations de types publiées de `nodefony` **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` `import { … } from "nodefony"` — 81 symboles. ### Classes (10) #### `BatchingHttpTransport` ```ts abstract class BatchingHttpTransport implements ITransport ``` Base d'un transport de logs HTTP **batché** — généralise le pattern LB.W (ring borné → drain coalescé → drop borné) à une destination réseau (Loki, OpenSearch). Mutualise toute la mécanique de file/flush/drop/cleanup ; la sous-classe n'implémente QUE `flushBatch` (formatage + push spécifiques). - `abstract readonly name: string` - `constructor(options?: BatchTransportOptions)` - `send(pdu: Pdu): Promise` — Enfile un log (O(1), non-bloquant). - `protected abstract flushBatch(batch: Pdu[]): Promise` — Pousse un lot de Pdu vers la destination — implémenté par la sous-classe (format + endpoint spécifiques). - `close(): Promise` — Flush final explicite (arrêt gracieux). - `get stats(): BatchTransportStats` — Compteurs d'observabilité (drop/échecs/queue). #### `ConsoleTransport` ```ts class ConsoleTransport implements ITransport ``` - `readonly name = "console"` - `constructor(pid?: string)` - `send(pdu: Pdu): Promise` #### `FileSink` ```ts class FileSink implements ILogSink ``` Driver de sink fichier NON bloquant (LB.W). Écrit via `fs.write` async sur un fd persistant ouvert en append (`"a"`) — **un fd PAR worker** (≠ stdout partagé hérité du master), donc sans contention d'inode. - `readonly name = "file"` - `constructor(options: FileSinkOptions)` - `get dropped(): number` — Lignes droppées (buffer saturé) — lu par une sonde, JAMAIS reloggé (récursion). - `writeOut(s: string): void` — Chunk classe-stdout (déjà coalescé par tick). - `writeErr(s: string): void` — stderr (sévérité ≤ 3 — ERROR/CRITIC/ALERT/EMERGENCY) → DURABLE même crash. - `flushSync(): void` — Flush SYNCHRONE de secours (process `exit`). - `close(): void` — Ferme le sink : plus rien n'est accepté, le pending part en SYNC, et le descripteur est rendu — mais **jamais sous une écriture en vol**. #### `FileTransport` ```ts class FileTransport implements ITransport ``` Transport d'écriture vers un fichier : une ligne par `Pdu` (JSONL ou texte), par UN flux d'ajout ouvert paresseusement au premier envoi. - `readonly name = "file"` - `constructor(options: FileTransportOptions)` - `get dropped(): number` — Lignes perdues depuis la création, faute de place dans la file d'écriture. - `send(pdu: Pdu): Promise` — Écrit la ligne du `Pdu` à la suite du fichier. - `close(): Promise` — Vide la file et ferme le fichier. #### `HttpTransport` ```ts class HttpTransport implements ITransport ``` - `readonly name = "http"` - `constructor(options: HttpTransportOptions)` - `send(pdu: Pdu): Promise` #### `LokiTransport` ```ts class LokiTransport extends BatchingHttpTransport ``` Transport de logs vers **Grafana Loki** (LB.4) — push HTTP **batché** sur `POST /loki/api/v1/push`. Étend `BatchingHttpTransport` : la queue/flush/ drop/cleanup sont mutualisés ; ici on ne fait que **formater le lot** au schéma Loki (streams + values) et l'envoyer. - `readonly name = "loki"` - `constructor(options: LokiTransportOptions)` - `protected flushBatch(batch: Pdu[]): Promise` — Pousse un lot de Pdu vers la destination — implémenté par la sous-classe (format + endpoint spécifiques). #### `OpenSearchTransport` ```ts class OpenSearchTransport extends BatchingHttpTransport ``` Transport de logs vers **OpenSearch** (LB.4) — indexation **batchée** via l'API `POST /_bulk` (NDJSON). Étend `BatchingHttpTransport` (queue/flush/drop mutualisés) ; ici on formate le lot au protocole bulk et on l'envoie. - `readonly name = "opensearch"` - `constructor(options: OpenSearchTransportOptions)` - `protected flushBatch(batch: Pdu[]): Promise` — Pousse un lot de Pdu vers la destination — implémenté par la sous-classe (format + endpoint spécifiques). #### `Pdu` ```ts class Pdu ``` - `payload: Pci` - `uid: number` - `severity: number` - `timeStamp: number` - `severityName: keyof typeof SysLogSeverity` - `typePayload: string | null` - `moduleName: ModuleName` - `msgid: Msgid` - `msg: Message` - `status: Status` - `pid: number` — PID du process émetteur (= procid RFC 5424). - `requestId?: string` — Identifiant de la requête en cours (corrélation log↔requête). - `static requestIdProvider: () => string | null` — Provider injectable du `requestId` courant (ALS). - `constructor(pci: Pci, severity?: Severity, moduleName?: ModuleName, msgid?: Msgid, msg?: Message, date?: PduDate)` - `static sysLogSeverity(): Record` — Map bidirectionnelle des sévérités RFC 5424 (`{ INFO: 6, 6: "INFO", ... }`). - `static severityToString(severity: number | string): SeverityName` — Convertit une sévérité numérique ou string en son nom canonique. - `getDate(): string` — Retourne le timestamp formaté `HH:MM:SS GMT±HHMM (TZ Name)`. - `toString(): string` — Sérialise le Pdu en string mono-ligne pour transport console/file. - `parseJson(str: string): Record | null` — Réhydrate un Pdu existant à partir d'une string JSON — mute uniquement ses champs de DONNÉES (`PDU_DATA_FIELDS`). #### `Syslog` ```ts class Syslog extends Event implements ISyslog ``` Hub central de logs structurés de Nodefony — conforme RFC 5424. - `settings: SyslogDefaultSettings` - `burstPrinted: number` - `missed: number` - `invalid: number` - `valid: number` - `errorTotal: number` — Cumul monotone des logs de classe ERREUR (sévérité 0–3 : ERROR/CRITIC/ALERT/EMERGENCY) acceptés depuis la construction. - `criticTotal: number` — Sous-ensemble CRITIQUE (sévérité 0–2 : CRITIC/ALERT/EMERGENCY). - `start: number` - `gated: number` — Nombre de logs court-circuités par le gate de sévérité (T2). - `constructor(settings?: SyslogDefaultSettings)` - `get ringStack(): Pdu[]` - `get bufferCapacity(): number` — Capacité MAX du ring buffer (`settings.maxStack`) — nombre de Pdu que la mémoire peut relire. - `get ringEnabled(): boolean` — `true` si les Pdu sont stockés dans le ring (relecture mémoire active). - `setRingEnabled(enabled: boolean): boolean` — Active/désactive le stockage mémoire (ring) à chaud — outil avancé perf/mémoire. - `get streamEnabled(): boolean` — `true` si la diffusion temps réel (`nodefony:syslog`) est active. - `setStreamEnabled(enabled: boolean): boolean` — Active/désactive la diffusion temps réel (bus `nodefony:syslog`) à chaud. - `setMaxStack(max: number): void` — Redimensionne le ring buffer (capacité de relecture en mémoire) en **préservant** les Pdu déjà présents (tronqués aux `max` plus récents si on rétrécit). - `static formatDebug(debug: DebugType): DebugType` - `init(environment: EnvironmentType, debug?: DebugType, options?: conditionsInterface): void` — Initialise le pipeline Syslog selon environnement + debug. - `static severityFromInput(level: string | number): number | null` — Valide STRICTEMENT une sévérité d'ENTRÉE (nom RFC 5424 ou numérique 0-7) → numéro, ou `null` si invalide. - `static parseDebugSpec(spec: string): { global: boolean; overrides: Array<{ module: string; level: number; }>; }` — Parse une spec `NF__DEBUG` (env runtime) en directives de debug ciblé. - `setSeverityThreshold(threshold: number | Exclude | null): void` — T2 — règle (ou lève) le gate d'entrée par sévérité À CHAUD, sans reboot. - `severityEnabled(severity: number | Exclude, msgid?: ModuleName): boolean` — T2 — un log de cette sévérité franchirait-il le gate d'entrée ? - `setDebugOverride(module: string, level: number | Exclude, ttlMs?: number): void` — Élève à chaud le seuil de verbosité d'UN module (debug ciblé), sans reboot et sans toucher aux autres modules. - `clearDebugOverride(module: string): boolean` — Retire l'override de debug ciblé d'un module (et son timer d'auto-extinction). - `clearAllDebugOverrides(): void` — Retire TOUS les overrides de debug ciblé + leurs timers (retour à 0 coût). - `getDebugOverrides(): Record` — Snapshot des overrides de debug ciblé actifs (introspection — endpoint admin, toggle Studio). - `getDebugOverrideExpiry(): Record` — Échéances (epoch ms) des overrides TEMPORISÉS (introspection — countdown Studio « s'éteint dans X »). - `get async(): boolean` - `set async(value: boolean)` - `clean(): this` — Alias de `reset` — purge ring buffer + listeners. - `reset(): this` — Reset complet — vide le ring buffer ET retire tous les listeners. - `clearLogStack(): void` — Vide uniquement le ring buffer (conserve les listeners attachés). - `pushStack(pdu: Pdu): number` — Push manuel d'un Pdu dans le ring buffer + incrémente compteur `valid`. - `log(payload: Pci, severity?: Severity, msgid?: ModuleName, msg?: Message, moduleName?: ModuleName): Pdu` — Crée un Pdu et le diffuse dans le pipeline (rate-limit → push → fire `"onLog"`). - `getLogStack(start?: number, end?: number, condition?: conditionsInterface): Pdu[] | Pdu` - `getLogs(conditions?: conditionsInterface | null, stack?: Pdu[] | null): Pdu[]` - `logToJson(conditions?: conditionsInterface | null, stack?: Pdu[] | null): string` - `loadStack(stack: Pdu[] | string, doEvent?: boolean, beforeConditions?: (pdu: Pdu, stackItem: Pdu) => void | null): Pdu[]` - `filter(conditions: conditionsInterface, callback: CallbackFunction): void` - `listenWithConditions(conditions: conditionsInterface, callback: CallbackFunction): void` - `error(data: Pci): Pdu` - `warn(data: Pci): Pdu` - `info(data: Pci): Pdu` - `debug(data: Pci): Pdu` - `trace(data: Pci, msgid?: ModuleName, msg?: Message): Pdu` - `print(...args: Pci[]): Pdu` - `logMultiple(severity: Severity, ...args: Pci[]): Pdu` - `addTransport(transport: ITransport): this` - `removeTransport(transport: ITransport): this` — Retire un transport d'écriture et le ferme (`ITransport.close`) : un transport retiré qui garderait son fichier ouvert fuirait un descripteur à chaque ré-initialisation du journal (`Kernel.initializeL … - `get transportCount(): number` — Nombre de transports d'écriture branchés (introspection — data plane Studio, tests d'idempotence). - `listTransports(): { name: string; enabled: boolean; }[]` — Liste polymorphe des transports d'écriture — chaque entrée porte le `name` de l'`ITransport` (`console`, `file`, `loki`, `syslog`…) et son état `enabled`. - `setTransportEnabled(name: string, enabled: boolean): boolean` — Active/désactive un transport d'écriture **à chaud, par nom** (outil dev / diagnostic — ex. - `static wrapper(pdu: Pdu): WrapperResult` - `static normalizeLog(pdu: Pdu, pid?: string): Pdu` — Transport console par défaut — formate un Pdu et l'écrit vers `process.stdout` ou `process.stderr` selon sévérité (ERROR+ vers stderr). - `static rawLog(pdu: Pdu, pid?: string): Pdu` - `static setOutputBuffering(mode: boolean | "auto"): void` — Mode de bufférisation de la sortie console — **process-global** (un seul `process.stdout`). - `static setLineFormat(format: "text" | "json"): void` — Forme des lignes d'écran — **process-global**. - `static get lineFormat(): "text" | "json"` — Forme courante des lignes d'écran (cf `Syslog.setLineFormat`). - `static flushOutput(): void` — Vide immédiatement (synchrone) le buffer stdout en attente. - `static setLogSink(sink: ILogSink | null): void` — Bascule le DRIVER de sink (LB.W — où partent les lignes après coalescing). - `static get logSinkName(): string` — Nom du driver de sink actif (`"stdout"` | `"null"` | `"file"` | custom). - `static get sinkEnabled(): boolean` — `true` si le sink texte écrit (non muté). - `static setSinkEnabled(enabled: boolean): boolean` — Mute/démute le sink texte **à chaud, sans changer la config ni le driver** (outil dev/diagnostic — ex. - `static overrideConsole(instance: Syslog): void` — Intercepte `console.log/warn/error/debug/info` → pipe vers le Syslog passé. - `static restoreConsole(): void` — Restaure `console.log/warn/error/debug/info` à leurs valeurs originales. #### `SyslogTransport` ```ts class SyslogTransport implements ITransport ``` - `readonly name = "syslog"` - `constructor(target: Syslog)` - `send(pdu: Pdu): Promise` ### Fonctions (30) #### `accessStatusFamily` ```ts function accessStatusFamily(status: number | null): number | null ``` La famille d'un statut d'accès, de 1 à 5 comme un statut HTTP — y compris pour un code de fermeture WebSocket (RFC 6455 §7.4), qui sinon passerait pour une erreur serveur à quatre chiffres. #### `consoleRequestIds` ```ts function consoleRequestIds(lines: Iterable): Set | null ``` Les requêtes de la console présentes dans un lot de lignes : celles dont UNE ligne vise la console. Les autres lignes d'une requête ne portent que son `requestId` — c'est par lui qu'on les écarte avec elle. #### `createFileLogDriver` ```ts function createFileLogDriver(options: FileLogDriverOptions): ILogDriver ``` Driver `file` du Log Backplane (LB.2) — destination de logs **JSONL queryable** (persistante, dev/VPS). Chaque ligne est un Pdu sérialisé en forme wire plate (`JSON.stringify`), produit côté WRITE par un transport file `format:"json"` ; ce format plat est aussi celui qu'ingèrent Promtail (Loki) / Filebeat (OpenSearch) sans transformation → le driver file est le tremplin testable vers les drivers prod (LB.4). #### `createLokiLogDriver` ```ts function createLokiLogDriver(options: LokiLogDriverOptions): ILogDriver ``` Driver `loki` du Log Backplane (LB.4) — relit les logs dans **Grafana Loki** via LogQL (`GET /loki/api/v1/query_range`). **Adaptateur, pas moteur** : Loki BORNE le rapatriement (sélecteur de labels + fenêtre temporelle + grep + budget de lignes), puis `filterPdus` est l'**autorité finale** sur le sous-ensemble rapatrié → sémantique EXACTEMENT identique aux drivers `memory`/`file` (inclusion insensible à la casse, ordering `uid`, pagination). Une logique, N façades. #### `createMemoryLogDriver` ```ts function createMemoryLogDriver(source: () => IPduLike[]): ILogDriver ``` Driver `memory` (LB.1) — le **ring buffer du Syslog EST le stockage**. Aucun write dédié : le ring est alimenté par `Syslog.pushStack` sur le hot path. Le driver n'ajoute que la **relecture** (`query`) = `filterPdus` sur un snapshot du ring. #### `createOpenSearchLogDriver` ```ts function createOpenSearchLogDriver(options: OpenSearchLogDriverOptions): ILogDriver ``` Driver `opensearch` du Log Backplane (LB.4) — relit les logs dans **OpenSearch** via `POST /{index}/_search` (Query DSL). **Adaptateur, pas moteur** : OpenSearch borne le rapatriement (range sur `timeStamp` + `sort` desc + budget `size`), puis `filterPdus` est l'**autorité finale** sur le sous-ensemble → sémantique identique aux drivers `memory`/`file`. Une logique, N façades. #### `filterPdus` ```ts function filterPdus(pdus: IPduLike[], criteria?: ILogQueryCriteria): ILogQueryResult ``` Filtre PUR d'un tableau de Pdu selon des critères — **0 I/O, 0 état, testable sans serveur**. C'est LA logique de filtrage du Log Backplane, réutilisée par le driver `memory` (sur `syslog.ringStack`), le futur driver `file` (sur les lignes relues) et la future commande CLI `syslog:filter`. Une logique, trois façades. #### `findAccessLine` ```ts function findAccessLine(rows: readonly T[], method: string, path: string, at: number): T | null ``` Retrouve la ligne d'accès d'une requête vue d'ailleurs — le navigateur, qui n'a pas toujours lu son `X-Request-Id` (document, WebSocket, `EventSource`) : même verbe, même chemin, et la plus proche de l'instant donné quand plusieurs connexions ont visé le même chemin. #### `getActiveLogDriver` ```ts function getActiveLogDriver(): ILogDriver | null ``` Driver actif (relecture), ou `null` si aucun n'est encore enregistré/câblé. #### `getLogDriver` ```ts function getLogDriver(name: string): ILogDriver ``` Récupère un driver ENREGISTRÉ par son nom SANS l'activer — pour le sonder (`probe`) ou l'introspecter avant un switch. `undefined` si non enregistré. #### `getLogDriverFactory` ```ts function getLogDriverFactory(name: string): ILogDriverFactory ``` Récupère la fabrique d'un driver, ou `undefined` si non enregistrée. #### `isConsolePath` ```ts function isConsolePath(path: string): boolean ``` Dit si un chemin est servi à la console d'administration elle-même — la seule règle de chemin du trafic de la console, que la ligne d'accès (`pduIsConsoleTraffic`) et la barre de débogage (qui voit le chemin des requêtes du navigateur) appliquent toutes deux. Une connexion à l'application n'en fait jamais partie. #### `isLogColorEnabled` ```ts function isLogColorEnabled(): boolean ``` `true` si la couleur ANSI est active (gate boot-time). #### `isToolingRequestId` ```ts function isToolingRequestId(requestId: string | null): boolean ``` Cette ligne (ou cette requête) vient-elle d'un appel de l'outillage, marqué par `TOOLING_REQUEST_ID_PREFIX` ? Pure et isomorphe. #### `listLogDriverFactories` ```ts function listLogDriverFactories(): string[] ``` Liste les noms de drivers ayant une fabrique (introspection Studio / CLI). #### `listLogDrivers` ```ts function listLogDrivers(): { name: string; capabilities: ILogDriver["capabilities"]; }[] ``` Liste des drivers enregistrés (introspection Studio / tests / data-plane). #### `parseAccessLine` ```ts function parseAccessLine(pdu: Pick): IAccessLine | null ``` Lit une ligne d'accès (`msgid "req"`) : verbe, statut, chemin, durée — la seule lecture de ce format, que les Journaux de la console et la barre de débogage partagent. #### `pduFlowStep` ```ts function pduFlowStep(pdu: FlowClassifiable): FlowStepId | null ``` Classe un Pdu en **étape de cycle de vie** (id stable) ou `null` si la ligne n'est pas un jalon (log applicatif libre, ex. `DB-DEMO`). PUR, isomorphe, 0 état — réutilisé par le filtre back (`filterPdus`) ET le rendu front (colonne « Étape » + sélecteur) → une SEULE logique, jamais de divergence. #### `pduIsConsoleRequest` ```ts function pduIsConsoleRequest(line: IConsoleLine, ids: ReadonlySet | null): boolean ``` Dit si une ligne appartient au trafic de la console : elle-même (cf `pduIsConsoleTraffic`), une ligne d'un appel marqué par l'outillage (`isToolingRequestId`), ou une ligne d'une requête de la console. #### `pduIsConsoleTraffic` ```ts function pduIsConsoleTraffic(pdu: Pick): boolean ``` Dit si un Pdu est du trafic de la console d'administration — ce que l'exploitant ne cherche pas en lisant les journaux de son application : une ligne qui porte l'URL de la requête (ligne d'accès `msgid "req"`, ou ligne `URL : …` du journal de requête, ouverture et fermeture WebSocket comprises) vers un chemin de la console, ou ce que le serveur Vite écrit sous le niveau WARNING (`msgid "frontend"` : démarrage, rechargement à chaud). #### `pduIsModuleExcluded` ```ts function pduIsModuleExcluded(pdu: Pick, excludedLc: string | null): boolean ``` Dit si une ligne tombe sous l'exclusion d'un module (`excludeModule`) : même nom, sans tenir compte de la casse — sauf la ligne qui porte l'URL de la requête. Celle-ci appartient à l'application même quand le framework l'écrit (le journal d'accès est signé `NODEFONY`) : masquer le framework ne doit jamais masquer les requêtes, sans quoi la vue se vide entièrement. #### `pduProtocol` ```ts function pduProtocol(pdu: Pick): LogProtocol ``` Classe un Pdu par **protocole** d'origine — `"ws"` ou `"http"` — de façon PURE, isomorphe et 0-alloc (une seule comparaison de `msgid`). #### `pduToRecord` ```ts function pduToRecord(pdu: IPduLike): ILogRecord ``` Sérialise un Pdu en `ILogRecord` (forme wire). Source unique de la projection Pdu→wire : réutilisée par `filterPdus` (driver memory) ET par le producteur data-plane `syslog` (framework) — pas de shape dupliqué qui dérive. #### `registerBuiltinLogDrivers` ```ts function registerBuiltinLogDrivers(): void ``` Enregistre les fabriques des drivers NATIFS du Log Backplane dans le registre de fabriques. Idempotent (appelé à chaque `initializeLog`, court-circuité après la 1ʳᵉ fois). C'est ICI — pas dans le Kernel — que vit la connaissance « nom → comment construire ce driver ». Le Kernel ne fait que résoudre + brancher, sans aucun `if (name === …)`. #### `registerLogDriver` ```ts function registerLogDriver(driver: ILogDriver): void ``` Enregistre (ou remplace) un driver par son nom. Si aucun driver actif n'est encore défini, le premier enregistré devient actif (défaut sain). #### `registerLogDriverFactory` ```ts function registerLogDriverFactory(name: string, factory: ILogDriverFactory): void ``` Enregistre (ou remplace) la fabrique d'un driver par son nom. #### `resolveColorEnabled` ```ts function resolveColorEnabled(isTTY: boolean): boolean ``` Applique les conventions d'environnement couleur PAR-DESSUS un signal `isTTY` **déjà résolu** — au boot on passe `Kernel.isTTY` (qui honore déjà `NF_NO_TTY`), sans re-lire `process.stdout`. Conventions : #### `resolveLogPush` ```ts function resolveLogPush(write: boolean, environment: string): boolean ``` L'application envoie-t-elle ELLE-MÊME ses journaux à une destination distante (Loki, OpenSearch) ? Un choix explicite (`write`) gagne toujours. Sans choix : oui en développement, NON en production. #### `setActiveLogDriver` ```ts function setActiveLogDriver(name: string): ILogDriver ``` Sélectionne le driver actif par nom (relecture des logs). #### `setLogColor` ```ts function setLogColor(enabled: boolean): void ``` Active/désactive la couleur ANSI des logs — à appeler **une fois au boot**. Swap les fonctions des slots ; aucun coût par log ensuite. ### Constantes (8) #### `BROWSER_ORIGIN` ```ts const BROWSER_ORIGIN = "browser" ``` `moduleName` porté par une entrée de journal venue d'un NAVIGATEUR. #### `FLOW_STEPS` ```ts const FLOW_STEPS: Record ``` Table des étapes — **source unique** de l'ordre et de l'appartenance protocole, partagée back (filtre) et front (sélecteur groupé HTTP / WebSocket / Commun). #### `NULL_LOG_SINK` ```ts const NULL_LOG_SINK: ILogSink ``` Sink `/dev/null` : noop total (bench — mesure du plafond sans I/O de log). #### `SEVERITY_NAMES` ```ts const SEVERITY_NAMES: readonly [ "EMERGENCY", "ALERT", "CRITIC", "ERROR", "WARNING", "NOTICE", "INFO", "DEBUG" ] ``` Les noms de sévérité RFC 5424, **dans l'ordre de l'enum** (l'index EST la valeur : `SEVERITY_NAMES[3] === "ERROR"`). Les huit niveaux de la RFC, et rien d'autre : une animation de terminal n'est pas un niveau de journal. #### `STDERR_LOG_SINK` ```ts const STDERR_LOG_SINK: ILogSink ``` Sink « sortie d'erreur » : TOUT le journal d'écran part sur `stderr`, la sortie standard restant à un flux que la machine lit — le bilan JSON du serveur de développement (`--output json`), où une seule ligne étrangère casse le `| jq` qui le consomme. #### `SYSLOG_LOG_CHANNEL` ```ts const SYSLOG_LOG_CHANNEL = "nodefony.syslog.log" ``` Nom du canal `node:diagnostics_channel` sur lequel chaque ligne ACCEPTÉE du journal est publiée — forme `module.fonction` de la documentation de Node, comme `nodefony.http.request`. Le message est le `Pdu` lui-même. #### `TOOLING_REQUEST_ID_PREFIX` ```ts const TOOLING_REQUEST_ID_PREFIX = "nf-tooling-" ``` Préfixe des requestId que l'outillage pose LUI-MÊME sur ses appels (la barre de débogage, par `X-Request-Id` — que le serveur adopte tel quel). Ses lignes se reconnaissent ainsi avant même que le serveur ne les écrive, celles qui précèdent la ligne d'accès comprises : l'observation ne s'observe pas, et ne se relance pas sur ce qu'elle a elle-même fait écrire. #### `logColor` ```ts const logColor: ColorMap ``` Helper de couleur partagé — référence STABLE, propriétés mutées par `setLogColor`. Les call-sites font `logColor.cyan("URL")`. ### Interfaces (24) #### `BatchTransportOptions` ```ts interface BatchTransportOptions ``` - `batchSize?: number` — Flush dès que la queue atteint cette taille (coalescence). - `flushIntervalMs?: number` — Flush périodique du reliquat (ms). - `maxQueue?: number` — Plafond DUR de la queue (anti-OOM). #### `BatchTransportStats` ```ts interface BatchTransportStats ``` Compteurs d'observabilité d'un transport batché (introspection / debug). - `dropped: number` — Pdu jetés faute de place (queue saturée = destination trop lente / down). - `failedBatches: number` — Lots dont le push HTTP a échoué (best-effort : on n'empile pas indéfiniment). - `queued: number` — Pdu actuellement en attente de flush. #### `FileLogDriverOptions` ```ts interface FileLogDriverOptions ``` - `path: string` — Chemin du fichier JSONL (1 enregistrement Pdu sérialisé — forme wire — par ligne). - `maxScanBytes?: number` — Plafond d'octets relus depuis la fin du fichier à chaque `query` (anti-OOM). #### `FileSinkOptions` ```ts interface FileSinkOptions ``` - `path: string` — Chemin du fichier de log (ouvert en append, créé si absent — dossier parent créé). - `maxPendingBytes?: number` — Octets max en attente avant DROP borné (anti-OOM). - `sync?: boolean` — Écriture SYNCHRONE directe (`writeSync`) au lieu du buffer async. - `write?: typeof fsWrite` — Écriture asynchrone employée par le drain. #### `FileTransportOptions` ```ts interface FileTransportOptions ``` - `path: string` - `format?: "json" | "text"` - `maxPendingBytes?: number` — Plafond d'octets en attente d'écriture (défaut 8 Mio). #### `FlowStepMeta` ```ts interface FlowStepMeta ``` Métadonnée **structurelle** d'une étape (jamais de présentation : libellé FR et couleur vivent côté front, qui mappe l'`id`). `order` = rang logique dans le cycle de SON protocole ; `protocol` = où l'étape apparaît (`"both"` = session). - `order: number` — Rang logique dans le cycle (tri du sélecteur d'étapes). - `protocol: LogProtocol | "both"` — Protocole d'appartenance — pilote le sélecteur adaptatif côté Studio. #### `HttpTransportOptions` ```ts interface HttpTransportOptions ``` - `url: string` - `headers?: Record` - `timeout?: number` #### `IAccessLine` ```ts interface IAccessLine ``` Une ligne d'accès lue : ce qu'il faut voir d'une requête d'un coup d'œil. - `method: string` — `GET`, `POST`… ou `WS` pour une connexion WebSocket. - `status: number | null` — Statut HTTP, ou code de fermeture WebSocket (`1000`…) sur une ligne `WS` ; `null` quand la ligne n'en porte pas (`---`). - `path: string` — Chemin et requête (`/api/users?page=2`), sans schéma ni hôte. - `url: string` — L'URL telle qu'écrite (`wss://h/socket`), schéma et hôte compris. - `duration: string | null` — Durée telle qu'écrite (`3.21ms`), `null` si absente. - `ip: string | null` — Adresse du client, `null` si absente. #### `ILogChannel` ```ts interface ILogChannel ``` Le canal de publication vu par le journal : le sous-ensemble du `Channel` de `node:diagnostics_channel` qu'il emploie. Structurel, pour que ce fichier n'importe pas `node:diagnostics_channel` (il sert aussi le navigateur) : le barrel Node branche le vrai canal par `setLogChannel`. - `readonly hasSubscribers: boolean` — `true` dès qu'un abonné écoute — LA garde du chemin chaud. - `publish(message: Pdu): void` — Remet la ligne à chaque abonné, de façon synchrone. #### `ILogConfigLike` ```ts interface ILogConfigLike ``` Sous-ensemble de `config.log` lu par les fabriques — évite une dépendance des drivers au type complet du Kernel (qui, lui, importe les drivers). - `queryFile?: { path?: string; maxScanBytes?: number; }` - `loki?: LokiDestinationConfig` — Même forme que la config publique : une seule déclaration, aucune dérive. - `opensearch?: OpenSearchDestinationConfig` — Même forme que la config publique : une seule déclaration, aucune dérive. #### `ILogDriver` ```ts interface ILogDriver ``` Contrat du **Log Backplane** (axe DESTINATION queryable, LB.0). - `readonly name: string` — Nom unique du driver (`"memory"` | `"file"` | `"elastic"` | custom). - `readonly capabilities: ILogDriverCapabilities` — Ce que le driver sait faire (pilote l'UI Studio + le contrat data-plane). - `query?(criteria: ILogQueryCriteria): Promise` — Interroge la destination — chemin **FROID** (admin/debug), `async`, **JAMAIS** dans le pipeline requête. - `probe?(): Promise` — Sonde de SANTÉ de la destination (chemin FROID, admin) — « est-ce que la cible répond, en combien de temps, et quelques infos utiles ? #### `ILogDriverCapabilities` ```ts interface ILogDriverCapabilities ``` Capacités déclarées d'un driver (introspection Studio + garde-fous endpoint). - `readonly write: boolean` — Le driver persiste les Pdu (≠ ring volatile). - `readonly query: boolean` — Le driver expose `query()` (relecture filtrée). - `readonly stream: boolean` — Le driver peut alimenter un flux temps réel (tap `onLog`). #### `ILogDriverContext` ```ts interface ILogDriverContext ``` Contexte passé à une fabrique de driver (tout ce qu'il faut pour se construire). - `logCfg: ILogConfigLike` — Config `log` de l'app (sous-ensemble lu par les fabriques). - `environment: string` — Environnement courant (`development` | `production` | …). - `logDir: string` — Répertoire ABSOLU des fichiers de log. - `pid: number` — PID du process courant (nom de fichier par worker). - `appName?: string` — Nom de l'application (nom de son paquet), quand elle est chargée — étiquette par défaut des destinations distantes, pour que deux applications d'un même Loki ne se confondent pas. - `getRingStack: () => IPduLike[]` — Fournit le ring buffer courant à la demande (driver `memory`, lazy). #### `ILogDriverMount` ```ts interface ILogDriverMount ``` Ce qu'une fabrique retourne : le driver de RELECTURE + (optionnel) le transport d'ÉCRITURE à brancher. `writeKey` déduplique le transport quand plusieurs drivers partagent la même destination d'écriture (ex. `file` ↔ `cluster-file` = même JSONL). - `driver: ILogDriver` - `transport?: ITransport` - `writeKey?: string` #### `ILogDriverProbe` ```ts interface ILogDriverProbe ``` Résultat d'une `ILogDriver.probe` — santé d'une destination de logs. Affiché par Studio (badge joignable/latence + infos) ; jamais de credential. - `ok: boolean` — `true` si la destination répond correctement. - `latencyMs: number` — Latence aller-retour de la sonde (ms). - `detail?: string` — Message d'erreur si `ok === false` (jamais de secret). - `info?: Record` — Infos utiles à afficher (version, statut cluster, nb d'entrées, endpoint…). #### `ILogQueryCriteria` ```ts interface ILogQueryCriteria ``` Critères de requête — tous optionnels, combinés en **AND**. Vide = tout (borné par `limit`). Les comparaisons string sont insensibles à la casse. `requestId` matche **exactement** (trace full-stack ciblée d'UNE requête) ; `module`/`msgid`/ `text` matchent par **inclusion**. - `requestId?: string` — Corrélation log↔requête (ALS) — match EXACT. - `severity?: string | string[]` — Nom(s) de sévérité RFC 5424 (`"ERROR"` ou `["ERROR","CRITIC"]`). - `module?: string` — Nom de module/service — inclusion insensible à la casse. - `msgid?: string` — Catégorie de message (msgid) — inclusion insensible à la casse. - `excludeModule?: string` — Nom de module EXCLU — égalité insensible à la casse (ex. - `from?: number` — Borne basse du `timeStamp` (epoch ms, inclus). - `to?: number` — Borne haute du `timeStamp` (epoch ms, inclus). - `text?: string` — Recherche plein-texte (payload string + msg + module + msgid). - `protocol?: "ws" | "http"` — Protocole d'origine du log : - `"ws"` : logs émis dans un contexte WebSocket (`msgid === "WEBSOCKET CONTEXT"`) ; - `"http"` : tout le reste du pipeline (requête HTTP, router, firewall, applicatif). - `flow?: FlowStepId | FlowStepId[]` — Étape(s) du cycle de vie d'une requête/connexion — classification STRUCTURÉE (cf `pduFlowStep`), pas une recherche texte. - `hideConsole?: boolean` — `true` = écarte les lignes d'accès servies à la console d'administration (relais Vite, pages et data plane `/nodefony`), cf `pduIsConsoleTraffic`. - `groupByRequest?: boolean` — `true` = une ligne par requête (`requestId`) : sa ligne d'accès quand elle existe, sinon la première dans l'ordre demandé, avec `lines` = le nombre de lignes regroupées. - `limit?: number` — Nombre max d'enregistrements renvoyés (le driver borne à un plafond sûr). - `offset?: number` — Décalage de pagination (depuis le plus récent). - `order?: "asc" | "desc"` — Ordre chronologique des `rows` : - `"desc"` (DÉFAUT) : du plus RÉCENT au plus ancien (entrée naturelle d'un viewer) ; - `"asc"` : du plus ANCIEN au plus récent (lecture chronologique d'une trace). #### `ILogQueryResult` ```ts interface ILogQueryResult ``` Résultat d'une requête : enregistrements (récents d'abord) + méta de pagination. - `rows: ILogRecord[]` — Enregistrements du plus RÉCENT au plus ancien, après `offset`/`limit`. - `total: number` — Nombre total d'enregistrements qui matchent les critères (avant pagination). - `truncated: boolean` — `true` s'il reste des résultats au-delà de la fenêtre renvoyée. #### `ILogRecord` ```ts interface ILogRecord ``` Forme **wire** d'un Pdu (isomorphe) — sérialisation stable partagée par TOUTES les façades (endpoint data-plane, canal `nodefony:syslog`, drivers). Le front réhydrate via `Object.assign(new Pdu(""), record)` → une seule logique de rendu. Produite par `pduToRecord`. - `uid: number` - `severity: number` - `severityName: string` - `moduleName: string` - `msgid: string` - `msg: string` - `timeStamp: number` - `pid: number` — PID émetteur (procid RFC 5424) — groupe par worker en cluster. - `requestId?: string` — Corrélation requête (ALS) si présent. - `payload: unknown` — Contenu brut (string/Error/objet). - `lines?: number` — Lignes regroupées sous cette requête (`groupByRequest`), elle comprise. #### `ILogSink` ```ts interface ILogSink ``` - `readonly name: string` - `writeOut(s: string): void` — Chunk classe-stdout (déjà coalescé par tick). - `writeErr(s: string): void` — Chunk classe-stderr (sévérité ≤ 3 — durable). - `flushSync(): void` — Flush SYNCHRONE de secours (process `exit`). - `close(): void` — Libère les ressources (fd…). #### `IPduLike` ```ts interface IPduLike ``` Sous-ensemble des champs d'un `Pdu` lus par `filterPdus` et `pduToRecord`. Permet de filtrer/projeter SANS instancier un `Pdu` — son constructeur incrémente un compteur d'`uid` et lit le `requestIdProvider`, donc effets de bord à proscrire lors d'une simple RELECTURE. Un `Pdu` le satisfait structurellement ; un enregistrement relu d'un fichier JSONL (driver `file`, LB.2) aussi → une SEULE logique de filtrage pour memory, file et le futur CLI. - `uid: number` - `severity: number` - `severityName: string` - `moduleName: string` - `msgid: string` - `msg: string` - `timeStamp: number` - `pid: number` - `payload: unknown` - `requestId?: string` #### `LokiLogDriverOptions` ```ts interface LokiLogDriverOptions ``` - `url: string` — Base URL de Loki, ex. - `write?: boolean` — `false` = relecture SEULE : les flux sont poussés par un COLLECTEUR, qui ne pose pas l'étiquette `severity` → la sévérité se filtre sur la LIGNE JSON. - `labels?: Record` — Labels de sélecteur de base (mêmes que le transport). - `tenantId?: string` — Tenant multi-tenancy → header `X-Scope-OrgID`. - `username?: string` — Utilisateur de l'authentification basique (Grafana Cloud : l'identifiant de l'instance). - `password?: string` — Mot de passe de l'authentification basique (Grafana Cloud : un jeton d'accès). - `headers?: Record` — Headers HTTP additionnels. - `maxScanLines?: number` — Budget de scan : nombre max de lignes RAPATRIÉES de Loki avant filtrage local (chemin admin FROID, anti-OOM). - `defaultLookbackMs?: number` — Fenêtre temporelle par défaut quand `from`/`to` sont absents (ms avant `now`). - `timeoutMs?: number` — Timeout de la query (ms). - `fetchImpl?: FetchLike` — Implémentation `fetch` (tests / proxy). #### `LokiTransportOptions` ```ts interface LokiTransportOptions extends BatchTransportOptions ``` - `url: string` — Base URL de Loki, ex. - `labels?: Record` — Labels de STREAM constants (basse cardinalité). - `tenantId?: string` — Tenant multi-tenancy → header `X-Scope-OrgID`. - `username?: string` — Utilisateur de l'authentification basique (Grafana Cloud : l'identifiant de l'instance). - `password?: string` — Mot de passe de l'authentification basique (Grafana Cloud : un jeton d'accès). - `headers?: Record` — Headers HTTP additionnels (auth proxy, etc.). - `timeoutMs?: number` — Timeout du push (ms). - `fetchImpl?: FetchLike` — Implémentation `fetch` (tests / proxy). #### `OpenSearchLogDriverOptions` ```ts interface OpenSearchLogDriverOptions ``` - `url: string` — Base URL d'OpenSearch, ex. - `index?: string` — Index interrogé (défaut `nodefony-logs`). - `username?: string` — Utilisateur (auth basic) — prod avec plugin sécurité activé. - `password?: string` — Mot de passe (auth basic). - `headers?: Record` — Headers HTTP additionnels. - `maxHits?: number` — Budget de scan : nombre max de documents RAPATRIÉS (`size`) avant filtrage local (chemin admin FROID, anti-OOM). - `timeoutMs?: number` — Timeout de la query (ms). - `fetchImpl?: FetchLike` — Implémentation `fetch` (tests / proxy). #### `OpenSearchTransportOptions` ```ts interface OpenSearchTransportOptions extends BatchTransportOptions ``` - `url: string` — Base URL d'OpenSearch, ex. - `index?: string` — Index cible (défaut `nodefony-logs`). - `username?: string` — Utilisateur (auth basic) — prod avec plugin sécurité activé. - `password?: string` — Mot de passe (auth basic). - `headers?: Record` — Headers HTTP additionnels. - `timeoutMs?: number` — Timeout du bulk (ms). - `fetchImpl?: FetchLike` — Implémentation `fetch` (tests / proxy). ### Types (9) #### `FetchLike` ```ts type FetchLike = (url: string, init?: FetchInitLike) => Promise ``` Signature compatible `globalThis.fetch` (surface réduite). #### `FlowStepId` ```ts type FlowStepId = "request-in" | "body-received" | "route-matched" | "kernel-dispatch" | "response" | "request-end" | "finish" | "ws-open" | "ws-message" | "ws-close" | "session" | "session-saved" ``` **Étape logique du cycle de vie d'une requête / connexion** — identifiant STABLE (clé de filtre côté back ET clé de mapping libellé/couleur côté front). #### `ILogDriverFactory` ```ts type ILogDriverFactory = (ctx: ILogDriverContext) => ILogDriverMount | null ``` Fabrique d'un driver. Retourne `null` si la config est insuffisante (ex. URL absente). #### `LogProtocol` ```ts type LogProtocol = "ws" | "http" ``` Protocole d'origine d'un enregistrement de log. #### `Message` ```ts type Message = string ``` #### `Msgid` ```ts type Msgid = string ``` #### `Pci` ```ts type Pci = unknown ``` #### `Severity` ```ts type Severity = SeverityKeys | SeverityValues ``` #### `SeverityName` ```ts type SeverityName = (typeof SEVERITY_NAMES)[number] ``` Un nom de sévérité RFC 5424. --- [← Toutes les références d'API](../../)