@intentius/chant-lexicon-grafana 0.97.0 → 0.99.0

package/src/skills/chant-grafana-alerting.md

@@ -0,0 +1,49 @@
+---
+skill: chant-grafana-alerting
+description: Declare Grafana-managed alert rules, server-side expressions, contact points, notification policies and mute timings with chant, turn an Slo into burn-rate rules, and import Grafana's alerting exports
+user-invocable: true
+---
+
+# Grafana-managed alerting with chant
+
+Everything is written to `provisioning/alerting/chant.yaml`, Grafana's alerting provisioning file. Mount `dist/grafana/provisioning` at `/etc/grafana/provisioning`.
+
+## A rule
+
+```ts
+import { AlertRule, AlertRuleGroup, PromQuery, ReduceExpression, ThresholdExpression } from "@intentius/chant-lexicon-grafana";
+
+const errors = new PromQuery({ datasource: prometheus, expr: 'sum(rate(http_requests_total{code=~"5.."}[5m]))', instant: true });
+const last = new ReduceExpression({ expression: "A", reducer: "last" });
+const high = new ThresholdExpression({ expression: "B", conditions: [{ evaluator: { type: "gt", params: [5] } }] });
+const rule = new AlertRule({ title: "5xx above 5/s", uid: "checkout-5xx", data: [errors, last, high], for: "5m", labels: { severity: "page" } });
+export const checkoutAlerts = new AlertRuleGroup({ name: "checkout", folder: "Checkout", interval: "1m", rules: [rule] });
+```
+
+- refIds follow `data` order (A, B, C); expressions name inputs by refId (`"A"`, or `$A` in a `MathExpression`). `condition` defaults to the last refId.
+- Queries need a `Datasource`, `ExternalDatasource` or `{ type, uid }`; never a `DatasourceVariable`.
+- Any plugin's model: `new AlertQuery({ datasource, model: { ... } })`. A typed query with its own range: `new AlertQuery({ query, relativeTimeRange: { from: "5m" } })`.
+- Set `uid` explicitly on rules whose title may change.
+
+## Notifications
+
+- `ContactPoint({ name, receivers: [{ type: "slack", settings: { url: "$__env{SLACK_URL}" } }] })`. Secrets always as `$__env{...}` or `$__file{...}`; GRAF002 flags literals.
+- `NotificationPolicy({ receiver: oncall, routes: [{ receiver: tickets, object_matchers: [["severity", "=", "ticket"]], mute_time_intervals: [weekends] }] })`. One per organisation: it replaces the whole tree.
+- `MuteTiming({ name: "weekends", time_intervals: [{ weekdays: ["saturday", "sunday"] }] })`, `NotificationTemplate({ name, template })`.
+- Pass entities rather than names where you can; GRAF113 checks names against what the build declares.
+
+## An SLO's burn-rate alerts
+
+```ts
+export const checkoutBurn = SloAlertRules({ slo: checkout, datasource: prometheus, folder: "SLOs" });
+```
+
+One rule per window pair, reading the `Slo`'s recorded `slo:sli_error:ratio_rate<window>` series, so the `Slo`'s Prometheus rule group must be loaded. Rules carry `severity: page|ticket` for the policy tree, or pass `contactPoint`.
+
+## Import
+
+`chant import alert-rules.yaml` reads a provisioning file or Grafana's export (`/api/v1/provisioning/alert-rules/export?format=yaml`, and the contact-points, policies and mute-timings exports). Read every warning: guessed datasource types, `[REDACTED]` secrets turned into `$__env{...}`, and delete/reset lists that are not carried.
+
+## Checks
+
+GRAF108 (PromQL), GRAF111 (condition and expression refIds), GRAF112 (datasources), GRAF113 (contact points, mute timings, matchers), GRAF114 (uids, intervals as multiples of 10s, duplicates).

package/src/skills/chant-grafana-provisioning.md

@@ -25,7 +25,7 @@ docker run -p 3000:3000 \
 
 ## Kubernetes
 
