@intentius/chant-lexicon-otel 0.100.0 → 0.102.0

package/src/platform.ts

@@ -17,6 +17,7 @@ import { DebugExporter } from "./components/exporters";
 import { HealthCheckExtension } from "./components/extensions";
 import { Pipeline } from "./pipeline";
 import { SIGNALS, parseComponentId, type CollectorConfig, type Signal } from "./model";
+import { receiverListenerPaths } from "./validate-config";
 
 /** 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/, "")}`;
@@ -95,35 +96,38 @@ function portName(parts: string[]): string {
   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);
+/** The value at a key path, if every key on the way is there. */
+function valueAt(value: unknown, path: string[]): unknown {
+  let cur: unknown = value;
+  for (const key of path) {
+    if (!cur || typeof cur !== "object" || Array.isArray(cur)) return undefined;
+    cur = (cur as Record<string, unknown>)[key];
   }
+  return cur;
 }
 
 const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
 
 /**
- * The ports a built collector config listens on: every receiver `endpoint`,
+ * The ports a built collector config listens on: the endpoint of every
+ * receiver that listens (otlp, zipkin, jaeger; the receivers OTEL117 knows),
  * named after the receiver and the protocol key above it (`otlp-grpc`,
- * `otlp-http`), and the `health_check` port if the service enables it.
+ * `otlp-http`), and the `health_check` port if the service enables it. A
+ * receiver whose `endpoint` is a server it connects to, such as
+ * kubeletstats' kubelet, adds no port, and neither does a receiver type the
+ * table doesn't list.
  */
 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);
+    for (const path of receiverListenerPaths(parsed?.type ?? id)) {
+      const p = portOf(valueAt(receiverConfig, path));
       if (!p || seen.has(p.port)) continue;
       seen.add(p.port);
-      const protocol = path.filter((k) => k !== "protocols");
+      const protocol = path.slice(0, -1).filter((k) => k !== "protocols");
       ports.push({ name: portName([...base, ...protocol]), port: p.port });
     }
   }

package/src/plugin.test.ts

@@ -29,6 +29,11 @@ describe("otel plugin", () => {
       "OTEL108",
       "OTEL109",
       "OTEL112",
+      "OTEL113",
+      "OTEL114",
+      "OTEL115",
+      "OTEL116",
+      "OTEL117",
     ]);
     for (const id of ids) expect(id.startsWith("OTEL")).toBe(true);
   });
@@ -53,4 +58,17 @@ describe("otel plugin", () => {
     expect(otelPlugin.mcpTools!().map((t) => t.name)).toEqual(["otel:diff"]);
     expect(otelPlugin.mcpResources!().map((r) => r.uri)).toEqual(["otel:resource-catalog"]);
   });
+
+  it("reports the collector topology for the graph, and nothing for a project without one", async () => {
+    const { OtlpReceiver, DebugExporter } = await import("./components");
+    const { Pipeline } = await import("./pipeline");
+    expect(otelPlugin.graphMeta!(new Map())).toBeUndefined();
+    expect(otelPlugin.graphMeta!(new Map([["other", { lexicon: "k8s", entityType: "Pod" } as never]]))).toBeUndefined();
+    const otlp = new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:4317" } } });
+    const debug = new DebugExporter({});
+    const meta = otelPlugin.graphMeta!(new Map<string, never>([["otlp", otlp as never], ["debug", debug as never], ["p", new Pipeline({ signal: "traces", receivers: [otlp], exporters: [debug] }) as never]]));
+    const collector = meta!.collector as { pipelines: { id: string }[]; exporters: { id: string; signals: string[] }[] };
+    expect(collector.pipelines.map((p) => p.id)).toEqual(["traces"]);
+    expect(collector.exporters.map((e) => [e.id, e.signals])).toEqual([["debug", ["traces"]]]);
+  });
 });

package/src/plugin.ts

@@ -14,7 +14,10 @@ import { OtelCollectorGenerator } from "./import/generator";
 import { collectorConfigImporter } from "./import/embedded";
 import { otelSkills } from "./skill-defs";
 import { BUILTIN_CATALOG } from "./catalog";
+import { compositeCatalog } from "./composites/catalog";
+import { DEFAULT_TEMPLATE, GENAI_TEMPLATE, K8S_AGENT_TEMPLATE } from "./init-templates";
 import { COLLECTOR_PIN } from "./define";
