@intentius/chant-lexicon-prometheus 0.124.31 → 0.124.32

package/dist/catalog.js

@@ -0,0 +1,66 @@
+/**
+ * The entity catalog: every class this package exports, keyed by class name.
+ * It feeds the packaged registry (`dist/meta.json`), LSP completions and
+ * hover, and the docs.
+ */
+import { RULE_GROUP_TYPE } from "./rules.js";
+import { PROMETHEUS_CONFIG_TYPE, SCRAPE_CONFIG_TYPE } from "./prometheus-config.js";
+import { INHIBIT_RULE_TYPE, RECEIVER_TYPE, ROUTE_TYPE, SETTINGS_TYPE, TIME_INTERVAL_TYPE } from "./alertmanager.js";
+export const CATALOG = [
+    {
+        className: "RuleGroup",
+        entityType: RULE_GROUP_TYPE,
+        file: "rule file",
+        description: "A group of recording and alerting rules, evaluated together on one interval",
+    },
+    {
+        className: "ScrapeConfig",
+        entityType: SCRAPE_CONFIG_TYPE,
+        file: "prometheus.yml",
+        description: "One scrape job: static or discovered targets, scrape settings, and relabelling",
+    },
+    {
+        className: "PrometheusConfig",
+        entityType: PROMETHEUS_CONFIG_TYPE,
+        file: "prometheus.yml",
+        description: "The global, alerting, rule_files, remote_write, remote_read and otlp sections of prometheus.yml",
+    },
+    {
+        className: "Route",
+        entityType: ROUTE_TYPE,
+        file: "alertmanager.yml",
+        description: "A node in Alertmanager's routing tree: matchers, grouping and timing, and the receiver alerts go to",
+    },
+    {
+        className: "Receiver",
+        entityType: RECEIVER_TYPE,
+        file: "alertmanager.yml",
+        description: "A notification receiver with webhook, email, Slack and PagerDuty integrations",
+    },
+    {
+        className: "InhibitRule",
+        entityType: INHIBIT_RULE_TYPE,
+        file: "alertmanager.yml",
+        description: "Mutes alerts matching target_matchers while an alert matching source_matchers fires",
+    },
+    {
+        className: "TimeInterval",
+        entityType: TIME_INTERVAL_TYPE,
+        file: "alertmanager.yml",
+        description: "A named set of time periods a route can mute or activate on",
+    },
+    {
+        className: "AlertmanagerSettings",
+        entityType: SETTINGS_TYPE,
+        file: "alertmanager.yml",
+        description: "The global block (SMTP, Slack and PagerDuty defaults, resolve_timeout) and the templates list",
+    },
+];
+/** The catalog as a chant lexicon registry, keyed by class name. */
+export function lexiconRegistry() {
+    const out = {};
+    for (const e of [...CATALOG].sort((a, b) => a.className.localeCompare(b.className))) {
+        out[e.className] = { resourceType: e.entityType, kind: "resource", lexicon: "prometheus" };
+    }
+    return out;
+}

package/dist/codegen/docs-cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env tsx
+import { generateDocs } from "./docs.js";
+await generateDocs({ verbose: true });

package/dist/codegen/docs.js

