@intentius/chant-lexicon-otel 0.95.1 → 0.96.0

package/dist/rules/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/dist/semconv.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 { type SchemaPin } from "./define.js";
+import { type CollectorConfig } from "./model.js";
+/** 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;
+}
+export declare const SEMCONV_VOCABULARIES: ReadonlyArray<SemconvVocabulary>;
+/** 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[];
+}
+/** The semconv vocabularies a collector config uses, each with its pin and the components that use it. */
+export declare function semconvUsage(config: CollectorConfig): SemconvUsage[];
+//# sourceMappingURL=semconv.d.ts.map

package/dist/semconv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semconv.d.ts","sourceRoot":"","sources":["../src/semconv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AAC7D,OAAO,EAAc,KAAK,eAAe,EAAsB,MAAM,SAAS,CAAC;AAE/E,wFAAwF;AACxF,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,SAAS,CAAC;IACf,2EAA2E;IAC3E,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CACpC;AAKD,eAAO,MAAM,oBAAoB,EAAE,aAAa,CAAC,iBAAiB,CAEhE,CAAC;AAEH,mEAAmE;AACnE,MAAM,WAAW,YAAa,SAAQ,SAAS;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,wFAAwF;IACxF,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAWD,0GAA0G;AAC1G,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,YAAY,EAAE,CAYpE"}

package/dist/serializer.d.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.
  *

package/dist/skills/chant-otel.md

@@ -6,7 +6,7 @@ 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.
+The otel lexicon (`@intentius/chant-lexicon-otel`) types collector config. Each receiver, processor, exporter, connector and extension is an entity, pipelines reference them, and `chant build` writes one collector config file.
 
 ## Project setup
 
@@ -40,13 +40,36 @@ Emits `receivers.otlp`, `processors.memory_limiter` and `processors.batch`, `exp
 
 | Kind | Types |
 |---|---|
-| receivers | otlp, prometheus, hostmetrics, filelog |
-| processors | batch, memory_limiter, resource, attributes, k8sattributes, resourcedetection |
-| exporters | otlp, otlphttp, debug, prometheus, googlecloud |
+| receivers | otlp, prometheus, hostmetrics, filelog, k8s_cluster, kubeletstats |
+| processors | batch, memory_limiter, resource, attributes, k8sattributes, resourcedetection, filter, transform, redaction, tail_sampling, probabilistic_sampler |
+| exporters | otlp, otlphttp, debug, prometheus, googlecloud, loadbalancing |
+| connectors | spanmetrics, servicegraph, routing, forward, count, sum |
 | extensions | health_check, pprof, zpages |
 
 Anything else goes through `defineComponent`; see the `chant-otel-custom-components` skill.
 
+## Connectors
+
+A connector joins two pipelines. List the same entity in `exporters` of the pipeline that feeds it and in `receivers` of the pipeline it feeds:
+
+```ts
+export const spanmetrics = new SpanMetricsConnector({ dimensions: [{ name: "http.route" }] });
+export const traces = new Pipeline({ signal: "traces", receivers: [otlp], exporters: [backend, spanmetrics] });
+export const red = new Pipeline({ signal: "metrics", name: "red", receivers: [spanmetrics], exporters: [prom] });
+```
+
+`spanmetrics` and `servicegraph` turn traces into metrics, `count` and `sum` turn any signal into metrics (`sum` adds up a numeric attribute), `routing` and `forward` keep the signal. A connector on one side only fails OTEL101; a pipeline whose signal the connector can't pair fails OTEL112.
+
+## GenAI workloads
+
+For services that emit GenAI spans, start from the preset instead of writing the processors by hand:
+
+```ts
+export const collector = genAiPipeline({ traceExporters: [tempo], metricExporters: [prom] });
+```
+
+It deletes prompt, completion, system-instruction and tool-call content from spans, span events and logs, and derives call, error, duration and token metrics (`genai_calls_total`, `genai_duration_seconds`, `genai_tokens_input_total`, `genai_tokens_output_total`) from every GenAI span before sampling. Keep content only when asked, with `keepContent: true`. `genAiComponents()` returns the pieces for hand-built pipelines.
+
 ## 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.
@@ -57,4 +80,4 @@ Anything else goes through `defineComponent`; see the `chant-otel-custom-compone
 
 ## 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.
