@intentius/chant-lexicon-grafana 0.96.0

package/src/codegen/docs.ts

@@ -0,0 +1,97 @@
+/**
+ * Documentation generation for the grafana lexicon: the generated reference
+ * pages from the core docs pipeline, plus the authored pages in docs/pages/.
+ */
+
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { docsPipeline, writeDocsSite, type DocsConfig } from "@intentius/chant/codegen/docs";
+
+function serviceFromType(resourceType: string): string {
+  const parts = resourceType.split("::");
+  return parts.length >= 2 ? parts[1] : "Grafana";
+}
+
+const overview = `The grafana lexicon types what a [Grafana](https://grafana.com/docs/grafana/latest/) dashboard
+shows: datasources, dashboards, rows, panels, queries and variables. \`chant build\`
+writes one JSON file per dashboard, the JSON Grafana imports as it is, plus the
+provisioning files Grafana reads for dashboards and datasources. Grafana server
+settings, users and plugins are out of scope.
+
+\`\`\`ts
+import { Datasource, PromQuery, TimeSeriesPanel, Dashboard } from "@intentius/chant-lexicon-grafana";
+
+const prometheus = new Datasource({ name: "Prometheus", type: "prometheus", url: "http://prometheus:9090" });
+const rate = new PromQuery({ expr: "sum(rate(http_requests_total[$__rate_interval]))" });
+const requests = new TimeSeriesPanel({ title: "Requests per second", datasource: prometheus, targets: [rate] });
+
+export const overview = new Dashboard({ title: "Overview", panels: [requests] });
+\`\`\`
+
+Panels: time series, stat, gauge, table, logs, traces, heatmap and text, plus
+rows. Queries: Prometheus (PromQL), Tempo (TraceQL) and Loki (LogQL). Panel
+options and query fields are generated from Grafana's own schemas at a pinned
+version, and every build validates the dashboards against the same schemas.
+\`definePanel\` and \`defineQuery\` add plugins chant doesn't ship.
+
+Three composites build whole dashboards from declarations in other lexicons:
+\`RedDashboard\` from an otel \`spanmetrics\` connector, \`SloDashboard\` from a
+prometheus \`Slo\` and \`AgentDashboard\` from the otel GenAI preset. Metric names
+come from the declaration, so renaming one moves the panels. See
+[Dashboards from Declarations](./composites/).
+
+Checks catch a query aimed at a datasource nobody declared (GRAF101) or of the
+wrong type (GRAF102), a \`$variable\` the dashboard doesn't declare (GRAF103),
+duplicate uids and ids (GRAF104), panels off the grid or overlapping (GRAF105),
+and anything Grafana's dashboard schema rejects (GRAF107).
+`;
+
+const outputFormat = `The grafana lexicon writes Grafana's own files, keyed by path under the
+directory of the \`-o\` output:
+
+- \`dashboards/<uid>.json\`, or \`dashboards/<folder>/<uid>.json\` for a
+  dashboard with a \`folder\`: the dashboard JSON, one file per dashboard.
+- \`provisioning/datasources/chant.yaml\`: every declared datasource.
+- \`provisioning/dashboards/chant.yaml\`: a file provider for the dashboards
+  directory; a default one unless a \`DashboardProvider\` is declared.
+
+The primary output (the \`-o\` file itself) is a JSON index of the dashboards,
+datasources and files that were built.
+
+- Dashboard JSON carries the pinned schema's \`schemaVersion\`, no numeric \`id\`,
+  and every field Grafana's schema requires (link defaults, an empty
+  \`annotations.list\`, \`fieldConfig.overrides\`).
+- Panels without a position are laid out in declaration order on the 24-column
+  grid. Ids and query \`refId\`s are assigned in order unless set.
+- A declared \`Datasource\` is written as \`{ type, uid }\` wherever it is
+  referenced, and as its uid inside another datasource's \`jsonData\`.
+- \`chant build\` rewrites JSON files with sorted keys; Grafana does not care
+  about key order.
+- Grafana's files have no metadata channel chant could use without changing
+  what Grafana imports, so no ownership marker is stamped.
+`;
+
+export async function generateDocs(opts?: { verbose?: boolean }): Promise<void> {
+  const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+
+  const config: DocsConfig = {
+    name: "grafana",
+    displayName: "Grafana",
+    description: "Typed Grafana dashboards, panels, queries and datasources, built to dashboard JSON and provisioning files",
+    distDir: join(pkgDir, "dist"),
+    outDir: join(pkgDir, "docs"),
+    basePath: process.env.DOCS_BASE_PATH ?? "/chant/lexicons/grafana/",
+    overview,
+    outputFormat,
+    serviceFromType,
+    srcDir: join(pkgDir, "src"),
+    examplesDir: join(pkgDir, "examples"),
+  };
+
+  const result = docsPipeline(config);
+  writeDocsSite(config, result);
+
+  if (opts?.verbose) {
+    console.error(`Generated ${result.pages.size} documentation pages`);
+  }
+}

