@intentius/chant-lexicon-prometheus 0.96.0

package/src/rules.ts

@@ -0,0 +1,127 @@
+/**
+ * `RuleGroup`: one group of recording and alerting rules.
+ *
+ * A group is the unit Prometheus evaluates together, on one interval, and
+ * the unit both destinations take: an entry under `groups:` in a rule file,
+ * and an entry in a Prometheus Operator `PrometheusRule`'s `spec.groups`. The
+ * same declaration renders to either; `ruleGroupConfig()` is the one
+ * conversion both go through.
+ *
+ * Rules are plain objects in the rule file's own shape, so a composite (the
+ * SLO declaration, say) can build them as data and hand a list to one or
+ * more groups.
+ */
+
+import { createResource } from "@intentius/chant/runtime";
+import type { Declarable } from "@intentius/chant/declarable";
+import {
+  isAlertingRuleConfig,
+  isRecordingRuleConfig,
+  type AlertingRuleConfig,
+  type LabelSet,
+  type RecordingRuleConfig,
+  type RuleConfig,
+  type RuleGroupConfig,
+} from "./model";
+
+export type RecordingRule = RecordingRuleConfig;
+export type AlertingRule = AlertingRuleConfig;
+export type Rule = RuleConfig;
+
+/** What `new RuleGroup(...)` takes: the group exactly as it appears in a rule file. */
+export type RuleGroupProps = RuleGroupConfig;
+
+export interface RuleGroupEntity extends Declarable {
+  readonly props: RuleGroupProps;
+  /** The group's `name`. */
+  readonly groupName: string;
+}
+
+export const RULE_GROUP_TYPE = "Prometheus::Rules::RuleGroup";
+
+const RuleGroupBase = createResource(RULE_GROUP_TYPE, "prometheus", {}) as unknown as (
+  this: object,
+  props: Record<string, unknown>,
+) => void;
+
+/**
+ * A group of recording and alerting rules.
+ *
+ * @example
+ * ```ts
+ * export const api = new RuleGroup({
+ *   name: "api",
+ *   interval: "30s",
+ *   rules: [
+ *     { record: "job:http_requests:rate5m", expr: "sum by (job) (rate(http_requests_total[5m]))" },
+ *     {
+ *       alert: "ApiHighErrorRate",
+ *       expr: 'sum(rate(http_requests_total{code=~"5.."}[5m])) / sum(rate(http_requests_total[5m])) > 0.05',
+ *       for: "10m",
+ *       labels: { severity: "page" },
+ *       annotations: { summary: "API 5xx ratio above 5%" },
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+export const RuleGroup = function (this: object, props: RuleGroupProps) {
+  RuleGroupBase.call(this, props as unknown as Record<string, unknown>);
+  Object.defineProperty(this, "groupName", { value: props?.name, enumerable: false });
+} as unknown as new (props: RuleGroupProps) => RuleGroupEntity;
+Object.defineProperty(RuleGroup, "name", { value: "RuleGroup" });
+
+/** True when `value` is a declared `RuleGroup`. */
+export function isRuleGroup(value: unknown): value is RuleGroupEntity {
+  return typeof value === "object" && value !== null && (value as Declarable).entityType === RULE_GROUP_TYPE;
+}
+
+function labelSet(value: LabelSet | undefined): LabelSet | undefined {
+  if (value === undefined || value === null) return undefined;
+  const out: LabelSet = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (v !== undefined) out[k] = String(v);
+  }
+  return out;
+}
+
+function defined<T extends Record<string, unknown>>(obj: T): T {
+  for (const k of Object.keys(obj)) if (obj[k] === undefined) delete obj[k];
+  return obj;
+}
+
+/** A rule in canonical key order, `undefined` fields dropped. */
+export function ruleConfig(rule: Rule): Rule {
+  if (isRecordingRuleConfig(rule)) {
+    return defined({ record: rule.record, expr: rule.expr, labels: labelSet(rule.labels) }) as RecordingRule;
+  }
+  if (isAlertingRuleConfig(rule)) {
+    return defined({
+      alert: rule.alert,
+      expr: rule.expr,
+      for: rule.for,
+      keep_firing_for: rule.keep_firing_for,
+      labels: labelSet(rule.labels),
+      annotations: labelSet(rule.annotations),
+    }) as AlertingRule;
+  }
+  // Neither `record` nor `alert`: keep it as written, and let PROM105 name it.
+  return { ...(rule as object) } as Rule;
+}
+
+/**
+ * The plain group a `RuleGroup` (or group props) renders to, in canonical key
+ * order. This is what goes under `groups:` in a rule file and into a
+ * `PrometheusRule`'s `spec.groups`.
+ */
+export function ruleGroupConfig(group: RuleGroupEntity | RuleGroupProps): RuleGroupConfig {
+  const p = isRuleGroup(group) ? group.props : group;
+  return defined({
+    name: p.name,
+    interval: p.interval,
+    query_offset: p.query_offset,
+    limit: p.limit,
+    labels: labelSet(p.labels),
+    rules: (p.rules ?? []).map(ruleConfig),
+  }) as RuleGroupConfig;
+}

