@intentius/chant-lexicon-otel 0.124.30 → 0.124.32

package/dist/lint/post-synth/otel120.js

@@ -0,0 +1,13 @@
+/**
+ * OTEL120: A component in the collector config holds a literal credential
+ *
+ * OTEL002's check over the emitted or imported config, with the same key pattern (`authorization`, `api-key`, `api_key`, `token`, `password`, `secret`, `key_pem`, `x-honeycomb-team`). A value containing `${` is a reference the collector expands at start-up, and a key ending in `_file` names a path. This catches what OTEL002 can't see: a config brought in by `chant import`, or one inside a ConfigMap.
+ */
+import { configDiagnostics } from "./otel-helpers.js";
+export const otel120 = {
+    id: "OTEL120",
+    description: "A component in the collector config holds a literal credential",
+    check(ctx) {
+        return configDiagnostics(ctx, "OTEL120");
+    },
+};

package/dist/lint/post-synth/otel121.js

@@ -0,0 +1,13 @@
+/**
+ * OTEL121: An exporter sends a credential over plaintext
+ *
+ * A started exporter sends a credential header (`authorization`, `api-key` and the other OTEL002 keys) or a credential key such as `api_key` or `token` to a non-loopback endpoint that is `http://`, or that has `tls.insecure: true` and isn't `https://`.
+ */
+import { configDiagnostics } from "./otel-helpers.js";
+export const otel121 = {
+    id: "OTEL121",
+    description: "An exporter sends a credential over plaintext",
+    check(ctx) {
+        return configDiagnostics(ctx, "OTEL121");
+    },
+};

package/dist/lint/post-synth/otel122.js

@@ -0,0 +1,13 @@
+/**
+ * OTEL122: zpages or pprof listens on a non-loopback address
+ *
+ * zpages serves span samples and pipeline internals, and pprof serves profiles, with no authentication. A started one bound to anything but loopback (`0.0.0.0`, a pod IP, an `${env:...}` host) is reachable by whoever reaches that address. `health_check` is not reported: it serves only a status, and a kubelet probe needs it on the pod IP.
+ */
+import { configDiagnostics } from "./otel-helpers.js";
+export const otel122 = {
+    id: "OTEL122",
+    description: "zpages or pprof listens on a non-loopback address",
+    check(ctx) {
+        return configDiagnostics(ctx, "OTEL122");
+    },
+};

package/dist/lint/post-synth/otel123.js

@@ -0,0 +1,13 @@
+/**
+ * OTEL123: A debug exporter at verbosity detailed shares a pipeline with a real exporter
+ *
+ * `verbosity: detailed` writes every record, attributes and bodies included, to the collector's log. In a pipeline that also sends to a backend, that copies the backend's data, sensitive values included, to wherever the collector's logs go.
+ */
+import { configDiagnostics } from "./otel-helpers.js";
+export const otel123 = {
+    id: "OTEL123",
+    description: "A debug exporter at verbosity detailed shares a pipeline with a real exporter",
+    check(ctx) {
+        return configDiagnostics(ctx, "OTEL123");
+    },
+};

package/dist/lint/post-synth/otel124.js

@@ -0,0 +1,13 @@
+/**
+ * OTEL124: A remote exporter has its sending queue or retries turned off
+ *
+ * A started exporter with a non-loopback endpoint and `sending_queue.enabled: false` blocks the pipeline when the backend is slow; with `retry_on_failure.enabled: false` it drops a failed request's data.
+ */
+import { configDiagnostics } from "./otel-helpers.js";
+export const otel124 = {
+    id: "OTEL124",
+    description: "A remote exporter has its sending queue or retries turned off",
+    check(ctx) {
+        return configDiagnostics(ctx, "OTEL124");
+    },
+};

package/dist/lint/post-synth/otel125.js

@@ -0,0 +1,13 @@
+/**
+ * OTEL125: A pipeline sends to a remote otlp or otlphttp exporter without batching
+ *
+ * No `batch` processor in the pipeline, and the `otlp` or `otlphttp` exporter (non-loopback endpoint) sets no `sending_queue.batch`. At v0.130.0 neither exporter batches by default, so each small request goes out on its own. Other exporters may batch themselves and are not checked.
+ */
+import { configDiagnostics } from "./otel-helpers.js";
+export const otel125 = {
+    id: "OTEL125",
+    description: "A pipeline sends to a remote otlp or otlphttp exporter without batching",
+    check(ctx) {
+        return configDiagnostics(ctx, "OTEL125");
+    },
+};

