@intentius/chant-lexicon-grafana 0.96.0

package/src/composites/red-dashboard.ts

@@ -0,0 +1,159 @@
+/**
+ * `RedDashboard`: rate, errors and duration per service, from a
+ * `spanmetrics` connector declaration.
+ *
+ * The metric names come from the connector's config through the otel
+ * lexicon's `spanMetricsNames()`: its namespace, its histogram unit, the
+ * default dimensions it keeps, and optionally the `prometheus` exporter's
+ * namespace. Renaming the connector's namespace moves every query here.
+ */
+
+import { Composite, type CompositeInstance } from "@intentius/chant/composite";
+import { spanMetricsNames, type PrometheusNaming, type SpanMetricsNames } from "@intentius/chant-lexicon-otel/metric-names";
+import type { OTelComponent } from "@intentius/chant-lexicon-otel/define";
+import type { SpanMetricsConnectorConfig } from "@intentius/chant-lexicon-otel/components/connectors";
+import type { PrometheusExporterConfig } from "@intentius/chant-lexicon-otel/components/exporters";
+import { Dashboard, type DashboardEntity } from "../dashboard";
+import { Row, 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 RedDashboardProps extends DashboardOptions {
+  /**
+   * The `spanmetrics` connector the metrics come from, or the names
+   * `spanMetricsNames()` returned for it.
+   */
+  spanMetrics: OTelComponent<"connector", "spanmetrics", SpanMetricsConnectorConfig> | SpanMetricsNames;
+  /** The `prometheus` exporter that serves them, when its `namespace` or `add_metric_suffixes` changes the names. */
+  exporter?: OTelComponent<"exporter", "prometheus", PrometheusExporterConfig> | PrometheusNaming;
+  /** Duration quantiles, one panel each (default p50, p95 and p99). */
+  quantiles?: number[];
+}
+
+export type RedDashboardMembers = { dashboard: DashboardEntity };
+
+/** What `RedDashboard(...)` returns: its dashboard, as `dashboard`. */
+export type RedDashboardInstance = CompositeInstance<RedDashboardMembers> & RedDashboardMembers;
+
+const DEFAULT_QUANTILES = [0.5, 0.95, 0.99];
+
+function isNames(x: unknown): x is SpanMetricsNames {
+  return typeof x === "object" && x !== null && "calls" in x && "labels" in x && "errorStatus" in x;
+}
+
+/** The PromQL the RED dashboard runs, from the connector's names. Exposed for tests and for panels of your own. */
+export function redQueries(names: SpanMetricsNames, quantiles: number[] = DEFAULT_QUANTILES, serviceFilter = "$service") {
+  const svc = names.labels.service;
+  const status = names.labels.statusCode;
+  if (!svc) throw new Error("RedDashboard: the connector excludes service.name, so there is no service to break the metrics down by");
+  if (!status) throw new Error("RedDashboard: the connector excludes status.code, so errors can't be told from successes");
+  const bySvc: Matcher[] = [[svc, "=~", serviceFilter]];
+  const calls = selector(names.calls.prometheus, bySvc);
+  const errors = selector(names.calls.prometheus, [...bySvc, [status, "=", names.errorStatus]]);
+  const buckets = names.duration ? selector(`${names.duration.prometheus}_bucket`, bySvc) : undefined;
+  return {
+    rate: sumRate(calls, [svc]),
+    errorRatio: `${sumRate(errors, [svc])}\n/\n${sumRate(calls, [svc])}`,
+    duration: buckets ? quantiles.map((q) => ({ quantile: q, expr: quantile(q, buckets, [svc]) })) : [],
+    services: `label_values(${names.calls.prometheus}, ${svc})`,
+  };
+}
+
+/**
+ * A RED dashboard (rate, errors, duration) per service, built from a
+ * `spanmetrics` connector declaration.
+ *
+ * @example
+ * ```ts
+ * import { SpanMetricsConnector } from "@intentius/chant-lexicon-otel";
+ * import { Datasource, RedDashboard } from "@intentius/chant-lexicon-grafana";
+ *
+ * export const spans = new SpanMetricsConnector({ namespace: "shop", histogram: { unit: "s" } });
+ * export const prometheus = new Datasource({ name: "Prometheus", type: "prometheus", url: "http://prometheus:9090" });
+ * export const red = RedDashboard({ spanMetrics: spans, datasource: prometheus });
+ * ```
+ */
+export const RedDashboard = Composite<RedDashboardProps, RedDashboardMembers>((props) => {
+  requireDatasource("RedDashboard", props.datasource);
+  if (!props.spanMetrics) throw new Error("RedDashboard: spanMetrics is required (a spanmetrics connector)");
+  const names = isNames(props.spanMetrics) ? props.spanMetrics : spanMetricsNames(props.spanMetrics, props.exporter);
+  const quantiles = props.quantiles ?? DEFAULT_QUANTILES;
+  for (const q of quantiles) {
+    if (!(typeof q === "number" && q > 0 && q < 1)) throw new Error(`RedDashboard: a quantile must be between 0 and 1, got ${String(q)}`);
+  }
+  const q = redQueries(names, quantiles);
+  const svc = names.labels.service!;
+  const ds = props.datasource;
+
+  const service = new QueryVariable({
+    name: "service",
+    label: "Service",
+    datasource: ds,
+    query: q.services,
+    multi: true,
+    includeAll: true,
+    allValue: ".*",
+    refresh: "onTimeRangeChange",
+    sort: 1,
+  });
+
+  const rate = new TimeSeriesPanel({
+    title: "Rate",
+    description: `Spans per second by service, from ${names.calls.prometheus}.`,
+    datasource: ds,
+    gridPos: { w: 12, h: 8 },
+    targets: [new PromQuery({ expr: q.rate, legendFormat: legend(svc) })],
+    fieldConfig: { defaults: { unit: "reqps" } },
+  });
+  const errors = new TimeSeriesPanel({
+    title: "Errors",
+    description: `Share of spans with ${names.labels.statusCode}="${names.errorStatus}", by service.`,
+    datasource: ds,
+    gridPos: { w: 12, h: 8 },
+    targets: [new PromQuery({ expr: q.errorRatio, legendFormat: legend(svc) })],
+    fieldConfig: { defaults: { unit: "percentunit", min: 0 } },
+  });
+
+  const rows = [new Row({ title: "Rate and errors", panels: [rate, errors] })];
+  if (names.duration && q.duration.length > 0) {
+    const width = Math.max(6, Math.floor(24 / q.duration.length));
+    const unit = durationUnit(names.duration.unit);
+    const panels = q.duration.map(
+      (d) =>
+        new TimeSeriesPanel({
+          title: `Duration ${quantileName(d.quantile)}`,
+          description: `${quantileName(d.quantile)} span duration by service, from ${names.duration!.prometheus}.`,
+          datasource: ds,
+          gridPos: { w: width, h: 8 },
+          targets: [new PromQuery({ expr: d.expr, legendFormat: legend(svc) })],
+          fieldConfig: { defaults: { unit } },
+        }),
+    );
+    rows.push(new Row({ title: "Duration", panels }));
+  }
+
+  const dashboard = new Dashboard({
+    ...dashboardProps(props, {
+      title: "Services: rate, errors, duration",
+      uid: slugUid(`red-${names.namespace || "spans"}`),
+      description: `Rate, errors and duration per service from the ${names.namespace || "unprefixed"} span metrics.`,
+      tags: ["red", "spanmetrics"],
+    }),
+    variables: [service],
+    panels: rows,
+  });
+  return { dashboard };
+}, "RedDashboard");

package/src/composites/shared.ts

@@ -0,0 +1,94 @@
+/**
+ * What the dashboard composites share: the dashboard-level props they all
+ * take, a PromQL selector builder, and the field configs they reuse.
+ */
+
+import type { DatasourceInput } from "../query";
+import type { DashboardLinkInput } from "../dashboard";
+import type { ThresholdsConfig } from "../schema/dashboard.gen";
+
+/** Dashboard settings every composite takes; each has a default derived from what it reads. */
+export interface DashboardOptions {
+  /** The Prometheus the metrics are queried from: a declared `Datasource`, or `{ type: "prometheus", uid }` for one declared elsewhere. */
+  datasource: DatasourceInput<"prometheus">;
+  title?: string;
+  /** The dashboard uid. Defaults to one derived from the source declaration. */
+  uid?: string;
+  description?: string;
+  tags?: string[];
+  /** The Grafana folder to provision it into. */
+  folder?: string;
+  /** Initial time range. */
+  time?: { from: string; to: string };
+  /** Auto-refresh interval, e.g. `30s`. */
+  refresh?: string;
+  links?: DashboardLinkInput[];
+}
+
+/** A label matcher: `[label, op, value]`. */
+export type Matcher = [label: string, op: "=" | "!=" | "=~" | "!~", value: string];
+
+/** `metric{a="x", b=~"y"}`; just `metric` with no matchers. */
+export function selector(metric: string, matchers: Matcher[]): string {
+  if (matchers.length === 0) return metric;
+  return `${metric}{${matchers.map(([l, op, v]) => `${l}${op}${JSON.stringify(v)}`).join(", ")}}`;
+}
+
+/** `sum by (labels) (rate(sel[range]))`, or `sum (...)` with no labels. */
+export function sumRate(sel: string, by: string[], range = "$__rate_interval"): string {
+  return `sum${by.length ? ` by (${by.join(", ")})` : ""} (rate(${sel}[${range}]))`;
+}
+
+/** `histogram_quantile(q, sum by (le, labels) (rate(bucket[range])))`. */
+export function quantile(q: number, bucketSel: string, by: string[]): string {
+  return `histogram_quantile(${num(q)}, ${sumRate(bucketSel, ["le", ...by])})`;
+}
+
+/** A number as PromQL and Grafana thresholds write it, without float noise. */
+export function num(n: number): string {
+  return String(Number(n.toPrecision(10)));
+}
+
+/** `p95` for 0.95, `p99.9` for 0.999. */
+export function quantileName(q: number): string {
+  return `p${num(q * 100)}`;
+}
+
+/** Legend text naming the label, `{{service_name}}`. */
+export function legend(...labels: string[]): string {
+  return labels.map((l) => `{{${l}}}`).join(" ");
+}
+
+/** Grafana's unit id for a spanmetrics histogram unit (`ms` or `s`). */
+export function durationUnit(unit: string | undefined): string {
+  return unit === "s" ? "s" : "ms";
+}
+
+/** Absolute thresholds from a base colour and `[value, colour]` steps. */
+export function thresholds(base: string, steps: Array<[number, string]>): ThresholdsConfig {
+  return { mode: "absolute", steps: [{ value: null, color: base }, ...steps.map(([value, color]) => ({ value, color }))] };
+}
+
+/** The props a composite passes to `Dashboard`, from the options and its own defaults. */
+export function dashboardProps(o: DashboardOptions, defaults: { title: string; uid: string; description: string; tags: string[] }) {
+  return {
+    title: o.title ?? defaults.title,
+    uid: o.uid ?? defaults.uid,
+    description: o.description ?? defaults.description,
+    tags: o.tags ?? defaults.tags,
+    time: o.time ?? { from: "now-6h", to: "now" },
+    ...(o.refresh !== undefined ? { refresh: o.refresh } : { refresh: "1m" }),
+    graphTooltip: "sharedCrosshair" as const,
+    ...(o.folder !== undefined ? { folder: o.folder } : {}),
+    ...(o.links !== undefined ? { links: o.links } : {}),
+  };
+}
+
+/** Throw unless a Prometheus datasource was passed. */
+export function requireDatasource(composite: string, ds: unknown): void {
+  if (ds === undefined || ds === null) throw new Error(`${composite}: datasource is required (a Prometheus Datasource or { type: "prometheus", uid })`);
+  const type = (ds as { datasourceType?: unknown; pluginType?: unknown; type?: unknown }).datasourceType ??
+    (ds as { pluginType?: unknown }).pluginType ??
+    (ds as { type?: unknown }).type;
+  if (type !== "prometheus") throw new Error(`${composite}: datasource must be a Prometheus datasource, got ${String(type)}`);
+}

package/src/composites/slo-dashboard.ts

@@ -0,0 +1,177 @@
+/**
+ * `SloDashboard`: one SLO's SLI, error budget and burn rates, from an `Slo`
+ * declaration.
+ *
+ * Every series name, the objective, the window and the burn-rate pairs come
+ * from the prometheus lexicon's `sloMetrics()`, which reads the same
+ * declaration the rules are built from. Renaming the SLO, changing its
+ * objective or its windows moves the panels and their threshold lines with
+ * it.
+ */
+
+import { Composite, type CompositeInstance } from "@intentius/chant/composite";
+import { sloMetrics, type SloInstance, type SloMetrics } from "@intentius/chant-lexicon-prometheus/composites/slo";
+import type { RuleGroupEntity } from "@intentius/chant-lexicon-prometheus/rules";
+import { Dashboard, type DashboardEntity } from "../dashboard";
+import { Row, StatPanel, TimeSeriesPanel } from "../panels";
+import { PromQuery } from "../query";
+import { slugUid } from "../util";
+import { dashboardProps, num, requireDatasource, selector, thresholds, type DashboardOptions } from "./shared";
+
+export interface SloDashboardProps extends DashboardOptions {
+  /** The `Slo(...)` the dashboard reads, its rule group, or what `sloMetrics()` returned for it. */
+  slo: SloInstance | RuleGroupEntity | SloMetrics;
+}
+
+export type SloDashboardMembers = { dashboard: DashboardEntity };
+
+/** What `SloDashboard(...)` returns: its dashboard, as `dashboard`. */
+export type SloDashboardInstance = CompositeInstance<SloDashboardMembers> & SloDashboardMembers;
+
+function isMetrics(x: unknown): x is SloMetrics {
+  return typeof x === "object" && x !== null && "errorBudgetRemaining" in x && "burnRates" in x && "selector" in x;
+}
+
+/** The PromQL the SLO dashboard runs, from `sloMetrics()`. Exposed for tests and for panels of your own. */
+export function sloQueries(m: SloMetrics) {
+  const s = (series: string) => `${series}${m.selector}`;
+  const budget = num(m.errorBudget);
+  return {
+    sli: `1 - ${s(m.windowErrorRatio)}`,
+    objective: s(m.objectiveRatio),
+    errorBudgetRemaining: s(m.errorBudgetRemaining),
+    alertsFiring: `sum(${selector("ALERTS", [
+      ["alertname", "=", m.alertName],
+      ["slo", "=", m.name],
+      ["alertstate", "=", "firing"],
+    ])}) or vector(0)`,
+    burnRates: m.burnRates.map((b) => ({
+      ...b,
+      longExpr: `${s(b.longRecord)} / ${budget}`,
+      shortExpr: `${s(b.shortRecord)} / ${budget}`,
+    })),
+  };
+}
+
+const PERCENT = { unit: "percentunit", decimals: 3 };
+
+/**
+ * A dashboard for one SLO: the SLI over its window against the objective,
+ * the error budget left, and each burn-rate alert's two windows with the
+ * rate it fires at drawn as a threshold line.
+ *
+ * @example
+ * ```ts
+ * import { Slo } from "@intentius/chant-lexicon-prometheus";
+ * import { SloDashboard } from "@intentius/chant-lexicon-grafana";
+ *
+ * export const checkout = Slo({ name: "checkout", objective: 0.999, window: "30d", sli: { ... } });
+ * export const checkoutSlo = SloDashboard({ slo: checkout, datasource: prometheus });
+ * ```
+ */
+export const SloDashboard = Composite<SloDashboardProps, SloDashboardMembers>((props) => {
+  requireDatasource("SloDashboard", props.datasource);
+  if (!props.slo) throw new Error("SloDashboard: slo is required (an Slo(...) declaration)");
+  const m = isMetrics(props.slo) ? props.slo : sloMetrics(props.slo);
+  const q = sloQueries(m);
+  const ds = props.datasource;
+  const objective = num(m.objective * 100);
+
+  const sli = new StatPanel({
+    title: `SLI over ${m.window}`,
+    description: `Share of good events over the last ${m.window}. Green at or above the ${objective}% objective.`,
+    datasource: ds,
+    gridPos: { w: 6, h: 5 },
+    targets: [new PromQuery({ expr: q.sli, legendFormat: "SLI" })],
+    options: { colorMode: "background", graphMode: "none", reduceOptions: { calcs: ["lastNotNull"] } },
+    fieldConfig: { defaults: { ...PERCENT, thresholds: thresholds("red", [[m.objective, "green"]]) } },
+  });
+  const target = new StatPanel({
+    title: "Objective",
+    datasource: ds,
+    gridPos: { w: 6, h: 5 },
+    targets: [new PromQuery({ expr: q.objective, legendFormat: "objective" })],
+    options: { colorMode: "none", graphMode: "none", reduceOptions: { calcs: ["lastNotNull"] } },
+    fieldConfig: { defaults: PERCENT },
+  });
+  const remaining = new StatPanel({
+    title: "Error budget remaining",
+    description: `Share of the ${m.window} error budget (${num(m.errorBudget * 100)}% of events) not yet spent. Below 0 the objective is missed.`,
+    datasource: ds,
+    gridPos: { w: 6, h: 5 },
+    targets: [new PromQuery({ expr: q.errorBudgetRemaining, legendFormat: "remaining" })],
+    options: { colorMode: "background", graphMode: "area", reduceOptions: { calcs: ["lastNotNull"] } },
+    fieldConfig: { defaults: { unit: "percentunit", decimals: 1, thresholds: thresholds("red", [[0, "orange"], [0.25, "green"]]) } },
+  });
+  const firing = new StatPanel({
+    title: "Burn-rate alerts firing",
+    description: `${m.alertName} alerts for this SLO, any tier.`,
+    datasource: ds,
+    gridPos: { w: 6, h: 5 },
+    targets: [new PromQuery({ expr: q.alertsFiring, legendFormat: "firing" })],
+    options: { colorMode: "background", graphMode: "none", reduceOptions: { calcs: ["lastNotNull"] } },
+    fieldConfig: { defaults: { unit: "none", decimals: 0, thresholds: thresholds("green", [[1, "red"]]) } },
+  });
+
+  const sliOverTime = new TimeSeriesPanel({
+    title: `SLI over ${m.window}`,
+    description: `The dashed line is the ${objective}% objective.`,
+    datasource: ds,
+    gridPos: { w: 12, h: 8 },
+    targets: [new PromQuery({ expr: q.sli, legendFormat: "SLI" })],
+    fieldConfig: {
+      defaults: { ...PERCENT, thresholds: thresholds("red", [[m.objective, "green"]]), custom: { thresholdsStyle: { mode: "dashed" } } },
+    },
+  });
+  const budgetOverTime = new TimeSeriesPanel({
+    title: "Error budget remaining",
+    datasource: ds,
+    gridPos: { w: 12, h: 8 },
+    targets: [new PromQuery({ expr: q.errorBudgetRemaining, legendFormat: "remaining" })],
+    fieldConfig: {
+      defaults: { unit: "percentunit", decimals: 1, thresholds: thresholds("red", [[0, "green"]]), custom: { thresholdsStyle: { mode: "dashed" } } },
+    },
+  });
+
+  const rows = [new Row({ title: "Objective", panels: [sli, target, remaining, firing, sliOverTime, budgetOverTime] })];
+
+  if (q.burnRates.length > 0) {
+    const panels = q.burnRates.map(
+      (b) =>
+        new TimeSeriesPanel({
+          title: `Burn rate ${b.long} / ${b.short} (${b.severity})`,
+          description:
+            `Error ratio over the budget: 1 spends the ${m.window} budget exactly over ${m.window}. ` +
+            `${b.alert} fires with severity ${b.severity} while both windows are above ${num(b.factor)}, which spends the budget in ${b.exhaustsIn}.`,
+          datasource: ds,
+          gridPos: { w: 12, h: 8 },
+          targets: [
+            new PromQuery({ expr: b.longExpr, legendFormat: b.long }),
+            new PromQuery({ expr: b.shortExpr, legendFormat: b.short }),
+          ],
+          fieldConfig: {
+            defaults: {
+              unit: "suffix:x",
+              decimals: 2,
+              min: 0,
+              thresholds: thresholds("green", [[b.factor, "red"]]),
+              custom: { thresholdsStyle: { mode: "dashed" } },
+            },
+          },
+        }),
+    );
+    rows.push(new Row({ title: "Burn rate by alert window", panels }));
+  }
+
+  const dashboard = new Dashboard({
+    ...dashboardProps(props, {
+      title: `SLO: ${m.name}`,
+      uid: slugUid(`slo-${m.name}`),
+      description: `${objective}% over ${m.window}: SLI, error budget and burn rates for the ${m.name} SLO.`,
+      tags: ["slo", m.name],
+    }),
+    time: props.time ?? { from: "now-7d", to: "now" },
+    panels: rows,
+  });
+  return { dashboard };
+}, "SloDashboard");

package/src/dashboard.ts

@@ -0,0 +1,123 @@
+/**
+ * `Dashboard` and `DashboardProvider`.
+ *
+ * A dashboard is written to `dashboards/<folder>/<uid>.json`, the JSON
+ * Grafana imports as it is. A provider is the entry in
+ * `provisioning/dashboards/chant.yaml` that points Grafana at those files;
+ * a build with dashboards and no declared provider gets a default one.
+ */
+
+import { createResource } from "@intentius/chant/runtime";
+import type { Declarable } from "@intentius/chant/declarable";
+import type { PanelEntity, RowEntity } from "./panels";
+import type { VariableEntity } from "./variables";
+import type { DashboardLink, TimePickerConfig } from "./schema/dashboard.gen";
+
+/** A dashboard link: `title` and `type` required, the rest defaulted as Grafana's editor would. */
+export type DashboardLinkInput = Partial<DashboardLink> & Pick<DashboardLink, "title" | "type">;
+
+export interface DashboardProps {
+  title: string;
+  /**
+   * Stable id: links, provisioning and the API address a dashboard by it.
+   * Letters, digits, `-` and `_`, at most 40 characters. Defaults to the
+   * export name as a uid (`checkoutService` becomes `checkout-service`).
+   */
+  uid?: string;
+  description?: string;
+  tags?: string[];
+  /** Initial time range. Defaults to the last 6 hours. */
+  time?: { from: string; to: string };
+  /** Auto-refresh interval, e.g. `30s`. */
+  refresh?: string;
+  /** `browser`, `utc` or an IANA zone. Defaults to `browser`. */
+  timezone?: string;
+  weekStart?: string;
+  fiscalYearStartMonth?: number;
+  liveNow?: boolean;
+  timepicker?: TimePickerConfig;
+  /** Shared crosshair or tooltip across panels. */
+  graphTooltip?: "default" | "sharedCrosshair" | "sharedTooltip";
+  /** Whether users may edit it in the UI. Defaults to true, as in Grafana. */
+  editable?: boolean;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  variables?: VariableEntity<any>[];
+  /** Panels and rows, top to bottom. A row's own `panels` follow it. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  panels?: Array<PanelEntity<any, any> | RowEntity>;
+  links?: DashboardLinkInput[];
+  /**
+   * The Grafana folder to provision it into. Written as a subdirectory of
+   * `dashboards/`, which the provider maps to folders
+   * (`foldersFromFilesStructure`). Leave it out for the General folder.
+   */
+  folder?: string;
+}
+
+export interface DashboardEntity extends Declarable {
+  readonly props: DashboardProps;
+}
+
+export const DASHBOARD_TYPE = "Grafana::Dashboard";
+
+const DashboardBase = createResource(DASHBOARD_TYPE, "grafana", {}) as unknown as (this: object, props: Record<string, unknown>) => void;
+
+/** A Grafana dashboard. */
+export const Dashboard = function (this: object, props: DashboardProps) {
+  DashboardBase.call(this, props as unknown as Record<string, unknown>);
+} as unknown as new (props: DashboardProps) => DashboardEntity;
+Object.defineProperty(Dashboard, "name", { value: "Dashboard" });
+
+export function isDashboardEntity(value: unknown): value is DashboardEntity {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Declarable).entityType === DASHBOARD_TYPE &&
+    (value as Declarable).lexicon === "grafana"
+  );
+}
+
+/** Where Grafana finds the dashboard files by default: mount `dashboards/` here. */
+export const DEFAULT_DASHBOARDS_PATH = "/var/lib/grafana/dashboards";
+
+export interface DashboardProviderProps {
+  /** Provider name, unique in the provisioning file. */
+  name: string;
+  orgId?: number;
+  /** Folder for dashboards not in a subdirectory. */
+  folder?: string;
+  folderUid?: string;
+  /** Where the `dashboards/` output is mounted in the Grafana container. Defaults to `/var/lib/grafana/dashboards`. */
+  path?: string;
+  /** Map subdirectories to Grafana folders. Defaults to true, which is what a dashboard's `folder` relies on. */
+  foldersFromFilesStructure?: boolean;
+  disableDeletion?: boolean;
+  allowUiUpdates?: boolean;
+  updateIntervalSeconds?: number;
+}
+
+export interface DashboardProviderEntity extends Declarable {
+  readonly props: DashboardProviderProps;
+}
+
+export const DASHBOARD_PROVIDER_TYPE = "Grafana::DashboardProvider";
+
+const ProviderBase = createResource(DASHBOARD_PROVIDER_TYPE, "grafana", {}) as unknown as (
+  this: object,
+  props: Record<string, unknown>,
+) => void;
+
+/** An entry in the dashboard provisioning file. Optional: a default one is written when none is declared. */
+export const DashboardProvider = function (this: object, props: DashboardProviderProps) {
+  ProviderBase.call(this, props as unknown as Record<string, unknown>);
+} as unknown as new (props: DashboardProviderProps) => DashboardProviderEntity;
+Object.defineProperty(DashboardProvider, "name", { value: "DashboardProvider" });
+
+export function isDashboardProviderEntity(value: unknown): value is DashboardProviderEntity {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Declarable).entityType === DASHBOARD_PROVIDER_TYPE &&
+    (value as Declarable).lexicon === "grafana"
+  );
+}

