@intentius/chant-lexicon-grafana 0.124.31 → 0.124.33

package/dist/actions/grafana.js

@@ -0,0 +1,36 @@
+/**
+ * The Grafana RBAC actions chant's live paths call, for a custom role on the
+ * service account whose token a `grafana.profiles.<env>` entry names. The
+ * basic Editor role covers all of them; these are for a narrower role.
+ *
+ * - `Observe`: `chant lifecycle diff --live` and `chant import --from`
+ *   (#2946), which read dashboards, folders and datasources.
+ * - `Apply`: the API applier (#2948), which also reads what it writes to
+ *   compare, and writes folders, library panels and dashboards.
+ * - `Prune`: the applier with `prune`, which deletes dashboards and folders
+ *   (never library panels or datasources).
+ *
+ * Grant them on `folders:*` and `dashboards:*` scopes, or on the folders
+ * chant writes to.
+ */
+export const GrafanaActions = {
+    Observe: ["dashboards:read", "folders:read", "datasources:read"],
+    Apply: [
+        "dashboards:read",
+        "dashboards:create",
+        "dashboards:write",
+        "folders:read",
+        "folders:create",
+        "folders:write",
+        "library.panels:read",
+        "library.panels:create",
+        "library.panels:write",
+    ],
+    Prune: ["dashboards:read", "dashboards:delete", "folders:read", "folders:delete"],
+};
+// A Map-backed lookup, so evaluable code avoids computed element access (EVL003).
+const GRAFANA_ACTIONS = new Map(Object.entries(GrafanaActions));
+/** The actions for one or more access levels, deduplicated, in first-seen order. */
+export function grafanaActionsFor(...levels) {
+    return [...new Set(levels.flatMap((l) => GRAFANA_ACTIONS.get(l) ?? []))];
+}

package/dist/actions/index.js

@@ -0,0 +1 @@
+export { GrafanaActions, grafanaActionsFor } from "./grafana.js";

package/dist/alerting-build.js

