@intentius/chant-lexicon-grafana 0.98.0 → 0.100.0

package/src/catalog.ts

@@ -5,13 +5,24 @@
  */
 
 import type { LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
-import { DATASOURCE_TYPE } from "./datasource";
+import { DATASOURCE_PROVISIONING_TYPE, DATASOURCE_TYPE, EXTERNAL_DATASOURCE_TYPE } from "./datasource";
+import { FOLDER_TYPE } from "./folder";
 import { DASHBOARD_TYPE, DASHBOARD_PROVIDER_TYPE } from "./dashboard";
 import * as panels from "./panels";
 import * as queries from "./query";
 import { VARIABLE_TYPE_PREFIX } from "./variables";
+import {
+  ALERT_QUERY_TYPE,
+  ALERT_RULE_GROUP_TYPE,
+  ALERT_RULE_TYPE,
+  CONTACT_POINT_TYPE,
+  EXPRESSION_TYPE_PREFIX,
+  MUTE_TIMING_TYPE,
+  NOTIFICATION_POLICY_TYPE,
+  NOTIFICATION_TEMPLATE_TYPE,
+} from "./alerting";
 
-export type CatalogKind = "dashboard" | "datasource" | "provider" | "panel" | "row" | "query" | "variable";
+export type CatalogKind = "dashboard" | "folder" | "datasource" | "provider" | "panel" | "row" | "query" | "variable" | "alerting" | "expression";
 
 export interface CatalogEntry {
   className: string;
@@ -57,6 +68,18 @@ const VARIABLES: Array<[string, string, string]> = [
   ["DatasourceVariable", "datasource", "A choice of datasource of one plugin type; usable wherever a datasource is"],
   ["ConstantVariable", "constant", "A hidden, fixed value"],
   ["TextboxVariable", "textbox", "A free-text box"],
+  ["AdhocVariable", "adhoc", "Key/value filters Grafana adds to every query sent to the variable's datasource"],
+  ["GroupByVariable", "groupby", "A choice of label keys Grafana groups every query to the variable's datasource by (experimental in Grafana)"],
+  ["SwitchVariable", "switch", "An on/off switch with a value for each state (Grafana 12.3 and later)"],
+];
+
+const EXPRESSIONS: Array<[string, string, string]> = [
+  ["ReduceExpression", "reduce", "A server-side expression reducing each series to one number (last, mean, max, ...)"],
+  ["MathExpression", "math", "A server-side math expression over other results by refId, e.g. $A / $B"],
+  ["ThresholdExpression", "threshold", "A server-side threshold, with an optional recovery threshold"],
+  ["ResampleExpression", "resample", "A server-side expression resampling a time series to a fixed window"],
+  ["ClassicConditionsExpression", "classic_conditions", "Grafana's legacy classic conditions, as a server-side expression"],
+  ["SqlExpression", "sql", "A server-side SQL expression over the other results"],
 ];
 
 export const BUILTIN_CATALOG: CatalogEntry[] = [
@@ -74,6 +97,27 @@ export const BUILTIN_CATALOG: CatalogEntry[] = [
     entityKind: "resource",
     description: "A datasource, declared once and referenced by panels, queries and variables",
   },
+  {
+    className: "ExternalDatasource",
+    entityType: EXTERNAL_DATASOURCE_TYPE,
+    kind: "datasource",
+    entityKind: "resource",
+    description: "A datasource that already exists in Grafana: referenced like a Datasource and checked by GRAF101/GRAF102, never provisioned",
+  },
+  {
+    className: "Folder",
+    entityType: FOLDER_TYPE,
+    kind: "folder",
+    entityKind: "resource",
+    description: "A folder with a stable uid, nested with parent; a dashboard's folder may be one instead of a path",
+  },
+  {
+    className: "DatasourceProvisioning",
+    entityType: DATASOURCE_PROVISIONING_TYPE,
+    kind: "provider",
+    entityKind: "resource",
+    description: "The datasource provisioning file's prune (on by default) and deleteDatasources",
+  },
   {
     className: "DashboardProvider",
     entityType: DASHBOARD_PROVIDER_TYPE,
@@ -88,6 +132,64 @@ export const BUILTIN_CATALOG: CatalogEntry[] = [
     entityKind: "property",
     description: "A full-width row header; its panels are placed below it, or inside it when collapsed",
   },
+  {
+    className: "AlertRuleGroup",
+    entityType: ALERT_RULE_GROUP_TYPE,
+    kind: "alerting",
+    entityKind: "resource",
+    description: "A group of Grafana-managed alert and recording rules in a folder, evaluated together at one interval",
+  },
+  {
+    className: "ContactPoint",
+    entityType: CONTACT_POINT_TYPE,
+    kind: "alerting",
+    entityKind: "resource",
+    description: "A contact point: the integrations (email, Slack, webhook, ...) alerts are sent to, under one name",
+  },
+  {
+    className: "NotificationPolicy",
+    entityType: NOTIFICATION_POLICY_TYPE,
+    kind: "alerting",
+    entityKind: "resource",
+    description: "An organisation's notification policy tree: the root receiver and the routes that match alerts to contact points",
+  },
+  {
+    className: "MuteTiming",
+    entityType: MUTE_TIMING_TYPE,
+    kind: "alerting",
+    entityKind: "resource",
+    description: "A named time interval that mutes (or, as active_time_intervals, enables) notifications",
+  },
+  {
+    className: "NotificationTemplate",
+    entityType: NOTIFICATION_TEMPLATE_TYPE,
+    kind: "alerting",
+    entityKind: "resource",
+    description: "A notification template group, Go templates contact point settings can use",
+  },
+  {
+    className: "AlertRule",
+    entityType: ALERT_RULE_TYPE,
+    kind: "alerting",
+    entityKind: "property",
+    description: "A Grafana-managed alert or recording rule: queries, expressions and the condition that fires it",
+  },
+  {
+    className: "AlertQuery",
+    entityType: ALERT_QUERY_TYPE,
+    kind: "alerting",
+    entityKind: "property",
+    description: "A datasource query of an alert rule, with its model as Grafana stores it and its time range",
+  },
+  ...EXPRESSIONS.map(
+    ([className, type, description]): CatalogEntry => ({
+      className,
+      entityType: `${EXPRESSION_TYPE_PREFIX}${type}`,
+      kind: "expression",
+      entityKind: "property",
+      description,
+    }),
+  ),
   ...panelEntries,
   ...queryEntries,
   ...VARIABLES.map(

package/src/codegen/docs.ts

@@ -13,7 +13,8 @@ function serviceFromType(resourceType: string): string {
 }
 
 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\`
+shows: datasources, dashboards, rows, panels, queries and variables, and
+Grafana-managed alerting. \`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.
@@ -28,11 +29,36 @@ const requests = new TimeSeriesPanel({ title: "Requests per second", datasource:
 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.
+Panels: time series, stat, gauge, table, logs, traces, heatmap, text, bar
+chart, bar gauge, pie chart, state timeline, status history, histogram, node
+graph, XY chart, trend, canvas, geomap, flame graph and alert list, plus rows.
+Queries: Prometheus (PromQL), Tempo (TraceQL), Loki (LogQL), Elasticsearch,
+CloudWatch, Azure Monitor, Cloud Monitoring, BigQuery, Pyroscope, and SQL for
+PostgreSQL, MySQL and MSSQL. Panel options and query fields are generated from
+Grafana's own schemas at a pinned version, corrected against Grafana's CUE, and
+track Grafana 12.4 and 13.x. Every build validates the dashboards against the
+same schemas.
+Dashboards are written in the classic (v1) JSON model. Grafana 13's v2 model
+(tabs, auto grids, conditional rendering) cannot be declared yet; import and
+drift read a v2 dashboard by converting it to the classic model, and say what
+the conversion loses.
 \`definePanel\` and \`defineQuery\` add plugins chant doesn't ship.
+\`chant import\` turns dashboard JSON exported from Grafana into this TypeScript,
+and it builds back to the same dashboard (see
+[Importing Dashboards](./importing/)). \`chant lifecycle diff --live\` reports
+a dashboard edited in Grafana as drift, property by property, and
+\`chant import --from <env>\` writes a running Grafana's dashboards as
+TypeScript (see [Drift and Live Export](./observing/)). \`grafanaApply\` writes
+a build to a running Grafana over its HTTP API, with folders and library
+panels, and prunes the project's own dashboards and folders (see
+[Apply over the API](./applying/)).
+
+Grafana-managed alerting is typed too: rule groups with their queries and
+server-side expressions (reduce, math, threshold, resample, classic
+conditions, SQL), contact points, the notification policy tree, mute timings
+and templates, written to Grafana's alerting provisioning file.
+\`SloAlertRules\` turns a prometheus \`Slo\` into burn-rate alert rules. See
+[Alerting](./alerting/).
 
 Three composites build whole dashboards from declarations in other lexicons:
 \`RedDashboard\` from an otel \`spanmetrics\` connector, \`SloDashboard\` from a
@@ -40,10 +66,17 @@ prometheus \`Slo\` and \`AgentDashboard\` from the otel GenAI preset. Metric nam
 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
+Checks catch a query aimed at a datasource nobody declared, with
+\`Datasource\` or \`ExternalDatasource\` (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).
+anything Grafana's dashboard schema rejects (GRAF107), PromQL sent to a
+Prometheus that doesn't parse (GRAF108), dashboard providers that load a
+dashboard twice or not into its declared folder (GRAF109), a panel repeated over a variable that only ever
+holds one value (GRAF110), and a unit Grafana doesn't know (GRAF115). For alerting, they catch rules whose condition or expressions name
+no query (GRAF111), queries to undeclared datasources (GRAF112), routes to
+undeclared contact points or mute timings (GRAF113), and uids, intervals and
+duplicates Grafana refuses (GRAF114).
 `;
 
 const outputFormat = `The grafana lexicon writes Grafana's own files, keyed by path under the
@@ -54,9 +87,12 @@ directory of the \`-o\` output:
 - \`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.
+- \`provisioning/alerting/chant.yaml\`: rule groups, contact points, the
+  notification policy tree, mute timings and templates, when the build
+  declares any.
 
 The primary output (the \`-o\` file itself) is a JSON index of the dashboards,
-datasources and files that were built.
+datasources, alerting 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
@@ -67,8 +103,12 @@ datasources and files that were built.
   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.
+- The dashboard JSON carries no ownership marker. Grafana keeps who manages a
+  dashboard in the resource's metadata on its \`dashboard.grafana.app\` API,
+  not in the JSON: for a provisioned dashboard, the name of the provider that
+  loaded it, which is \`chant\` unless a \`DashboardProvider\` names another.
+  \`chant lifecycle diff --live\` reads that back (see
+  [Drift and Live Export](../observing/)).
 `;
 
 export async function generateDocs(opts?: { verbose?: boolean }): Promise<void> {

package/src/codegen/generate.ts

@@ -4,7 +4,11 @@
  * 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
+ * 2. `src/spec/schemas.gen.ts`, the same schemas with the overlay applied, as
+ *    JSON text. Validation (GRAF107, the `/validation` subpath) reads them
+ *    from there rather than from the files, so it needs no filesystem access
+ *    and works bundled. Committed and checked the same way.
+ * 3. `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.
  */
@@ -29,6 +33,27 @@ function dashboardExtras(schema: Record<string, unknown>): string[] {
   return ["/** The dashboard `schemaVersion` the pinned schema defaults to, and the one chant emits. */", `export const DASHBOARD_SCHEMA_VERSION = ${v};`];
 }
 
+/** `src/spec/schemas.gen.ts`: each schema validation uses, overlay applied, as one line of JSON text. */
+export function schemaDataModule(): string {
+  const lines = [
+    "// Code generated by chant generate. DO NOT EDIT.",
+    "// The vendored Grafana schemas (src/spec/schemas/, see src/pin.ts) with the",
+    "// correction overlay (src/spec/overlay/) applied, as JSON text, for",
+    "// src/schema-validate.ts. A module rather than a file read, so validation",
+    "// needs no filesystem access and survives bundling; text rather than object",
+    "// literals, so loading it costs little until a schema is parsed.",
+    "",
+    'import type { SchemaName } from "../pin";',
+    "",
+    "export const SCHEMA_JSON: Readonly<Record<SchemaName, string>> = {",
+  ];
+  for (const name of SCHEMA_NAMES) {
+    lines.push(`  ${JSON.stringify(name)}: ${JSON.stringify(JSON.stringify(loadSchema(name as SchemaName)))},`);
+  }
+  lines.push("};", "");
+  return lines.join("\n");
+}
+
 /** Every generated schema module, keyed by path relative to the package root. */
 export function schemaModules(): Record<string, string> {
   const out: Record<string, string> = {};
@@ -37,6 +62,7 @@ export function schemaModules(): Record<string, string> {
     const extra = name === "dashboard" ? dashboardExtras(schema) : [];
     out[`src/schema/${name}.gen.ts`] = schemaModule(name, schema, extra).source;
   }
+  out["src/spec/schemas.gen.ts"] = schemaDataModule();
   return out;
 }
 

package/src/codegen/schema-types.ts

@@ -1,9 +1,9 @@
 /**
  * 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
+ * Each vendored schema, with its correction overlay applied, 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.
  */
@@ -99,6 +99,15 @@ function objectType(node: Node, indent: string): string {
   return lines.length === 2 ? "Record<string, never>" : lines.join("\n");
 }
 
+/**
+ * A branch that only constrains which keys are present (`{ required: [...] }`),
+ * like the overlay's "a panel has a `type` or a `libraryPanel`". It says
+ * nothing about the shape, so the type ignores it and validation enforces it.
+ */
+function constraintOnly(branches: Node[] | undefined): boolean {
+  return Array.isArray(branches) && branches.every((b) => Object.keys(b).every((k) => k === "required"));
+}
+
 /** The TypeScript type for one schema node. */
 export function tsType(node: Node | boolean | undefined, indent = ""): string {
   if (node === undefined || node === true) return "unknown";
@@ -106,8 +115,8 @@ export function tsType(node: Node | boolean | undefined, indent = ""): string {
   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.oneOf && !constraintOnly(node.oneOf)) return union(node.oneOf.map((n) => paren(tsType(n, indent))));
+  if (node.anyOf && !constraintOnly(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] : [];
@@ -154,7 +163,8 @@ export function schemaModule(name: SchemaName, schema: Record<string, unknown>,
   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.`,
+    `// src/spec/schemas/${name}.jsonschema.json (see src/pin.ts) and its correction`,
+    "// overlay in src/spec/overlay/ (see src/spec/overlay.ts). DO NOT EDIT.",
     "/* eslint-disable */",
     "",
   ];

package/src/composites/agent-dashboard.ts

@@ -18,6 +18,7 @@ import { slugUid } from "../util";
 import {
   dashboardProps,
   durationUnit,
+  errorRatio,
   legend,
   quantile,
   quantileName,
@@ -75,8 +76,7 @@ export function agentQueries(m: GenAiMetrics, q = 0.95) {
   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 ratio = (matchers: Matcher[], by: string[]) => errorRatio(selector(calls, [...matchers, err]), selector(calls, matchers), by);
   const tokens: Matcher[] = [[tokenModel, "=~", "$model"]];
 
   return {
@@ -191,13 +191,16 @@ export const AgentDashboard = Composite<AgentDashboardProps, AgentDashboardMembe
       }),
     ],
   });
+  // One instant query at the end of the range: `increase(...[$__range])`
+  // is the total over the whole range, so evaluating it at every step of a
+  // range query would only repeat that work for points the stat throws away.
   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 })],