package/src/serializer.test.ts

@@ -0,0 +1,179 @@
+import { describe, expect, test } from "vitest";
+import { load } from "js-yaml";
+import type { Declarable } from "@intentius/chant/declarable";
+import { prometheusSerializer, ALERTMANAGER_FILE } from "./serializer";
+import { AlertmanagerSettings, InhibitRule, Receiver, Route, RuleGroup, TimeInterval } from "./index";
+import type { AlertmanagerConfig, RuleFileConfig } from "./model";
+import type { SerializerResult } from "@intentius/chant/serializer";
+
+function entities(record: Record<string, unknown>): Map<string, Declarable> {
+  return new Map(Object.entries(record) as Array<[string, Declarable]>);
+}
+
+function primary(out: ReturnType<typeof prometheusSerializer.serialize>): string {
+  return typeof out === "string" ? out : out.primary;
+}
+
+const api = () =>
+  new RuleGroup({
+    name: "api",
+    interval: "30s",
+    rules: [
+      { record: "job:http_requests:rate5m", expr: "sum by (job) (rate(http_requests_total[5m]))" },
+      { alert: "ApiDown", expr: 'up{job="api"} == 0', for: "5m", labels: { severity: "page" }, annotations: { summary: "api is down" } },
+    ],
+  });
+
+describe("prometheus serializer", () => {
+  // 1, 2
+  test("name and rule prefix", () => {
+    expect(prometheusSerializer.name).toBe("prometheus");
+    expect(prometheusSerializer.rulePrefix).toBe("PROM");
+  });
+
+  // 3
+  test("an empty map serializes to the empty string", () => {
+    expect(prometheusSerializer.serialize(new Map())).toBe("");
+  });
+
+  // 4
+  test("one rule group is a rule file", () => {
+    expect(prometheusSerializer.serialize(entities({ api: api() }))).toBe(`groups:
+  - name: api
+    interval: 30s
+    rules:
+      - record: job:http_requests:rate5m
+        expr: sum by (job) (rate(http_requests_total[5m]))
+      - alert: ApiDown
+        expr: up{job="api"} == 0
+        for: 5m
+        labels:
+          severity: page
+        annotations:
+          summary: api is down
+`);
+  });
+
+  // 5, 6: the export name never appears; the group's own name is used
+  test("the group name comes from props, not the export name", () => {
+    const out = primary(prometheusSerializer.serialize(entities({ someExportName: api() })));
+    expect(out).not.toContain("someExportName");
+    expect((load(out) as RuleFileConfig).groups[0].name).toBe("api");
+  });
+
+  // 7
+  test("several groups come out sorted by name", () => {
+    const b = new RuleGroup({ name: "b", rules: [{ record: "b:x", expr: "1" }] });
+    const a = new RuleGroup({ name: "a", rules: [{ record: "a:x", expr: "1" }] });
+    const file = load(primary(prometheusSerializer.serialize(entities({ b, a })))) as RuleFileConfig;
+    expect(file.groups.map((g) => g.name)).toEqual(["a", "b"]);
+  });
+
+  // 8, 9: nothing is injected; what is set is what comes out
+  test("nothing is defaulted in", () => {
+    const g = new RuleGroup({ name: "g", rules: [{ alert: "A", expr: "vector(1)" }] });
+    expect(load(primary(prometheusSerializer.serialize(entities({ g }))))).toEqual({
+      groups: [{ name: "g", rules: [{ alert: "A", expr: "vector(1)" }] }],
+    });
+  });
+
+  // 10: non-prometheus entities are ignored
+  test("entities from other lexicons are skipped", () => {
+    const foreign = { lexicon: "k8s", entityType: "K8s::Core::ConfigMap", kind: "resource", props: {} };
+    expect(prometheusSerializer.serialize(entities({ foreign }))).toBe("");
+  });
+
+  // 11
+  test("keys come out in rule-file order whatever order they were written in", () => {
+    const g = new RuleGroup({
+      rules: [{ annotations: { summary: "s" }, labels: { severity: "page" }, for: "1m", expr: "up == 0", alert: "A" }],
+      interval: "1m",
+      name: "g",
+    } as never);
+    const text = primary(prometheusSerializer.serialize(entities({ g })));
+    expect(text.indexOf("name: g")).toBeLessThan(text.indexOf("interval"));
+    const rule = text.slice(text.indexOf("- alert"));
+    const order = ["alert", "expr", "for", "labels", "annotations"].map((k) => rule.indexOf(`${k}:`));
+    expect([...order].sort((x, y) => x - y)).toEqual(order);
+  });
+
+  // 12: format-specific
+  describe("alertmanager.yml", () => {
+    const hook = () => new Receiver({ name: "hook", webhook_configs: [{ url: "http://hook:8080/" }] });
+
+    test("alone, it is the primary output", () => {
+      const h = hook();
+      const root = new Route({ receiver: h, group_by: ["alertname"] });
+      const out = prometheusSerializer.serialize(entities({ h, root }));
+      expect(typeof out).toBe("string");
+      expect(load(out as string)).toEqual({
+        route: { receiver: "hook", group_by: ["alertname"] },
+        receivers: [{ name: "hook", webhook_configs: [{ url: "http://hook:8080/" }] }],
+      });
+    });
+
+    test("beside a rule file, it is written as alertmanager.yml", () => {
+      const h = hook();
+      const out = prometheusSerializer.serialize(entities({ api: api(), h, root: new Route({ receiver: h }) })) as SerializerResult;
+      expect((load(out.primary) as RuleFileConfig).groups).toHaveLength(1);
+      expect(Object.keys(out.files ?? {})).toEqual([ALERTMANAGER_FILE]);
+      expect((load(out.files![ALERTMANAGER_FILE]) as AlertmanagerConfig).route?.receiver).toBe("hook");
+    });
+
+    test("sections come out in Alertmanager's order, references by name", () => {
+      const h = hook();
+      const quiet = new TimeInterval({ name: "weekend", time_intervals: [{ weekdays: ["saturday", "sunday"] }] });
+      const out = primary(
+        prometheusSerializer.serialize(
+          entities({
+            quiet,
+            inhibit: new InhibitRule({ source_matchers: ['severity="page"'], target_matchers: ['severity="ticket"'], equal: ["alertname"] }),
+            h,
+            root: new Route({ receiver: h, routes: [{ matchers: ['severity="ticket"'], receiver: "hook", mute_time_intervals: [quiet] }] }),
+            settings: new AlertmanagerSettings({ global: { resolve_timeout: "5m" }, templates: ["/etc/am/*.tmpl"] }),
+          }),
+        ),
+      );
+      const keys = Object.keys(load(out) as object);
+      expect(keys).toEqual(["global", "templates", "route", "inhibit_rules", "receivers", "time_intervals"]);
+      expect((load(out) as AlertmanagerConfig).route?.routes?.[0].mute_time_intervals).toEqual(["weekend"]);
+    });
+
+    test("a receiver or interval reached only through a route is still emitted", () => {
+      const h = hook();
+      const quiet = new TimeInterval({ name: "night", time_intervals: [{ times: [{ start_time: "22:00", end_time: "24:00" }] }] });
+      const out = load(primary(prometheusSerializer.serialize(entities({ root: new Route({ receiver: h, mute_time_intervals: [quiet] }) })))) as AlertmanagerConfig;
+      expect(out.receivers?.map((r) => r.name)).toEqual(["hook"]);
+      expect(out.time_intervals?.map((t) => t.name)).toEqual(["night"]);
+    });
+
+    test("a child Route entity is not a second root", () => {
+      const h = hook();
+      const child = new Route({ matchers: ['severity="page"'], receiver: h });
+      const out = prometheusSerializer.serialize(entities({ h, child, root: new Route({ receiver: h, routes: [child] }) }));
+      expect(typeof out).toBe("string");
+      expect((load(out as string) as AlertmanagerConfig).route?.routes).toHaveLength(1);
+    });
+
+    test("two roots warn and the first wins", () => {
+      const h = hook();
+      const out = prometheusSerializer.serialize(entities({ h, a: new Route({ receiver: h }), b: new Route({ receiver: "other" }) })) as SerializerResult;
+      expect(out.warnings?.[0]).toContain("2 root Routes");
+      expect((load(out.primary) as AlertmanagerConfig).route?.receiver).toBe("hook");
+    });
+  });
+
+  test("round-trip: the rule file parses back to the declared group", () => {
+    const g = api();
+    const file = load(primary(prometheusSerializer.serialize(entities({ g })))) as RuleFileConfig;
+    expect(file.groups[0]).toEqual(g.props);
+  });
+
+  test("a multi-line expr survives as a block scalar", () => {
+    const expr = "sum(rate(a[5m]))\n  /\nsum(rate(b[5m]))";
+    const g = new RuleGroup({ name: "g", rules: [{ record: "a:ratio", expr }] });
+    const text = primary(prometheusSerializer.serialize(entities({ g })));
+    expect(text).toContain("expr: |-");
+    expect((load(text) as RuleFileConfig).groups[0].rules[0].expr).toBe(expr);
+  });
+});

