@intentius/chant-lexicon-otel 0.106.4 → 0.108.0

package/src/lint/post-synth/otel-helpers.ts

@@ -8,7 +8,7 @@ import type { SerializerResult } from "@intentius/chant/serializer";
 import { loadAll } from "js-yaml";
 import type { Declarable } from "@intentius/chant/declarable";
 import { looksLikeCollectorConfig, type CollectorConfig } from "../../model";
-import { configMapCollectorConfigs, describeConfigMapConfig } from "../../configmap";
+import { configMapCollectorConfigs, describeConfigMapConfig, describeOperatorCollectorConfig, operatorCollectorConfig } from "../../configmap";
 import { validateCollectorConfig, validateCollectorEntities, type CollectorIssueCode, type CollectorIssue } from "../../validate-config";
 import { attributionIssues } from "../../attribution";
 
@@ -19,13 +19,16 @@ export interface FoundCollectorConfig {
   config: CollectorConfig;
   /** Set when the config is a value in a Kubernetes ConfigMap (chant #2930). */
   configMap?: { namespace: string; name: string; key: string };
+  /** Set when the config is the `spec.config` of an OpenTelemetry Operator `OpenTelemetryCollector` (chant #3367). */
+  operator?: { namespace: string; name: string };
 }
 
 /**
  * Every collector config in the output: the otel lexicon's own, any YAML
  * document shaped like one, and any ConfigMap data value that parses as one
  * (how `OtelCollector`, `OtelCollectorGateway` and `GkeOtelCollector` carry
- * theirs). Parsed with js-yaml rather than `ctx.docs`, because collector
+ * theirs), and the `spec.config` of an OpenTelemetry Operator
+ * `OpenTelemetryCollector` (chant #3367). Parsed with js-yaml rather than `ctx.docs`, because collector
  * configs are written with flow lists (`[otlp, batch]`) that core's small
  * YAML reader keeps as strings.
  *
@@ -57,6 +60,8 @@ export function collectorConfigs(ctx: PostSynthContext): FoundCollectorConfig[]
         for (const { config, ...configMap } of configMapCollectorConfigs(doc)) {
           out.push({ source, config, configMap });
         }
+        const cr = operatorCollectorConfig(doc);
+        if (cr) out.push({ source, config: cr.config, operator: { namespace: cr.namespace, name: cr.name } });
       }
     }
   }
@@ -64,7 +69,11 @@ export function collectorConfigs(ctx: PostSynthContext): FoundCollectorConfig[]
 }
 
 function toDiagnostic(issue: CollectorIssue, found?: Omit<FoundCollectorConfig, "config">): PostSynthDiagnostic {
-  const where = found?.configMap ? describeConfigMapConfig(found.configMap) : found && found.source !== "otel" ? found.source : undefined;
+  const where = found?.configMap
+    ? describeConfigMapConfig(found.configMap)
+    : found?.operator
+      ? describeOperatorCollectorConfig(found.operator)
+      : found && found.source !== "otel" ? found.source : undefined;
   return {
     checkId: issue.code,
     severity: issue.severity,
@@ -87,11 +96,15 @@ function configIssues(ctx: PostSynthContext, config: CollectorConfig): Collector
 /**
  * Every config-level diagnostic (OTEL101-OTEL106, OTEL112-OTEL127 and any later
  * config check) over the collector configs in the output. `configMapsOnly`
- * keeps the configs held in ConfigMaps, which is what WK8604 reads.
+ * keeps the configs held in ConfigMaps. `hostedOnly` keeps those and the `spec.config` of an operator `OpenTelemetryCollector`, which is what WK8604 reads.
  */
-export function collectorConfigDiagnostics(ctx: PostSynthContext, opts: { configMapsOnly?: boolean } = {}): PostSynthDiagnostic[] {
+export function collectorConfigDiagnostics(
+  ctx: PostSynthContext,
+  opts: { configMapsOnly?: boolean; hostedOnly?: boolean } = {},
+): PostSynthDiagnostic[] {
   return collectorConfigs(ctx)
     .filter((found) => !opts.configMapsOnly || found.configMap)
+    .filter((found) => !opts.hostedOnly || found.configMap || found.operator)
     .flatMap(({ config, ...found }) => configIssues(ctx, config).map((i) => toDiagnostic(i, found)));
 }
 

package/src/metric-names.ts

@@ -239,3 +239,144 @@ export function serviceGraphNames(
     clientDuration: metric("request_client", "histogram", "s"),
   };
 }
