@intentius/chant-lexicon-prometheus 0.106.4 → 0.108.0

package/src/op/slo-rule-tests.test.ts

@@ -0,0 +1,84 @@
+/**
+ * The promtool tests generated from an `Slo`: their shape always, and
+ * `promtool test rules` over them when promtool is on PATH (or named by
+ * $PROMTOOL).
+ */
+import { beforeAll, describe, expect, test } from "vitest";
+import { load } from "js-yaml";
+import { Slo, sloMetrics } from "../composites/slo";
+import { ruleFileYaml } from "../build";
+import { hasTool, promtoolTestRules } from "../tools";
+import { seriesLabels, seriesValues, sloRuleTests } from "./slo-rule-tests";
+
+const PROMTOOL = process.env.PROMTOOL ?? "promtool";
+
+const slo = Slo({
+  name: "checkout",
+  objective: 0.995,
+  window: "30d",
+  sli: {
+    good: 'sum(rate(requests_total{code!~"5.."}[{{window}}]))',
+    total: "sum(rate(requests_total[{{window}}]))",
+  },
+});
+const input = { slo, good: 'requests_total{code="200"}', bad: 'requests_total{code="500"}' };
+
+interface TestFile {
+  rule_files: string[];
+  evaluation_interval: string;
+  tests: Array<{
+    interval: string;
+    input_series: Array<{ series: string; values: string }>;
+    alert_rule_test: Array<{ eval_time: string; alertname: string; exp_alerts: Array<{ exp_labels: Record<string, string> }> }>;
+  }>;
+}
+
+describe("sloRuleTests", () => {
+  test("series parsing and promtool's a+bxn notation", () => {
+    expect(seriesLabels('requests_total{code="200", job="api"}')).toEqual({ __name__: "requests_total", code: "200", job: "api" });
+    expect(seriesLabels("up")).toEqual({ __name__: "up" });
+    expect(() => seriesLabels('x{code=~"5.."}')).toThrow(/equality only/);
+    expect(seriesValues([0, 10, 20, 30, 35, 40])).toBe("0+10x3 35+5x1");
+    expect(seriesValues([5])).toBe("5");
+  });
+
+  test("one file per step size, each naming rules.yml, two scenarios per burn-rate pair", () => {
+    const files = sloRuleTests([input]).map((y) => load(y) as TestFile);
+    const m = sloMetrics(slo);
+    expect(files.map((f) => f.evaluation_interval)).toEqual(["1m", "5m"]);
+    for (const f of files) expect(f.rule_files).toEqual(["rules.yml"]);
+    expect(files.reduce((n, f) => n + f.tests.length, 0)).toBe(2 * m.burnRates.length);
+    expect(files[0].tests[0].input_series.map((s) => s.series)).toEqual([input.good, input.bad]);
+  });
+
+  test("the expectations come from the evaluator: each pair fires above its rate and not below it", () => {
+    const files = sloRuleTests([input]).map((y) => load(y) as TestFile);
+    const m = sloMetrics(slo);
+    const tests = files.flatMap((f) => f.tests);
+    m.burnRates.forEach((b, i) => {
+      const [above, below] = [tests[2 * i], tests[2 * i + 1]];
+      const fires = (t: (typeof tests)[number], k: number) =>
+        t.alert_rule_test[k].exp_alerts.some((a) => Object.entries(b.labels).every(([key, v]) => a.exp_labels[key] === v));
+      expect(fires(above, 0), `${b.long}/${b.short} before onset`).toBe(false);
+      expect(fires(above, 1), `${b.long}/${b.short} after onset`).toBe(true);
+      expect(fires(above, 2), `${b.long}/${b.short} end of burn`).toBe(true);
+      expect(fires(below, 0), `${b.long}/${b.short} at 0.9x`).toBe(false);
+      expect(above.alert_rule_test[0].alertname).toBe(m.alertName);
+    });
+  });
+
+  describe.skipIf(!hasTool(PROMTOOL))("with promtool", () => {
+    // promtool takes most of 20s over the ticket pairs' days of samples on a CI
+    // runner, past the unit budget, which does not count a beforeAll.
+    let results: Array<{ ok: boolean; output: string }> = [];
+    beforeAll(() => {
+      const rules = ruleFileYaml([slo.rules]);
+      results = sloRuleTests([input]).map((yaml) => promtoolTestRules(rules, yaml, PROMTOOL));
+    }, 300_000);
+
+    test("promtool test rules agrees with every generated file", () => {
+      expect(results).toHaveLength(2);
+      for (const r of results) expect(r.ok, r.output).toBe(true);
+    });
+  });
+});

package/src/op/slo-rule-tests.ts