package/src/codegen/generate-cli.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env tsx
+/**
+ * CLI entry point for `npm run generate` in lexicon-grafana.
+ */
+import { generate, writeGeneratedFiles } from "./generate";
+
+const result = await generate({ verbose: true });
+writeGeneratedFiles(result);

package/src/codegen/generate.ts

@@ -0,0 +1,83 @@
+/**
+ * The grafana lexicon's generate step, offline and deterministic.
+ *
+ * 1. `src/schema/<name>.gen.ts` from each vendored schema in `src/spec/schemas/`
+ *    (see `src/pin.ts`). These are committed, and a test fails when they
+ *    drift from what this step would write.
+ * 2. `src/generated/lexicon-grafana.json`, the registry of entity classes
+ *    the package exports, derived from the catalog so the packaged
+ *    `dist/meta.json` cannot disagree with the classes.
+ */
+
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { mkdirSync, writeFileSync } from "fs";
+import type { GenerateResult } from "@intentius/chant/codegen/generate";
+import { SCHEMA_NAMES, type SchemaName } from "../pin";
+import { digestMismatches, loadSchema } from "../spec/schemas";
+import { schemaModule } from "./schema-types";
+
+export type { GenerateResult };
+
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+
+/** The dashboard schema's own default `schemaVersion`, the one the serializer emits. */
+function dashboardExtras(schema: Record<string, unknown>): string[] {
+  const defs = schema.definitions as Record<string, { properties?: Record<string, { default?: unknown }> }>;
+  const v = defs.Dashboard?.properties?.schemaVersion?.default;
+  if (typeof v !== "number") throw new Error("grafana: dashboard schema has no default schemaVersion");
+  return ["/** The dashboard `schemaVersion` the pinned schema defaults to, and the one chant emits. */", `export const DASHBOARD_SCHEMA_VERSION = ${v};`];
+}
+
+/** Every generated schema module, keyed by path relative to the package root. */
+export function schemaModules(): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const name of SCHEMA_NAMES) {
+    const schema = loadSchema(name as SchemaName);
+    const extra = name === "dashboard" ? dashboardExtras(schema) : [];
+    out[`src/schema/${name}.gen.ts`] = schemaModule(name, schema, extra).source;
+  }
+  return out;
+}
+
+/** The packaged types entry re-exports the compiled declarations. */
+const TYPES_DTS = `// The grafana lexicon's entity classes are hand-written in src/, with panel
+// and query types generated into src/schema/; this entry re-exports them.
+export * from "../index";
+`;
+
+export async function generate(opts?: { verbose?: boolean; force?: boolean }): Promise<GenerateResult> {
+  const bad = digestMismatches();
+  if (bad.length > 0) {
+    throw new Error(
+      `grafana: vendored schemas do not match GRAFANA_SCHEMA_PIN: ${bad.map((b) => `${b.name} (${b.actual.slice(0, 12)}…)`).join(", ")}. ` +
+        "Run `just fetch-schemas` and update src/pin.ts.",
+    );
+  }
+  const modules = schemaModules();
+  for (const [rel, source] of Object.entries(modules)) {
+    mkdirSync(dirname(join(pkgDir, rel)), { recursive: true });
+    writeFileSync(join(pkgDir, rel), source);
+  }
+  const { BUILTIN_CATALOG, lexiconRegistry } = await import("../catalog");
+  const lexiconJSON = `${JSON.stringify(lexiconRegistry(), null, 2)}\n`;
+  if (opts?.verbose) {
+    console.error(`grafana: ${Object.keys(modules).length} schema modules, ${BUILTIN_CATALOG.length} entity classes`);
+  }
+  return {
+    lexiconJSON,
+    typesDTS: TYPES_DTS,
+    indexTS: "",
+    resources: BUILTIN_CATALOG.length,
+    properties: 0,
+    enums: 0,
+    warnings: [],
+  };
+}
+
+/** Write the registry to src/generated/lexicon-grafana.json, for tools that read it from there. */
+export function writeGeneratedFiles(result: GenerateResult): void {
+  const dir = join(pkgDir, "src", "generated");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "lexicon-grafana.json"), result.lexiconJSON);
+}

