Référence d'API — nodefony — syslog

stable

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#

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<void> — Enfile un log (O(1), non-bloquant).
• protected abstract flushBatch(batch: Pdu[]): Promise<void> — Pousse un lot de Pdu vers la destination — implémenté par la sous-classe (format + endpoint spécifiques).
• close(): Promise<void> — Flush final explicite (arrêt gracieux).
• get stats(): BatchTransportStats — Compteurs d’observabilité (drop/échecs/queue).

ConsoleTransport#

class ConsoleTransport implements ITransport

• readonly name = "console"
• constructor(pid?: string)
• send(pdu: Pdu): Promise<void>

FileSink#

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#

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<void> — Écrit la ligne du Pdu à la suite du fichier.
• close(): Promise<void> — Vide la file et ferme le fichier.

HttpTransport#

class HttpTransport implements ITransport

• readonly name = "http"
• constructor(options: HttpTransportOptions)
• send(pdu: Pdu): Promise<void>

LokiTransport#

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<void> — Pousse un lot de Pdu vers la destination — implémenté par la sous-classe (format + endpoint spécifiques).

OpenSearchTransport#

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<void> — Pousse un lot de Pdu vers la destination — implémenté par la sous-classe (format + endpoint spécifiques).

Pdu#

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<Severity, Severity> — 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<string, unknown> | null — Réhydrate un Pdu existant à partir d’une string JSON — mute uniquement ses champs de DONNÉES (PDU_DATA_FIELDS).

Syslog#

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<Severity, number> | null): void — T2 — règle (ou lève) le gate d’entrée par sévérité À CHAUD, sans reboot.
• severityEnabled(severity: number | Exclude<Severity, number>, msgid?: ModuleName): boolean — T2 — un log de cette sévérité franchirait-il le gate d’entrée ?
• setDebugOverride(module: string, level: number | Exclude<Severity, number>, 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<string, number> — Snapshot des overrides de debug ciblé actifs (introspection — endpoint admin, toggle Studio).
• getDebugOverrideExpiry(): Record<string, number> — É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#

class SyslogTransport implements ITransport

• readonly name = "syslog"
• constructor(target: Syslog)
• send(pdu: Pdu): Promise<void>

Fonctions (30)#

accessStatusFamily#

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#

function consoleRequestIds(lines: Iterable<IConsoleLine>): Set<string> | 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#

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#

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#

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#

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#

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#

function findAccessLine<T extends AccessCandidate>(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#

function getActiveLogDriver(): ILogDriver | null

Driver actif (relecture), ou null si aucun n’est encore enregistré/câblé.

getLogDriver#

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#

function getLogDriverFactory(name: string): ILogDriverFactory

Récupère la fabrique d’un driver, ou undefined si non enregistrée.

isConsolePath#

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#

function isLogColorEnabled(): boolean

true si la couleur ANSI est active (gate boot-time).

isToolingRequestId#

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#

function listLogDriverFactories(): string[]

Liste les noms de drivers ayant une fabrique (introspection Studio / CLI).

listLogDrivers#

function listLogDrivers(): { name: string; capabilities: ILogDriver["capabilities"]; }[]

Liste des drivers enregistrés (introspection Studio / tests / data-plane).

parseAccessLine#

function parseAccessLine(pdu: Pick<IPduLike, "msgid" | "payload">): 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#

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#

function pduIsConsoleRequest(line: IConsoleLine, ids: ReadonlySet<string> | 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#

function pduIsConsoleTraffic(pdu: Pick<IPduLike, "msgid" | "payload" | "severity">): 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#

function pduIsModuleExcluded(pdu: Pick<IPduLike, "moduleName" | "msgid" | "payload">, 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#

function pduProtocol(pdu: Pick<IPduLike, "msgid">): 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#

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#

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#

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#

function registerLogDriverFactory(name: string, factory: ILogDriverFactory): void

Enregistre (ou remplace) la fabrique d’un driver par son nom.

resolveColorEnabled#

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#

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#

function setActiveLogDriver(name: string): ILogDriver

Sélectionne le driver actif par nom (relecture des logs).

setLogColor#

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#

const BROWSER_ORIGIN = "browser"

moduleName porté par une entrée de journal venue d’un NAVIGATEUR.

FLOW_STEPS#

const FLOW_STEPS: Record<FlowStepId, FlowStepMeta>

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#

const NULL_LOG_SINK: ILogSink

Sink /dev/null : noop total (bench — mesure du plafond sans I/O de log).

SEVERITY_NAMES#

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#

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#

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#

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#

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#

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#

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#

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#

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#

interface FileTransportOptions

• path: string
• format?: "json" | "text"
• maxPendingBytes?: number — Plafond d’octets en attente d’écriture (défaut 8 Mio).

FlowStepMeta#

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#

interface HttpTransportOptions

• url: string
• headers?: Record<string, string>
• timeout?: number

IAccessLine#

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#

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#

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#

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<ILogQueryResult> — Interroge la destination — chemin FROID (admin/debug), async, JAMAIS dans le pipeline requête.
• probe?(): Promise<ILogDriverProbe> — 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#

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#

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#

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#

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<string, string | number> — Infos utiles à afficher (version, statut cluster, nb d’entrées, endpoint…).

ILogQueryCriteria#

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#

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#

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#

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#

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#

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<string, string> — 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<string, string> — 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#

interface LokiTransportOptions extends BatchTransportOptions

• url: string — Base URL de Loki, ex.
• labels?: Record<string, string> — 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<string, string> — Headers HTTP additionnels (auth proxy, etc.).
• timeoutMs?: number — Timeout du push (ms).
• fetchImpl?: FetchLike — Implémentation fetch (tests / proxy).

OpenSearchLogDriverOptions#

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<string, string> — 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#

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<string, string> — Headers HTTP additionnels.
• timeoutMs?: number — Timeout du bulk (ms).
• fetchImpl?: FetchLike — Implémentation fetch (tests / proxy).

Types (9)#

FetchLike#

type FetchLike = (url: string, init?: FetchInitLike) => Promise<FetchResponseLike>

Signature compatible globalThis.fetch (surface réduite).

FlowStepId#

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#

type ILogDriverFactory = (ctx: ILogDriverContext) => ILogDriverMount | null

Fabrique d’un driver. Retourne null si la config est insuffisante (ex. URL absente).

LogProtocol#

type LogProtocol = "ws" | "http"

Protocole d’origine d’un enregistrement de log.

Message#

type Message = string

Msgid#

type Msgid = string

Pci#

type Pci = unknown

Severity#

type Severity = SeverityKeys | SeverityValues

SeverityName#

type SeverityName = (typeof SEVERITY_NAMES)[number]

Un nom de sévérité RFC 5424.

← Toutes les références d’API