@@ -0,0 +1,262 @@
+/**
+ * From alerting entities to Grafana's alerting provisioning file,
+ * `provisioning/alerting/chant.yaml`.
+ *
+ * The file is what Grafana's file provisioner reads
+ * (`pkg/services/provisioning/alerting`, the same at v12.4.11 and v13.2.2)
+ * and what `GET /api/v1/provisioning/*\/export` writes: `apiVersion: 1`
+ * and the lists `groups`, `contactPoints`, `policies`, `muteTimes` and
+ * `templates`. Mount `provisioning/` at `/etc/grafana/provisioning`, as for
+ * datasources and dashboards.
+ *
+ * Plain functions, so a test or another lexicon can render the same file
+ * with `alertingYaml()` without a build.
+ */
+import { dump } from "js-yaml";
+import { durationMs, isValidDuration } from "@intentius/chant-lexicon-prometheus/duration";
+import { EXPRESSION_DATASOURCE_UID, isAlertQueryEntity, isAlertRuleGroupEntity, isContactPointEntity, isExpressionEntity, isMuteTimingEntity, isNotificationPolicyEntity, isNotificationTemplateEntity, } from "./alerting.js";
+import { isDashboardEntity } from "./dashboard.js";
+import { isQueryEntity } from "./query.js";
+import { isDatasourceVariable } from "./variables.js";
+import { compact, slugUid } from "./util.js";
+// build.ts imports this module too; only functions cross the cycle, and only at call time.
+import { datasourceRef, targetJson } from "./build.js";
+/** Where the alerting provisioning file goes, relative to the build output directory. */
+export const ALERTING_FILE = "provisioning/alerting/chant.yaml";
+/** The time range a query reads when neither it nor its rule sets one: the last 10 minutes, Grafana's editor default. */
+export const DEFAULT_RELATIVE_TIME_RANGE = { from: 600, to: 0 };
+/** A rule group's evaluation interval when it sets none. */
+export const DEFAULT_GROUP_INTERVAL = "1m";
+/** The keys an alerting provisioning file can hold, from `AlertingFileV1`. */
+export const ALERTING_FILE_KEYS = [
+    "apiVersion",
+    "groups",
+    "deleteRules",
+    "contactPoints",
+    "deleteContactPoints",
+    "policies",
+    "resetPolicies",
+    "muteTimes",
+    "deleteMuteTimes",
+    "templates",
+    "deleteTemplates",
+];
+// ── Durations ───────────────────────────────────────────────────
+/** A duration as whole seconds: a number is taken as seconds, a string as a Prometheus duration. */
+export function durationSeconds(value, what) {
+    if (typeof value === "number") {
+        if (!Number.isInteger(value) || value < 0)
+            throw new Error(`grafana: ${what} must be a whole number of seconds, got ${value}`);
+        return value;
+    }
+    if (!isValidDuration(value))
+        throw new Error(`grafana: ${what} "${value}" is not a duration like 10m or 1h`);
+    return Math.floor(durationMs(value) / 1000);
+}
+function timeRange(range, what) {
+    return { from: durationSeconds(range.from, `${what} from`), to: durationSeconds(range.to ?? 0, `${what} to`) };
+}
+// ── References ──────────────────────────────────────────────────
+function receiverName(receiver) {
+    return typeof receiver === "string" ? receiver : receiver.props.name;
+}
+function timingNames(list) {
+    return list?.map((t) => (typeof t === "string" ? t : t.props.name));
+}
+// ── Rules ───────────────────────────────────────────────────────
+const REF_IDS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+function refIdAt(i) {
+    return i < REF_IDS.length ? REF_IDS[i] : `${REF_IDS[Math.floor(i / REF_IDS.length) - 1]}${REF_IDS[i % REF_IDS.length]}`;
+}
+/** The uid a query's datasource resolves to, and its type when known. */
+function datasourceOf(input, where) {
+    if (input === undefined || input === null)
+        throw new Error(`grafana: ${where} has no datasource; an alert query must name one`);
+    if (typeof input === "string")
+        return { uid: input };
+    if (isDatasourceVariable(input)) {
+        throw new Error(`grafana: ${where} uses a DatasourceVariable; alert rules are evaluated without dashboard variables, so name the datasource itself`);
+    }
+    const ref = datasourceRef(input);
+    return { uid: ref.uid, ...(ref.type ? { type: ref.type } : {}) };
+}
+function typedQueryModel(query, refId, where) {
+    const ds = datasourceOf(query.props.datasource, where);
+    const model = targetJson(query, 0, ds.type ? { type: ds.type, uid: ds.uid } : undefined);
+    return { uid: ds.uid, model: { ...model, refId } };
+}
+/** One entry of `data`, as the file holds it. */
+export function alertQueryJson(item, index, ruleRange, rule) {
+    const where = `alert rule "${rule}" data[${index}]`;
+    const fallbackRange = ruleRange ? timeRange(ruleRange, `${where} relativeTimeRange`) : { ...DEFAULT_RELATIVE_TIME_RANGE };
+    if (isExpressionEntity(item)) {
+        const { refId: ownRefId, relativeTimeRange, ...rest } = item.props;
+        const refId = ownRefId ?? refIdAt(index);
+        return compact({
+            refId,
+            relativeTimeRange: relativeTimeRange ? timeRange(relativeTimeRange, `${where} relativeTimeRange`) : undefined,
+            datasourceUid: EXPRESSION_DATASOURCE_UID,
+            model: { datasource: { type: EXPRESSION_DATASOURCE_UID, uid: EXPRESSION_DATASOURCE_UID }, refId, type: item.expressionKind, ...rest },
+        });
+    }
+    if (isAlertQueryEntity(item)) {
+        const p = item.props;
+        const refId = p.refId ?? refIdAt(index);
+        const range = p.relativeTimeRange ? timeRange(p.relativeTimeRange, `${where} relativeTimeRange`) : fallbackRange;
+        let uid;
+        let model;
+        if (p.query) {
+            const typed = typedQueryModel(p.query, refId, where);
+            const own = p.datasource !== undefined ? datasourceOf(p.datasource, where) : undefined;
+            uid = own?.uid ?? typed.uid;
+            model = { ...typed.model, ...(p.model ?? {}) };
+        }
+        else {
+            uid = datasourceOf(p.datasource, where).uid;
+            model = p.model ?? {};
+        }
+        return compact({ refId, queryType: p.queryType, relativeTimeRange: range, datasourceUid: uid, model });
+    }
+    if (isQueryEntity(item)) {
+        const refId = item.props.refId ?? refIdAt(index);
+        const typed = typedQueryModel(item, refId, where);
+        return { refId, relativeTimeRange: fallbackRange, datasourceUid: typed.uid, model: typed.model };
+    }
+    throw new Error(`grafana: ${where} must be a query (PromQuery, AlertQuery, ...) or an expression (ReduceExpression, ...)`);
+}
+/** One rule as the file holds it. */
+export function alertRuleJson(rule) {
+    const p = rule.props;
+    const data = (p.data ?? []).map((d, i) => alertQueryJson(d, i, p.relativeTimeRange, p.title));
+    const condition = p.condition ?? (p.record ? undefined : data[data.length - 1]?.refId);
+    const dashboardUid = p.dashboardUid === undefined ? undefined : isDashboardEntity(p.dashboardUid) ? (p.dashboardUid.props.uid ?? slugUid(p.dashboardUid.props.title)) : p.dashboardUid;
+    const ns = p.notification_settings;
+    return compact({
+        uid: p.uid ?? slugUid(p.title),
+        title: p.title,
+        condition,
+        data,
+        dashboardUid,
+        panelId: p.panelId,
+        noDataState: p.noDataState,
+        execErrState: p.execErrState,
+        for: p.for,
+        keepFiringFor: p.keepFiringFor,
+        missing_series_evals_to_resolve: p.missing_series_evals_to_resolve,
+        annotations: p.annotations,
+        labels: p.labels,
+        isPaused: p.isPaused,
+        notification_settings: ns
+            ? {
+                receiver: receiverName(ns.receiver),
+                group_by: ns.group_by,
+                group_wait: ns.group_wait,
+                group_interval: ns.group_interval,
+                repeat_interval: ns.repeat_interval,
+                mute_time_intervals: timingNames(ns.mute_time_intervals),
+                active_time_intervals: timingNames(ns.active_time_intervals),
+            }
+            : undefined,
+        record: p.record ? { ...p.record } : undefined,
+    });
+}
+/** One rule group as the file holds it. */
+export function ruleGroupJson(group) {
+    const p = group.props;
+    return compact({
+        orgId: p.orgId,
+        name: p.name,
+        folder: p.folder,
+        interval: p.interval ?? DEFAULT_GROUP_INTERVAL,
+        rules: (p.rules ?? []).map(alertRuleJson),
+    });
+}
+// ── Notifications ───────────────────────────────────────────────
+/** One contact point as the file holds it. A receiver without a uid gets one from the name and the integration type. */
+export function contactPointJson(cp) {
+    const p = cp.props;
+    const taken = new Set();
+    const receivers = (p.receivers ?? []).map((r) => {
+        let uid = r.uid ?? slugUid(`${p.name} ${r.type}`);
+        if (r.uid === undefined)
+            for (let n = 2; taken.has(uid); n++)
+                uid = slugUid(`${p.name} ${r.type} ${n}`);
+        taken.add(uid);
+        return compact({ uid, type: r.type, settings: (r.settings ?? {}), disableResolveMessage: r.disableResolveMessage });
+    });
+    return compact({ orgId: p.orgId, name: p.name, receivers });
+}
+function routeJson(route) {
+    return compact({
+        receiver: route.receiver === undefined ? undefined : receiverName(route.receiver),
+        group_by: route.group_by,
+        object_matchers: route.object_matchers?.map((m) => [...m]),
+        matchers: route.matchers,
+        match: route.match,
+        match_re: route.match_re,
+        continue: route.continue,
+        group_wait: route.group_wait,
+        group_interval: route.group_interval,
+        repeat_interval: route.repeat_interval,
+        mute_time_intervals: timingNames(route.mute_time_intervals),
+        active_time_intervals: timingNames(route.active_time_intervals),
+        routes: route.routes?.map(routeJson),
+    });
+}
+/** One organisation's policy tree as the file holds it. */
+export function notificationPolicyJson(policy) {
+    const p = policy.props;
+    return compact({
+        orgId: p.orgId,
+        receiver: receiverName(p.receiver),
+        group_by: p.group_by,
+        group_wait: p.group_wait,
+        group_interval: p.group_interval,
+        repeat_interval: p.repeat_interval,
+        mute_time_intervals: timingNames(p.mute_time_intervals),
+        active_time_intervals: timingNames(p.active_time_intervals),
+        routes: p.routes?.map(routeJson),
+    });
+}
+export function muteTimingJson(t) {
+    return compact({ orgId: t.props.orgId, name: t.props.name, time_intervals: (t.props.time_intervals ?? []) });
+}
+export function notificationTemplateJson(t) {
+    return compact({ orgId: t.props.orgId, name: t.props.name, template: t.props.template });
+}
+// ── The file ────────────────────────────────────────────────────
+/** The alerting provisioning file as YAML text. */
+export function alertingYaml(file) {
+    return `# Grafana alerting provisioning, generated by chant.\n${dump(file, { lineWidth: -1, noRefs: true, quotingType: '"' })}`;
+}
+/** The alerting provisioning file for the alerting entities among these, or undefined when there are none. */
+export function buildAlerting(entities) {
+    const all = [...entities];
+    const byName = (a, b) => a.name.localeCompare(b.name);
+    const groups = all
+        .filter(isAlertRuleGroupEntity)
+        .map(ruleGroupJson)
+        .sort((a, b) => a.folder.localeCompare(b.folder) || a.name.localeCompare(b.name));
+    const contactPoints = all.filter(isContactPointEntity).map(contactPointJson).sort(byName);
+    const policies = all.filter(isNotificationPolicyEntity).map(notificationPolicyJson);
+    const muteTimes = all.filter(isMuteTimingEntity).map(muteTimingJson).sort(byName);
+    const templates = all.filter(isNotificationTemplateEntity).map(notificationTemplateJson).sort(byName);
+    if (groups.length + contactPoints.length + policies.length + muteTimes.length + templates.length === 0)
+        return undefined;
+    const file = compact({
+        apiVersion: 1,
+        groups: groups.length > 0 ? groups : undefined,
+        contactPoints: contactPoints.length > 0 ? contactPoints : undefined,
+        policies: policies.length > 0 ? policies : undefined,
+        muteTimes: muteTimes.length > 0 ? muteTimes : undefined,
+        templates: templates.length > 0 ? templates : undefined,
+    });
+    const index = {
+        ruleGroups: groups.map((g) => ({ name: g.name, folder: g.folder, rules: g.rules.length })),
+        contactPoints: contactPoints.map((c) => c.name),
+        policies: policies.length,
+        muteTimings: muteTimes.map((m) => m.name),
+        templates: templates.map((t) => t.name),
+    };
+    return { file, index };
+}

