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

Collator observability

(no submodules)

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

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

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.