package/src/serializer.ts

@@ -0,0 +1,55 @@
+/**
+ * Prometheus serializer.
+ *
+ * Emits the two files a Prometheus setup reads:
+ *
+ * - the rule file (`groups:`), from every `RuleGroup` in the build, the file
+ *   `rule_files:` points at and `promtool check rules` reads;
+ * - `alertmanager.yml`, from the `Route`, `Receiver`, `InhibitRule`,
+ *   `TimeInterval` and `AlertmanagerSettings` entities, the file
+ *   `amtool check-config` reads.
+ *
+ * The rule file is the primary output when the build declares any rule
+ * groups, and `alertmanager.yml` is written beside it when the build also
+ * declares Alertmanager entities. A build with only Alertmanager entities
+ * emits `alertmanager.yml` as the primary output. Rules inside a group and
+ * child routes keep the order they are written in, which is the order that
+ * matters to Prometheus and Alertmanager; groups, receivers and time
+ * intervals, whose order means nothing, are sorted by name.
+ *
+ * Neither file has a metadata channel, so there is no ownership marker to
+ * stamp.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import type { Serializer, SerializerResult } from "@intentius/chant/serializer";
+import type { LexiconOutput } from "@intentius/chant/lexicon-output";
+import { buildAlertmanagerConfig, buildRuleFile, emitYaml } from "./build";
+
+/** The filename `alertmanager.yml` is written under when it sits beside a rule file. */
+export const ALERTMANAGER_FILE = "alertmanager.yml";
+
+export const prometheusSerializer: Serializer = {
+  name: "prometheus",
+  rulePrefix: "PROM",
+
+  serialize(entities: Map<string, Declarable>, _outputs?: LexiconOutput[]): string | SerializerResult {
+    const rules = buildRuleFile(entities);
+    const am = buildAlertmanagerConfig(entities);
+    const hasRules = rules.groups.length > 0;
+    const hasAm = am.count > 0;
+    const warnings = am.warnings;
+
+    if (!hasRules && !hasAm) return "";
+    if (!hasAm) return emitYaml(rules.config);
+    if (!hasRules) {
+      const text = emitYaml(am.config);
+      return warnings.length === 0 ? text : { primary: text, warnings };
+    }
+    return {
+      primary: emitYaml(rules.config),
+      files: { [ALERTMANAGER_FILE]: emitYaml(am.config) },
+      ...(warnings.length > 0 ? { warnings } : {}),
+    };
+  },
+};

