# otel

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

Wires `@suaveplan/ports`' OpenTelemetry instrumentation: three counters
that track lookup volume per kind, lane lookup volume per mode, and ETA
estimations per confidence band; plus three histograms recording the
duration of `findNearestPort`, `estimateLaneDistance`, and `estimateETA`.
Every public function in the package emits exactly one counter
increment and (where relevant) one histogram sample on each call so
operators can build dashboards without re-instrumenting consumers.

## Features

- Three counters: `ports.lookup_total{kind}`,
  `ports.lane_lookup_total{mode}`, `ports.eta_total{confidence}`.
- Three histograms: `ports.find_nearest_duration_ms`,
  `ports.lane_distance_duration_ms`, `ports.eta_duration_ms`, all in
  millisecond units.
- `refreshPortsMeters()` rebinds every instrument against the current
  global `MeterProvider` — tests call this after wiring an in-memory
  exporter so subsequent record calls land on the test provider rather
  than the module-load meter.
- Recorder helpers (`recordPortLookup`, `recordLaneLookup`,
  `recordEta`, `record*Duration`) are 1:1 with the named instruments
  and accept the literal-typed label values directly.
- Meter is named `@suaveplan/ports` at version `0.1.0`.

## Usage: Basic

```ts
import { recordPortLookup } from "@suaveplan/ports";

recordPortLookup("findPort");
```

## Usage: Advanced

```ts
import { MeterProvider } from "@opentelemetry/sdk-metrics";
import { metrics } from "@opentelemetry/api";
import { refreshPortsMeters } from "@suaveplan/ports";

const provider = new MeterProvider();
metrics.setGlobalMeterProvider(provider);
refreshPortsMeters();
// Now every subsequent ports operation lands on `provider`.
```

## API Reference

- `recordPortLookup(kind)` — kind ∈ `findPort | byCountry | byType |
  search | findNearest | inRadius`.
- `recordLaneLookup(mode)` — mode ∈ `sea | rail | air | all`.
- `recordEta(confidence)` — confidence ∈ `high | medium | low`.
- `recordFindNearestDuration(ms)`,
  `recordLaneDistanceDuration(ms)`, `recordEtaDuration(ms)`.
- `refreshPortsMeters()` — re-resolve every instrument.

## Implementation Notes

Instruments are module-scope `let` bindings so `refreshPortsMeters` can
swap them in place; otherwise the OTel API would route emissions to the
original meter even after `setGlobalMeterProvider`. The histograms use
the `ms` unit hint so exporters render them as durations. The package
deliberately does not start its own spans — span management is the
caller's responsibility, and instruments stay focused on aggregate
behaviour rather than per-call tracing.