@intentius/chant-lexicon-grafana 0.98.0 → 0.100.0

package/src/composites/slo-alert-rules.ts

@@ -0,0 +1,149 @@
+/**
+ * `SloAlertRules`: an `Slo`'s multiwindow, multi-burn-rate alerts as
+ * Grafana-managed alert rules, for teams that page from Grafana rather
+ * than from Prometheus and Alertmanager.
+ *
+ * The windows, factors, thresholds and labels come from the prometheus
+ * lexicon's `sloMetrics()`, the same numbers the `Slo`'s own Prometheus
+ * alerts use. Each burn-rate pair becomes one rule that reads the two
+ * error ratios the `Slo` records (`slo:sli_error:ratio_rate<window>`) as
+ * instant Prometheus queries, and a math expression that holds while both
+ * are above the pair's threshold:
+ *
+ *     A = slo:sli_error:ratio_rate1h{slo="checkout"}
+ *     B = slo:sli_error:ratio_rate5m{slo="checkout"}
+ *     C = $A > 0.0144 && $B > 0.0144        (condition)
+ *
+ * So the `Slo`'s rule group must be loaded into the Prometheus the rules
+ * query: the recording rules are what make a 3-day window cheap to
+ * evaluate every minute.
+ */
+
+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 {
+  AlertRule,
+  AlertRuleGroup,
+  MathExpression,
+  type AlertRuleGroupEntity,
+  type ContactPointEntity,
+  type ExecErrState,
+  type NoDataState,
+} from "../alerting";
+import { PromQuery, type DatasourceInput } from "../query";
+import { slugUid } from "../util";
+import { num, requireDatasource } from "./shared";
+
+export interface SloAlertRulesProps {
+  /** The `Slo(...)` the rules alert on, its rule group, or what `sloMetrics()` returned for it. It must have alerting on. */
+  slo: SloInstance | RuleGroupEntity | SloMetrics;
+  /** The Prometheus holding the `Slo`'s recorded series: a declared `Datasource`, an `ExternalDatasource`, or `{ type: "prometheus", uid }`. */
+  datasource: DatasourceInput<"prometheus">;
+  /** The Grafana folder the rules are stored in, by title. */
+  folder: string;
+  /** The rule group's name. Defaults to the `Slo`'s group name, `slo-<name>`. */
+  group?: string;
+  /** How often the rules are evaluated, a multiple of 10s. Defaults to `1m`. */
+  interval?: string;
+  /**
+   * Send the alerts straight to this contact point. Left out, they go
+   * through the notification policy tree, which can route on the
+   * `severity` label (`page` or `ticket` by default).
+   */
+  contactPoint?: ContactPointEntity | string;
+  /** How long a pair must hold before its alert fires. Default: none; the short window already filters blips. */
+  for?: string;
+  /** More labels on every rule, e.g. `team`. */
+  labels?: Record<string, string>;
+  /** More annotations on every rule, e.g. `runbook_url`. */
+  annotations?: Record<string, string>;
+  /** What no data does. Defaults to `OK`: no recorded ratio means no traffic, so no budget is burning. */
+  noDataState?: NoDataState;
+  /** What a query error does. Defaults to `Error`. */
+  execErrState?: ExecErrState;
+}
+
+export type SloAlertRulesMembers = {
+  /** One rule per burn-rate pair, page tier first. */
+  rules: AlertRuleGroupEntity;
+};
+
+/** What `SloAlertRules(...)` returns: its rule group, as `rules`. */
+export type SloAlertRulesInstance = CompositeInstance<SloAlertRulesMembers> & SloAlertRulesMembers;
+
+function isMetrics(x: unknown): x is SloMetrics {
+  return typeof x === "object" && x !== null && "errorBudgetRemaining" in x && "burnRates" in x && "selector" in x;
+}
+
+/** A rule uid for one pair: the SLO's name cut to fit, then the windows, at most 40 characters. */
+function pairUid(name: string, long: string, short: string): string {
+  const suffix = `-${long}-${short}`.toLowerCase();
+  return `${slugUid(`slo ${name}`).slice(0, 40 - suffix.length).replace(/-$/, "")}${suffix}`;
+}
+
+/** The queries and condition of each burn-rate rule, from `sloMetrics()`. Exposed for tests and for rules of your own. */
+export function sloAlertQueries(m: SloMetrics) {
+  return m.burnRates.map((b) => ({
+    ...b,
+    uid: pairUid(m.name, b.long, b.short),
+    longExpr: `${b.longRecord}${m.selector}`,
+    shortExpr: `${b.shortRecord}${m.selector}`,
+    condition: `$A > ${num(b.threshold)} && $B > ${num(b.threshold)}`,
+  }));
+}
+
+/**
+ * Grafana-managed burn-rate alerts for an `Slo`: one rule per window pair,
+ * with the labels and annotations the `Slo`'s Prometheus alerts carry.
+ *
+ * @example
+ * ```ts
+ * import { Slo } from "@intentius/chant-lexicon-prometheus";
+ * import { SloAlertRules } from "@intentius/chant-lexicon-grafana";
+ *
+ * export const checkout = Slo({ name: "checkout", objective: 0.999, window: "30d", sli: { ... } });
+ * export const checkoutAlerts = SloAlertRules({ slo: checkout, datasource: prometheus, folder: "SLOs" });
+ * ```
+ */
+export const SloAlertRules = Composite<SloAlertRulesProps, SloAlertRulesMembers>((props) => {
+  requireDatasource("SloAlertRules", props.datasource);
+  if (!props.slo) throw new Error("SloAlertRules: slo is required (an Slo(...) declaration)");
+  if (typeof props.folder !== "string" || props.folder.trim() === "") throw new Error("SloAlertRules: folder is required (the Grafana folder title)");
+  const m = isMetrics(props.slo) ? props.slo : sloMetrics(props.slo);
+  const pairs = sloAlertQueries(m);
+  if (pairs.length === 0) {
+    throw new Error(`SloAlertRules: the Slo "${m.name}" has alerting turned off, so it has no burn-rate windows to alert on`);
+  }
+  const ds = props.datasource;
+  const budget = num(m.errorBudget);
+  const rules = pairs.map(
+    (p) =>
+      new AlertRule({
+        title: `SLO ${m.name} error budget burn ${p.long}/${p.short} (${p.severity})`,
+        uid: p.uid,
+        data: [
+          new PromQuery({ datasource: ds, expr: p.longExpr, instant: true, range: false }),
+          new PromQuery({ datasource: ds, expr: p.shortExpr, instant: true, range: false }),
+          new MathExpression({ expression: p.condition }),
+        ],
+        condition: "C",
+        noDataState: props.noDataState ?? "OK",
+        execErrState: props.execErrState ?? "Error",
+        ...(props.for !== undefined ? { for: props.for } : {}),
+        labels: { ...(props.labels ?? {}), ...p.labels },
+        annotations: {
+          summary: `SLO ${m.name} is burning its error budget more than ${num(p.factor)}x too fast (${p.long} and ${p.short} windows)`,
+          description:
+            `The error ratio over both the last ${p.long} and the last ${p.short} is above ${num(p.threshold)} ` +
+            `(${num(p.factor)} times the ${budget} budget of a ${num(m.objective)} objective). ` +
+            `At that rate the ${m.window} error budget is gone in ${p.exhaustsIn}.`,
+          ...(props.annotations ?? {}),
+        },
+        ...(props.contactPoint !== undefined ? { notification_settings: { receiver: props.contactPoint } } : {}),
+      }),
+  );
+  return {
+    rules: new AlertRuleGroup({ name: props.group ?? m.group, folder: props.folder, interval: props.interval ?? "1m", rules }),
+  };
+}, "SloAlertRules");