+import { collectorTopologyOf } from "./topology";
 
 const catalogResource: McpResourceContribution = {
   uri: "otel:resource-catalog",
@@ -77,6 +80,14 @@ export const otelPlugin: LexiconPlugin = {
     return rules;
   },
 
+  // Where this project's telemetry goes, for `chant workspace graph` (#2559).
+  // A project with no collector pipeline and no component reports nothing.
+  graphMeta(entities) {
+    const topology = collectorTopologyOf(entities.values());
+    if (topology.pipelines.length === 0 && topology.components.length === 0) return undefined;
+    return { collector: topology };
+  },
+
   postSynthChecks() {
     return postSynthChecks;
   },
@@ -87,6 +98,10 @@ export const otelPlugin: LexiconPlugin = {
 
   skills: otelSkills,
 
+  composites() {
+    return compositeCatalog;
+  },
+
   mcpTools() {
     return [createDiffTool(otelSerializer, "Compare current collector config output against the previous build", "otel")];
   },
@@ -95,6 +110,13 @@ export const otelPlugin: LexiconPlugin = {
     return [catalogResource];
   },
 
+  // `chant init --lexicon otel [--template k8s-agent|genai]`; see ./init-templates.ts.
+  initTemplates(template?: string) {
+    if (template === "k8s-agent") return K8S_AGENT_TEMPLATE;
+    if (template === "genai") return GENAI_TEMPLATE;
+    return DEFAULT_TEMPLATE;
+  },
+
   detectTemplate(data: unknown) {
     return detectTemplate(data);
   },

package/src/skills/chant-otel.md

@@ -15,6 +15,10 @@ The otel lexicon (`@intentius/chant-lexicon-otel`) types collector config. Each
 export default { lexicons: ["otel"] };
 ```
 
+`chant init --lexicon otel` scaffolds a collector; `--template k8s-agent` scaffolds a per-node Kubernetes agent and `--template genai` a GenAI collector.
+
+For a per-node Kubernetes agent, `NodeAgent({ exporters, metricExporters?, clusterName?, kubeletStats? })` declares the whole config: OTLP, host metrics, container logs, `k8sattributes` filtered to the node, and `memory_limiter` first and `batch` last on every pipeline. Pass `Object.values(agent.members)` wherever an entity list is taken, such as the k8s lexicon's `OtelCollector` `config`, which adds what the config reads from the node: `K8S_NODE_NAME` from `spec.nodeName`, the host root at `/hostfs` and `/var/log/pods` read-only, group 0 for the log files, and the RBAC.
+
 ## Declaring components
 
 Every component class takes the collector's own config keys (snake_case, as in the collector docs) plus an optional `name`. The id is `type`, or `type/name` when `name` is set.
@@ -41,10 +45,10 @@ Emits `receivers.otlp`, `processors.memory_limiter` and `processors.batch`, `exp
 | Kind | Types |
 |---|---|
 | receivers | otlp, prometheus, hostmetrics, filelog, k8s_cluster, kubeletstats |
-| processors | batch, memory_limiter, resource, attributes, k8sattributes, resourcedetection, filter, transform, redaction, tail_sampling, probabilistic_sampler |
+| processors | batch, memory_limiter, resource, attributes, k8sattributes, resourcedetection, filter, transform, redaction, tail_sampling, probabilistic_sampler, deltatocumulative |
 | exporters | otlp, otlphttp, debug, prometheus, googlecloud, loadbalancing |
-| connectors | spanmetrics, servicegraph, routing, forward, count, sum |
-| extensions | health_check, pprof, zpages |
+| connectors | spanmetrics, servicegraph, routing, forward, count, sum, signaltometrics |
+| extensions | health_check, pprof, zpages, k8s_leader_elector |
 
 Anything else goes through `defineComponent`; see the `chant-otel-custom-components` skill.
 
@@ -58,7 +62,7 @@ export const traces = new Pipeline({ signal: "traces", receivers: [otlp], export
 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.
+`spanmetrics` and `servicegraph` turn traces into metrics, `count` and `sum` turn any signal into metrics (`sum` adds up a numeric attribute), `signaltometrics` builds metrics you name, of any type, from any signal with OTTL values, `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. Pipelines that feed each other in a loop through connectors fail OTEL113, a connector id that is also a receiver or exporter id fails OTEL114, and every pipeline a `routing` connector routes to must list it in `receivers` (OTEL115).
 
 ## GenAI workloads
 
@@ -68,7 +72,7 @@ For services that emit GenAI spans, start from the preset instead of writing the
 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.
+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`. When a dashboard or backend expects the semantic conventions' names, add `clientMetrics: "derive"` for `gen_ai.client.operation.duration` and `gen_ai.client.token.usage` from spans, or `"passthrough"` when the SDK already records them; never both. Read metric names from `genAiMetrics(options)` (`.client` for the conventions' ones) instead of writing them out. `genAiComponents()` returns the pieces for hand-built pipelines. The token sums and derived client metrics are deltas: `deltaToCumulative: "auto"` puts a `deltatocumulative` processor in front of any metric exporter other than `prometheus` or `debug` (the default with `clientMetrics: "derive"`), `true` always, `false` never.
 
 ## Rules
 
@@ -76,6 +80,8 @@ It deletes prompt, completion, system-instruction and tool-call content from spa
 - Put `memory_limiter` first in `processors` (OTEL105).
 - Never write a credential literally. Use `"${env:NAME}"` and the collector reads it at start-up (OTEL002).
 - Every pipeline needs at least one receiver and one exporter (OTEL102). A declared component no pipeline uses is a warning (OTEL103).
+- Don't split metrics by a per-request id (`gen_ai.conversation.id`, `gen_ai.response.id`, `gen_ai.tool.call.id`, `session.id`, `user.id`, `enduser.id`) or a content key: each value starts new time series (OTEL116).
+- Give every listener its own port. The collector's own metrics already use localhost:8888, so a `prometheus` exporter there makes it exit with "address already in use" (OTEL117).
 - Declared extensions are enabled in declaration order unless a `Service` lists `extensions` itself.
 
 ## Starting from an existing config

package/src/testdata/genai-configured.yaml

@@ -0,0 +1,108 @@
+# chant: semconv gen_ai github.com/open-telemetry/semantic-conventions@v1.41.1 (transform/genai_content, redaction/genai_content, filter/genai_spans, spanmetrics/genai, sum/genai_tokens)
+
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+      http:
+        endpoint: 0.0.0.0:4318
+
+processors:
+  memory_limiter:
+    check_interval: 1s
+    limit_percentage: 80
+    spike_limit_percentage: 20
+  transform/genai_content:
+    error_mode: ignore
+    trace_statements:
+      - context: span
+        statements: ["delete_key(span.attributes, \"gen_ai.system_instructions\")", "delete_key(span.attributes, \"gen_ai.input.messages\")", "delete_key(span.attributes, \"gen_ai.output.messages\")", "delete_key(span.attributes, \"gen_ai.tool.call.arguments\")", "delete_key(span.attributes, \"gen_ai.tool.call.result\")", "delete_key(span.attributes, \"gen_ai.retrieval.query.text\")", "delete_key(span.attributes, \"gen_ai.retrieval.documents\")", "delete_key(span.attributes, \"gen_ai.prompt\")", "delete_key(span.attributes, \"gen_ai.completion\")", "delete_matching_keys(span.attributes, \"^gen_ai\\\\.(prompt|completion)\\\\.[0-9]+\\\\..+$\")"]
+      - context: spanevent
+        statements: ["delete_key(spanevent.attributes, \"gen_ai.system_instructions\")", "delete_key(spanevent.attributes, \"gen_ai.input.messages\")", "delete_key(spanevent.attributes, \"gen_ai.output.messages\")", "delete_key(spanevent.attributes, \"gen_ai.tool.call.arguments\")", "delete_key(spanevent.attributes, \"gen_ai.tool.call.result\")", "delete_key(spanevent.attributes, \"gen_ai.retrieval.query.text\")", "delete_key(spanevent.attributes, \"gen_ai.retrieval.documents\")", "delete_key(spanevent.attributes, \"gen_ai.prompt\")", "delete_key(spanevent.attributes, \"gen_ai.completion\")", "delete_matching_keys(spanevent.attributes, \"^gen_ai\\\\.(prompt|completion)\\\\.[0-9]+\\\\..+$\")"]
+    log_statements:
+      - context: log
+        statements: ["delete_key(log.attributes, \"gen_ai.system_instructions\")", "delete_key(log.attributes, \"gen_ai.input.messages\")", "delete_key(log.attributes, \"gen_ai.output.messages\")", "delete_key(log.attributes, \"gen_ai.tool.call.arguments\")", "delete_key(log.attributes, \"gen_ai.tool.call.result\")", "delete_key(log.attributes, \"gen_ai.retrieval.query.text\")", "delete_key(log.attributes, \"gen_ai.retrieval.documents\")", "delete_key(log.attributes, \"gen_ai.prompt\")", "delete_key(log.attributes, \"gen_ai.completion\")", "delete_matching_keys(log.attributes, \"^gen_ai\\\\.(prompt|completion)\\\\.[0-9]+\\\\..+$\")", "delete_matching_keys(log.body, \"^(content|message|tool_calls)$\") where IsMap(log.body) and (IsMatch(log.event_name, \"^(gen_ai\\\\.system\\\\.message|gen_ai\\\\.user\\\\.message|gen_ai\\\\.assistant\\\\.message|gen_ai\\\\.tool\\\\.message|gen_ai\\\\.choice)$\") or IsMatch(log.attributes[\"event.name\"], \"^(gen_ai\\\\.system\\\\.message|gen_ai\\\\.user\\\\.message|gen_ai\\\\.assistant\\\\.message|gen_ai\\\\.tool\\\\.message|gen_ai\\\\.choice)$\"))", "set(log.body, \"\") where IsString(log.body) and (IsMatch(log.event_name, \"^(gen_ai\\\\.system\\\\.message|gen_ai\\\\.user\\\\.message|gen_ai\\\\.assistant\\\\.message|gen_ai\\\\.tool\\\\.message|gen_ai\\\\.choice)$\") or IsMatch(log.attributes[\"event.name\"], \"^(gen_ai\\\\.system\\\\.message|gen_ai\\\\.user\\\\.message|gen_ai\\\\.assistant\\\\.message|gen_ai\\\\.tool\\\\.message|gen_ai\\\\.choice)$\"))"]
+  redaction/genai_content:
+    allow_all_keys: true
+    blocked_key_patterns: [^(gen_ai\.system_instructions|gen_ai\.input\.messages|gen_ai\.output\.messages|gen_ai\.tool\.call\.arguments|gen_ai\.tool\.call\.result|gen_ai\.retrieval\.query\.text|gen_ai\.retrieval\.documents|gen_ai\.prompt|gen_ai\.completion)$, "^gen_ai\\.(prompt|completion)\\.[0-9]+\\..+$"]
+    blocked_values: ["secret-[a-z]+"]
+  filter/sampler:
+    traces:
+      span: [status.code != STATUS_CODE_ERROR]
+  batch: {}
+  filter/genai_spans:
+    error_mode: ignore
+    traces:
+      span: ["attributes[\"gen_ai.operation.name\"] == nil"]
+
+exporters:
+  otlp/tempo:
+    endpoint: tempo:4317
+    tls:
+      insecure: true
+  prometheus:
+    endpoint: 0.0.0.0:8889
+  debug:
+    verbosity: basic
+
+connectors:
+  forward/genai: {}
+  forward/sampled: {}
+  spanmetrics/genai:
+    namespace: agents.support
+    dimensions:
+      - name: gen_ai.operation.name
+      - name: gen_ai.request.model
+      - name: gen_ai.tool.name
+      - name: error.type
+      - name: gen_ai.agent.name
+    histogram:
+      unit: s
+      explicit:
+        buckets: [100ms, 250ms, 500ms, 1s, 2s, 5s, 10s, 20s, 40s, 80s]
+    metrics_flush_interval: 15s
+  sum/genai_tokens:
+    spans:
+      agents.support.tokens.input:
+        source_attribute: gen_ai.usage.input_tokens
+        description: Input tokens used by GenAI operations
+        conditions: ["attributes[\"gen_ai.usage.input_tokens\"] != nil and not (kind == SPAN_KIND_INTERNAL and (attributes[\"gen_ai.operation.name\"] == \"invoke_agent\" or attributes[\"gen_ai.operation.name\"] == \"invoke_workflow\"))"]
+        attributes:
+          - key: gen_ai.request.model
+            default_value: unknown
+      agents.support.tokens.output:
+        source_attribute: gen_ai.usage.output_tokens
+        description: Output tokens used by GenAI operations
+        conditions: ["attributes[\"gen_ai.usage.output_tokens\"] != nil and not (kind == SPAN_KIND_INTERNAL and (attributes[\"gen_ai.operation.name\"] == \"invoke_agent\" or attributes[\"gen_ai.operation.name\"] == \"invoke_workflow\"))"]
+        attributes:
+          - key: gen_ai.request.model
+            default_value: unknown
+
+extensions:
+  health_check:
+    endpoint: 0.0.0.0:13133
+
+service:
+  extensions: [health_check]
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [memory_limiter, transform/genai_content, redaction/genai_content]
+      exporters: [forward/genai, forward/sampled]
+    traces/sampled:
+      receivers: [forward/sampled]
+      processors: [filter/sampler, batch]
+      exporters: [otlp/tempo]
+    traces/genai:
+      receivers: [forward/genai]
+      processors: [filter/genai_spans]
+      exporters: [spanmetrics/genai, sum/genai_tokens]
+    metrics/genai:
+      receivers: [spanmetrics/genai, sum/genai_tokens]
+      processors: [batch]
+      exporters: [prometheus]
+    logs:
+      receivers: [otlp]
+      processors: [memory_limiter, transform/genai_content, redaction/genai_content, batch]
+      exporters: [debug]

package/src/testdata/genai-default.yaml

@@ -0,0 +1,92 @@
+# chant: semconv gen_ai github.com/open-telemetry/semantic-conventions@v1.41.1 (transform/genai_content, redaction/genai_content, filter/genai_spans, spanmetrics/genai, sum/genai_tokens)
+
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+      http:
+        endpoint: 0.0.0.0:4318
+
+processors:
+  memory_limiter:
+    check_interval: 1s
+    limit_percentage: 80
+    spike_limit_percentage: 20
+  transform/genai_content:
+    error_mode: ignore
+    trace_statements:
+      - context: span
+        statements: ["delete_key(span.attributes, \"gen_ai.system_instructions\")", "delete_key(span.attributes, \"gen_ai.input.messages\")", "delete_key(span.attributes, \"gen_ai.output.messages\")", "delete_key(span.attributes, \"gen_ai.tool.call.arguments\")", "delete_key(span.attributes, \"gen_ai.tool.call.result\")", "delete_key(span.attributes, \"gen_ai.retrieval.query.text\")", "delete_key(span.attributes, \"gen_ai.retrieval.documents\")", "delete_key(span.attributes, \"gen_ai.prompt\")", "delete_key(span.attributes, \"gen_ai.completion\")", "delete_matching_keys(span.attributes, \"^gen_ai\\\\.(prompt|completion)\\\\.[0-9]+\\\\..+$\")"]
+      - context: spanevent
+        statements: ["delete_key(spanevent.attributes, \"gen_ai.system_instructions\")", "delete_key(spanevent.attributes, \"gen_ai.input.messages\")", "delete_key(spanevent.attributes, \"gen_ai.output.messages\")", "delete_key(spanevent.attributes, \"gen_ai.tool.call.arguments\")", "delete_key(spanevent.attributes, \"gen_ai.tool.call.result\")", "delete_key(spanevent.attributes, \"gen_ai.retrieval.query.text\")", "delete_key(spanevent.attributes, \"gen_ai.retrieval.documents\")", "delete_key(spanevent.attributes, \"gen_ai.prompt\")", "delete_key(spanevent.attributes, \"gen_ai.completion\")", "delete_matching_keys(spanevent.attributes, \"^gen_ai\\\\.(prompt|completion)\\\\.[0-9]+\\\\..+$\")"]
+    log_statements:
+      - context: log
+        statements: ["delete_key(log.attributes, \"gen_ai.system_instructions\")", "delete_key(log.attributes, \"gen_ai.input.messages\")", "delete_key(log.attributes, \"gen_ai.output.messages\")", "delete_key(log.attributes, \"gen_ai.tool.call.arguments\")", "delete_key(log.attributes, \"gen_ai.tool.call.result\")", "delete_key(log.attributes, \"gen_ai.retrieval.query.text\")", "delete_key(log.attributes, \"gen_ai.retrieval.documents\")", "delete_key(log.attributes, \"gen_ai.prompt\")", "delete_key(log.attributes, \"gen_ai.completion\")", "delete_matching_keys(log.attributes, \"^gen_ai\\\\.(prompt|completion)\\\\.[0-9]+\\\\..+$\")", "delete_matching_keys(log.body, \"^(content|message|tool_calls)$\") where IsMap(log.body) and (IsMatch(log.event_name, \"^(gen_ai\\\\.system\\\\.message|gen_ai\\\\.user\\\\.message|gen_ai\\\\.assistant\\\\.message|gen_ai\\\\.tool\\\\.message|gen_ai\\\\.choice)$\") or IsMatch(log.attributes[\"event.name\"], \"^(gen_ai\\\\.system\\\\.message|gen_ai\\\\.user\\\\.message|gen_ai\\\\.assistant\\\\.message|gen_ai\\\\.tool\\\\.message|gen_ai\\\\.choice)$\"))", "set(log.body, \"\") where IsString(log.body) and (IsMatch(log.event_name, \"^(gen_ai\\\\.system\\\\.message|gen_ai\\\\.user\\\\.message|gen_ai\\\\.assistant\\\\.message|gen_ai\\\\.tool\\\\.message|gen_ai\\\\.choice)$\") or IsMatch(log.attributes[\"event.name\"], \"^(gen_ai\\\\.system\\\\.message|gen_ai\\\\.user\\\\.message|gen_ai\\\\.assistant\\\\.message|gen_ai\\\\.tool\\\\.message|gen_ai\\\\.choice)$\"))"]
+  redaction/genai_content:
+    allow_all_keys: true
+    blocked_key_patterns: [^(gen_ai\.system_instructions|gen_ai\.input\.messages|gen_ai\.output\.messages|gen_ai\.tool\.call\.arguments|gen_ai\.tool\.call\.result|gen_ai\.retrieval\.query\.text|gen_ai\.retrieval\.documents|gen_ai\.prompt|gen_ai\.completion)$, "^gen_ai\\.(prompt|completion)\\.[0-9]+\\..+$"]
+  batch: {}
+  filter/genai_spans:
+    error_mode: ignore
+    traces:
+      span: ["attributes[\"gen_ai.operation.name\"] == nil"]
+
+exporters:
+  debug:
+    verbosity: basic
+
+connectors:
+  forward/genai: {}
+  spanmetrics/genai:
+    namespace: genai
+    dimensions:
+      - name: gen_ai.operation.name
+      - name: gen_ai.request.model
+      - name: gen_ai.tool.name
+      - name: error.type
+    histogram:
+      unit: s
+      explicit:
+        buckets: [100ms, 250ms, 500ms, 1s, 2s, 5s, 10s, 20s, 40s, 80s]
+    metrics_flush_interval: 15s
+  sum/genai_tokens:
+    spans:
+      genai.tokens.input:
+        source_attribute: gen_ai.usage.input_tokens
+        description: Input tokens used by GenAI operations
+        conditions: ["attributes[\"gen_ai.usage.input_tokens\"] != nil and not (kind == SPAN_KIND_INTERNAL and (attributes[\"gen_ai.operation.name\"] == \"invoke_agent\" or attributes[\"gen_ai.operation.name\"] == \"invoke_workflow\"))"]
+        attributes:
+          - key: gen_ai.request.model
+            default_value: unknown
+      genai.tokens.output:
+        source_attribute: gen_ai.usage.output_tokens
+        description: Output tokens used by GenAI operations
+        conditions: ["attributes[\"gen_ai.usage.output_tokens\"] != nil and not (kind == SPAN_KIND_INTERNAL and (attributes[\"gen_ai.operation.name\"] == \"invoke_agent\" or attributes[\"gen_ai.operation.name\"] == \"invoke_workflow\"))"]
+        attributes:
+          - key: gen_ai.request.model
+            default_value: unknown
+
+extensions:
+  health_check:
+    endpoint: 0.0.0.0:13133
+
+service:
+  extensions: [health_check]
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [memory_limiter, transform/genai_content, redaction/genai_content, batch]
+      exporters: [debug, forward/genai]
+    traces/genai:
+      receivers: [forward/genai]
+      processors: [filter/genai_spans]
+      exporters: [spanmetrics/genai, sum/genai_tokens]
+    metrics/genai:
+      receivers: [spanmetrics/genai, sum/genai_tokens]
+      processors: [batch]
+      exporters: [debug]
+    logs:
+      receivers: [otlp]
+      processors: [memory_limiter, transform/genai_content, redaction/genai_content, batch]
+      exporters: [debug]

package/src/topology.test.ts

@@ -56,6 +56,18 @@ describe("collectorTopology", () => {
     ]);
   });
 
+  test("reports the wire protocols a component speaks, and none for one that states none (#2558)", () => {
+    const topo = collectorTopologyOf(entities);
+    const protocols = (id: string) => topo.components.find((c) => c.id === id)!.protocols;
+    expect(protocols("otlp")).toEqual(["grpc", "http/protobuf", "http/json"]);
+    expect(protocols("otlphttp/honeycomb")).toEqual(["http/protobuf"]);
+    expect(protocols("health_check")).toEqual([]);
+    const json = collectorTopologyOf([new OtlpHttpExporter({ endpoint: "https://x", encoding: "json" })]);
+    expect(json.components[0]!.protocols).toEqual(["http/json"]);
+    const httpOnly = collectorTopologyOf([new OtlpReceiver({ protocols: { http: {} } })]);
+    expect(httpOnly.components[0]!.protocols).toEqual(["http/protobuf", "http/json"]);
+  });
+
   test("reports receiver listen addresses, defaults included, and extension endpoints", () => {
     const topo = collectorTopologyOf(entities);
     expect(topo.components.find((c) => c.id === "otlp")!.endpoints).toEqual(["0.0.0.0:4317", "localhost:4318"]);

package/src/topology.ts

@@ -41,6 +41,11 @@ 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 wire protocols it speaks, as OTLP SDKs name them (`grpc`, `http/protobuf`, `http/json`).
+   * Empty when its definition states none, which a protocol check reads as unknown.
+   */
+  protocols: string[];
   /** The pipelines that use it. For a connector, those on either side; for an extension, empty. */
   pipelines: string[];
 }
@@ -87,6 +92,16 @@ export interface CollectorTopology {
   semconv: SemconvUsage[];
 }
 
+function protocolsOf(kind: ComponentKind, type: string, config: Record<string, unknown> | null | undefined): string[] {
+  const def = definitionOf(kind, type);
+  if (!def?.protocols) return [];
+  try {
+    return def.protocols((config ?? {}) as never);
+  } catch {
+    return [];
+  }
+}
+
 function endpointsOf(kind: ComponentKind, type: string, config: Record<string, unknown> | null | undefined): string[] {
   const def = definitionOf(kind, type);
   const cfg = config ?? {};
@@ -131,6 +146,7 @@ export function collectorTopology(config: CollectorConfig): CollectorTopology {
         builtin: def?.builtin ?? false,
         ...(def ? { schema: { ...def.pin } } : {}),
         endpoints: endpointsOf(kind, type, cfg),
+        protocols: protocolsOf(kind, type, cfg),
         pipelines: inPipelines,
       });
     }

package/src/typecheck.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Type-level guarantees of the otel lexicon's hand-written types: what
+ * TypeScript rejects before a build runs. Each `@ts-expect-error` line is a
+ * mistake the types must keep catching; tsc fails on the directive if the
+ * line ever compiles (`tsconfig.typecheck.json`, scripts/typecheck.ts). The
+ * runtime assertions keep vitest's view of the file honest.
+ */
+import { describe, expect, expectTypeOf, test } from "vitest";
+import {
+  BatchProcessor,
+  DebugExporter,
+  HealthCheckExtension,
+  MemoryLimiterProcessor,
+  NodeAgent,
+  OtlpExporter,
+  OtlpReceiver,
+  Pipeline,
+  Service,
+  SpanMetricsConnector,
+  TailSamplingProcessor,
+  defineComponent,
+  type PipelineEntity,
+  type TailSamplingPolicy,
+} from "./index";
+import { generate } from "./codegen/generate";
+
+const otlp = new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:4317" } } });
+const batch = new BatchProcessor({});
+const debug = new DebugExporter({ verbosity: "basic" });
+const health = new HealthCheckExtension({});
+const spanmetrics = new SpanMetricsConnector({});
+
+describe("pipelines take components of the right kind", () => {
+  test("receivers, processors and exporters in their own slots; a connector on either side", () => {
+    const traces = new Pipeline({ signal: "traces", receivers: [otlp], processors: [batch], exporters: [debug, spanmetrics] });
+    const metrics = new Pipeline({ signal: "metrics", receivers: [spanmetrics], exporters: [debug] });
+    expectTypeOf(traces).toEqualTypeOf<PipelineEntity>();
+    expect(traces.pipelineId).toBe("traces");
+    expect(metrics.pipelineId).toBe("metrics");
+  });
+
+  test("a component of the wrong kind is a type error", () => {
+    // @ts-expect-error a receiver is not an exporter
+    new Pipeline({ signal: "traces", receivers: [otlp], exporters: [otlp] });
+    // @ts-expect-error an exporter is not a processor
+    new Pipeline({ signal: "traces", receivers: [otlp], processors: [debug], exporters: [debug] });
+    // @ts-expect-error an extension is not a receiver
+    new Pipeline({ signal: "traces", receivers: [health], exporters: [debug] });
+    // @ts-expect-error a processor is not an extension
+    new Service({ extensions: [batch] });
+    expect(true).toBe(true);
+  });
+
+  test("the signal is one the collector knows", () => {
+    // @ts-expect-error "spans" is not a signal; "traces" is
+    new Pipeline({ signal: "spans", receivers: [otlp], exporters: [debug] });
+    expect(true).toBe(true);
+  });
+});
+
+describe("component configs are typed", () => {
+  test("a wrongly typed setting is a type error", () => {
+    // @ts-expect-error limit_mib is a number
+    new MemoryLimiterProcessor({ check_interval: "1s", limit_mib: "400" });
+    // @ts-expect-error verbosity is basic, normal or detailed
+    new DebugExporter({ verbosity: "verbose" });
+    // @ts-expect-error tls is an object, not a flag
+    new OtlpExporter({ endpoint: "tempo:4317", tls: true });
+    expect(true).toBe(true);
+  });
+
+  test("tail sampling policies are discriminated by type", () => {
+    const errors: TailSamplingPolicy = { name: "errors", type: "status_code", status_code: { status_codes: ["ERROR"] } };
+    // @ts-expect-error a latency policy carries its settings under `latency`
+    const wrong: TailSamplingPolicy = { name: "slow", type: "latency", probabilistic: { sampling_percentage: 10 } };
+    // @ts-expect-error decision_wait is required
+    new TailSamplingProcessor({ policies: [errors] });
+    expect(wrong.name).toBe("slow");
+  });
+
+  test("a custom component's config type follows its definition", () => {
+    const Vendor = defineComponent<{ token: string }>()({
+      kind: "exporter",
+      type: "vendor",
+      pin: { source: "github.com/example/vendorexporter", version: "v1.0.0" },
+    });
+    new Vendor({ token: "${env:VENDOR_TOKEN}" });
+    // @ts-expect-error token is a string
+    new Vendor({ token: 42 });
+    expect(Vendor.definition.type).toBe("vendor");
+  });
+});
+
+describe("NodeAgent props", () => {
+  test("exporters are required and must be exporters", () => {
+    const agent = NodeAgent({ exporters: [debug] });
+    expectTypeOf(agent.traces).toEqualTypeOf<PipelineEntity>();
+    // @ts-expect-error exporters is required
+    expect(() => NodeAgent({})).toThrow(/exporters/);
+    // @ts-expect-error a receiver is not an exporter
+    NodeAgent({ exporters: [otlp] });
+    // @ts-expect-error hostMetrics is a switch or its settings
+    NodeAgent({ exporters: [debug], hostMetrics: "on" });
+  });
+});
+
+describe("the packaged types entry", () => {
+  test("re-exports the package's own declarations", async () => {
+    const result = await generate();
+    expect(result.typesDTS).toContain('export * from "../index"');
+  });
+});