+
+// ── RED queries over span metrics ────────────────────────────────────
+//
+// The PromQL a RED dashboard and RED alerts share. They live here, next to
+// the names they read, so the grafana lexicon (panels) and the prometheus
+// lexicon (alerting rules) build the same expressions without either one
+// importing the other.
+
+/** A label matcher: `[label, op, value]`. */
+export type PromMatcher = [label: string, op: "=" | "!=" | "=~" | "!~", value: string];
+
+/** `metric{a="x", b=~"y"}`; just `metric` with no matchers. */
+export function promSelector(metric: string, matchers: PromMatcher[]): string {
+  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: string, by: string[], range: string): string {
+  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: string, allSel: string, by: string[], range: string): string {
+  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: number): string {
+  return String(Number(n.toPrecision(10)));
+}
+
+/** `histogram_quantile(q, sum by (le, labels) (rate(bucket[range])))`. */
+export function promQuantile(q: number, bucketSel: string, by: string[], range: string): string {
+  return `histogram_quantile(${promNumber(q)}, ${promSumRate(bucketSel, ["le", ...by], range)})`;
+}
+
+/** The `span_kind` label values the spanmetrics connector writes. */
+export type SpanMetricsKind =
+  | "SPAN_KIND_UNSPECIFIED"
+  | "SPAN_KIND_INTERNAL"
+  | "SPAN_KIND_SERVER"
+  | "SPAN_KIND_CLIENT"
+  | "SPAN_KIND_PRODUCER"
+  | "SPAN_KIND_CONSUMER";
+
+/** Every `span_kind` value, in the order the spec lists them. */
+export const SPAN_METRICS_KINDS: readonly SpanMetricsKind[] = 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: readonly SpanMetricsKind[] = Object.freeze(["SPAN_KIND_SERVER", "SPAN_KIND_CONSUMER"]);
+
+/** What `spanMetricsRedQueries` takes besides the names. */
+export interface RedQueryOptions {
+  /** The range every `rate` reads: `$__rate_interval` on a dashboard, `5m` in a rule. */
+  range: string;
+  /** Duration quantiles, one expression each (default p50, p95 and p99). */
+  quantiles?: number[];
+  /** A regex the service label must match, e.g. `$service`. Unset: no service matcher. */
+  serviceMatch?: string;
+  /**
+   * The span kinds counted (default server and consumer spans). `[]` counts
+   * every kind. With the default, a connector that excludes `span.kind`
+   * gets no kind filter; naming kinds for such a connector is an error.
+   */
+  spanKinds?: readonly SpanMetricsKind[];
+  /** Labels the results are split by besides the service label. */
+  by?: string[];
+  /** The name errors are reported under, e.g. `RedDashboard`. */
+  owner?: string;
+}
+
+/** The RED expressions for one spanmetrics connector. */
+export interface RedQueries {
+  /** The service label the results are split by. */
+  service: string;
+  /** The span-kind matcher, or none. */
+  kindMatchers: PromMatcher[];
+  /** Counted spans per second. */
+  rate: string;
+  /** Errors over counted spans, 0 for a service with none. */
+  errorRatio: string;
+  /** One expression per quantile, in the histogram's unit. Empty when the connector has no histogram. */
+  duration: Array<{ quantile: number; expr: string }>;
+}
+
+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: SpanMetricsNames, kinds: readonly SpanMetricsKind[] | undefined, owner = "spanKindMatchers"): PromMatcher[] {
+  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: SpanMetricsNames, options: RedQueryOptions): RedQueries {
+  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: PromMatcher[] = [...(options.serviceMatch !== undefined ? [[svc, "=~", options.serviceMatch] as PromMatcher] : []), ...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) })) : [],
+  };
+}