package/src/config.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import { grafanaConfigSchema, resolveGrafanaTarget } from "./config";
+import { namespaceOf } from "./api/client";
+import { grafanaPlugin } from "./plugin";
+
+const config = {
+  grafana: {
+    profiles: {
+      prod: { url: "https://grafana.example.com/", token: { env: "GF_PROD" }, orgId: 2 },
+      local: { url: "http://localhost:3000", basicAuth: { user: { env: "GF_USER" }, password: { env: "GF_PASS" } } },
+    },
+  },
+};
+
+describe("grafana config namespace", () => {
+  it("is declared on the plugin and rejects an unknown key in a profile", () => {
+    expect(grafanaPlugin.configSchema).toBe(grafanaConfigSchema);
+    expect(grafanaConfigSchema.safeParse({ profiles: { prod: { url: "x", tokn: { env: "T" } } } }).success).toBe(false);
+    expect(grafanaConfigSchema.safeParse(config.grafana).success).toBe(true);
+  });
+});
+
+describe("resolveGrafanaTarget", () => {
+  it("binds an environment's profile, with the token from the variable it names", () => {
+    expect(resolveGrafanaTarget({ environment: "prod", config, env: { GF_PROD: "glsa_x" } })).toEqual({
+      url: "https://grafana.example.com",
+      auth: { token: "glsa_x" },
+      orgId: 2,
+      source: "grafana.profiles.prod",
+    });
+  });
+
+  it("basic auth, from two variables", () => {
+    expect(resolveGrafanaTarget({ environment: "local", config, env: { GF_USER: "admin", GF_PASS: "admin" } })).toMatchObject({ auth: { user: "admin", password: "admin" } });
+  });
+
+  it("a profile whose credential variable is unset is no-credentials, not an anonymous read", () => {
+    expect(resolveGrafanaTarget({ environment: "prod", config, env: {} })).toEqual({ reason: "no-credentials", detail: expect.stringContaining("GF_PROD") });
+    expect(resolveGrafanaTarget({ environment: "local", config, env: { GF_USER: "a" } })).toEqual({ reason: "no-credentials", detail: expect.stringContaining("GF_PASS") });
+  });
+
+  it("falls back to GRAFANA_URL and GRAFANA_TOKEN, or GRAFANA_USER and GRAFANA_PASSWORD", () => {
+    expect(resolveGrafanaTarget({ environment: "dev", config, env: { GRAFANA_URL: "http://g:3000", GRAFANA_TOKEN: "t", GRAFANA_ORG_ID: "3" } })).toEqual({
+      url: "http://g:3000",
+      auth: { token: "t" },
+      orgId: 3,
+      source: "env GRAFANA_URL",
+    });
+    expect(resolveGrafanaTarget({ env: { GRAFANA_URL: "http://g", GRAFANA_USER: "u", GRAFANA_PASSWORD: "p" } })).toMatchObject({ auth: { user: "u", password: "p" } });
+  });
+
+  it("no profile and no GRAFANA_URL is no-binding", () => {
+    expect(resolveGrafanaTarget({ environment: "dev", config, env: {} })).toEqual({ reason: "no-binding", detail: expect.stringContaining("grafana.profiles.dev") });
+  });
+
+  it("the dashboard API namespace follows the organisation", () => {
+    expect(namespaceOf({})).toBe("default");
+    expect(namespaceOf({ orgId: 4 })).toBe("org-4");
+    expect(namespaceOf({ orgId: 4, namespace: "stacks-12" })).toBe("stacks-12");
+  });
+});

