@intentius/chant-lexicon-grafana 0.98.0 → 0.100.0

package/src/skills/chant-grafana.md

@@ -26,11 +26,11 @@ const tempo = new Datasource({ name: "Tempo", type: "tempo", url: "http://tempo:
 export { prometheus, tempo };
 ```
 
-The uid defaults to the name as a uid (`prometheus`, `tempo`). Secrets go in `secureJsonData` as `"$__env{NAME}"` or `"$__file{/path}"`, never literally (GRAF002). A declared `Datasource` inside `jsonData` is written as its uid, which is how a Tempo datasource links to Loki or Prometheus.
+The uid defaults to the name as a uid (`prometheus`, `tempo`). Secrets go in `secureJsonData` as `"$__env{NAME}"` or `"$__file{/path}"`, never literally (GRAF002). `jsonData` and the `secureJsonData` keys are typed per plugin for every plugin with a query class. A declared `Datasource` inside `jsonData` is written as its uid, which is how a Tempo datasource links to Loki or Prometheus and a Prometheus exemplar to Tempo; a link field only takes a datasource of a type Grafana offers there.
 
 ## Queries
 
-`PromQuery` (PromQL in `expr`), `TempoQuery` (TraceQL in `query`) and `LokiQuery` (LogQL in `expr`). Fields are typed from Grafana's own query schemas. `datasource` only accepts a datasource of the query's plugin type, so a PromQL query can't be pointed at Tempo.
+`PromQuery` (PromQL in `expr`), `TempoQuery` (TraceQL in `query`), `LokiQuery` (LogQL in `expr`), `ElasticsearchQuery`, `CloudWatchQuery`, `AzureMonitorQuery`, `CloudMonitoringQuery`, `BigQueryQuery`, `PyroscopeQuery`, and `PostgresQuery`, `MySQLQuery` and `MSSQLQuery` (SQL in `rawSql`). Fields are typed from Grafana's own query schemas, or by hand for SQL. `datasource` only accepts a datasource of the query's plugin type, so a PromQL query can't be pointed at Tempo.
 
 ```ts
 const requestRate = new PromQuery({
@@ -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,23 @@ 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, ad hoc and group by 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; an object-form variable query is checked on its `query`).
+- GRAF109: the dashboard providers put each dashboard in its declared folder, and no two load the same files.
+- GRAF110: a panel or row repeats over a query, custom or datasource variable with `multi` or `includeAll`, or a group by variable; anything else shows it once (warning).
+- 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."
+    }
+  ]
+}