@intentius/chant-lexicon-otel 0.95.0 → 0.96.0

package/src/lint/post-synth/otel101.ts

@@ -1,7 +1,7 @@
 /**
  * OTEL101: A pipeline uses a receiver, processor or exporter that is not declared
  *
- * The collector refuses to start on this. Typed entity references cannot go wrong this way, so it mostly catches id strings (`"otlp/backend"`) and hand-edited or parsed configs. A connector id is accepted in receivers and exporters.
+ * The collector refuses to start on this. Typed entity references cannot go wrong this way, so it mostly catches id strings (`"otlp/backend"`) and hand-edited or parsed configs. A connector id is accepted in receivers and exporters, but a connector counts as used only when one pipeline lists it as an exporter and another lists it as a receiver; listed on one side only, it fails this check.
  */
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";

package/src/lint/post-synth/otel103.ts

@@ -1,7 +1,7 @@
 /**
  * OTEL103: A declared component is never used
  *
- * A receiver, processor or exporter no pipeline lists, or an extension missing from service.extensions, is ignored by the collector. Usually it means a pipeline was meant to list it. A warning, since the config still runs.
+ * A receiver, processor, exporter or connector no pipeline lists, or an extension missing from service.extensions, is ignored by the collector. Usually it means a pipeline was meant to list it. A warning, since the config still runs.
  */
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";

package/src/lint/post-synth/otel112.ts