@@ -0,0 +1,105 @@
+/**
+ * Documentation generation for the prometheus lexicon: the generated
+ * reference pages from the core docs pipeline, plus the authored pages in
+ * docs/pages/.
+ */
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { docsPipeline, writeDocsSite } from "@intentius/chant/codegen/docs";
+function serviceFromType(resourceType) {
+    const parts = resourceType.split("::");
+    return parts.length >= 2 ? parts[1] : "Prometheus";
+}
+const overview = `The prometheus lexicon types [Prometheus](https://prometheus.io/) recording and
+alerting rules and [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/)
+routing. \`chant build\` emits the rule file Prometheus loads through
+\`rule_files:\`, and the \`alertmanager.yml\` Alertmanager reads.
+
+\`\`\`ts
+import { RuleGroup, Route, Receiver } from "@intentius/chant-lexicon-prometheus";
+
+export const api = new RuleGroup({
+  name: "api",
+  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: "ApiErrors", expr: "job:http_errors:ratio5m > 0.05", for: "10m", labels: { severity: "page" }, annotations: { summary: "5xx ratio above 5%" } },
+  ],
+});
+
+export const oncall = new Receiver({ name: "oncall", pagerduty_configs: [{ routing_key_file: "/etc/alertmanager/secrets/pd-key" }] });
+export const fallback = new Receiver({ name: "fallback", webhook_configs: [{ url: "http://alert-sink:8080/" }] });
+export const root = new Route({ receiver: fallback, group_by: ["alertname", "job"], routes: [{ matchers: ['severity="page"'], receiver: oncall }] });
+\`\`\`
+
+The same \`RuleGroup\` renders into a Prometheus Operator \`PrometheusRule\`
+through the k8s lexicon, so rules are declared once whichever way Prometheus
+loads them.
+
+The \`Slo\` composite builds a service level objective to a \`RuleGroup\`:
+error ratios per window, the error budget left, and the SRE Workbook's
+multiwindow multi-burn-rate alerts. See [SLOs](./slos/).
+
+The \`GenAiRules\` composite builds recording rules, opt-in alerts and spend
+from a declared price table for the otel lexicon's GenAI collector preset,
+reading every metric name from its \`GenAiMetrics\`. See
+[GenAI Rules](./genai-rules/).
+
+Checks run at build time: PromQL syntax in every \`expr\` (PROM104), unique
+group names (PROM101), valid durations (PROM103), routes that name
+declared receivers (PROM201), and every alert severity routed by some route
+(PROM202). \`promtool check rules\` and \`amtool check-config\` are wrapped as
+helpers for tests and CI, and run when installed.
+
+\`chant import\` turns an existing rule file or \`alertmanager.yml\` into this
+TypeScript, and \`chant build\` on the result gives the file back (see
+Importing Rule Files and alertmanager.yml).
+`;
+const outputFormat = `The prometheus lexicon serializes two files:
+
+- **The rule file**, from every \`RuleGroup\` in the build: \`groups:\`, each
+  with its \`name\`, optional \`interval\`, \`query_offset\`, \`limit\` and
+  \`labels\`, and its \`rules\`. This is the file \`rule_files:\` points at and
+  \`promtool check rules\` reads.
+- **\`alertmanager.yml\`**, from the \`AlertmanagerSettings\`, \`Route\`,
+  \`InhibitRule\`, \`Receiver\` and \`TimeInterval\` entities, in that section
+  order: \`global\`, \`templates\`, \`route\`, \`inhibit_rules\`, \`receivers\`,
+  \`time_intervals\`, \`tracing\`.
+
+The rule file is the primary output when the build declares any rule
+groups, and \`alertmanager.yml\` is written beside it (\`-o dist/rules.yml\`
+also writes \`dist/alertmanager.yml\`). A build with only Alertmanager
+entities emits \`alertmanager.yml\` as its primary output.
+
+- Rules inside a group and child routes keep the order they are written in,
+  which is the order Prometheus evaluates and Alertmanager matches them.
+  Groups, receivers and time intervals, whose order carries no meaning, are
+  sorted by name, so the files are the same however they were built. Keys
+  inside a rule come out in the order Prometheus documents them (\`record\`
+  or \`alert\`, \`expr\`, \`for\`, \`keep_firing_for\`, \`labels\`,
+  \`annotations\`).
+- A route references its receiver and time intervals by name in the output,
+  whether the declaration used the entity or a string.
+- The root route is the one \`Route\` no other route lists as a child.
+- Neither file has a metadata channel, so no ownership marker is stamped.
+`;
+export async function generateDocs(opts) {
+    const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+    const config = {
+        name: "prometheus",
+        displayName: "Prometheus",
+        description: "Typed Prometheus rule groups and Alertmanager routing",
+        distDir: join(pkgDir, "dist"),
+        outDir: join(pkgDir, "docs"),
+        basePath: process.env.DOCS_BASE_PATH ?? "/chant/lexicons/prometheus/",
+        overview,
+        outputFormat,
+        serviceFromType,
+        srcDir: join(pkgDir, "src"),
+        examplesDir: join(pkgDir, "examples"),
+    };
+    const result = docsPipeline(config);
+    writeDocsSite(config, result);
+    if (opts?.verbose) {
+        console.error(`Generated ${result.pages.size} documentation pages`);
+    }
+}

package/dist/codegen/generate-cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env tsx
+/**
+ * CLI entry point for `npm run generate` in lexicon-prometheus.
+ */
+import { generate, writeGeneratedFiles } from "./generate.js";
+const result = await generate({ verbose: true });
+writeGeneratedFiles(result);

package/dist/codegen/generate.js

