# `instruments.ts`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

Builds and caches the OpenTelemetry instrument bundle the Yoga GraphQL
engine emits per request. The bundle covers a counter
(`graphql.requests_total`), two histograms (`graphql.request_duration_ms`,
`graphql.resolver_duration_ms`), an observable gauge
(`graphql.subscriptions_active`), and a schema-rebuild counter
(`graphql.schema_rebuilds_total`) — every metric the design doc §10
acceptance criteria enumerate.

The lazy-bound + reset pattern lets test code install a fresh
`MeterProvider`, call `resetYogaInstruments()`, exercise the engine, and
read counter / histogram observations directly off the provider — the
package never holds a stale meter reference across test boundaries.

## Features

- Singleton bundle keyed on the meter name `@suaveplan/api-graphql-yoga`.
- `resetYogaInstruments()` clears the cache for tests.
- Histograms carry units (`ms`); counters carry descriptions for the
  Prometheus exporter.

## Usage: Basic

```ts
import { getYogaInstruments } from "@suaveplan/api-graphql-yoga";

const instruments = getYogaInstruments();
instruments.requestsTotal.add(1, {
    operation_type: "query",
    operation_name: "Ping",
    outcome: "ok",
});
```

## Usage: Advanced

```ts
import { metrics } from "@opentelemetry/api";
import { MeterProvider } from "@opentelemetry/sdk-metrics";
import {
    getYogaInstruments,
    resetYogaInstruments,
} from "@suaveplan/api-graphql-yoga";

const provider = new MeterProvider();
metrics.setGlobalMeterProvider(provider);
resetYogaInstruments();
const instruments = getYogaInstruments();
instruments.requestDurationMs.record(12.5);
```

## API Reference

- `YogaInstruments` — readonly record with one entry per metric.
- `getYogaInstruments()` — lazy-binding accessor.
- `resetYogaInstruments()` — test helper.

## Implementation Notes

Observable gauges (`subscriptionsActive`) are bound but not subscribed
inside this module; the engine attaches a callback that returns the live
subscription count when the gauge is sampled.