# `instruments.ts`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

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

```ts
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

```ts
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.