otel

(no submodules)

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

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

recordPortLookup("findPort");

Usage: Advanced

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.

2.6 KiB Raw Blame History