@intentius/chant-lexicon-otel 0.81.0

package/src/platform.ts

@@ -0,0 +1,143 @@
+/**
+ * What the platform composites share: a default collector config, the image
+ * that runs it, where the config is mounted, and the ports a rendered config
+ * listens on.
+ *
+ * The docker, k8s and fly collector composites build on this. A composite
+ * declares its config with this lexicon, renders it with `collectorYaml`, and
+ * reads the listening ports back from the built config, so the ports it
+ * publishes follow whatever config the caller declared.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import { COLLECTOR_PIN, type OTelComponent } from "./define";
+import { OtlpReceiver } from "./components/receivers";
+import { BatchProcessor, MemoryLimiterProcessor } from "./components/processors";
+import { DebugExporter } from "./components/exporters";
+import { HealthCheckExtension } from "./components/extensions";
+import { Pipeline } from "./pipeline";
+import { SIGNALS, parseComponentId, type CollectorConfig, type Signal } from "./model";
+
+/** The contrib collector image at the version the built-in components are typed against. */
+export const COLLECTOR_IMAGE = `otel/opentelemetry-collector-contrib:${COLLECTOR_PIN.version.replace(/^v/, "")}`;
+
+/** Where the platform composites mount the rendered config inside the container. */
+export const COLLECTOR_CONFIG_PATH = "/etc/otel/config.yaml";
+
+export interface OtlpCollectorOptions {
+  /** Where telemetry goes. Default: one `debug` exporter at `basic` verbosity. */
+  exporters?: OTelComponent<"exporter", string, any>[];
+  /** Which signals get a pipeline. Default: traces, metrics and logs. */
+  signals?: Signal[];
+  /** Serve `health_check` on 0.0.0.0:13133. Default: true. */
+  healthCheck?: boolean;
+}
+
+/**
+ * The entities of a small OTLP collector: an `otlp` receiver on 4317 (gRPC)
+ * and 4318 (HTTP), `memory_limiter` then `batch`, the given exporters, and a
+ * `health_check` extension. Pass the result to `collectorYaml`.
+ */
+export function otlpCollector(options: OtlpCollectorOptions = {}): Declarable[] {
+  const { exporters = [new DebugExporter({ verbosity: "basic" })], signals = [...SIGNALS], healthCheck = true } = options;
+  const otlp = new OtlpReceiver({
+    protocols: {
+      grpc: { endpoint: "0.0.0.0:4317" },
+      http: { endpoint: "0.0.0.0:4318" },
+    },
+  });
+  const memoryLimiter = new MemoryLimiterProcessor({
+    check_interval: "1s",
+    limit_percentage: 80,
+    spike_limit_percentage: 20,
+  });
+  const batch = new BatchProcessor({});
+  const entities: Declarable[] = [otlp, memoryLimiter, batch, ...exporters];
+  if (healthCheck) entities.push(new HealthCheckExtension({ endpoint: "0.0.0.0:13133" }));
+  for (const signal of signals) {
+    entities.push(new Pipeline({ signal, receivers: [otlp], processors: [memoryLimiter, batch], exporters }));
+  }
+  return entities;
+}
+
+/** A port a collector config listens on. */
+export interface CollectorPort {
+  /** A name usable as a k8s port name: lowercase, `-` separated, at most 15 characters. */
+  name: string;
+  port: number;
+}
+
+export interface CollectorEndpoints {
+  /** Ports the receivers listen on, in config order, one entry per port. */
+  ports: CollectorPort[];
+  /**
+   * The `health_check` extension, when the service enables one and it listens
+   * on an address other than localhost. A probe from outside the container
+   * cannot reach a localhost listener.
+   */
+  healthCheck?: { port: number; path: string };
+}
+
+function portOf(endpoint: unknown): { host: string; port: number } | undefined {
+  if (typeof endpoint !== "string") return undefined;
+  const m = endpoint.match(/^(.*):(\d+)$/);
+  if (!m) return undefined;
+  return { host: m[1], port: Number(m[2]) };
+}
+
+function portName(parts: string[]): string {
+  const name = parts
+    .join("-")
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  return name.slice(0, 15).replace(/-$/, "");
+}
+
+/** Every `endpoint` value under a receiver's config, with the key path that led to it. */
+function receiverEndpoints(value: unknown, path: string[], out: Array<{ path: string[]; endpoint: unknown }>): void {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return;
+  for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+    if (key === "endpoint") out.push({ path, endpoint: child });
+    else receiverEndpoints(child, [...path, key], out);
+  }
+}
+
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+
+/**
+ * The ports a built collector config listens on: every receiver `endpoint`,
+ * named after the receiver and the protocol key above it (`otlp-grpc`,
+ * `otlp-http`), and the `health_check` port if the service enables it.
+ */
+export function collectorEndpoints(config: CollectorConfig): CollectorEndpoints {
+  const ports: CollectorPort[] = [];
+  const seen = new Set<number>();
+  for (const [id, receiverConfig] of Object.entries(config.receivers ?? {})) {
+    const found: Array<{ path: string[]; endpoint: unknown }> = [];
+    receiverEndpoints(receiverConfig, [], found);
+    const parsed = parseComponentId(id);
+    const base = parsed ? [parsed.type, ...(parsed.name ? [parsed.name] : [])] : [id];
+    for (const { path, endpoint } of found) {
+      const p = portOf(endpoint);
+      if (!p || seen.has(p.port)) continue;
+      seen.add(p.port);
+      const protocol = path.filter((k) => k !== "protocols");
+      ports.push({ name: portName([...base, ...protocol]), port: p.port });
+    }
+  }
+
+  let healthCheck: CollectorEndpoints["healthCheck"];
+  const enabled = config.service?.extensions ?? [];
+  for (const id of enabled) {
+    if (parseComponentId(id)?.type !== "health_check") continue;
+    const ext = (config.extensions?.[id] ?? {}) as { endpoint?: unknown; path?: unknown };
+    const p = portOf(ext.endpoint ?? "localhost:13133");
+    if (!p || LOCAL_HOSTS.has(p.host)) continue;
+    healthCheck = { port: p.port, path: typeof ext.path === "string" ? ext.path : "/" };
+    break;
+  }
+
+  return { ports, ...(healthCheck ? { healthCheck } : {}) };
+}

