@intentius/chant-lexicon-otel 0.81.0

package/src/skills/chant-otel.md

@@ -0,0 +1,60 @@
+---
+skill: chant-otel
+description: Declare OpenTelemetry Collector config (receivers, processors, exporters, pipelines) as typed chant entities and build collector YAML
+user-invocable: true
+---
+
+# OpenTelemetry Collector config with chant
+
+The otel lexicon (`@intentius/chant-lexicon-otel`) types collector config. Each receiver, processor, exporter and extension is an entity, pipelines reference them, and `chant build` writes one collector config file.
+
+## Project setup
+
+```ts
+// chant.config.ts
+export default { lexicons: ["otel"] };
+```
+
+## Declaring components
+
+Every component class takes the collector's own config keys (snake_case, as in the collector docs) plus an optional `name`. The id is `type`, or `type/name` when `name` is set.
+
+```ts
+import {
+  OtlpReceiver, MemoryLimiterProcessor, BatchProcessor, OtlpExporter, DebugExporter, Pipeline,
+} from "@intentius/chant-lexicon-otel";
+
+export const otlp = new OtlpReceiver({
+  protocols: { grpc: { endpoint: "0.0.0.0:4317" }, http: { endpoint: "0.0.0.0:4318" } },
+});
+export const limiter = new MemoryLimiterProcessor({ check_interval: "1s", limit_percentage: 80, spike_limit_percentage: 20 });
+export const batch = new BatchProcessor({ timeout: "5s" });
+export const backend = new OtlpExporter({ name: "backend", endpoint: "tempo.observability:4317", tls: { insecure: true } });
+
+export const traces = new Pipeline({ signal: "traces", receivers: [otlp], processors: [limiter, batch], exporters: [backend] });
+```
+
+Emits `receivers.otlp`, `processors.memory_limiter` and `processors.batch`, `exporters.otlp/backend`, and `service.pipelines.traces`.
+
+## Built-in set
+
+| Kind | Types |
+|---|---|
+| receivers | otlp, prometheus, hostmetrics, filelog |
+| processors | batch, memory_limiter, resource, attributes, k8sattributes, resourcedetection |
+| exporters | otlp, otlphttp, debug, prometheus, googlecloud |
+| extensions | health_check, pprof, zpages |
+
+Anything else goes through `defineComponent`; see the `chant-otel-custom-components` skill.
+
+## Rules
+
+- Reference components by entity where you can. A string id (`"otlp/backend"`) is allowed for a component declared elsewhere, and OTEL101 fails the build if nothing declares it.
+- Put `memory_limiter` first in `processors` (OTEL105).
+- Never write a credential literally. Use `"${env:NAME}"` and the collector reads it at start-up (OTEL002).
+- Every pipeline needs at least one receiver and one exporter (OTEL102). A declared component no pipeline uses is a warning (OTEL103).
+- Declared extensions are enabled in declaration order unless a `Service` lists `extensions` itself.
+
+## Reading the result
+
+`collectorTopologyOf(entities)` returns the pipelines, each component's endpoints and schema pin, and for each exporter the signals it carries, as plain data.

