@intentius/chant-lexicon-prometheus 0.124.31 → 0.124.33

package/dist/composites/slo.js

@@ -0,0 +1,353 @@
+/**
+ * `Slo`: a service level objective that builds to Prometheus rules.
+ *
+ * One declaration expands to one `RuleGroup`, `slo-<name>`, holding:
+ *
+ * - recording rules: the SLI's error ratio over every window the alerts read
+ *   (`slo:sli_error:ratio_rate<window>`), the error ratio over the whole SLO
+ *   window, the objective (`slo:objective:ratio`) and the share of the error
+ *   budget left (`slo:error_budget:remaining`). Every series carries an
+ *   `slo` label with the SLO's name.
+ * - multiwindow, multi-burn-rate alerts from the Google SRE Workbook
+ *   ("Alerting on SLOs", alert 6). Each alert pairs a long window with a
+ *   short one and fires while both burn the error budget faster than the
+ *   pair's factor: the long window keeps a short spike from paging, the
+ *   short window stops the alert soon after the burn does.
+ *
+ * An SLI that sees no events in a window (a sparse one: a job that runs a few
+ * times a day) records no ratio for that window, where good/total would be
+ * 0/0 and record NaN. The SLO window's ratio is an average of the shortest
+ * recorded ratio, and one NaN in a range keeps `avg_over_time` NaN for the
+ * whole window, so the idle windows are left out and the average covers only
+ * the windows that had events. The SLI expressions are the caller's: `rate()`
+ * over a counter that first appears inside the range sees one sample and
+ * counts nothing, so a sparse SLI should count events as an increase that
+ * includes a series' first sample (`eventCount`, see the SLOs page).
+ *
+ * Both kinds share a group because Prometheus evaluates a group's rules in
+ * order: the alerts read the ratios recorded in the same evaluation. In
+ * separate groups they would read the previous evaluation's, and with an
+ * evaluation interval of 5m (the lookback) not at all.
+ *
+ * The Workbook's factors (14.4, 6, 3 and 1) assume a 30-day SLO window: each
+ * is the share of the budget a pair may burn over its long window, times the
+ * SLO window, over the long window (2% of the budget in 1h is
+ * 0.02 * 720h / 1h = 14.4). For any other window the lexicon keeps the
+ * windows and budget shares and recomputes the factor the same way, so a
+ * 28-day SLO pages at 0.02 * 672h / 1h = 13.44.
+ *
+ * `sloMetrics()` returns the recorded series names, the objective, the
+ * window and the burn-rate thresholds, so a dashboard or another rule reads
+ * them from the declaration instead of repeating them.
+ */
+import { Composite } from "@intentius/chant/composite";
+import { RuleGroup } from "../rules.js";
+import { durationMs, formatDuration, isValidDuration } from "../duration.js";
+import { checkPromql } from "../promql.js";
+/** The placeholder an SLI expression writes where its range goes, e.g. `[{{window}}]`. */
+export const SLO_WINDOW_PLACEHOLDER = "{{window}}";
+/** The Workbook's pairs ("Alerting on SLOs", table 5-8), as shares of the budget. */
+export const DEFAULT_BURN_RATES = Object.freeze({
+    page: Object.freeze([
+        Object.freeze({ long: "1h", short: "5m", budgetConsumed: 0.02 }),
+        Object.freeze({ long: "6h", short: "30m", budgetConsumed: 0.05 }),
+    ]),
+    ticket: Object.freeze([
+        Object.freeze({ long: "1d", short: "2h", budgetConsumed: 0.1 }),
+        Object.freeze({ long: "3d", short: "6h", budgetConsumed: 0.1 }),
+    ]),
+});
+const DEFAULT_ALERT_NAME = "ErrorBudgetBurn";
+const NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+const ALERT_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const SLO_METRICS = Symbol.for("chant.prometheus.slo");
+/** Record names. */
+const errorRatioRecord = (window) => `slo:sli_error:ratio_rate${window}`;
+const ERROR_BUDGET_REMAINING = "slo:error_budget:remaining";
+const OBJECTIVE_RATIO = "slo:objective:ratio";
+/** A number as PromQL writes it, without float noise: `1 - 0.995` is `0.005`. */
+function num(n) {
+    return String(Number(n.toPrecision(10)));
+}
+function fail(name, message) {
+    throw new Error(`Slo "${name}": ${message}`);
+}
+/** Check the props and work out every pair's factor; throws on anything the rules could not be built from. */
+function resolve(props) {
+    const name = typeof props?.name === "string" ? props.name : "";
+    if (!NAME.test(name))
+        fail(name, "name must be letters, digits, '.', '_' or '-', starting with a letter or digit");
+    const problem = sloPropsProblem(props);
+    if (problem)
+        fail(name, problem);
+    const windowMs = durationMs(props.window);
+    // Rounded, so 1 - 0.995 is 0.005 and not 0.0050000000000000044.
+    const budget = Number((1 - props.objective).toPrecision(12));
+    const alerting = props.alerting ?? {};
+    const alertName = alerting.alertName ?? DEFAULT_ALERT_NAME;
+    if (!ALERT_NAME.test(alertName))
+        fail(name, `alertName "${alertName}" is not a valid alert name`);
+    const pairs = [];
+    for (const tier of ["page", "ticket"]) {
+        const tierProps = alerting[tier];
+        if (tierProps === false)
+            continue;
+        const t = tierProps ?? {};
+        if (t.for !== undefined && !isValidDuration(t.for))
+            fail(name, `alerting.${tier}.for "${t.for}" is not a Prometheus duration`);
+        const windows = t.burnRates === undefined || t.burnRates === "default" ? DEFAULT_BURN_RATES[tier] : t.burnRates;
+        if (!Array.isArray(windows) || windows.length === 0)
+            fail(name, `alerting.${tier}.burnRates must be "default" or a non-empty list`);
+        windows.forEach((w, i) => {
+            const at = `alerting.${tier}.burnRates[${i}]`;
+            const longMs = isValidDuration(w.long) ? durationMs(w.long) : 0;
+            const shortMs = isValidDuration(w.short) ? durationMs(w.short) : 0;
+            if (longMs <= 0)
+                fail(name, `${at}.long "${w.long}" is not a positive Prometheus duration`);
+            if (shortMs <= 0)
+                fail(name, `${at}.short "${w.short}" is not a positive Prometheus duration`);
+            if (shortMs >= longMs)
+                fail(name, `${at}: the short window ${w.short} must be shorter than the long window ${w.long}`);
+            if (longMs > windowMs)
+                fail(name, `${at}: the long window ${w.long} is longer than the SLO window ${props.window}`);
+            const hasShare = w.budgetConsumed !== undefined;
+            const hasFactor = w.factor !== undefined;
+            if (hasShare === hasFactor)
+                fail(name, `${at} must set exactly one of budgetConsumed and factor`);
+            let factor;
+            if (hasShare) {
+                const s = w.budgetConsumed;
+                if (!(typeof s === "number" && s > 0 && s <= 1))
+                    fail(name, `${at}.budgetConsumed must be above 0 and at most 1, got ${s}`);
+                factor = Number(((s * windowMs) / longMs).toPrecision(6));
+            }
+            else {
+                factor = w.factor;
+                if (!(typeof factor === "number" && Number.isFinite(factor) && factor > 0))
+                    fail(name, `${at}.factor must be a positive number, got ${factor}`);
+            }
+            // An error ratio can't exceed 1, so a threshold at or above 1 never fires.
+            if (factor * budget >= 1) {
+                fail(name, `${at}: a burn rate of ${factor} on a budget of ${num(budget)} needs an error ratio of ${num(factor * budget)}, which can never happen`);
+            }
+            pairs.push({ tier, tierProps: t, long: w.long, short: w.short, factor });
+        });
+    }
+    const seen = new Set();
+    for (const p of pairs) {
+        const key = `${p.tier} ${p.long} ${p.short}`;
+        if (seen.has(key))
+            fail(name, `alerting.${p.tier} lists the pair ${p.long}/${p.short} twice`);
+        seen.add(key);
+    }
+    const byMs = new Map();
+    for (const p of pairs) {
+        for (const w of [p.long, p.short]) {
+            const ms = durationMs(w);
+            if (!byMs.has(ms))
+                byMs.set(ms, w);
+        }
+    }
+    byMs.delete(windowMs);
+    const windows = [...byMs.entries()].sort((a, b) => a[0] - b[0]).map(([, w]) => w);
+    windows.push(props.window);
+    return { props, budget, windowMs, pairs, alertName, windows };
+}
+/**
+ * What is wrong with an SLO's objective, window or SLI, or `undefined`.
+ * `Slo()` throws with this message; the PROM003 lint rule reports it at the
+ * literal in the source.
+ */
+export function sloPropsProblem(props) {
+    const o = props.objective;
+    if (typeof o !== "number" || !Number.isFinite(o) || o <= 0 || o >= 1) {
+        return `objective must be strictly between 0 and 1 (e.g. 0.995 for 99.5%), got ${String(o)}`;
+    }
+    if (!isValidDuration(props.window) || durationMs(props.window) === 0) {
+        return `window must be a positive Prometheus duration (e.g. 28d or 30d), got ${JSON.stringify(props.window)}`;
+    }
+    const sli = props.sli;
+    if (typeof sli !== "object" || sli === null)
+        return "sli must set good and total, or errors and total";
+    const hasGood = "good" in sli;
+    const hasErrors = "errors" in sli;
+    if (hasGood === hasErrors || !("total" in sli))
+        return "sli must set good and total, or errors and total";
+    for (const key of [hasGood ? "good" : "errors", "total"]) {
+        const problem = sliExprProblem(sli[key]);
+        if (problem)
+            return `sli.${key} ${problem}`;
+    }
+    return undefined;
+}
+/** What is wrong with one SLI expression, or `undefined`. */
+export function sliExprProblem(expr) {
+    if (typeof expr !== "string" || expr.trim() === "")
+        return "must be a PromQL expression";
+    if (!expr.includes(SLO_WINDOW_PLACEHOLDER)) {
+        return `must contain ${SLO_WINDOW_PLACEHOLDER} where the range goes, e.g. rate(x[${SLO_WINDOW_PLACEHOLDER}]), so it can be recorded per window`;
+    }
+    const checked = checkPromql(withWindow(expr, "5m"));
+    if (!checked.ok)
+        return `is not valid PromQL once ${SLO_WINDOW_PLACEHOLDER} is filled in: ${checked.message}`;
+    return undefined;
+}
+/**
+ * The number of events a counter saw over a window, counting a series' first
+ * sample. `rate()` and `increase()` need two samples in the range, so a counter
+ * that first appears inside the window reads as no events for the first one.
+ * This is the increase over the window where the series existed before it
+ * (never below 0, so a counter reset counts nothing), and the series' own
+ * value where it did not. Use it for `good`, `errors` and `total` of a sparse
+ * SLI; `window` defaults to the `{{window}}` placeholder an `Slo` fills in.
+ *
+ * `selector` is an instant vector selector, e.g. `jobs_total{result="ok"}`. It
+ * appears three times, so it must have no range and no `offset` of its own.
+ */
+export function eventCount(selector, window = SLO_WINDOW_PLACEHOLDER) {
+    const sel = typeof selector === "string" ? selector.trim() : "";
+    if (sel === "")
+        throw new Error("eventCount: selector must be an instant vector selector, e.g. jobs_total{result=\"ok\"}");
+    if (/\boffset\b/.test(sel) || /\[[^\]]*\]\s*$/.test(sel) || /^(sum|rate|increase)\b/.test(sel)) {
+        throw new Error(`eventCount: "${sel}" must be a plain instant vector selector, with no range, offset or function`);
+    }
+    return `sum(clamp_min(${sel} - ${sel} offset ${window}, 0) or (${sel} unless ${sel} offset ${window}))`;
+}
+function withWindow(expr, window) {
+    return expr.split(SLO_WINDOW_PLACEHOLDER).join(window);
+}
+function metricsOf(r) {
+    const { props, budget, pairs, alertName, windows } = r;
+    const errorRatio = {};
+    for (const w of windows)
+        errorRatio[w] = errorRatioRecord(w);
+    const burnRates = pairs.map((p) => ({
+        tier: p.tier,
+        severity: p.tierProps.severity ?? p.tier,
+        long: p.long,
+        short: p.short,
+        factor: p.factor,
+        threshold: Number((p.factor * budget).toPrecision(10)),
+        longRecord: errorRatioRecord(p.long),
+        shortRecord: errorRatioRecord(p.short),
+        alert: alertName,
+        labels: { slo: props.name, severity: p.tierProps.severity ?? p.tier, long_window: p.long, short_window: p.short },
+        exhaustsIn: formatDuration(Math.round(r.windowMs / p.factor / 60000) * 60000),
+    }));
+    return {
+        name: props.name,
+        objective: props.objective,
+        errorBudget: budget,
+        window: props.window,
+        labels: { slo: props.name },
+        selector: `{slo="${props.name}"}`,
+        windows: [...windows],
+        errorRatio,
+        windowErrorRatio: errorRatioRecord(props.window),
+        errorBudgetRemaining: ERROR_BUDGET_REMAINING,
+        objectiveRatio: OBJECTIVE_RATIO,
+        burnRates,
+        alertName,
+        group: `slo-${props.name}`,
+    };
+}
+function recordingRules(r, m) {
+    const { props } = r;
+    const sli = props.sli;
+    // A window with no events records nothing: `total > 0` drops the idle
+    // window's 0/0 NaN, and the SLO window's average then covers only the
+    // windows that had events. The numerator falls back to `0 * total`, so a
+    // window whose events were all good (or all bad) still records 0 (or 1)
+    // where its own series is absent.
+    const ratio = (w) => {
+        const total = `(${withWindow(sli.total, w)}) > 0`;
+        const some = (expr) => `((${expr}) or 0 * (${total}))`;
+        return sli.errors !== undefined
+            ? `${some(withWindow(sli.errors, w))}\n/\n(${total})`
+            : `1 - (\n  ${some(withWindow(sli.good, w))}\n  /\n  (${total})\n)`;
+    };
+    const labels = { slo: props.name };
+    const rules = [];
+    const alertWindows = m.windows.slice(0, -1);
+    for (const w of alertWindows)
+        rules.push({ record: m.errorRatio[w], expr: ratio(w), labels });
+    // The whole window as an average of the shortest recorded ratio, as Sloth
+    // does: a range over weeks of raw counters, every evaluation, is the most
+    // expensive query a rule file can hold. Without alert windows there is no
+    // shorter ratio to average, so the window is read from the SLI directly.
+    rules.push({
+        record: m.windowErrorRatio,
+        expr: alertWindows.length > 0 ? `avg_over_time(${m.errorRatio[alertWindows[0]]}${m.selector}[${props.window}])` : ratio(props.window),
+        labels,
+    });
+    rules.push({ record: OBJECTIVE_RATIO, expr: `vector(${num(props.objective)})`, labels });
+    rules.push({ record: ERROR_BUDGET_REMAINING, expr: `1 - (${m.windowErrorRatio}${m.selector} / ${num(r.budget)})`, labels });
+    return rules;
+}
+function alertRules(r, m) {
+    const { props } = r;
+    return r.pairs.map((p, i) => {
+        const b = m.burnRates[i];
+        const cond = (record) => `${record}${m.selector} > (${num(p.factor)} * ${num(r.budget)})`;
+        const rule = {
+            alert: b.alert,
+            expr: `(\n  ${cond(b.longRecord)}\n)\nand\n(\n  ${cond(b.shortRecord)}\n)`,
+            labels: { ...(p.tierProps.labels ?? {}), ...b.labels },
+            annotations: {
+                summary: `SLO ${props.name} is burning its error budget more than ${num(p.factor)}x too fast (${p.long} and ${p.short} windows)`,
+                description: `${props.description ? `${props.description} ` : ""}The error ratio over both the last ${p.long} and the last ${p.short} is above ` +
+                    `${num(b.threshold)} (${num(p.factor)} times the ${num(r.budget)} budget of a ${num(props.objective)} objective). ` +
+                    `At that rate the ${props.window} error budget is gone in ${b.exhaustsIn}.`,
+                ...(p.tierProps.annotations ?? {}),
+            },
+        };
+        if (p.tierProps.for !== undefined)
+            rule.for = p.tierProps.for;
+        return rule;
+    });
+}
+/**
+ * An SLO, built to recording rules and multiwindow multi-burn-rate alerts.
+ *
+ * @example
+ * ```ts
+ * export const orderAck = Slo({
+ *   name: "order-acknowledged",
+ *   objective: 0.995,
+ *   window: "28d",
+ *   sli: {
+ *     good: 'sum(rate(traces_span_metrics_calls_total{span_name="order.ack",status_code!="STATUS_CODE_ERROR"}[{{window}}]))',
+ *     total: 'sum(rate(traces_span_metrics_calls_total{span_name="order.ack"}[{{window}}]))',
+ *   },
+ * });
+ * // orderAck.rules is a RuleGroup; sloMetrics(orderAck) names its series.
+ * ```
+ */
+export const Slo = Composite((props) => {
+    const r = resolve(props);
+    const m = metricsOf(r);
+    const rules = [...recordingRules(r, m), ...alertRules(r, m)];
+    const group = new RuleGroup({
+        name: m.group,
+        ...(props.interval !== undefined ? { interval: props.interval } : {}),
+        ...(props.labels !== undefined ? { labels: props.labels } : {}),
+        rules,
+    });
+    Object.defineProperty(group, SLO_METRICS, { value: m, enumerable: false });
+    return { rules: group };
+}, "Slo");
+/**
+ * The recorded series names, objective, window and burn-rate thresholds of
+ * an SLO. Pass the `Slo(...)` result, its rule group, or the props
+ * it was built from; a dashboard reads names from here, so renaming or
+ * re-windowing the SLO moves its panels with it.
+ */
+export function sloMetrics(slo) {
+    const stashed = (x) => typeof x === "object" && x !== null ? x[SLO_METRICS] : undefined;
+    const direct = stashed(slo) ?? stashed(slo.rules);
+    if (direct)
+        return structuredClone(direct);
+    if (typeof slo === "object" && slo !== null && "objective" in slo && "sli" in slo)
+        return metricsOf(resolve(slo));
+    throw new Error("sloMetrics: pass an Slo(...) result, its rule group, or SLO props");
+}

