HTTP plugin OTel instruments

(no submodules)

Purpose

observability/instruments.ts centralises every OpenTelemetry counter, histogram, and tracer emitted by @suaveplan/queue-distribution-http. Instruments are registered under the meter / tracer name "@suaveplan/queue-distribution-http" so consumers configuring an SDK can route them with a single rule. Tracer / meter handles are cached behind resetInstrumentCache() so tests can swap providers between assertions.

Features

Counters: queue_dist_http.request_total{outcome}, queue_dist_http.connect.attempts_total{outcome}.
Histogram: queue_dist_http.request.duration_ms{outcome}.
Tracers: queue_dist_http.sendTask, queue_dist_http.connect.
resetInstrumentCache() for tests that install a new provider mid-suite.

Usage: Basic Example

Production code calls the instruments automatically. Consumers add a meter / tracer provider at startup:

import { MeterProvider } from "@opentelemetry/sdk-metrics";
import { metrics } from "@opentelemetry/api";

metrics.setGlobalMeterProvider(new MeterProvider({/* …readers… */}));

Usage: Advanced Example

In tests, install an in-memory exporter, drive the system, then assert directly on the captured metrics.

import {
    AggregationTemporality,
    InMemoryMetricExporter,
    MeterProvider,
    PeriodicExportingMetricReader,
} from "@opentelemetry/sdk-metrics";
import { metrics } from "@opentelemetry/api";
import { resetInstrumentCache } from "@suaveplan/queue-distribution-http/observability/instruments";

const exporter = new InMemoryMetricExporter(AggregationTemporality.DELTA);
const reader = new PeriodicExportingMetricReader({ exporter, exportIntervalMillis: 100 });
metrics.setGlobalMeterProvider(new MeterProvider({ readers: [reader] }));
resetInstrumentCache();
// … run system under test, then await reader.forceFlush() …

API Reference

function resetInstrumentCache(): void.
function recordHttpRequestOutcome(outcome: "success" | "failure"): void.
function recordHttpRequestDuration(durationMs, outcome): void.
function recordConnectAttempt(outcome: "success" | "failure" | "exhausted"): void.
function getSendTaskTracer(): Tracer, function getConnectTracer(): Tracer.

Implementation Notes

The instruments share a single meter handle so the per-call overhead in the hot path is a single map lookup. resetInstrumentCache() is wired exclusively for tests; production code never calls it because the underlying global provider is set once at startup. The outcome attribute is constrained to the three documented values for connect attempts and two for requests — keeping the cardinality bounded for backend dashboards.

2.7 KiB Raw Blame History