`instruments.ts`

(no submodules)

Purpose

Owns the OpenTelemetry instrument bundle for @suaveplan/api-plugin-file-upload: four counters and one histogram. Every public route handler and the underlying FileUploadService reach for these instruments and emit on every success/failure path, so operators get a uniform observability surface without bespoke per-handler boilerplate.

Features

Lazy bind: getUploadInstruments() resolves against the global MeterProvider exactly once and caches the result.
resetUploadInstruments() clears the cache so test setup that installs a fresh provider can force re-bind.
Outcome labels (success / rejected / error / accepted / duplicate) are documented in the JSDoc so dashboards have stable label semantics.
upload.bytes_total uses the OTel By unit so Prometheus scrapers can derive throughput correctly.

Usage: Basic

import { getUploadInstruments } from "@suaveplan/api-plugin-file-upload/otel/instruments";

const m = getUploadInstruments();
m.singleShotTotal.add(1, { outcome: "success" });
m.bytesTotal.add(byteLength);

Usage: Advanced

import {
    getUploadInstruments,
    resetUploadInstruments,
} from "@suaveplan/api-plugin-file-upload";
import { MeterProvider } from "@opentelemetry/sdk-metrics";
import { metrics } from "@opentelemetry/api";

beforeEach(() => {
    metrics.setGlobalMeterProvider(new MeterProvider());
    resetUploadInstruments();
});

it("complete emits counter and histogram", async () => {
    const m = getUploadInstruments();
    const start = performance.now();
    /* ... */
    m.completesTotal.add(1, { outcome: "success" });
    m.completeDurationMs.record(performance.now() - start, {
        outcome: "success",
    });
});

API Reference

UploadInstruments — shape of the bundle: singleShotTotal, chunksTotal, completesTotal, bytesTotal (all Counter), completeDurationMs (Histogram).
getUploadInstruments(): UploadInstruments — returns the cached bundle.
resetUploadInstruments(): void — clears the cache.

Implementation Notes

The meter name @suaveplan/api-plugin-file-upload doubles as the OTel scope so traces correlate with the package origin.
All counters share the same outcome label vocabulary so dashboards can apply a single label-mapping rule across the bundle.
The histogram unit is ms rather than s because every other timing instrument in Suaveplan standardised on ms for sub-second resolution at the dashboard layer.

2.5 KiB Raw Blame History

instruments.ts