+`collectorTopologyOf(entities)` returns the pipelines, each component's endpoints and schema pin, for each exporter the signals it carries, the connector `edges` between pipelines, and under `semconv` the semantic-conventions version (`GENAI_SEMCONV_PIN`) the config's `gen_ai.` keys follow, as plain data.

package/dist/topology.d.ts

@@ -3,14 +3,18 @@
  *
  * `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.
+ * and schema pins, for each exporter the pipelines and signals it carries,
+ * the edges connectors make from one pipeline to another, and the
+ * semantic-convention versions its attribute keys follow. 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 { type SchemaPin } from "./define.js";
 import { type CollectorConfig, type ComponentKind } from "./model.js";
+import { type SemconvUsage } from "./semconv.js";
+export type { SemconvUsage } from "./semconv.js";
 export interface TopologyPipeline {
     /** The id under `service.pipelines`, e.g. `traces` or `traces/backend`. */
     id: string;
@@ -32,9 +36,22 @@ export interface TopologyComponent {
     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. */
+    /** The pipelines that use it. For a connector, those on either side; for an extension, empty. */
     pipelines: string[];
 }
+/** One hop from a pipeline to another through a connector. */
+export interface TopologyEdge {
+    /** The connector's id. */
+    connector: string;
+    /** The pipeline that lists the connector as an exporter. */
+    from: string;
+    /** That pipeline's signal. */
+    fromSignal: string;
+    /** The pipeline that lists the connector as a receiver. */
+    to: string;
+    /** That pipeline's signal. */
+    toSignal: string;
+}
 export interface TopologyExporter {
     id: string;
     type: string;
@@ -48,6 +65,18 @@ export interface CollectorTopology {
     components: TopologyComponent[];
     /** The exporters again, grouped for the question "where does this telemetry go". */
     exporters: TopologyExporter[];
+    /**
+     * Pipeline-to-pipeline edges through connectors, one per (from, to) pair the
+     * connector supports. For a connector whose definition this process lacks,
+     * every pair.
+     */
+    edges: TopologyEdge[];
+    /**
+     * The semantic-convention vocabularies the config's attribute keys come
+     * from, each with the pin this package follows for it (`GENAI_SEMCONV_PIN`
+     * for `gen_ai`) and the components that use it. Empty when none is used.
+     */
+    semconv: SemconvUsage[];
 }
 /** The topology of a collector config. */
 export declare function collectorTopology(config: CollectorConfig): CollectorTopology;

package/dist/topology.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"topology.d.ts","sourceRoot":"","sources":["../src/topology.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,EAAgD,KAAK,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAEjH,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,EAAE,EAAE,MAAM,CAAC;IACX,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kHAAkH;IAClH,OAAO,EAAE,OAAO,CAAC;IACjB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,wGAAwG;IACxG,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,kEAAkE;IAClE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,oFAAoF;IACpF,SAAS,EAAE,gBAAgB,EAAE,CAAC;CAC/B;AAeD,0CAA0C;AAC1C,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,iBAAiB,CA4C5E;AAED,gGAAgG;AAChG,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,iBAAiB,CAE/G"}
+{"version":3,"file":"topology.d.ts","sourceRoot":"","sources":["../src/topology.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,EAAgD,KAAK,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AACjH,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAE5D,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,EAAE,EAAE,MAAM,CAAC;IACX,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kHAAkH;IAClH,OAAO,EAAE,OAAO,CAAC;IACjB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,wGAAwG;IACxG,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,iGAAiG;IACjG,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,kEAAkE;IAClE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,oFAAoF;IACpF,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B;;;;OAIG;IACH,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB;;;;OAIG;IACH,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAeD,0CAA0C;AAC1C,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,iBAAiB,CA2D5E;AAED,gGAAgG;AAChG,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,iBAAiB,CAE/G"}

package/dist/validate-config.d.ts

@@ -9,7 +9,8 @@
  */
 import type { Declarable } from "@intentius/chant/declarable";
 import { type CollectorConfig } from "./model.js";
-export type CollectorIssueCode = "OTEL101" | "OTEL102" | "OTEL103" | "OTEL104" | "OTEL105" | "OTEL106" | "OTEL107" | "OTEL108" | "OTEL109";
+import "./components/connectors.js";
+export type CollectorIssueCode = "OTEL101" | "OTEL102" | "OTEL103" | "OTEL104" | "OTEL105" | "OTEL106" | "OTEL107" | "OTEL108" | "OTEL109" | "OTEL112";
 export interface CollectorIssue {
     code: CollectorIssueCode;
     severity: "error" | "warning";
@@ -19,7 +20,10 @@ export interface CollectorIssue {
     /** The component id the issue is about, when it is about one. */
     component?: string;
 }
-/** Check a collector config's references and pipeline shape (OTEL101-OTEL106). */
+/**
+ * Check a collector config's references and pipeline shape (OTEL101-OTEL106),
+ * and each connector's signals against its definition (OTEL112).
+ */
 export declare function validateCollectorConfig(config: CollectorConfig): CollectorIssue[];
 /**
  * Check declared entities for what only the declaration knows (OTEL107-OTEL109):

package/dist/validate-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-config.d.ts","sourceRoot":"","sources":["../src/validate-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAG9D,OAAO,EAA0C,KAAK,eAAe,EAAE,MAAM,SAAS,CAAC;AAGvF,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,CAAC;AAEd,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,kBAAkB,CAAC;IACzB,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAQD,kFAAkF;AAClF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,eAAe,GAAG,cAAc,EAAE,CA2HjF;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,cAAc,EAAE,CAyDpH"}
+{"version":3,"file":"validate-config.d.ts","sourceRoot":"","sources":["../src/validate-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAG9D,OAAO,EAA4D,KAAK,eAAe,EAA4B,MAAM,SAAS,CAAC;AAGnI,OAAO,yBAAyB,CAAC;AAEjC,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,CAAC;AAEd,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,kBAAkB,CAAC;IACzB,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAkBD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,eAAe,GAAG,cAAc,EAAE,CA0JjF;AA2CD;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,cAAc,EAAE,CAyDpH"}

package/dist/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAiB,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAMvF,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAEvF,0DAA0D;AAC1D,eAAO,MAAM,cAAc,UAqB1B,CAAC;AAEF,wBAAsB,QAAQ,IAAI,OAAO,CAAC,cAAc,CAAC,CA2CxD"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAiB,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAMvF,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAEvF,0DAA0D;AAC1D,eAAO,MAAM,cAAc,UA6B1B,CAAC;AAEF,wBAAsB,QAAQ,IAAI,OAAO,CAAC,cAAc,CAAC,CA2CxD"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@intentius/chant-lexicon-otel",
-  "version": "0.95.1",
-  "description": "OpenTelemetry Collector lexicon for chant — typed receivers, processors, exporters, extensions and pipelines, serialized to collector YAML",
+  "version": "0.96.0",
+  "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",
   "repository": {
@@ -68,7 +68,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.95.1",
+    "@intentius/chant": "^0.96.0",
     "typescript": "^5.9.3"
   }
 }

package/src/catalog.ts

@@ -6,13 +6,14 @@
 
 import type { LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
 import { componentEntityType, type ComponentClass } from "./define";
+import type { ComponentKind } from "./model";
 import * as components from "./components";
 import { PIPELINE_TYPE, SERVICE_TYPE } from "./pipeline";
 
 export interface CatalogEntry {
   className: string;
   entityType: string;
-  kind: "receiver" | "processor" | "exporter" | "extension" | "pipeline" | "service";
+  kind: ComponentKind | "pipeline" | "service";
   /** The collector type, for components. */
   type?: string;
   description: string;

package/src/codegen/docs.ts

@@ -13,8 +13,8 @@ function serviceFromType(resourceType: string): string {
 }
 
 const overview = `The otel lexicon types [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)
