---
title: "Référence d'API — nodefony — realtime-platformHealth"
source: docs/api/core/realtime-platformHealth.md
url: https://nodefony.github.io/nodefony-core/docs/api/core/realtime-platformHealth/
---


[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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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](../../)