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

otel/instruments.ts

(no submodules)

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

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

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

Usage: Advanced Example

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 — 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.