package/dist/composites/watchdog.js

@@ -0,0 +1,110 @@
+/**
+ * `Watchdog`: an alert that always fires, routed to a heartbeat receiver.
+ *
+ * The alert's expression is `vector(1)`, so it fires from the first rule
+ * evaluation for as long as Prometheus evaluates rules and Alertmanager
+ * delivers notifications. The route sends it to a heartbeat service
+ * (healthchecks.io, Dead Man's Snitch, a PagerDuty or Opsgenie heartbeat),
+ * which raises its own alarm when the notifications stop: the whole alerting
+ * path, not just Prometheus, is down.
+ *
+ * The route is a child route, matched on the alert's name and severity. Put
+ * it first under the root route: `AlertRouting({ routes: [watchdog.route] })`,
+ * or the `routes` of a root `Route` of your own. Left unnested it is a second
+ * root, and the build warns.
+ *
+ * By default the receiver is a webhook that reads its URL from a file
+ * (`url_file`), since a heartbeat URL is a credential; mount the file into
+ * Alertmanager.
+ */
+import { Composite } from "@intentius/chant/composite";
+import { Receiver, Route, isReceiver } from "../alertmanager.js";
+import { RuleGroup } from "../rules.js";
+import { durationMs, isValidDuration } from "../duration.js";
+const ALERT_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const GROUP_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+/** The default heartbeat URL file. */
+export const WATCHDOG_URL_FILE = "/etc/alertmanager/secrets/heartbeat-url";
+function fail(message) {
+    throw new Error(`Watchdog: ${message}`);
+}
+/**
+ * An always-firing alert and the route that sends it to a heartbeat receiver.
+ *
+ * @example
+ * ```ts
+ * import { AlertRouting, Watchdog } from "@intentius/chant-lexicon-prometheus";
+ *
+ * export const watchdog = Watchdog({ urlFile: "/etc/alertmanager/secrets/healthchecks-url" });
+ * export const routing = AlertRouting({ routes: [watchdog.route] });
+ * ```
+ */
+export const Watchdog = Composite((input) => {
+    const props = input ?? {};
+    const alert = props.alert ?? "Watchdog";
+    if (!ALERT_NAME.test(alert))
+        fail(`alert "${alert}" is not a valid alert name`);
+    const severity = props.severity ?? "none";
+    if (typeof severity !== "string" || severity === "")
+        fail("severity must be a non-empty string");
+    const repeat = props.repeatInterval ?? "1m";
+    if (!isValidDuration(repeat) || !durationMs(repeat))
+        fail(`repeatInterval "${repeat}" is not a positive duration`);
+    // repeat_interval under group_interval is PROM223; a faster heartbeat brings the group interval down with it.
+    const groupInterval = (durationMs(repeat) ?? 0) < 60000 ? repeat : "1m";
+    const groupName = props.group ?? "watchdog";
+    if (!GROUP_NAME.test(groupName))
+        fail(`group "${groupName}" must be letters, digits, '.', '_' or '-'`);
+    if (props.urlFile !== undefined && props.receiver !== undefined)
+        fail("urlFile configures the default receiver; leave it out when receiver is set");
+    if (props.urlFile !== undefined && props.urlFile.trim() === "")
+        fail("urlFile must be a path");
+    let receiver;
+    let ref;
+    if (typeof props.receiver === "string") {
+        if (props.receiver === "")
+            fail("receiver must name a receiver");
+        ref = props.receiver;
+    }
+    else if (isReceiver(props.receiver)) {
+        ref = props.receiver;
+    }
+    else {
+        const p = props.receiver ?? {
+            name: "heartbeat",
+            webhook_configs: [{ url_file: props.urlFile ?? WATCHDOG_URL_FILE, send_resolved: false }],
+        };
+        if (!p.name)
+            fail("receiver.name is required");
+        receiver = new Receiver(p);
+        ref = receiver;
+    }
+    const rules = new RuleGroup({
+        name: groupName,
+        rules: [
+            {
+                alert,
+                expr: "vector(1)",
+                labels: { ...(props.labels ?? {}), severity },
+                annotations: {
+                    summary: "Always firing, to show the alerting pipeline works",
+                    description: "This alert fires all the time. A heartbeat service receives it every few minutes and raises its own alarm when it stops arriving, which means Prometheus, Alertmanager or the path between them is down.",
+                    ...(props.annotations ?? {}),
+                },
+            },
+        ],
+    });
+    const route = new Route({
+        receiver: ref,
+        matchers: [`alertname=${JSON.stringify(alert)}`, `severity=${JSON.stringify(severity)}`],
+        group_by: ["alertname"],
+        group_wait: "0s",
+        group_interval: groupInterval,
+        repeat_interval: repeat,
+        continue: false,
+    });
+    const members = { rules, route };
+    if (receiver)
+        members.receiver = receiver;
+    return members;
+}, "Watchdog");