package/dist/lint/post-synth/otel126.js

@@ -0,0 +1,13 @@
+/**
+ * OTEL126: k8sattributes extracts a metadata field it does not support
+ *
+ * Each name in a `k8sattributes` processor's `extract.metadata` must be one `Config.Validate` accepts at collector-contrib v0.130.0 (`K8S_ATTRIBUTES_METADATA`); the collector refuses any other.
+ */
+import { configDiagnostics } from "./otel-helpers.js";
+export const otel126 = {
+    id: "OTEL126",
+    description: "k8sattributes extracts a metadata field it does not support",
+    check(ctx) {
+        return configDiagnostics(ctx, "OTEL126");
+    },
+};

package/dist/lint/post-synth/otel127.js

@@ -0,0 +1,13 @@
+/**
+ * OTEL127: resourcedetection lists a detector that does not exist
+ *
+ * Each name in a started `resourcedetection` processor's `detectors` must be one the processor registers at collector-contrib v0.130.0 (`RESOURCE_DETECTORS`); any other fails the processor's build and the collector exits.
+ */
+import { configDiagnostics } from "./otel-helpers.js";
+export const otel127 = {
+    id: "OTEL127",
+    description: "resourcedetection lists a detector that does not exist",
+    check(ctx) {
+        return configDiagnostics(ctx, "OTEL127");
+    },
+};

package/dist/lint/rules/component-id-syntax.js

