@intentius/chant-lexicon-otel 0.106.4 → 0.108.0

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

@@ -0,0 +1,115 @@
+import { describe, expect, test } from "vitest";
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import { collectorHealthObserve, declaredEndpoints, splitEndpoint } from "./collector-health";
+
+function fakeFetch(answers: Record<string, number | "refused">): { f: typeof fetch; urls: string[] } {
+  const urls: string[] = [];
+  const f = (async (input: string | URL | Request) => {
+    const url = String(input);
+    urls.push(url);
+    const a = answers[url];
+    if (a === undefined || a === "refused") throw Object.assign(new TypeError("fetch failed"), { cause: { code: "ECONNREFUSED" } });
+    return new Response("", { status: a });
+  }) as typeof fetch;
+  return { f, urls };
+}
+
+const withHealth = {
+  extensions: { health_check: { endpoint: "0.0.0.0:13133" }, zpages: { endpoint: "localhost:55679" } },
+  service: {
+    extensions: ["health_check", "zpages"],
+    telemetry: { metrics: { readers: [{ pull: { exporter: { prometheus: { host: "0.0.0.0", port: 8888 } } } }] } },
+    pipelines: { traces: { receivers: ["otlp"], exporters: ["debug"] } },
+  },
+};
+
+describe("the endpoints a collector config declares", () => {
+  test("health_check, zpages and the pull reader's metrics, with 0.0.0.0 read as localhost", () => {
+    expect(declaredEndpoints(withHealth)).toEqual([
+      { kind: "healthCheck", url: "http://localhost:13133/" },
+      { kind: "zpages", url: "http://localhost:55679/debug/servicez" },
+      { kind: "telemetry", url: "http://localhost:8888/metrics" },
+    ]);
+  });
+
+  test("health_check at its v0.130.0 default (localhost:13133, /) when it sets nothing, and its own path", () => {
+    expect(declaredEndpoints({ extensions: { health_check: {} }, service: { extensions: ["health_check"] } })).toEqual([
+      { kind: "healthCheck", url: "http://localhost:13133/" },
+    ]);
+    expect(
+      declaredEndpoints({ extensions: { "health_check/ready": { endpoint: "${env:POD_IP}:8080", path: "/ready" } }, service: { extensions: ["health_check/ready"] } }),
+    ).toEqual([{ kind: "healthCheck", url: "http://localhost:8080/ready" }]);
+  });
+
+  test("an extension declared but not enabled in service.extensions is not an endpoint", () => {
+    expect(declaredEndpoints({ extensions: { health_check: {} }, service: {} })).toEqual([]);
+  });
+
+  test("the older telemetry address, host and URL overrides", () => {
+    const cfg = { extensions: { health_check: {} }, service: { extensions: ["health_check"], telemetry: { metrics: { address: ":8888" } } } };
+    expect(declaredEndpoints(cfg, "otel.example")).toEqual([
+      { kind: "healthCheck", url: "http://otel.example:13133/" },
+      { kind: "telemetry", url: "http://otel.example:8888/metrics" },
+    ]);
+    expect(declaredEndpoints(cfg, undefined, { healthCheck: "http://127.0.0.1:31333/" })[0]).toEqual({ kind: "healthCheck", url: "http://127.0.0.1:31333/" });
+  });
+
+  test("splitEndpoint reads host:port, :port and URLs", () => {
+    expect(splitEndpoint("0.0.0.0:13133")).toEqual({ host: "0.0.0.0", port: "13133" });
+    expect(splitEndpoint(":8888")).toEqual({ host: "", port: "8888" });
+    expect(splitEndpoint("http://otel:13133/x")).toEqual({ host: "otel", port: "13133" });
+    expect(splitEndpoint("nope")).toBeUndefined();
+  });
+});
+
+describe("collectorHealthObserve", () => {
+  test("one resource per collector: in-sync when every declared endpoint answers 200", async () => {
+    const { f } = fakeFetch({ "http://localhost:13133/": 200, "http://localhost:55679/debug/servicez": 200, "http://localhost:8888/metrics": 200 });
+    const r = await collectorHealthObserve({ collectors: [{ name: "gateway", configObject: withHealth }], _fetch: f, probeIntervalMs: 0 });
+    expect(r.resources).toEqual([{ name: "gateway", status: "in-sync", detail: "health_check ok, zpages ok, telemetry ok" }]);
+  });
+
+  test("drifted when an endpoint answers otherwise or not at all, naming each", async () => {
+    const { f, urls } = fakeFetch({ "http://localhost:13133/": 503, "http://localhost:55679/debug/servicez": 200 });
+    const r = await collectorHealthObserve({ collectors: [{ name: "gateway", configObject: withHealth }], _fetch: f, probes: 2, probeIntervalMs: 0 });
+    expect(r.resources[0].status).toBe("drifted");
+    expect(r.resources[0].detail).toBe(
+      "health_check http://localhost:13133/ answered 503; telemetry http://localhost:8888/metrics did not answer (ECONNREFUSED)",
+    );
+    // A failing endpoint is probed `probes` times before it counts.
+    expect(urls.filter((u) => u === "http://localhost:13133/")).toHaveLength(2);
+  });
+
+  test("no health_check in service.extensions is unknown, never drifted, and nothing is probed", async () => {
+    const { f, urls } = fakeFetch({});
+    const r = await collectorHealthObserve({
+      collectors: [{ name: "agent", configObject: { extensions: { zpages: {} }, service: { extensions: ["zpages"] } } }],
+      _fetch: f,
+    });
+    expect(r.resources).toEqual([{ name: "agent", status: "unknown", detail: "no health_check in service.extensions" }]);
+    expect(urls).toEqual([]);
+  });
+
+  test("an unreadable config is unknown", async () => {
+    const r = await collectorHealthObserve({ collectors: [{ name: "x", config: "/nonexistent/collector.yaml" }] });
+    expect(r.resources[0]).toMatchObject({ name: "x", status: "unknown" });
+    expect(r.resources[0].detail).toMatch(/config unreadable/);
+  });
+
+  test("against a real HTTP server standing in for health_check", async () => {
+    const server: Server = createServer((req, res) => {
+      res.statusCode = req.url === "/" ? 200 : 404;
+      res.end('{"status":"Server available"}');
+    });
+    await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
+    const port = (server.address() as AddressInfo).port;
+    try {
+      const config = { extensions: { health_check: { endpoint: `0.0.0.0:${port}` } }, service: { extensions: ["health_check"] } };
+      const up = await collectorHealthObserve({ collectors: [{ name: "c", configObject: config, host: "127.0.0.1" }] });
+      expect(up.resources[0].status).toBe("in-sync");
+    } finally {
+      await new Promise<void>((r) => server.close(() => r()));
+    }
+  });
+});

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