package/src/config.ts

@@ -0,0 +1,138 @@
+/**
+ * The `grafana` namespace in `chant.config.ts` (#2946): which Grafana each
+ * chant environment observes, exports from and (#2948) applies to.
+ *
+ * ```ts
+ * import type { ChantConfig } from "@intentius/chant/config";
+ * import "@intentius/chant-lexicon-grafana";   // brings the `grafana` key into ChantConfig
+ *
+ * export default {
+ *   lexicons: ["grafana"],
+ *   grafana: {
+ *     profiles: {
+ *       staging: { url: "https://grafana.staging.example.com", token: { env: "GRAFANA_STAGING_TOKEN" } },
+ *       prod: { url: "https://grafana.example.com", token: { env: "GRAFANA_PROD_TOKEN" }, orgId: 2 },
+ *     },
+ *   },
+ * } satisfies ChantConfig;
+ * ```
+ *
+ * A profile is keyed by chant environment, as `k8s.profiles.<env>` is.
+ * Credentials are named by their environment variable, never written in
+ * the config. An environment with no profile falls back to `GRAFANA_URL`
+ * with `GRAFANA_TOKEN`, or `GRAFANA_USER` and `GRAFANA_PASSWORD` (see
+ * `resolveGrafanaTarget`).
+ *
+ * One schema, three consumers, as in the fountain lexicon: core validates the
+ * namespace against it at load, the type is derived from it, and that type
+ * augments `ChantConfig`.
+ */
+
+import { z } from "zod";
+import type { ChantConfig } from "@intentius/chant/config";
+import type { GrafanaAuth, GrafanaTarget } from "./api/client";
+
+const envRef = z.strictObject({ env: z.string() });
+
+export const grafanaProfileSchema = z.strictObject({
+  /** Base URL of the Grafana instance. */
+  url: z.string(),
+  /** A service account token, named by its environment variable. */
+  token: envRef.optional(),
+  /** Basic auth, each half named by its environment variable. For a local instance; use a token elsewhere. */
+  basicAuth: z.strictObject({ user: envRef, password: envRef }).optional(),
+  /** Organisation id. Defaults to 1. */
+  orgId: z.number().int().positive().optional(),
+  /** The `dashboard.grafana.app` namespace, when it is not `default` / `org-<id>` (Grafana Cloud: `stacks-<id>`). */
+  namespace: z.string().optional(),
+});
+
+export const grafanaConfigSchema = z.strictObject({
+  /** One Grafana per chant environment. */
+  profiles: z.record(z.string(), grafanaProfileSchema).optional(),
+});
+
+export type GrafanaProfile = z.infer<typeof grafanaProfileSchema>;
+export type GrafanaConfig = z.infer<typeof grafanaConfigSchema>;
+
+declare module "@intentius/chant/config" {
+  interface ChantConfig {
+    grafana?: GrafanaConfig;
+  }
+}
+
+/** Compile-time proof that the augmentation reaches `ChantConfig`. */
+export type GrafanaConfigNamespace = NonNullable<ChantConfig["grafana"]>;
+
+/** Why no target could be resolved, in the observation vocabulary. */
+export interface UnresolvedTarget {
+  readonly reason: "no-binding" | "no-credentials";
+  readonly detail: string;
+}
+
+function isUnresolved(v: GrafanaTarget | UnresolvedTarget): v is UnresolvedTarget {
+  return "reason" in v;
+}
+
+export { isUnresolved as isUnresolvedTarget };
+
+/**
+ * The Grafana an environment reads from. Pure: `config` and `env` are
+ * passed in.
+ *
+ * 1. `grafana.profiles.<environment>`. A profile that names a credential
+ *    variable which is not set is `no-credentials`, not an anonymous read:
+ *    the profile said how to authenticate.
+ * 2. `GRAFANA_URL`, with `GRAFANA_TOKEN`, or `GRAFANA_USER` and
+ *    `GRAFANA_PASSWORD`, or neither (an instance with anonymous access; a
+ *    refused read is then `no-credentials`).
+ * 3. Otherwise `no-binding`.
+ */
+export function resolveGrafanaTarget(input: {
+  environment?: string;
+  config?: Pick<ChantConfig, "grafana">;
+  env?: Record<string, string | undefined>;
+}): GrafanaTarget | UnresolvedTarget {
+  const env = input.env ?? process.env;
+  const profile = input.environment !== undefined ? input.config?.grafana?.profiles?.[input.environment] : undefined;
+  if (profile) {
+    const source = `grafana.profiles.${input.environment}`;
+    let auth: GrafanaAuth | undefined;
+    if (profile.token) {
+      const token = env[profile.token.env];
+      if (!token) return { reason: "no-credentials", detail: `${source}.token names ${profile.token.env}, which is not set` };
+      auth = { token };
+    } else if (profile.basicAuth) {
+      const user = env[profile.basicAuth.user.env];
+      const password = env[profile.basicAuth.password.env];
+      if (!user || !password) {
+        const missing = [!user ? profile.basicAuth.user.env : undefined, !password ? profile.basicAuth.password.env : undefined].filter(Boolean).join(" and ");
+        return { reason: "no-credentials", detail: `${source}.basicAuth names ${missing}, which ${missing.includes(" and ") ? "are" : "is"} not set` };
+      }
+      auth = { user, password };
+    }
+    return {
+      url: profile.url.replace(/\/+$/, ""),
+      ...(auth ? { auth } : {}),
+      ...(profile.orgId !== undefined ? { orgId: profile.orgId } : {}),
+      ...(profile.namespace ? { namespace: profile.namespace } : {}),
+      source,
+    };
+  }
+
+  const url = env.GRAFANA_URL;
+  if (!url) {
+    const where = input.environment !== undefined ? `grafana.profiles.${input.environment} is not declared and ` : "";
+    return { reason: "no-binding", detail: `${where}GRAFANA_URL is not set, so there is no Grafana to read` };
+  }
+  let auth: GrafanaAuth | undefined;
+  if (env.GRAFANA_TOKEN) auth = { token: env.GRAFANA_TOKEN };
+  else if (env.GRAFANA_USER && env.GRAFANA_PASSWORD) auth = { user: env.GRAFANA_USER, password: env.GRAFANA_PASSWORD };
+  const orgId = env.GRAFANA_ORG_ID ? Number(env.GRAFANA_ORG_ID) : undefined;
+  return {
+    url: url.replace(/\/+$/, ""),
+    ...(auth ? { auth } : {}),
+    ...(orgId !== undefined && Number.isInteger(orgId) && orgId > 0 ? { orgId } : {}),
+    source: "env GRAFANA_URL",
+  };
+}

