Référence d'API — nodefony — realtime-platformHealth

stable

Documentation › Référence d’API › nodefony › realtime-platformHealth

Générée depuis les déclarations de types publiées de nodefony 10.0.0-beta.6 : 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" — 11 symboles.

Interfaces (10)#

IBackplaneInfo#

interface IBackplaneInfo

Carte d’identité d’un backplane — descripteur de DONNÉE (pas un log) décrivant l’état du fond de panier. Source unique alimentant trois sorties cohérentes : la ligne stdout au boot, le champ backplane de la sonde (/api/health) et la vue Studio. Réutilisable par les tests / un agent IA sans dupliquer la connaissance « c’est quoi ce backplane ».

• driver: string — Nom du driver (clé du registre).
• kind: string — Nature du transport.
• originId: string — Identité de CE pair (process/pod).
• crossPod: boolean — true si le fan-out franchit les frontières de pod (multi-host).
• channel?: string — Canal/topic de transport, si applicable (canal Redis, topic Kafka).
• sealed?: boolean — Les messages sont-ils scellés (authenticité de l’émetteur vérifiée) ?
• sealRejectedTotal?: number — Messages reçus du bus dont le sceau est refusé — unité : un message reçu d’un exemplaire, jeté parce que son sceau ne se vérifie pas (ADR-0021 S6, S9).
• queue?: IBackplaneQueueInfo — État de la file d’envoi vers le bus (octets en vol, seuil, jetés).
• bytes?: boolean — Les octets d’une charge traversent-ils le bus intacts (IBackplane.enableBytes) ?

IBackplaneQueueInfo#

interface IBackplaneQueueInfo

Compteurs de la file d’envoi d’un backplane à transport réseau : ce qui est publié mais pas encore acquitté par le bus. Sans borne, cette file (interne au client réseau) grossit sans limite sous rafale — d’où le seuil et ses compteurs, exposés jusqu’à la sonde et Studio. Cf BackplanePublishQueue.

• bytes: number — Octets publiés en attente d’acquittement par le transport (instantané).
• maxBytes: number — Seuil au-dessus duquel une publication est jetée ; 0 = illimité.
• droppedTotal: number — Publications JETÉES faute de place (monotone).
• failedTotal: number — Publications REFUSÉES par le transport (bus coupé…) (monotone).

IInstanceErrorHealth#

interface IInstanceErrorHealth

Santé erreurs per-instance — compteurs Syslog monotones (cf Syslog.errorTotal / Syslog.criticTotal). Permet une carte « erreurs par worker » + un taux d’erreur pod (delta côté lecteur). Lecture pure d’entiers, 0 scan du ring buffer.

• errorTotal: number — Logs ERROR/CRITIC/ALERT/EMERGENCY cumulés (sévérité 0–3) (monotone).
• criticTotal: number — Sous-ensemble CRITIQUE : CRITIC/ALERT/EMERGENCY (sévérité 0–2) (monotone).

IOrmLeanHealth#

interface IOrmLeanHealth

Santé ORM agrégée per-instance (lean) — somme process-wide de tous les connecteurs enregistrés, dérivée des singletons queryFlowMonitor + connectionMonitor (0 ping, 0 toSQL, O(N connecteurs)). Rejoint le report de sonde du worker à chaque tick (≥ 1 s). Tous les cumuls sont monotones → débit/s dérivé côté lecteur (delta/ts, comme le CPU%).

• connectors: number — Connecteurs ORM enregistrés (registre).
• connected: number — Connecteurs actuellement connectés (isConnected()).
• assumed: number — Parmi les connectés, ceux dont l’état est SUPPOSÉ et non constaté : leur adapter n’a aucun signal de cycle de vie à traduire (base embarquée, driver muet), donc « connecté » y veut seulement dire …
• queryTotal: number — Requêtes ORM cumulées, tous connecteurs (monotone ; 0 si flux OFF en prod).
• slowTotal: number — Requêtes lentes cumulées (au-dessus du seuil slowMs) (monotone).
• errorTotal: number — Erreurs de connexion ORM cumulées (monotone).
• reconnectTotal: number — Reconnexions ORM cumulées (monotone).
• maxEwmaMs: number | null — Pire latence EWMA (ms) parmi les connecteurs (instantané), ou null si non observé.

IProcessHealth#

interface IProcessHealth