package/src/skill-defs.ts

@@ -0,0 +1,43 @@
+import { createSkillsLoader } from "@intentius/chant/lexicon-plugin-helpers";
+
+/** The prometheus lexicon's AI skills, read from src/skills/. */
+export const prometheusSkills = createSkillsLoader(import.meta.url, [
+  {
+    file: "chant-prometheus.md",
+    name: "chant-prometheus",
+    description: "Declare Prometheus recording and alerting rule groups as typed chant entities and build a rule file that passes promtool",
+    triggers: [
+      { type: "context" as const, value: "prometheus rules" },
+      { type: "context" as const, value: "alerting rule" },
+      { type: "context" as const, value: "recording rule" },
+    ],
+    examples: [
+      {
+        title: "A recording rule and an alert on it",
+        output:
+          "export const api = new RuleGroup({\n" +
+          '  name: "api",\n' +
+          "  rules: [\n" +
+          '    { record: "job:http_errors:ratio5m", expr: \'sum by (job) (rate(http_requests_total{code=~"5.."}[5m])) / sum by (job) (rate(http_requests_total[5m]))\' },\n' +
+          '    { alert: "ApiErrors", expr: "job:http_errors:ratio5m > 0.05", for: "10m", labels: { severity: "page" }, annotations: { summary: "5xx ratio above 5%" } },\n' +
+          "  ],\n" +
+          "});",
+      },
+    ],
+  },
+  {
+    file: "chant-prometheus-alertmanager.md",
+    name: "chant-prometheus-alertmanager",
+    description: "Declare Alertmanager routing (routes, receivers, inhibit rules, time intervals) and keep every alert severity routed",
+    triggers: [
+      { type: "context" as const, value: "alertmanager" },
+      { type: "context" as const, value: "alert routing" },
+    ],
+  },
+  {
+    file: "chant-prometheus-kubernetes.md",
+    name: "chant-prometheus-kubernetes",
+    description: "Render the same RuleGroups into a Prometheus Operator PrometheusRule, or into ConfigMaps for a plain Prometheus and Alertmanager on Kubernetes",
+    triggers: [{ type: "context" as const, value: "PrometheusRule" }],
+  },
+]);

