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