-Put the two provisioning files in one ConfigMap mounted at `/etc/grafana/provisioning/datasources` and `/etc/grafana/provisioning/dashboards` (a `subPath` each, or two ConfigMaps), and the dashboard JSON in another mounted at `/var/lib/grafana/dashboards`. `grafanaFiles(entities)` returns every file by path, so a k8s composite can build those ConfigMaps from the same declarations without a second build.
+Use `GrafanaConfigMaps({ entities, namespace })` from `@intentius/chant-lexicon-grafana/k8s` in a k8s build root. It writes one ConfigMap per dashboard labelled `grafana_dashboard: "1"`, with the folder in the `k8s-sidecar-target-directory` annotation. The datasource file goes in a ConfigMap labelled `grafana_datasource: "1"`, and the provider file in a third. The Grafana Helm chart's sidecar picks these up as they are. For a Grafana without the sidecar, spread `grafanaVolumes({ entities })`'s `volumes` and `volumeMounts` into the Deployment: provisioning goes under `/etc/grafana/provisioning`, and each dashboard folder gets a projected volume of its own. `grafanaFiles(entities)` still returns every file by path for any other layout.
 
 ## Changing where dashboards live
 
@@ -35,8 +35,8 @@ Declare a `DashboardProvider` to change the mount path, pin a folder, or allow U
 export const provider = new DashboardProvider({ name: "team", path: "/dashboards", allowUiUpdates: true });
 ```
 
-With no provider declared, chant writes one named `chant` that reads `/var/lib/grafana/dashboards` and maps subdirectories to folders.
+With no provider declared, chant writes one named `chant` that reads `/var/lib/grafana/dashboards` and maps subdirectories to folders. A provider with `folder` set puts every dashboard in that folder and ignores the dashboards' own `folder`; GRAF109 warns. Two providers on the same or nested paths load every dashboard twice, which GRAF109 reports as an error. A dashboard `folder` of `"Platform/Kubernetes"` nests on Grafana 13.1 and later.
 
 ## Checking before Grafana does
 
-`chant lint` and `chant build` run GRAF101-GRAF107 on the output, including a check against Grafana's dashboard schema at the pinned version. To check against a real Grafana, the lexicon's `import.test.ts` boots `grafana/grafana` with Docker, provisions the example and reads each dashboard back over the HTTP API.
+`chant lint` and `chant build` run the GRAF1xx checks on the output, including a check against Grafana's dashboard schema at the pinned version, a PromQL syntax check on every query sent to a Prometheus, and a check that the providers put each dashboard in its declared folder, once. To check against a real Grafana, the lexicon's `import.test.ts` boots `grafana/grafana` with Docker, provisions the example and reads each dashboard back over the HTTP API.

package/src/skills/chant-grafana.md

@@ -41,7 +41,7 @@ const requestRate = new PromQuery({
 
 ## Panels and dashboards
 
-Panel classes: `TimeSeriesPanel`, `StatPanel`, `GaugePanel`, `TablePanel`, `LogsPanel`, `TracesPanel`, `HeatmapPanel`, `TextPanel`, plus `Row`. `options` and `fieldConfig.defaults.custom` are typed from each panel's schema, and every option is optional because Grafana fills in the rest.
+Panel classes: `TimeSeriesPanel`, `StatPanel`, `GaugePanel`, `TablePanel`, `LogsPanel`, `TracesPanel`, `HeatmapPanel`, `TextPanel`, `BarChartPanel`, `BarGaugePanel`, `PieChartPanel`, `StateTimelinePanel`, `StatusHistoryPanel`, `HistogramPanel`, `NodeGraphPanel`, `XYChartPanel`, `TrendPanel`, `CanvasPanel`, `GeomapPanel`, `FlameGraphPanel`, `AlertListPanel`, plus `Row`. `options` and `fieldConfig.defaults.custom` are typed from each panel's schema, and every option is optional because Grafana fills in the rest.
 
 ```ts
 const rate = new TimeSeriesPanel({ title: "Request rate", datasource: prometheus, targets: [requestRate] });