package/src/codegen/package.ts

@@ -0,0 +1,41 @@
+/**
+ * grafana lexicon packaging, delegating to core's packagePipeline.
+ */
+
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import {
+  packagePipeline,
+  collectSkills,
+  type PackageOptions,
+  type PackageResult,
+} from "@intentius/chant/codegen/package";
+import { generate } from "./generate";
+import { grafanaSkills } from "../skill-defs";
+
+export type { PackageOptions, PackageResult };
+
+// src/codegen/package.ts -> src/
+const srcDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+export async function packageLexicon(opts: PackageOptions = {}): Promise<PackageResult> {
+  const pkgJson = JSON.parse(readFileSync(join(srcDir, "..", "package.json"), "utf-8"));
+  return packagePipeline(
+    {
+      generate: (genOpts) => generate({ verbose: genOpts.verbose, force: genOpts.force }),
+      buildManifest: () => ({
+        name: "grafana",
+        version: pkgJson.version ?? "0.0.1",
+        chantVersion: ">=0.1.0",
+        namespace: "Grafana",
+        intrinsics: [],
+        pseudoParameters: {},
+      }),
+      srcDir,
+      collectSkills: () => collectSkills(grafanaSkills()),
+      version: pkgJson.version ?? "0.0.1",
+    },
+    opts,
+  );
+}

package/src/codegen/schema-types.ts

