65 lines
2.5 KiB
Markdown
65 lines
2.5 KiB
Markdown
# `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.
|