package/src/plugin.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import { isLexiconPlugin } from "@intentius/chant/lexicon";
+import { otelPlugin } from "./plugin";
+import { otelAuditCatalog } from "./lint/audit-catalog";
+
+describe("otel plugin", () => {
+  it("is a valid LexiconPlugin", () => {
+    expect(isLexiconPlugin(otelPlugin)).toBe(true);
+  });
+
+  it("is named otel and serializes under the OTEL prefix", () => {
+    expect(otelPlugin.name).toBe("otel");
+    expect(otelPlugin.serializer.name).toBe("otel");
+    expect(otelPlugin.serializer.rulePrefix).toBe("OTEL");
+  });
+
+  it("ships lint rules and post-synth checks, all under the OTEL prefix", () => {
+    const ids = [...otelPlugin.lintRules!().map((r) => r.id), ...otelPlugin.postSynthChecks!().map((c) => c.id)];
+    expect(ids).toEqual([
+      "OTEL001",
+      "OTEL002",
+      "OTEL101",
+      "OTEL102",
+      "OTEL103",
+      "OTEL104",
+      "OTEL105",
+      "OTEL106",
+      "OTEL107",
+      "OTEL108",
+      "OTEL109",
+    ]);
+    for (const id of ids) expect(id.startsWith("OTEL")).toBe(true);
+  });
+
+  it("catalogues every post-synth check for chant audit", () => {
+    for (const check of otelPlugin.postSynthChecks!()) expect(otelAuditCatalog[check.id]).toBeDefined();
+  });
+
+  it("detects a collector config and nothing else", () => {
+    expect(otelPlugin.detectTemplate!({ receivers: { otlp: {} }, service: { pipelines: { traces: {} } } })).toBe(true);
+    expect(otelPlugin.detectTemplate!({ apiVersion: "v1", kind: "ConfigMap" })).toBe(false);
+    expect(otelPlugin.detectTemplate!({ services: { web: {} } })).toBe(false);
+  });
+
+  it("loads its skills with content", () => {
+    const skills = otelPlugin.skills!();
+    expect(skills.map((s) => s.name)).toEqual(["chant-otel", "chant-otel-custom-components", "chant-otel-platforms"]);
+    for (const s of skills) expect(s.content.length).toBeGreaterThan(100);
+  });
+
+  it("registers namespaced MCP contributions", () => {
+    expect(otelPlugin.mcpTools!().map((t) => t.name)).toEqual(["otel:diff"]);
+    expect(otelPlugin.mcpResources!().map((r) => r.uri)).toEqual(["otel:resource-catalog"]);
+  });
+});

