`instruments.ts`

(no submodules)

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

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

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

Usage: Advanced

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.

2.1 KiB Raw Blame History

instruments.ts