package/src/topology.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, test } from "vitest";
+import { load } from "js-yaml";
+import { collectorTopology, collectorTopologyOf } from "./topology";
+import { collectorYaml } from "./collector";
+import {
+  BatchProcessor,
+  DebugExporter,
+  GoogleCloudExporter,
+  HealthCheckExtension,
+  OtlpHttpExporter,
+  OtlpReceiver,
+  PrometheusExporter,
+} from "./components";
+import { Pipeline } from "./pipeline";
+import type { CollectorConfig } from "./model";
+
+describe("collectorTopology", () => {
+  const otlp = new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:4317" }, http: {} } });
+  const batch = new BatchProcessor({});
+  const honeycomb = new OtlpHttpExporter({ name: "honeycomb", endpoint: "https://api.honeycomb.io" });
+  const prom = new PrometheusExporter({ endpoint: "0.0.0.0:8889" });
+  const gc = new GoogleCloudExporter({ project: "p1" });
+  const debug = new DebugExporter({});
+  const health = new HealthCheckExtension({ endpoint: "0.0.0.0:13133" });
+  const entities = [
+    otlp,
+    batch,
+    honeycomb,
+    prom,
+    gc,
+    debug,
+    health,
+    new Pipeline({ signal: "traces", receivers: [otlp], processors: [batch], exporters: [honeycomb, gc] }),
+    new Pipeline({ signal: "metrics", receivers: [otlp], processors: [batch], exporters: [prom, gc] }),
+    new Pipeline({ signal: "logs", name: "debug", receivers: [otlp], exporters: [debug] }),
+  ];
+
+  test("names every pipeline and where each exporter sends which signals", () => {
+    const topo = collectorTopologyOf(entities);
+    expect(topo.pipelines.map((p) => [p.id, p.signal])).toEqual([
+      ["traces", "traces"],
+      ["metrics", "metrics"],
+      ["logs/debug", "logs"],
+    ]);
+    expect(topo.exporters).toEqual([
+      { id: "otlphttp/honeycomb", type: "otlphttp", endpoints: ["https://api.honeycomb.io"], pipelines: ["traces"], signals: ["traces"] },
+      { id: "prometheus", type: "prometheus", endpoints: ["0.0.0.0:8889"], pipelines: ["metrics"], signals: ["metrics"] },
+      {
+        id: "googlecloud",
+        type: "googlecloud",
+        endpoints: ["googlecloud://projects/p1"],
+        pipelines: ["traces", "metrics"],
+        signals: ["traces", "metrics"],
+      },
+      { id: "debug", type: "debug", endpoints: ["console"], pipelines: ["logs/debug"], signals: ["logs"] },
+    ]);
+  });
+
+  test("reports receiver listen addresses, defaults included, and extension endpoints", () => {
+    const topo = collectorTopologyOf(entities);
+    expect(topo.components.find((c) => c.id === "otlp")!.endpoints).toEqual(["0.0.0.0:4317", "localhost:4318"]);
+    expect(topo.components.find((c) => c.id === "health_check")!.endpoints).toEqual(["0.0.0.0:13133/"]);
+  });
+
+  test("reads a parsed YAML file the same as the declaration it came from", () => {
+    const parsed = load(collectorYaml(entities)) as CollectorConfig;
+    expect(collectorTopology(parsed)).toEqual(collectorTopologyOf(entities));
+  });
+
+  test("a component this process has no definition for falls back to its endpoint key", () => {
+    const topo = collectorTopology({
+      exporters: { "kafka/out": { brokers: ["k:9092"] }, "somevendor": { endpoint: "https://v.example" } },
+      service: { pipelines: { traces: { receivers: [], exporters: ["kafka/out", "somevendor"] } } },
+    });
+    expect(topo.components.map((c) => [c.id, c.type, c.name, c.builtin, c.endpoints])).toEqual([
+      ["kafka/out", "kafka", "out", false, []],
+      ["somevendor", "somevendor", undefined, false, ["https://v.example"]],
+    ]);
+  });
+});

package/src/topology.ts

