@intentius/chant-lexicon-grafana 0.124.30 → 0.124.32

package/dist/composites/slo-dashboard.js

@@ -0,0 +1,153 @@
+/**
+ * `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 } from "@intentius/chant/composite";
+import { sloMetrics } from "@intentius/chant-lexicon-prometheus/composites/slo";
+import { Dashboard } from "../dashboard.js";
+import { Row, StatPanel, TimeSeriesPanel } from "../panels.js";
+import { PromQuery } from "../query.js";
+import { slugUid } from "../util.js";
+import { dashboardProps, num, requireDatasource, selector, thresholds } from "./shared.js";
+function isMetrics(x) {
+    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) {
+    const s = (series) => `${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((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/dist/config.js

@@ -0,0 +1,110 @@
+/**
+ * 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";
+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(),
+});
+function isUnresolved(v) {
+    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) {
+    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;
+        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;
+    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/dist/contact-point-check.js

@@ -0,0 +1,61 @@
+/**
+ * Checks one contact point receiver's `settings` against the options Grafana
+ * lists for its integration (`src/contact-point-settings.gen.ts`): a key the
+ * integration does not take, and a required option left out. An integration
+ * the table does not know is not checked.
+ */
+import { CONTACT_POINT_NOTIFIERS } from "./contact-point-settings.gen.js";
+function distance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let prev = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const tmp = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+            prev = tmp;
+        }
+    }
+    return row[b.length];
+}
+function closest(key, known) {
+    const lower = key.toLowerCase();
+    const exact = known.find((k) => k.toLowerCase() === lower);
+    if (exact)
+        return exact;
+    const best = known.map((k) => [k, distance(lower, k.toLowerCase())]).sort((x, y) => x[1] - y[1])[0];
+    return best && best[1] <= Math.max(2, Math.floor(key.length / 3)) ? best[0] : undefined;
+}
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+function walk(options, value, prefix, out) {
+    const known = options.map((o) => o.key);
+    for (const key of Object.keys(value)) {
+        if (known.includes(key))
+            continue;
+        const near = closest(key, known);
+        out.push({
+            severity: "warning",
+            path: `${prefix}${key}`,
+            message: `${prefix}${key} is not a setting of this integration${near ? `; did you mean ${prefix}${near}?` : ""}`,
+        });
+    }
+    for (const o of options) {
+        const v = value[o.key];
+        if (o.required && (v === undefined || v === null || v === "")) {
+            out.push({ severity: "error", path: `${prefix}${o.key}`, message: `${prefix}${o.key} is required` });
+        }
+        if (o.options && isObject(v))
+            walk(o.options, v, `${prefix}${o.key}.`, out);
+        if (o.options && o.kind === "objects" && Array.isArray(v)) {
+            v.forEach((item, i) => isObject(item) && walk(o.options, item, `${prefix}${o.key}[${i}].`, out));
+        }
+    }
+}
+export function checkContactPointSettings(type, settings) {
+    const schema = CONTACT_POINT_NOTIFIERS[type];
+    if (!schema)
+        return [];
+    const out = [];
+    walk(schema.options, settings, "", out);
+    return out;
+}

package/dist/contact-point-secrets.js

@@ -0,0 +1,32 @@
+import { CONTACT_POINT_NOTIFIERS } from "./contact-point-settings.gen.js";
+/** The dotted paths of the options marked `secure`, through nested objects (`tlsConfig.clientKey`). */
+function securePaths(options, prefix = "") {
+    return options.flatMap((o) => [...(o.secure ? [`${prefix}${o.key}`] : []), ...(o.options ? securePaths(o.options, `${prefix}${o.key}.`) : [])]);
+}
+/**
+ * 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` (the same list on 12.4.11), read from the table
+ * `just fetch-notifiers` writes. 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 = Object.freeze(Object.fromEntries(Object.entries(CONTACT_POINT_NOTIFIERS).map(([type, schema]) => [type, securePaths(schema.options)])));
+/** 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, settings) {
+    const out = [];
+    for (const path of CONTACT_POINT_SECRET_SETTINGS[type] ?? []) {
+        let node = settings;
+        for (const seg of path.split("."))
+            node = node && typeof node === "object" ? node[seg] : undefined;
+        if (node !== undefined)
+            out.push([path, node]);
+    }
+    return out;
+}