first commit

docs/foundation/flow/streams-chunk-queue/src/telemetry/telemetry.md

@@ -0,0 +1,79 @@
+# telemetry
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Exposes the OpenTelemetry instruments that the `StreamingChunkQueue`
+records during its lifecycle. Centralising instrument creation in one
+lazy singleton means the SDK can be configured after import without
+losing observations, and tests can swap the underlying meter via
+`resetTelemetryForTest`.
+
+## Features
+
+- One `meter` per process (`@suaveplan/streams-chunk-queue`).
+- Five counters (`chunks_received_total`, `chunks_streamed_total`,
+  `validation_failures_total`, `decryption_failures_total`,
+  `rate_limited_total`).
+- One histogram (`stream_duration_ms`) recorded when a transfer
+  completes.
+- Lazy initialisation — instruments are created on first call to
+  `getTelemetry()`.
+- `resetTelemetryForTest()` discards the cache so each test fixture
+  observes a fresh holder.
+
+## Usage: Basic
+
+```ts
+import { getTelemetry } from "@suaveplan/streams-chunk-queue";
+
+const t = getTelemetry();
+t.chunksReceived.add(1);
+```
+
+## Usage: Advanced
+
+```ts
+import { getTelemetry, resetTelemetryForTest } from "@suaveplan/streams-chunk-queue";
+
+beforeEach(() => resetTelemetryForTest());
+```
+
+## API Reference
+
+### `getTelemetry()` → `StreamsChunkQueueTelemetry`
+
+Returns the singleton holder of OTel instruments.
+
+### `resetTelemetryForTest()` → `void`
+
+Drops the cache so the next `getTelemetry()` call rebuilds a new
+holder. Intended for test isolation only.
+
+### `StreamsChunkQueueTelemetry`
+
+```ts
+interface StreamsChunkQueueTelemetry {
+    chunksReceived: Counter;
+    chunksStreamed: Counter;
+    validationFailures: Counter;
+    decryptionFailures: Counter;
+    rateLimited: Counter;
+    streamDuration: Histogram;
+}
+```
+
+## Implementation Notes
+
+OTel's `metrics.getMeter` returns a no-op meter when no SDK is
+registered, which is the desired behaviour for unit tests and for
+applications that have not yet configured observability. The lazy
+cache ensures that a late `MeterProvider` registration is picked up the
+first time a chunk is received. The counters were chosen so a single
+dashboard tile (`chunks_received_total - chunks_streamed_total`)
+exposes the in-flight backlog without requiring a separate gauge. The
+histogram records on `stream:complete` only, so it never includes
+partial transfers that errored on timeout.