@intentius/chant-lexicon-prometheus 0.101.0 → 0.104.0

package/src/collector-metrics.ts

@@ -0,0 +1,262 @@
+/**
+ * The metric names the collector configs in a build emit through their
+ * `spanmetrics`, `servicegraph`, `sum` and `signaltometrics` connectors (the
+ * last two are how the otel GenAI preset counts tokens and derives the
+ * conventions' client metrics), and the PromQL that reads under those
+ * connectors' namespaces without matching one of them (PROM301).
+ *
+ * Grafana's GRAF118 runs `collectorMetricIssues` over panel queries; the
+ * prometheus lexicon runs it over rule files. Names follow the otel lexicon's
+ * `metric-names.ts`, with each config's `prometheus` and
+ * `prometheusremotewrite` exporters' `namespace` and `add_metric_suffixes`.
+ * A component under a renamed type (`span_metrics`, `service_graph`,
+ * `signal_to_metrics`) is read as the built-in it names, through the otel
+ * lexicon's `canonicalTypeOf`.
+ *
+ * Collector configs come from two places. `chant build` gives a lexicon's
+ * checks only that lexicon's output, but every entity in the build, so the
+ * otel lexicon's own config is rebuilt from the build's otel entities with
+ * `buildCollectorConfig`. Any output document shaped like a collector config,
+ * or a Kubernetes ConfigMap holding one, is read as well.
+ */
+
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { buildCollectorConfig } from "@intentius/chant-lexicon-otel/collector";
+import { isOTelComponent } from "@intentius/chant-lexicon-otel/define";
+import { collectorConfigs } from "@intentius/chant-lexicon-otel/lint/post-synth/otel-helpers";
+import {
+  prometheusLabel,
+  prometheusMetricName,
+  serviceGraphNames,
+  spanMetricsNames,
+  SERVICEGRAPH_NAMESPACE,
+  SPANMETRICS_DEFAULT_NAMESPACE,
+  type CollectorMetric,
+  type PrometheusNaming,
+  type SpanMetricsNamingConfig,
+} from "@intentius/chant-lexicon-otel/metric-names";
+import { canonicalTypeOf, type CollectorConfig } from "@intentius/chant-lexicon-otel/model";
+import { parsePromql, selectors } from "./promql-analysis";
+
+type SyntaxNode = NonNullable<ReturnType<typeof parsePromql>>;
+type Obj = Record<string, unknown>;
+
+/** One metric a collector config emits, as Prometheus sees it. */
+export interface EmittedMetric {
+  /** The connector that emits it, e.g. `spanmetrics/genai`. */
+  connector: string;
+  /** The labels a series of it can carry; undefined when the exporter adds every resource attribute. */
+  labels?: Set<string>;
+}
+
+/** What the collector configs in a build emit. */
+export interface CollectorMetrics {
+  /** The name prefixes the connectors own, e.g. `traces_span_metrics_`. */
+  namespaces: string[];
+  /** Every emitted Prometheus name. A histogram is its `_bucket`, `_sum` and `_count` series. */
+  metrics: Map<string, EmittedMetric[]>;
+}
+
+/** Labels the `prometheus` exporter, or the scrape, adds to every series: `job` and `instance` from the resource, and the scope. */
+const ADDED_LABELS = ["job", "instance", "otel_scope_name", "otel_scope_version", "otel_scope_schema_url"];
+
+function asObj(v: unknown): Obj {
+  return v && typeof v === "object" && !Array.isArray(v) ? (v as Obj) : {};
+}
+
+/** A component's type, with a renamed built-in's new name read as the old one (`span_metrics/genai` is `spanmetrics`). */
+function typeOf(kind: "connector" | "exporter", id: string): string {
+  return canonicalTypeOf(kind, id);
+}
+
+function sanitize(name: string): string {
+  return name.replace(/[^A-Za-z0-9_:]/g, "_");
+}
+
+/** The common dotted prefix of a connector's metric names (`genai.tokens` for `genai.tokens.input` and `.output`). */
+function commonPrefix(names: string[]): string | undefined {
+  if (names.length === 0) return undefined;
+  const split = names.map((n) => n.split("."));
+  const out: string[] = [];
+  for (let i = 0; i < split[0].length - 1; i++) {
+    if (split.every((s) => s.length - 1 > i && s[i] === split[0][i])) out.push(split[0][i]);
+    else break;
+  }
+  if (out.length === 0 && names.length === 1 && split[0].length > 1) return split[0].slice(0, -1).join(".");
+  return out.length > 0 ? out.join(".") : undefined;
+}
+
+/** Every collector config in the build: rebuilt from its otel entities, and found in its output. */
+export function buildCollectorConfigs(ctx: PostSynthContext): CollectorConfig[] {
+  const configs = collectorConfigs(ctx).map((f) => f.config);
+  const otel = [...(ctx.entities?.values() ?? [])].filter((e) => e?.lexicon === "otel");
+  if (otel.some(isOTelComponent)) configs.push(buildCollectorConfig(otel).config);
+  return configs;
+}
+
+/** The metrics the collector configs emit; undefined when there are none. */
+export function collectorMetrics(configs: CollectorConfig[]): CollectorMetrics | undefined {
+  if (configs.length === 0) return undefined;
+  const namespaces = new Set<string>();
+  const metrics = new Map<string, EmittedMetric[]>();
+
+  for (const config of configs) {
+    const exporters = Object.entries(asObj(config.exporters)).filter(([id]) => typeOf("exporter", id) === "prometheus" || typeOf("exporter", id) === "prometheusremotewrite");
+    const namings: Array<{ naming: PrometheusNaming; openLabels: boolean }> =
+      exporters.length > 0
+        ? exporters.map(([, c]) => {
+            const e = asObj(c);
+            return {
+              naming: { ...(typeof e.namespace === "string" ? { namespace: e.namespace } : {}), ...(e.add_metric_suffixes === false ? { add_metric_suffixes: false } : {}) },
+              openLabels: asObj(e.resource_to_telemetry_conversion).enabled === true,
+            };
+          })
+        : [{ naming: {}, openLabels: false }];
+
+    for (const { naming, openLabels } of namings) {
+      const prefix = (ns: string) => `${naming.namespace ? `${sanitize(naming.namespace)}_` : ""}${sanitize(ns)}_`;
+      // The two connectors' defaults are theirs in every build that has a collector config.
+      namespaces.add(prefix(SPANMETRICS_DEFAULT_NAMESPACE));
+      namespaces.add(prefix(SERVICEGRAPH_NAMESPACE));
+
+      const add = (connector: string, m: CollectorMetric, extra: string[] = []) => {
+        const labels = openLabels ? undefined : new Set([...m.dimensions.map(prometheusLabel), ...extra.map(prometheusLabel), ...ADDED_LABELS]);
+        // A classic histogram is served as three series whatever add_metric_suffixes says.
+        const series: Array<[string, Set<string> | undefined]> =
+          m.type === "histogram"
+            ? [
+                [`${m.prometheus}_bucket`, labels ? new Set([...labels, "le"]) : undefined],
+                [`${m.prometheus}_sum`, labels],
+                [`${m.prometheus}_count`, labels],
+              ]
+            : [[m.prometheus, labels]];
+        for (const [name, l] of series) {
+          metrics.set(name, [...(metrics.get(name) ?? []), { connector, ...(l ? { labels: l } : {}) }]);
+        }
+      };
+
+      for (const [id, raw] of Object.entries(asObj(config.connectors))) {
+        const c = asObj(raw);
+        switch (typeOf("connector", id)) {
+          case "spanmetrics": {
+            const n = spanMetricsNames(c as SpanMetricsNamingConfig, naming);
+            if (n.namespace !== "") namespaces.add(prefix(n.namespace));
+            for (const m of [n.calls, n.duration, n.events]) if (m) add(id, m);
+            break;
+          }
+          case "servicegraph": {
+            const n = serviceGraphNames(c, naming);
+            for (const m of [n.requests, n.failed, n.serverDuration, n.clientDuration]) add(id, m);
+            break;
+          }
+          case "sum": {
+            const names: string[] = [];
+            for (const signal of ["spans", "spanevents", "metrics", "datapoints", "logs"]) {
+              for (const [name, def] of Object.entries(asObj(c[signal]))) {
+                const attrs = (Array.isArray(asObj(def).attributes) ? (asObj(def).attributes as unknown[]) : []).map((a) => String(asObj(a).key ?? ""));
+                names.push(name);
+                add(id, { name, prometheus: prometheusMetricName(name, "sum", undefined, naming), type: "sum", dimensions: attrs.filter(Boolean) });
+              }
+            }
+            const ns = commonPrefix(names);
+            if (ns) namespaces.add(prefix(ns));
+            break;
+          }
+          case "signaltometrics": {
+            const names: string[] = [];
+            for (const signal of ["spans", "datapoints", "logs", "profiles"]) {
+              for (const def of Array.isArray(c[signal]) ? (c[signal] as unknown[]) : []) {
+                const m = asObj(def);
+                if (typeof m.name !== "string") continue;
+                const type = m.histogram !== undefined || m.exponential_histogram !== undefined ? "histogram" : m.sum !== undefined ? "sum" : undefined;
+                if (!type) continue;
+                const unit = typeof m.unit === "string" ? m.unit : undefined;
+                const attrs = [
+                  ...(Array.isArray(m.attributes) ? (m.attributes as unknown[]) : []),
+                  ...(Array.isArray(m.include_resource_attributes) ? (m.include_resource_attributes as unknown[]) : []),
+                ].map((a) => String(asObj(a).key ?? ""));
+                names.push(m.name);
+                add(id, { name: m.name, prometheus: prometheusMetricName(m.name, type, unit, naming), type, ...(unit ? { unit } : {}), dimensions: attrs.filter(Boolean) });
+              }
+            }
+            const ns = commonPrefix(names);
+            if (ns) namespaces.add(prefix(ns));
+            break;
+          }
+        }
+      }
+    }
+  }
+  return { namespaces: [...namespaces], metrics };
+}
+
+// ── PromQL ──────────────────────────────────────────────────────────
+
+/** Functions that write a label of their own, so an aggregation over them can group by it. */
+const RELABEL = new Set(["label_replace", "label_join"]);
+
+/** Every `by (...)` aggregation in the expression: its labels and the text it aggregates. */
+function byAggregations(top: SyntaxNode, src: string): Array<{ labels: string[]; body: string }> {
+  const out: Array<{ labels: string[]; body: string }> = [];
+  const walk = (n: SyntaxNode) => {
+    if (n.name === "AggregateExpr") {
+      const mod = n.getChild("AggregateModifier");
+      const body = n.getChild("FunctionCallBody");
+      if (mod?.getChild("By") && body) {
+        const labels = (mod.getChild("GroupingLabels")?.getChildren("LabelName") ?? []).map((l) => src.slice(l.from, l.to));
+        out.push({ labels, body: src.slice(body.from + 1, body.to - 1) });
+      }
+    }
+    for (let c = n.firstChild; c; c = c.nextSibling) walk(c);
+  };
+  walk(top);
+  return out;
+}
+
+export interface CollectorMetricIssue {
+  kind: "name" | "label";
+  metric: string;
+  label?: string;
+  message: string;
+}
+
+/**
+ * What a PromQL expression reads under the build's connector namespaces and
+ * the build does not emit: a metric name no connector writes, and a
+ * `by (...)` label none of the aggregated metrics carries. A name outside
+ * every namespace is not read. An aggregation is checked only when every
+ * series under it is an emitted metric and nothing under it adds a label
+ * (`label_replace`, `label_join`). Selectors come from the lexicon's
+ * `promql-analysis.ts`.
+ */
+export function collectorMetricIssues(expr: string, emitted: CollectorMetrics): CollectorMetricIssue[] {
+  const top = parsePromql(expr);
+  if (!top) return [];
+  const issues: CollectorMetricIssue[] = [];
+  const owned = (name: string) => emitted.namespaces.some((p) => name.startsWith(p));
+
+  const seen = new Set<string>();
+  for (const { name } of selectors(expr)) {
+    if (!name || seen.has(name) || !owned(name) || emitted.metrics.has(name)) continue;
+    seen.add(name);
+    const p = emitted.namespaces.filter((x) => name.startsWith(x)).sort((a, b) => b.length - a.length)[0];
+    issues.push({ kind: "name", metric: name, message: `reads ${name}, which no collector config in the build emits under ${p.slice(0, -1)}` });
+  }
+
+  const reported = new Set<string>();
+  for (const { labels, body } of byAggregations(top, expr)) {
+    const read = selectors(body);
+    if (read.length === 0 || read.some((s) => s.within.some((fn) => RELABEL.has(fn)))) continue;
+    const metrics = read.map((s) => (s.name ? emitted.metrics.get(s.name) : undefined));
+    if (!metrics.every((m) => m !== undefined && m.every((e) => e.labels))) continue;
+    const carried = new Set(metrics.flatMap((m) => m!.flatMap((e) => [...e.labels!])));
+    const shown = [...new Set(read.map((s) => s.name!))].join(", ");
+    for (const label of labels) {
+      const key = `${label} ${shown}`;
+      if (carried.has(label) || reported.has(key)) continue;
+      reported.add(key);
+      issues.push({ kind: "label", metric: shown, label, message: `groups ${shown} by ${label}, which is not a dimension the collector config declares for it` });
+    }
+  }
+  return issues;
+}