package/src/datasource.ts

@@ -0,0 +1,93 @@
+/**
+ * `Datasource`: a Grafana datasource, declared once.
+ *
+ * A declared datasource is written to the datasource provisioning file, and
+ * panels, queries and variables hold the entity itself rather than a uid
+ * string. The class is generic in the plugin type, so a `PromQuery` cannot
+ * be pointed at a Tempo datasource without a type error.
+ */
+
+import { createResource } from "@intentius/chant/runtime";
+import type { Declarable } from "@intentius/chant/declarable";
+import { slugUid } from "./util";
+
+/** Datasource plugin types this lexicon types queries for. Any other plugin id is accepted as a string. */
+export type KnownDatasourceType = "prometheus" | "tempo" | "loki";
+
+/** How Grafana reaches the datasource: through its backend (`proxy`) or from the browser (`direct`). */
+export type DatasourceAccess = "proxy" | "direct";
+
+export interface DatasourceProps<T extends string = string> {
+  /** Display name, unique within the Grafana organisation. */
+  name: string;
+  /** The datasource plugin id, e.g. `prometheus`, `tempo`, `loki`. */
+  type: T;
+  /** Stable id panels refer to. Defaults to the name as a uid (`Prometheus` becomes `prometheus`). */
+  uid?: string;
+  url?: string;
+  access?: DatasourceAccess;
+  isDefault?: boolean;
+  basicAuth?: boolean;
+  basicAuthUser?: string;
+  user?: string;
+  database?: string;
+  withCredentials?: boolean;
+  /**
+   * Plugin settings. A declared `Datasource` anywhere in here is written as
+   * its uid, so `tracesToLogsV2: { datasourceUid: loki }` links Tempo to a
+   * declared Loki.
+   */
+  jsonData?: Record<string, unknown>;
+  /**
+   * Secrets. Write them as Grafana provisioning expands them
+   * (`$__env{NAME}`, `$__file{/path}`, `${NAME}`), not as literals: GRAF002
+   * flags a literal.
+   */
+  secureJsonData?: Record<string, string>;
+  /** Whether users may edit the provisioned datasource in the UI. Defaults to false. */
+  editable?: boolean;
+  orgId?: number;
+  version?: number;
+}
+
+export interface DatasourceEntity<T extends string = string> extends Declarable {
+  readonly props: DatasourceProps<T>;
+  /** The plugin id. */
+  readonly datasourceType: T;
+  /** The uid panels will reference. */
+  readonly uid: string;
+}
+
+export const DATASOURCE_TYPE = "Grafana::Datasource";
+
+const Base = createResource(DATASOURCE_TYPE, "grafana", {}) as unknown as (this: object, props: Record<string, unknown>) => void;
+
+export interface DatasourceConstructor {
+  new <T extends string>(props: DatasourceProps<T>): DatasourceEntity<T>;
+}
+
+/** A Grafana datasource, provisioned from `provisioning/datasources/chant.yaml`. */
+export const Datasource = function (this: object, props: DatasourceProps) {
+  Base.call(this, props as unknown as Record<string, unknown>);
+  Object.defineProperty(this, "datasourceType", { value: props.type, enumerable: false });
+  Object.defineProperty(this, "uid", { value: props.uid ?? slugUid(props.name), enumerable: false });
+} as unknown as DatasourceConstructor;
+Object.defineProperty(Datasource, "name", { value: "Datasource" });
+
+export function isDatasourceEntity(value: unknown): value is DatasourceEntity {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Declarable).entityType === DATASOURCE_TYPE &&
+    (value as Declarable).lexicon === "grafana"
+  );
+}
+
+/** A datasource declared somewhere this build can't see, named by its Grafana ref. */
+export interface DatasourceRef<T extends string = string> {
+  type: T;
+  uid: string;
+}
+
+/** Grafana's own pseudo-datasources, which need no declaration. */
+export const BUILTIN_DATASOURCE_UIDS: ReadonlySet<string> = new Set(["grafana", "-- Grafana --", "-- Mixed --", "-- Dashboard --"]);

