# `otel/instruments.ts`

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

This module owns the singleton OpenTelemetry instrument set for `@suaveplan/drive-sharing`. It captures a `Meter` and `Tracer` from the global OTel API on first use, builds every counter / histogram declared in the OpenSpec change, and exposes setter / reset hooks so tests can route everything through an in-memory `MeterProvider` for assertion.

## Features

- Lazy-singleton instrument acquisition: zero cost when no provider is registered (no-op meters are returned automatically by `@opentelemetry/api`).
- `setDriveShareMeterProvider` / `setDriveShareTracerProvider` accept `undefined` to fall back to the global default — handy for `afterEach` cleanup.
- Eight counters and three histograms covering partitions, grants, tokens, transfers, key rotations, policy checks, and envelope encrypt / decrypt latency.
- Safe-by-construction: only IDs (which are public-by-design), durations, and counts are recorded — never key material or plaintext bytes.

## Usage: Basic Example

```ts
import { getDriveShareInstruments } from "@suaveplan/drive-sharing/otel";

const i = getDriveShareInstruments();
i.grantCheckTotal.add(1);
i.envelopeDurationMs.record(2.7);
```

## Usage: Advanced Example

```ts
import {
    getDriveShareInstruments,
    setDriveShareMeterProvider,
    resetDriveShareInstruments,
} from "@suaveplan/drive-sharing/otel";

const records: Array<[string, number]> = [];
const provider = {
    getMeter: () => ({
        createCounter: (name: string) => ({
            add: (v: number) => records.push([name, v]),
        }),
        createHistogram: (name: string) => ({
            record: (v: number) => records.push([name, v]),
        }),
    }),
} as unknown as Parameters<typeof setDriveShareMeterProvider>[0];

setDriveShareMeterProvider(provider);
try {
    getDriveShareInstruments().grantDeniedTotal.add(1);
    // assert against `records`
} finally {
    setDriveShareMeterProvider(undefined);
    resetDriveShareInstruments();
}
```

## API Reference

### `interface DriveShareInstruments`

The structural shape of the instrument bundle. Field summary:

| Field | Type | Notes |
|---|---|---|
| `partitionMemberTotal` | Counter | Members added |
| `grantDeniedTotal` | Counter | Grant denials with `reason` attribute |
| `grantCheckTotal` | Counter | Grant checks (allowed + denied) |
| `grantCreateTotal` | Counter | Grants created |
| `partitionCreateTotal` | Counter | Partitions created |
| `tokenCreateTotal` | Counter | Tokens created |
| `tokenValidateTotal` | Counter | Token validations |
| `tokenRevokedTotal` | Counter | Tokens revoked |
| `transferBytesTotal` | Counter | Bytes transferred |
| `keyRotateTotal` | Counter | Key rotations |
| `policyCheckDurationMs` | Histogram | Policy-check latency in ms |
| `envelopeDurationMs` | Histogram | Envelope encrypt/decrypt latency in ms |
| `transferDurationMs` | Histogram | Cross-partition transfer latency in ms |

### Functions

- `getDriveShareInstruments(): DriveShareInstruments` — returns the lazy singleton.
- `setDriveShareMeterProvider(provider | undefined): void` — overrides the meter source. `undefined` clears the override.
- `resetDriveShareInstruments(): void` — forces re-acquisition on next call.
- `getDriveShareTracer(): Tracer` — lazy singleton tracer.
- `setDriveShareTracerProvider(provider | undefined): void` — overrides the tracer source.
- `resetDriveShareTracer(): void` — forces re-acquisition on next call.

## Implementation Notes

- The module captures the OTel global state once and caches it for the rest of the process lifetime to avoid `getMeter` overhead on hot paths (grant checks, envelope encrypt) — at scale these are sub-millisecond operations and accruing 1µs of OTel overhead per call would dominate the budget.
- `setDriveShareMeterProvider(undefined)` resets to the default global provider but does **not** automatically rebuild the instrument cache — callers must invoke `resetDriveShareInstruments()` explicitly. This keeps the no-op fast path predictable.
- Counter and histogram unit strings follow the [UCUM standard](https://ucum.org/) — `ms` for durations, `By` for bytes, `{members}` etc. for dimensionless counts.
- The `description` text for each instrument is the contract that downstream observability dashboards will display; reword cautiously.