+      targets: [new PromQuery({ expr, legendFormat: title, instant: true, range: false })],
       options: { graphMode: "none", colorMode: "none", reduceOptions: { calcs: ["lastNotNull"] } },
       fieldConfig: { defaults: { unit: "short", decimals: 0 } },
     });

package/src/composites/catalog.test.ts

@@ -19,7 +19,7 @@ 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(exported).toEqual(["AgentDashboard", "RedDashboard", "SloAlertRules", "SloDashboard"]);
     expect(catalogued, "regenerate with `npm run generate:composite-catalogs -- grafana`").toEqual(exported);
   });
 
@@ -27,7 +27,7 @@ describe("the grafana composite catalog", () => {
     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"]);
+      expect(entry.bundles, entry.name).toEqual(entry.name === "SloAlertRules" ? ["AlertRuleGroup"] : ["Dashboard"]);
     }
   });
 

package/src/composites/catalog.ts

@@ -102,6 +102,12 @@ export const compositeCatalog: CompositeEntry[] = [
         "required": false,
         "description": "Duration quantiles, one panel each (default p50, p95 and p99)."
       },
+      {
+        "name": "spanKinds",
+        "type": "SpanKind[]",
+        "required": false,
+        "description": "The span kinds the queries count (default server and consumer spans)."
+      },
       {
         "name": "datasource",
         "type": "DatasourceInput<\"prometheus\">",
@@ -154,6 +160,82 @@ export const compositeCatalog: CompositeEntry[] = [
       }
     ]
   },
