first commit

docs/networking/drive/drive-sharing/src/otel/instruments.md

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