@@ -0,0 +1,211 @@
+/**
+ * Running collectors as resources a `ConvergeOp` observes (#3369).
+ *
+ * `collectorHealthObserve` returns one resource per collector, from the
+ * endpoints its config declares:
+ *
+ * - the `health_check` extension (`service.extensions`), at its `endpoint`
+ *   and `path`. At v0.130.0 it answers on `localhost:13133` at `/` by
+ *   default, 200 while the collector runs, and reports no per-component
+ *   status, so a 200 is all it says.
+ * - the `zpages` extension, when the service enables it: `/debug/servicez`
+ *   on its endpoint (default `localhost:55679`).
+ * - the collector's own metrics, when `service.telemetry.metrics` declares
+ *   where they are served: a `pull` reader's prometheus exporter
+ *   (`host`/`port`), or the older `address`. `/metrics` on it.
+ *
+ * A collector whose service enables no `health_check` is `unknown`, never
+ * `drifted`: nothing it declares says whether it is healthy. One that does
+ * is `in-sync` when every declared endpoint answers 200, and `drifted`
+ * otherwise, with each endpoint that did not in the detail.
+ *
+ * The config's hosts are where the collector listens, which is often
+ * `0.0.0.0` or a pod address. `host` replaces the host of every endpoint (a
+ * port-forward, a container's published ports), and `endpoints` replaces
+ * whole URLs.
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { load } from "js-yaml";
+import { parseComponentId } from "../../model";
+
+export type CollectorEndpointKind = "healthCheck" | "zpages" | "telemetry";
+
+export interface ObservedCollector {
+  /** The resource name. */
+  name: string;
+  /** The collector config file, relative to the working directory, read on each tick. */
+  config?: string;
+  /** The config itself, in place of `config`. */
+  configObject?: Record<string, unknown>;
+  /** Where the collector is reached, replacing every endpoint's host. Default: the config's host, with 0.0.0.0 and empty read as localhost. */
+  host?: string;
+  /** Whole URLs, replacing the ones read from the config. */
+  endpoints?: Partial<Record<CollectorEndpointKind, string>>;
+}
+
+export interface CollectorHealthObserveArgs {
+  collectors: ObservedCollector[];
+  /** Per-request timeout, ms. Default 5000. */
+  timeoutMs?: number;
+  /** Probes of a failing endpoint before it counts as down. Default 2. */
+  probes?: number;
+  /** Time between probes, ms. Default 1000. */
+  probeIntervalMs?: number;
+  /** Replaces fetch. For tests. */
+  _fetch?: typeof fetch;
+}
+
+export interface CollectorHealthObserveResult {
+  resources: { name: string; status: "in-sync" | "drifted" | "unknown"; detail: string }[];
+}
+
+export interface DeclaredEndpoint {
+  kind: CollectorEndpointKind;
+  url: string;
+}
+
+const DEFAULTS = {
+  healthCheck: { endpoint: "localhost:13133", path: "/" },
+  zpages: { endpoint: "localhost:55679", path: "/debug/servicez" },
+} as const;
+
+const isRecord = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
+
+/** `host:port`, `:port` or a URL, as host and port. A `${env:...}` host reads as unknown (empty). */
+export function splitEndpoint(endpoint: string): { host: string; port: string } | undefined {
+  let s = endpoint.trim().replace(/^[a-z]+:\/\//i, "");
+  s = s.replace(/\/.*$/, "");
+  const m = /^(.*):(\d+)$/.exec(s);
+  if (!m) return undefined;
+  const host = m[1].includes("${") ? "" : m[1];
+  return { host, port: m[2] };
+}
+
+function urlOf(endpoint: string, path: string, host: string | undefined): string | undefined {
+  const parts = splitEndpoint(endpoint);
+  if (!parts) return undefined;
+  let h = host ?? parts.host;
+  if (h === "" || h === "0.0.0.0" || h === "::" || h === "[::]") h = "localhost";
+  return `http://${h}:${parts.port}${path.startsWith("/") ? path : `/${path}`}`;
+}
+
+/** The first enabled extension of `type`, and its config. */
+function enabledExtension(config: Record<string, unknown>, type: string): Record<string, unknown> | undefined {
+  const service = isRecord(config.service) ? config.service : {};
+  const enabled = Array.isArray(service.extensions) ? service.extensions : [];
+  const extensions = isRecord(config.extensions) ? config.extensions : {};
+  for (const id of enabled) {
+    if (typeof id !== "string" || parseComponentId(id)?.type !== type) continue;
+    const body = extensions[id];
+    return isRecord(body) ? body : {};
+  }
+  return undefined;
+}
+
+/** Where `service.telemetry.metrics` serves the collector's own metrics, as `host:port`, when the config says. */
+function telemetryEndpoint(config: Record<string, unknown>): string | undefined {
+  const service = isRecord(config.service) ? config.service : {};
+  const telemetry = isRecord(service.telemetry) ? service.telemetry : {};
+  const metrics = isRecord(telemetry.metrics) ? telemetry.metrics : undefined;
+  if (!metrics || metrics.level === "none") return undefined;
+  if (typeof metrics.address === "string") return metrics.address;
+  const readers = Array.isArray(metrics.readers) ? metrics.readers : [];
+  for (const r of readers) {
+    const prom = isRecord(r) && isRecord(r.pull) && isRecord(r.pull.exporter) ? r.pull.exporter.prometheus : undefined;
+    if (isRecord(prom) && (typeof prom.port === "number" || typeof prom.port === "string")) {
+      const host = typeof prom.host === "string" ? prom.host : "localhost";
+      return `${host}:${prom.port}`;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The endpoints a collector config declares, as URLs. `healthCheck` is
+ * present only when the service enables a `health_check` extension.
+ */
+export function declaredEndpoints(config: Record<string, unknown>, host?: string, overrides: Partial<Record<CollectorEndpointKind, string>> = {}): DeclaredEndpoint[] {
+  const out: DeclaredEndpoint[] = [];
+  const push = (kind: CollectorEndpointKind, url: string | undefined) => {
+    const u = overrides[kind] ?? url;
+    if (u) out.push({ kind, url: u });
+  };
+  const hc = enabledExtension(config, "health_check");
+  if (hc) {
+    const endpoint = typeof hc.endpoint === "string" ? hc.endpoint : DEFAULTS.healthCheck.endpoint;
+    const path = typeof hc.path === "string" ? hc.path : DEFAULTS.healthCheck.path;
+    push("healthCheck", urlOf(endpoint, path, host));
+  }
+  const zp = enabledExtension(config, "zpages");
+  if (zp) {
+    const endpoint = typeof zp.endpoint === "string" ? zp.endpoint : DEFAULTS.zpages.endpoint;
+    push("zpages", urlOf(endpoint, DEFAULTS.zpages.path, host));
+  }
+  const tel = telemetryEndpoint(config);
+  if (tel) push("telemetry", urlOf(tel, "/metrics", host));
+  return out;
+}
+
+const LABEL: Record<CollectorEndpointKind, string> = { healthCheck: "health_check", zpages: "zpages", telemetry: "telemetry" };
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+async function probe(f: typeof fetch, url: string, timeoutMs: number): Promise<string | undefined> {
+  try {
+    const res = await f(url, { signal: AbortSignal.timeout(timeoutMs) });
+    await res.body?.cancel().catch(() => undefined);
+    return res.status === 200 ? undefined : `answered ${res.status}`;
+  } catch (err) {
+    const cause = (err as { cause?: { code?: string } }).cause?.code;
+    return `did not answer (${cause ?? (err as Error).message})`;
+  }
+}
+
+function collectorConfig(c: ObservedCollector): Record<string, unknown> {
+  if (c.configObject) return c.configObject;
+  if (!c.config) throw new Error(`collector "${c.name}" names no config`);
+  const value = load(readFileSync(resolve(process.cwd(), c.config), "utf8"));
+  if (!isRecord(value)) throw new Error(`collector "${c.name}": ${c.config} does not hold a YAML mapping`);
+  return value;
+}
+
+/** Observe each collector through the endpoints its config declares: one resource per collector. */
+export async function collectorHealthObserve(args: CollectorHealthObserveArgs): Promise<CollectorHealthObserveResult> {
+  const f = args._fetch ?? fetch;
+  const timeoutMs = args.timeoutMs ?? 5000;
+  const probes = Math.max(1, args.probes ?? 2);
+  const interval = args.probeIntervalMs ?? 1000;
+  const resources: CollectorHealthObserveResult["resources"] = [];
+  for (const c of args.collectors) {
+    let config: Record<string, unknown>;
+    try {
+      config = collectorConfig(c);
+    } catch (err) {
+      resources.push({ name: c.name, status: "unknown", detail: `config unreadable: ${(err as Error).message}` });
+      continue;
+    }
+    const endpoints = declaredEndpoints(config, c.host, c.endpoints);
+    if (!endpoints.some((e) => e.kind === "healthCheck")) {
+      resources.push({ name: c.name, status: "unknown", detail: "no health_check in service.extensions" });
+      continue;
+    }
+    const failures: string[] = [];
+    for (const e of endpoints) {
+      let why: string | undefined;
+      for (let i = 0; i < probes; i++) {
+        why = await probe(f, e.url, timeoutMs);
+        if (!why) break;
+        if (i + 1 < probes) await sleep(interval);
+      }
+      if (why) failures.push(`${LABEL[e.kind]} ${e.url} ${why}`);
+    }
+    resources.push(
+      failures.length === 0
+        ? { name: c.name, status: "in-sync", detail: endpoints.map((e) => `${LABEL[e.kind]} ok`).join(", ") }
+        : { name: c.name, status: "drifted", detail: failures.join("; ") },
+    );
+  }
+  return { resources };
+}

package/src/op/activities/exec.ts

@@ -0,0 +1,33 @@
+/**
+ * How the otel activities run a binary: a child process whose exit code,
+ * stdout and stderr are returned rather than thrown, so the caller decides
+ * what a non-zero exit means. Tests pass their own runner.
+ */
+
+import { execFile } from "node:child_process";
+
+export interface ExecResult {
+  /** The exit code, or null when the binary could not be started. */
+  code: number | null;
+  stdout: string;
+  stderr: string;
+  /** Why the binary could not be started (ENOENT and the like). */
+  error?: string;
+}
+
+export type ExecRunner = (bin: string, args: string[], opts?: { cwd?: string; timeoutMs?: number }) => Promise<ExecResult>;
+
+export const defaultExec: ExecRunner = (bin, args, opts = {}) =>
+  new Promise((resolve) => {
+    execFile(
+      bin,
+      args,
+      { cwd: opts.cwd, timeout: opts.timeoutMs ?? 120_000, maxBuffer: 32 * 1024 * 1024, encoding: "utf8" },
+      (err, stdout, stderr) => {
+        if (!err) return resolve({ code: 0, stdout, stderr });
+        const e = err as NodeJS.ErrnoException & { code?: unknown };
+        if (typeof e.code === "number") return resolve({ code: e.code, stdout, stderr });
+        resolve({ code: null, stdout: stdout ?? "", stderr: stderr ?? "", error: e.message });
+      },
+    );
+  });

package/src/op/activities/github.ts

@@ -0,0 +1,127 @@
+/**
+ * What the audit activities read from GitHub and write back to it: release
+ * lists over the REST API, and a sticky issue or a proposal pull request
+ * through `git` and `gh`. The prometheus lexicon's rule audit uses the issue
+ * half too.
+ */
+
+import { execFile } from "node:child_process";
+
+/** Runs `git` or `gh`, returning stdout. Rejects on a non-zero exit. */
+export type CommandRunner = (bin: "git" | "gh", args: string[], cwd: string) => Promise<string>;
+
+export const defaultRunner: CommandRunner = (bin, args, cwd) =>
+  new Promise((resolve, reject) => {
+    execFile(bin, args, { cwd, maxBuffer: 16 * 1024 * 1024, encoding: "utf8" }, (err, stdout, stderr) => {
+      if (err) reject(new Error(`${bin} ${args.join(" ")} failed: ${(stderr || err.message).trim()}`));
+      else resolve(stdout);
+    });
+  });
+
+export interface Release {
+  tag: string;
+  publishedAt?: string;
+}
+
+/** `v1.2.3` as numbers, or undefined when the tag is not a plain semver. */
+export function semverOf(tag: string): [number, number, number] | undefined {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(tag.trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : undefined;
+}
+
+export function compareSemver(a: string, b: string): number {
+  const x = semverOf(a);
+  const y = semverOf(b);
+  if (!x || !y) return a.localeCompare(b);
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] - y[i];
+  return 0;
+}
+
+/**
+ * The published, non-prerelease releases of `repo` (`owner/name`) with a
+ * plain semver tag, newest first. Reads one page of 100, which covers
+ * months of collector releases.
+ */
+export async function fetchReleases(repo: string, f: typeof fetch = fetch, token = process.env.GITHUB_TOKEN): Promise<Release[]> {
+  const headers: Record<string, string> = { Accept: "application/vnd.github+json" };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  const res = await f(`https://api.github.com/repos/${repo}/releases?per_page=100`, { headers });
+  if (!res.ok) throw new Error(`GitHub releases of ${repo}: HTTP ${res.status}`);
+  const body = (await res.json()) as Array<{ tag_name?: string; draft?: boolean; prerelease?: boolean; published_at?: string }>;
+  return body
+    .filter((r) => !r.draft && !r.prerelease && typeof r.tag_name === "string" && semverOf(r.tag_name))
+    .map((r) => ({ tag: r.tag_name!, ...(r.published_at ? { publishedAt: r.published_at } : {}) }))
+    .sort((a, b) => compareSemver(b.tag, a.tag));
+}
+
+/**
+ * Open an issue titled `title`, or edit the body of the open one that
+ * already has that title, so a scheduled audit keeps one issue current
+ * instead of opening one per run. Returns its URL.
+ */
+export async function stickyIssue(run: CommandRunner, cwd: string, title: string, body: string, labels: string[] = []): Promise<string> {
+  const listed = await run("gh", ["issue", "list", "--state", "open", "--search", `"${title}" in:title`, "--json", "number,title,url"], cwd);
+  const open = (JSON.parse(listed || "[]") as Array<{ number: number; title: string; url: string }>).find((i) => i.title === title);
+  if (open) {
+    await run("gh", ["issue", "edit", String(open.number), "--body", body], cwd);
+    return open.url;
+  }
+  const args = ["issue", "create", "--title", title, "--body", body];
+  for (const l of labels) args.push("--label", l);
+  return (await run("gh", args, cwd)).trim();
+}
+
+export interface ProposalFile {
+  /** Path relative to the repository root. */
+  path: string;
+  content: string;
+}
+
+export interface ProposeOptions {
+  /** The repository root. */
+  root: string;
+  branch: string;
+  title: string;
+  body: string;
+  files: ProposalFile[];
+  commitMessage: string;
+  remote?: string;
+  /** The branch the pull request targets. Default: the remote's default branch. */
+  base?: string;
+  /** A directory for the worktree the commit is made in. */
+  worktreeDir: string;
+}
+
+/**
+ * Commit `files` on `branch`, from the remote's default branch, in a
+ * worktree of its own (the checked-out branch and working tree are never
+ * touched), push it, and open a pull request, or edit the open one for that
+ * branch. Returns the pull request's URL.
+ */
+export async function proposePullRequest(run: CommandRunner, o: ProposeOptions): Promise<string> {
+  const remote = o.remote ?? "origin";
+  await run("git", ["fetch", remote], o.root);
+  let base = o.base;
+  if (!base) {
+    const head = (await run("git", ["symbolic-ref", "--short", `refs/remotes/${remote}/HEAD`], o.root).catch(() => `${remote}/main`)).trim();
+    base = head.startsWith(`${remote}/`) ? head.slice(remote.length + 1) : head;
+  }
+  await run("git", ["worktree", "add", "--force", "-B", o.branch, o.worktreeDir, `${remote}/${base}`], o.root);
+  try {
+    const { writeFileSync } = await import("node:fs");
+    const { join } = await import("node:path");
+    for (const f of o.files) writeFileSync(join(o.worktreeDir, f.path), f.content);
+    await run("git", ["add", ...o.files.map((f) => f.path)], o.worktreeDir);
+    await run("git", ["commit", "-m", o.commitMessage], o.worktreeDir);
+    await run("git", ["push", "--force", remote, `HEAD:refs/heads/${o.branch}`], o.worktreeDir);
+  } finally {
+    await run("git", ["worktree", "remove", "--force", o.worktreeDir], o.root).catch(() => undefined);
+  }
+  const listed = await run("gh", ["pr", "list", "--head", o.branch, "--state", "open", "--json", "number,url"], o.root);
+  const open = (JSON.parse(listed || "[]") as Array<{ number: number; url: string }>)[0];
+  if (open) {
+    await run("gh", ["pr", "edit", String(open.number), "--title", o.title, "--body", o.body], o.root);
+    return open.url;
+  }
+  return (await run("gh", ["pr", "create", "--head", o.branch, "--base", base, "--title", o.title, "--body", o.body], o.root)).trim();
+}

package/src/op/activities/index.ts

@@ -0,0 +1,19 @@
+/**
+ * otel Op activities (#3369), resolved by the core activity registry when a
+ * project's `chant.config.ts` lists the `otel` lexicon. Every function this
+ * module exports is an activity, bound by its export name, so the helpers
+ * behind them stay in their own files.
+ *
+ * - `otelcolValidate`, `otelcolComponents`: the collector binary's own
+ *   checks over a config file.
+ * - `collectorHealthObserve`: running collectors as the resources of a
+ *   `ConvergeOp({ observe })`.
+ * - `collectorAudit`: the lexicon's pins against upstream releases, the
+ *   step of `CollectorAuditOp`.
+ */
+export { otelcolValidate, otelcolComponents } from "./otelcol";
+export type { OtelcolValidateArgs, OtelcolValidateResult, OtelcolComponentsArgs, OtelcolComponentsResult, MissingComponent } from "./otelcol";
+export { collectorHealthObserve } from "./collector-health";
+export type { CollectorHealthObserveArgs, CollectorHealthObserveResult, ObservedCollector, CollectorEndpointKind } from "./collector-health";
+export { collectorAudit } from "./collector-audit";
+export type { CollectorAuditArgs, CollectorAuditResult, CollectorAuditFinding, CollectorAuditFindingKind, CollectorAuditMode } from "./collector-audit";

package/src/op/activities/otelcol.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, test } from "vitest";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { COLLECTOR_PIN } from "../../define";
+import type { ExecRunner } from "./exec";
+import {
+  configComponents,
+  missingComponents,
+  otelcolBin,
+  otelcolComponents,
+  otelcolValidate,
+  parseComponentsOutput,
+  parseOtelcolVersion,
+} from "./otelcol";
+
+const FIXTURE = readFileSync(join(import.meta.dirname, "..", "testdata", "otelcol-components-v0.130.0.yaml"), "utf8");
+
+const CONFIG = `receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+processors:
+  batch: {}
+exporters:
+  debug: {}
+  otlp/tempo:
+    endpoint: tempo:4317
+connectors:
+  spanmetrics: {}
+extensions:
+  health_check: {}
+service:
+  extensions: [health_check]
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [debug, otlp/tempo, spanmetrics]
+    metrics:
+      receivers: [spanmetrics]
+      exporters: [debug]
+`;
+
+function configFile(text = CONFIG): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-otelcol-op-"));
+  const file = join(dir, "collector.yaml");
+  writeFileSync(file, text);
+  return file;
+}
+
+/** A runner that answers `--version` with `version`, and records the calls. */
+function fakeExec(version: string, rest: Partial<Record<string, { code: number; stdout?: string; stderr?: string }>> = {}) {
+  const calls: string[][] = [];
+  const exec: ExecRunner = async (bin, args) => {
+    calls.push([bin, ...args]);
+    if (args[0] === "--version") return { code: 0, stdout: `otelcol-contrib version ${version}\n`, stderr: "" };
+    const r = rest[args[0]] ?? { code: 0 };
+    return { code: r.code, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+  };
+  return { exec, calls };
+}
+
+const PIN = COLLECTOR_PIN.version.replace(/^v/, "");
+
+describe("otelcolValidate", () => {
+  test("parses the version line the binary prints", () => {
+    expect(parseOtelcolVersion("otelcol-contrib version 0.130.0")).toBe("v0.130.0");
+    expect(parseOtelcolVersion("otelcol version v0.131.1-dev\n")).toBe("v0.131.1-dev");
+    expect(parseOtelcolVersion("no version here")).toBeUndefined();
+  });
+
+  test("the binary is bin, then $OTELCOL_BIN, then otelcol-contrib", () => {
+    expect(otelcolBin("/opt/otelcol", { OTELCOL_BIN: "x" })).toBe("/opt/otelcol");
+    expect(otelcolBin(undefined, { OTELCOL_BIN: "x" })).toBe("x");
+    expect(otelcolBin(undefined, {})).toBe("otelcol-contrib");
+  });
+
+  test("at the pinned version, runs validate over the config and passes", async () => {
+    const file = configFile();
+    const { exec, calls } = fakeExec(PIN, { validate: { code: 0, stdout: "" } });
+    const r = await otelcolValidate({ config: file, bin: "otelcol-contrib", _exec: exec });
+    expect(r).toMatchObject({ ok: true, version: COLLECTOR_PIN.version, bin: "otelcol-contrib" });
+    expect(calls[1]).toEqual(["otelcol-contrib", "validate", `--config=${file}`]);
+  });
+
+  test("refuses a binary at another version, before validating", async () => {
+    const { exec, calls } = fakeExec("0.140.0");
+    await expect(otelcolValidate({ config: configFile(), _exec: exec })).rejects.toThrow(/is v0\.140\.0.*COLLECTOR_PIN/);
+    expect(calls).toHaveLength(1);
+  });
+
+  test("with a version given, checks the binary against that one instead", async () => {
+    const ok = fakeExec("0.140.0", { validate: { code: 0 } });
+    await expect(otelcolValidate({ config: configFile(), version: "v0.140.0", _exec: ok.exec })).resolves.toMatchObject({ version: "v0.140.0" });
+    const off = fakeExec(PIN);
+    await expect(otelcolValidate({ config: configFile(), version: "0.140.0", _exec: off.exec })).rejects.toThrow(/the step asks for v0\.140\.0/);
+  });
+
+  test("a config the binary rejects fails the step with its output", async () => {
+    const { exec } = fakeExec(PIN, { validate: { code: 1, stderr: "Error: invalid configuration: receivers::otlp: unknown field" } });
+    await expect(otelcolValidate({ config: configFile(), _exec: exec })).rejects.toThrow(/rejected .*unknown field/s);
+  });
+
+  test("a binary that will not start says so", async () => {
+    const exec: ExecRunner = async () => ({ code: null, stdout: "", stderr: "", error: "spawn otelcol-contrib ENOENT" });
+    await expect(otelcolValidate({ config: configFile(), bin: "otelcol-contrib", _exec: exec })).rejects.toThrow(/could not run otelcol-contrib: spawn otelcol-contrib ENOENT/);
+  });
+});
+
+describe("otelcolComponents", () => {
+  test("parses the v0.130.0 components output (pins the unstable format)", () => {
+    const list = parseComponentsOutput(FIXTURE);
+    expect(list.version).toBe("v0.130.0");
+    expect([...list.components.receiver].sort()).toEqual(["k8s_cluster", "otlp", "prometheus"]);
+    expect([...list.components.processor].sort()).toEqual(["batch", "memory_limiter", "tail_sampling"]);
+    expect([...list.components.exporter].sort()).toEqual(["debug", "otlp", "prometheus"]);
+    expect([...list.components.connector].sort()).toEqual(["forward", "spanmetrics"]);
+    expect([...list.components.extension].sort()).toEqual(["health_check", "zpages"]);
+  });
+
+  test("reads the older forms too: plain name lists and mappings", () => {
+    const list = parseComponentsOutput("receivers: [otlp, jaeger]\nexporters:\n  debug: {}\n  otlp: {}\n");
+    expect([...list.components.receiver]).toEqual(["otlp", "jaeger"]);
+    expect([...list.components.exporter]).toEqual(["debug", "otlp"]);
+    expect(list.version).toBeUndefined();
+  });
+
+  test("output with no component sections is an error, not an empty list", () => {
+    expect(() => parseComponentsOutput("buildinfo:\n  version: 0.130.0\n")).toThrow(/listed no receivers/);
+    expect(() => parseComponentsOutput("::: not yaml")).toThrow();
+  });
+
+  test("the config's components by kind, and the ones the binary lacks", () => {
+    const used = configComponents({ receivers: { otlp: {} }, exporters: { "otlp/tempo": {}, "loki/x": {} }, connectors: { spanmetrics: {} } });
+    expect(used.exporter).toEqual(["otlp/tempo", "loki/x"]);
+    const missing = missingComponents(used, parseComponentsOutput(FIXTURE));
+    expect(missing).toEqual([{ kind: "exporter", id: "loki/x", type: "loki" }]);
+  });
+
+  test("a renamed built-in counts under either name", () => {
+    const list = parseComponentsOutput("exporters:\n  - name: otlp_grpc\nreceivers:\n  - name: otlp\n");
+    expect(missingComponents(configComponents({ exporters: { otlp: {} } }), list)).toEqual([]);
+    const old = parseComponentsOutput("exporters:\n  - name: otlp\nreceivers:\n  - name: otlp\n");
+    expect(missingComponents(configComponents({ exporters: { otlp_grpc: {} } }), old)).toEqual([]);
+  });
+
+  test("passes a config the binary was built for", async () => {
+    const { exec } = fakeExec(PIN, { components: { code: 0, stdout: FIXTURE } });
+    const r = await otelcolComponents({ config: configFile(), _exec: exec });
+    expect(r.missing).toEqual([]);
+    expect(r.used.connector).toEqual(["spanmetrics"]);
+    expect(r.version).toBe("v0.130.0");
+  });
+
+  test("refuses a config with a component the binary was not built with", async () => {
+    const { exec } = fakeExec(PIN, { components: { code: 0, stdout: FIXTURE } });
+    const config = configFile(CONFIG.replace("  debug: {}", "  debug: {}\n  datadog: {}"));
+    await expect(otelcolComponents({ config, _exec: exec })).rejects.toThrow(/1 component\(s\).*exporter datadog/s);
+  });
+});