@intentius/chant-lexicon-prometheus 0.105.1 → 0.106.3

package/src/schemastore.test.ts

@@ -0,0 +1,142 @@
+/**
+ * SchemaStore's `prometheus.json` as a cross-check on the `prometheus.yml`
+ * model, in tests only (#3365). The schema is vendored as a fixture
+ * (import/testdata/schemastore-prometheus.json) so the tests need no network.
+ *
+ * It is not what the types are generated from: the schema is strict
+ * (`additionalProperties: false`) and behind Prometheus v3.15.0, so a config
+ * Prometheus accepts can fail it. The tests walk a document down the schema
+ * and report every key a strict object does not list. A key in KNOWN_GAPS is
+ * one the schema lacks and the lexicon types; anything else is a mismatch.
+ */
+
+import { describe, expect, test } from "vitest";
+import { load } from "js-yaml";
+import { readFileSync } from "fs";
+import { join } from "path";
+import type { Declarable } from "@intentius/chant/declarable";
+import { prometheusConfigYaml } from "./build";
+import { PROMETHEUS_CONFIG_SECTIONS, TYPED_SD_KINDS } from "./config-model";
+import { PrometheusConfig, ScrapeConfig } from "./prometheus-config";
+
+const testdata = join(import.meta.dirname, "import", "testdata");
+
+type Schema = { [key: string]: unknown };
+const SCHEMA = JSON.parse(readFileSync(join(testdata, "schemastore-prometheus.json"), "utf-8")) as Schema;
+
+/**
+ * What SchemaStore's schema lacks that Prometheus v3.15.0 and the lexicon have,
+ * by the path to the key (`[]` is a list item).
+ */
+const KNOWN_GAPS = [
+  "otlp",
+  "runtime",
+  "scrape_configs.[].kubernetes_sd_configs.[].attach_metadata",
+];
+
+function deref(s: Schema): Schema {
+  let cur = s;
+  while (typeof cur.$ref === "string") {
+    let node: unknown = SCHEMA;
+    for (const part of cur.$ref.replace(/^#\//, "").split("/")) node = (node as Schema)[part];
+    cur = node as Schema;
+  }
+  return cur;
+}
+
+/** The schema and every `oneOf` / `anyOf` / `allOf` branch of it, references resolved. */
+function branches(s: Schema): Schema[] {
+  const self = deref(s);
+  const out = [self];
+  for (const key of ["oneOf", "anyOf", "allOf"]) {
+    for (const b of (self[key] as Schema[] | undefined) ?? []) out.push(...branches(b));
+  }
+  return out;
+}
+
+/** Paths of the keys in `value` that a strict object in `schema` does not list. */
+function unlistedKeys(value: unknown, schema: Schema, path: string[] = [], out: string[] = []): string[] {
+  const bs = branches(schema);
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      for (const b of bs) if (b.items) unlistedKeys(item, b.items as Schema, [...path, "[]"], out);
+    }
+  } else if (typeof value === "object" && value !== null) {
+    const props: Record<string, Schema> = {};
+    let strict = false;
+    const patterns: Array<[RegExp, Schema]> = [];
+    for (const b of bs) {
+      Object.assign(props, (b.properties as Record<string, Schema> | undefined) ?? {});
+      if (b.additionalProperties === false) strict = true;
+      for (const [p, sub] of Object.entries((b.patternProperties as Record<string, Schema> | undefined) ?? {})) {
+        patterns.push([new RegExp(p), sub]);
+      }
+    }
+    for (const [key, v] of Object.entries(value)) {
+      if (key in props) {
+        unlistedKeys(v, props[key], [...path, key], out);
+        continue;
+      }
+      const matched = patterns.filter(([re]) => re.test(key));
+      for (const [, sub] of matched) unlistedKeys(v, sub, [...path, key], out);
+      if (strict && matched.length === 0) out.push([...path, key].join("."));
+    }
+  }
+  return out;
+}
+
+const gapsOf = (yaml: string) => [...new Set(unlistedKeys(load(yaml), SCHEMA))].sort();
+const fixture = (name: string) => readFileSync(join(testdata, name), "utf-8");
+
+describe("SchemaStore prometheus.json as a cross-check (#3365)", () => {
+  test("the vendored schema is SchemaStore's prometheus.json", () => {
+    expect(SCHEMA.$id).toBe("https://json.schemastore.org/prometheus.json");
+    expect(SCHEMA.additionalProperties).toBe(false);
+  });
+
+  test("the full fixture differs from the schema only by the known gaps", () => {
+    expect(gapsOf(fixture("prometheus-full.yml"))).toEqual([...KNOWN_GAPS].sort());
+  });
+
+  test("a config built from the typed sections, without the known gaps, has no key the schema lacks", () => {
+    const yaml = prometheusConfigYaml([
+      new PrometheusConfig({
+        global: { scrape_interval: "15s", scrape_timeout: "10s", evaluation_interval: "30s", external_labels: { cluster: "dev" } },
+        alerting: { alertmanagers: [{ scheme: "http", api_version: "v2", static_configs: [{ targets: ["alertmanager:9093"] }] }] },
+        rule_files: ["rules.yml"],
+        remote_write: [
+          {
+            url: "http://mimir:9009/api/v1/push",
+            queue_config: { capacity: 10000 },
+            write_relabel_configs: [{ source_labels: ["__name__"], regex: "debug_.*", action: "drop" }],
+          },
+        ],
+      }),
+      new ScrapeConfig({
+        job_name: "app",
+        scrape_interval: "5s",
+        params: { format: ["prometheus"] },
+        static_configs: [{ targets: ["app:8080"], labels: { tier: "web" } }],
+        metric_relabel_configs: [{ source_labels: ["__name__"], regex: "go_.*", action: "drop" }],
+      }),
+      new ScrapeConfig({ job_name: "dns", dns_sd_configs: [{ names: ["api.service.internal"], type: "A", port: 9100 }] }),
+    ] as Declarable[]);
+    expect(gapsOf(yaml)).toEqual([]);
+  });
+
+  test("the keys the lexicon adds to the top level are the ones the schema lacks", () => {
+    const schemaKeys = Object.keys(SCHEMA.properties as Record<string, unknown>);
+    // The lexicon types every section the schema has.
+    expect(schemaKeys.filter((k) => !PROMETHEUS_CONFIG_SECTIONS.includes(k))).toEqual([]);
+    // And three the schema predates.
+    expect(PROMETHEUS_CONFIG_SECTIONS.filter((k) => !schemaKeys.includes(k))).toEqual(["otlp", "tracing", "runtime"]);
+  });
+
+  test("every typed discovery kind is one the schema lists; the rest are carried untyped", () => {
+    const definitions = Object.keys(SCHEMA.definitions as Record<string, unknown>);
+    const schemaKinds = definitions.filter((k) => k.endsWith("_sd_configs"));
+    expect(schemaKinds).toHaveLength(24);
+    expect(TYPED_SD_KINDS.filter((k) => !schemaKinds.includes(k))).toEqual([]);
+    expect(schemaKinds.filter((k) => !TYPED_SD_KINDS.includes(k))).toHaveLength(18);
+  });
+});