package/src/contact-point-secrets.ts

@@ -0,0 +1,63 @@
+/**
+ * The contact point settings Grafana stores encrypted, per integration: the
+ * options marked `secure` by `GET /api/alert-notifiers?version=2` on
+ * `grafana/grafana:13.2.2` (commit 1bea008f; the same list on 12.4.11).
+ * Nested settings are dotted paths (`tlsConfig.clientKey`).
+ *
+ * GRAF002 flags a literal at one of these paths, and the importer replaces
+ * the `[REDACTED]` that an export without secrets writes there.
+ */
+export const CONTACT_POINT_SECRET_SETTINGS: Readonly<Record<string, readonly string[]>> = Object.freeze({
+  dingding: ["url"],
+  discord: ["url"],
+  email: [],
+  googlechat: ["url"],
+  jira: ["user", "password", "api_token"],
+  kafka: ["password"],
+  line: ["token"],
+  mqtt: ["password", "tlsConfig.caCertificate", "tlsConfig.clientCertificate", "tlsConfig.clientKey"],
+  oncall: ["password", "authorization_credentials"],
+  opsgenie: ["apiKey"],
+  pagerduty: ["integrationKey"],
+  "prometheus-alertmanager": ["basicAuthPassword"],
+  pushover: ["apiToken", "userKey"],
+  sensugo: ["apikey"],
+  slack: ["token", "url"],
+  sns: ["sigv4.access_key", "sigv4.secret_key"],
+  teams: [],
+  telegram: ["bottoken"],
+  threema: ["api_secret"],
+  victorops: ["url"],
+  webex: ["bot_token"],
+  webhook: [
+    "password",
+    "authorization_credentials",
+    "tlsConfig.caCertificate",
+    "tlsConfig.clientCertificate",
+    "tlsConfig.clientKey",
+    "hmacConfig.secret",
+    "http_config.oauth2.client_secret",
+    "http_config.oauth2.tls_config.caCertificate",
+    "http_config.oauth2.tls_config.clientCertificate",
+    "http_config.oauth2.tls_config.clientKey",
+  ],
+  wechat: ["api_secret", "http_config.basic_auth.password", "http_config.authorization.credentials", "http_config.oauth2.client_secret"],
+  wecom: ["url", "secret"],
+});
+
+/** How Grafana provisioning reads a value from outside the file: `$VAR`, `${VAR}`, `$__env{…}`, `$__file{…}`, `$__vault{…}`. */
+export const EXPANDED_VALUE = /\$(\{[A-Za-z_][A-Za-z0-9_]*\}|[A-Za-z_][A-Za-z0-9_]*|__(env|file|vault)\{[^}]+\})/;
+
+/** What an export without secrets writes in place of each one. */
+export const REDACTED = "[REDACTED]";
+
+/** The secret settings of one receiver present in `settings`, with their values: `[path, value]`. */
+export function secretSettings(type: string, settings: Record<string, unknown>): Array<[string, unknown]> {
+  const out: Array<[string, unknown]> = [];
+  for (const path of CONTACT_POINT_SECRET_SETTINGS[type] ?? []) {
+    let node: unknown = settings;
+    for (const seg of path.split(".")) node = node && typeof node === "object" ? (node as Record<string, unknown>)[seg] : undefined;
+    if (node !== undefined) out.push([path, node]);
+  }
+  return out;
+}