@@ -55,9 +55,11 @@ export const overview = new Dashboard({
 });
 ```
 
-Leave `gridPos` out and panels are placed left to right, wrapping at 24 columns; give `x` and `y` to place one exactly. `Row({ title, panels, collapsed })` starts a full-width row. Dashboard uids default to the export name as a uid (`overview`).
+`transformations` is typed per transformer id, from Grafana v13.2.2's transformers: `transformation("organize", { excludeByName: { Time: true } })` checks the options against that one transformer, and a `{ id, options }` literal works too. Use `customTransformation(id, options)` for a plugin's transformer or options the types don't have.
 
-chant's lint wants flat declarations: extract nested objects (`time`, `options`) to named consts, keep at most eight declarations per file, and export entities with `export { a, b }`.
+Leave `gridPos` out and panels are placed left to right, wrapping at 24 columns and flowing around explicitly placed panels; give `x` and `y` to place one exactly. `Row({ title, panels, collapsed })` starts a full-width row. Dashboard uids default to the export name as a uid (`overview`).
+
+Panels, rows, queries and variables are property-kind, so chant's core lint doesn't count them toward the eight-per-file limit (COR009) and lets them carry `fieldConfig` and `options` inline (COR001). The dashboard is a resource: lift its own nested objects (`time`, `links`) into named consts.
 
 ## Dashboards built from other declarations
 
@@ -75,18 +77,22 @@ const agents = AgentDashboard({ genAi: genai, datasource: prometheus });
 export { services, checkoutSlo, agents };
 ```
 
-Pass the `prometheus` exporter as `exporter` to `RedDashboard` when its `namespace` changes the names. `datasource` may be a `{ type: "prometheus", uid }` ref to a datasource declared elsewhere. Never hand-write the span-metric or SLO series names in a query next to these; use `spanMetricsNames()` (otel), `sloMetrics()` (prometheus) or `genAiMetrics()` (otel), or the composites' `redQueries`, `sloQueries` and `agentQueries`.
+Pass the `prometheus` exporter as `exporter` to `RedDashboard` when its `namespace` changes the names. `RedDashboard` counts server and consumer spans only; pass `spanKinds` to count others, or `[]` for every kind. `datasource` may be a `{ type: "prometheus", uid }` ref to a datasource declared elsewhere. Never hand-write the span-metric or SLO series names in a query next to these; use `spanMetricsNames()` (otel), `sloMetrics()` (prometheus) or `genAiMetrics()` (otel), or the composites' `redQueries`, `sloQueries` and `agentQueries`.
 
 ## Rules
 
