Initial Commit

packages/threejs/r3f/r3f-networking/src/observability/observability.md

@@ -0,0 +1,69 @@
+# `observability`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## 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
+
+```ts
+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:
+
+```ts
+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.