-config: receivers, processors, exporters, extensions and the pipelines that
-connect them. \`chant build\` emits one collector config file, the YAML
+config: receivers, processors, exporters, connectors, extensions and the
+pipelines that connect them. \`chant build\` emits one collector config file, the YAML
 \`otelcol --config\` reads as it is.
 
 \`\`\`ts
@@ -32,10 +32,15 @@ export const traces = new Pipeline({
 });
 \`\`\`
 
-The built-in component set is otlp, prometheus, hostmetrics and filelog
-receivers; batch, memory_limiter, resource, attributes, k8sattributes and
-resourcedetection processors; otlp, otlphttp, debug, prometheus and
-googlecloud exporters; and the health_check, pprof and zpages extensions.
+The built-in component set is otlp, prometheus, hostmetrics, filelog,
+k8s_cluster and kubeletstats receivers; batch, memory_limiter, resource,
+attributes, k8sattributes, resourcedetection, filter, transform, redaction,
+tail_sampling and probabilistic_sampler processors; otlp, otlphttp, debug,
+prometheus, googlecloud and loadbalancing exporters; spanmetrics,
+servicegraph, routing, forward, count and sum connectors; and the
+health_check, pprof and zpages extensions. \`genAiPipeline()\` is a preset for
+GenAI workloads: it removes prompt and completion content and derives agent
+RED and token metrics.
 Their config types follow the collector-contrib release named on the
 Custom components page. A component chant doesn't ship is added with
 \`defineComponent\`, and it is serialized and checked the same way as the
@@ -43,13 +48,14 @@ built-ins.
 
 Checks catch a pipeline that uses a component nobody declared (OTEL101), a
 pipeline with no receivers or exporters (OTEL102), a declared component no
-pipeline uses (OTEL103), and a literal credential in source (OTEL002).
+pipeline uses (OTEL103), a connector joining pipelines of signals it can't
+convert (OTEL112), and a literal credential in source (OTEL002).
 `;
 
 const outputFormat = `The otel lexicon serializes every otel entity in a build into **one
 collector config file** in YAML, the file \`otelcol --config\` reads.
 
-- Sections come out as receivers, processors, exporters, extensions, service,
+- Sections come out as receivers, processors, exporters, connectors, extensions, service,
   separated by a blank line. Empty sections are left out.
 - A component's id is its collector type, or \`type/name\` when its \`name\` is
   set. The export name in source never appears in the output.

package/src/collector.ts

@@ -12,10 +12,14 @@ import { definitionFor, isOTelComponent, type OTelComponent } from "./define";
 import { SECTION_OF, type CollectorConfig, type PipelineConfig } from "./model";
 import { isPipelineEntity, isServiceEntity, type ComponentRef, type PipelineEntity, type ServiceEntity } from "./pipeline";
 import { emitCollectorYaml } from "./yaml";
+import { semconvUsage } from "./semconv";
 
 export interface BuiltCollector {
   config: CollectorConfig;
-  /** One line per custom component naming its schema pin. Becomes the YAML's `# chant:` header. */
+  /**
+   * One line per custom component naming its schema pin, and one per semconv
+   * vocabulary the config uses. Becomes the YAML's `# chant:` header.
+   */
   header: string[];
   /** Non-fatal problems, e.g. two components declaring the same id. */
   warnings: string[];