@@ -0,0 +1,122 @@
+/**
+ * Where telemetry goes, as plain data.
+ *
+ * `collectorTopology()` reads a collector config (declared, or parsed from a
+ * YAML file) and returns its pipelines, its components with their endpoints
+ * and schema pins, and for each exporter the pipelines and signals it
+ * carries. It is the surface a reader such as `chant workspace graph` uses to
+ * say where a member's telemetry is sent, and what a declared telemetry
+ * endpoint link can point at.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import { buildCollectorConfig } from "./collector";
+import { definitionOf, type SchemaPin } from "./define";
+import { parseComponentId, pipelineSignal, SECTION_OF, type CollectorConfig, type ComponentKind } from "./model";
+
+export interface TopologyPipeline {
+  /** The id under `service.pipelines`, e.g. `traces` or `traces/backend`. */
+  id: string;
+  /** `traces`, `metrics` or `logs`. */
+  signal: string;
+  receivers: string[];
+  processors: string[];
+  exporters: string[];
+}
+
+export interface TopologyComponent {
+  /** The collector id, `type` or `type/name`. */
+  id: string;
+  kind: ComponentKind;
+  type: string;
+  name?: string;
+  /** True for a component this package ships; false for a custom one, or one this process has no definition for. */
+  builtin: boolean;
+  /** The schema pin of its definition, when this process has the definition. */
+  schema?: SchemaPin;
+  /** Addresses it listens on or sends to, as the config states them. Empty when the config names none. */
+  endpoints: string[];
+  /** The pipelines that use it. For an extension, empty. */
+  pipelines: string[];
+}
+
+export interface TopologyExporter {
+  id: string;
+  type: string;
+  endpoints: string[];
+  pipelines: string[];
+  /** The signals that reach it, deduplicated, in pipeline order. */
+  signals: string[];
+}
+
+export interface CollectorTopology {
+  pipelines: TopologyPipeline[];
+  components: TopologyComponent[];
+  /** The exporters again, grouped for the question "where does this telemetry go". */
+  exporters: TopologyExporter[];
+}
+
+function endpointsOf(kind: ComponentKind, type: string, config: Record<string, unknown> | null | undefined): string[] {
+  const def = definitionOf(kind, type);
+  const cfg = config ?? {};
+  if (def?.endpoints) {
+    try {
+      return def.endpoints(cfg as never);
+    } catch {
+      return [];
+    }
+  }
+  return typeof cfg.endpoint === "string" && cfg.endpoint !== "" ? [cfg.endpoint] : [];
+}
+
+/** The topology of a collector config. */
+export function collectorTopology(config: CollectorConfig): CollectorTopology {
+  const pipelines: TopologyPipeline[] = Object.entries(config.service?.pipelines ?? {}).map(([id, p]) => ({
+    id,
+    signal: pipelineSignal(id),
+    receivers: (p?.receivers ?? []).map(String),
+    processors: (p?.processors ?? []).map(String),
+    exporters: (p?.exporters ?? []).map(String),
+  }));
+
+  const components: TopologyComponent[] = [];
+  for (const kind of Object.keys(SECTION_OF) as ComponentKind[]) {
+    const section = SECTION_OF[kind];
+    for (const [id, cfg] of Object.entries(config[section] ?? {})) {
+      const parsed = parseComponentId(id);
+      const type = parsed?.type ?? id;
+      const def = definitionOf(kind, type);
+      const field = section as "receivers" | "processors" | "exporters" | "extensions";
+      const inPipelines =
+        field === "extensions" ? [] : pipelines.filter((p) => p[field].includes(id)).map((p) => p.id);
+      components.push({
+        id,
+        kind,
+        type,
+        ...(parsed?.name !== undefined ? { name: parsed.name } : {}),
+        builtin: def?.builtin ?? false,
+        ...(def ? { schema: { ...def.pin } } : {}),
+        endpoints: endpointsOf(kind, type, cfg),
+        pipelines: inPipelines,
+      });
+    }
+  }
+
+  const exporters: TopologyExporter[] = components
+    .filter((c) => c.kind === "exporter")
+    .map((c) => {
+      const signals: string[] = [];
+      for (const pid of c.pipelines) {
+        const s = pipelineSignal(pid);
+        if (!signals.includes(s)) signals.push(s);
+      }
+      return { id: c.id, type: c.type, endpoints: c.endpoints, pipelines: c.pipelines, signals };
+    });
+
+  return { pipelines, components, exporters };
+}
+
+/** The topology of declared entities, i.e. of the config the serializer would emit for them. */
+export function collectorTopologyOf(entities: Iterable<Declarable> | Map<string, Declarable>): CollectorTopology {
+  return collectorTopology(buildCollectorConfig(entities).config);
+}

package/src/validate-cli.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env tsx
+import { printValidationResult } from "@intentius/chant/codegen/validate";
+import { validate } from "./validate";
+
+const result = await validate();
+printValidationResult(result);
+if (!result.success) process.exit(1);

package/src/validate-config.ts