@@ -0,0 +1,66 @@
+import { ts } from "@intentius/chant/lint/typescript";
+import { isComponentId } from "../../model.js";
+import { calleeName, COMPONENT_CLASS, literalText, position, propertyName } from "./otel-ast.js";
+/**
+ * OTEL001: a component id or instance name the collector can't parse.
+ *
+ * A pipeline may name a component by id string (`"otlp/backend"`), and every
+ * component takes an instance `name`. Both end up in the collector's
+ * `type[/name]` syntax, where a space, an empty name or a stray `/` is a
+ * config error at collector start. This catches the literal cases in source,
+ * before a build: a string in a `Pipeline`'s receivers, processors or
+ * exporters that isn't `type` or `type/name`, and a component `name` that is
+ * empty, contains whitespace or starts with `/`.
+ */
+export const componentIdSyntaxRule = {
+    id: "OTEL001",
+    severity: "error",
+    category: "correctness",
+    description: "Collector component id or instance name is not valid type[/name] syntax",
+    check(context) {
+        const diagnostics = [];
+        const source = context.sourceFile;
+        const flag = (node, message) => {
+            diagnostics.push({ ruleId: "OTEL001", severity: "error", message, file: context.filePath, ...position(source, node) });
+        };
+        const visit = (node) => {
+            if (ts.isNewExpression(node) || ts.isCallExpression(node)) {
+                const name = calleeName(node);
+                const arg = node.arguments?.[0];
+                if (name && arg && ts.isObjectLiteralExpression(arg)) {
+                    if (name === "Pipeline") {
+                        for (const prop of arg.properties) {
+                            const key = propertyName(prop);
+                            if (key !== "receivers" && key !== "processors" && key !== "exporters")
+                                continue;
+                            const init = prop.initializer;
+                            if (!ts.isArrayLiteralExpression(init))
+                                continue;
+                            for (const el of init.elements) {
+                                const text = literalText(el);
+                                if (text !== undefined && !isComponentId(text)) {
+                                    flag(el, `"${text}" in ${key} is not a collector component id; write type or type/name, e.g. "otlp" or "otlp/backend"`);
+                                }
+                            }
+                        }
+                    }
+                    if (name === "Pipeline" || COMPONENT_CLASS.test(name)) {
+                        for (const prop of arg.properties) {
+                            if (propertyName(prop) !== "name")
+                                continue;
+                            const text = literalText(prop.initializer);
+                            if (text === undefined)
+                                continue;
+                            if (text === "" || /\s/.test(text) || text.startsWith("/")) {
+                                flag(prop, `instance name "${text}" makes an invalid id; a name is non-empty, has no whitespace and does not start with "/"`);
+                            }
+                        }
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(source);
+        return diagnostics;
+    },
+};

package/dist/lint/rules/index.js

@@ -0,0 +1,6 @@
+import { componentIdSyntaxRule } from "./component-id-syntax.js";
+import { literalCredentialRule } from "./literal-credential.js";
+export { componentIdSyntaxRule } from "./component-id-syntax.js";
+export { literalCredentialRule } from "./literal-credential.js";
+/** All lint rules provided by this lexicon (imported by plugin.ts's lintRules()). */
+export const rules = [componentIdSyntaxRule, literalCredentialRule];

package/dist/lint/rules/literal-credential.js

@@ -0,0 +1,91 @@
+import { ts } from "@intentius/chant/lint/typescript";
+import { calleeName, COMPONENT_CLASS, literalText, position, propertyName } from "./otel-ast.js";
+// Shared with OTEL120, which applies the same check to the emitted YAML.
+import { SECRET_KEY } from "../../config-hygiene.js";
+/**
+ * OTEL002: a credential written as a literal in a component's config.
+ *
+ * Exporters authenticate with headers (`authorization`, `api-key`, vendor
+ * headers) or keys (`api_key`, `password`, `key_pem`). A literal value there
+ * is a secret in the repository and in the emitted YAML. The collector reads
+ * `${env:NAME}` and `${file:/path}` at start-up, so the declaration never
+ * needs the value itself. Any string containing `${` is treated as such a
+ * reference, and keys ending in `_file` name a path and are left alone.
+ */
+export const literalCredentialRule = {
+    id: "OTEL002",
+    severity: "error",
+    category: "security",
+    description: "Collector credential declared as a literal instead of ${env:...}",
+    check(context) {
+        const diagnostics = [];
+        const source = context.sourceFile;
+        // `const x = { ... }` (or `[...]`, or a string) anywhere in the file, so a
+        // config value lifted out of the constructor into a named const, the way
+        // COR001 asks, is scanned where it is used.
+        const consts = new Map();
+        const collect = (node) => {
+            if (ts.isVariableDeclarationList(node) && node.flags & ts.NodeFlags.Const) {
+                for (const d of node.declarations) {
+                    if (ts.isIdentifier(d.name) && d.initializer)
+                        consts.set(d.name.text, d.initializer);
+                }
+            }
+            ts.forEachChild(node, collect);
+        };
+        collect(source);
+        const flag = (key, node) => diagnostics.push({
+            ruleId: "OTEL002",
+            severity: "error",
+            message: `\`${key}\` is a literal credential; write "\${env:NAME}" (or "\${file:/path}") and let the collector read it at start-up`,
+            file: context.filePath,
+            ...position(source, node),
+        });
+        const scanned = new Set();
+        const scanValue = (key, value) => {
+            let init = value;
+            if (ts.isIdentifier(init)) {
+                const resolved = consts.get(init.text);
+                if (!resolved)
+                    return;
+                init = resolved;
+            }
+            if (ts.isObjectLiteralExpression(init) || ts.isArrayLiteralExpression(init)) {
+                if (scanned.has(init))
+                    return;
+                scanned.add(init);
+                if (ts.isObjectLiteralExpression(init))
+                    scan(init);
+                else
+                    for (const el of init.elements)
+                        scanValue(undefined, el);
+                return;
+            }
+            if (!key || !SECRET_KEY.test(key) || /_file$/i.test(key))
+                return;
+            const text = literalText(init);
+            if (text === undefined || text === "" || text.includes("${"))
+                return;
+            flag(key, value);
+        };
+        const scan = (obj) => {
+            for (const prop of obj.properties) {
+                if (ts.isShorthandPropertyAssignment(prop))
+                    scanValue(prop.name.text, prop.name);
+                else if (ts.isPropertyAssignment(prop))
+                    scanValue(propertyName(prop), prop.initializer);
+            }
+        };
+        const visit = (node) => {
+            if (ts.isNewExpression(node) || ts.isCallExpression(node)) {
+                const name = calleeName(node);
+                const arg = node.arguments?.[0];
+                if (name && COMPONENT_CLASS.test(name) && arg && ts.isObjectLiteralExpression(arg))
+                    scan(arg);
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(source);
+        return diagnostics;
+    },
+};

package/dist/lint/rules/otel-ast.js

@@ -0,0 +1,30 @@
+import { ts } from "@intentius/chant/lint/typescript";
+/** The constructor name of a `new X(...)` or `X(...)` expression, if it is a plain or dotted name. */
+export function calleeName(node) {
+    const callee = node.expression;
+    if (ts.isIdentifier(callee))
+        return callee.text;
+    if (ts.isPropertyAccessExpression(callee))
+        return callee.name.text;
+    return undefined;
+}
+/** Built-in and custom collector component classes follow this naming, e.g. `OtlpExporter`. */
+export const COMPONENT_CLASS = /(Receiver|Processor|Exporter|Extension)$/;
+/** A property's key as text, for identifier and string-literal keys. */
+export function propertyName(prop) {
+    if (!ts.isPropertyAssignment(prop))
+        return undefined;
+    if (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name))
+        return prop.name.text;
+    return undefined;
+}
+/** The text of a string literal or substitution-free template, else undefined. */
+export function literalText(node) {
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+        return node.text;
+    return undefined;
+}
+export function position(source, node) {
+    const { line, character } = source.getLineAndCharacterOfPosition(node.getStart(source));
+    return { line: line + 1, column: character + 1 };
+}

package/dist/lsp/completions.js

@@ -0,0 +1,11 @@
+import { LexiconIndex, lexiconCompletions } from "@intentius/chant/lsp/lexicon-providers";
+import { lexiconRegistry } from "../catalog.js";
+let cachedIndex = null;
+function getIndex() {
+    cachedIndex ?? (cachedIndex = new LexiconIndex(lexiconRegistry()));
+    return cachedIndex;
+}
+/** Completions for the otel entity classes: the built-in components, Pipeline and Service. */
+export function completions(ctx) {
+    return lexiconCompletions(ctx, getIndex(), "OpenTelemetry Collector entity");
+}

package/dist/lsp/hover.js

@@ -0,0 +1,23 @@
+import { LexiconIndex, lexiconHover } from "@intentius/chant/lsp/lexicon-providers";
+import { BUILTIN_CATALOG, lexiconRegistry } from "../catalog.js";
+import { COLLECTOR_PIN } from "../define.js";
+let cachedIndex = null;
+function getIndex() {
+    cachedIndex ?? (cachedIndex = new LexiconIndex(lexiconRegistry()));
+    return cachedIndex;
+}
+/** Hover for otel entity classes: what the component does and its collector id. */
+export function hover(ctx) {
+    return lexiconHover(ctx, getIndex(), resourceHover);
+}
+function resourceHover(className, entry) {
+    const cat = BUILTIN_CATALOG.find((c) => c.className === className);
+    const lines = [`**${className}**`, "", `otel type: \`${entry.resourceType}\``];
+    if (cat?.description)
+        lines.push("", cat.description);
+    if (cat?.type) {
+        lines.push("", `Collector id \`${cat.type}\`, or \`${cat.type}/<name>\` with \`name\` set. ` +
+            `Config typed against ${COLLECTOR_PIN.source} ${COLLECTOR_PIN.version}.`);
+    }
+    return { contents: lines.join("\n") };
+}

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "otel",
-  "version": "0.124.30",
+  "version": "0.124.32",
   "chantVersion": ">=0.1.0",
   "namespace": "OTel",
   "intrinsics": [],

package/dist/metric-names.js

@@ -0,0 +1,244 @@
+/**
+ * The metric names a collector emits, as the `prometheus` exporter serves
+ * them: `spanMetricsNames()` for a `spanmetrics` connector, and the naming
+ * rules `genAiMetrics()` uses too.
+ *
+ * A dashboard or an SLO reads names from here instead of repeating them, so
+ * renaming the connector's namespace (or the exporter's) moves every query
+ * built from it.
+ *
+ * Naming follows the collector's Prometheus translation at `COLLECTOR_PIN`
+ * with the exporter's defaults: `.` and any other character Prometheus does
+ * not allow become `_`; counters take `_total`; a unit becomes a suffix
+ * (`ms` is `_milliseconds`, `s` is `_seconds`); the exporter's `namespace`
+ * is a prefix joined with `_`; `add_metric_suffixes: false` drops the
+ * suffixes. Attribute names become label names the same way
+ * (`service.name` is `service_name`).
+ *
+ * This module holds types and string functions only, so a lexicon that
+ * builds queries from it does not load the collector components.
+ */
+import { canonicalComponentType } from "./model.js";
+/** The four dimensions spanmetrics puts on every metric unless `exclude_dimensions` names them. */
+export const SPANMETRICS_DEFAULT_DIMENSIONS = Object.freeze(["service.name", "span.name", "span.kind", "status.code"]);
+/** The spanmetrics namespace when the connector sets none. */
+export const SPANMETRICS_DEFAULT_NAMESPACE = "traces.span.metrics";
+/** The `status.code` value of a span that ended in error: the value an error-ratio query selects. */
+export const SPAN_STATUS_ERROR = "STATUS_CODE_ERROR";
+/** The Prometheus unit words for the units collector components use. */
+const UNIT_WORDS = {
+    ms: "milliseconds",
+    s: "seconds",
+    us: "microseconds",
+    ns: "nanoseconds",
+    By: "bytes",
+    "1": "ratio",
+};
+/** An attribute name as a Prometheus label: `service.name` is `service_name`. */
+export function prometheusLabel(attribute) {
+    const label = attribute.replace(/[^A-Za-z0-9_]/g, "_");
+    return /^[0-9]/.test(label) ? `key_${label}` : label;
+}
+/**
+ * An OTLP metric name as the `prometheus` exporter serves it.
+ *
+ * @param type `sum` (a monotonic counter, `_total`) or `histogram`.
+ * @param unit The metric's unit, e.g. `ms`. Units in braces (`{call}`) add nothing.
+ */
+export function prometheusMetricName(name, type, unit, naming = {}) {
+    let out = name.replace(/[^A-Za-z0-9_:]/g, "_");
+    if (naming.namespace)
+        out = `${naming.namespace.replace(/[^A-Za-z0-9_:]/g, "_")}_${out}`;
+    if (naming.add_metric_suffixes === false)
+        return out;
+    const word = unit && !unit.startsWith("{") ? (UNIT_WORDS[unit] ?? unit.replace(/[^A-Za-z0-9_:]/g, "_")) : undefined;
+    if (word && !out.endsWith(`_${word}`))
+        out = `${out}_${word}`;
+    if (type === "sum" && !out.endsWith("_total"))
+        out = `${out}_total`;
+    return out;
+}
+function configOf(connector) {
+    const d = connector;
+    if (typeof d.componentType === "string") {
+        if (canonicalComponentType("connector", d.componentType) !== "spanmetrics")
+            throw new Error(`spanMetricsNames: expected a spanmetrics connector, got ${d.componentType}`);
+        return (d.props ?? {});
+    }
+    return connector;
+}
+/**
+ * The Prometheus names of the metrics a `spanmetrics` connector emits, read
+ * from its declaration: its namespace, dimensions and histogram unit, and
+ * optionally the `prometheus` exporter's namespace and suffix setting.
+ *
+ * @example
+ * ```ts
+ * const spans = new SpanMetricsConnector({ namespace: "shop", histogram: { unit: "s" } });
+ * spanMetricsNames(spans).calls.prometheus;    // "shop_calls_total"
+ * spanMetricsNames(spans).duration!.prometheus; // "shop_duration_seconds"
+ * ```
+ */
+export function spanMetricsNames(connector, exporter) {
+    const c = configOf(connector);
+    const naming = exporter && "props" in exporter && typeof exporter.props === "object" ? exporter.props : (exporter ?? {});
+    const namespace = c.namespace ?? SPANMETRICS_DEFAULT_NAMESPACE;
+    const metricName = (n) => (namespace === "" ? n : `${namespace}.${n}`);
+    const excluded = new Set(c.exclude_dimensions ?? []);
+    const defaults = SPANMETRICS_DEFAULT_DIMENSIONS.filter((d) => !excluded.has(d));
+    const names = (extra) => (extra ?? []).map((d) => d.name);
+    const common = [...defaults, ...names(c.dimensions)];
+    const metric = (n, type, dims, unit) => ({
+        name: metricName(n),
+        prometheus: prometheusMetricName(metricName(n), type, unit, naming),
+        type,
+        ...(unit ? { unit } : {}),
+        dimensions: dims,
+    });
+    const label = (attr) => (defaults.includes(attr) ? prometheusLabel(attr) : undefined);
+    const labels = {};
+    const service = label("service.name");
+    const spanName = label("span.name");
+    const spanKind = label("span.kind");
+    const statusCode = label("status.code");
+    if (service)
+        labels.service = service;
+    if (spanName)
+        labels.spanName = spanName;
+    if (spanKind)
+        labels.spanKind = spanKind;
+    if (statusCode)
+        labels.statusCode = statusCode;
+    return {
+        namespace,
+        calls: metric("calls", "sum", [...common, ...names(c.calls_dimensions)]),
+        ...(c.histogram?.disable ? {} : { duration: metric("duration", "histogram", [...common, ...names(c.histogram?.dimensions)], c.histogram?.unit ?? "ms") }),
+        ...(c.events?.enabled ? { events: metric("events", "sum", [...common, ...names(c.events.dimensions)]) } : {}),
+        labels,
+        errorStatus: SPAN_STATUS_ERROR,
+    };
+}
+/** The prefix of every metric the `servicegraph` connector emits; the connector takes no namespace. */
+export const SERVICEGRAPH_NAMESPACE = "traces_service_graph";
+/**
+ * The Prometheus names of the metrics a `servicegraph` connector emits at
+ * `COLLECTOR_PIN`, with its default feature gates: latency in seconds, under
+ * `_request_server` and `_request_client`. Every metric carries `client`,
+ * `server`, `connection_type` and `failed`, `client_<d>` and `server_<d>` for
+ * each configured dimension, and `virtual_node` when
+ * `virtual_node_extra_label` is set (connector/servicegraphconnector/connector.go).
+ */
+export function serviceGraphNames(connector, exporter) {
+    const d = connector;
+    if (typeof d.componentType === "string" && d.componentType !== "servicegraph") {
+        throw new Error(`serviceGraphNames: expected a servicegraph connector, got ${d.componentType}`);
+    }
+    const c = (typeof d.componentType === "string" ? (d.props ?? {}) : connector);
+    const naming = exporter && "props" in exporter && typeof exporter.props === "object" ? exporter.props : (exporter ?? {});
+    const dimensions = [
+        "client",
+        "server",
+        "connection_type",
+        "failed",
+        ...(c.dimensions ?? []).flatMap((dim) => [`client_${dim}`, `server_${dim}`]),
+        ...(c.virtual_node_extra_label ? ["virtual_node"] : []),
+    ];
+    const metric = (n, type, unit) => ({
+        name: `${SERVICEGRAPH_NAMESPACE}_${n}`,
+        prometheus: prometheusMetricName(`${SERVICEGRAPH_NAMESPACE}_${n}`, type, unit, naming),
+        type,
+        ...(unit ? { unit } : {}),
+        dimensions,
+    });
+    return {
+        requests: metric("request_total", "sum"),
+        failed: metric("request_failed_total", "sum"),
+        serverDuration: metric("request_server", "histogram", "s"),
+        clientDuration: metric("request_client", "histogram", "s"),
+    };
+}
+/** `metric{a="x", b=~"y"}`; just `metric` with no matchers. */
+export function promSelector(metric, matchers) {
+    if (matchers.length === 0)
+        return metric;
+    return `${metric}{${matchers.map(([l, op, v]) => `${l}${op}${JSON.stringify(v)}`).join(", ")}}`;
+}
+/** `sum by (labels) (rate(sel[range]))`, or `sum (...)` with no labels. */
+export function promSumRate(sel, by, range) {
+    return `sum${by.length ? ` by (${by.join(", ")})` : ""} (rate(${sel}[${range}]))`;
+}
+/**
+ * `errors / all` as rates summed by `by`, with the numerator padded to zero:
+ * `(errors or all * 0) / all`. A group with calls but no error series gets 0
+ * instead of dropping out of the result.
+ */
+export function promErrorRatio(errorSel, allSel, by, range) {
+    const all = promSumRate(allSel, by, range);
+    return `(\n${promSumRate(errorSel, by, range)}\nor\n${all} * 0\n)\n/\n${all}`;
+}
+/** A number as PromQL writes it, without float noise. */
+export function promNumber(n) {
+    return String(Number(n.toPrecision(10)));
+}
+/** `histogram_quantile(q, sum by (le, labels) (rate(bucket[range])))`. */
+export function promQuantile(q, bucketSel, by, range) {
+    return `histogram_quantile(${promNumber(q)}, ${promSumRate(bucketSel, ["le", ...by], range)})`;
+}
+/** Every `span_kind` value, in the order the spec lists them. */
+export const SPAN_METRICS_KINDS = Object.freeze([
+    "SPAN_KIND_UNSPECIFIED",
+    "SPAN_KIND_INTERNAL",
+    "SPAN_KIND_SERVER",
+    "SPAN_KIND_CLIENT",
+    "SPAN_KIND_PRODUCER",
+    "SPAN_KIND_CONSUMER",
+]);
+/** The kinds RED queries count unless told otherwise: the spans that serve a request or consume a message. */
+export const RED_DEFAULT_SPAN_KINDS = Object.freeze(["SPAN_KIND_SERVER", "SPAN_KIND_CONSUMER"]);
+const DEFAULT_RED_QUANTILES = [0.5, 0.95, 0.99];
+/**
+ * The span-kind matcher for `kinds`, or none: none for `[]`, and none for
+ * the default kinds when the connector excludes `span.kind`.
+ */
+export function spanKindMatchers(names, kinds, owner = "spanKindMatchers") {
+    const label = names.labels.spanKind;
+    if (kinds === undefined)
+        return label ? [[label, "=~", RED_DEFAULT_SPAN_KINDS.join("|")]] : [];
+    for (const k of kinds) {
+        if (!SPAN_METRICS_KINDS.includes(k))
+            throw new Error(`${owner}: unknown span kind ${JSON.stringify(k)}; use one of ${SPAN_METRICS_KINDS.join(", ")}`);
+    }
+    if (kinds.length === 0)
+        return [];
+    if (!label)
+        throw new Error(`${owner}: the connector excludes span.kind, so the metrics can't be filtered by spanKinds`);
+    return [[label, "=~", [...new Set(kinds)].join("|")]];
+}
+/**
+ * Rate, error ratio and duration quantiles per service, from a spanmetrics
+ * connector's names. The grafana lexicon's `RedDashboard` and the prometheus
+ * lexicon's `RedAlerts` both build their queries here.
+ */
+export function spanMetricsRedQueries(names, options) {
+    const owner = options.owner ?? "spanMetricsRedQueries";
+    const svc = names.labels.service;
+    const status = names.labels.statusCode;
+    if (!svc)
+        throw new Error(`${owner}: the connector excludes service.name, so there is no service to break the metrics down by`);
+    if (!status)
+        throw new Error(`${owner}: the connector excludes status.code, so errors can't be told from successes`);
+    const kind = spanKindMatchers(names, options.spanKinds, owner);
+    const scope = [...(options.serviceMatch !== undefined ? [[svc, "=~", options.serviceMatch]] : []), ...kind];
+    const by = [svc, ...(options.by ?? [])];
+    const calls = promSelector(names.calls.prometheus, scope);
+    const errors = promSelector(names.calls.prometheus, [...scope, [status, "=", names.errorStatus]]);
+    const buckets = names.duration ? promSelector(`${names.duration.prometheus}_bucket`, scope) : undefined;
+    const quantiles = options.quantiles ?? DEFAULT_RED_QUANTILES;
+    return {
+        service: svc,
+        kindMatchers: kind,
+        rate: promSumRate(calls, by, options.range),
+        errorRatio: promErrorRatio(errors, calls, by, options.range),
+        duration: buckets ? quantiles.map((q) => ({ quantile: q, expr: promQuantile(q, buckets, by, options.range) })) : [],
+    };
+}