Santé PROCESS d’un worker — lue par ProcessProbe, agrégée par worker dans le snapshot pod (cf ClusterProbeAggregator). Volontairement lean (sérialisée par worker à chaque tick de report ≥ 1 s) : juste de quoi peupler une grille « salle des machines » (1 carte/worker). Les sondes lourdes (GC, heap-spaces, ctx-switches) restent au canal nodefony:supervision per-process pour le drill-down.

• pid: number — PID du worker (= instanceId de la vue pod).
• uptime: number — Uptime du process (secondes).
• cpuPercent: number — % d’UN cœur sur l’intervalle (comme top : un Node mono-thread sature ~100).
• eventLoopMs: number — Retard moyen de la boucle sur l’intervalle (ms), période d’échantillonnage retranchée : 0 sur une boucle libre.
• eventLoopMaxMs: number — Pire retard de la boucle sur l’intervalle (ms) : le plus long blocage.
• eluUtilization: number — Saturation de la boucle (ELU) sur l’intervalle, 0–1 (~1 = thread saturé).
• rss: number — Resident Set Size (octets).
• heapUsed: number — Heap V8 utilisé (octets).
• heapTotal: number — Heap V8 total (octets).
• heapLimit: number — Plafond heap V8 (octets, constant) — pour heapUsed/heapLimit (% avant OOM).
• external: number — Mémoire hors-heap (buffers, etc.) (octets).
• ts: number — Horodatage de la mesure.

IProcessRich#

interface IProcessRich

Sonde process riche d’un worker — le complément du lean IProcessHealth pour le drill-down (Phase 2). Ne contient QUE ce qui manque au lean : pression GC, répartition du heap V8, ressources actives, ELU active/idle (ms) et changements de contexte OS. Fusionné côté front avec le lean déjà présent dans le snapshot pod.

• gc: { count: number; pauseMs: number; major: number; minor: number; } — Pression GC sur l’intervalle (cycles, pause totale ms, majeurs/mineurs).
• heapSpaces: { name: string; used: number; size: number; }[] — Répartition mémoire V8 par espace (new/old/code/large_object…), octets.
• handles: { total: number; byType: Record<string, number>; } — Ressources actives qui tiennent la boucle, total + par type.
• elu: { active: number; idle: number; } — Saturation de la boucle sur l’intervalle (ms actifs / idle ; utilization est dans le lean).
• ctx: { voluntary: number; involuntary: number; } — Changements de contexte OS sur l’intervalle (volontaires = cède, involontaires = préempté).
• loadavg: [ number, number, number ] — Load average système (1/5/15 min).
• heapLimit: number — Limite de heap V8 du process (octets) — constante.
• cpuCount: number — Nombre de cœurs vus par le process — constante.
• ts: number — Horodatage de la mesure.

IRealtimeChannelStat#

interface IRealtimeChannelStat

Stat per-canal du hub (fan-out).

• channel: string — Nom du canal (suffixe :<ms> de granularité inclus).
• subscribers: number — Abonnés locaux vivants (sinks) — instantané.
• messages: number — Publications cumulées sur ce canal (monotone) → débit dérivé côté lecteur.

IRealtimeClusterHealth#

interface IRealtimeClusterHealth

Vue POD agrégée de la socket (mode cluster) — la santé de TOUS les workers du pod consolidée. Servie par n’importe quel worker via l’endpoint santé quand le master pousse le snapshot agrégé (sinon on retombe sur IRealtimeHealth per-instance).