package/src/plugin.ts

@@ -0,0 +1,111 @@
+import type { LexiconPlugin } from "@intentius/chant/lexicon";
+import type { CompletionContext, HoverContext } from "@intentius/chant/lsp/types";
+import type { McpResourceContribution } from "@intentius/chant/mcp/types";
+import { createDiffTool } from "@intentius/chant/lexicon-plugin-helpers";
+import { otelSerializer } from "./serializer";
+import { rules } from "./lint/rules";
+import { postSynthChecks } from "./lint/post-synth";
+import { otelAuditCatalog } from "./lint/audit-catalog";
+import { completions } from "./lsp/completions";
+import { hover } from "./lsp/hover";
+import { detectTemplate } from "./detect";
+import { otelSkills } from "./skill-defs";
+import { BUILTIN_CATALOG } from "./catalog";
+import { COLLECTOR_PIN } from "./define";
+
+const catalogResource: McpResourceContribution = {
+  uri: "otel:resource-catalog",
+  name: "OpenTelemetry Collector component catalog",
+  description: "The collector components, pipelines and service block this lexicon types, with the collector release they follow",
+  mimeType: "application/json",
+  async handler(): Promise<string> {
+    return JSON.stringify({ pin: COLLECTOR_PIN, entities: BUILTIN_CATALOG });
+  },
+};
+
+/**
+ * OpenTelemetry Collector lexicon plugin.
+ *
+ * Typed receivers, processors, exporters and extensions, pipelines and the
+ * service block, serialized to one collector config file. A component chant
+ * doesn't ship comes in through `defineComponent`, and is serialized and
+ * checked the same way as the built-ins.
+ */
+export const otelPlugin: LexiconPlugin = {
+  name: "otel",
+  serializer: otelSerializer,
+
+  // ── Required lifecycle methods ────────────────────────────────
+
+  async generate(options?: { verbose?: boolean }): Promise<void> {
+    const { generate, writeGeneratedFiles } = await import("./codegen/generate");
+    writeGeneratedFiles(await generate(options));
+  },
+
+  async validate(_options?: { verbose?: boolean }): Promise<void> {
+    const { validate } = await import("./validate");
+    const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+    printValidationResult(await validate());
+  },
+
+  async coverage(_options?: { verbose?: boolean; minOverall?: number }): Promise<void> {
+    const components = BUILTIN_CATALOG.filter((c) => c.type !== undefined);
+    const byKind = new Map<string, string[]>();
+    for (const c of components) byKind.set(c.kind, [...(byKind.get(c.kind) ?? []), c.type!]);
+    console.error(`otel: ${components.length} built-in components, typed against ${COLLECTOR_PIN.source} ${COLLECTOR_PIN.version}`);
+    for (const [kind, types] of byKind) console.error(`  ${kind}s: ${types.join(", ")}`);
+    console.error("  anything else: defineComponent (see docs: custom components)");
+  },
+
+  async package(options?: { verbose?: boolean; force?: boolean }): Promise<void> {
+    const { packageLexicon } = await import("./codegen/package");
+    const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+    const { join, dirname } = await import("path");
+    const { fileURLToPath } = await import("url");
+    const { spec, stats } = await packageLexicon(options);
+    const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+    writeBundleSpec(spec, join(pkgDir, "dist"));
+    console.error(`Packaged ${stats.resources} entities, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+  },
+
+  // ── Optional extensions ────────────────────────────────────
+
+  lintRules() {
+    return rules;
+  },
+
+  postSynthChecks() {
+    return postSynthChecks;
+  },
+
+  auditCatalog() {
+    return otelAuditCatalog;
+  },
+
+  skills: otelSkills,
+
+  mcpTools() {
+    return [createDiffTool(otelSerializer, "Compare current collector config output against the previous build", "otel")];
+  },
+
+  mcpResources() {
+    return [catalogResource];
+  },
+
+  detectTemplate(data: unknown) {
+    return detectTemplate(data);
+  },
+
+  completionProvider(ctx: CompletionContext) {
+    return completions(ctx);
+  },
+
+  hoverProvider(ctx: HoverContext) {
+    return hover(ctx);
+  },
+
+  async docs(options?: { verbose?: boolean }) {
+    const { generateDocs } = await import("./codegen/docs");
+    return generateDocs(options);
+  },
+};

package/src/serializer.test.ts

@@ -0,0 +1,187 @@
+import { describe, expect, test } from "vitest";
+import { load } from "js-yaml";
+import type { Declarable } from "@intentius/chant/declarable";
+import { otelSerializer } from "./serializer";
+import {
+  BatchProcessor,
+  DebugExporter,
+  GoogleCloudExporter,
+  HealthCheckExtension,
+  MemoryLimiterProcessor,
+  OtlpExporter,
+  OtlpReceiver,
+  Pipeline,
+  PprofExtension,
+  Service,
+} from "./index";
+
+function entities(record: Record<string, unknown>): Map<string, Declarable> {
+  return new Map(Object.entries(record) as Array<[string, Declarable]>);
+}
+
+function primary(out: ReturnType<typeof otelSerializer.serialize>): string {
+  return typeof out === "string" ? out : out.primary;
+}
+
+describe("otel serializer", () => {
+  // 1, 2
+  test("name and rule prefix", () => {
+    expect(otelSerializer.name).toBe("otel");
+    expect(otelSerializer.rulePrefix).toBe("OTEL");
+  });
+
+  // 3
+  test("an empty map serializes to the empty string", () => {
+    expect(otelSerializer.serialize(new Map())).toBe("");
+  });
+
+  // 4
+  test("a minimal traces pipeline", () => {
+    const otlp = new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:4317" } } });
+    const debug = new DebugExporter({ verbosity: "basic" });
+    const out = otelSerializer.serialize(
+      entities({ otlp, debug, traces: new Pipeline({ signal: "traces", receivers: [otlp], exporters: [debug] }) }),
+    );
+    expect(out).toBe(`receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+
+exporters:
+  debug:
+    verbosity: basic
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      exporters: [debug]
+`);
+  });
+
+  // 5, 6: the collector id comes from the type and the instance name, never the export name
+  test("the export name does not leak into the id; an instance name makes type/name", () => {
+    const tempo = new OtlpExporter({ name: "tempo", endpoint: "tempo:4317" });
+    const plain = new OtlpExporter({ endpoint: "other:4317" });
+    const yaml = primary(otelSerializer.serialize(entities({ myTempoExporter: tempo, anotherOne: plain })));
+    const parsed = load(yaml) as any;
+    expect(Object.keys(parsed.exporters)).toEqual(["otlp/tempo", "otlp"]);
+    expect(yaml).not.toContain("myTempoExporter");
+    expect(parsed.exporters["otlp/tempo"]).toEqual({ endpoint: "tempo:4317" });
+  });
+
+  // 7
+  test("several pipelines, in declaration order, sharing components", () => {
+    const otlp = new OtlpReceiver({ protocols: { grpc: {}, http: {} } });
+    const batch = new BatchProcessor({});
+    const debug = new DebugExporter({});
+    const parsed = load(
+      primary(
+        otelSerializer.serialize(
+          entities({
+            otlp,
+            batch,
+            debug,
+            logs: new Pipeline({ signal: "logs", receivers: [otlp], processors: [batch], exporters: [debug] }),
+            traces: new Pipeline({ signal: "traces", name: "debug", receivers: [otlp], exporters: [debug] }),
+          }),
+        ),
+      ),
+    ) as any;
+    expect(Object.keys(parsed.service.pipelines)).toEqual(["logs", "traces/debug"]);
+    expect(parsed.service.pipelines["traces/debug"].processors).toBeUndefined();
+    expect(parsed.receivers.otlp).toEqual({ protocols: { grpc: {}, http: {} } });
+  });
+
+  // 8
+  test("declared extensions are enabled by default, in declaration order", () => {
+    const health = new HealthCheckExtension({ endpoint: "0.0.0.0:13133" });
+    const pprof = new PprofExtension({});
+    const parsed = load(primary(otelSerializer.serialize(entities({ health, pprof })))) as any;
+    expect(parsed.service.extensions).toEqual(["health_check", "pprof"]);
+  });
+
+  // 9
+  test("a Service that lists extensions wins over the default, and carries telemetry", () => {
+    const health = new HealthCheckExtension({});
+    const pprof = new PprofExtension({});
+    const parsed = load(
+      primary(
+        otelSerializer.serialize(
+          entities({ health, pprof, service: new Service({ extensions: [health], telemetry: { logs: { level: "warn" } } }) }),
+        ),
+      ),
+    ) as any;
+    expect(parsed.service.extensions).toEqual(["health_check"]);
+    expect(parsed.service.telemetry).toEqual({ logs: { level: "warn" } });
+  });
+
+  // 10
+  test("a component a pipeline references but nobody listed is still emitted", () => {
+    const otlp = new OtlpReceiver({ protocols: { grpc: {} } });
+    const debug = new DebugExporter({});
+    const parsed = load(
+      primary(otelSerializer.serialize(entities({ traces: new Pipeline({ signal: "traces", receivers: [otlp], exporters: [debug] }) }))),
+    ) as any;
+    expect(Object.keys(parsed.receivers)).toEqual(["otlp"]);
+    expect(Object.keys(parsed.exporters)).toEqual(["debug"]);
+  });
+
+  // 11
+  test("sections come out in collector order whatever the declaration order", () => {
+    const debug = new DebugExporter({});
+    const health = new HealthCheckExtension({});
+    const limiter = new MemoryLimiterProcessor({ check_interval: "1s", limit_mib: 400 });
+    const otlp = new OtlpReceiver({ protocols: { grpc: {} } });
+    const yaml = primary(
+      otelSerializer.serialize(
+        entities({
+          traces: new Pipeline({ signal: "traces", receivers: [otlp], processors: [limiter], exporters: [debug] }),
+          debug,
+          health,
+          limiter,
+          otlp,
+        }),
+      ),
+    );
+    const sections = yaml.split("\n").filter((l) => /^[a-z]/.test(l));
+    expect(sections).toEqual(["receivers:", "processors:", "exporters:", "extensions:", "service:"]);
+  });
+
+  // 12a: the output parses back to what was declared
+  test("round-trips through a YAML parser, including values that need quoting", () => {
+    const exporter = new OtlpExporter({
+      name: "vendor",
+      endpoint: "api.vendor.example:443",
+      headers: { "x-api-key": "${env:VENDOR_KEY}", "x-tenant": "true", "x-shard": "0012" },
+      compression: "gzip",
+      retry_on_failure: { enabled: true, max_elapsed_time: "300s" },
+    });
+    const gc = new GoogleCloudExporter({ project: "my-project", metric: { known_domains: ["a,b", "c"] } });
+    const parsed = load(primary(otelSerializer.serialize(entities({ exporter, gc })))) as any;
+    expect(parsed.exporters["otlp/vendor"].headers).toEqual({
+      "x-api-key": "${env:VENDOR_KEY}",
+      "x-tenant": "true",
+      "x-shard": "0012",
+    });
+    expect(parsed.exporters["otlp/vendor"].retry_on_failure).toEqual({ enabled: true, max_elapsed_time: "300s" });
+    expect(parsed.exporters.googlecloud.metric.known_domains).toEqual(["a,b", "c"]);
+  });
+
+  // 12b
+  test("two components with one id: the first is emitted and a warning says so", () => {
+    const a = new DebugExporter({ verbosity: "basic" });
+    const b = new DebugExporter({ verbosity: "detailed" });
+    const out = otelSerializer.serialize(entities({ a, b }));
+    expect(typeof out).toBe("object");
+    const result = out as { primary: string; warnings?: string[] };
+    expect((load(result.primary) as any).exporters.debug).toEqual({ verbosity: "basic" });
+    expect(result.warnings?.[0]).toContain('declare the id "debug"');
+  });
+
+  test("non-otel entities are ignored", () => {
+    const foreign = { lexicon: "k8s", entityType: "K8s::Core::ConfigMap", kind: "resource", props: {} } as unknown as Declarable;
+    expect(otelSerializer.serialize(entities({ foreign }))).toBe("");
+  });
+});

package/src/serializer.ts

@@ -0,0 +1,31 @@
+/**
+ * OpenTelemetry Collector serializer.
+ *
+ * Emits one collector config file from every otel entity in the build: the
+ * YAML `otelcol --config` reads as it is. Section order is fixed (receivers,
+ * processors, exporters, extensions, service); components and pipelines keep
+ * the order they are declared in, and each component's config keeps the key
+ * order it was written in, since collector docs and diffs read that way.
+ *
+ * A collector config has no metadata channel, so there is no ownership marker
+ * to stamp. A custom component's schema pin is written as a `# chant:` comment
+ * line above the config (see `define.ts`).
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import type { Serializer, SerializerResult } from "@intentius/chant/serializer";
+import type { LexiconOutput } from "@intentius/chant/lexicon-output";
+import { buildCollectorConfig } from "./collector";
+import { emitCollectorYaml } from "./yaml";
+
+export const otelSerializer: Serializer = {
+  name: "otel",
+  rulePrefix: "OTEL",
+
+  serialize(entities: Map<string, Declarable>, _outputs?: LexiconOutput[]): string | SerializerResult {
+    const built = buildCollectorConfig(entities);
+    const yaml = emitCollectorYaml(built.config, { header: built.header });
+    if (built.warnings.length === 0) return yaml;
+    return { primary: yaml, warnings: built.warnings };
+  },
+};

package/src/skill-defs.ts

@@ -0,0 +1,36 @@
+import { createSkillsLoader } from "@intentius/chant/lexicon-plugin-helpers";
+
+/** The otel lexicon's AI skills, read from src/skills/. */
+export const otelSkills = createSkillsLoader(import.meta.url, [
+  {
+    file: "chant-otel.md",
+    name: "chant-otel",
+    description: "Declare OpenTelemetry Collector config (receivers, processors, exporters, pipelines) as typed chant entities and build collector YAML",
+    triggers: [
+      { type: "context" as const, value: "opentelemetry" },
+      { type: "context" as const, value: "otel collector" },
+      { type: "file-pattern" as const, value: "*.otel.ts" },
+    ],
+    examples: [
+      {
+        title: "An OTLP-in, OTLP-out traces pipeline",
+        output:
+          'const otlp = new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:4317" } } });\n' +
+          'const backend = new OtlpExporter({ name: "backend", endpoint: "tempo:4317" });\n' +
+          "export const traces = new Pipeline({ signal: \"traces\", receivers: [otlp], exporters: [backend] });",
+      },
+    ],
+  },
+  {
+    file: "chant-otel-custom-components.md",
+    name: "chant-otel-custom-components",
+    description: "Add a collector component chant doesn't ship (a vendor exporter, an in-house processor) with defineComponent, and pin its schema",
+    triggers: [{ type: "context" as const, value: "otel custom component" }],
+  },
+  {
+    file: "chant-otel-platforms.md",
+    name: "chant-otel-platforms",
+    description: "Run a declared collector config on Kubernetes, GKE, Docker or Fly by rendering it into the platform's own config file",
+    triggers: [{ type: "context" as const, value: "deploy otel collector" }],
+  },
+]);

package/src/skills/chant-otel-custom-components.md

@@ -0,0 +1,51 @@
+---
+skill: chant-otel-custom-components
+description: Add a collector component chant doesn't ship (a vendor exporter, an in-house processor) with defineComponent, and pin its schema
+user-invocable: true
+---
+
+# Custom collector components
+
+chant ships a core set of collector components. For anything else, define the component once and use it like a built-in.
+
+```ts
+import { defineComponent, Pipeline, OtlpReceiver } from "@intentius/chant-lexicon-otel";
+
+export interface DatadogExporterConfig {
+  api: { key: string; site?: string };
+  traces?: { span_name_as_resource_name?: boolean };
+}
+
+export const DatadogExporter = defineComponent<DatadogExporterConfig>()({
+  kind: "exporter",
+  type: "datadog",
+  pin: {
+    source: "github.com/open-telemetry/opentelemetry-collector-contrib/exporter/datadogexporter",
+    version: "v0.130.0",
+  },
+  validate: (c) => (c.api.key.includes("${") ? [] : ["api.key must come from ${env:...}"]),
+  endpoints: (c) => [`https://api.${c.api.site ?? "datadoghq.com"}`],
+});
+
+export const dd = new DatadogExporter({ name: "eu", api: { key: "${env:DD_API_KEY}", site: "datadoghq.eu" } });
+export const traces = new Pipeline({ signal: "traces", receivers: [new OtlpReceiver({ protocols: { grpc: {} } })], exporters: [dd] });
+```
+
+## What you supply
+
+| Field | Required | Meaning |
+|---|---|---|
+| `kind` | yes | receiver, processor, exporter or extension |
+| `type` | yes | the collector type, the part of the id before `/` |
+| `pin` | yes | `{ source, version, digest? }`: where the config schema comes from and which release the type follows |
+| `validate` | no | a function returning problems, or any zod-compatible schema (anything with `safeParse`) |
+| `endpoints` | no | where the component sends or listens, for `collectorTopology()` |
+| `description` | no | one line for docs |
+
+## How it is checked and pinned
+
+- The same serializer emits it, and OTEL101-OTEL108 apply to it as to any built-in. `validate` failures are OTEL107.
+- The pin is written as a `# chant: exporter datadog/eu schema <source>@<version>` comment above the emitted config, and returned by `collectorTopology()`.
+- A definition without a usable pin fails the build (OTEL109).
+- chant records the pin; it does not fetch or verify the schema. Ship the definition in a package and the package version pins it for everyone who imports it.
+- You cannot redefine a built-in type. Declare a named instance instead (`new OtlpExporter({ name: "vendor", ... })`).

package/src/skills/chant-otel-platforms.md

@@ -0,0 +1,34 @@
+---
+skill: chant-otel-platforms
+description: Run a declared collector config on Kubernetes, GKE, Docker or Fly by rendering it into the platform's own config file
+user-invocable: true
+---
+
+# Running the collector config on a platform
+
+The otel lexicon produces collector YAML. A platform lexicon runs the collector and carries the YAML to it.
+
+## Rendering the YAML inside another lexicon
+
+`collectorYaml(entities)` returns exactly what the otel serializer would emit for those entities. Use it wherever a platform needs the config as a string:
+
+```ts
+import { OtlpReceiver, DebugExporter, Pipeline, collectorYaml } from "@intentius/chant-lexicon-otel";
+import { ConfigMap } from "@intentius/chant-lexicon-k8s";
+
+const otlp = new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:4317" } } });
+const debug = new DebugExporter({ verbosity: "basic" });
+
+export const collectorConfig = new ConfigMap({
+  metadata: { name: "otel-collector-config" },
+  data: { "config.yaml": collectorYaml([otlp, debug, new Pipeline({ signal: "traces", receivers: [otlp], exporters: [debug] })]) },
+});
+```
+
+## GKE
+
+The k8s lexicon's `GkeOtelCollector` composite is built this way: it declares an otlp receiver, batch and resourcedetection processors and a googlecloud exporter, renders them with `collectorYaml`, and mounts the result from a ConfigMap into a DaemonSet running under Workload Identity.
+
+## Checking a rendered config
+
+`validateCollectorConfig(config)` runs OTEL101-OTEL106 over any parsed collector config, so a composite's generated YAML can be checked in its own tests.