first commit

docs/api-stack/api/api-plugin-export/src/otel/instruments.md

@@ -0,0 +1,56 @@
+# `instruments.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+OpenTelemetry instrument factory for `@suaveplan/api-plugin-export`. Builds a cached bundle of six instruments — five counters and one histogram — bound to the meter named `@suaveplan/api-plugin-export`. The cache lets the hot path (`POST /exports` + `GET /:id/download`) resolve instruments once per process instead of paying the meter-provider lookup cost on every job, while `resetExportInstruments()` gives tests a hook to rebind against an in-memory `MeterProvider` installed at suite startup.
+
+## Features
+
+- Lazy resolution against the global `MeterProvider`, cached after the first call.
+- `export.jobs_total` counter (with `outcome` attribute) for every job, completed or failed.
+- `export.rows_total` and `export.bytes_total` counters that track the cumulative size of successful exports.
+- `export.duration_ms` histogram so dashboards / SLOs can report p50 / p99 latency.
+- `export.download.served` counter (with `format` attribute) for every successful download.
+- `export.download.failed` counter (with `reason` attribute) for every failed download.
+- `resetExportInstruments()` for tests installing fresh providers.
+
+## Usage: Basic
+
+```ts
+import { getExportInstruments } from "@suaveplan/api-plugin-export";
+
+const inst = getExportInstruments();
+inst.jobsTotal.add(1, { outcome: "completed" });
+inst.rowsTotal.add(rowCount);
+inst.bytesTotal.add(byteSize);
+inst.durationMs.record(elapsedMs);
+```
+
+## Usage: Advanced
+
+```ts
+// In test setup, after installing a fresh MeterProvider:
+import {
+    getExportInstruments,
+    resetExportInstruments,
+} from "@suaveplan/api-plugin-export";
+
+resetExportInstruments();
+const inst = getExportInstruments(); // rebinds against the new provider
+```
+
+## API Reference
+
+| Symbol | Kind | Notes |
+|---|---|---|
+| `ExportInstruments` | interface | `{ jobsTotal, rowsTotal, bytesTotal, durationMs, downloadServed, downloadFailed }`. |
+| `getExportInstruments()` | function | Lazy + cached. |
+| `resetExportInstruments()` | function | Drops the cache. |
+
+## Implementation Notes
+
+The bundle is held in a module-scope `let cached: ExportInstruments | undefined` rather than in a class instance, because the function is the only documented entry point and there is no per-plugin state to keep — every plugin instance in a process shares the same meter. Counters use `add(value, attributes?)`; the `outcome` attribute is set by the call site rather than declared on the instrument because OTel attributes are runtime keys, not instrument metadata. The histogram unit is set to `"ms"` (lower-case) per OTel semantic conventions for latency. Resetting between tests is mandatory: meter handles cache internally inside `@opentelemetry/api`, so without `resetExportInstruments()` a test would emit to whichever provider was installed when the *first* `getExportInstruments()` call ran — usually the global default provider, which loses every metric.