• cluster: true — Discriminant : vue agrégée multi-worker (≠ IRealtimeHealth per-instance).
• ts: number — Horodatage du snapshot agrégé (ms epoch).
• instanceCount: number — Nombre de workers présents dans l’agrégat.
• instances: IRealtimeHealth[] — Santé par worker (détail per-instance pour le drill-down).
• totals: { channelCount: number; publishTotal: number; fanoutTotal: number; inboundTotal: number; ingressRejectedTotal: number; localOnlyTotal: number; connectionCount: number; bytesSentTotal: number; … — Totaux pod (sommes des scalaires ; backpressure max = pire worker).

IRealtimeHealth#

interface IRealtimeHealth extends IRealtimeProbe

Snapshot enrichi de l’identité d’instance — santé per-instance d’un worker/pod.

• instanceId: string — Identifiant de CE process/pod (per-instance).
• process?: IProcessHealth — Santé PROCESS du worker (CPU/mém/event-loop) — additif : la grille « salle des machines » de la vue pod lit instances[].process par worker.
• rich?: IProcessRich — Sonde process riche (GC/heap-spaces/handles/ELU active-idle/ctx-switches) — présente UNIQUEMENT pendant un drill-down de CE worker (le master a envoyé nf:probe:enrich à ce pid).
• orm?: IOrmLeanHealth — Santé ORM lean du worker (connecteurs/requêtes/erreurs/latence EWMA) — additif, comme process.
• errors?: IInstanceErrorHealth — Compteurs d’erreurs Syslog du worker (ERROR/CRITIC cumulés) — additif.
• backplaneDrivers?: string[] — Drivers de backplane enregistrés dans ce process (clés du registre ouvert : natifs + ceux qu’une application a ajoutés par registerBackplaneDriver).
• ormRich?: unknown — Diagnostic ORM riche du worker (par connecteur : ping/latence/stockage/pool + flux requêtes) — blob OPAQUE { health, flow } produit par le driver, présent UNIQUEMENT pendant un drill ORM de CE w …

IRealtimeProbe#

interface IRealtimeProbe

Snapshot PUR du hub (sans identité process) — ce que renvoie RealtimeHub.probe(). Per-instance/pod (cloud-native) ; l’agrégat multi-pod = backplane Redis / Prometheus.

• ts: number — Horodatage du snapshot (ms epoch) — base du calcul de débit côté lecteur.
• channels: IRealtimeChannelStat[] — Canaux actifs (≥ 1 abonné) avec abonnés + publications cumulées.
• channelCount: number — Nombre de canaux actifs (= 1 provider/canal/pod).
• publishTotal: number — Appels publish cumulés (monotone).
• fanoutTotal: number — Livraisons cumulées (publish × abonnés) — vrai coût de fan-out (monotone).
• inboundTotal: number — Frames entrantes full-duplex cumulées (canaux gated SIP/bridge) (monotone).
• ingressRejectedTotal: number — Messages d’ingress backplane REFUSÉS (canal non déclaré broadcast) — monotone.
• localOnlyTotal: number — Publications restées sur CE serveur alors qu’un bus est branché — canal non déclaré diffusable (@RealtimeBroadcast) — monotone ; toujours 0 sans bus.
• systemFloorDeniedTotal: number — Abonnements clients REFUSÉS par le plancher des canaux de plateforme — monotone.
• sealRejectedTotal: number — Messages du bus REFUSÉS parce que leur sceau ne se vérifie pas — monotone, unité : un message reçu d’un exemplaire.
• frameRateRejectedTotal: number — Trames entrantes ÉCARTÉES par la borne de débit, avant tout décodage — monotone, unité : une trame reçue.
• allowTimedOutTotal: number — Appels d’allow restés SANS RÉPONSE dans allowTimeoutMs — monotone, unité : un appel d’allow.
• allowSaturatedTotal: number — Demandes d’abonnement rendues unavailable SANS appel d’allow — monotone, unité : une demande.
• authenticateTimedOutTotal: number — Poignées de main fermées en 1013 faute d’authentification dans authenticateTimeoutMs — monotone, unité : une poignée de main.
• binaryDiscardedTotal: number — Trames BINAIRES reçues et écartées faute de lecteur — monotone, unité : une trame reçue.
• malformedDiscardedTotal: number — Trames reçues et écartées parce qu’illisibles par le codec de la connexion — JSON invalide, CBOR tronqué — monotone, unité : une trame reçue.
• connectionCount: number — Connexions realtime vivantes.
• bytesSentTotal: number — Somme cumulée des octets envoyés, toutes connexions, fermées comprises (monotone).
• messagesSentTotal: number — Somme cumulée des frames envoyées, toutes connexions, fermées comprises (monotone).
• backpressure: { maxBufferedAmount: number; totalBufferedAmount: number; slowConsumers: number; drops: number; } — Backpressure agrégée (instantanée) — risque #1.
• backplane?: IBackplaneInfo — Carte d’identité du backplane effectif (driver, transport, cross-pod, canal).

Types (1)#

RealtimeHealthReport#

type RealtimeHealthReport = IRealtimeClusterHealth | IRealtimeHealth

Ce que publie nodefony:socket et ce que rend /nodefony/realtime/api/health : la vue POD agrégée en mode cluster, sinon la santé du seul worker qui répond. Le discriminant est cluster: true.

← Toutes les références d’API