package/src/op/activities/collector-audit.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, test } from "vitest";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { COLLECTOR_PIN, GENAI_SEMCONV_PIN } from "../../define";
+import {
+  builtinComponents,
+  bumpPins,
+  collectorAudit,
+  componentDir,
+  parseStability,
+  stabilityFindings,
+} from "./collector-audit";
+import { compareSemver } from "./github";
+import type { CommandRunner } from "./github";
+
+const releases = (tags: string[]) => tags.map((t) => ({ tag_name: t, draft: false, prerelease: false }));
+
+/** Answers the two release lists, and metadata.yaml for the components in `meta` (keyed by `<repo>/<tag>/<dir>`). */
+function fakeFetch(contrib: string[], semconv: string[], meta: Record<string, string> = {}): { f: typeof fetch; urls: string[] } {
+  const urls: string[] = [];
+  const f = (async (input: string | URL | Request) => {
+    const url = String(input);
+    urls.push(url);
+    if (url.includes("opentelemetry-collector-contrib/releases")) return Response.json(releases(contrib));
+    if (url.includes("semantic-conventions/releases")) return Response.json(releases(semconv));
+    const m = /raw\.githubusercontent\.com\/[^/]+\/([^/]+)\/([^/]+)\/(.+)\/metadata\.yaml$/.exec(url);
+    const key = m ? `${m[1]}/${m[2]}/${m[3]}` : "";
+    if (meta[key] !== undefined) return new Response(meta[key]);
+    return new Response("not found", { status: 404 });
+  }) as typeof fetch;
+  return { f, urls };
+}
+
+const stability = (levels: Record<string, string[]>) =>
+  `type: x\nstatus:\n  class: receiver\n  stability:\n${Object.entries(levels)
+    .map(([l, s]) => `    ${l}: [${s.join(", ")}]`)
+    .join("\n")}\n`;
+
+describe("collectorAudit's pieces", () => {
+  test("the built-in components, and where each lives upstream", () => {
+    const comps = builtinComponents();
+    expect(comps.length).toBeGreaterThan(10);
+    expect(comps).toContainEqual({ kind: "receiver", type: "otlp" });
+    expect(componentDir({ kind: "receiver", type: "k8s_cluster" })).toBe("receiver/k8sclusterreceiver");
+    expect(componentDir({ kind: "extension", type: "health_check" })).toBe("extension/healthcheckextension");
+  });
+
+  test("stability by signal from metadata.yaml", () => {
+    expect(parseStability(stability({ beta: ["traces", "metrics"], deprecated: ["logs"] }))).toEqual({ traces: "beta", metrics: "beta", logs: "deprecated" });
+    expect(parseStability("type: x\n")).toBeUndefined();
+  });
+
+  test("a deprecated signal and a changed level are findings; an unchanged component is not", () => {
+    const c = { kind: "receiver" as const, type: "x" };
+    expect(stabilityFindings(c, { traces: "beta" }, { traces: "beta" }, "v1.0.0", "v1.1.0")).toEqual([]);
+    expect(stabilityFindings(c, { traces: "alpha" }, { traces: "beta" }, "v1.0.0", "v1.1.0")).toEqual([
+      { kind: "stability-changed", subject: "receiver/x", detail: "traces alpha to beta (v1.0.0 to v1.1.0)" },
+    ]);
+    expect(stabilityFindings(c, { logs: "beta" }, { logs: "deprecated" }, "v1.0.0", "v1.1.0")).toEqual([
+      { kind: "deprecated", subject: "receiver/x", detail: "logs deprecated at v1.1.0" },
+    ]);
+  });
+
+  test("bumpPins moves only the two pin versions in define.ts", () => {
+    const text = readFileSync(join(import.meta.dirname, "..", "..", "define.ts"), "utf8");
+    const out = bumpPins(text, { collector: "v0.140.0", genai: "v1.50.0" });
+    const block = (text: string, name: string) => new RegExp(`export const ${name}: SchemaPin = Object\\.freeze\\(\\{[^}]*\\}`).exec(text)![0];
+    expect(block(out, "COLLECTOR_PIN")).toContain('version: "v0.140.0"');
+    expect(block(out, "GENAI_SEMCONV_PIN")).toContain('version: "v1.50.0"');
+    // SEMCONV_PIN, and the custom-component pin in define.ts's doc comment, are left alone.
+    expect(block(out, "SEMCONV_PIN")).toBe(block(text, "SEMCONV_PIN"));
+    const changed = out.split("\n").filter((l, i) => l !== text.split("\n")[i]);
+    expect(changed).toHaveLength(2);
+    expect(() => bumpPins("nothing", { collector: "v1.0.0" })).toThrow(/no COLLECTOR_PIN/);
+  });
+
+  test("semver ordering", () => {
+    expect(compareSemver("v0.131.0", "v0.130.0")).toBeGreaterThan(0);
+    expect(compareSemver("v0.99.0", "v0.130.0")).toBeLessThan(0);
+  });
+});
+
+describe("collectorAudit", () => {
+  test("current pins and no stability reading: no findings, report mode does nothing else", async () => {
+    const { f } = fakeFetch([COLLECTOR_PIN.version, "v0.129.0"], [GENAI_SEMCONV_PIN.version]);
+    const r = await collectorAudit({ stability: false, _fetch: f, _run: async () => { throw new Error("no git in report mode"); } });
+    expect(r.findings).toEqual([]);
+    expect(r.collector).toEqual({ pin: COLLECTOR_PIN.version, latest: COLLECTOR_PIN.version, behind: 0 });
+    expect(r.summary).toContain(`COLLECTOR_PIN ${COLLECTOR_PIN.version}: current`);
+  });
+
+  test("pins behind the newest releases are findings, prereleases ignored", async () => {
+    const { f } = fakeFetch(["v0.132.0", "v0.131.0", COLLECTOR_PIN.version], ["v1.42.0", GENAI_SEMCONV_PIN.version]);
+    const r = await collectorAudit({ stability: false, _fetch: f });
+    expect(r.findings.map((x) => x.kind)).toEqual(["collector-pin-behind", "semconv-pin-behind"]);
+    expect(r.collector).toEqual({ pin: COLLECTOR_PIN.version, latest: "v0.132.0", behind: 2 });
+    expect(r.semconv.behind).toBe(1);
+  });
+
+  test("component stability at the pin and at the newest release, contrib then core, within the budget", async () => {
+    const meta = {
+      // otlp is a core component: contrib answers 404 for it.
+      [`opentelemetry-collector/v0.131.0/receiver/otlpreceiver`]: stability({ stable: ["traces"], deprecated: ["logs"] }),
+      [`opentelemetry-collector/${COLLECTOR_PIN.version}/receiver/otlpreceiver`]: stability({ stable: ["traces", "logs"] }),
+    };
+    const { f, urls } = fakeFetch(["v0.131.0", COLLECTOR_PIN.version], [GENAI_SEMCONV_PIN.version], meta);
+    const r = await collectorAudit({ _fetch: f, stabilityBudget: 500 });
+    expect(r.findings).toContainEqual({ kind: "deprecated", subject: "receiver/otlp", detail: "logs deprecated at v0.131.0" });
+    expect(r.unchecked).not.toContain("receiver/otlp");
+    expect(r.unchecked.length).toBe(builtinComponents().length - 1);
+    // Looked for in contrib first, then core.
+    const otlp = urls.filter((u) => u.includes("/v0.131.0/receiver/otlpreceiver/"));
+    expect(otlp[0]).toContain("opentelemetry-collector-contrib");
+    expect(otlp[1]).toContain("open-telemetry/opentelemetry-collector/");
+
+    const capped = fakeFetch(["v0.131.0", COLLECTOR_PIN.version], [GENAI_SEMCONV_PIN.version], meta);
+    await collectorAudit({ _fetch: capped.f, stabilityBudget: 3 });
+    expect(capped.urls.filter((u) => u.includes("raw.githubusercontent.com"))).toHaveLength(3);
+  });
+
+  test("an unreadable release list is no finding", async () => {
+    const f = (async () => new Response("rate limited", { status: 403 })) as unknown as typeof fetch;
+    const r = await collectorAudit({ stability: false, _fetch: f });
+    expect(r.findings).toEqual([]);
+    expect(r.collector.latest).toBeNull();
+    expect(r.summary).toContain("release list unreadable");
+  });
+
+  test("pull-request mode bumps the pins in a worktree and opens a pull request", async () => {
+    const { f } = fakeFetch(["v0.131.0", COLLECTOR_PIN.version], [GENAI_SEMCONV_PIN.version]);
+    const calls: string[] = [];
+    const lexiconDir = join(import.meta.dirname, "..", "..", "..");
+    const run: CommandRunner = async (bin, args) => {
+      calls.push(`${bin} ${args.join(" ")}`);
+      if (args[0] === "rev-parse") return join(lexiconDir, "..", "..") + "\n";
+      if (args[0] === "symbolic-ref") return "origin/main\n";
+      if (args[0] === "worktree" && args[1] === "add") throw new Error("stop before writing files");
+      return "";
+    };
+    await expect(collectorAudit({ mode: "pull-request", stability: false, lexiconDir, _fetch: f, _run: run })).rejects.toThrow(/stop before/);
+    expect(calls.some((c) => c.startsWith("git worktree add --force -B chant/otel-pins"))).toBe(true);
+    expect(calls.some((c) => c.startsWith("git worktree remove"))).toBe(false);
+  });
+
+  test("pull-request mode end to end against a recorded git and gh", async () => {
+    const { f } = fakeFetch(["v0.131.0", COLLECTOR_PIN.version], [GENAI_SEMCONV_PIN.version]);
+    const calls: string[] = [];
+    const lexiconDir = join(import.meta.dirname, "..", "..", "..");
+    const { mkdirSync } = await import("node:fs");
+    const run: CommandRunner = async (bin, args) => {
+      calls.push(`${bin} ${args.join(" ")}`);
+      if (args[0] === "rev-parse") return join(lexiconDir, "..", "..") + "\n";
+      if (args[0] === "symbolic-ref") return "origin/main\n";
+      if (args[0] === "worktree" && args[1] === "add") mkdirSync(join(args[5], "lexicons", "otel", "src"), { recursive: true });
+      if (bin === "gh" && args[1] === "list") return "[]";
+      if (bin === "gh" && args[1] === "create") return "https://github.com/INTENTIUS/chant/pull/1\n";
+      return "";
+    };
+    const r = await collectorAudit({ mode: "pull-request", stability: false, lexiconDir, _fetch: f, _run: run });
+    expect(r.prUrl).toBe("https://github.com/INTENTIUS/chant/pull/1");
+    expect(calls).toContain("git add lexicons/otel/src/define.ts");
+    expect(calls.some((c) => c.startsWith("git commit -m chore(otel): move COLLECTOR_PIN to v0.131.0"))).toBe(true);
+    expect(calls.some((c) => c.startsWith("git push --force origin HEAD:refs/heads/chant/otel-pins"))).toBe(true);
+    expect(calls.some((c) => c.startsWith("gh pr create --head chant/otel-pins --base main"))).toBe(true);
+  });
+});