-- GRAF101: every panel, query and query variable names a declared datasource. GRAF102: of the right type.
+- GRAF101: every panel, query and query variable names a declared datasource (`Datasource` or `ExternalDatasource`), and every datasource variable's plugin type has one. GRAF102: of the right type.
 - GRAF103: every `$name`/`${name}` in a query, title or repeat is a declared variable (`$__*` are Grafana's own).
 - GRAF104: unique dashboard uids, datasource uids and names, panel ids, variable names and refIds.
 - GRAF105: panels fit the 24-column grid and don't overlap.
 - GRAF106: uids of 1-40 letters, digits, `-`, `_`; dashboards have titles.
 - GRAF107: the dashboard matches Grafana's schema at the pinned version.
+- GRAF108: every query and query variable sent to a Prometheus parses as PromQL (template variables and `$__` macros are substituted first).
+- GRAF109: the dashboard providers put each dashboard in its declared folder, and no two load the same files.
+- GRAF115 (warning): every panel unit is a Grafana unit id (`bytes`, `s`, `percent`, `reqps`, ...) or a custom unit (`suffix: cores`, `prefix:$`, `si:mF`, `count:reqs`, `currency:EUR`). Grafana shows anything else as literal text after the value.
+- GRAF111-GRAF114: alert rules, contact points, policies and mute timings; see the chant-grafana-alerting skill.
 
-GRAF101 and GRAF102 compare against the datasources in the same build root, so keep datasources and dashboards in one `chant build` (chant #1939).
+GRAF101 and GRAF102 compare against the datasources in the same build root, so keep datasources and dashboards in one `chant build` (chant #1939). For a datasource that exists in Grafana but is provisioned elsewhere, declare `new ExternalDatasource({ type: "prometheus", uid: "mimir" })` and use it like a `Datasource`; it is checked against, never provisioned.
 
 ## Other plugins
 

package/src/spec/fetch-cli.ts

@@ -6,11 +6,11 @@
  * `GRAFANA_SCHEMA_PIN`, then `npm run generate`.
  */
 import { writeFileSync } from "fs";
-import { GRAFANA_SCHEMA_PIN, SCHEMA_NAMES, schemaUrl } from "../pin";
+import { GRAFANA_SCHEMA_PIN, VENDORED_SCHEMA_NAMES, schemaUrl } from "../pin";
 import { schemaPath, sha256 } from "./schemas";
 
 let changed = 0;
-for (const name of SCHEMA_NAMES) {
+for (const name of VENDORED_SCHEMA_NAMES) {
   const res = await fetch(schemaUrl(name));
   if (!res.ok) throw new Error(`${name}: HTTP ${res.status} from ${schemaUrl(name)}`);
   const text = await res.text();
@@ -22,6 +22,6 @@ for (const name of SCHEMA_NAMES) {
 }
 console.error(
   changed === 0
-    ? `All ${SCHEMA_NAMES.length} schemas match the pin (${GRAFANA_SCHEMA_PIN.ref}).`
+    ? `All ${VENDORED_SCHEMA_NAMES.length} schemas match the pin (${GRAFANA_SCHEMA_PIN.ref}).`
     : `${changed} schema(s) differ from the pin: update GRAFANA_SCHEMA_PIN.files in src/pin.ts, then run npm run generate.`,
 );

package/src/spec/fetch-units-cli.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env tsx
+/**
+ * `just fetch-units`: download Grafana's unit registry
+ * (`packages/grafana-data/src/valueFormats/categories.ts`) at the tag in
+ * `GRAFANA_UNITS_SOURCE`, pull out every unit id, and rewrite
+ * `src/spec/units.gen.ts`. Run it when moving to a newer Grafana, then review
+ * the diff: an id Grafana dropped is one GRAF115 starts warning about.
+ */
+import { writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { sha256 } from "./schemas";
+import { GRAFANA_UNITS_SOURCE, LEGACY_UNIT_ALIASES } from "./units";
+
+const { repo, ref, commit, path } = GRAFANA_UNITS_SOURCE;
+const url = `https://raw.githubusercontent.com/${repo}/${commit}/${path}`;
+const res = await fetch(url);
+if (!res.ok) throw new Error(`HTTP ${res.status} from ${url}`);
+const text = await res.text();
+
+// Each format is `{ name: t(...), id: '<id>', fn: ... }`; ids are plain string literals.
+const ids: string[] = [];
+for (const m of text.matchAll(/\bid:\s*'([^']+)'/g)) if (!ids.includes(m[1])) ids.push(m[1]);
+for (const alias of LEGACY_UNIT_ALIASES) if (!ids.includes(alias)) ids.push(alias);
+if (ids.length < 200) throw new Error(`only ${ids.length} unit ids found in ${url}; has the file's shape changed?`);
+
+const out = `// Generated by \`just fetch-units\` (src/spec/fetch-units-cli.ts). Do not edit.
+// Source: https://github.com/${repo}/blob/${ref}/${path}
+// Commit ${commit}, sha256 ${sha256(text)}.
+// The ids Grafana's getValueFormat() indexes, plus the legacy aliases it resolves (valueFormats.ts).
+
+export const GRAFANA_UNIT_IDS: readonly string[] = [
+${ids.map((id) => `  ${JSON.stringify(id)},`).join("\n")}
+];
+`;
+writeFileSync(join(dirname(fileURLToPath(import.meta.url)), "units.gen.ts"), out);
+console.error(`${ids.length} unit ids from ${repo}@${ref} written to src/spec/units.gen.ts`);

package/src/spec/overlay/canvas.overlay.json

@@ -0,0 +1,142 @@
+{
+  "$comment": "Corrections to the vendored canvas.jsonschema.json (foundation-sdk v0.0.20). Sources are Grafana's CUE at the tag in `grafana`. See src/spec/overlay.ts.",
+  "schema": "canvas",
+  "grafana": "v13.2.2",
+  "patches": [
+    {
+      "op": "add",
+      "path": "/definitions/TooltipDisplayMode",
+      "value": {
+        "enum": [
+          "single",
+          "multi",
+          "none"
+        ],
+        "type": "string"
+      },
+      "source": "packages/grafana-schema/src/common/mudball.cue:237",
+      "why": "Definition for CanvasTooltip.mode, below."
+    },
+    {
+      "op": "add",
+      "path": "/definitions/CanvasTooltip",
+      "value": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "mode"
+        ],
+        "properties": {
+          "mode": {
+            "$ref": "#/definitions/TooltipDisplayMode"
+          },
+          "disableForOneClick": {
+            "type": "boolean"
+          }
+        }
+      },
+      "source": "public/app/plugins/panel/canvas/panelcfg.cue:92-95",
+      "why": "Definition for Options.tooltip, below."
+    },
+    {
+      "op": "add",
+      "path": "/definitions/Options/properties/tooltip",
+      "value": {
+        "$ref": "#/definitions/CanvasTooltip",
+        "description": "Controls tooltip options"
+      },
+      "source": "public/app/plugins/panel/canvas/panelcfg.cue:116-117",
+      "why": "In the CUE's Options; Grafana writes it into every canvas it loads."
+    },
+    {
+      "op": "add",
+      "path": "/definitions/Options/properties/zoomToContent",
+      "value": {
+        "type": "boolean",
+        "default": true,
+        "description": "Zoom to content"
+      },
+      "source": "public/app/plugins/panel/canvas/panelcfg.cue:104-105",
+      "why": "In the CUE's Options; Grafana writes it into every canvas it loads."
+    },
+    {
+      "op": "add",
+      "path": "/definitions/DirectionDimensionConfig",
+      "value": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "mode"
+        ],
+        "properties": {
+          "field": {
+            "type": "string"
+          },
+          "mode": {
+            "enum": [
+              "fixed",
+              "field"
+            ],
+            "type": "string"
+          },
+          "fixed": {
+            "enum": [
+              "forward",
+              "reverse",
+              "both",
+              "none"
+            ],
+            "type": "string"
+          }
+        }
+      },
+      "source": "packages/grafana-schema/src/common/dimensions.cue:51-59",
+      "why": "Definition for CanvasConnection.direction, below."
+    },
+    {
+      "op": "add",
+      "path": "/definitions/CanvasConnection/properties/direction",
+      "value": {
+        "$ref": "#/definitions/DirectionDimensionConfig"
+      },
+      "source": "public/app/plugins/panel/canvas/panelcfg.cue:76",
+      "why": "In the CUE's CanvasConnection; Grafana writes it for a connection drawn with an arrow direction."
+    },
+    {
+      "op": "add",
+      "path": "/definitions/Options/properties/root/properties/constraint",
+      "value": {
+        "$ref": "#/definitions/Constraint"
+      },
+      "source": "public/app/plugins/panel/canvas/panelcfg.cue:108-115",
+      "why": "The CUE lists only name, type and elements on the root, but the root is a frame element (CanvasFrameOptions extends CanvasElementOptions, public/app/features/canvas/frame.ts:3 at v13.2.2) and Grafana writes the element's constraint on it, as panelcfg.cue:86-89 types it for every other element."
+    },
+    {
+      "op": "add",
+      "path": "/definitions/Options/properties/root/properties/placement",
+      "value": {
+        "$ref": "#/definitions/Placement"
+      },
+      "source": "public/app/plugins/panel/canvas/panelcfg.cue:108-115",
+      "why": "The CUE lists only name, type and elements on the root, but the root is a frame element (CanvasFrameOptions extends CanvasElementOptions, public/app/features/canvas/frame.ts:3 at v13.2.2) and Grafana writes the element's placement on it, as panelcfg.cue:86-89 types it for every other element."
+    },
+    {
+      "op": "add",
+      "path": "/definitions/Options/properties/root/properties/background",
+      "value": {
+        "$ref": "#/definitions/BackgroundConfig"
+      },
+      "source": "public/app/plugins/panel/canvas/panelcfg.cue:108-115",
+      "why": "The CUE lists only name, type and elements on the root, but the root is a frame element (CanvasFrameOptions extends CanvasElementOptions, public/app/features/canvas/frame.ts:3 at v13.2.2) and Grafana writes the element's background on it, as panelcfg.cue:86-89 types it for every other element."
+    },
+    {
+      "op": "add",
+      "path": "/definitions/Options/properties/root/properties/border",
+      "value": {
+        "$ref": "#/definitions/LineConfig"
+      },
+      "source": "public/app/plugins/panel/canvas/panelcfg.cue:108-115",
+      "why": "The CUE lists only name, type and elements on the root, but the root is a frame element (CanvasFrameOptions extends CanvasElementOptions, public/app/features/canvas/frame.ts:3 at v13.2.2) and Grafana writes the element's border on it, as panelcfg.cue:86-89 types it for every other element."
+    }
+  ]
+}