package/dist/alerting.js

@@ -0,0 +1,125 @@
+/**
+ * Grafana-managed alerting: rule groups, their rules, queries and
+ * server-side expressions, contact points, the notification policy tree,
+ * mute timings and notification templates.
+ *
+ * Everything here is written to Grafana's alerting file provisioning
+ * format, `provisioning/alerting/chant.yaml` (see `alerting-build.ts`). The
+ * shapes follow the file format as Grafana reads it
+ * (`pkg/services/provisioning/alerting/*_types.go`, identical at v12.4.11
+ * and v13.2.2), so a key here is the key in the file. Server-side
+ * expressions are typed from the vendored `expr` schema (see `src/pin.ts`).
+ *
+ * Resources: `AlertRuleGroup`, `ContactPoint`, `NotificationPolicy`,
+ * `MuteTiming`, `NotificationTemplate`. Property-kind (they live inside a
+ * rule group): `AlertRule`, `AlertQuery` and the expression classes.
+ */
+import { createProperty, createResource } from "@intentius/chant/runtime";
+/** The datasource uid Grafana gives server-side expressions. */
+export const EXPRESSION_DATASOURCE_UID = "__expr__";
+export const ALERT_QUERY_TYPE = "Grafana::AlertQuery";
+const AlertQueryBase = createProperty(ALERT_QUERY_TYPE, "grafana");
+/**
+ * One datasource query of an alert rule. A typed query (`PromQuery`) can go
+ * straight into a rule's `data`; `AlertQuery` is for a query model of any
+ * plugin, or to give a typed query its own time range or refId.
+ */
+export const AlertQuery = function (props) {
+    AlertQueryBase.call(this, props);
+};
+Object.defineProperty(AlertQuery, "name", { value: "AlertQuery" });
+export function isAlertQueryEntity(value) {
+    return typeof value === "object" && value !== null && value.entityType === ALERT_QUERY_TYPE && value.lexicon === "grafana";
+}
+export const EXPRESSION_TYPE_PREFIX = "Grafana::Expression::";
+function expressionClass(kind, className) {
+    const Base = createProperty(`${EXPRESSION_TYPE_PREFIX}${kind}`, "grafana");
+    const Cls = function (props) {
+        Base.call(this, props);
+        Object.defineProperty(this, "expressionKind", { value: kind, enumerable: false });
+    };
+    Object.defineProperty(Cls, "name", { value: className });
+    return Cls;
+}
+/** Reduce a series to one number per series: `expression` is a refId (`A` or `$A`). */
+export const ReduceExpression = expressionClass("reduce", "ReduceExpression");
+/** Arithmetic and logic over results by refId: `$A / $B`, `$A > 0.05 && $B > 0.05`. */
+export const MathExpression = expressionClass("math", "MathExpression");
+/** Compare a result with a threshold; an `unloadEvaluator` adds a recovery threshold. */
+export const ThresholdExpression = expressionClass("threshold", "ThresholdExpression");
+/** Resample a time series to a fixed `window`. */
+export const ResampleExpression = expressionClass("resample", "ResampleExpression");
+/** Grafana's legacy classic conditions: reducers, evaluators and and/or across queries. */
+export const ClassicConditionsExpression = expressionClass("classic_conditions", "ClassicConditionsExpression");
+/** A SQL query over the other results (Grafana's SQL expressions). */
+export const SqlExpression = expressionClass("sql", "SqlExpression");
+export function isExpressionEntity(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.lexicon === "grafana" &&
+        typeof value.entityType === "string" &&
+        value.entityType.startsWith(EXPRESSION_TYPE_PREFIX));
+}
+export const ALERT_RULE_TYPE = "Grafana::AlertRule";
+const AlertRuleBase = createProperty(ALERT_RULE_TYPE, "grafana");
+/** A Grafana-managed alert or recording rule, inside an `AlertRuleGroup`. */
+export const AlertRule = function (props) {
+    AlertRuleBase.call(this, props);
+};
+Object.defineProperty(AlertRule, "name", { value: "AlertRule" });
+export function isAlertRuleEntity(value) {
+    return typeof value === "object" && value !== null && value.entityType === ALERT_RULE_TYPE && value.lexicon === "grafana";
+}
+export const ALERT_RULE_GROUP_TYPE = "Grafana::AlertRuleGroup";
+const GroupBase = createResource(ALERT_RULE_GROUP_TYPE, "grafana", {});
+/** A group of Grafana-managed rules, evaluated together at one interval. */
+export const AlertRuleGroup = function (props) {
+    GroupBase.call(this, props);
+};
+Object.defineProperty(AlertRuleGroup, "name", { value: "AlertRuleGroup" });
+export function isAlertRuleGroupEntity(value) {
+    return typeof value === "object" && value !== null && value.entityType === ALERT_RULE_GROUP_TYPE && value.lexicon === "grafana";
+}
+export const CONTACT_POINT_TYPE = "Grafana::ContactPoint";
+const ContactPointBase = createResource(CONTACT_POINT_TYPE, "grafana", {});
+/** A contact point: one or more integrations alerts are sent to, under one name. */
+export const ContactPoint = function (props) {
+    ContactPointBase.call(this, props);
+};
+Object.defineProperty(ContactPoint, "name", { value: "ContactPoint" });
+export function isContactPointEntity(value) {
+    return typeof value === "object" && value !== null && value.entityType === CONTACT_POINT_TYPE && value.lexicon === "grafana";
+}
+export const MUTE_TIMING_TYPE = "Grafana::MuteTiming";
+const MuteTimingBase = createResource(MUTE_TIMING_TYPE, "grafana", {});
+/** A named time interval, for a policy's or rule's `mute_time_intervals` or `active_time_intervals`. */
+export const MuteTiming = function (props) {
+    MuteTimingBase.call(this, props);
+};
+Object.defineProperty(MuteTiming, "name", { value: "MuteTiming" });
+export function isMuteTimingEntity(value) {
+    return typeof value === "object" && value !== null && value.entityType === MUTE_TIMING_TYPE && value.lexicon === "grafana";
+}
+export const NOTIFICATION_TEMPLATE_TYPE = "Grafana::NotificationTemplate";
+const TemplateBase = createResource(NOTIFICATION_TEMPLATE_TYPE, "grafana", {});
+/** A notification template group, usable from contact point settings. */
+export const NotificationTemplate = function (props) {
+    TemplateBase.call(this, props);
+};
+Object.defineProperty(NotificationTemplate, "name", { value: "NotificationTemplate" });
+export function isNotificationTemplateEntity(value) {
+    return (typeof value === "object" && value !== null && value.entityType === NOTIFICATION_TEMPLATE_TYPE && value.lexicon === "grafana");
+}
+export const NOTIFICATION_POLICY_TYPE = "Grafana::NotificationPolicy";
+const PolicyBase = createResource(NOTIFICATION_POLICY_TYPE, "grafana", {});
+/**
+ * An organisation's notification policy tree, from its root. Provisioning it
+ * replaces the whole tree, so there is one per organisation.
+ */
+export const NotificationPolicy = function (props) {
+    PolicyBase.call(this, props);
+};
+Object.defineProperty(NotificationPolicy, "name", { value: "NotificationPolicy" });
+export function isNotificationPolicyEntity(value) {
+    return (typeof value === "object" && value !== null && value.entityType === NOTIFICATION_POLICY_TYPE && value.lexicon === "grafana");
+}