package/src/detect.ts

@@ -0,0 +1,30 @@
+/**
+ * What a parsed Grafana document looks like. Kept free of the plugin and the
+ * TypeScript compiler so it bundles for edge runtimes, like the other
+ * lexicons' `detect` modules.
+ */
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Dashboard JSON: a `panels` array plus a `schemaVersion` or a `templating` block. */
+export function looksLikeDashboard(data: unknown): data is Record<string, unknown> {
+  if (!isObject(data)) return false;
+  return Array.isArray(data.panels) && (typeof data.schemaVersion === "number" || isObject(data.templating));
+}
+
+/** A datasource provisioning file: `apiVersion` and a `datasources` list. */
+export function looksLikeDatasourceProvisioning(data: unknown): data is { apiVersion: unknown; datasources: unknown[] } {
+  return isObject(data) && data.apiVersion !== undefined && Array.isArray(data.datasources);
+}
+
+/** A dashboard provisioning file: `apiVersion` and a `providers` list. */
+export function looksLikeDashboardProvisioning(data: unknown): data is { apiVersion: unknown; providers: unknown[] } {
+  return isObject(data) && data.apiVersion !== undefined && Array.isArray(data.providers);
+}
+
+/** Template detection for `chant import` and friends: any of the three. */
+export function detectTemplate(data: unknown): boolean {
+  return looksLikeDashboard(data) || looksLikeDatasourceProvisioning(data) || looksLikeDashboardProvisioning(data);
+}