+  {
+    "name": "SloAlertRules",
+    "lexicon": "grafana",
+    "description": "Grafana-managed burn-rate alerts for an `Slo`: one rule per window pair, with the labels and annotations the `Slo`'s Prometheus alerts carry.",
+    "bundles": [
+      "AlertRuleGroup"
+    ],
+    "params": [
+      {
+        "name": "slo",
+        "type": "SloInstance | RuleGroupEntity | SloMetrics",
+        "required": true,
+        "description": "The `Slo(...)` the rules alert on, its rule group, or what `sloMetrics()` returned for it."
+      },
+      {
+        "name": "datasource",
+        "type": "DatasourceInput<\"prometheus\">",
+        "required": true,
+        "description": "The Prometheus holding the `Slo`'s recorded series: a declared `Datasource`, an `ExternalDatasource`, or `{ type: \"prometheus\", uid }`."
+      },
+      {
+        "name": "folder",
+        "type": "string",
+        "required": true,
+        "description": "The Grafana folder the rules are stored in, by title."
+      },
+      {
+        "name": "group",
+        "type": "string",
+        "required": false,
+        "description": "The rule group's name."
+      },
+      {
+        "name": "interval",
+        "type": "string",
+        "required": false,
+        "description": "How often the rules are evaluated, a multiple of 10s."
+      },
+      {
+        "name": "contactPoint",
+        "type": "ContactPointEntity | string",
+        "required": false,
+        "description": "Send the alerts straight to this contact point."
+      },
+      {
+        "name": "for",
+        "type": "string",
+        "required": false,
+        "description": "How long a pair must hold before its alert fires."
+      },
+      {
+        "name": "labels",
+        "type": "Record<string, string>",
+        "required": false,
+        "description": "More labels on every rule, e.g. `team`."
+      },
+      {
+        "name": "annotations",
+        "type": "Record<string, string>",
+        "required": false,
+        "description": "More annotations on every rule, e.g. `runbook_url`."
+      },
+      {
+        "name": "noDataState",
+        "type": "NoDataState",
+        "required": false,
+        "description": "What no data does."
+      },
+      {
+        "name": "execErrState",
+        "type": "ExecErrState",
+        "required": false,
+        "description": "What a query error does."
+      }
+    ]
+  },
   {
     "name": "SloDashboard",
     "lexicon": "grafana",

package/src/composites/composites.test.ts

@@ -15,7 +15,7 @@ import { Datasource } from "../datasource";
 import { buildGrafana, type DashboardJson } from "../build";
 import { validateGrafanaOutput } from "../validate-output";
 import { validateDashboardSchema } from "../schema-validate";
-import { AgentDashboard, RedDashboard, SloDashboard } from "./index";
+import { AgentDashboard, RedDashboard, redQueries, SloDashboard } from "./index";
 
 const prometheus = new Datasource({ name: "Prometheus", type: "prometheus", url: "http://prometheus:9090" });
 
@@ -78,16 +78,64 @@ describe("RedDashboard", () => {
     expectClean(json, out);
     expect(json.uid).toBe("red-traces-span-metrics");
     expect(panels(json).map((p) => p.title)).toEqual(["Rate", "Errors", "Duration p50", "Duration p95", "Duration p99"]);
-    expect(panelByTitle(json, "Rate").targets).toMatchObject([
-      { expr: 'sum by (service_name) (rate(traces_span_metrics_calls_total{service_name=~"$service"}[$__rate_interval]))' },
-    ]);
-    expect((panelByTitle(json, "Errors").targets as Json[])[0].expr).toContain('status_code="STATUS_CODE_ERROR"');
+    const calls = 'traces_span_metrics_calls_total{service_name=~"$service", span_kind=~"SPAN_KIND_SERVER|SPAN_KIND_CONSUMER"}';
+    const errors = 'traces_span_metrics_calls_total{service_name=~"$service", span_kind=~"SPAN_KIND_SERVER|SPAN_KIND_CONSUMER", status_code="STATUS_CODE_ERROR"}';
+    expect(panelByTitle(json, "Rate").targets).toMatchObject([{ expr: `sum by (service_name) (rate(${calls}[$__rate_interval]))` }]);
+    expect(panelByTitle(json, "Rate").description).toBe("Server and consumer spans per second by service, from traces_span_metrics_calls_total.");
+    expect((panelByTitle(json, "Errors").targets as Json[])[0].expr).toBe(
+      "(\n" +
+        `sum by (service_name) (rate(${errors}[$__rate_interval]))\n` +
+        "or\n" +
+        `sum by (service_name) (rate(${calls}[$__rate_interval])) * 0\n` +
+        ")\n/\n" +
+        `sum by (service_name) (rate(${calls}[$__rate_interval]))`,
+    );
     expect((panelByTitle(json, "Duration p95").targets as Json[])[0].expr).toBe(
-      'histogram_quantile(0.95, sum by (le, service_name) (rate(traces_span_metrics_duration_milliseconds_bucket{service_name=~"$service"}[$__rate_interval])))',
+      'histogram_quantile(0.95, sum by (le, service_name) (rate(traces_span_metrics_duration_milliseconds_bucket{service_name=~"$service", span_kind=~"SPAN_KIND_SERVER|SPAN_KIND_CONSUMER"}[$__rate_interval])))',
     );
     expect((panelByTitle(json, "Duration p95").fieldConfig as { defaults: Json }).defaults.unit).toBe("ms");
     const templating = json.templating as unknown as { list: Json[] };
-    expect(templating.list.map((v) => [v.name, v.query])).toEqual([["service", "label_values(traces_span_metrics_calls_total, service_name)"]]);
+    expect(templating.list.map((v) => [v.name, v.query])).toEqual([
+      ["service", 'label_values(traces_span_metrics_calls_total{span_kind=~"SPAN_KIND_SERVER|SPAN_KIND_CONSUMER"}, service_name)'],
+    ]);
+  });
+
+  test("spanKinds picks the kinds counted; [] counts every kind", () => {
+    const names = spanMetricsNames(new SpanMetricsConnector({ namespace: "shop" }));
+    const all = redQueries(names, [0.5], "$service", []);
+    expect(all.rate).toBe('sum by (service_name) (rate(shop_calls_total{service_name=~"$service"}[$__rate_interval]))');
+    expect(all.services).toBe("label_values(shop_calls_total, service_name)");
+
+    const client = redQueries(names, [0.5], "checkout", ["SPAN_KIND_CLIENT", "SPAN_KIND_PRODUCER", "SPAN_KIND_CLIENT"]);
+    expect(client.rate).toBe(
+      'sum by (service_name) (rate(shop_calls_total{service_name=~"checkout", span_kind=~"SPAN_KIND_CLIENT|SPAN_KIND_PRODUCER"}[$__rate_interval]))',
+    );
+    for (const e of [client.rate, client.errorRatio, ...client.duration.map((d) => d.expr)]) {
+      expect(checkPromql(asPromql(e)), e).toEqual({ ok: true });
+    }
+
+    const { json, out } = built(
+      RedDashboard({ spanMetrics: new SpanMetricsConnector({ namespace: "shop" }), spanKinds: ["SPAN_KIND_SERVER"], datasource: prometheus }).dashboard,
+    );
+    expectClean(json, out);
+    for (const e of exprs(json)) expect(e).toContain('span_kind=~"SPAN_KIND_SERVER"');
+    expect(panelByTitle(json, "Errors").description).toBe('Share of server spans with status_code="STATUS_CODE_ERROR", by service.');
+
+    const every = built(RedDashboard({ spanMetrics: new SpanMetricsConnector({ namespace: "shop" }), spanKinds: [], datasource: prometheus }).dashboard);
+    for (const e of exprs(every.json)) expect(e).not.toContain("span_kind");
+    expect(panelByTitle(every.json, "Rate").description).toBe("Spans per second by service, from shop_calls_total.");
+  });
+
+  test("a connector that excludes span.kind gets no kind filter by default, and naming kinds for it is an error", () => {
+    const connector = new SpanMetricsConnector({ exclude_dimensions: ["span.kind"] });
+    const { json, out } = built(RedDashboard({ spanMetrics: connector, datasource: prometheus }).dashboard);
+    expectClean(json, out);
+    for (const e of exprs(json)) expect(e).not.toContain("span_kind");
+    expect(() => RedDashboard({ spanMetrics: connector, spanKinds: ["SPAN_KIND_SERVER"], datasource: prometheus })).toThrow(/excludes span\.kind/);
+    expect(() => RedDashboard({ spanMetrics: connector, spanKinds: [], datasource: prometheus })).not.toThrow();
+    expect(() =>
+      RedDashboard({ spanMetrics: new SpanMetricsConnector({}), spanKinds: ["SERVER" as never], datasource: prometheus }),
+    ).toThrow(/unknown span kind "SERVER"/);
   });
 
   test("renaming the connector's namespace moves every query; its histogram unit moves the duration metric", () => {
@@ -259,10 +307,26 @@ describe("AgentDashboard", () => {
       "Input tokens",
       "Output tokens",
     ]);
+    const calls = 'genai_calls_total{service_name=~"$service", gen_ai_request_model=~"$model"}';
+    const errors = 'genai_calls_total{service_name=~"$service", gen_ai_request_model=~"$model", status_code="STATUS_CODE_ERROR"}';
     expect((panelByTitle(json, "Errors by model").targets as Json[])[0].expr).toBe(
-      'sum by (gen_ai_request_model) (rate(genai_calls_total{service_name=~"$service", gen_ai_request_model=~"$model", status_code="STATUS_CODE_ERROR"}[$__rate_interval]))\n/\n' +
-        'sum by (gen_ai_request_model) (rate(genai_calls_total{service_name=~"$service", gen_ai_request_model=~"$model"}[$__rate_interval]))',
+      "(\n" +
+        `sum by (gen_ai_request_model) (rate(${errors}[$__rate_interval]))\n` +
+        "or\n" +
+        `sum by (gen_ai_request_model) (rate(${calls}[$__rate_interval])) * 0\n` +
+        ")\n/\n" +
+        `sum by (gen_ai_request_model) (rate(${calls}[$__rate_interval]))`,
     );
+    expect((panelByTitle(json, "Errors by tool").targets as Json[])[0].expr).toMatch(/^\(\nsum by \(gen_ai_tool_name\) .*\nor\n.* \* 0\n\)\n\/\n/s);
+    // The token totals are one instant query each, not a range query of full-range increases.
+    for (const [title, metric] of [["Input tokens", "genai_tokens_input_total"], ["Output tokens", "genai_tokens_output_total"]]) {
+      expect(panelByTitle(json, title).targets).toMatchObject([
+        { expr: `sum(increase(${metric}{gen_ai_request_model=~"$model"}[$__range]))`, instant: true, range: false },
+      ]);
+    }
+    for (const title of ["Input tokens by model", "Errors by model"]) {
+      expect((panelByTitle(json, title).targets as Json[])[0].instant).toBeUndefined();
+    }
     expect((panelByTitle(json, "Latency p95 by tool").targets as Json[])[0].expr).toBe(
       'histogram_quantile(0.95, sum by (le, gen_ai_tool_name) (rate(genai_duration_seconds_bucket{service_name=~"$service", gen_ai_request_model=~"$model", gen_ai_tool_name!=""}[$__rate_interval])))',
     );

package/src/composites/index.ts

@@ -3,10 +3,12 @@
  * read, so renaming a metric at its source moves it in the panels.
  */
 
-export { RedDashboard, redQueries } from "./red-dashboard";
-export type { RedDashboardProps, RedDashboardMembers, RedDashboardInstance } from "./red-dashboard";
+export { RedDashboard, redQueries, RED_DEFAULT_SPAN_KINDS } from "./red-dashboard";
+export type { RedDashboardProps, RedDashboardMembers, RedDashboardInstance, SpanKind } from "./red-dashboard";
 export { SloDashboard, sloQueries } from "./slo-dashboard";
 export type { SloDashboardProps, SloDashboardMembers, SloDashboardInstance } from "./slo-dashboard";
 export { AgentDashboard, agentQueries } from "./agent-dashboard";
 export type { AgentDashboardProps, AgentDashboardMembers, AgentDashboardInstance } from "./agent-dashboard";
 export type { DashboardOptions } from "./shared";
+export { SloAlertRules, sloAlertQueries } from "./slo-alert-rules";
+export type { SloAlertRulesProps, SloAlertRulesMembers, SloAlertRulesInstance } from "./slo-alert-rules";