first commit

docs/localization/i18n/i18n-backend-fs-multifile/src/observability/observability.md

@@ -0,0 +1,92 @@
+# `observability.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Self-contained OpenTelemetry instrument set for the
+`@suaveplan/i18n-backend-fs-multifile` package. The module wires every
+public counter and histogram emitted by `MultiFileFsBackend` and exposes
+an in-memory state ring used by spec-conformance tests so production
+code paths can be exercised without standing up a full OTel SDK.
+
+The module is loaded lazily by `getMultiFileFsBackendMetrics()` — the
+first call to any production path (`recordRead`, `recordWrite`) builds a
+single shared `Meter` and caches the resulting `Histogram`/`Counter`
+instances. Subsequent calls hit the cache. When no `MeterProvider` is
+registered (the default in production), every instrument is a no-op,
+keeping the cost path-neutral when telemetry is off.
+
+## Features
+
+- Lazily-built histograms and counters under the
+  `i18n.backend.fs_multifile.*` prefix.
+- Five instruments: `read_duration_ms`, `read_total`,
+  `read_errors_total`, `write_duration_ms`, `write_total`.
+- Every emission carries a `backend` label plus a `layout` label
+  (`nested` / `flat` / `glob`) so consumers can size watchers per
+  layout.
+- In-memory state ring (`getMultiFileFsBackendMetricsState`,
+  `resetMultiFileFsBackendMetricsState`) so spec-conformance tests can
+  assert exact attribute payloads without an exporter.
+- `resetMultiFileFsBackendMetricsCache` test hook to drop the cached
+  instruments between cases when a different MeterProvider is required.
+
+## Usage: Basic Example
+
+```ts
+import {
+    recordRead,
+    recordWrite,
+} from "@suaveplan/i18n-backend-fs-multifile/observability";
+
+recordRead("multi-file-fs", "en", "auth", "nested", "hit", 0.42);
+recordWrite("multi-file-fs", "nested", "ok", 0.31);
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    getMultiFileFsBackendMetricsState,
+    resetMultiFileFsBackendMetricsCache,
+    resetMultiFileFsBackendMetricsState,
+} from "@suaveplan/i18n-backend-fs-multifile/observability";
+
+resetMultiFileFsBackendMetricsCache();
+resetMultiFileFsBackendMetricsState();
+
+// ... run code that hits the backend ...
+
+const state = getMultiFileFsBackendMetricsState();
+const outcomes = state.readTotal.map((s) => s.attributes["outcome"]);
+expect(outcomes).toContain("hit");
+```
+
+## API Reference
+
+- `recordRead(backend, locale, namespace, layout, outcome, durationMs, errorCode?)`:
+  emits the `read_duration_ms` histogram and `read_total` counter; if
+  `errorCode` is supplied, also increments `read_errors_total{code,layout}`.
+- `recordWrite(backend, layout, outcome, durationMs)`: emits the
+  `write_duration_ms` histogram and `write_total` counter.
+- `getMultiFileFsBackendMetrics()`: lazy build / return cached
+  instruments — idempotent.
+- `getMultiFileFsBackendMetricsState()`: return the in-memory state
+  ring snapshot.
+- `resetMultiFileFsBackendMetricsState()`: clear the in-memory state
+  ring.
+- `resetMultiFileFsBackendMetricsCache()`: drop the cached instruments
+  so a fresh MeterProvider can take over (test-only escape hatch).
+
+## Implementation Notes
+
+- The `layout` attribute is mandatory on every counter and histogram so
+  operators can split SLOs per wire layout — `glob` patterns tend to
+  hide expensive resolutions behind dynamic substitution.
+- The state ring is unbounded by design and is the test-only path. The
+  `resetMultiFileFsBackendMetricsState` helper is the supported way to
+  prevent ring growth across tests.
+- The OTel meter is named `suaveplan.i18n-backend-fs-multifile` so
+  consumers can apply per-package views.