first commit

docs/geospatial/logistics/ports/src/otel/otel.md

@@ -0,0 +1,72 @@
+# 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.