package/src/serializer.ts

@@ -1,30 +1,35 @@
 /**
  * Prometheus serializer.
  *
- * Emits the two files a Prometheus setup reads:
+ * Emits the 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;
+ * - `prometheus.yml`, from the `PrometheusConfig` and `ScrapeConfig`
+ *   entities, the file `promtool check config` 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.
+ * The first of those a build produces, in that order, is the primary output
+ * and the others are written beside it: the rule file, then `prometheus.yml`
+ * (`PROMETHEUS_FILE`), then `alertmanager.yml`. A project that declares only
+ * rule groups, or only Alertmanager entities, sees no change. 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, scrape jobs,
+ * 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.
+ * None of these files 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";
+import { buildAlertmanagerConfig, buildPrometheusConfig, buildRuleFile, emitYaml } from "./build";
+
+/** The filename `prometheus.yml` is written under when it sits beside a rule file or `alertmanager.yml`. */
+export const PROMETHEUS_FILE = "prometheus.yml";
 
 /** The filename `alertmanager.yml` is written under when it sits beside a rule file. */
 export const ALERTMANAGER_FILE = "alertmanager.yml";
@@ -35,20 +40,25 @@ export const prometheusSerializer: Serializer = {
 
   serialize(entities: Map<string, Declarable>, _outputs?: LexiconOutput[]): string | SerializerResult {
     const rules = buildRuleFile(entities);
+    const prom = buildPrometheusConfig(entities);
     const am = buildAlertmanagerConfig(entities);
-    const hasRules = rules.groups.length > 0;
-    const hasAm = am.count > 0;
-    const warnings = am.warnings;
+    const warnings = [...prom.warnings, ...am.warnings];
+
+    // The files this build writes, in the order of the primary: the rule file,
+    // then prometheus.yml, then alertmanager.yml.
+    const out: Array<[string, string]> = [];
+    if (rules.groups.length > 0) out.push(["rules", emitYaml(rules.config)]);
+    if (prom.count > 0) out.push([PROMETHEUS_FILE, emitYaml(prom.config)]);
+    if (am.count > 0) out.push([ALERTMANAGER_FILE, emitYaml(am.config)]);
 
-    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 };
+    if (out.length === 0) return "";
+    if (out.length === 1) {
+      return warnings.length === 0 ? out[0][1] : { primary: out[0][1], warnings };
     }
+    const [[, primary], ...rest] = out;
     return {
-      primary: emitYaml(rules.config),
-      files: { [ALERTMANAGER_FILE]: emitYaml(am.config) },
+      primary,
+      files: Object.fromEntries(rest),
       ...(warnings.length > 0 ? { warnings } : {}),
     };
   },