@@ -0,0 +1,17 @@
+/**
+ * OTEL112: A connector joins pipelines whose signals it does not convert
+ *
+ * Each connector supports fixed signal pairs: `spanmetrics` and `servicegraph` read traces and write metrics, `count` writes metrics from any signal, `routing` and `forward` keep the signal. Every pipeline that feeds a connector must pair with a pipeline it feeds through one of those pairs, and the other way round, or the collector refuses to start. A traces pipeline that receives from `spanmetrics` fails this check. Custom connectors are checked when their `defineComponent` call lists `connects`.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { configDiagnostics } from "./otel-helpers";
+
+export const otel112: PostSynthCheck = {
+  id: "OTEL112",
+  description: "A connector joins pipelines whose signals it does not convert",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return configDiagnostics(ctx, "OTEL112");
+  },
+};

package/src/metric-names.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, test } from "vitest";
+import { PrometheusExporter, SpanMetricsConnector } from "./components";
+import { genAiComponents, genAiMetrics } from "./genai";
+import { prometheusLabel, prometheusMetricName, spanMetricsNames } from "./metric-names";
+
+describe("spanMetricsNames", () => {
+  test("defaults: the traces.span.metrics namespace and a millisecond histogram", () => {
+    const n = spanMetricsNames(new SpanMetricsConnector({}));
+    expect(n.namespace).toBe("traces.span.metrics");
+    expect(n.calls).toEqual({
+      name: "traces.span.metrics.calls",
+      prometheus: "traces_span_metrics_calls_total",
+      type: "sum",
+      dimensions: ["service.name", "span.name", "span.kind", "status.code"],
+    });
+    expect(n.duration?.prometheus).toBe("traces_span_metrics_duration_milliseconds");
+    expect(n.duration?.unit).toBe("ms");
+    expect(n.events).toBeUndefined();
+    expect(n.labels).toEqual({ service: "service_name", spanName: "span_name", spanKind: "span_kind", statusCode: "status_code" });
+    expect(n.errorStatus).toBe("STATUS_CODE_ERROR");
+  });
+
+  test("namespace, unit and dimensions come from the declaration", () => {
+    const connector = new SpanMetricsConnector({
+      namespace: "shop.spans",
+      dimensions: [{ name: "http.route" }],
+      calls_dimensions: [{ name: "peer.service" }],
+      exclude_dimensions: ["span.kind"],
+      histogram: { unit: "s", dimensions: [{ name: "http.method" }] },
+      events: { enabled: true, dimensions: [{ name: "exception.type" }] },
+    });
+    const n = spanMetricsNames(connector);
+    expect(n.calls.prometheus).toBe("shop_spans_calls_total");
+    expect(n.calls.dimensions).toEqual(["service.name", "span.name", "status.code", "http.route", "peer.service"]);
+    expect(n.duration?.prometheus).toBe("shop_spans_duration_seconds");
+    expect(n.duration?.dimensions).toEqual(["service.name", "span.name", "status.code", "http.route", "http.method"]);
+    expect(n.events?.prometheus).toBe("shop_spans_events_total");
+    expect(n.labels.spanKind).toBeUndefined();
+  });
+
+  test("an empty namespace means no prefix; a disabled histogram means no duration", () => {
+    const n = spanMetricsNames({ namespace: "", histogram: { disable: true } });
+    expect(n.calls.prometheus).toBe("calls_total");
+    expect(n.duration).toBeUndefined();
+  });
+
+  test("the exporter's namespace and suffix setting", () => {
+    const connector = new SpanMetricsConnector({ namespace: "spans" });
+    const exporter = new PrometheusExporter({ endpoint: "0.0.0.0:8889", namespace: "otel" });
+    expect(spanMetricsNames(connector, exporter).calls.prometheus).toBe("otel_spans_calls_total");
+    expect(spanMetricsNames(connector, { add_metric_suffixes: false }).duration?.prometheus).toBe("spans_duration");
+  });
+
+  test("only a spanmetrics connector", () => {
+    expect(() => spanMetricsNames(new PrometheusExporter({ endpoint: "0.0.0.0:8889" }) as never)).toThrow(/spanmetrics/);
+  });
+
+  test("agrees with genAiMetrics for the preset's own connector", () => {
+    for (const namespace of [undefined, "agents"]) {
+      const parts = genAiComponents({ namespace });
+      const n = spanMetricsNames(parts.spanMetrics);
+      const g = genAiMetrics({ namespace });
+      expect(n.calls.prometheus).toBe(g.calls.prometheus);
+      expect(n.duration?.prometheus).toBe(g.duration.prometheus);
+      expect(n.calls.dimensions).toEqual(g.calls.dimensions);
+    }
+  });
+});
+
+describe("prometheus naming", () => {
+  test("labels", () => {
+    expect(prometheusLabel("gen_ai.request.model")).toBe("gen_ai_request_model");
+    expect(prometheusLabel("0day")).toBe("key_0day");
+  });
+  test("suffixes are not doubled, and brace units add nothing", () => {
+    expect(prometheusMetricName("requests_total", "sum")).toBe("requests_total");
+    expect(prometheusMetricName("latency.seconds", "histogram", "s")).toBe("latency_seconds");
+    expect(prometheusMetricName("calls", "sum", "{call}")).toBe("calls_total");
+  });
+});

package/src/metric-names.ts

@@ -0,0 +1,176 @@
+/**
+ * The metric names a collector emits, as the `prometheus` exporter serves
+ * them: `spanMetricsNames()` for a `spanmetrics` connector, and the naming
+ * rules `genAiMetrics()` uses too.
+ *
+ * A dashboard or an SLO reads names from here instead of repeating them, so
+ * renaming the connector's namespace (or the exporter's) moves every query
+ * built from it.
+ *
+ * Naming follows the collector's Prometheus translation at `COLLECTOR_PIN`
+ * with the exporter's defaults: `.` and any other character Prometheus does
+ * not allow become `_`; counters take `_total`; a unit becomes a suffix
+ * (`ms` is `_milliseconds`, `s` is `_seconds`); the exporter's `namespace`
+ * is a prefix joined with `_`; `add_metric_suffixes: false` drops the
+ * suffixes. Attribute names become label names the same way
+ * (`service.name` is `service_name`).
+ *
+ * This module holds types and string functions only, so a lexicon that
+ * builds queries from it does not load the collector components.
+ */
+
+/** A metric a collector component emits, as the collector names it and as Prometheus exposes it. */
+export interface CollectorMetric {
+  /** The OTLP metric name. */
+  name: string;
+  /** The name the `prometheus` exporter serves; histograms add `_bucket`, `_sum` and `_count`. */
+  prometheus: string;
+  type: "sum" | "histogram";
+  unit?: string;
+  /** Attribute names on its data points, beyond the resource. Prometheus labels replace `.` with `_`. */
+  dimensions: string[];
+}
+
+/** The four dimensions spanmetrics puts on every metric unless `exclude_dimensions` names them. */
+export const SPANMETRICS_DEFAULT_DIMENSIONS: readonly string[] = Object.freeze(["service.name", "span.name", "span.kind", "status.code"]);
+
+/** The spanmetrics namespace when the connector sets none. */
+export const SPANMETRICS_DEFAULT_NAMESPACE = "traces.span.metrics";
+
+/** The `status.code` value of a span that ended in error: the value an error-ratio query selects. */
+export const SPAN_STATUS_ERROR = "STATUS_CODE_ERROR";
+
+/** The Prometheus unit words for the units collector components use. */
+const UNIT_WORDS: Record<string, string> = {
+  ms: "milliseconds",
+  s: "seconds",
+  us: "microseconds",
+  ns: "nanoseconds",
+  By: "bytes",
+  "1": "ratio",
+};
+
+/** How the `prometheus` exporter is configured, as far as naming goes. */
+export interface PrometheusNaming {
+  /** The exporter's `namespace`, put in front of every name and joined with `_`. */
+  namespace?: string;
+  /** The exporter's `add_metric_suffixes` (default true): unit and `_total` suffixes. */
+  add_metric_suffixes?: boolean;
+}
+
+/** An attribute name as a Prometheus label: `service.name` is `service_name`. */
+export function prometheusLabel(attribute: string): string {
+  const label = attribute.replace(/[^A-Za-z0-9_]/g, "_");
+  return /^[0-9]/.test(label) ? `key_${label}` : label;
+}
+
+/**
+ * An OTLP metric name as the `prometheus` exporter serves it.
+ *
+ * @param type `sum` (a monotonic counter, `_total`) or `histogram`.
+ * @param unit The metric's unit, e.g. `ms`. Units in braces (`{call}`) add nothing.
+ */
+export function prometheusMetricName(name: string, type: "sum" | "histogram", unit?: string, naming: PrometheusNaming = {}): string {
+  let out = name.replace(/[^A-Za-z0-9_:]/g, "_");
+  if (naming.namespace) out = `${naming.namespace.replace(/[^A-Za-z0-9_:]/g, "_")}_${out}`;
+  if (naming.add_metric_suffixes === false) return out;
+  const word = unit && !unit.startsWith("{") ? (UNIT_WORDS[unit] ?? unit.replace(/[^A-Za-z0-9_:]/g, "_")) : undefined;
+  if (word && !out.endsWith(`_${word}`)) out = `${out}_${word}`;
+  if (type === "sum" && !out.endsWith("_total")) out = `${out}_total`;
+  return out;
+}
+
+/** The parts of a spanmetrics config the metric names depend on. */
+export interface SpanMetricsNamingConfig {
+  namespace?: string;
+  dimensions?: Array<{ name: string }>;
+  calls_dimensions?: Array<{ name: string }>;
+  exclude_dimensions?: string[];
+  histogram?: { disable?: boolean; unit?: "ms" | "s"; dimensions?: Array<{ name: string }> };
+  events?: { enabled?: boolean; dimensions?: Array<{ name: string }> };
+}
+
+/** The metrics one `spanmetrics` connector emits, and the labels a query selects them by. */
+export interface SpanMetricsNames {
+  /** The connector's namespace (empty: no prefix). */
+  namespace: string;
+  /** Span count; `status.code` = `STATUS_CODE_ERROR` selects the errors. */
+  calls: CollectorMetric;
+  /** Span duration histogram. Absent when `histogram.disable` is set. */
+  duration?: CollectorMetric;
+  /** Span event count. Present only when `events.enabled` is set. */
+  events?: CollectorMetric;
+  /**
+   * The default dimensions as Prometheus labels. One is absent when
+   * `exclude_dimensions` leaves it out, so a query can't select by it.
+   */
+  labels: { service?: string; spanName?: string; spanKind?: string; statusCode?: string };
+  /** The `status_code` value of an error span. */
+  errorStatus: string;
+}
+
+type Declared = { componentType?: unknown; props?: unknown };
+
+function configOf(connector: SpanMetricsNamingConfig | Declared): SpanMetricsNamingConfig {
+  const d = connector as Declared;
+  if (typeof d.componentType === "string") {
+    if (d.componentType !== "spanmetrics") throw new Error(`spanMetricsNames: expected a spanmetrics connector, got ${d.componentType}`);
+    return (d.props ?? {}) as SpanMetricsNamingConfig;
+  }
+  return connector as SpanMetricsNamingConfig;
+}
+
+/**
+ * The Prometheus names of the metrics a `spanmetrics` connector emits, read
+ * from its declaration: its namespace, dimensions and histogram unit, and
+ * optionally the `prometheus` exporter's namespace and suffix setting.
+ *
+ * @example
+ * ```ts
+ * const spans = new SpanMetricsConnector({ namespace: "shop", histogram: { unit: "s" } });
+ * spanMetricsNames(spans).calls.prometheus;    // "shop_calls_total"
+ * spanMetricsNames(spans).duration!.prometheus; // "shop_duration_seconds"
+ * ```
+ */
+export function spanMetricsNames(
+  connector: SpanMetricsNamingConfig | Declared,
+  exporter?: PrometheusNaming | { props?: PrometheusNaming },
+): SpanMetricsNames {
+  const c = configOf(connector);
+  const naming: PrometheusNaming =
+    exporter && "props" in exporter && typeof exporter.props === "object" ? (exporter.props as PrometheusNaming) : ((exporter ?? {}) as PrometheusNaming);
+  const namespace = c.namespace ?? SPANMETRICS_DEFAULT_NAMESPACE;
+  const metricName = (n: string) => (namespace === "" ? n : `${namespace}.${n}`);
+  const excluded = new Set(c.exclude_dimensions ?? []);
+  const defaults = SPANMETRICS_DEFAULT_DIMENSIONS.filter((d) => !excluded.has(d));
+  const names = (extra?: Array<{ name: string }>) => (extra ?? []).map((d) => d.name);
+  const common = [...defaults, ...names(c.dimensions)];
+
+  const metric = (n: string, type: "sum" | "histogram", dims: string[], unit?: string): CollectorMetric => ({
+    name: metricName(n),
+    prometheus: prometheusMetricName(metricName(n), type, unit, naming),
+    type,
+    ...(unit ? { unit } : {}),
+    dimensions: dims,
+  });
+
+  const label = (attr: string) => (defaults.includes(attr) ? prometheusLabel(attr) : undefined);
+  const labels: SpanMetricsNames["labels"] = {};
+  const service = label("service.name");
+  const spanName = label("span.name");
+  const spanKind = label("span.kind");
+  const statusCode = label("status.code");
+  if (service) labels.service = service;
+  if (spanName) labels.spanName = spanName;
+  if (spanKind) labels.spanKind = spanKind;
+  if (statusCode) labels.statusCode = statusCode;
+
+  return {
+    namespace,
+    calls: metric("calls", "sum", [...common, ...names(c.calls_dimensions)]),
+    ...(c.histogram?.disable ? {} : { duration: metric("duration", "histogram", [...common, ...names(c.histogram?.dimensions)], c.histogram?.unit ?? "ms") }),
+    ...(c.events?.enabled ? { events: metric("events", "sum", [...common, ...names(c.events.dimensions)]) } : {}),
+    labels,
+    errorStatus: SPAN_STATUS_ERROR,
+  };
+}