@@ -136,6 +140,10 @@ export function buildCollectorConfig(entities: Iterable<Declarable> | Map<string
     const digest = pin?.digest ? ` ${pin.digest}` : "";
     header.push(`chant: ${c.componentKind} ${c.componentId} schema ${pin?.source ?? "(unpinned)"}@${pin?.version ?? "(unpinned)"}${digest}`);
   }
+  for (const use of semconvUsage(config)) {
+    const digest = use.digest ? ` ${use.digest}` : "";
+    header.push(`chant: semconv ${use.namespace} ${use.source}@${use.version}${digest} (${use.components.join(", ")})`);
+  }
 
   return { config, header, warnings, components, pipelines, service };
 }

package/src/components/connectors.ts

@@ -0,0 +1,276 @@
+/**
+ * Built-in connectors: spanmetrics, servicegraph, routing, forward, count, sum.
+ *
+ * A connector is an exporter in one pipeline and a receiver in another. Put
+ * the same entity in `exporters` of the pipeline that feeds it and in
+ * `receivers` of the pipeline it feeds. `connects` lists the signal pairs each
+ * connector's factory registers; OTEL112 checks pipelines against them.
+ */
+
+import { defineBuiltin } from "../define";
+import type { ConnectorSignalPair } from "../model";
+import type { Duration } from "./common";
+
+const SAME_SIGNAL: ConnectorSignalPair[] = [
+  { from: "traces", to: "traces" },
+  { from: "metrics", to: "metrics" },
+  { from: "logs", to: "logs" },
+];
+
+// ── spanmetrics ──────────────────────────────────────────────────────
+
+/** A span or resource attribute added as a metric dimension. */
+export interface SpanMetricsDimension {
+  name: string;
+  /** Value used when the attribute is missing. Without it, spans lacking the attribute get no dimension. */
+  default?: string;
+}
+
+export interface SpanMetricsConnectorConfig {
+  /** Extra dimensions on every metric, beyond service.name, span.name, span.kind and status.code. */
+  dimensions?: SpanMetricsDimension[];
+  /** Extra dimensions on the calls metric only. */
+  calls_dimensions?: SpanMetricsDimension[];
+  /** Default dimensions to leave out. */
+  exclude_dimensions?: string[];
+  resource_metrics_cache_size?: number;
+  /** Resource attributes that key the metrics' resource, so a restart doesn't start a new series. */
+  resource_metrics_key_attributes?: string[];
+  aggregation_temporality?: "AGGREGATION_TEMPORALITY_CUMULATIVE" | "AGGREGATION_TEMPORALITY_DELTA";
+  histogram?: {
+    disable?: boolean;
+    unit?: "ms" | "s";
+    /** Explicit bucket boundaries. Set this or `exponential`, not both. */
+    explicit?: { buckets?: Duration[] };
+    exponential?: { max_size?: number };
+    /** Extra dimensions on the duration histogram only. */
+    dimensions?: SpanMetricsDimension[];
+  };
+  /** How often metrics are emitted (default 60s). */
+  metrics_flush_interval?: Duration;
+  /** Drop a series not updated for this long. */
+  metrics_expiration?: Duration;
+  metric_timestamp_cache_size?: number;
+  /** Prefix for the emitted metric names (default `traces.span.metrics`). */
+  namespace?: string;
+  exemplars?: { enabled?: boolean; max_per_data_point?: number };
+  /** Also count span events. Needs `dimensions` when enabled. */
+  events?: { enabled?: boolean; dimensions?: SpanMetricsDimension[] };
+  include_instrumentation_scope?: string[];
+  aggregation_cardinality_limit?: number;
+}
+
+/** Turns spans into request, error and duration (RED) metrics. */
+export const SpanMetricsConnector = defineBuiltin<SpanMetricsConnectorConfig, "connector", "spanmetrics">({
+  kind: "connector",
+  type: "spanmetrics",
+  description: "Turns spans into call-count and duration metrics per service, span name, kind and status",
+  connects: [{ from: "traces", to: "metrics" }],
+  validate: (c) => {
+    const problems: string[] = [];
+    if (c.histogram?.explicit && c.histogram?.exponential) {
+      problems.push("histogram: set explicit or exponential buckets, not both");
+    }
+    if (c.events?.enabled && (c.events.dimensions ?? []).length === 0) {
+      problems.push("events: enabled needs at least one dimension");
+    }
+    const reserved = new Set(["service.name", "span.name", "span.kind", "status.code"]);
+    for (const d of c.dimensions ?? []) {
+      if (reserved.has(d.name)) problems.push(`dimensions: "${d.name}" is already a default dimension`);
+      reserved.add(d.name);
+    }
+    return problems;
+  },
+});
+
+// ── servicegraph ─────────────────────────────────────────────────────
+
+export interface ServiceGraphConnectorConfig {
+  latency_histogram_buckets?: Duration[];
+  /** Span attributes added as dimensions on the edge metrics. */
+  dimensions?: string[];
+  /** How long an unpaired client or server span waits for its other half. */
+  store?: { ttl?: Duration; max_items?: number };
+  cache_loop?: Duration;
+  store_expiration_loop?: Duration;
+  /** Attributes that name the peer when only one side of a call is instrumented. */
+  virtual_node_peer_attributes?: string[];
+  virtual_node_extra_label?: boolean;
+  metrics_flush_interval?: Duration;
+  /** Attributes that name the database for a database call edge. */
+  database_name_attributes?: string[];
+}
+
+/** Builds service-to-service edge metrics from paired client and server spans. */
+export const ServiceGraphConnector = defineBuiltin<ServiceGraphConnectorConfig, "connector", "servicegraph">({
+  kind: "connector",
+  type: "servicegraph",
+  description: "Builds service-to-service request and latency metrics from paired client and server spans",
+  connects: [{ from: "traces", to: "metrics" }],
+});
+
+// ── routing ──────────────────────────────────────────────────────────
+
+export interface RoutingTableItem {
+  /** The OTTL context the condition runs in. `request` routes on request metadata such as headers. */
+  context?: "resource" | "span" | "metric" | "datapoint" | "log" | "request";
+  /** An OTTL `route() where ...` statement. Set this or `condition`, not both. */
+  statement?: string;
+  /** An OTTL condition. Set this or `statement`, not both. */
+  condition?: string;
+  /** Pipeline ids (`traces/tenant-a`) that receive matching data. Each must list this connector as a receiver. */
+  pipelines: string[];
+}
+
+export interface RoutingConnectorConfig {
+  table: RoutingTableItem[];
+  /** Pipelines for data no route matches. */
+  default_pipelines?: string[];
+  error_mode?: "ignore" | "silent" | "propagate";
+}
+
+/** Sends each item to the pipelines whose route matches it. */
+export const RoutingConnector = defineBuiltin<RoutingConnectorConfig, "connector", "routing">({
+  kind: "connector",
+  type: "routing",
+  description: "Routes traces, metrics or logs to pipelines by OTTL condition",
+  connects: SAME_SIGNAL,
+  validate: (c) => {
+    const problems: string[] = [];
+    if ((c.table ?? []).length === 0) problems.push("table is empty");
+    (c.table ?? []).forEach((item, i) => {
+      if (!item.statement && !item.condition) problems.push(`table[${i}]: set a condition or a statement`);
+      if (item.statement && item.condition) problems.push(`table[${i}]: set a condition or a statement, not both`);
+      if (item.context === "request" && !item.condition) problems.push(`table[${i}]: the request context needs a condition`);
+      if ((item.pipelines ?? []).length === 0) problems.push(`table[${i}]: no pipelines`);
+    });
+    return problems;
+  },
+});
+
+// ── forward ──────────────────────────────────────────────────────────
+
+export interface ForwardConnectorConfig {}
+
+/** Passes data unchanged from one pipeline to another of the same signal. */
+export const ForwardConnector = defineBuiltin<ForwardConnectorConfig, "connector", "forward">({
+  kind: "connector",
+  type: "forward",
+  description: "Passes data unchanged to another pipeline of the same signal",
+  connects: SAME_SIGNAL,
+});
+
+// ── count ────────────────────────────────────────────────────────────
+
+export interface CountMetricInfo {
+  description?: string;
+  /** OTTL conditions; an item is counted when any matches. None counts every item. */
+  conditions?: string[];
+  /** Attributes to split the count by. Not supported for `metrics`. */
+  attributes?: Array<{ key: string; default_value?: string | number | boolean }>;
+}
+
+/** Each key is the name of a metric to emit. */
+export interface CountConnectorConfig {
+  spans?: Record<string, CountMetricInfo>;
+  spanevents?: Record<string, CountMetricInfo>;
+  metrics?: Record<string, CountMetricInfo>;
+  datapoints?: Record<string, CountMetricInfo>;
+  logs?: Record<string, CountMetricInfo>;
+  profiles?: Record<string, CountMetricInfo>;
+}
+
+/** Counts spans, span events, metrics, data points or log records, as metrics. */
+export const CountConnector = defineBuiltin<CountConnectorConfig, "connector", "count">({
+  kind: "connector",
+  type: "count",
+  description: "Counts spans, span events, metrics, data points or log records and emits the counts as metrics",
+  connects: [
+    { from: "traces", to: "metrics" },
+    { from: "metrics", to: "metrics" },
+    { from: "logs", to: "metrics" },
+    { from: "profiles", to: "metrics" },
+  ],
+  validate: (c) => {
+    const problems: string[] = [];
+    for (const [section, metrics] of Object.entries(c) as Array<[string, Record<string, CountMetricInfo> | undefined]>) {
+      for (const [name, info] of Object.entries(metrics ?? {})) {
+        if (name === "") problems.push(`${section}: metric name missing`);
+        if (section === "metrics" && (info?.attributes ?? []).length > 0) {
+          problems.push(`metrics.${name}: attributes are not supported when counting metrics`);
+        }
+      }
+    }
+    return problems;
+  },
+});
+
+// ── sum ──────────────────────────────────────────────────────────────
+
+export interface SumMetricInfo {
+  /** The attribute whose numeric value is summed. Strings that parse as numbers count; others are skipped. */
+  source_attribute: string;
+  description?: string;
+  /** OTTL conditions; an item is summed when any matches. None sums every item that has the attribute. */
+  conditions?: string[];
+  /**
+   * Attributes to split the sum by. Not supported for `metrics`. An item
+   * missing one of them is skipped unless it has a `default_value`. Use at
+   * most one: with more, the pinned collector adds each value once per
+   * attribute (OTEL107 reports it).
+   */
+  attributes?: Array<{ key: string; default_value?: string | number | boolean }>;
+}
+
+/**
+ * Each key is the name of a metric to emit. The connector emits monotonic
+ * sums with delta temporality; the `prometheus` exporter accumulates them,
+ * while an exporter that needs cumulative input wants a `deltatocumulative`
+ * processor in front of it.
+ */
+export interface SumConnectorConfig {
+  spans?: Record<string, SumMetricInfo>;
+  spanevents?: Record<string, SumMetricInfo>;
+  metrics?: Record<string, SumMetricInfo>;
+  datapoints?: Record<string, SumMetricInfo>;
+  logs?: Record<string, SumMetricInfo>;
+}
+
+/** Sums a numeric attribute of spans, span events, data points or log records, as metrics. */
+export const SumConnector = defineBuiltin<SumConnectorConfig, "connector", "sum">({
+  kind: "connector",
+  type: "sum",
+  description: "Sums a numeric attribute of spans, span events, data points or log records and emits the sums as metrics",
+  connects: [
+    { from: "traces", to: "metrics" },
+    { from: "metrics", to: "metrics" },
+    { from: "logs", to: "metrics" },
+  ],
+  validate: (c) => {
+    const problems: string[] = [];
+    let total = 0;
+    for (const [section, metrics] of Object.entries(c) as Array<[string, Record<string, SumMetricInfo> | undefined]>) {
+      for (const [name, info] of Object.entries(metrics ?? {})) {
+        total++;
+        if (name === "") problems.push(`${section}: metric name missing`);
+        if (!info?.source_attribute) problems.push(`${section}.${name}: source_attribute is missing`);
+        if (section === "metrics" && (info?.attributes ?? []).length > 0) {
+          problems.push(`${section}.${name}: attributes are not supported when summing metrics`);
+        }
+        (info?.attributes ?? []).forEach((a, i) => {
+          if (!a.key) problems.push(`${section}.${name}.attributes[${i}]: key is missing`);
+        });
+        // At the pinned release the connector adds each value once per
+        // attribute key (sumconnector summer.increment), so two keys double
+        // every sum.
+        if ((info?.attributes ?? []).length > 1) {
+          problems.push(
+            `${section}.${name}: more than one attribute multiplies each sum by the number of attributes in the pinned collector; split by one attribute`,
+          );
+        }
+      }
+    }
+    if (total === 0) problems.push("no metric is configured, so the connector emits nothing");
+    return problems;
+  },
+});