first commit

docs/localization/i18n/i18n-formatter-collator/src/observability/observability.md

@@ -0,0 +1,100 @@
+# Collator observability
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+The Collator formatter exports two OpenTelemetry instruments and a
+small in-memory state ring so spec-conformance tests can assert exact
+attribute payloads without standing up a full SDK exporter. The
+instrument names match the canonical Wave-3 formatter contract —
+every sibling formatter emits the same two metric names so dashboards
+and alerts compose cleanly across the family.
+
+## Features
+
+- Histogram `i18n.format.collator.duration_ms` (unit `ms`) — per-compare/-sort wall-clock time
+- Counter `i18n.format.cache_hit{formatter="collator"}` — increments on cache reuse only
+- In-memory state ring (`getCollatorMetricsState()`) for spec-conformance
+- `resetCollatorMetricsState()` test-only helper
+
+## Usage: Basic Example
+
+```ts
+import { metrics } from "@opentelemetry/api";
+import { MeterProvider } from "@opentelemetry/sdk-metrics";
+
+const provider = new MeterProvider({ readers: [/* reader */] });
+metrics.setGlobalMeterProvider(provider);
+
+import { compareStrings } from "@suaveplan/i18n-formatter-collator";
+compareStrings("a", "b", "en-GB");
+// emits via your reader
+```
+
+## Usage: Advanced Example
+
+```ts
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import {
+    clearCollatorCache,
+    compareStrings,
+} from "@suaveplan/i18n-formatter-collator";
+import {
+    getCollatorMetricsState,
+    resetCollatorMetricsState,
+} from "@suaveplan/i18n-formatter-collator";
+
+it("emits histogram + cache-hit counter", () => {
+    clearCollatorCache();
+    resetCollatorMetricsState();
+    compareStrings("a", "b", "en-GB", { sensitivity: "base", usage: "sort" });
+    compareStrings("a", "b", "en-GB", { sensitivity: "base", usage: "sort" });
+    const state = getCollatorMetricsState();
+    expect(state.durationSamples).toHaveLength(2);
+    expect(state.cacheHitSamples).toHaveLength(1);
+    expect(state.durationSamples[0]?.attributes).toMatchObject({
+        locale: "en-GB",
+        usage: "sort",
+        sensitivity: "base",
+    });
+});
+```
+
+## API Reference
+
+### `recordCollatorFormat(locale, usage, sensitivity, durationMs): void`
+
+Records the duration histogram sample. Tags: `locale`, `usage`,
+`sensitivity`. Called internally by `compareStrings` /
+`formatCollation`.
+
+### `recordCollatorCacheHit(): void`
+
+Increments the cache-hit counter with the constant tag
+`{ formatter: "collator" }`.
+
+### `getCollatorMetricsState(): CollatorMetricsState`
+
+Returns the in-memory ring of `durationSamples` and
+`cacheHitSamples`. Used by spec-conformance tests.
+
+### `resetCollatorMetricsState(): void`
+
+Clears both ring buffers. Test-only helper.
+
+## Implementation Notes
+
+- The OTel meter is named `suaveplan.i18n.formatter.collator`. Every
+  formatter in the family has its own meter so OTel resource
+  attributes can be tied per-package if a consumer chooses.
+- Defaults supplied to the histogram tag when caller omits options:
+  `usage = "sort"`, `sensitivity = "variant"` (matching `Intl.Collator`
+  defaults). Every sample carries non-null values for all three tags.
+- Sample dashboard query (PromQL/Grafana over OTLP):
+  `histogram_quantile(0.99, sum(rate(i18n_format_collator_duration_ms_bucket[5m])) by (le, locale, usage))`
+- The in-memory ring is intentionally unbounded — tests are short and
+  call `resetCollatorMetricsState()` between cases. A long-running
+  test loop should call reset to avoid memory growth.