@@ -0,0 +1,173 @@
+/**
+ * `promtool test rules` input generated from `Slo` declarations (#3369),
+ * lifted from `composites/slo-burn.test.ts`.
+ *
+ * For each burn-rate pair an `Slo` builds, two synthetic scenarios over a
+ * good and a bad request counter: healthy for the pair's long window, then
+ * burning the error budget at 1.25 times the pair's factor (it must fire)
+ * and at 0.9 times it (it must not). The small evaluator in `rule-eval.ts`
+ * runs the SLO's rules over each scenario and says which alerts fire at a
+ * few evaluation times around the expected onset; those become the
+ * `alert_rule_test` expectations, so `promtool test rules` holds Prometheus
+ * to the same answer.
+ *
+ * The SLI expressions are the author's, so the generator cannot invent the
+ * series they read: `good` and `bad` name one series each (`metric{labels}`),
+ * counters such that the SLI counts `good` as good events and `bad` as bad
+ * ones. The evaluator throws on PromQL it does not implement, which then
+ * fails here, at authoring time, rather than in promtool.
+ *
+ * Pairs whose long window is a day or more step in five minutes, the rest in
+ * one, and promtool's `evaluation_interval` is per file, so the result is
+ * one test file per step size.
+ */
+
+import { dump } from "js-yaml";
+import { sloMetrics, type SloBurnRate, type SloInstance } from "../composites/slo";
+import { ruleGroupConfig } from "../rules";
+import { RuleEvaluator, type FiringAlert } from "../rule-eval";
+import { durationMs } from "../duration";
+import type { AlertingRuleConfig } from "../model";
+
+const MIN = 60_000;
+
+export interface SloTestInput {
+  /** The `Slo(...)` result. */
+  slo: SloInstance;
+  /** The good-events counter, e.g. `requests_total{code="200"}`. */
+  good: string;
+  /** The bad-events counter, e.g. `requests_total{code="500"}`. */
+  bad: string;
+  /** Events per minute. Default 1000. */
+  rate?: number;
+}
+
+interface Scenario {
+  step: number;
+  healthy: number;
+  burning: number;
+  burn: number;
+}
+
+/** `metric{a="1",b="2"}` as a label set with `__name__`. */
+export function seriesLabels(series: string): Record<string, string> {
+  const m = /^\s*([A-Za-z_:][A-Za-z0-9_:]*)\s*(?:\{(.*)\})?\s*$/.exec(series);
+  if (!m) throw new Error(`"${series}" is not a series: write metric{label="value",...}`);
+  const labels: Record<string, string> = { __name__: m[1] };
+  const body = m[2]?.trim();
+  if (body) {
+    const re = /\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*"((?:[^"\\]|\\.)*)"\s*(?:,|$)/y;
+    let pos = 0;
+    while (pos < body.length) {
+      re.lastIndex = pos;
+      const p = re.exec(body);
+      if (!p) throw new Error(`"${series}": label matchers must be name="value" (equality only)`);
+      labels[p[1]] = p[2].replace(/\\(.)/g, "$1");
+      pos = re.lastIndex;
+    }
+  }
+  return labels;
+}
+
+/** Counter samples as promtool's `a+bxn` segments. */
+export function seriesValues(values: number[]): string {
+  const parts: string[] = [];
+  let i = 0;
+  while (i < values.length) {
+    const start = values[i];
+    if (i + 1 >= values.length) {
+      parts.push(`${start}`);
+      break;
+    }
+    const inc = values[i + 1] - values[i];
+    let j = i + 1;
+    while (j + 1 < values.length && Math.abs(values[j + 1] - values[j] - inc) < 1e-9) j++;
+    parts.push(`${start}+${inc}x${j - i}`);
+    i = j + 1;
+  }
+  return parts.join(" ");
+}
+
+function isPair(a: FiringAlert, b: SloBurnRate): boolean {
+  return a.labels.alertname === b.alert && Object.entries(b.labels).every(([k, v]) => a.labels[k] === v);
+}
+
+const minutes = (d: string): number => durationMs(d)! / MIN;
+
+/** One scenario: the counters' samples, and the evaluator's firing alerts by minute. */
+function simulate(input: SloTestInput, s: Scenario) {
+  const m = sloMetrics(input.slo);
+  const rate = input.rate ?? 1000;
+  const goodLabels = seriesLabels(input.good);
+  const badLabels = seriesLabels(input.bad);
+  const ev = new RuleEvaluator([ruleGroupConfig(input.slo.rules)]);
+  const total = s.healthy + s.burning;
+  const good: number[] = [];
+  const bad: number[] = [];
+  let g = 0;
+  let e = 0;
+  const timeline = new Map<number, FiringAlert[]>();
+  for (let minute = 0; minute <= total; minute += s.step) {
+    if (minute > 0) {
+      const burning = minute > s.healthy && minute <= s.healthy + s.burning;
+      const b = burning ? rate * s.step * s.burn * m.errorBudget : 0;
+      e += b;
+      g += rate * s.step - b;
+    }
+    good.push(g);
+    bad.push(e);
+    ev.add(goodLabels, minute * MIN, g);
+    ev.add(badLabels, minute * MIN, e);
+    timeline.set(minute, ev.step(minute * MIN));
+  }
+  return { good, bad, timeline };
+}
+
+function testGroup(input: SloTestInput, s: Scenario, checkAt: number[]) {
+  const m = sloMetrics(input.slo);
+  const alertRules = ruleGroupConfig(input.slo.rules).rules.filter((r): r is AlertingRuleConfig => "alert" in r);
+  const { good, bad, timeline } = simulate(input, s);
+  return {
+    interval: `${s.step}m`,
+    input_series: [
+      { series: input.good, values: seriesValues(good) },
+      { series: input.bad, values: seriesValues(bad) },
+    ],
+    alert_rule_test: checkAt.map((minute) => ({
+      eval_time: `${minute}m`,
+      alertname: m.alertName,
+      exp_alerts: (timeline.get(minute) ?? [])
+        .filter((a) => a.labels.alertname === m.alertName)
+        .map((a) => {
+          const rule = alertRules.find((r) => Object.entries(r.labels ?? {}).every(([k, v]) => a.labels[k] === v));
+          const { alertname: _, ...labels } = a.labels;
+          return { exp_labels: labels, ...(rule?.annotations ? { exp_annotations: rule.annotations } : {}) };
+        }),
+    })),
+  };
+}
+
+/**
+ * The `promtool test rules` files for these SLOs, one per step size, each
+ * naming `rules.yml` (where `promtoolTestRules` writes the rule file).
+ */
+export function sloRuleTests(inputs: SloTestInput[]): string[] {
+  const byStep = new Map<number, unknown[]>();
+  for (const input of inputs) {
+    for (const b of sloMetrics(input.slo).burnRates) {
+      const long = minutes(b.long);
+      const step = long >= 24 * 60 ? 5 : 1;
+      const snap = (x: number) => Math.round(x / step) * step;
+      const above: Scenario = { step, healthy: long, burning: long, burn: b.factor * 1.25 };
+      const fireAt = above.healthy + ((long - step) * b.factor) / above.burn;
+      const below: Scenario = { step, healthy: long, burning: long, burn: b.factor * 0.9 };
+      const groups = byStep.get(step) ?? [];
+      groups.push(testGroup(input, above, [snap(fireAt - 4 * step), snap(fireAt + 4 * step), above.healthy + long]));
+      groups.push(testGroup(input, below, [below.healthy + long]));
+      byStep.set(step, groups);
+    }
+  }
+  return [...byStep.entries()]
+    .sort(([a], [b]) => a - b)
+    .map(([step, tests]) => dump({ rule_files: ["rules.yml"], evaluation_interval: `${step}m`, tests }, { lineWidth: -1 }));
+}

