`telemetry/telemetry.ts` — OpenTelemetry instruments

(no submodules)

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

import {
    getConvertCounter,
    getConvertDuration,
} from "@suaveplan/emblem-solver";

getConvertCounter().add(1);
getConvertDuration().record(12.5);

Usage: Advanced

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.

2.4 KiB Raw Blame History

telemetry/telemetry.ts — OpenTelemetry instruments