telemetry

(no submodules)

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

import { getTelemetry } from "@suaveplan/streams-chunk-queue";

const t = getTelemetry();
t.chunksReceived.add(1);

Usage: Advanced

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`

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.

2.3 KiB Raw Blame History