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