first commit

docs/api-stack/api/api-plugin-file-upload/src/otel/instruments.md

@@ -0,0 +1,64 @@
+# `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.