package/src/op/activities/collector-audit.ts

@@ -0,0 +1,265 @@
+/**
+ * `collectorAudit`: the otel lexicon's pins against what upstream has
+ * released since (#3369), the activity behind `CollectorAuditOp`.
+ *
+ * Three readings, each against a moving upstream:
+ *
+ * - the contrib release list against `COLLECTOR_PIN`: how many releases
+ *   the pin is behind, and the newest one.
+ * - component stability from each built-in component's `metadata.yaml`, at
+ *   the pin and at the newest release: a signal whose stability level
+ *   changed between the two, and any signal that is `deprecated` or
+ *   `unmaintained` at the newest release. A component's file is looked up
+ *   in contrib, then in core, at `<kind>/<type><kind>/metadata.yaml`; one
+ *   found in neither is listed as unchecked, never as a finding.
+ * - `GENAI_SEMCONV_PIN` against the semantic-conventions releases.
+ *
+ * `mode` says what to do with the findings: `report` returns them;
+ * `issue` keeps one open issue current; `pull-request` also bumps the pins
+ * in the lexicon's `src/define.ts` on a proposal branch and opens (or
+ * edits) a pull request with the findings as its body. Only the pin values
+ * change: the config types written against the old pin are the reviewer's
+ * to move, which the body says.
+ */
+
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative, resolve } from "node:path";
+import { load } from "js-yaml";
+import { COLLECTOR_PIN, GENAI_SEMCONV_PIN, type ComponentClass } from "../../define";
+import * as components from "../../components";
+import type { ComponentKind } from "../../model";
+import { compareSemver, defaultRunner, fetchReleases, proposePullRequest, stickyIssue, type CommandRunner, type Release } from "./github";
+
+export type CollectorAuditMode = "report" | "issue" | "pull-request";
+
+export const CONTRIB_REPO = "open-telemetry/opentelemetry-collector-contrib";
+export const CORE_REPO = "open-telemetry/opentelemetry-collector";
+export const SEMCONV_REPO = "open-telemetry/semantic-conventions";
+
+export interface CollectorAuditArgs {
+  mode?: CollectorAuditMode;
+  /**
+   * The otel lexicon's directory, whose `src/define.ts` a pull request
+   * edits. Default `<cwd>/lexicons/otel`.
+   */
+  lexiconDir?: string;
+  /** Check component stability. Default true. */
+  stability?: boolean;
+  /** At most this many `metadata.yaml` reads. Default 200. */
+  stabilityBudget?: number;
+  /** The proposal branch. Default `chant/otel-pins`. */
+  branch?: string;
+  /** Replaces fetch. For tests. */
+  _fetch?: typeof fetch;
+  /** Replaces git and gh. For tests. */
+  _run?: CommandRunner;
+}
+
+export type CollectorAuditFindingKind = "collector-pin-behind" | "semconv-pin-behind" | "stability-changed" | "deprecated";
+
+export interface CollectorAuditFinding {
+  kind: CollectorAuditFindingKind;
+  /** The pin or the component (`receiver/otlp`) the finding is about. */
+  subject: string;
+  detail: string;
+}
+
+export interface CollectorAuditResult {
+  mode: CollectorAuditMode;
+  collector: { pin: string; latest: string | null; behind: number };
+  semconv: { pin: string; latest: string | null; behind: number };
+  findings: CollectorAuditFinding[];
+  /** Components whose metadata.yaml was in neither repository, or past the budget. */
+  unchecked: string[];
+  summary: string;
+  issueUrl?: string;
+  prUrl?: string;
+}
+
+/** A built-in component's kind and collector type. */
+export interface BuiltinComponent {
+  kind: ComponentKind;
+  type: string;
+}
+
+export function builtinComponents(): BuiltinComponent[] {
+  const out: BuiltinComponent[] = [];
+  const seen = new Set<string>();
+  for (const value of Object.values(components) as unknown[]) {
+    if (typeof value !== "function") continue;
+    const def = (value as Partial<ComponentClass>).definition;
+    if (!def || !def.builtin || typeof def.type !== "string") continue;
+    const key = `${def.kind}/${def.type}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ kind: def.kind, type: def.type });
+  }
+  return out.sort((a, b) => `${a.kind}/${a.type}`.localeCompare(`${b.kind}/${b.type}`));
+}
+
+/** The directory a component lives in upstream: `receiver/k8s_cluster` is `receiver/k8sclusterreceiver`. */
+export function componentDir(c: BuiltinComponent): string {
+  return `${c.kind}/${c.type.replace(/_/g, "")}${c.kind}`;
+}
+
+/** Stability level by signal, from a `metadata.yaml`'s `status.stability`. */
+export type Stability = Record<string, string>;
+
+export function parseStability(text: string): Stability | undefined {
+  let doc: unknown;
+  try {
+    doc = load(text);
+  } catch {
+    return undefined;
+  }
+  const status = (doc as { status?: { stability?: unknown } } | undefined)?.status;
+  const stability = status?.stability;
+  if (!stability || typeof stability !== "object") return undefined;
+  const out: Stability = {};
+  for (const [level, signals] of Object.entries(stability as Record<string, unknown>)) {
+    for (const s of Array.isArray(signals) ? signals : []) if (typeof s === "string") out[s] = level;
+  }
+  return out;
+}
+
+async function fetchText(f: typeof fetch, url: string): Promise<string | undefined> {
+  const res = await f(url);
+  if (res.status === 404) return undefined;
+  if (!res.ok) throw new Error(`${url}: HTTP ${res.status}`);
+  return res.text();
+}
+
+/** A component's stability at `tag`, from contrib or core; undefined when neither has its metadata.yaml. */
+async function stabilityAt(f: typeof fetch, c: BuiltinComponent, tag: string, budget: { left: number }): Promise<Stability | undefined> {
+  for (const repo of [CONTRIB_REPO, CORE_REPO]) {
+    if (budget.left <= 0) return undefined;
+    budget.left--;
+    const text = await fetchText(f, `https://raw.githubusercontent.com/${repo}/${tag}/${componentDir(c)}/metadata.yaml`);
+    if (text !== undefined) return parseStability(text);
+  }
+  return undefined;
+}
+
+const RETIRED = new Set(["deprecated", "unmaintained"]);
+
+/** Findings for one component, from its stability at the pin and at the newest release. */
+export function stabilityFindings(c: BuiltinComponent, atPin: Stability | undefined, atLatest: Stability, pin: string, latest: string): CollectorAuditFinding[] {
+  const subject = `${c.kind}/${c.type}`;
+  const out: CollectorAuditFinding[] = [];
+  const retired = Object.entries(atLatest).filter(([, level]) => RETIRED.has(level));
+  if (retired.length > 0) {
+    out.push({ kind: "deprecated", subject, detail: `${retired.map(([s, l]) => `${s} ${l}`).join(", ")} at ${latest}` });
+  }
+  if (atPin && pin !== latest) {
+    const changed = [...new Set([...Object.keys(atPin), ...Object.keys(atLatest)])]
+      .filter((s) => atPin[s] !== atLatest[s] && !RETIRED.has(atLatest[s] ?? ""))
+      .map((s) => `${s} ${atPin[s] ?? "absent"} to ${atLatest[s] ?? "absent"}`);
+    if (changed.length > 0) out.push({ kind: "stability-changed", subject, detail: `${changed.join(", ")} (${pin} to ${latest})` });
+  }
+  return out;
+}
+
+function behindCount(releases: Release[], pin: string): number {
+  return releases.filter((r) => compareSemver(r.tag, pin) > 0).length;
+}
+
+/** `src/define.ts` with `COLLECTOR_PIN` and `GENAI_SEMCONV_PIN` moved to the given versions. */
+export function bumpPins(text: string, to: { collector?: string; genai?: string }): string {
+  let out = text;
+  const bump = (name: string, version: string) => {
+    const re = new RegExp(`(export const ${name}: SchemaPin = Object\\.freeze\\(\\{[^}]*?version:\\s*")([^"]+)(")`);
+    if (!re.test(out)) throw new Error(`define.ts has no ${name} with a version to bump`);
+    out = out.replace(re, `$1${version}$3`);
+  };
+  if (to.collector) bump("COLLECTOR_PIN", to.collector);
+  if (to.genai) bump("GENAI_SEMCONV_PIN", to.genai);
+  return out;
+}
+
+export function renderCollectorAuditSummary(r: Omit<CollectorAuditResult, "summary" | "mode">): string {
+  let out = "## Collector audit\n\n";
+  out += `- COLLECTOR_PIN ${r.collector.pin}: ${r.collector.latest === null ? "release list unreadable" : r.collector.behind === 0 ? "current" : `${r.collector.behind} release(s) behind ${r.collector.latest}`}\n`;
+  out += `- GENAI_SEMCONV_PIN ${r.semconv.pin}: ${r.semconv.latest === null ? "release list unreadable" : r.semconv.behind === 0 ? "current" : `${r.semconv.behind} release(s) behind ${r.semconv.latest}`}\n`;
+  const comps = r.findings.filter((f) => f.kind === "deprecated" || f.kind === "stability-changed");
+  if (comps.length > 0) {
+    out += "\n| Component | Finding | Detail |\n|---|---|---|\n";
+    for (const f of comps) out += `| ${f.subject} | ${f.kind} | ${f.detail} |\n`;
+  } else {
+    out += "\nNo component stability findings.\n";
+  }
+  if (r.unchecked.length > 0) out += `\nUnchecked (no metadata.yaml found, or past the budget): ${r.unchecked.join(", ")}\n`;
+  return out;
+}
+
+/** Audit the otel lexicon's pins and its built-in components against upstream releases. */
+export async function collectorAudit(args: CollectorAuditArgs = {}): Promise<CollectorAuditResult> {
+  const f = args._fetch ?? fetch;
+  const run = args._run ?? defaultRunner;
+  const mode = args.mode ?? "report";
+  const findings: CollectorAuditFinding[] = [];
+  const unchecked: string[] = [];
+
+  const contrib = await fetchReleases(CONTRIB_REPO, f).catch(() => null);
+  const semconv = await fetchReleases(SEMCONV_REPO, f).catch(() => null);
+  const collector = { pin: COLLECTOR_PIN.version, latest: contrib?.[0]?.tag ?? null, behind: contrib ? behindCount(contrib, COLLECTOR_PIN.version) : 0 };
+  const sem = { pin: GENAI_SEMCONV_PIN.version, latest: semconv?.[0]?.tag ?? null, behind: semconv ? behindCount(semconv, GENAI_SEMCONV_PIN.version) : 0 };
+  if (collector.latest && collector.behind > 0) {
+    findings.push({ kind: "collector-pin-behind", subject: "COLLECTOR_PIN", detail: `${collector.pin} is ${collector.behind} release(s) behind ${collector.latest}` });
+  }
+  if (sem.latest && sem.behind > 0) {
+    findings.push({ kind: "semconv-pin-behind", subject: "GENAI_SEMCONV_PIN", detail: `${sem.pin} is ${sem.behind} release(s) behind ${sem.latest}` });
+  }
+
+  if (args.stability !== false) {
+    const latest = collector.latest ?? collector.pin;
+    const budget = { left: args.stabilityBudget ?? 200 };
+    for (const c of builtinComponents()) {
+      const atLatest = await stabilityAt(f, c, latest, budget).catch(() => undefined);
+      if (!atLatest) {
+        unchecked.push(`${c.kind}/${c.type}`);
+        continue;
+      }
+      const atPin = latest === collector.pin ? atLatest : await stabilityAt(f, c, collector.pin, budget).catch(() => undefined);
+      findings.push(...stabilityFindings(c, atPin, atLatest, collector.pin, latest));
+    }
+  }
+
+  const base = { collector, semconv: sem, findings, unchecked };
+  const summary = renderCollectorAuditSummary(base);
+  const result: CollectorAuditResult = { mode, ...base, summary };
+  if (findings.length === 0 || mode === "report") return result;
+
+  const cwd = process.cwd();
+  if (mode === "issue") {
+    result.issueUrl = await stickyIssue(run, cwd, "otel: collector audit findings", summary);
+    return result;
+  }
+
+  // pull-request: bump the pins that are behind.
+  const to = {
+    ...(collector.latest && collector.behind > 0 ? { collector: collector.latest } : {}),
+    ...(sem.latest && sem.behind > 0 ? { genai: sem.latest } : {}),
+  };
+  if (!to.collector && !to.genai) {
+    result.issueUrl = await stickyIssue(run, cwd, "otel: collector audit findings", summary);
+    return result;
+  }
+  const lexiconDir = resolve(args.lexiconDir ?? join(cwd, "lexicons", "otel"));
+  const root = (await run("git", ["rev-parse", "--show-toplevel"], lexiconDir)).trim();
+  const definePath = join(lexiconDir, "src", "define.ts");
+  const content = bumpPins(readFileSync(definePath, "utf8"), to);
+  const moved = [to.collector ? `COLLECTOR_PIN to ${to.collector}` : "", to.genai ? `GENAI_SEMCONV_PIN to ${to.genai}` : ""].filter(Boolean).join(" and ");
+  result.prUrl = await proposePullRequest(run, {
+    root,
+    branch: args.branch ?? "chant/otel-pins",
+    title: `chore(otel): move ${moved}`,
+    body:
+      `${summary}\n\nThis moves the pin values only. The config types, defaults and checks written against ${collector.pin} ` +
+      "still need reading against the release notes before this merges.\n",
+    files: [{ path: relative(root, definePath), content }],
+    commitMessage: `chore(otel): move ${moved}`,
+    worktreeDir: join(mkdtempSync(join(tmpdir(), "chant-otel-pins-")), "wt"),
+  });
+  return result;
+}