first commit

docs/media/image/emblem-solver/src/telemetry/telemetry.md

@@ -0,0 +1,69 @@
+# `telemetry/telemetry.ts` — OpenTelemetry instruments
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+This module owns the OpenTelemetry instruments emitted by `convert()`. It
+exposes a counter (`emblem_solver.convert.total`) and a histogram
+(`emblem_solver.convert.duration_ms`), both lazily initialised on first
+use so importing the package does not register instruments unless they
+are actually needed.
+
+## Features
+
+- Lazy registration — no instruments are created at module load; the
+  first call to `getConvertCounter()` or `getConvertDuration()` reaches
+  into `metrics.getMeter("@suaveplan/emblem-solver")` and caches the
+  result.
+- Instruments are independent objects so a downstream OTel SDK can
+  configure views per instrument.
+- Test helpers (`__resetTelemetryForTests`, `__peekTelemetryForTests`)
+  let the test suite assert lazy-registration behaviour without forcing
+  the production code to expose internals.
+- Histogram unit is `ms`; emitting an OTel view that converts to seconds
+  is the consumer's responsibility.
+
+## Usage: Basic
+
+```ts
+import {
+    getConvertCounter,
+    getConvertDuration,
+} from "@suaveplan/emblem-solver";
+
+getConvertCounter().add(1);
+getConvertDuration().record(12.5);
+```
+
+## Usage: Advanced
+
+```ts
+import { metrics } from "@opentelemetry/api";
+import { getConvertCounter } from "@suaveplan/emblem-solver";
+
+metrics.setGlobalMeterProvider(myProvider);
+// the next call lazily creates the counter against `myProvider`'s meter:
+getConvertCounter().add(1, { layerOrder: "auto" });
+```
+
+## API Reference
+
+| Symbol | Kind | Description |
+|---|---|---|
+| `getConvertCounter()` | fn | Lazy `Counter` for `emblem_solver.convert.total` |
+| `getConvertDuration()` | fn | Lazy `Histogram` for `emblem_solver.convert.duration_ms` |
+| `__resetTelemetryForTests()` | fn | Test-only: drop cached instruments |
+| `__peekTelemetryForTests()` | fn | Test-only: inspect cached instruments |
+
+## Implementation Notes
+
+The `metrics.getMeter` call is deferred until first use so that a host
+that swaps the global meter provider after import still sees its
+provider's instruments. Without this, instruments would be bound to the
+no-op default and silently discard recordings. The test helpers are
+exported from the module (rather than placed in a separate `__internal`
+file) because they need to reach the module-scope `let` bindings; keeping
+them here avoids exposing those bindings through a different surface.