package/src/dashboard.ts

@@ -12,6 +12,8 @@ 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";
+import { isFolderEntity, type FolderEntity } from "./folder";
+import type { AnnotationInput } from "./annotations";
 
 /** A dashboard link: `title` and `type` required, the rest defaulted as Grafana's editor would. */
 export type DashboardLinkInput = Partial<DashboardLink> & Pick<DashboardLink, "title" | "type">;
@@ -40,6 +42,13 @@ export interface DashboardProps {
   graphTooltip?: "default" | "sharedCrosshair" | "sharedTooltip";
   /** Whether users may edit it in the UI. Defaults to true, as in Grafana. */
   editable?: boolean;
+  /**
+   * The dashboard schema version the JSON is written at. Leave it out for
+   * the pinned one (`DASHBOARD_SCHEMA_VERSION`). `chant import` sets it for
+   * a dashboard saved by an older Grafana, so Grafana still runs its
+   * migrations when it loads the rebuilt JSON.
+   */
+  schemaVersion?: number;
   // 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. */
@@ -47,23 +56,50 @@ export interface DashboardProps {
   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.
+   * Annotation queries: events drawn on the dashboard's time series panels
+   * (deploys, incidents), each from a datasource. Grafana adds its own
+   * "Annotations & Alerts" query to every dashboard that has none with
+   * `builtIn: 1`, so leave that one out unless you change it.
    */
-  folder?: string;
+  annotations?: AnnotationInput[];
+  /**
+   * The Grafana folder: a path (`"Platform/Kubernetes"`) or a `Folder`,
+   * which pins the folder's uid. Written as a subdirectory of `dashboards/`,
+   * which the provider maps to folders (`foldersFromFilesStructure`); a path
+   * nests one directory in another, which Grafana 13.1 and later make a
+   * Kubernetes folder inside Platform, and earlier versions use only the
+   * last level (GRAF109 warns). The API applier creates each level with its
+   * uid. Leave it out for the General folder.
+   */
+  folder?: string | FolderEntity;
 }
 
+/** A dashboard's props as the entity holds them: `folder` is always the path, and a `Folder` given for it is `folderEntity`. */
+export type DashboardEntityProps = Omit<DashboardProps, "folder"> & { folder?: string };
+
 export interface DashboardEntity extends Declarable {
-  readonly props: DashboardProps;
+  readonly props: DashboardEntityProps;
+  /** The `Folder` the dashboard was given, when it was given one rather than a path. */
+  readonly folderEntity?: FolderEntity;
 }
 
 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. */
+/**
+ * A Grafana dashboard. A `Folder` given as its `folder` is held as the
+ * folder's path, so everything that reads the dashboard's props (the build,
+ * the checks, observation's diff) sees one form; the `Folder` itself, for its
+ * uid, is `folderEntity`.
+ */
 export const Dashboard = function (this: object, props: DashboardProps) {
+  const folder = props.folder;
+  if (isFolderEntity(folder)) {
+    DashboardBase.call(this, { ...props, folder: folder.path } as unknown as Record<string, unknown>);
+    Object.defineProperty(this, "folderEntity", { value: folder, enumerable: false });
+    return;
+  }
   DashboardBase.call(this, props as unknown as Record<string, unknown>);
 } as unknown as new (props: DashboardProps) => DashboardEntity;
 Object.defineProperty(Dashboard, "name", { value: "Dashboard" });
@@ -84,8 +120,15 @@ export interface DashboardProviderProps {
   /** Provider name, unique in the provisioning file. */
   name: string;
   orgId?: number;
-  /** Folder for dashboards not in a subdirectory. */
-  folder?: string;
+  /**
+   * Put every dashboard this provider loads in this folder: a title, or a
+   * root-level `Folder`, whose title and uid are written as `folder` and
+   * `folderUid` (Grafana creates a provider's folder at the root, so a
+   * nested `Folder` is refused). Setting it (or `folderUid`) turns
+   * `foldersFromFilesStructure` off by default, so each dashboard's own
+   * `folder` is ignored (GRAF109 warns).
+   */
+  folder?: string | FolderEntity;
   folderUid?: string;
   /** Where the `dashboards/` output is mounted in the Grafana container. Defaults to `/var/lib/grafana/dashboards`. */
   path?: string;
@@ -96,8 +139,11 @@ export interface DashboardProviderProps {
   updateIntervalSeconds?: number;
 }
 
+/** A provider's props as the entity holds them: a `Folder` given for `folder` is written out as `folder` and `folderUid`. */
+export type DashboardProviderEntityProps = Omit<DashboardProviderProps, "folder"> & { folder?: string };
+
 export interface DashboardProviderEntity extends Declarable {
-  readonly props: DashboardProviderProps;
+  readonly props: DashboardProviderEntityProps;
 }
 
 export const DASHBOARD_PROVIDER_TYPE = "Grafana::DashboardProvider";
@@ -109,6 +155,19 @@ const ProviderBase = createResource(DASHBOARD_PROVIDER_TYPE, "grafana", {}) as u
 
 /** 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) {
+  const folder = props.folder;
+  if (isFolderEntity(folder)) {
+    if (folder.props.parent) {
+      throw new Error(
+        `grafana: DashboardProvider "${props.name}" puts its dashboards in the Folder "${folder.path}", which is nested; Grafana creates a provider's folder at the root. Give it a root-level Folder, or leave folder out and set each dashboard's folder`,
+      );
+    }
+    if (props.folderUid !== undefined && props.folderUid !== folder.uid) {
+      throw new Error(`grafana: DashboardProvider "${props.name}" has folderUid "${props.folderUid}", but its Folder's uid is "${folder.uid}"`);
+    }
+    ProviderBase.call(this, { ...props, folder: folder.props.title, folderUid: folder.uid } as unknown as Record<string, unknown>);
+    return;
+  }
   ProviderBase.call(this, props as unknown as Record<string, unknown>);
 } as unknown as new (props: DashboardProviderProps) => DashboardProviderEntity;
 Object.defineProperty(DashboardProvider, "name", { value: "DashboardProvider" });

package/src/datasource-refs.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "vitest";
+import { datasourceUses, knownDatasources, resolveDatasourceRef } from "./datasource-refs";
+
+const known = knownDatasources([{ name: "Prometheus", type: "prometheus", uid: "prom" }], [{ type: "loki", uid: "logs", name: "Logs" }]);
+
+function dashboard(panels: unknown[], variables: unknown[] = []) {
+  return { uid: "d", title: "D", panels, templating: { list: variables } };
+}
+
+describe("resolveDatasourceRef", () => {
+  const vars = new Map([["ds", { type: "datasource", name: "ds", query: "prometheus" }]]);
+
+  test("resolves provisioned and external datasources to their plugin type", () => {
+    expect(resolveDatasourceRef({ uid: "prom" }, vars, known)).toMatchObject({ kind: "declared", type: "prometheus", datasource: { external: false } });
+    expect(resolveDatasourceRef({ type: "loki", uid: "logs" }, vars, known)).toMatchObject({ kind: "declared", type: "loki", datasource: { external: true, name: "Logs" } });
+  });
+
+  test("resolves a datasource variable to its plugin type", () => {
+    expect(resolveDatasourceRef({ uid: "${ds}" }, vars, known)).toEqual({ kind: "variable", variable: "ds", declared: true, type: "prometheus" });
+    expect(resolveDatasourceRef({ type: "tempo", uid: "$other" }, vars, known)).toEqual({ kind: "variable", variable: "other", declared: false, type: "tempo" });
+  });
+
+  test("separates Grafana's pseudo-datasources, unknown uids and no ref", () => {
+    expect(resolveDatasourceRef({ type: "datasource", uid: "-- Mixed --" }, vars, known).kind).toBe("builtin");
+    expect(resolveDatasourceRef({ type: "prometheus", uid: "gone" }, vars, known)).toEqual({ kind: "undeclared", uid: "gone", type: "prometheus" });
+    expect(resolveDatasourceRef(undefined, vars, known)).toEqual({ kind: "default" });
+    expect(resolveDatasourceRef({ type: "prometheus" }, vars, known)).toEqual({ kind: "default", type: "prometheus" });
+  });
+});
+
+describe("datasourceUses", () => {
+  test("a query without its own ref goes where its panel's goes", () => {
+    const d = dashboard([{ type: "stat", id: 1, title: "p", datasource: { uid: "prom" }, targets: [{ refId: "A", expr: "up" }, { refId: "B", datasource: { uid: "logs" } }] }]);
+    const queries = datasourceUses(d, known).filter((u) => u.kind === "query");
+    expect(queries.map((u) => [u.target?.refId, u.ref === undefined, u.resolved.type])).toEqual([
+      ["A", true, "prometheus"],
+      ["B", false, "loki"],
+    ]);
+  });
+
+  test("a query under a -- Mixed -- panel with no ref goes to the default datasource", () => {
+    const d = dashboard([{ type: "table", id: 1, datasource: { type: "datasource", uid: "-- Mixed --" }, targets: [{ refId: "A" }] }]);
+    expect(datasourceUses(d, known).find((u) => u.kind === "query")?.resolved).toEqual({ kind: "default" });
+  });
+
+  test("covers panels in collapsed rows and query variables, and skips rows", () => {
+    const d = dashboard(
+      [{ type: "row", id: 1, collapsed: true, datasource: { uid: "prom" }, panels: [{ type: "stat", id: 2, datasource: { uid: "logs" }, targets: [] }] }],
+      [{ type: "query", name: "job", datasource: { uid: "prom" }, query: "label_values(job)" }],
+    );
+    expect(datasourceUses(d, known).map((u) => [u.kind, u.where, u.resolved.type])).toEqual([
+      ["panel", 'panel (untitled) (id 2)', "loki"],
+      ["variable", 'variable "job"', "prometheus"],
+    ]);
+  });
+});