@intentius/chant-lexicon-grafana 0.97.0 → 0.99.0

package/src/composites/red-dashboard.ts

@@ -6,6 +6,10 @@
  * 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.
+ *
+ * The queries count server and consumer spans only by default, the spans
+ * that handle a request or a message, so a service's outgoing calls and
+ * its internal spans don't inflate its rate or dilute its error ratio.
  */
 
 import { Composite, type CompositeInstance } from "@intentius/chant/composite";
@@ -21,6 +25,7 @@ import { slugUid } from "../util";
 import {
   dashboardProps,
   durationUnit,
+  errorRatio,
   legend,
   quantile,
   quantileName,
@@ -41,8 +46,36 @@ export interface RedDashboardProps extends DashboardOptions {
   exporter?: OTelComponent<"exporter", "prometheus", PrometheusExporterConfig> | PrometheusNaming;
   /** Duration quantiles, one panel each (default p50, p95 and p99). */
   quantiles?: number[];
+  /**
+   * The span kinds the queries count (default server and consumer spans).
+   * `[]` counts every kind. With the default, a connector that excludes
+   * `span.kind` gets no kind filter; naming kinds for such a connector is
+   * an error.
+   */
+  spanKinds?: SpanKind[];
 }
 
+/** The `span_kind` label values the spanmetrics connector writes. */
+export type SpanKind =
+  | "SPAN_KIND_UNSPECIFIED"
+  | "SPAN_KIND_INTERNAL"
+  | "SPAN_KIND_SERVER"
+  | "SPAN_KIND_CLIENT"
+  | "SPAN_KIND_PRODUCER"
+  | "SPAN_KIND_CONSUMER";
+
+const SPAN_KINDS: readonly SpanKind[] = [
+  "SPAN_KIND_UNSPECIFIED",
+  "SPAN_KIND_INTERNAL",
+  "SPAN_KIND_SERVER",
+  "SPAN_KIND_CLIENT",
+  "SPAN_KIND_PRODUCER",
+  "SPAN_KIND_CONSUMER",
+];
+
+/** The kinds `RedDashboard` counts unless told otherwise: the spans that serve a request or consume a message. */
+export const RED_DEFAULT_SPAN_KINDS: readonly SpanKind[] = Object.freeze(["SPAN_KIND_SERVER", "SPAN_KIND_CONSUMER"]);
+
 export type RedDashboardMembers = { dashboard: DashboardEntity };
 
 /** What `RedDashboard(...)` returns: its dashboard, as `dashboard`. */
@@ -50,28 +83,65 @@ export type RedDashboardInstance = CompositeInstance<RedDashboardMembers> & RedD
 
 const DEFAULT_QUANTILES = [0.5, 0.95, 0.99];
 
+function cap(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
 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") {
+/**
+ * The span-kind matcher for `kinds`, or none: none for `[]`, and none for
+ * the default kinds when the connector excludes `span.kind`.
+ */
+function spanKindMatchers(names: SpanMetricsNames, kinds: readonly SpanKind[] | undefined): Matcher[] {
+  const label = names.labels.spanKind;
+  if (kinds === undefined) return label ? [[label, "=~", RED_DEFAULT_SPAN_KINDS.join("|")]] : [];
+  for (const k of kinds) {
+    if (!SPAN_KINDS.includes(k)) throw new Error(`RedDashboard: unknown span kind ${JSON.stringify(k)}; use one of ${SPAN_KINDS.join(", ")}`);
+  }
+  if (kinds.length === 0) return [];
+  if (!label) throw new Error("RedDashboard: the connector excludes span.kind, so the metrics can't be filtered by spanKinds");
+  return [[label, "=~", [...new Set(kinds)].join("|")]];
+}
+
+/**
+ * The PromQL the RED dashboard runs, from the connector's names. Exposed for
+ * tests and for panels of your own. `spanKinds` defaults to server and
+ * consumer spans; `[]` counts every kind.
+ */
+export function redQueries(
+  names: SpanMetricsNames,
+  quantiles: number[] = DEFAULT_QUANTILES,
+  serviceFilter = "$service",
+  spanKinds?: readonly SpanKind[],
+) {
   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;
+  const kind = spanKindMatchers(names, spanKinds);
+  const scope: Matcher[] = [[svc, "=~", serviceFilter], ...kind];
+  const calls = selector(names.calls.prometheus, scope);
+  const errors = selector(names.calls.prometheus, [...scope, [status, "=", names.errorStatus]]);
+  const buckets = names.duration ? selector(`${names.duration.prometheus}_bucket`, scope) : undefined;
   return {
     rate: sumRate(calls, [svc]),
-    errorRatio: `${sumRate(errors, [svc])}\n/\n${sumRate(calls, [svc])}`,
+    errorRatio: errorRatio(errors, calls, [svc]),
     duration: buckets ? quantiles.map((q) => ({ quantile: q, expr: quantile(q, buckets, [svc]) })) : [],
-    services: `label_values(${names.calls.prometheus}, ${svc})`,
+    services: `label_values(${selector(names.calls.prometheus, kind)}, ${svc})`,
   };
 }
 
+/** "server and consumer spans", for panel descriptions. */
+function kindsText(names: SpanMetricsNames, kinds: readonly SpanKind[] | undefined): string {
+  const counted = kinds ?? (names.labels.spanKind ? RED_DEFAULT_SPAN_KINDS : []);
+  if (counted.length === 0) return "spans";
+  const words = [...new Set(counted)].map((k) => k.replace(/^SPAN_KIND_/, "").toLowerCase());
+  return `${words.length > 1 ? `${words.slice(0, -1).join(", ")} and ${words[words.length - 1]}` : words[0]} spans`;
+}
+
 /**
  * A RED dashboard (rate, errors, duration) per service, built from a
  * `spanmetrics` connector declaration.
@@ -94,7 +164,8 @@ export const RedDashboard = Composite<RedDashboardProps, RedDashboardMembers>((p
   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 q = redQueries(names, quantiles, "$service", props.spanKinds);
+  const counted = kindsText(names, props.spanKinds);
   const svc = names.labels.service!;
   const ds = props.datasource;
 
@@ -112,7 +183,7 @@ export const RedDashboard = Composite<RedDashboardProps, RedDashboardMembers>((p
 
   const rate = new TimeSeriesPanel({
     title: "Rate",
-    description: `Spans per second by service, from ${names.calls.prometheus}.`,
+    description: `${cap(counted)} per second by service, from ${names.calls.prometheus}.`,
     datasource: ds,
     gridPos: { w: 12, h: 8 },
     targets: [new PromQuery({ expr: q.rate, legendFormat: legend(svc) })],
@@ -120,7 +191,7 @@ export const RedDashboard = Composite<RedDashboardProps, RedDashboardMembers>((p
   });
   const errors = new TimeSeriesPanel({
     title: "Errors",
-    description: `Share of spans with ${names.labels.statusCode}="${names.errorStatus}", by service.`,
+    description: `Share of ${counted} with ${names.labels.statusCode}="${names.errorStatus}", by service.`,
     datasource: ds,
     gridPos: { w: 12, h: 8 },
     targets: [new PromQuery({ expr: q.errorRatio, legendFormat: legend(svc) })],
@@ -135,7 +206,7 @@ export const RedDashboard = Composite<RedDashboardProps, RedDashboardMembers>((p
       (d) =>
         new TimeSeriesPanel({
           title: `Duration ${quantileName(d.quantile)}`,
-          description: `${quantileName(d.quantile)} span duration by service, from ${names.duration!.prometheus}.`,
+          description: `${quantileName(d.quantile)} duration of ${counted} by service, from ${names.duration!.prometheus}.`,
           datasource: ds,
           gridPos: { w: width, h: 8 },
           targets: [new PromQuery({ expr: d.expr, legendFormat: legend(svc) })],

package/src/composites/shared.ts

@@ -39,6 +39,17 @@ export function sumRate(sel: string, by: string[], range = "$__rate_interval"):
   return `sum${by.length ? ` by (${by.join(", ")})` : ""} (rate(${sel}[${range}]))`;
 }
 
+/**
+ * `errors / all` as rates summed by `by`, with the numerator padded to zero:
+ * `(errors or all * 0) / all`. A group with calls but no error series gets
+ * 0 instead of dropping out of the result, so a panel shows 0% rather than
+ * "No data" for a service that has had no errors.
+ */
+export function errorRatio(errorSel: string, allSel: string, by: string[]): string {
+  const all = sumRate(allSel, by);
+  return `(\n${sumRate(errorSel, by)}\nor\n${all} * 0\n)\n/\n${all}`;
+}
+
 /** `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])})`;

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

@@ -40,6 +40,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. */
@@ -49,7 +56,10 @@ export interface DashboardProps {
   /**
    * 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.
+   * (`foldersFromFilesStructure`). `"Platform/Kubernetes"` nests one
+   * directory in another, which Grafana 13.1 and later make a Kubernetes
+   * folder inside Platform; earlier versions use only the last level
+   * (GRAF109 warns). Leave it out for the General folder.
    */
   folder?: string;
 }
@@ -84,7 +94,11 @@ export interface DashboardProviderProps {
   /** Provider name, unique in the provisioning file. */
   name: string;
   orgId?: number;
-  /** Folder for dashboards not in a subdirectory. */
+  /**
+   * Put every dashboard this provider loads in this folder. Setting it (or
+   * `folderUid`) turns `foldersFromFilesStructure` off by default, so each
+   * dashboard's own `folder` is ignored (GRAF109 warns).
+   */
   folder?: string;
   folderUid?: string;
   /** Where the `dashboards/` output is mounted in the Grafana container. Defaults to `/var/lib/grafana/dashboards`. */