@@ -0,0 +1,232 @@
+/**
+ * Collector config checks, as plain functions over `CollectorConfig` and over
+ * declared entities.
+ *
+ * The post-synth checks in `lint/post-synth/` are thin wrappers around these,
+ * so the same rules can run anywhere a config exists: on a build's output, on
+ * a composite's generated YAML, or on a collector file parsed by some other
+ * tool.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import { definitionFor, isOTelComponent, isUsablePin, runValidator } from "./define";
+import { componentConfig } from "./collector";
+import { isComponentId, pipelineSignal, SIGNALS, type CollectorConfig } from "./model";
+import { isPipelineEntity } from "./pipeline";
+
+export type CollectorIssueCode =
+  | "OTEL101"
+  | "OTEL102"
+  | "OTEL103"
+  | "OTEL104"
+  | "OTEL105"
+  | "OTEL106"
+  | "OTEL107"
+  | "OTEL108"
+  | "OTEL109";
+
+export interface CollectorIssue {
+  code: CollectorIssueCode;
+  severity: "error" | "warning";
+  message: string;
+  /** The pipeline id the issue is about, when it is about one. */
+  pipeline?: string;
+  /** The component id the issue is about, when it is about one. */
+  component?: string;
+}
+
+const KNOWN_SIGNALS = new Set<string>([...SIGNALS, "profiles"]);
+
+function ids(section: Record<string, unknown> | undefined): Set<string> {
+  return new Set(Object.keys(section ?? {}));
+}
+
+/** Check a collector config's references and pipeline shape (OTEL101-OTEL106). */
+export function validateCollectorConfig(config: CollectorConfig): CollectorIssue[] {
+  const issues: CollectorIssue[] = [];
+  const receivers = ids(config.receivers);
+  const processors = ids(config.processors);
+  const exporters = ids(config.exporters);
+  const extensions = ids(config.extensions);
+  const connectors = ids(config.connectors);
+  const pipelines = config.service?.pipelines ?? {};
+
+  const used = { receivers: new Set<string>(), processors: new Set<string>(), exporters: new Set<string>() };
+
+  for (const [pipelineId, pipeline] of Object.entries(pipelines)) {
+    const signal = pipelineSignal(pipelineId);
+    if (!KNOWN_SIGNALS.has(signal) || !isComponentId(pipelineId)) {
+      issues.push({
+        code: "OTEL106",
+        severity: "error",
+        pipeline: pipelineId,
+        message: `pipeline "${pipelineId}" does not name a signal; a pipeline id is traces, metrics or logs, optionally followed by /name`,
+      });
+    }
+    const p = pipeline ?? {};
+    const lists: Array<["receivers" | "processors" | "exporters", string[] | undefined, Set<string>, string]> = [
+      ["receivers", p.receivers, receivers, "receiver"],
+      ["processors", p.processors, processors, "processor"],
+      ["exporters", p.exporters, exporters, "exporter"],
+    ];
+    for (const [field, refs, declared, noun] of lists) {
+      for (const ref of refs ?? []) {
+        const id = String(ref);
+        used[field].add(id);
+        if (!isComponentId(id)) {
+          issues.push({
+            code: "OTEL106",
+            severity: "error",
+            pipeline: pipelineId,
+            component: id,
+            message: `pipeline "${pipelineId}" lists ${noun} "${id}", which is not a component id (type or type/name)`,
+          });
+          continue;
+        }
+        const viaConnector = field !== "processors" && connectors.has(id);
+        if (!declared.has(id) && !viaConnector) {
+          issues.push({
+            code: "OTEL101",
+            severity: "error",
+            pipeline: pipelineId,
+            component: id,
+            message: `pipeline "${pipelineId}" uses ${noun} "${id}", which is not declared under ${field}; the collector refuses to start`,
+          });
+        }
+      }
+    }
+    if ((p.receivers ?? []).length === 0) {
+      issues.push({
+        code: "OTEL102",
+        severity: "error",
+        pipeline: pipelineId,
+        message: `pipeline "${pipelineId}" has no receivers, so nothing enters it`,
+      });
+    }
+    if ((p.exporters ?? []).length === 0) {
+      issues.push({
+        code: "OTEL102",
+        severity: "error",
+        pipeline: pipelineId,
+        message: `pipeline "${pipelineId}" has no exporters, so what enters it goes nowhere`,
+      });
+    }
+    const procs = (p.processors ?? []).map(String);
+    const limiterAt = procs.findIndex((id) => id === "memory_limiter" || id.startsWith("memory_limiter/"));
+    if (limiterAt > 0) {
+      issues.push({
+        code: "OTEL105",
+        severity: "warning",
+        pipeline: pipelineId,
+        component: procs[limiterAt],
+        message: `pipeline "${pipelineId}" runs ${procs[limiterAt]} at position ${limiterAt + 1}; put it first so it can refuse data before other processors buffer it`,
+      });
+    }
+  }
+
+  const unused: Array<[Set<string>, Set<string>, string]> = [
+    [receivers, used.receivers, "receiver"],
+    [processors, used.processors, "processor"],
+    [exporters, used.exporters, "exporter"],
+  ];
+  for (const [declared, usedIds, noun] of unused) {
+    for (const id of declared) {
+      if (!usedIds.has(id)) {
+        issues.push({
+          code: "OTEL103",
+          severity: "warning",
+          component: id,
+          message: `${noun} "${id}" is declared but no pipeline uses it; the collector ignores it`,
+        });
+      }
+    }
+  }
+
+  const enabled = new Set((config.service?.extensions ?? []).map(String));
+  for (const id of enabled) {
+    if (!extensions.has(id)) {
+      issues.push({
+        code: "OTEL104",
+        severity: "error",
+        component: id,
+        message: `service.extensions enables "${id}", which is not declared under extensions; the collector refuses to start`,
+      });
+    }
+  }
+  for (const id of extensions) {
+    if (!enabled.has(id)) {
+      issues.push({
+        code: "OTEL103",
+        severity: "warning",
+        component: id,
+        message: `extension "${id}" is declared but not listed in service.extensions, so it never starts`,
+      });
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Check declared entities for what only the declaration knows (OTEL107-OTEL109):
+ * each component's own config rules, duplicate ids, and custom components'
+ * schema pins.
+ */
+export function validateCollectorEntities(entities: Iterable<Declarable> | Map<string, Declarable>): CollectorIssue[] {
+  const list = entities instanceof Map ? [...entities.values()] : [...entities];
+  const issues: CollectorIssue[] = [];
+  const seen = new Map<string, number>();
+  const pipelineIds = new Map<string, number>();
+
+  for (const e of list) {
+    if (isPipelineEntity(e)) {
+      pipelineIds.set(e.pipelineId, (pipelineIds.get(e.pipelineId) ?? 0) + 1);
+      continue;
+    }
+    if (!isOTelComponent(e)) continue;
+    const key = `${e.componentKind} ${e.componentId}`;
+    seen.set(key, (seen.get(key) ?? 0) + 1);
+
+    const def = definitionFor(e.entityType);
+    if (!def) continue;
+    if (!def.builtin && !isUsablePin(def.pin)) {
+      issues.push({
+        code: "OTEL109",
+        severity: "error",
+        component: e.componentId,
+        message: `custom ${e.componentKind} "${e.componentId}" has no schema pin; give defineComponent a pin with a source and a version`,
+      });
+    }
+    for (const problem of runValidator(def.validate, componentConfig(e) as never)) {
+      issues.push({
+        code: "OTEL107",
+        severity: "error",
+        component: e.componentId,
+        message: `${e.componentKind} "${e.componentId}": ${problem}`,
+      });
+    }
+  }
+
+  for (const [key, count] of seen) {
+    if (count > 1) {
+      const [kind, id] = key.split(" ");
+      issues.push({
+        code: "OTEL108",
+        severity: "error",
+        component: id,
+        message: `${count} ${kind}s declare the id "${id}"; give each a distinct name`,
+      });
+    }
+  }
+  for (const [id, count] of pipelineIds) {
+    if (count > 1) {
+      issues.push({
+        code: "OTEL108",
+        severity: "error",
+        pipeline: id,
+        message: `${count} pipelines declare the id "${id}"; give each a distinct name`,
+      });
+    }
+  }
+  return issues;
+}

package/src/validate.ts

@@ -0,0 +1,82 @@
+/**
+ * Validate the otel lexicon's own artifacts: every built-in class is in the
+ * registry, every built-in definition carries the collector pin, and every
+ * built-in constructs and serializes.
+ */
+
+import type { ValidateCheck, ValidateResult } from "@intentius/chant/codegen/validate";
+import { BUILTIN_CATALOG, lexiconRegistry } from "./catalog";
+import * as components from "./components";
+import { COLLECTOR_PIN, type ComponentClass } from "./define";
+import { collectorYaml } from "./collector";
+
+export type { ValidateCheck, ValidateResult } from "@intentius/chant/codegen/validate";
+
+/** Every entity class the package must keep exporting. */
+export const REQUIRED_NAMES = [
+  "OtlpReceiver",
+  "PrometheusReceiver",
+  "HostMetricsReceiver",
+  "FileLogReceiver",
+  "BatchProcessor",
+  "MemoryLimiterProcessor",
+  "ResourceProcessor",
+  "AttributesProcessor",
+  "K8sAttributesProcessor",
+  "ResourceDetectionProcessor",
+  "OtlpExporter",
+  "OtlpHttpExporter",
+  "DebugExporter",
+  "PrometheusExporter",
+  "GoogleCloudExporter",
+  "HealthCheckExtension",
+  "PprofExtension",
+  "ZPagesExtension",
+  "Pipeline",
+  "Service",
+];
+
+export async function validate(): Promise<ValidateResult> {
+  const checks: ValidateCheck[] = [];
+  const registry = lexiconRegistry();
+
+  const missing = REQUIRED_NAMES.filter((n) => !(n in registry));
+  checks.push(
+    missing.length === 0
+      ? { name: "required-names", ok: true }
+      : { name: "required-names", ok: false, error: `Missing required names: ${missing.join(", ")}` },
+  );
+
+  const classes = (Object.entries(components) as Array<[string, unknown]>).filter(
+    (e): e is [string, ComponentClass] => typeof e[1] === "function" && "definition" in (e[1] as object),
+  );
+  const unpinned = classes.filter(([, c]) => c.definition.pin !== COLLECTOR_PIN || !c.definition.builtin).map(([n]) => n);
+  checks.push(
+    unpinned.length === 0
+      ? { name: "builtins-pinned", ok: true }
+      : { name: "builtins-pinned", ok: false, error: `Not pinned to the collector release: ${unpinned.join(", ")}` },
+  );
+
+  const broken: string[] = [];
+  for (const [name, Cls] of classes) {
+    try {
+      const yaml = collectorYaml([new (Cls as unknown as new (p: object) => never)({})]);
+      if (!yaml.includes(Cls.definition.type)) broken.push(name);
+    } catch (err) {
+      broken.push(`${name} (${err instanceof Error ? err.message : String(err)})`);
+    }
+  }
+  checks.push(
+    broken.length === 0
+      ? { name: "builtins-serialize", ok: true }
+      : { name: "builtins-serialize", ok: false, error: `Failed to serialize: ${broken.join(", ")}` },
+  );
+
+  checks.push(
+    BUILTIN_CATALOG.length === Object.keys(registry).length
+      ? { name: "catalog-matches-registry", ok: true }
+      : { name: "catalog-matches-registry", ok: false, error: "catalog and registry disagree" },
+  );
+
+  return { success: checks.every((c) => c.ok), checks };
+}

package/src/yaml.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "vitest";
+import { load } from "js-yaml";
+import { emitCollectorYaml, isPlainSafe } from "./yaml";
+
+describe("collector YAML emitter", () => {
+  test.each([
+    ["0.0.0.0:4317", true],
+    ["custom.googleapis.com/c1", true],
+    ["${env:KEY}", true],
+    ["true", false],
+    ["8080", false],
+    ["1:30", false],
+    ["a: b", false],
+    ["- x", false],
+    ["", false],
+    [" x", false],
+  ])("isPlainSafe(%j) in block context is %s", (s, safe) => {
+    expect(isPlainSafe(s, false)).toBe(safe);
+  });
+
+  test("a string with flow indicators is quoted inside a flow list", () => {
+    expect(isPlainSafe("${env:KEY}", true)).toBe(false);
+    const yaml = emitCollectorYaml({ receivers: { x: { list: ["${env:A}", "b"] } } });
+    expect(yaml).toContain('list: ["${env:A}", b]');
+    expect((load(yaml) as any).receivers.x.list).toEqual(["${env:A}", "b"]);
+  });
+
+  test("lists of maps are block style, nested lists and empty values survive", () => {
+    const config = {
+      processors: {
+        attributes: {
+          actions: [
+            { key: "env", action: "upsert", value: "prod" },
+            { key: "secret", action: "delete" },
+          ],
+          empty: [],
+          nested: [[1, 2], [{ a: 1 }]],
+          none: null,
+          blank: {},
+        },
+      },
+    };
+    const yaml = emitCollectorYaml(config);
+    expect(yaml).toContain("    actions:\n      - key: env\n        action: upsert\n        value: prod\n      - key: secret\n");
+    expect(load(yaml)).toEqual(config);
+  });
+
+  test("a header becomes comment lines above the config", () => {
+    const yaml = emitCollectorYaml({ exporters: { debug: {} } }, { header: ["chant: hello"] });
+    expect(yaml.startsWith("# chant: hello\n\nexporters:\n  debug: {}\n")).toBe(true);
+  });
+
+  test("an empty config is empty", () => {
+    expect(emitCollectorYaml({})).toBe("");
+  });
+});