# 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.