package/dist/annotations.js

@@ -0,0 +1,47 @@
+/**
+ * Dashboard annotations: the queries in a dashboard's `annotations.list`
+ * whose events Grafana draws on time series panels (deploy markers,
+ * incidents, alert state changes).
+ *
+ * An annotation is plain data on `Dashboard.annotations`, typed from
+ * Grafana's `AnnotationQuery`, except that its `datasource` takes the same
+ * values a panel's does (a `Datasource`, an `ExternalDatasource`, a
+ * `DatasourceVariable` or a `{ type, uid }` ref) and its `target` may be a
+ * query entity (`new PromQuery({ expr })`). What a datasource plugin keeps
+ * beside the common keys (Prometheus's legacy `expr`, `step`,
+ * `titleFormat`) is written as given.
+ *
+ * Grafana adds its built-in "Annotations & Alerts" query (`builtIn: 1`, the
+ * `-- Grafana --` datasource) to any dashboard without one, so a dashboard
+ * leaves it out unless it changes it (hides the toggle, turns it off).
+ */
+import { isQueryEntity } from "./query.js";
+import { compact } from "./util.js";
+/** The refId Grafana gives an annotation query's target. */
+export const ANNOTATION_REF_ID = "Anno";
+/**
+ * One annotation as the entry Grafana stores in `annotations.list`.
+ * `datasourceRef` resolves the datasource the same way a panel's is (it is
+ * build.ts's, passed in so this module needs nothing from the build).
+ */
+export function annotationJson(input, datasourceRef) {
+    const { name, datasource, enable, iconColor, target, ...rest } = input;
+    let ds = datasourceRef(datasource);
+    let targetJson;
+    if (isQueryEntity(target)) {
+        const { datasource: queryDs, ...model } = target.props;
+        ds ?? (ds = datasourceRef(queryDs));
+        targetJson = compact({ refId: ANNOTATION_REF_ID, ...(target.queryDefinition.defaults ?? {}), ...model });
+    }
+    else {
+        targetJson = target;
+    }
+    return compact({
+        ...(ds ? { datasource: ds } : {}),
+        enable: enable ?? true,
+        iconColor: iconColor ?? "red",
+        name,
+        ...rest,
+        ...(targetJson !== undefined ? { target: targetJson } : {}),
+    });
+}