package/src/skills/chant-prometheus-alertmanager.md

@@ -0,0 +1,58 @@
+---
+skill: chant-prometheus-alertmanager
+description: Declare Alertmanager routing (routes, receivers, inhibit rules, time intervals) and keep every alert severity routed
+user-invocable: true
+---
+
+# Alertmanager routing with chant
+
+`Route`, `Receiver`, `InhibitRule`, `TimeInterval` and `AlertmanagerSettings` build `alertmanager.yml`. When the same build root declares `RuleGroup`s, the rule file is the primary output and `alertmanager.yml` is written beside it.
+
+```ts
+import { AlertmanagerSettings, InhibitRule, Receiver, Route, TimeInterval } from "@intentius/chant-lexicon-prometheus";
+
+export const settings = new AlertmanagerSettings({ global: { resolve_timeout: "5m" } });
+
+export const oncall = new Receiver({
+  name: "oncall",
+  pagerduty_configs: [{ routing_key_file: "/etc/alertmanager/secrets/pagerduty-key" }],
+});
+export const team = new Receiver({
+  name: "team-slack",
+  slack_configs: [{ api_url_file: "/etc/alertmanager/secrets/slack-url", channel: "#alerts", send_resolved: true }],
+});
+export const sink = new Receiver({ name: "default", webhook_configs: [{ url: "http://alert-sink.monitoring:8080/" }] });
+
+export const offHours = new TimeInterval({
+  name: "off-hours",
+  time_intervals: [{ weekdays: ["saturday", "sunday"] }, { times: [{ start_time: "18:00", end_time: "24:00" }] }],
+});
+
+export const root = new Route({
+  receiver: sink,
+  group_by: ["alertname", "job"],
+  group_wait: "30s",
+  group_interval: "5m",
+  repeat_interval: "4h",
+  routes: [
+    { matchers: ['severity="page"'], receiver: oncall },
+    { matchers: ['severity="ticket"'], receiver: team, mute_time_intervals: [offHours] },
+  ],
+});
+
+export const pageMutesTicket = new InhibitRule({
+  source_matchers: ['severity="page"'],
+  target_matchers: ['severity="ticket"'],
+  equal: ["alertname", "job"],
+});
+```
+
+## What the checks hold you to
+
+- One root route (the `Route` no other route nests), with a receiver and no matchers (PROM205).
+- Routes name receivers and time intervals that exist (PROM201, PROM204). Reference the entity rather than a string and TypeScript does most of this.
+- Every `severity` an alert in the same build root carries is matched by some route below the root (PROM202). The check only sees one build root (chant #1939): keep the rules and the Alertmanager config in the same one, or it goes quiet.
+- Credentials go in `*_file` fields. Alertmanager does not expand environment variables in its config, and a literal `api_url`, `routing_key` or `auth_password` is flagged (PROM001).
+- Each integration has somewhere to send (PROM209): a webhook `url`, a Slack `api_url` (or `global.slack_api_url`), a PagerDuty key, an email `to`/`smarthost`/`from` (or the global SMTP defaults).
+
+Run `amtoolCheckConfig(alertmanagerYaml(entities))` in a test to have `amtool check-config` confirm it when installed.

package/src/skills/chant-prometheus-kubernetes.md

@@ -0,0 +1,48 @@
+---
+skill: chant-prometheus-kubernetes
+description: Render the same RuleGroups into a Prometheus Operator PrometheusRule, or into ConfigMaps for a plain Prometheus and Alertmanager on Kubernetes
+user-invocable: true
+---
+
+# Prometheus rules on Kubernetes
+
+A `RuleGroup` from `@intentius/chant-lexicon-prometheus` renders to two places: the rule file, and a Prometheus Operator `PrometheusRule` from `@intentius/chant-lexicon-k8s`.
+
+## Into a PrometheusRule
+
+```ts
+import { PrometheusRule } from "@intentius/chant-lexicon-k8s";
+import { RuleGroup } from "@intentius/chant-lexicon-prometheus";
+
+const api = new RuleGroup({
+  name: "api",
+  rules: [{ alert: "ApiDown", expr: 'up{job="api"} == 0', for: "5m", labels: { severity: "page" }, annotations: { summary: "api is down" } }],
+});
+
+export const apiRules = new PrometheusRule({
+  metadata: { name: "api-rules", labels: { release: "kube-prometheus-stack" } },
+  spec: { groups: [api] },
+});
+```
+
+The k8s serializer writes each `RuleGroup` in `spec.groups` as the same group the rule file would hold. Declare the group with `const` (not exported) when it should only appear inside the CRD; export it too when the build should also write the rule file.
+
+`MonitoredService` takes the groups directly:
+
+```ts
+MonitoredService({ name: "api", image: "api:1.0", ruleGroups: [api] });
+```
+
+Its older `alertRules` prop still works, and both may be set; the groups come after the `alertRules` group.
+
+## Without the operator
+
+For a plain Prometheus or Alertmanager Deployment, put the files in ConfigMaps with `ruleFileYaml(groups)` and `alertmanagerYaml(entities)`:
+
+```ts
+import { ConfigMap } from "@intentius/chant-lexicon-k8s";
+import { ruleFileYaml, alertmanagerYaml } from "@intentius/chant-lexicon-prometheus";
+
+export const rulesCm = new ConfigMap({ metadata: { name: "prometheus-rules" }, data: { "rules.yml": ruleFileYaml([api]) } });
+export const amCm = new ConfigMap({ metadata: { name: "alertmanager" }, data: { "alertmanager.yml": alertmanagerYaml([root, oncall, sink]) } });
+```

package/src/skills/chant-prometheus.md

@@ -0,0 +1,91 @@
+---
+skill: chant-prometheus
+description: Declare Prometheus recording and alerting rule groups as typed chant entities and build a rule file that passes promtool
+user-invocable: true
+---
+
+# Prometheus rules with chant
+
+The prometheus lexicon (`@intentius/chant-lexicon-prometheus`) types Prometheus rule groups. Each `RuleGroup` is an entity; `chant build` writes the rule file Prometheus loads through `rule_files:`.
+
+## Project setup
+
+```ts
+// chant.config.ts
+export default { lexicons: ["prometheus"] };
+```
+
+## Declaring a group
+
+A group takes the rule file's own keys (`name`, `interval`, `query_offset`, `limit`, `labels`, `rules`). Rules are plain objects: `record` + `expr` for a recording rule, `alert` + `expr` (+ `for`, `keep_firing_for`, `labels`, `annotations`) for an alerting rule.
+
+```ts
+import { RuleGroup } from "@intentius/chant-lexicon-prometheus";
+
+export const api = new RuleGroup({
+  name: "api",
+  interval: "30s",
+  rules: [
+    {
+      record: "job:http_errors:ratio5m",
+      expr: 'sum by (job) (rate(http_requests_total{code=~"5.."}[5m])) / sum by (job) (rate(http_requests_total[5m]))',
+    },
+    {
+      alert: "ApiErrorRatioHigh",
+      expr: "job:http_errors:ratio5m > 0.05",
+      for: "10m",
+      labels: { severity: "page" },
+      annotations: { summary: "{{ $labels.job }} 5xx ratio above 5%", runbook_url: "https://runbooks.example.com/api-errors" },
+    },
+  ],
+});
+```
+
+Build it with `chant build src --lexicon prometheus -o dist/rules.yml`.
+
+## Rules of thumb
+
+- Name recording rules `level:metric:operations` (`job:http_errors:ratio5m`), and alert on the recorded series rather than repeating the expression.
+- Give every alert a `severity` label (PROM106) that an Alertmanager route matches (PROM202), and a `summary` annotation (PROM107).
+- Alerts may share a name when their labels differ, e.g. the same alert at `severity: "page"` and `severity: "ticket"`. Two rules with the same name *and* labels overwrite each other (PROM102).
+- Durations are Prometheus durations: `30s`, `5m`, `1h30m`. Not `1.5h`, not `90 seconds` (PROM103).
+- Every `expr` is parsed with the Prometheus project's PromQL grammar at build time (PROM104) and, for literals, in the editor (PROM002).
+
+## Checking with promtool
+
+```ts
+import { ruleFileYaml, promtoolCheckRules } from "@intentius/chant-lexicon-prometheus";
+
+const result = promtoolCheckRules(ruleFileYaml([api]));
+if (result.ran && !result.ok) throw new Error(result.output);
+```
+
+`ran` is false when `promtool` isn't on PATH (or `$PROMTOOL`), so a test can skip instead of failing.
+
+## Building rules from data
+
+`RuleGroup` takes plain rule objects, so a composite can generate them: map over services or windows, return one or more `RuleGroup`s, and the rule file and a `PrometheusRule` both pick them up. `ruleGroupConfig(group)` gives the plain group as it appears in the file.
+
+## SLOs
+
+`Slo` builds an SLO to one `RuleGroup`: error ratios per window, the error budget left, and the SRE Workbook's multiwindow burn-rate alerts (page at 1h/5m and 6h/30m, ticket at 1d/2h and 3d/6h, factors scaled to the SLO window). It is a composite, called without `new`.
+
+```ts
+import { Slo, sloMetrics } from "@intentius/chant-lexicon-prometheus";
+
+export const checkout = Slo({
+  name: "checkout",
+  objective: 0.999,
+  window: "30d",
+  sli: {
+    good: 'sum(rate(http_requests_total{job="checkout",code!~"5.."}[{{window}}]))',
+    total: 'sum(rate(http_requests_total{job="checkout"}[{{window}}]))',
+  },
+});
+
+sloMetrics(checkout).errorRatio["1h"]; // "slo:sli_error:ratio_rate1h"
+```
+
+- Write the objective as a fraction strictly between 0 and 1, and put `{{window}}` where each SLI expression's range goes (PROM003).
+- Alerts carry `severity` `page` or `ticket`; route both (PROM202).
+- Read series names from `sloMetrics()` in dashboards instead of repeating them.