package/dist/config-model.js

@@ -0,0 +1,52 @@
+/**
+ * The plain-data model of `prometheus.yml`: global settings, scrape configs,
+ * relabelling, service discovery, Alertmanager targets and remote storage.
+ *
+ * Written by hand against Prometheus v3.15.0 (`config/config.go` and
+ * `discovery/*`), field names in the file's own snake_case. SchemaStore's
+ * `prometheus.json` is not used to generate these: it is strict about unknown
+ * keys and behind v3.15.0 (no `runtime`, `otlp` or `tracing`, 11 of about 20
+ * `global` keys, 24 of 32 discovery kinds), so types generated from it would
+ * reject configs Prometheus accepts.
+ *
+ * Six discovery kinds are typed: kubernetes, file, http, dns, ec2 and consul.
+ * Any other `<kind>_sd_configs` key is carried as untyped data.
+ */
+/** The discovery kinds typed above. */
+export const TYPED_SD_KINDS = Object.freeze([
+    "kubernetes_sd_configs",
+    "file_sd_configs",
+    "http_sd_configs",
+    "dns_sd_configs",
+    "ec2_sd_configs",
+    "consul_sd_configs",
+]);
+/** Top-level keys of `prometheus.yml`, in the order Prometheus documents them. */
+export const PROMETHEUS_CONFIG_SECTIONS = Object.freeze([
+    "global",
+    "alerting",
+    "rule_files",
+    "scrape_config_files",
+    "scrape_configs",
+    "remote_write",
+    "remote_read",
+    "otlp",
+    "storage",
+    "tracing",
+    "runtime",
+]);
+const GLOBAL_ONLY_KEYS = ["scrape_interval", "scrape_timeout", "evaluation_interval", "external_labels", "rule_query_offset", "query_log_file"];
+/** True when a parsed document has the shape of a `prometheus.yml`. */
+export function looksLikePrometheusConfig(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const v = value;
+    if ("apiVersion" in v || "kind" in v || "groups" in v || "route" in v || "receivers" in v)
+        return false;
+    if (PROMETHEUS_CONFIG_SECTIONS.some((k) => k !== "global" && k !== "runtime" && k !== "storage" && k !== "tracing" && k in v)) {
+        return true;
+    }
+    // `global:` alone is Alertmanager's too; only Prometheus's own keys settle it.
+    const g = v.global;
+    return typeof g === "object" && g !== null && GLOBAL_ONLY_KEYS.some((k) => k in g);
+}