@@ -0,0 +1,173 @@
+/**
+ * JSON Schema (draft-07, the subset cog emits) to TypeScript declarations.
+ *
+ * Each vendored schema becomes one module under `src/schema/`: one exported
+ * type per entry in `definitions`, with the schema's descriptions as doc
+ * comments. `required` is kept, so the types say what the schema says; the
+ * entity props wrap panel options in `DeepPartial` where Grafana fills the
+ * rest in on import.
+ */
+
+import type { SchemaName } from "../pin";
+
+interface Node {
+  type?: string | string[];
+  $ref?: string;
+  enum?: unknown[];
+  const?: unknown;
+  oneOf?: Node[];
+  anyOf?: Node[];
+  allOf?: Node[];
+  items?: Node | Node[];
+  properties?: Record<string, Node>;
+  additionalProperties?: boolean | Node;
+  required?: string[];
+  description?: string;
+  deprecated?: boolean;
+  default?: unknown;
+  [key: string]: unknown;
+}
+
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+/**
+ * Keys written quoted even though they are identifiers. The repo's egress
+ * scan (test/egress-catalogue.ts) reads a bare `fetch` as a call to the
+ * global, and the dashboard schema has an action option named `fetch`.
+ */
+const QUOTED_KEYS = new Set(["fetch"]);
+
+/** `dataquery` -> `Dataquery`: every exported type starts upper-case. */
+export function typeName(defName: string): string {
+  return defName.charAt(0).toUpperCase() + defName.slice(1);
+}
+
+function refName(ref: string): string {
+  const m = /^#\/definitions\/(.+)$/.exec(ref);
+  if (!m) throw new Error(`schema-types: only local #/definitions refs are supported, got "${ref}"`);
+  return typeName(m[1]);
+}
+
+function literal(value: unknown): string {
+  return JSON.stringify(value);
+}
+
+function paren(t: string): string {
+  return /[|&]/.test(t) && !/^\{[\s\S]*\}$/.test(t) ? `(${t})` : t;
+}
+
+function union(parts: string[]): string {
+  const uniq = [...new Set(parts)];
+  if (uniq.includes("unknown")) return "unknown";
+  return uniq.length === 0 ? "never" : uniq.join(" | ");
+}
+
+function docComment(node: Node, indent: string): string[] {
+  const lines: string[] = [];
+  const text = typeof node.description === "string" ? node.description.trim() : "";
+  const deprecated = node.deprecated === true || typeof node["x-deprecation-message"] === "string";
+  if (!text && !deprecated) return lines;
+  lines.push(`${indent}/**`);
+  for (const raw of text ? text.replace(/\*\//g, "*\\/").split("\n") : []) {
+    const l = raw.trimEnd();
+    lines.push(`${indent} *${l ? ` ${l}` : ""}`);
+  }
+  if (deprecated) {
+    const msg = typeof node["x-deprecation-message"] === "string" ? ` ${String(node["x-deprecation-message"])}` : "";
+    lines.push(`${indent} * @deprecated${msg.replace(/\*\//g, "*\\/")}`);
+  }
+  lines.push(`${indent} */`);
+  return lines;
+}
+
+function objectType(node: Node, indent: string): string {
+  const props = node.properties ?? {};
+  const required = new Set(node.required ?? []);
+  const inner = `${indent}  `;
+  const lines: string[] = ["{"];
+  for (const [key, child] of Object.entries(props)) {
+    lines.push(...docComment(child, inner));
+    const k = IDENT.test(key) && !QUOTED_KEYS.has(key) ? key : JSON.stringify(key);
+    lines.push(`${inner}${k}${required.has(key) ? "" : "?"}: ${tsType(child, inner)};`);
+  }
+  const ap = node.additionalProperties;
+  if (ap !== undefined && ap !== false) {
+    const t = ap === true || Object.keys(ap).length === 0 ? "unknown" : tsType(ap, inner);
+    lines.push(`${inner}[key: string]: ${Object.keys(props).length > 0 ? "unknown" : t};`);
+  }
+  lines.push(`${indent}}`);
+  return lines.length === 2 ? "Record<string, never>" : lines.join("\n");
+}
+
+/** The TypeScript type for one schema node. */
+export function tsType(node: Node | boolean | undefined, indent = ""): string {
+  if (node === undefined || node === true) return "unknown";
+  if (node === false) return "never";
+  if (node.$ref) return refName(node.$ref);
+  if (node.const !== undefined) return literal(node.const);
+  if (Array.isArray(node.enum)) return union(node.enum.map(literal));
+  if (node.oneOf) return union(node.oneOf.map((n) => paren(tsType(n, indent))));
+  if (node.anyOf) return union(node.anyOf.map((n) => paren(tsType(n, indent))));
+  if (node.allOf) return node.allOf.map((n) => paren(tsType(n, indent))).join(" & ");
+
+  const types = Array.isArray(node.type) ? node.type : node.type ? [node.type] : [];
+  if (types.length === 0) return node.properties ? objectType(node, indent) : "unknown";
+  return union(
+    types.map((t) => {
+      switch (t) {
+        case "string":
+          return "string";
+        case "number":
+        case "integer":
+          return "number";
+        case "boolean":
+          return "boolean";
+        case "null":
+          return "null";
+        case "array": {
+          if (Array.isArray(node.items)) return `[${node.items.map((n) => tsType(n, indent)).join(", ")}]`;
+          return `${paren(tsType(node.items, indent))}[]`;
+        }
+        case "object": {
+          if (node.properties) return objectType(node, indent);
+          const ap = node.additionalProperties;
+          if (ap === false) return "Record<string, never>";
+          if (ap === undefined || ap === true || Object.keys(ap).length === 0) return "Record<string, unknown>";
+          return `Record<string, ${tsType(ap, indent)}>`;
+        }
+        default:
+          return "unknown";
+      }
+    }),
+  );
+}
+
+export interface GeneratedModule {
+  /** Module source, ready to write. */
+  source: string;
+  /** Exported type names, in definition order. */
+  types: string[];
+}
+
+/** One schema file to one TypeScript module. */
+export function schemaModule(name: SchemaName, schema: Record<string, unknown>, extra: string[] = []): GeneratedModule {
+  const defs = (schema.definitions ?? {}) as Record<string, Node>;
+  const out: string[] = [
+    "// Code generated by chant generate from the vendored Grafana schema",
+    `// src/spec/schemas/${name}.jsonschema.json (see src/pin.ts). DO NOT EDIT.`,
+    "/* eslint-disable */",
+    "",
+  ];
+  const types: string[] = [];
+  for (const [defName, def] of Object.entries(defs)) {
+    const tn = typeName(defName);
+    types.push(tn);
+    out.push(...docComment(def, ""));
+    const t = tsType(def, "");
+    if (t.startsWith("{")) out.push(`export interface ${tn} ${t}`);
+    else out.push(`export type ${tn} = ${t};`);
+    out.push("");
+  }
+  out.push(...extra);
+  return { source: `${out.join("\n").replace(/\n+$/, "")}\n`, types };
+}

package/src/composites/agent-dashboard.ts

@@ -0,0 +1,235 @@
+/**
+ * `AgentDashboard`: latency and errors per model and per tool, and token
+ * usage per model, from the otel lexicon's GenAI preset.
+ *
+ * Metric names come from `genAiMetrics()` (or the `metrics` of
+ * `genAiComponents()`), and label names from the preset's GenAI attribute
+ * keys, so a preset with another `namespace` moves every query here.
+ */
+
+import { Composite, type CompositeInstance } from "@intentius/chant/composite";
+import { GENAI_ATTRIBUTES, type GenAiMetric, type GenAiMetrics } from "@intentius/chant-lexicon-otel/genai";
+import { prometheusLabel, SPAN_STATUS_ERROR } from "@intentius/chant-lexicon-otel/metric-names";
+import { Dashboard, type DashboardEntity } from "../dashboard";
+import { Row, StatPanel, TimeSeriesPanel } from "../panels";
+import { PromQuery } from "../query";
+import { QueryVariable } from "../variables";
+import { slugUid } from "../util";
+import {
+  dashboardProps,
+  durationUnit,
+  legend,
+  quantile,
+  quantileName,
+  requireDatasource,
+  selector,
+  sumRate,
+  type DashboardOptions,
+  type Matcher,
+} from "./shared";
+
+export interface AgentDashboardProps extends DashboardOptions {
+  /** The preset's metrics: `genAiMetrics(options)` with the options the collector was built with, or `genAiComponents(options)`. */
+  genAi: GenAiMetrics | { metrics: GenAiMetrics };
+  /** The latency quantile per model and per tool (default 0.95). */
+  quantile?: number;
+}
+
+export type AgentDashboardMembers = { dashboard: DashboardEntity };
+
+/** What `AgentDashboard(...)` returns: its dashboard, as `dashboard`. */
+export type AgentDashboardInstance = CompositeInstance<AgentDashboardMembers> & AgentDashboardMembers;
+
+function metricsOf(genAi: AgentDashboardProps["genAi"]): GenAiMetrics {
+  const m = (genAi as { metrics?: GenAiMetrics }).metrics ?? (genAi as GenAiMetrics);
+  if (!m || !m.calls || !m.duration || !m.inputTokens || !m.outputTokens) {
+    throw new Error("AgentDashboard: genAi must be genAiMetrics(...) or genAiComponents(...) from the otel lexicon");
+  }
+  return m;
+}
+
+function labelOf(metric: GenAiMetric, attribute: string): string {
+  if (!metric.dimensions.includes(attribute)) {
+    throw new Error(`AgentDashboard: ${metric.name} has no ${attribute} dimension, so it can't be broken down by it`);
+  }
+  return prometheusLabel(attribute);
+}
+
+/** The PromQL the agent dashboard runs, from the preset's metrics. Exposed for tests and for panels of your own. */
+export function agentQueries(m: GenAiMetrics, q = 0.95) {
+  const model = labelOf(m.calls, GENAI_ATTRIBUTES.requestModel);
+  const tool = labelOf(m.calls, GENAI_ATTRIBUTES.toolName);
+  const errorType = labelOf(m.calls, GENAI_ATTRIBUTES.errorType);
+  const status = labelOf(m.calls, "status.code");
+  const service = labelOf(m.calls, "service.name");
+  labelOf(m.duration, GENAI_ATTRIBUTES.requestModel);
+  labelOf(m.duration, GENAI_ATTRIBUTES.toolName);
+  const tokenModel = labelOf(m.inputTokens, GENAI_ATTRIBUTES.requestModel);
+  labelOf(m.outputTokens, GENAI_ATTRIBUTES.requestModel);
+
+  const scope: Matcher[] = [
+    [service, "=~", "$service"],
+    [model, "=~", "$model"],
+  ];
+  const toolScope: Matcher[] = [...scope, [tool, "!=", ""]];
+  const err: Matcher = [status, "=", SPAN_STATUS_ERROR];
+  const calls = m.calls.prometheus;
+  const buckets = `${m.duration.prometheus}_bucket`;
+  const ratio = (matchers: Matcher[], by: string[]) =>
+    `${sumRate(selector(calls, [...matchers, err]), by)}\n/\n${sumRate(selector(calls, matchers), by)}`;
+  const tokens: Matcher[] = [[tokenModel, "=~", "$model"]];
+
+  return {
+    labels: { model, tool, errorType, status, service, tokenModel },
+    services: `label_values(${calls}, ${service})`,
+    models: `label_values(${calls}, ${model})`,
+    model: {
+      rate: sumRate(selector(calls, scope), [model]),
+      errorRatio: ratio(scope, [model]),
+      latency: quantile(q, selector(buckets, scope), [model]),
+    },
+    tool: {
+      rate: sumRate(selector(calls, toolScope), [tool]),
+      errorRatio: ratio(toolScope, [tool]),
+      latency: quantile(q, selector(buckets, toolScope), [tool]),
+    },
+    errorsByType: sumRate(selector(calls, [...scope, err]), [errorType]),
+    tokens: {
+      inputRate: sumRate(selector(m.inputTokens.prometheus, tokens), [tokenModel]),
+      outputRate: sumRate(selector(m.outputTokens.prometheus, tokens), [tokenModel]),
+      inputTotal: `sum(increase(${selector(m.inputTokens.prometheus, tokens)}[$__range]))`,
+      outputTotal: `sum(increase(${selector(m.outputTokens.prometheus, tokens)}[$__range]))`,
+    },
+  };
+}
+
+/**
+ * A dashboard for agents instrumented with GenAI spans: calls, errors and
+ * latency per model and per tool, errors by type, and token usage per
+ * model, from the GenAI preset's metrics.
+ *
+ * @example
+ * ```ts
+ * import { genAiMetrics } from "@intentius/chant-lexicon-otel";
+ * import { AgentDashboard } from "@intentius/chant-lexicon-grafana";
+ *
+ * export const agents = AgentDashboard({ genAi: genAiMetrics(), datasource: prometheus });
+ * ```
+ */
+export const AgentDashboard = Composite<AgentDashboardProps, AgentDashboardMembers>((props) => {
+  requireDatasource("AgentDashboard", props.datasource);
+  if (!props.genAi) throw new Error("AgentDashboard: genAi is required (genAiMetrics(...) from the otel lexicon)");
+  const m = metricsOf(props.genAi);
+  const qv = props.quantile ?? 0.95;
+  if (!(typeof qv === "number" && qv > 0 && qv < 1)) throw new Error(`AgentDashboard: quantile must be between 0 and 1, got ${String(qv)}`);
+  const q = agentQueries(m, qv);
+  const ds = props.datasource;
+  const p = quantileName(qv);
+  const latencyUnit = durationUnit(m.duration.unit);
+  const prefix = m.calls.name.replace(/\.calls$/, "");
+
+  const service = new QueryVariable({
+    name: "service",
+    label: "Service",
+    datasource: ds,
+    query: q.services,
+    multi: true,
+    includeAll: true,
+    allValue: ".*",
+    refresh: "onTimeRangeChange",
+    sort: 1,
+  });
+  const model = new QueryVariable({
+    name: "model",
+    label: "Model",
+    datasource: ds,
+    query: q.models,
+    multi: true,
+    includeAll: true,
+    allValue: ".*",
+    refresh: "onTimeRangeChange",
+    sort: 1,
+  });
+
+  const series = (title: string, expr: string, by: string, unit: string, description?: string) =>
+    new TimeSeriesPanel({
+      title,
+      ...(description ? { description } : {}),
+      datasource: ds,
+      gridPos: { w: 8, h: 8 },
+      targets: [new PromQuery({ expr, legendFormat: legend(by) })],
+      fieldConfig: { defaults: { unit, ...(unit === "percentunit" ? { min: 0 } : {}) } },
+    });
+
+  const { labels } = q;
+  const models = new Row({
+    title: "Models",
+    panels: [
+      series("Calls by model", q.model.rate, labels.model, "reqps", `GenAI operations per second, from ${m.calls.prometheus}.`),
+      series("Errors by model", q.model.errorRatio, labels.model, "percentunit", `Share of operations that ended with ${labels.status}="${SPAN_STATUS_ERROR}".`),
+      series(`Latency ${p} by model`, q.model.latency, labels.model, latencyUnit, `From ${m.duration.prometheus}.`),
+    ],
+  });
+  const tools = new Row({
+    title: "Tools",
+    panels: [
+      series("Tool calls", q.tool.rate, labels.tool, "reqps", `Operations with a ${GENAI_ATTRIBUTES.toolName}, per second.`),
+      series("Errors by tool", q.tool.errorRatio, labels.tool, "percentunit"),
+      series(`Latency ${p} by tool`, q.tool.latency, labels.tool, latencyUnit),
+    ],
+  });
+  const errors = new Row({
+    title: "Errors",
+    panels: [
+      new TimeSeriesPanel({
+        title: "Errors by type",
+        description: `Failed operations per second by ${GENAI_ATTRIBUTES.errorType}.`,
+        datasource: ds,
+        gridPos: { w: 24, h: 8 },
+        targets: [new PromQuery({ expr: q.errorsByType, legendFormat: legend(labels.errorType) })],
+        fieldConfig: { defaults: { unit: "reqps" } },
+      }),
+    ],
+  });
+  const tokenStat = (title: string, expr: string) =>
+    new StatPanel({
+      title,
+      description: "Over the dashboard's time range.",
+      datasource: ds,
+      gridPos: { w: 4, h: 8 },
+      targets: [new PromQuery({ expr, legendFormat: title })],
+      options: { graphMode: "none", colorMode: "none", reduceOptions: { calcs: ["lastNotNull"] } },
+      fieldConfig: { defaults: { unit: "short", decimals: 0 } },
+    });
+  const tokenRate = (title: string, expr: string, source: string) =>
+    new TimeSeriesPanel({
+      title,
+      description: `Tokens per second by model, from ${source}.`,
+      datasource: ds,
+      gridPos: { w: 8, h: 8 },
+      targets: [new PromQuery({ expr, legendFormat: legend(labels.tokenModel) })],
+      fieldConfig: { defaults: { unit: "short" }, overrides: [] },
+      options: { tooltip: { mode: "multi" } },
+    });
+  const tokens = new Row({
+    title: "Tokens",
+    panels: [
+      tokenRate("Input tokens by model", q.tokens.inputRate, m.inputTokens.prometheus),
+      tokenRate("Output tokens by model", q.tokens.outputRate, m.outputTokens.prometheus),
+      tokenStat("Input tokens", q.tokens.inputTotal),
+      tokenStat("Output tokens", q.tokens.outputTotal),
+    ],
+  });
+
+  const dashboard = new Dashboard({
+    ...dashboardProps(props, {
+      title: "Agents: models, tools and tokens",
+      uid: slugUid(`${prefix}-agents`),
+      description: `Calls, errors and latency per model and tool, and token usage per model, from the ${prefix} GenAI metrics.`,
+      tags: ["genai", "agents"],
+    }),
+    variables: [service, model],
+    panels: [models, tools, errors, tokens],
+  });
+  return { dashboard };
+}, "AgentDashboard");

package/src/composites/catalog.test.ts

@@ -0,0 +1,37 @@
+/**
+ * The composite catalog matches what this lexicon exports (#2662).
+ *
+ * `catalog.ts` is generated by `npm run generate:composite-catalogs` and is
+ * what `chant serve mcp` lists.
+ */
+
+import { describe, expect, test } from "vitest";
+import { isCompositeDefinition } from "@intentius/chant";
+import * as composites from "./index";
+import { compositeCatalog } from "./catalog";
+import { grafanaPlugin } from "../plugin";
+
+const exported = Object.entries(composites)
+  .filter(([, value]) => isCompositeDefinition(value))
+  .map(([name]) => name)
+  .sort();
+const catalogued = compositeCatalog.map((entry) => entry.name).sort();
+
+describe("the grafana composite catalog", () => {
+  test("every exported composite has an entry, and every entry names an exported composite", () => {
+    expect(exported).toEqual(["AgentDashboard", "RedDashboard", "SloDashboard"]);
+    expect(catalogued, "regenerate with `npm run generate:composite-catalogs -- grafana`").toEqual(exported);
+  });
+
+  test("every entry says what it is and what it bundles", () => {
+    for (const entry of compositeCatalog) {
+      expect(entry.lexicon, entry.name).toBe("grafana");
+      expect(entry.description.length, entry.name).toBeGreaterThan(0);
+      expect(entry.bundles, entry.name).toEqual(["Dashboard"]);
+    }
+  });
+
+  test("the plugin contributes it", () => {
+    expect(grafanaPlugin.composites?.()).toBe(compositeCatalog);
+  });
+});