first commit

docs/api-stack/api/api-graphql-ui-altair/src/instruments/instruments.md

@@ -0,0 +1,67 @@
+# `instruments` — OTel counter for Altair UI requests
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`instruments` owns the package's single OpenTelemetry counter,
+`graphql.ui.requests_total`, labelled with the constant
+`ui="altair"`. The counter name is deliberately identical to the
+GraphiQL sibling's so dashboards summing across both UIs can drop the
+`ui` label and add the two series. The `MeterProvider` is injectable —
+operators can hand in their own provider for in-process testing or rely
+on the OTel global the rest of the host has registered at boot.
+
+## Features
+
+- Single counter — `graphql.ui.requests_total`.
+- Constant label preset: `{ ui: "altair" }`.
+- `recordRequest()` convenience captures the label internally so call
+  sites never repeat the label literal (no drift risk).
+- Meter name pinned to `@suaveplan/api-graphql-ui-altair` for trace
+  correlation.
+- Falls back to the OTel global `MeterProvider` when none is supplied.
+
+## Usage: Basic
+
+```ts
+import { createAltairInstruments } from "@suaveplan/api-graphql-ui-altair/instruments";
+
+const inst = createAltairInstruments();
+inst.recordRequest();
+```
+
+## Usage: Advanced
+
+```ts
+import { MeterProvider } from "@opentelemetry/sdk-metrics";
+import { createAltairInstruments } from "@suaveplan/api-graphql-ui-altair/instruments";
+
+const meterProvider = new MeterProvider({
+    /* readers / exporters configured in the host */
+});
+
+const inst = createAltairInstruments({ meterProvider });
+
+// Inside the HTML response handler:
+inst.recordRequest(); // graphql.ui.requests_total{ui="altair"} += 1
+```
+
+## API Reference
+
+- `createAltairInstruments(config?: AltairInstrumentsConfig): AltairInstruments`.
+- `AltairInstruments` — `{ meter, requestsTotal, recordRequest }`,
+  frozen.
+- `GRAPHQL_UI_REQUESTS_COUNTER` — literal `"graphql.ui.requests_total"`.
+- `ALTAIR_UI_LABEL` — literal `"altair"`.
+- `ALTAIR_METER_NAME` — literal `"@suaveplan/api-graphql-ui-altair"`.
+
+## Implementation Notes
+
+The counter description block documents the cross-package label contract
+so operators reading the OTel discovery endpoint understand why two
+packages emit the same metric name. The `Object.freeze` on the return
+record prevents accidental mutation downstream — the bundle is meant to
+be a singleton per host instance.