first commit

docs/foundation/flow/queue-distribution-http/src/observability/instruments.md

@@ -0,0 +1,59 @@
+# HTTP plugin OTel instruments
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## 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:
+
+```ts
+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.
+
+```ts
+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.