package/src/composites/composites.test.ts

@@ -184,12 +184,9 @@ describe("the rules an Slo builds", () => {
     expect(sloMetrics(direct).burnRates).toEqual([]);
   });
 
-  test("the same Slo renders inside the rule file promtool accepts", () => {
+  test.skipIf(!hasPromtool)("the same Slo renders inside the rule file promtool accepts", () => {
     const r = promtoolCheckRules(ruleFileYaml([slo.rules]), PROMTOOL);
-    if (!hasPromtool) {
-      expect(r.ran).toBe(false);
-      return;
-    }
+    expect(r.ran).toBe(true);
     expect(r.output).toContain("SUCCESS");
     expect(r.ok).toBe(true);
   });

package/src/import/embedded.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "vitest";
 import { embeddedDocument, type EmbeddedContent } from "@intentius/chant/import/embedded";
 import { prometheusPlugin } from "../plugin";
-import { ruleGroupsImporter } from "./embedded";
+import { alertmanagerImporter, ruleGroupsImporter } from "./embedded";
 
 const GROUPS = [
   { name: "api", rules: [{ alert: "ApiDown", expr: "up{job=\"api\"} == 0", for: "5m" }] },
@@ -25,8 +25,8 @@ const site = (over: Partial<EmbeddedContent>): EmbeddedContent => ({
 });
 
 describe("rule groups embedded in another lexicon's resource (#2962)", () => {
-  test("the plugin registers the importer", () => {
-    expect(prometheusPlugin.embeddedImporters?.()).toEqual([ruleGroupsImporter]);
+  test("the plugin registers the importers", () => {
+    expect(prometheusPlugin.embeddedImporters?.()).toEqual([ruleGroupsImporter, alertmanagerImporter]);
   });
 
   test("matches a PrometheusRule's groups and a rule file held as text; not an alertmanager.yml", () => {
@@ -54,3 +54,52 @@ describe("rule groups embedded in another lexicon's resource (#2962)", () => {
     expect(out.value.bindings).toEqual([{ from: "rules.ts", name: "api" }]);
   });
 });
+
+const ALERTMANAGER = `route:
+  receiver: team
+  routes:
+    - matchers: [severity="critical"]
+      receiver: pager
+      mute_time_intervals: [nights]
+receivers:
+  - name: team
+  - name: pager
+time_intervals:
+  - name: nights
+    time_intervals:
+      - times: [{ start_time: "22:00", end_time: "24:00" }]
+inhibit_rules:
+  - source_matchers: [severity="critical"]
+    target_matchers: [severity="warning"]
+templates: [/etc/alertmanager/*.tmpl]
+`;
+
+describe("an alertmanager.yml embedded in another lexicon's resource (#3031)", () => {
+  const configMap = (text: string) =>
+    site({ hostType: "K8s::Core::ConfigMap", location: 'ConfigMap am data["alertmanager.yml"]', text, document: embeddedDocument(text) });
+
+  test("matches an alertmanager.yml held as text; not a rule file, nor a selected member", () => {
+    expect(alertmanagerImporter.matches(configMap(ALERTMANAGER))).toBe(true);
+    expect(alertmanagerImporter.matches(configMap(RULE_FILE))).toBe(false);
+    expect(alertmanagerImporter.matches(site({ document: { groups: GROUPS }, select: "groups" }))).toBe(false);
+    expect(ruleGroupsImporter.matches(configMap(ALERTMANAGER))).toBe(false);
+  });
+
+  test("becomes alertmanagerYaml over every declaration the standalone import writes", () => {
+    const out = alertmanagerImporter.import(configMap(ALERTMANAGER));
+    expect(out.files.map((f) => f.path)).toEqual(["receivers.ts", "time-intervals.ts", "routes.ts", "inhibit-rules.ts", "settings.ts"]);
+    expect(out.value).toEqual({
+      bindings: [
+        { from: "receivers.ts", name: "team" },
+        { from: "receivers.ts", name: "pager" },
+        { from: "time-intervals.ts", name: "nights" },
+        { from: "routes.ts", name: "root" },
+        { from: "inhibit-rules.ts", name: "inhibitRule1" },
+        { from: "settings.ts", name: "settings" },
+      ],
+      shape: "list",
+      through: { from: "@intentius/chant-lexicon-prometheus", name: "alertmanagerYaml" },
+    });
+    expect(out.warnings).toEqual([]);
+  });
+});

package/src/import/embedded.ts

@@ -1,19 +1,27 @@
 /**
- * Rule groups embedded in another lexicon's resource, for `chant import`
- * (#2962): a k8s `PrometheusRule`'s `spec.groups`, or a rule file held as
- * text in a ConfigMap.
+ * Prometheus and Alertmanager content embedded in another lexicon's
+ * resource, for `chant import`: a k8s `PrometheusRule`'s `spec.groups`, or a
+ * rule file held as text in a ConfigMap (#2962), and an `alertmanager.yml`
+ * held as text in a ConfigMap (#3031).
  *
  * The groups are imported exactly as `chant import rules.yml` would import
  * them, into a directory of its own. `spec.groups` becomes the list of the
  * declared groups (an `Slo`'s by its `rules` member), which the k8s
  * serializer renders as the same groups; a rule file becomes
  * `ruleFileYaml([...])`, the text the prometheus serializer writes.
+ *
+ * An `alertmanager.yml` is imported exactly as `chant import alertmanager.yml`
+ * would import it, and becomes `alertmanagerYaml([...])` over every receiver,
+ * time interval, root route, inhibit rule and settings it declares. The
+ * ConfigMap then holds the config as the serializer writes it: the same
+ * config, with Alertmanager's deprecated spellings rewritten as the
+ * standalone import rewrites them.
  */
 
 import type { EmbeddedContentImporter, EmbeddedImport } from "@intentius/chant/import/embedded";
-import { looksLikeRuleFile } from "../model";
+import { looksLikeAlertmanagerConfig, looksLikeRuleFile } from "../model";
 import { parsePrometheusYaml } from "./parser";
-import { generateRuleFile } from "./generator";
+import { generateAlertmanager, generateRuleFile } from "./generator";
 
 const PACKAGE = "@intentius/chant-lexicon-prometheus";
 
@@ -42,3 +50,27 @@ export const ruleGroupsImporter: EmbeddedContentImporter = {
     };
   },
 };
+
+export const alertmanagerImporter: EmbeddedContentImporter = {
+  what: "an Alertmanager config",
+
+  matches(content) {
+    return content.select === undefined && typeof content.text === "string" && looksLikeAlertmanagerConfig(content.document);
+  },
+
+  import(content): EmbeddedImport {
+    const parsed = parsePrometheusYaml(content.text!);
+    if (parsed.kind !== "alertmanager") throw new Error("this is not an alertmanager.yml");
+    const { files, declarations } = generateAlertmanager(parsed.config);
+    if (declarations.length === 0) throw new Error("the import declared nothing");
+    return {
+      files,
+      value: {
+        bindings: declarations.map((d) => ({ from: d.path, name: d.name })),
+        shape: "list",
+        through: { from: PACKAGE, name: "alertmanagerYaml" },
+      },
+      warnings: parsed.warnings,
+    };
+  },
+};

package/src/import/generator.ts

@@ -381,6 +381,21 @@ function untypedComment(what: string, keys: string[]): string[] {
 
 /** Generate the TypeScript declaring one `alertmanager.yml`. */
 export function generateAlertmanagerFiles(config: AlertmanagerConfig): GeneratedFile[] {
+  return generateAlertmanager(config).files;
+}
+
+/** A declaration an `alertmanager.yml` import exports: its module and variable. */
+export interface AlertmanagerDeclaration {
+  readonly path: string;
+  readonly name: string;
+}
+
+/**
+ * Generate the TypeScript declaring one `alertmanager.yml`, and list every
+ * declaration it exports, module by module (#3031: a ConfigMap holding the
+ * file becomes `alertmanagerYaml([...])` over them).
+ */
+export function generateAlertmanager(config: AlertmanagerConfig): { files: GeneratedFile[]; declarations: AlertmanagerDeclaration[] } {
   const names = new Names([...LEXICON_NAMES, "global", "tracing"]);
   const modules: Module[] = [];
   const receiverVars = new Map<string, { v: string; mod: Module }>();
@@ -558,7 +573,10 @@ export function generateAlertmanagerFiles(config: AlertmanagerConfig): Generated
     mod.exports.push(v);
   }
 
-  return modules.map((m) => ({ path: m.path, content: m.render() }));
+  return {
+    files: modules.map((m) => ({ path: m.path, content: m.render() })),
+    declarations: modules.flatMap((m) => m.exports.map((name) => ({ path: m.path, name }))),
+  };
 }
 
 /** The rule file and `alertmanager.yml` TypeScript generator `chant import` runs. */

package/src/import/testdata/alertmanager-integrations.yml

@@ -50,12 +50,16 @@ route:
 receivers:
   - name: chat
     slack_configs:
-      - channel: '#alerts'
+      - api_url: https://slack.com/api/chat.postMessage
+        channel: '#alerts'
         message_text: '{{ .CommonLabels.alertname }}'
         callback_id: alerts
         image_url: https://example.com/graph.png
         thumb_url: https://example.com/thumb.png
         update_message: true
+        http_config:
+          authorization:
+            credentials_file: /etc/alertmanager/secrets/slack-bot-token
         timeout: 10s
         fields:
           - title: Severity

package/src/index.ts

@@ -66,6 +66,7 @@ export { parseMatchers, matcherMatches, matcher, type Matcher, type MatchOp, typ
 export { checkPromql, PROMQL_GRAMMAR, type PromqlCheck } from "./promql";
 export {
   validateRuleFile,
+  validateRunbookUrls,
   validateAlertmanagerConfig,
   validateSeverityRouting,
   alertSeverities,

package/src/init-templates.test.ts

@@ -24,7 +24,9 @@ describe("init templates", () => {
     try {
       expect(result.errors).toEqual([]);
       expect(result.outputs.get("prometheus")).toBeTruthy();
-      expect(runPostSynthChecks(postSynthChecks, result)).toEqual([]);
+      // As `chant build` reports them: through the default (`recommended`) preset.
+      const recommended = new Set(prometheusPlugin.lintPresets!().recommended);
+      expect(runPostSynthChecks(postSynthChecks, result).filter((d) => recommended.has(d.checkId))).toEqual([]);
       const lint = await lintCommand({ path: join(dir, "src"), format: "stylish", fix: false });
       expect(lint.errorCount + lint.warningCount, lint.output).toBe(0);
     } finally {

package/src/lint/audit-catalog.ts

@@ -9,7 +9,8 @@
  * listed for a reader who meets them in a lint report.
  */
 
-import { auditRule, type RuleMeta } from "@intentius/chant/audit/catalog";
+import { applyLineage, auditRule, type RuleMeta } from "@intentius/chant/audit/catalog";
+import { prometheusAuditLineage } from "./audit-lineage";
 
 function sourceRule(id: string, category: RuleMeta["category"], title: string, remediation: string): RuleMeta {
   return { id, tier: "merge-worthy", fixKind: "guidance", category, title, remediation, yamlBased: false };
@@ -118,6 +119,118 @@ export const prometheusAuditCatalog: Record<string, RuleMeta> = {
     "merge-worthy",
     "correctness",
     "Receiver integration missing its destination or credential",
-    "Set the integration's url, api_url, routing_key or to/smarthost/from (or their *_file and global equivalents).",
+    "Set the integration's destination and credential (url, webhook_url, api_key, routing_key, chat_id, room_id, to/smarthost/from, ...), through its *_file or global equivalent where there is one.",
+  ),
+  PROM210: outputRule(
+    "PROM210",
+    "merge-worthy",
+    "correctness",
+    "Integration or global setting Alertmanager rejects",
+    "Set one of each value and its *_file, and use a value Alertmanager allows (e.g. message_type text or markdown, parse_mode Markdown, MarkdownV2 or HTML).",
+  ),
+  PROM211: outputRule(
+    "PROM211",
+    "report-only",
+    "best-practice",
+    "Alerting rule has no for, or for: 0s",
+    "Set for to how long the condition must hold before the alert fires, e.g. 5m.",
+  ),
+  PROM212: outputRule(
+    "PROM212",
+    "report-only",
+    "best-practice",
+    "Alerting rule has no runbook_url annotation (opt-in)",
+    "Add a runbook_url annotation linking to what the responder should do.",
+  ),
+  PROM213: outputRule(
+    "PROM213",
+    "merge-worthy",
+    "correctness",
+    "Alert expression has no comparison",
+    "Add the condition the alert fires on, e.g. > 0.05, or use absent() for a missing series.",
+  ),
+  PROM214: outputRule(
+    "PROM214",
+    "merge-worthy",
+    "correctness",
+    "Alert template reads a label the expression aggregates away",
+    "Keep the label in the aggregation's by (...), or stop reading it in the template.",
+  ),
+  PROM215: outputRule(
+    "PROM215",
+    "merge-worthy",
+    "correctness",
+    "rate, irate or increase over a name that is not a counter's",
+    "Read a counter (a name ending in _total, _count, _sum or _bucket), or use delta() or deriv() for a gauge.",
+  ),
+  PROM216: outputRule(
+    "PROM216",
+    "merge-worthy",
+    "correctness",
+    "histogram_quantile over a series without _bucket, or without le",
+    "Pass the histogram's _bucket series, and keep le in the aggregation: sum by (le, ...) (rate(x_bucket[5m])).",
+  ),
+  PROM217: outputRule(
+    "PROM217",
+    "report-only",
+    "best-practice",
+    "Recording rule name is not level:metric:operations",
+    "Name the recorded series level:metric:operations, e.g. job:http_requests:rate5m.",
+  ),
+  PROM218: outputRule(
+    "PROM218",
+    "report-only",
+    "best-practice",
+    "Regex matcher needs no regex, or is anchored",
+    'Use = or != for a plain value, and drop ^ and $ from a regex, which Prometheus anchors already (job=~"api|web").',
+  ),
+  PROM219: outputRule("PROM219", "merge-worthy", "correctness", "Alerting rule sets the alertname label", "Remove the alertname label; rename the rule instead."),
+  PROM220: outputRule(
+    "PROM220",
+    "merge-worthy",
+    "security",
+    "Receiver turns off TLS certificate verification",
+    "Remove insecure_skip_verify, and set ca_file to the CA that signed the endpoint's certificate.",
+  ),
+  PROM221: outputRule(
+    "PROM221",
+    "merge-worthy",
+    "security",
+    "SMTP credentials sent with require_tls false",
+    "Set require_tls (or global.smtp_require_tls) to true, or use force_implicit_tls with an SMTPS port.",
+  ),
+  PROM222: outputRule(
+    "PROM222",
+    "merge-worthy",
+    "security",
+    "Credentials sent to an http:// receiver URL",
+    "Point the integration at an https:// URL.",
+  ),
+  PROM223: outputRule(
+    "PROM223",
+    "merge-worthy",
+    "correctness",
+    "repeat_interval is shorter than group_interval",
+    "Set repeat_interval to a multiple of group_interval, or lower group_interval.",
+  ),
+  PROM224: outputRule(
+    "PROM224",
+    "merge-worthy",
+    "correctness",
+    "Inhibit rule matches one alert as source and target, with no equal",
+    "List the labels source and target must share under equal (e.g. alertname, cluster), or make the matchers exclusive.",
+  ),
+  PROM301: outputRule(
+    "PROM301",
+    "merge-worthy",
+    "correctness",
+    "Rule reads a connector metric no collector in the build emits",
+    "Read the name spanMetricsNames(), serviceGraphNames() or genAiMetrics() gives for the declared connector, and group by its declared dimensions, or add the dimension to the connector.",
   ),
 };
+
+/** Post-synth checks the `recommended` lint preset leaves out (#3363); see `prometheusPlugin.lintPresets()`. */
+export const OPT_IN_CHECKS: ReadonlySet<string> = new Set(["PROM212"]);
+
+// Prior art credits live beside the rules in ./audit-lineage.ts (see core audit/prior-art.ts).
+applyLineage(prometheusAuditCatalog, prometheusAuditLineage);