@@ -0,0 +1,42 @@
+/**
+ * The prometheus lexicon's "generation" step.
+ *
+ * There is no upstream schema to fetch: Prometheus and Alertmanager define
+ * their config files as Go structs and publish no machine-readable schema for
+ * them. The types are written by hand against the releases in
+ * `PROMETHEUS_PIN` (src/pin.ts), and this step derives the registry from the
+ * entity catalog, so the packaged `dist/meta.json` can never disagree with
+ * the classes the package exports.
+ */
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { mkdirSync, writeFileSync } from "fs";
+import { CATALOG, lexiconRegistry } from "../catalog.js";
+/** The packaged types entry re-exports the compiled declarations, which carry every config type. */
+const TYPES_DTS = `// The prometheus lexicon's entity classes and config types are hand-written in
+// src/ and compiled to dist/index.d.ts; this entry re-exports them.
+export * from "../index.js";
+`;
+export async function generate(opts) {
+    const registry = lexiconRegistry();
+    const lexiconJSON = `${JSON.stringify(registry, null, 2)}\n`;
+    if (opts?.verbose) {
+        console.error(`prometheus: ${CATALOG.length} entities (RuleGroup and the Alertmanager kinds)`);
+    }
+    return {
+        lexiconJSON,
+        typesDTS: TYPES_DTS,
+        indexTS: "",
+        resources: CATALOG.length,
+        properties: 0,
+        enums: 0,
+        warnings: [],
+    };
+}
+/** Write the registry to src/generated/lexicon-prometheus.json, for tools that read it from there. */
+export function writeGeneratedFiles(result) {
+    const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+    const dir = join(pkgDir, "src", "generated");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "lexicon-prometheus.json"), result.lexiconJSON);
+}

package/dist/codegen/package.js

@@ -0,0 +1,28 @@
+/**
+ * prometheus lexicon packaging, delegating to core's packagePipeline.
+ */
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
+import { packagePipeline, collectSkills, } from "@intentius/chant/codegen/package";
+import { generate } from "./generate.js";
+import { prometheusSkills } from "../skill-defs.js";
+// src/codegen/package.ts -> src/
+const srcDir = dirname(moduleSourceDir(import.meta.url));
+export async function packageLexicon(opts = {}) {
+    const pkgJson = JSON.parse(readFileSync(join(srcDir, "..", "package.json"), "utf-8"));
+    return packagePipeline({
+        generate: (genOpts) => generate({ verbose: genOpts.verbose, force: genOpts.force }),
+        buildManifest: () => ({
+            name: "prometheus",
+            version: pkgJson.version ?? "0.0.1",
+            chantVersion: ">=0.1.0",
+            namespace: "Prometheus",
+            intrinsics: [],
+            pseudoParameters: {},
+        }),
+        srcDir,
+        collectSkills: () => collectSkills(prometheusSkills()),
+        version: pkgJson.version ?? "0.0.1",
+    }, opts);
+}

package/dist/collector-metrics.js

@@ -0,0 +1,225 @@
+/**
+ * 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 { 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, } from "@intentius/chant-lexicon-otel/metric-names";
+import { canonicalTypeOf } from "@intentius/chant-lexicon-otel/model";
+import { parsePromql, selectors } from "./promql-analysis.js";
+/** 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) {
+    return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+}
+/** 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, id) {
+    return canonicalTypeOf(kind, id);
+}
+function sanitize(name) {
+    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) {
+    if (names.length === 0)
+        return undefined;
+    const split = names.map((n) => n.split("."));
+    const out = [];
+    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) {
+    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) {
+    if (configs.length === 0)
+        return undefined;
+    const namespaces = new Set();
+    const metrics = new Map();
+    for (const config of configs) {
+        const exporters = Object.entries(asObj(config.exporters)).filter(([id]) => typeOf("exporter", id) === "prometheus" || typeOf("exporter", id) === "prometheusremotewrite");
+        const namings = 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) => `${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, m, extra = []) => {
+                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 = 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, 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 = [];
+                        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 : []).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 = [];
+                        for (const signal of ["spans", "datapoints", "logs", "profiles"]) {
+                            for (const def of Array.isArray(c[signal]) ? c[signal] : []) {
+                                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 : []),
+                                    ...(Array.isArray(m.include_resource_attributes) ? m.include_resource_attributes : []),
+                                ].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, src) {
+    const out = [];
+    const walk = (n) => {
+        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;
+}
+/**
+ * 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, emitted) {
+    const top = parsePromql(expr);
+    if (!top)
+        return [];
+    const issues = [];
+    const owned = (name) => emitted.namespaces.some((p) => name.startsWith(p));
+    const seen = new Set();
+    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();
+    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;
+}