first commit

docs/api-stack/api/api-graphql-yoga/src/instruments/instruments.md

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