package/src/model.ts

@@ -12,22 +12,44 @@
 export const SIGNALS = ["traces", "metrics", "logs"] as const;
 export type Signal = (typeof SIGNALS)[number];
 
-/** The component kinds this lexicon types. Connectors are not modeled yet. */
-export const COMPONENT_KINDS = ["receiver", "processor", "exporter", "extension"] as const;
+/**
+ * The component kinds this lexicon types. A connector is an exporter in one
+ * pipeline and a receiver in another, which is how one pipeline feeds another
+ * (traces into span metrics, say).
+ */
+export const COMPONENT_KINDS = ["receiver", "processor", "exporter", "connector", "extension"] as const;
 export type ComponentKind = (typeof COMPONENT_KINDS)[number];
 
+/** A top-level config section that holds components. */
+export type ComponentSection = "receivers" | "processors" | "exporters" | "connectors" | "extensions";
+
 /** The top-level config section each component kind lives under. */
-export const SECTION_OF: Record<ComponentKind, "receivers" | "processors" | "exporters" | "extensions"> = {
+export const SECTION_OF: Record<ComponentKind, ComponentSection> = {
   receiver: "receivers",
   processor: "processors",
   exporter: "exporters",
+  connector: "connectors",
   extension: "extensions",
 };
 
+/**
+ * One signal pair a connector supports: it is an exporter in a `from`
+ * pipeline and a receiver in a `to` pipeline. `spanmetrics` has one,
+ * traces to metrics; `forward` has one per signal. `profiles` is the
+ * collector's experimental fourth signal, which `count` reads.
+ */
+export interface ConnectorSignalPair {
+  from: Signal | "profiles";
+  to: Signal | "profiles";
+}
+
 /** A component id, `type` or `type/name`, exactly as the collector spells it. */
 export type ComponentId = string;
 
-/** One pipeline under `service.pipelines`. */
+/**
+ * One pipeline under `service.pipelines`. `receivers` and `exporters` may name
+ * connectors as well as receivers and exporters.
+ */
 export interface PipelineConfig {
   receivers?: ComponentId[];
   processors?: ComponentId[];

package/src/otelcol-validate.test.ts

@@ -0,0 +1,143 @@
+/**
+ * The filter, transform and redaction processors and the k8s_cluster and
+ * kubeletstats receivers, rendered into one config and checked by the real
+ * collector.
+ *
+ * The `otelcol validate` tests run when `otelcol-contrib` is on PATH (or
+ * `OTELCOL_BIN` names a contrib build) and skip otherwise; CI does not install
+ * it. The structural tests run everywhere.
+ */
+
+import { describe, expect, test } from "vitest";
+import { spawnSync } from "child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { load } from "js-yaml";
+import type { Declarable } from "@intentius/chant/declarable";
+import { collectorYaml } from "./collector";
+import { validateCollectorConfig, validateCollectorEntities } from "./validate-config";
+import type { CollectorConfig } from "./model";
+import { Pipeline } from "./pipeline";
+import {
+  DebugExporter,
+  FilterProcessor,
+  K8sClusterReceiver,
+  KubeletStatsReceiver,
+  OtlpReceiver,
+  RedactionProcessor,
+  TransformProcessor,
+} from "./components";
+
+function findOtelcol(): string | undefined {
+  const candidates = [process.env.OTELCOL_BIN, "otelcol-contrib"].filter((c): c is string => !!c);
+  for (const bin of candidates) {
+    const r = spawnSync(bin, ["--version"], { encoding: "utf-8" });
+    if (r.status === 0) return bin;
+  }
+  return undefined;
+}
+
+const OTELCOL = findOtelcol();
+
+function otelcolValidate(yaml: string): { ok: boolean; output: string } {
+  const dir = mkdtempSync(join(tmpdir(), "chant-otelcol-"));
+  try {
+    const file = join(dir, "config.yaml");
+    writeFileSync(file, yaml);
+    // kubeletstats and k8s_cluster are built during validate; auth_type none keeps them off the Kubernetes API.
+    const r = spawnSync(OTELCOL!, ["validate", `--config=${file}`], { encoding: "utf-8", timeout: 60_000 });
+    return { ok: r.status === 0, output: `${r.stdout ?? ""}${r.stderr ?? ""}` };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function fixture(): Declarable[] {
+  const otlp = new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:4317" } } });
+  const cluster = new K8sClusterReceiver({
+    auth_type: "none",
+    collection_interval: "30s",
+    node_conditions_to_report: ["Ready", "MemoryPressure"],
+    allocatable_types_to_report: ["cpu", "memory", "pods"],
+  });
+  const kubelet = new KubeletStatsReceiver({
+    auth_type: "none",
+    endpoint: "http://localhost:10255",
+    metric_groups: ["node", "pod", "container"],
+    extra_metadata_labels: ["container.id"],
+  });
+  const dropHealth = new FilterProcessor({
+    name: "health",
+    error_mode: "ignore",
+    traces: { span: ['attributes["http.route"] == "/healthz"'] },
+    metrics: { datapoint: ['metric.name == "k8s.pod.phase" and value_int == 0'] },
+    logs: { log_record: ["severity_number < SEVERITY_NUMBER_INFO"] },
+  });
+  const tidy = new TransformProcessor({
+    error_mode: "ignore",
+    trace_statements: [
+      { context: "span", conditions: ["kind == SPAN_KIND_SERVER"], statements: ['set(attributes["tier"], "edge")'] },
+      'delete_key(span.attributes, "http.request.header.cookie")',
+    ],
+    metric_statements: [{ context: "datapoint", statements: ['delete_key(attributes, "pod_ip")'] }],
+    log_statements: [{ context: "log", statements: ['set(severity_text, "WARN") where severity_number == 13'] }],
+  });
+  const scrub = new RedactionProcessor({
+    allow_all_keys: true,
+    blocked_key_patterns: ["^gen_ai\\.(prompt|completion)"],
+    blocked_values: ["4[0-9]{12}(?:[0-9]{3})?"],
+    allowed_values: [".+@example\\.com"],
+    hash_function: "sha3",
+    summary: "silent",
+  });
+  const debug = new DebugExporter({});
+  return [
+    otlp,
+    cluster,
+    kubelet,
+    dropHealth,
+    tidy,
+    scrub,
+    debug,
+    new Pipeline({ signal: "traces", receivers: [otlp], processors: [dropHealth, tidy, scrub], exporters: [debug] }),
+    new Pipeline({ signal: "metrics", receivers: [cluster, kubelet], processors: [dropHealth, tidy], exporters: [debug] }),
+    new Pipeline({ signal: "logs", receivers: [otlp], processors: [dropHealth, tidy, scrub], exporters: [debug] }),
+  ];
+}
+
+describe("rendered config with filter, transform, redaction, k8s_cluster and kubeletstats", () => {
+  test("passes the lexicon's own checks", () => {
+    const entities = fixture();
+    expect(validateCollectorEntities(entities)).toEqual([]);
+    const config = load(collectorYaml(entities)) as CollectorConfig;
+    expect(validateCollectorConfig(config)).toEqual([]);
+    expect(Object.keys(config.receivers ?? {})).toEqual(["otlp", "k8s_cluster", "kubeletstats"]);
+    expect(Object.keys(config.processors ?? {})).toEqual(["filter/health", "transform", "redaction"]);
+    expect(config.service?.pipelines?.metrics?.receivers).toEqual(["k8s_cluster", "kubeletstats"]);
+  });
+
+  test("OTTL and regexes reach the YAML unchanged", () => {
+    const config = load(collectorYaml(fixture())) as any;
+    expect(config.processors["filter/health"].traces.span).toEqual(['attributes["http.route"] == "/healthz"']);
+    expect(config.processors.transform.trace_statements[1]).toBe('delete_key(span.attributes, "http.request.header.cookie")');
+    expect(config.processors.redaction.blocked_key_patterns).toEqual(["^gen_ai\\.(prompt|completion)"]);
+  });
+
+  test.skipIf(!OTELCOL)("otelcol validate accepts it", () => {
+    const { ok, output } = otelcolValidate(collectorYaml(fixture()));
+    expect(output).toBe("");
+    expect(ok).toBe(true);
+  });
+
+  test.skipIf(!OTELCOL)("otelcol validate rejects OTTL written for the wrong context", () => {
+    const otlp = new OtlpReceiver({ protocols: { grpc: {} } });
+    const bad = new FilterProcessor({ traces: { span: ['metric.name == "x"'] } });
+    const debug = new DebugExporter({});
+    const { ok, output } = otelcolValidate(
+      collectorYaml([otlp, bad, debug, new Pipeline({ signal: "traces", receivers: [otlp], processors: [bad], exporters: [debug] })]),
+    );
+    expect(ok).toBe(false);
+    expect(output).toContain("unable to parse OTTL condition");
+  });
+});

package/src/pipeline.ts

@@ -5,6 +5,10 @@
  * keeps the reference checked by TypeScript, or by id string (`otlp/backend`)
  * for a component declared somewhere chant can't see. OTEL101 catches a
  * string that names nothing declared.
+ *
+ * A connector goes in `exporters` of the pipeline that feeds it and in
+ * `receivers` of the pipeline it feeds. The same entity on both sides is what
+ * joins the two pipelines.
  */
 
 import { createResource } from "@intentius/chant/runtime";
@@ -12,7 +16,7 @@ import type { Declarable } from "@intentius/chant/declarable";
 import type { OTelComponent } from "./define";
 import { componentId, type ComponentKind, type Signal } from "./model";
 
-/** A reference to a component of kind `K`: the declared entity, or its id. */
+/** A reference to a component of kind `K` (or of any kind in a union): the declared entity, or its id. */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type ComponentRef<K extends ComponentKind> = OTelComponent<K, string, any> | string;
 
@@ -20,9 +24,11 @@ export interface PipelineProps {
   signal: Signal;
   /** The instance name. The pipeline id becomes `signal/name`. */
   name?: string;
-  receivers: ComponentRef<"receiver">[];
+  /** Receivers, and connectors this pipeline takes data from. */
+  receivers: ComponentRef<"receiver" | "connector">[];
   processors?: ComponentRef<"processor">[];
-  exporters: ComponentRef<"exporter">[];
+  /** Exporters, and connectors this pipeline hands data to. */
+  exporters: ComponentRef<"exporter" | "connector">[];
 }
 
 export interface PipelineEntity extends Declarable {

package/src/plugin.test.ts

@@ -28,6 +28,7 @@ describe("otel plugin", () => {
       "OTEL107",
       "OTEL108",
       "OTEL109",
+      "OTEL112",
     ]);
     for (const id of ids) expect(id.startsWith("OTEL")).toBe(true);
   });

package/src/plugin.ts

@@ -26,7 +26,7 @@ const catalogResource: McpResourceContribution = {
 /**
  * OpenTelemetry Collector lexicon plugin.
  *
- * Typed receivers, processors, exporters and extensions, pipelines and the
+ * Typed receivers, processors, exporters, connectors 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.

package/src/semconv.ts

@@ -0,0 +1,63 @@
+/**
+ * Semantic-convention vocabularies a collector config can depend on, and how
+ * to tell that it does.
+ *
+ * A collector config has no metadata channel, so a config cannot say which
+ * semconv version its attribute keys follow. What it can show is that it uses
+ * a vocabulary: a `spanmetrics` dimension named `gen_ai.request.model`, an
+ * OTTL statement deleting `gen_ai.input.messages`. `semconvUsage()` finds
+ * those and pairs each vocabulary with the pin this package's keys follow, the
+ * same way `collectorTopology()` pairs a component type with the pin of the
+ * definition this process has. Reading a parsed YAML file and reading the
+ * declaration give the same answer.
+ */
+
+import { GENAI_SEMCONV_PIN, type SchemaPin } from "./define";
+import { SECTION_OF, type CollectorConfig, type ComponentKind } from "./model";
+
+/** One attribute vocabulary and the version of its conventions this package follows. */
+export interface SemconvVocabulary {
+  /** The attribute namespace, e.g. `gen_ai`. */
+  namespace: string;
+  pin: SchemaPin;
+  /** True when a string in a component's config refers to this namespace. */
+  matches: (text: string) => boolean;
+}
+
+// `gen_ai.` as a key, in OTTL (`attributes["gen_ai.x"]`) or in an RE2 pattern (`gen_ai\.`).
+const GEN_AI_REF = /(^|[^A-Za-z0-9_])gen_ai(\\\\|\\)?\./;
+
+export const SEMCONV_VOCABULARIES: ReadonlyArray<SemconvVocabulary> = Object.freeze([
+  { namespace: "gen_ai", pin: GENAI_SEMCONV_PIN, matches: (text: string) => GEN_AI_REF.test(text) },
+]);
+
+/** A vocabulary a config uses, with the components that use it. */
+export interface SemconvUsage extends SchemaPin {
+  namespace: string;
+  /** Component ids whose config names an attribute of this namespace, in config order. */
+  components: string[];
+}
+
+function mentions(value: unknown, test: (text: string) => boolean): boolean {
+  if (typeof value === "string") return test(value);
+  if (Array.isArray(value)) return value.some((v) => mentions(v, test));
+  if (value && typeof value === "object") {
+    return Object.entries(value as Record<string, unknown>).some(([k, v]) => test(k) || mentions(v, test));
+  }
+  return false;
+}
+
+/** The semconv vocabularies a collector config uses, each with its pin and the components that use it. */
+export function semconvUsage(config: CollectorConfig): SemconvUsage[] {
+  const out: SemconvUsage[] = [];
+  for (const vocab of SEMCONV_VOCABULARIES) {
+    const components: string[] = [];
+    for (const kind of Object.keys(SECTION_OF) as ComponentKind[]) {
+      for (const [id, cfg] of Object.entries(config[SECTION_OF[kind]] ?? {})) {
+        if (mentions(cfg, vocab.matches)) components.push(id);
+      }
+    }
+    if (components.length > 0) out.push({ namespace: vocab.namespace, ...vocab.pin, components });
+  }
+  return out;
+}

package/src/serializer.ts

@@ -3,7 +3,7 @@
  *
  * 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
+ * processors, exporters, connectors, 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.
  *