# 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.