`observability`

(no submodules)

Purpose

OTel meter wiring for the whole @suaveplan/r3f-networking package. Exposes two histograms, two counters, and a small recorder facade. Every externally-visible operation that affects multiplayer state is instrumented here so dashboards over the meter @suaveplan/r3f-networking can be assembled without reading code.

Features

Histogram r3f_net.snapshot_dispatch_ms (unit ms) — time spent dispatching one authoritative server snapshot through the local sync pipeline.
Histogram r3f_net.prediction_divergence (unit m) — magnitude of the last reconciliation error.
Counter r3f_net.snapshots_total{outcome} — snapshot frames received, labelled with accepted | out_of_order | rejected.
Counter r3f_net.peer_events_total{event} — peer lifecycle events, labelled with connected | dropped.
Convenience recordSnapshot(outcome) + recordPeerEvent(event) helpers with the label vocabulary locked at compile time.

Usage: Basic Example

import { recordSnapshot, snapshotDispatchMs } from "@suaveplan/r3f-networking";

const t0 = performance.now();
applySnapshot(frame);
snapshotDispatchMs.record(performance.now() - t0);
recordSnapshot("accepted");

Usage: Advanced Example

Wire the counter to a divergence histogram in the reconciliation path:

import {
    predictionDivergence,
    recordSnapshot,
} from "@suaveplan/r3f-networking";

const result = predictor.reconcile(authoritative, lastAckSeq);
predictionDivergence.record(result.error);
recordSnapshot(result.error > snapThreshold ? "rejected" : "accepted");

API Reference

snapshotDispatchMs: Histogram — duration per server-snapshot dispatch.
predictionDivergence: Histogram — magnitude of reconciliation error.
snapshotsTotal: Counter — total snapshots, with the outcome attribute.
peerEventsTotal: Counter — total peer events, with the event attribute.
recordSnapshot(outcome: SnapshotOutcome): void
recordPeerEvent(event: "connected" | "dropped"): void
type SnapshotOutcome = "accepted" | "out_of_order" | "rejected".

Implementation Notes

The meter is acquired once at module evaluation; consumers configuring an SDK later in startup will still pick up these instruments via the OTel global provider lazy-rebind contract. Attribute vocabularies are deliberately small to keep label cardinality bounded. No business-string labels (peer IDs, entity IDs) are emitted at the histogram or counter level.

2.5 KiB Raw Blame History

observability