package/src/tools.ts

@@ -1,5 +1,5 @@
 /**
- * `promtool check rules` and `amtool check-config`, when they are installed.
+ * `promtool check rules`, `promtool check config` and `amtool check-config`, when they are installed.
  *
  * The lexicon's own checks cover structure, references and PromQL syntax.
  * The upstream tools add what only Prometheus and Alertmanager know (PromQL
@@ -10,9 +10,9 @@
  */
 
 import { spawnSync } from "child_process";
-import { mkdtempSync, rmSync, writeFileSync } from "fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "fs";
 import { tmpdir } from "os";
-import { join } from "path";
+import { dirname, join } from "path";
 
 export interface ToolResult {
   /** False when the binary isn't installed; `ok` and `output` are then meaningless. */
@@ -46,6 +46,34 @@ export function promtoolCheckRules(yaml: string, bin = process.env.PROMTOOL ?? "
   return runOnText(bin, (f) => ["check", "rules", f], "rules.yml", yaml);
 }
 
+/**
+ * Run `promtool check config` over `prometheus.yml` text. The config is written
+ * as `prometheus.yml` in a directory of its own, and `files` (path relative to
+ * that directory to contents) are written beside it: `check config` also reads
+ * the rule files, certificates and credentials files the config names, so a
+ * config that names any needs them here. `bin` defaults to `promtool` on PATH.
+ */
+export function promtoolCheckConfig(
+  yaml: string,
+  files: Record<string, string> = {},
+  bin = process.env.PROMTOOL ?? "promtool",
+): ToolResult {
+  if (!hasTool(bin)) return { ran: false, ok: false, output: "" };
+  const dir = mkdtempSync(join(tmpdir(), "chant-prometheus-"));
+  try {
+    writeFileSync(join(dir, "prometheus.yml"), yaml);
+    for (const [path, content] of Object.entries(files)) {
+      const target = join(dir, path);
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, content);
+    }
+    const r = spawnSync(bin, ["check", "config", "prometheus.yml"], { cwd: dir, encoding: "utf-8" });
+    return { ran: true, ok: r.status === 0, output: `${r.stdout ?? ""}${r.stderr ?? ""}` };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
 /**
  * Run `promtool test rules` over rule file YAML and a unit-test file for it.
  * The test file's `rule_files:` should name `rules.yml`, which is where the

package/src/validate-config.ts

@@ -66,7 +66,8 @@ export type PrometheusIssueCode =
   | "PROM221"
   | "PROM222"
   | "PROM223"
-  | "PROM224";
+  | "PROM224"
+  | "PROM225";
 
 export interface PrometheusIssue {
   code: PrometheusIssueCode;

package/src/validate-relabel.ts

@@ -0,0 +1,53 @@
+/**
+ * PROM225: a `labeldrop` or `labelkeep` relabel step carries a field the
+ * action does not take.
+ *
+ * Both actions match `regex` against label names, so `source_labels`,
+ * `separator`, `target_label`, `modulus` and `replacement` have nothing to
+ * act on. Prometheus rejects the file when it loads it (the importer's
+ * fixture was fixed for the same reason, #3537).
+ */
+
+import type { PrometheusConfigFile } from "./config-model";
+import type { PrometheusIssue } from "./validate-config";
+
+const RELABEL_KEYS = new Set(["relabel_configs", "metric_relabel_configs", "alert_relabel_configs", "write_relabel_configs"]);
+const FOREIGN_FIELDS = ["source_labels", "separator", "target_label", "modulus", "replacement"] as const;
+
+/** Every relabel step in a `prometheus.yml`, with where it sits, e.g. `scrape_configs[0].relabel_configs[1]`. */
+function relabelSteps(node: unknown, path: string, out: Array<{ path: string; step: Record<string, unknown> }>): void {
+  if (Array.isArray(node)) {
+    node.forEach((v, i) => relabelSteps(v, `${path}[${i}]`, out));
+    return;
+  }
+  if (typeof node !== "object" || node === null) return;
+  for (const [key, value] of Object.entries(node)) {
+    const here = path ? `${path}.${key}` : key;
+    if (RELABEL_KEYS.has(key) && Array.isArray(value)) {
+      value.forEach((step, i) => {
+        if (typeof step === "object" && step !== null && !Array.isArray(step)) out.push({ path: `${here}[${i}]`, step: step as Record<string, unknown> });
+      });
+    } else {
+      relabelSteps(value, here, out);
+    }
+  }
+}
+
+/** PROM225 over one `prometheus.yml`. */
+export function validateRelabelFields(config: PrometheusConfigFile): PrometheusIssue[] {
+  const steps: Array<{ path: string; step: Record<string, unknown> }> = [];
+  relabelSteps(config, "", steps);
+  const issues: PrometheusIssue[] = [];
+  for (const { path, step } of steps) {
+    if (step.action !== "labeldrop" && step.action !== "labelkeep") continue;
+    const extra = FOREIGN_FIELDS.filter((f) => step[f] !== undefined);
+    if (extra.length === 0) continue;
+    issues.push({
+      code: "PROM225",
+      severity: "error",
+      subject: path,
+      message: `${path}: a ${String(step.action)} step matches regex against label names and takes no ${extra.join(", ")}; Prometheus rejects the file, so remove ${extra.length === 1 ? "it" : "them"}`,
+    });
+  }
+  return issues;
+}

package/src/validate.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, test } from "vitest";
+import { validate } from "./validate";
+import { hasTool } from "./tools";
+
+const PROMTOOL = hasTool(process.env.PROMTOOL ?? "promtool");
+
+describe("the lexicon's validate()", () => {
+  test("passes, and says whether promtool check config ran", async () => {
+    const result = await validate();
+    expect(result.checks.filter((c) => !c.ok)).toEqual([]);
+    expect(result.success).toBe(true);
+    const check = result.checks.find((c) => c.name.startsWith("promtool-check-config"));
+    expect(check).toBeDefined();
+    if (PROMTOOL) expect(check!.name).toBe("promtool-check-config");
+    else expect(check!.name).toContain("skipped");
+  });
+});

package/src/validate.ts

@@ -1,20 +1,23 @@
 /**
  * Validate the prometheus lexicon's own artifacts: every class is in the
  * registry, every entity constructs and serializes, and a sample rule file
- * and Alertmanager config pass the lexicon's own checks.
+ * and Alertmanager config pass the lexicon's own checks, and `promtool check
+ * config` accepts a sample `prometheus.yml` when `promtool` is installed.
  */
 
 import type { ValidateCheck, ValidateResult } from "@intentius/chant/codegen/validate";
 import { CATALOG, lexiconRegistry } from "./catalog";
 import { RuleGroup } from "./rules";
 import { AlertmanagerSettings, InhibitRule, Receiver, Route, TimeInterval } from "./alertmanager";
-import { buildAlertmanagerConfig, buildRuleFile } from "./build";
+import { buildAlertmanagerConfig, buildRuleFile, prometheusConfigYaml, ruleFileYaml } from "./build";
+import { PrometheusConfig, ScrapeConfig } from "./prometheus-config";
+import { hasTool, promtoolCheckConfig } from "./tools";
 import { validateAlertmanagerConfig, validateRuleFile } from "./validate-config";
 
 export type { ValidateCheck, ValidateResult } from "@intentius/chant/codegen/validate";
 
 /** Every entity class the package must keep exporting. */
-export const REQUIRED_NAMES = ["RuleGroup", "Route", "Receiver", "InhibitRule", "TimeInterval", "AlertmanagerSettings"];
+export const REQUIRED_NAMES = ["RuleGroup", "ScrapeConfig", "PrometheusConfig", "Route", "Receiver", "InhibitRule", "TimeInterval", "AlertmanagerSettings"];
 
 export async function validate(): Promise<ValidateResult> {
   const checks: ValidateCheck[] = [];
@@ -62,5 +65,26 @@ export async function validate(): Promise<ValidateResult> {
       : { name: "alertmanager-roundtrip", ok: false, error: amIssues.map((i) => i.message).join("; ") },
   );
 
+  // `promtool check config` over a sample prometheus.yml, with the rule file it names beside it.
+  const promtool = process.env.PROMTOOL ?? "promtool";
+  if (!hasTool(promtool)) {
+    checks.push({ name: `promtool-check-config (skipped: ${promtool} is not installed)`, ok: true });
+  } else {
+    const config = prometheusConfigYaml([
+      new PrometheusConfig({
+        global: { scrape_interval: "15s", evaluation_interval: "30s" },
+        rule_files: ["rules.yml"],
+        alerting: { alertmanagers: [{ static_configs: [{ targets: ["alertmanager:9093"] }] }] },
+      }),
+      new ScrapeConfig({ job_name: "prometheus", static_configs: [{ targets: ["localhost:9090"] }] }),
+    ]);
+    const r = promtoolCheckConfig(config, { "rules.yml": ruleFileYaml([group]) }, promtool);
+    checks.push(
+      r.ok
+        ? { name: "promtool-check-config", ok: true }
+        : { name: "promtool-check-config", ok: false, error: r.output.trim() || "promtool check config failed" },
+    );
+  }
+
   return { success: checks.every((c) => c.ok), checks };
 }