@intentius/chant-lexicon-otel 0.124.46 → 0.124.49

package/dist/validate.js

@@ -33,6 +33,7 @@ export const REQUIRED_NAMES = [
     "PrometheusExporter",
     "GoogleCloudExporter",
     "LoadBalancingExporter",
+    "ClickHouseExporter",
     "SpanMetricsConnector",
     "ServiceGraphConnector",
     "RoutingConnector",

package/dist/workspace-links.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The workspace links an otel member's declarations state (#4397): each
+ * table a `clickhouse` exporter writes, and each column its insert names, as
+ * a link to the sql member that declares them (#3931).
+ *
+ * | Link | Output |
+ * |---|---|
+ * | the table | `<database>.<table>` |
+ * | a column | `<database>.<table>.<column>`, anchored on the table |
+ *
+ * The exporter's config does not name the sql member, so each link is
+ * matched to the one member that exposes the table (`resolveLinks` in
+ * chant's `workspace/links.ts`). `chant workspace check` then fails (WSP093)
+ * when a table the exporter writes, or a column its insert names, is renamed
+ * or dropped in the sql member. The tables and columns come from
+ * `clickhouse-tables.ts`, which OTEL129 reads in one build root.
+ *
+ * A config value chant can't read without the environment, such as a
+ * database set from `${env:CH_DB}`, is a gap (WSP099), and the tables it
+ * names are not linked.
+ */
+import type { Declarable } from "@intentius/chant/declarable";
+import type { LexiconWorkspaceLinks } from "@intentius/chant/graph-ir";
+export declare function otelWorkspaceLinks(entities: ReadonlyMap<string, Declarable>): LexiconWorkspaceLinks | undefined;
+//# sourceMappingURL=workspace-links.d.ts.map

package/dist/workspace-links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-links.d.ts","sourceRoot":"","sources":["../src/workspace-links.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAwB,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAK7F,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,qBAAqB,GAAG,SAAS,CAqB/G"}

package/dist/workspace-links.js

@@ -0,0 +1,49 @@
+/**
+ * The workspace links an otel member's declarations state (#4397): each
+ * table a `clickhouse` exporter writes, and each column its insert names, as
+ * a link to the sql member that declares them (#3931).
+ *
+ * | Link | Output |
+ * |---|---|
+ * | the table | `<database>.<table>` |
+ * | a column | `<database>.<table>.<column>`, anchored on the table |
+ *
+ * The exporter's config does not name the sql member, so each link is
+ * matched to the one member that exposes the table (`resolveLinks` in
+ * chant's `workspace/links.ts`). `chant workspace check` then fails (WSP093)
+ * when a table the exporter writes, or a column its insert names, is renamed
+ * or dropped in the sql member. The tables and columns come from
+ * `clickhouse-tables.ts`, which OTEL129 reads in one build root.
+ *
+ * A config value chant can't read without the environment, such as a
+ * database set from `${env:CH_DB}`, is a gap (WSP099), and the tables it
+ * names are not linked.
+ */
+import { clickhouseExportersOf } from "./clickhouse-tables.js";
+import { collectorConfig } from "./collector.js";
+export function otelWorkspaceLinks(entities) {
+    const keyOf = new Map();
+    for (const [key, e] of entities) {
+        const c = e;
+        if (c.componentKind === "exporter" && c.componentType === "clickhouse" && typeof c.componentId === "string")
+            keyOf.set(c.componentId, key);
+    }
+    if (keyOf.size === 0)
+        return undefined;
+    const links = [];
+    const gaps = [];
+    for (const exp of clickhouseExportersOf(collectorConfig(entities.values()))) {
+        const entity = keyOf.get(exp.id) ?? exp.id;
+        for (const u of exp.unread)
+            gaps.push(`exporter ${exp.id} (${entity}) sets ${u}, which is read from the environment, so the tables it names are not linked`);
+        for (const t of exp.tables) {
+            const table = `${exp.database}.${t.name}`;
+            links.push({ output: table, entity });
+            for (const column of t.columns)
+                links.push({ output: `${table}.${column}`, anchor: table, entity });
+        }
+    }
+    if (links.length === 0 && gaps.length === 0)
+        return undefined;
+    return { links, ...(gaps.length ? { gaps } : {}) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-otel",
-  "version": "0.124.46",
+  "version": "0.124.49",
   "description": "OpenTelemetry Collector lexicon for chant — typed receivers, processors, exporters, connectors, extensions and pipelines, serialized to collector YAML",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -74,11 +74,12 @@
   },
   "devDependencies": {
     "@intentius/chant": "*",
+    "@intentius/chant-lexicon-sql": "*",
     "@types/js-yaml": "^4.0.9",
     "tsc-alias": "^1.8.17",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.46"
+    "@intentius/chant": "^0.124.49"
   }
 }

package/src/build/capability-plugin.ts

@@ -0,0 +1,30 @@
+/**
+ * `otelCapabilityPlugin`, the otel lexicon's capability plugin (#3374). One
+ * build verb, `ocb-build`, contributed through core's `CapabilityPlugin`
+ * contract as helm contributes `helm-upgrade`: a project declaring
+ * `lexicons: ["otel"]` gets it registered when it runs components.
+ */
+import type { Capability } from "@intentius/chant/components/capability";
+import type { BuildSpec } from "@intentius/chant/components/component";
+import { ownPackageVersion, type CapabilityPlugin } from "@intentius/chant/components/capability-plugin";
+import { ocbBuildCapability, type OcbBuildInput } from "./ocb-build";
+
+export const OTEL_VERB_FAMILIES = {
+  build: ["ocb-build"],
+} as const;
+
+export const otelCapabilityPlugin: CapabilityPlugin = {
+  name: "otel",
+  version: ownPackageVersion(import.meta.url),
+  capabilities(): Array<Capability<never, unknown>> {
+    return [ocbBuildCapability as Capability<never, unknown>];
+  },
+  families(): Record<string, readonly string[]> {
+    return OTEL_VERB_FAMILIES;
+  },
+};
+
+/** A component's `build` field for `ocb-build`: `build: ocbBuild({ config: "dist/builder-config.yaml" })`. */
+export function ocbBuild(input: OcbBuildInput): BuildSpec {
+  return { kind: "ocb-build", ...input };
+}

package/src/build/ocb-build.ts

@@ -0,0 +1,73 @@
+/**
+ * `ocb-build`, the build verb for a custom collector (#3374): run the
+ * OpenTelemetry Collector Builder over the `builder-config.yaml` a
+ * `Distribution` writes, and hand the directory it generates on as a `dir`
+ * artifact. That directory holds the generated sources and the binary, so a
+ * `docker-build` step whose `context` is the directory (with a Dockerfile the
+ * component provides) builds the collector image, and the rest of the
+ * component's path (SBOM, sign, attest, publish by digest, deploy) is the
+ * one any image takes.
+ *
+ * The output directory is the manifest's `dist.output_path`. ocb's own
+ * default is a fresh temporary directory, which a later step could not name,
+ * so a manifest without one is refused before ocb runs.
+ */
+
+import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { load } from "js-yaml";
+import type { Capability } from "@intentius/chant/components/capability";
+import { defaultProcessRunner, q, requireTool, type ProcessRunner } from "@intentius/chant/components/verbs/process-runner";
+
+export interface OcbBuildInput {
+  /** The builder manifest, e.g. `dist/builder-config.yaml`. */
+  config: string;
+  /** The builder binary. Default: `ocb`. */
+  ocb?: string;
+  /** Generate the sources without compiling them (`--skip-compilation`). */
+  skipCompilation?: boolean;
+}
+
+export interface OcbBuildOutput {
+  /** The artifact kind: a directory, for `docker-build`'s `context`. */
+  kind: "dir";
+  /** The directory ocb wrote, the manifest's `dist.output_path` resolved against the manifest's directory. */
+  dir: string;
+  /** `sha256:` over the manifest's bytes: the same manifest names the same build. */
+  manifestDigest: string;
+}
+
+/** The output directory a manifest names, resolved the way ocb resolves it: relative to the working directory ocb runs in. */
+export function ocbOutputPath(manifestText: string, cwd: string): string | undefined {
+  const doc = load(manifestText) as { dist?: { output_path?: unknown } } | undefined;
+  const out = doc?.dist?.output_path;
+  if (typeof out !== "string" || out.trim() === "") return undefined;
+  return isAbsolute(out) ? out : resolve(cwd, out);
+}
+
+export function createOcbBuildCapability(runner: ProcessRunner = defaultProcessRunner()): Capability<OcbBuildInput, OcbBuildOutput> {
+  return {
+    kind: "ocb-build",
+    async run(_ctx, input) {
+      const text = readFileSync(input.config, "utf8");
+      // ocb resolves output_path against its working directory; run it in the manifest's.
+      const cwd = dirname(resolve(input.config));
+      const dir = ocbOutputPath(text, cwd);
+      if (!dir) {
+        throw new Error(
+          `ocb-build: ${input.config} sets no dist.output_path, so ocb would write to a temporary directory no later step can name. Set dist.output_path on the Distribution.`,
+        );
+      }
+      const ocb = input.ocb ?? "ocb";
+      await requireTool(runner, ocb, "build a custom collector from a Distribution");
+      const flags = input.skipCompilation ? " --skip-compilation" : "";
+      await runner.run(`${q(ocb)} --config ${q(resolve(input.config))}${flags}`, { cwd });
+      const manifestDigest = `sha256:${createHash("sha256").update(text).digest("hex")}`;
+      return { kind: "dir", dir, manifestDigest };
+    },
+  };
+}
+
+/** Default `ocb-build` capability, backed by the real process runner. */
+export const ocbBuildCapability: Capability<OcbBuildInput, OcbBuildOutput> = createOcbBuildCapability();

package/src/clickhouse-exporter.e2e.test.ts

@@ -0,0 +1,208 @@
+/**
+ * A contrib v0.130.0 collector with `create_schema: false` writes logs,
+ * traces and every metric type into tables built from the sql lexicon's
+ * `OtelTables` (#4397).
+ *
+ * A scratch ClickHouse of the sql lexicon's pinned image gets the tables
+ * `OtelTables` declares, created from their DDL in the serializer's apply
+ * order, so the exporter finds them and creates nothing. A collector of
+ * `COLLECTOR_IMAGE` on the same Docker network runs the config chant builds
+ * from a `ClickHouseExporter`. One OTLP/HTTP request per signal goes in, and
+ * every table, the trace-id lookup table filled by its materialized view
+ * included, must then hold a row. Skips cleanly without Docker.
+ */
+
+import { execFile } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { expandComposite } from "@intentius/chant/composite";
+import type { Declarable } from "@intentius/chant/declarable";
+import type { SerializerResult } from "@intentius/chant/serializer";
+import { OtelTables } from "@intentius/chant-lexicon-sql/clickhouse";
+import { sqlSerializer } from "@intentius/chant-lexicon-sql/serializer";
+import { dockerAvailable, startScratchServer, type ScratchServer } from "@intentius/chant-lexicon-sql/clickhouse/container";
+import { clickhouseQuery } from "@intentius/chant-lexicon-sql/clickhouse/http";
+import { clickhouseImage } from "@intentius/chant-lexicon-sql/spec/pin";
+import { collectorYaml } from "./collector";
+import { ClickHouseExporter, OtlpReceiver } from "./components";
+import { Pipeline } from "./pipeline";
+import { COLLECTOR_IMAGE } from "./platform";
+
+const exec = promisify(execFile);
+const enabled = await dockerAvailable();
+const DB = "otel_4397";
+const suffix = `${Date.now().toString(36)}-${process.pid}`;
+const network = `chant-otel-4397-${suffix}`;
+const collectorName = `chant-otel-4397-col-${suffix}`;
+const dir = mkdtempSync(join(tmpdir(), "chant-otel-4397-"));
+let server: ScratchServer | undefined;
+let otlpUrl = "";
+
+const q = <T = Record<string, unknown>>(sql: string) => clickhouseQuery<T>(server!.endpoint, sql);
+
+/** The tables, from `OtelTables`, in the order the sql serializer applies them. */
+function tablesDdl(): string[] {
+  const entities = new Map<string, Declarable>();
+  for (const [k, v] of expandComposite("otel", OtelTables({ database: DB }))) entities.set(k, v);
+  const primary = (sqlSerializer.serialize(entities) as SerializerResult).primary;
+  const order = (JSON.parse(primary) as { applyOrder: string[] }).applyOrder;
+  return order.map((k) => (entities.get(k) as unknown as { props: { ddl: string } }).props.ddl);
+}
+
+beforeAll(async () => {
+  if (!enabled) return;
+  server = await startScratchServer(clickhouseImage(), { namePrefix: "chant-otel-4397-ch" });
+  await q(`CREATE DATABASE ${DB}`);
+  for (const ddl of tablesDdl()) await q(ddl);
+
+  const otlp = new OtlpReceiver({ protocols: { http: { endpoint: "0.0.0.0:4318" } } });
+  const clickhouse = new ClickHouseExporter({ endpoint: `tcp://${server.name}:9000`, database: DB, create_schema: false, async_insert: false });
+  const yaml = collectorYaml([
+    otlp,
+    clickhouse,
+    ...(["logs", "traces", "metrics"] as const).map((signal) => new Pipeline({ signal, receivers: [otlp], exporters: [clickhouse] })),
+  ]);
+  writeFileSync(join(dir, "config.yaml"), yaml);
+
+  await exec("docker", ["network", "create", network]);
+  await exec("docker", ["network", "connect", network, server.name]);
+  await exec(
+    "docker",
+    ["run", "-d", "--name", collectorName, "--network", network, "-p", "127.0.0.1::4318", "-v", `${dir}:/etc/otelcol-contrib:ro`, COLLECTOR_IMAGE, "--config=/etc/otelcol-contrib/config.yaml"],
+    { timeout: 600_000 },
+  );
+  const { stdout } = await exec("docker", ["port", collectorName, "4318/tcp"]);
+  otlpUrl = `http://${stdout.trim().split("\n")[0]}`;
+}, 900_000);
+
+afterAll(async () => {
+  await exec("docker", ["rm", "-f", collectorName]).catch(() => undefined);
+  await server?.stop();
+  await exec("docker", ["network", "rm", network]).catch(() => undefined);
+  rmSync(dir, { recursive: true, force: true });
+});
+
+const now = BigInt(Date.now()) * 1_000_000n;
+const ns = (offsetMs = 0) => String(now + BigInt(offsetMs) * 1_000_000n);
+const resource = { attributes: [{ key: "service.name", value: { stringValue: "chant-e2e" } }] };
+const TRACE_ID = "5b8efff798038103d269b633813fc60c";
+
+const PAYLOADS: Record<string, unknown> = {
+  "/v1/logs": {
+    resourceLogs: [{ resource, scopeLogs: [{ scope: { name: "e2e" }, logRecords: [{ timeUnixNano: ns(), severityText: "INFO", severityNumber: 9, body: { stringValue: "hello" }, traceId: TRACE_ID }] }] }],
+  },
+  "/v1/traces": {
+    resourceSpans: [
+      {
+        resource,
+        scopeSpans: [
+          {
+            scope: { name: "e2e" },
+            spans: [
+              {
+                traceId: TRACE_ID,
+                spanId: "eee19b7ec3c1b174",
+                name: "op",
+                kind: 2,
+                startTimeUnixNano: ns(),
+                endTimeUnixNano: ns(5),
+                events: [{ timeUnixNano: ns(1), name: "evt" }],
+                status: { code: 1 },
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+  "/v1/metrics": {
+    resourceMetrics: [
+      {
+        resource,
+        scopeMetrics: [
+          {
+            scope: { name: "e2e" },
+            metrics: [
+              { name: "g", gauge: { dataPoints: [{ timeUnixNano: ns(), asDouble: 1 }] } },
+              { name: "s", sum: { aggregationTemporality: 2, isMonotonic: true, dataPoints: [{ startTimeUnixNano: ns(-1000), timeUnixNano: ns(), asInt: "3" }] } },
+              {
+                name: "h",
+                histogram: { aggregationTemporality: 2, dataPoints: [{ startTimeUnixNano: ns(-1000), timeUnixNano: ns(), count: "2", sum: 3, bucketCounts: ["1", "1"], explicitBounds: [1] }] },
+              },
+              {
+                name: "eh",
+                exponentialHistogram: {
+                  aggregationTemporality: 2,
+                  dataPoints: [{ startTimeUnixNano: ns(-1000), timeUnixNano: ns(), count: "2", sum: 3, scale: 0, zeroCount: "0", positive: { offset: 0, bucketCounts: ["2"] } }],
+                },
+              },
+              { name: "sm", summary: { dataPoints: [{ startTimeUnixNano: ns(-1000), timeUnixNano: ns(), count: "2", sum: 3, quantileValues: [{ quantile: 0.5, value: 1 }] }] } },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+};
+
+/** POST until the collector takes it: it is still starting for the first few seconds. */
+async function send(path: string, body: unknown): Promise<void> {
+  const deadline = Date.now() + 120_000;
+  let last = "";
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${otlpUrl}${path}`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+      if (res.ok) return;
+      last = `${res.status} ${await res.text()}`;
+    } catch (err) {
+      last = String(err);
+    }
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+  throw new Error(`the collector did not take ${path}: ${last}`);
+}
+
+const TABLES = [
+  "otel_logs",
+  "otel_traces",
+  "otel_traces_trace_id_ts",
+  "otel_metrics_gauge",
+  "otel_metrics_sum",
+  "otel_metrics_summary",
+  "otel_metrics_histogram",
+  "otel_metrics_exponential_histogram",
+];
+
+describe.skipIf(!enabled)(`a ${COLLECTOR_IMAGE} clickhouse exporter writes into OtelTables (#4397)`, () => {
+  test(
+    "logs, traces and every metric type land in the declared tables, and the exporter created none",
+    async () => {
+      for (const [path, body] of Object.entries(PAYLOADS)) await send(path, body);
+
+      const counts = async () => Object.fromEntries(await Promise.all(TABLES.map(async (t) => [t, Number((await q<{ n: string }>(`SELECT count() AS n FROM ${DB}.${t}`))[0].n)] as const)));
+      const deadline = Date.now() + 120_000;
+      let seen = await counts();
+      while (Object.values(seen).some((n) => n === 0) && Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 1000));
+        seen = await counts();
+      }
+      if (Object.values(seen).some((n) => n === 0)) {
+        const logs = await exec("docker", ["logs", "--tail", "60", collectorName]).catch((e) => ({ stdout: "", stderr: String(e) }));
+        console.error(logs.stdout, logs.stderr);
+      }
+      expect(Object.entries(seen).filter(([, n]) => n === 0).map(([t]) => t)).toEqual([]);
+
+      const [span] = await q<{ ServiceName: string; SpanName: string; events: string }>(`SELECT ServiceName, SpanName, length(Events.Name) AS events FROM ${DB}.otel_traces`);
+      expect(span).toMatchObject({ ServiceName: "chant-e2e", SpanName: "op" });
+      expect(Number(span.events)).toBe(1);
+
+      // create_schema: false: the database holds the declared tables and view, and nothing else.
+      const objects = (await q<{ name: string }>(`SELECT name FROM system.tables WHERE database = '${DB}' ORDER BY name`)).map((r) => r.name);
+      expect(objects).toEqual([...TABLES, "otel_traces_trace_id_ts_mv"].sort());
+    },
+    300_000,
+  );
+});

package/src/clickhouse-tables.test.ts

@@ -0,0 +1,216 @@
+/**
+ * The clickhouse exporter's tables (#4397): which tables and columns an
+ * exporter config writes, OTEL129 over a build root that also declares them
+ * with the sql lexicon's `OtelTables`, and the workspace links the otel
+ * lexicon states for them.
+ */
+
+import { describe, expect, test } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { build } from "@intentius/chant/build";
+import type { Declarable } from "@intentius/chant/declarable";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { OtelTables } from "@intentius/chant-lexicon-sql/clickhouse";
+import { sqlSerializer } from "@intentius/chant-lexicon-sql/serializer";
+import { CLICKHOUSE_EXPORTER_COLUMNS, clickhouseExportersOf, clickhouseExporterTargets } from "./clickhouse-tables";
+import { collectorYaml } from "./collector";
+import { COLLECTOR_PIN } from "./define";
+import { ClickHouseExporter, OtlpReceiver, BatchProcessor } from "./components";
+import { Pipeline } from "./pipeline";
+import { otel129 } from "./lint/post-synth/otel129";
+import { otelPlugin } from "./plugin";
+import { otelSerializer } from "./serializer";
+import { otelWorkspaceLinks } from "./workspace-links";
+import { pkgDir } from "./import/testdata/fixtures";
+
+const ALL = new Set(["logs", "traces", "metrics"]);
+
+describe("clickhouseExporterTargets", () => {
+  test("the exporter's defaults at v0.130.0: database default, otel_* tables, create_schema true", () => {
+    const t = clickhouseExporterTargets("clickhouse", { endpoint: "tcp://ch:9000" }, ALL);
+    expect(t.database).toBe("default");
+    expect(t.createSchema).toBe(true);
+    expect(t.tables.map((x) => x.name)).toEqual([
+      "otel_logs",
+      "otel_traces",
+      "otel_metrics_gauge",
+      "otel_metrics_sum",
+      "otel_metrics_summary",
+      "otel_metrics_histogram",
+      "otel_metrics_exponential_histogram",
+    ]);
+  });
+
+  test("database: the option wins unless it is default, then the endpoint's path", () => {
+    expect(clickhouseExporterTargets("c", { endpoint: "tcp://ch:9000/fromdsn", database: "otel" }, ALL).database).toBe("otel");
+    expect(clickhouseExporterTargets("c", { endpoint: "tcp://ch:9000/fromdsn", database: "default" }, ALL).database).toBe("fromdsn");
+    expect(clickhouseExporterTargets("c", { endpoint: "tcp://ch:9000/fromdsn" }, ALL).database).toBe("fromdsn");
+  });
+
+  test("only the tables of the signals whose pipelines use the exporter", () => {
+    const t = clickhouseExporterTargets("c", { endpoint: "tcp://ch:9000", traces_table_name: "spans" }, new Set(["traces"]));
+    expect(t.tables.map((x) => [x.key, x.name])).toEqual([["traces_table_name", "spans"]]);
+  });
+
+  test("metric names: metrics_tables per type; the deprecated metrics_table_name is a prefix only when none is set", () => {
+    const named = clickhouseExporterTargets("c", { endpoint: "tcp://ch:9000", metrics_table_name: "m", metrics_tables: { sum: { name: "s" } } }, new Set(["metrics"]));
+    expect(named.tables.map((x) => x.name)).toEqual(["otel_metrics_gauge", "s", "otel_metrics_summary", "otel_metrics_histogram", "otel_metrics_exponential_histogram"]);
+    const prefixed = clickhouseExporterTargets("c", { endpoint: "tcp://ch:9000", metrics_table_name: "m" }, new Set(["metrics"]));
+    expect(prefixed.tables.map((x) => x.name)).toEqual(["m_gauge", "m_sum", "m_summary", "m_histogram", "m_exponential_histogram"]);
+  });
+
+  test("a value read from the environment is not guessed", () => {
+    const t = clickhouseExporterTargets("c", { endpoint: "tcp://ch:9000", database: "${env:CH_DB}" }, ALL);
+    expect(t.tables).toEqual([]);
+    expect(t.unread).toEqual(["database ${env:CH_DB}"]);
+    const named = clickhouseExporterTargets("c", { endpoint: "tcp://ch:9000", logs_table_name: "${env:T}" }, new Set(["logs"]));
+    expect(named.tables).toEqual([]);
+    expect(named.unread).toEqual(["logs_table_name ${env:T}"]);
+  });
+
+  test("the insert columns are columns OtelTables declares, Nested fields under their column", () => {
+    const t = OtelTables({});
+    const cols = (e: unknown) => (e as { props: { columns: Array<{ name: string }> } }).props.columns.map((c) => c.name);
+    expect(cols(t.logs)).toEqual(expect.arrayContaining([...CLICKHOUSE_EXPORTER_COLUMNS.logs]));
+    expect(cols(t.traces)).toEqual(expect.arrayContaining([...CLICKHOUSE_EXPORTER_COLUMNS.traces]));
+    expect(cols(t.metricsGauge)).toEqual(expect.arrayContaining([...CLICKHOUSE_EXPORTER_COLUMNS.gauge]));
+    expect(cols(t.metricsSum)).toEqual(expect.arrayContaining([...CLICKHOUSE_EXPORTER_COLUMNS.sum]));
+    expect(cols(t.metricsSummary)).toEqual(expect.arrayContaining([...CLICKHOUSE_EXPORTER_COLUMNS.summary]));
+    expect(cols(t.metricsHistogram)).toEqual(expect.arrayContaining([...CLICKHOUSE_EXPORTER_COLUMNS.histogram]));
+    expect(cols(t.metricsExponentialHistogram)).toEqual(expect.arrayContaining([...CLICKHOUSE_EXPORTER_COLUMNS.exponential_histogram]));
+  });
+});
+
+describe("ClickHouseExporter", () => {
+  test("is a built-in at COLLECTOR_PIN, with an endpoint check", () => {
+    expect(ClickHouseExporter.definition.builtin).toBe(true);
+    expect(ClickHouseExporter.definition.pin.version).toBe(COLLECTOR_PIN.version);
+    const validate = ClickHouseExporter.definition.validate as (c: unknown) => string[];
+    expect(validate({ endpoint: "" })).toEqual(["endpoint is empty; the exporter requires it"]);
+    expect(validate({ endpoint: "clickhouse 9000" })[0]).toMatch(/is not a URL/);
+    expect(validate({ endpoint: "${env:CH_URL}" })).toEqual([]);
+    expect(validate({ endpoint: "tcp://ch:9000" })).toEqual([]);
+  });
+});
+
+/** A collector writing every signal through one clickhouse exporter. */
+function collector(exporter: Record<string, unknown>): Declarable[] {
+  const otlp = new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:4317" } } });
+  const batch = new BatchProcessor({});
+  const clickhouse = new ClickHouseExporter({ endpoint: "tcp://clickhouse:9000", ...exporter } as never);
+  return [
+    otlp,
+    batch,
+    clickhouse,
+    ...(["logs", "traces", "metrics"] as const).map((signal) => new Pipeline({ signal, receivers: [otlp], processors: [batch], exporters: [clickhouse] })),
+  ];
+}
+
+function ctxOf(otel: Declarable[], sql: object): PostSynthContext {
+  const entities = new Map<string, Declarable>();
+  otel.forEach((e, i) => entities.set(`otel${i}`, e));
+  for (const [k, e] of Object.entries(sql)) if (e) entities.set(k, e as Declarable);
+  return { outputs: new Map([["otel", collectorYaml(otel)]]), entities, buildResult: { outputs: new Map(), entities, warnings: [], errors: [], sourceFileCount: 1 } } as PostSynthContext;
+}
+
+describe("OTEL129: the exporter's tables against the sql build in the same root", () => {
+  test("silent when the build declares the tables and create_schema is false", () => {
+    expect(otel129.check(ctxOf(collector({ database: "otel", create_schema: false }), OtelTables({ database: "otel" })))).toEqual([]);
+  });
+
+  test("a renamed table fails, naming the exporter's key and the declared tables", () => {
+    const diags = otel129.check(ctxOf(collector({ database: "otel", create_schema: false }), OtelTables({ database: "otel", tables: { logs: "app_logs" } })));
+    expect(diags.map((d) => [d.checkId, d.severity, d.entity])).toEqual([["OTEL129", "error", "clickhouse"]]);
+    expect(diags[0].message).toMatch(/writes logs to otel\.otel_logs \(logs_table_name\), which the sql build does not declare/);
+    expect(diags[0].message).toContain("otel.app_logs");
+  });
+
+  test("another database fails every table", () => {
+    const diags = otel129.check(ctxOf(collector({ create_schema: false }), OtelTables({ database: "otel" })));
+    expect(diags).toHaveLength(7);
+    expect(diags.every((d) => d.severity === "error" && /default\.otel_/.test(d.message))).toBe(true);
+  });
+
+  test("a column the insert names but the table lacks fails", () => {
+    const tables = OtelTables({}) as unknown as Record<string, Declarable>;
+    const logs = tables.logs as unknown as { props: { columns: Array<{ name: string }> } };
+    logs.props.columns = logs.props.columns.filter((c) => c.name !== "Body" && c.name !== "LogAttributes");
+    const diags = otel129.check(ctxOf(collector({ create_schema: false }), tables));
+    expect(diags.map((d) => d.message)).toEqual([expect.stringMatching(/inserts logs into default\.otel_logs with columns Body, LogAttributes, which the declared table does not have/)]);
+  });
+
+  test("create_schema left at true warns for the declared tables", () => {
+    const diags = otel129.check(ctxOf(collector({}), OtelTables({})));
+    expect(diags.map((d) => [d.severity, d.entity])).toEqual([["warning", "clickhouse"]]);
+    expect(diags[0].message).toMatch(/create_schema true \(the default\).*default\.otel_logs/);
+  });
+
+  test("a root with no sql ClickHouse tables is not checked", () => {
+    expect(otel129.check(ctxOf(collector({}), {}))).toEqual([]);
+  });
+
+  test("runs in a real build of one root that uses both lexicons, and fails when a table is renamed", async () => {
+    // A fresh project per build: a module once imported is not read again.
+    const run = async (logs: string) => {
+      const dir = mkdtempSync(join(pkgDir, ".roundtrip-tmp-"));
+      try {
+        mkdirSync(join(dir, "src"));
+        writeFileSync(join(dir, "chant.config.ts"), 'export default { lexicons: ["otel", "sql"] };\n');
+        writeFileSync(join(dir, "package.json"), '{ "name": "otel-clickhouse-root", "private": true, "type": "module" }\n');
+        writeFileSync(
+          join(dir, "src", "main.ts"),
+          [
+            'import { ClickHouseExporter, OtlpReceiver, Pipeline } from "@intentius/chant-lexicon-otel";',
+            'import { OtelTables } from "@intentius/chant-lexicon-sql/clickhouse";',
+            `export const otelTables = OtelTables({ database: "otel", tables: { logs: "${logs}" } });`,
+            'export const otlp = new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:4317" } } });',
+            'export const clickhouse = new ClickHouseExporter({ endpoint: "tcp://clickhouse:9000", database: "otel", create_schema: false });',
+            'export const logs = new Pipeline({ signal: "logs", receivers: [otlp], exporters: [clickhouse] });',
+            "",
+          ].join("\n"),
+        );
+        const result = await build(join(dir, "src"), [otelSerializer, sqlSerializer]);
+        expect(result.errors).toEqual([]);
+        // chant build hands each lexicon's checks its own output and every entity.
+        return otel129.check({ outputs: new Map([["otel", result.outputs.get("otel")!]]), entities: result.entities, buildResult: result } as PostSynthContext);
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    };
+    expect(await run("otel_logs")).toEqual([]);
+    expect((await run("otel_logs_v2")).map((d) => [d.checkId, d.severity])).toEqual([["OTEL129", "error"]]);
+  });
+});
+
+describe("the otel lexicon's workspace links", () => {
+  test("each table the exporter writes, and each column its insert names anchored on the table", () => {
+    const entities = new Map<string, Declarable>();
+    collector({ database: "otel", create_schema: false }).forEach((e, i) => entities.set(i === 2 ? "clickhouse" : `e${i}`, e));
+    const links = otelPlugin.workspaceLinks!(entities)!;
+    expect(links.gaps).toBeUndefined();
+    const tables = links.links.filter((l) => !l.anchor).map((l) => l.output);
+    expect(tables).toEqual([
+      "otel.otel_logs",
+      "otel.otel_traces",
+      "otel.otel_metrics_gauge",
+      "otel.otel_metrics_sum",
+      "otel.otel_metrics_summary",
+      "otel.otel_metrics_histogram",
+      "otel.otel_metrics_exponential_histogram",
+    ]);
+    expect(links.links).toContainEqual({ output: "otel.otel_traces.Events", anchor: "otel.otel_traces", entity: "clickhouse" });
+    expect(links.links.every((l) => l.entity === "clickhouse")).toBe(true);
+  });
+
+  test("an environment-set database is a gap; a project with no clickhouse exporter states none", () => {
+    const entities = new Map<string, Declarable>();
+    collector({ database: "${env:CH_DB}" }).forEach((e, i) => entities.set(`e${i}`, e));
+    expect(otelWorkspaceLinks(entities)).toEqual({ links: [], gaps: [expect.stringMatching(/sets database \$\{env:CH_DB\}, which is read from the environment/)] });
+    expect(otelWorkspaceLinks(new Map([["otlp", new OtlpReceiver({})]]))).toBeUndefined();
+  });
+
+  test("clickhouseExportersOf skips an exporter no pipeline uses", () => {
+    expect(clickhouseExportersOf({ exporters: { clickhouse: { endpoint: "tcp://x:9000" } }, service: { pipelines: {} } })).toEqual([]);
+  });
+});