package/src/plugin.ts

@@ -18,6 +18,7 @@ import { CATALOG } from "./catalog";
 import { PROMETHEUS_PIN } from "./pin";
 import { PROMQL_GRAMMAR } from "./promql";
 import { compositeCatalog } from "./composites/catalog";
+import { prometheusConfigSchema } from "./config";
 
 const catalogResource: McpResourceContribution = {
   uri: "prometheus:resource-catalog",
@@ -39,6 +40,7 @@ const catalogResource: McpResourceContribution = {
 export const prometheusPlugin: LexiconPlugin = {
   name: "prometheus",
   serializer: prometheusSerializer,
+  configSchema: prometheusConfigSchema,
 
   // ── Required lifecycle methods ────────────────────────────────
 
@@ -153,6 +155,20 @@ export const prometheusPlugin: LexiconPlugin = {
     return hover(ctx);
   },
 
+  // ── Live observation and export (#3371) ──────────────────────
+  // Behind dynamic imports, so `chant build` never loads a transport. The
+  // ruler and Alertmanager are named by `prometheus.profiles.<env>` (./config.ts).
+
+  async describeResources(options) {
+    const { describeResources } = await import("./describe-resources");
+    return describeResources(options);
+  },
+
+  async exportResources(options) {
+    const { exportResources } = await import("./export-resources");
+    return exportResources(options);
+  },
+
   async docs(options?: { verbose?: boolean }) {
     const { generateDocs } = await import("./codegen/docs");
     return generateDocs(options);