first commit

docs/security-stack/security/license/src/otel/instruments.md

@@ -0,0 +1,89 @@
+# `@suaveplan/license` — otel/instruments
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+OpenTelemetry instrumentation for the license package. Registers a
+single `@opentelemetry/api` meter (`@suaveplan/license@0.1.0`) and
+attaches three instruments to it: a generation counter, a validation
+counter (attribute `license.valid: boolean`), and a validation-duration
+histogram (unit `ms`). When no SDK is wired the meter falls back to the
+Noop implementation, so importing this module has zero side effects in
+production unless the host application registers a real provider.
+
+## Features
+
+- `license.generate_total` — counter incremented once per successful
+  `generateLicense` call.
+- `license.validate_total` — counter incremented per validation call
+  with attribute `license.valid: boolean` (and, on failure, `license.error`
+  carrying the enum value).
+- `license.validate_duration_ms` — histogram of validation latency in
+  milliseconds.
+- Five `ATTR_*` constants exported so call sites and tests reference
+  attribute keys by name, not by stringly-typed literals.
+
+## Usage: Basic
+
+```ts
+import {
+    ATTR_LICENSE_VALID,
+    licenseValidateTotal,
+} from "@suaveplan/license/otel/instruments";
+
+licenseValidateTotal.add(1, { [ATTR_LICENSE_VALID]: true });
+```
+
+## Usage: Advanced
+
+Wire an in-memory provider for tests and assert that the instruments
+emit:
+
+```ts
+import { metrics } from "@opentelemetry/api";
+import {
+    AggregationTemporality,
+    InMemoryMetricExporter,
+    MeterProvider,
+    PeriodicExportingMetricReader,
+} from "@opentelemetry/sdk-metrics";
+
+const exporter = new InMemoryMetricExporter(AggregationTemporality.CUMULATIVE);
+const reader = new PeriodicExportingMetricReader({ exporter, exportIntervalMillis: 60_000 });
+const provider = new MeterProvider({ readers: [reader] });
+metrics.setGlobalMeterProvider(provider);
+
+// ...exercise the license package...
+
+await provider.forceFlush();
+console.log(exporter.getMetrics());
+```
+
+## API Reference
+
+### Instruments
+
+- `licenseGenerateTotal: Counter`
+- `licenseValidateTotal: Counter`
+- `licenseValidateDurationMs: Histogram`
+
+### Attribute keys
+
+- `ATTR_LICENSE_VALID = "license.valid"`
+- `ATTR_LICENSE_ERROR = "license.error"`
+- `ATTR_LICENSE_TIER = "license.tier"`
+- `ATTR_LICENSE_PRODUCT_ID = "license.product_id"`
+- `ATTR_LICENSE_SIGNING_KEY_ID = "license.signing_key_id"`
+
+## Implementation Notes
+
+The meter is fetched at module load via `metrics.getMeter(...)`. The
+`@opentelemetry/api` library guarantees that subsequent calls with the
+same name+version return the same meter instance, so importing
+`instruments.ts` from multiple call sites does not create duplicate
+counters. The Noop fallback means `licenseGenerateTotal.add(...)` is a
+zero-cost call when no SDK is wired — safe to leave the instrumentation
+on in every code path.