@push-stream-std/push-instrument (0.0.8)
Installation
@push-stream-std:registry=https://hub.kl1.tenere.ai/api/packages/push-stream-std/npm/npm install @push-stream-std/push-instrument@0.0.8"@push-stream-std/push-instrument": "0.0.8"About this package
@push-stream-std/push-instrument
Instrument stream for debugging and metrics.
Published as @push-stream-std/push-instrument.
Synopsis
import { instrument } from '@push-stream-std/push-instrument';
import { values } from '@push-stream-std/push-pushable';
import { collect } from '@push-stream-std/push-concat';
const inst = instrument({ name: 'my-stream' });
values([1, 2, 3, 4, 5])
.pipe(inst)
.pipe(collect((err, results) => {
console.log(inst.stats);
// { name: 'my-stream', count: 5, bytes: 5, throughput: ..., avgLatency: ..., ... }
}));
Install
npm config set @push-stream-std:registry https://hub.kl1.tenere.ai/api/packages/push-stream-std/npm/
npm config set -- //hub.kl1.tenere.ai/api/packages/push-stream-std/npm/:_authToken "$PACKAGE_TOKEN"
npm install @push-stream-std/push-instrument
Why
A push-stream through operator that wraps any stream and collects real-time performance metrics. It tracks item count, byte size, throughput, average write latency, pause/resume counts, total pause duration, and error count. Useful for debugging stream performance, monitoring production pipelines, and identifying backpressure bottlenecks. All time measurements use Date.now() for zero-dependency operation.
API
instrument(options)
Creates a through stream that passes data through while collecting metrics.
Parameters:
options.name(string, default'stream') — Label included in stats output.options.onWrite(function, optional) — Called on each write with(data, stats).options.onEnd(function, optional) — Called when the stream ends with(stats).options.onPause(function, optional) — Called on backpressure pause with(stats).options.onResume(function, optional) — Called when resuming after pause with(stats).options.metrics(boolean, defaulttrue) — Whether to collect metrics (currently unused at runtime; stats are always collected).
Returns: A push-stream through (has sink, source, pipe, write, end, abort, resume, paused, ended).
Stream stats object (accessible via stream.stats):
name— The configured name.count— Number of items written.bytes— Total bytes (string length or 1 per item).startTime— Timestamp when the first write occurred.lastWriteTime— Timestamp of the last write.pauseCount— Number of backpressure pauses.resumeCount— Number of resume events.totalPauseDuration— Cumulative milliseconds spent paused.endTime— Timestamp whenend()was called.errors— Number of errors encountered.throughput— Bytes per second, computed on access.avgLatency— Average time between writes in ms (0 if fewer than 2 writes).elapsed— Milliseconds from first write to now (or end).
Tests
npm test
Tests cover stat collection accuracy (count, bytes, timing), throughput calculation, callback invocation for write/end/pause/resume events, and backpressure counting.
Requirements
Node.js 22 or later. ESM only.