@intentius/chant-lexicon-otel 0.100.0 → 0.102.0

package/src/composites/composites.test.ts

@@ -0,0 +1,138 @@
+/**
+ * The `NodeAgent` composite: validation, defaults, the switches, and that the
+ * config it declares passes the lexicon's own config checks.
+ */
+import { describe, expect, test } from "vitest";
+import { load } from "js-yaml";
+import type { Declarable } from "@intentius/chant/declarable";
+import { NodeAgent, nodeAgentPropsProblem, type NodeAgentProps } from "./index";
+import { OtlpExporter, PrometheusExporter } from "../components/exporters";
+import { collectorYaml } from "../collector";
+import { validateCollectorConfig } from "../validate-config";
+import type { CollectorConfig } from "../model";
+
+const gateway = new OtlpExporter({ name: "gateway", endpoint: "otel-gateway.observability.svc:4317", tls: { insecure: true } });
+const base: NodeAgentProps = { exporters: [gateway] };
+
+/** A section of the built config, read loosely: the assertions name the keys they expect. */
+type Loose = Record<string, any>; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+function configOf(props: NodeAgentProps): CollectorConfig {
+  const agent = NodeAgent(props);
+  return load(collectorYaml(Object.values(agent.members) as Declarable[])) as CollectorConfig;
+}
+
+describe("NodeAgent validation", () => {
+  test("needs at least one exporter", () => {
+    expect(() => NodeAgent({ exporters: [] })).toThrow(/NodeAgent: exporters must name at least one exporter/);
+    expect(nodeAgentPropsProblem({ ...base, metricExporters: [] })).toMatch(/metricExporters/);
+  });
+
+  test("rejects a memory limit that is not a positive whole number, and a node env var that is not a name", () => {
+    expect(() => NodeAgent({ ...base, memoryLimitMib: 0 })).toThrow(/memoryLimitMib/);
+    expect(() => NodeAgent({ ...base, memoryLimitMib: 1.5 })).toThrow(/memoryLimitMib/);
+    expect(() => NodeAgent({ ...base, nodeNameEnv: "NODE-NAME" })).toThrow(/not an environment variable name/);
+    expect(nodeAgentPropsProblem(base)).toBeUndefined();
+  });
+});
+
+describe("NodeAgent defaults", () => {
+  const config = configOf(base);
+
+  test("the config passes every config check", () => {
+    expect(validateCollectorConfig(config)).toEqual([]);
+  });
+
+  test("OTLP, host metrics and container logs in; memory_limiter first and batch last", () => {
+    expect(Object.keys(config.receivers ?? {}).sort()).toEqual(["filelog", "hostmetrics", "otlp"]);
+    const pipelines = config.service?.pipelines ?? {};
+    expect(Object.keys(pipelines).sort()).toEqual(["logs", "metrics", "traces"]);
+    for (const p of Object.values(pipelines)) {
+      expect(p.processors).toEqual(["memory_limiter", "k8sattributes", "resourcedetection", "batch"]);
+      expect(p.exporters).toEqual(["otlp/gateway"]);
+    }
+    expect(pipelines.metrics.receivers).toEqual(["otlp", "hostmetrics"]);
+    expect(pipelines.logs.receivers).toEqual(["filelog", "otlp"]);
+    expect(pipelines.traces.receivers).toEqual(["otlp"]);
+  });
+
+  test("k8sattributes keeps to this node's pods and matches log records by pod uid", () => {
+    const k8s = config.processors?.k8sattributes as Loose;
+    expect(k8s.filter).toEqual({ node_from_env_var: "K8S_NODE_NAME" });
+    expect(k8s.extract.metadata).toContain("k8s.pod.uid");
+    expect(k8s.pod_association.map((a: Loose) => a.sources[0].name ?? a.sources[0].from)).toEqual(["k8s.pod.ip", "k8s.pod.uid", "connection"]);
+  });
+
+  test("the agent's own container logs are left out", () => {
+    const filelog = config.receivers?.filelog as Loose;
+    expect(filelog.include).toEqual(["/var/log/pods/*/*/*.log"]);
+    expect(filelog.exclude).toEqual(["/var/log/pods/*/otel-collector/*.log"]);
+    expect(filelog.operators).toEqual([{ type: "container", id: "container-parser" }]);
+  });
+
+  test("memory_limiter defaults to 400 MiB with a quarter of it as spike limit, and health_check is served", () => {
+    expect(config.processors?.memory_limiter).toMatchObject({ limit_mib: 400, spike_limit_mib: 100 });
+    expect(config.service?.extensions).toEqual(["health_check"]);
+    expect(config.extensions?.health_check).toEqual({ endpoint: "0.0.0.0:13133" });
+  });
+
+  test("no tail sampling and no kubeletstats", () => {
+    expect(config.processors?.tail_sampling).toBeUndefined();
+    expect(config.receivers?.kubeletstats).toBeUndefined();
+  });
+});
+
+describe("NodeAgent options", () => {
+  test("clusterName adds a resource processor before batch", () => {
+    const config = configOf({ ...base, clusterName: "prod-eu-1" });
+    expect(config.service?.pipelines?.traces.processors).toEqual(["memory_limiter", "k8sattributes", "resourcedetection", "resource", "batch"]);
+    expect(config.processors?.resource).toEqual({ attributes: [{ key: "k8s.cluster.name", value: "prod-eu-1", action: "upsert" }] });
+    expect(validateCollectorConfig(config)).toEqual([]);
+  });
+
+  test("metricExporters sends metrics elsewhere", () => {
+    const scrape = new PrometheusExporter({ endpoint: "0.0.0.0:8889" });
+    const config = configOf({ ...base, metricExporters: [scrape] });
+    expect(config.service?.pipelines?.metrics.exporters).toEqual(["prometheus"]);
+    expect(config.service?.pipelines?.traces.exporters).toEqual(["otlp/gateway"]);
+    expect(validateCollectorConfig(config)).toEqual([]);
+  });
+
+  test("kubeletStats reads this node's kubelet with the service account, named by the node env var", () => {
+    const config = configOf({ ...base, kubeletStats: { interval: "1m" }, nodeNameEnv: "NODE_NAME" });
+    expect(config.receivers?.kubeletstats).toEqual({
+      collection_interval: "1m",
+      auth_type: "serviceAccount",
+      endpoint: "https://${env:NODE_NAME}:10250",
+      insecure_skip_verify: true,
+      node: "${env:NODE_NAME}",
+    });
+    expect(config.service?.pipelines?.metrics.receivers).toEqual(["otlp", "hostmetrics", "kubeletstats"]);
+    expect((config.processors?.k8sattributes as Loose).filter).toEqual({ node_from_env_var: "NODE_NAME" });
+    expect(validateCollectorConfig(config)).toEqual([]);
+  });
+
+  test("host metrics, container logs and health_check can be turned off; OTLP stays", () => {
+    const agent = NodeAgent({ ...base, hostMetrics: false, containerLogs: false, healthCheck: false });
+    expect(Object.keys(agent.members).sort()).toEqual([
+      "batch",
+      "k8sAttributes",
+      "logs",
+      "memoryLimiter",
+      "metrics",
+      "otlp",
+      "resourceDetection",
+      "traces",
+    ]);
+    const config = configOf({ ...base, hostMetrics: false, containerLogs: false, healthCheck: false });
+    expect(Object.keys(config.receivers ?? {})).toEqual(["otlp"]);
+    expect(config.service?.extensions).toBeUndefined();
+    expect(validateCollectorConfig(config)).toEqual([]);
+  });
+
+  test("host metrics and container logs take their own settings", () => {
+    const config = configOf({ ...base, hostMetrics: { interval: "1m", rootPath: "/host" }, containerLogs: { selfContainer: "agent" } });
+    expect(config.receivers?.hostmetrics).toMatchObject({ collection_interval: "1m", root_path: "/host" });
+    expect((config.receivers?.filelog as Loose).exclude).toEqual(["/var/log/pods/*/agent/*.log"]);
+  });
+});

package/src/composites/index.ts

@@ -0,0 +1,6 @@
+/**
+ * otel lexicon composites: declarations that expand to a collector config's components and pipelines.
+ */
+
+export { NodeAgent, nodeAgentPropsProblem } from "./node-agent";
+export type { NodeAgentProps, NodeAgentMembers, NodeAgentInstance } from "./node-agent";

package/src/composites/node-agent.ts

@@ -0,0 +1,220 @@
+/**
+ * `NodeAgent`: the collector config a per-node agent runs on Kubernetes.
+ *
+ * One collector per node (a DaemonSet) takes OTLP from the pods on its node,
+ * reads the node's own telemetry, puts Kubernetes metadata on all of it, and
+ * hands it on, usually to a gateway tier. This composite declares that
+ * config:
+ *
+ * - receivers: `otlp` (gRPC on 4317, HTTP on 4318), and by default
+ *   `hostmetrics` (CPU, memory, load, filesystem, network of the node, read
+ *   under `/hostfs`) and `filelog` (container logs under `/var/log/pods`,
+ *   parsed by the `container` operator). `kubeletstats` (pod and container
+ *   resource metrics from the local kubelet) is opt-in.
+ * - processors, in order: `memory_limiter`; `k8sattributes`, filtered to
+ *   pods on this node and matching by pod IP, pod UID or the connection;
+ *   `resourcedetection` (`env`, `system`); a `resource` processor setting
+ *   `k8s.cluster.name` when `clusterName` is given; `batch`.
+ * - a `traces`, a `metrics` and a `logs` pipeline, each through those
+ *   processors to the given exporters.
+ * - a `health_check` extension on 0.0.0.0:13133.
+ *
+ * Tail sampling is left out on purpose: an agent sees only its node's
+ * spans of a trace, so a sampling decision there is made on partial traces.
+ * Sample on the gateway.
+ *
+ * What the pod has to provide: the node name in an environment variable
+ * (`K8S_NODE_NAME` by default, from `spec.nodeName`), the host root mounted
+ * read-only at `/hostfs` for `hostmetrics`, `/var/log/pods` mounted
+ * read-only for `filelog`, and a service account that may get, list and
+ * watch pods, namespaces and nodes (and replicasets, for
+ * `k8s.deployment.name`). The k8s lexicon's `OtelCollector` takes this
+ * composite's entities as its `config` and derives all of that from them:
+ * the variable, the read-only host mounts, group 0 for the root-owned log
+ * files, the RBAC and the ports.
+ */
+
+import { Composite, type CompositeInstance } from "@intentius/chant/composite";
+import type { Duration } from "../components/common";
+import { OtlpReceiver, HostMetricsReceiver, FileLogReceiver, type HostMetricsReceiverConfig } from "../components/receivers";
+import { KubeletStatsReceiver } from "../components/k8s-receivers";
+import {
+  BatchProcessor,
+  K8sAttributesProcessor,
+  MemoryLimiterProcessor,
+  ResourceDetectionProcessor,
+  ResourceProcessor,
+  type K8sAttributesProcessorConfig,
+} from "../components/processors";
+import { HealthCheckExtension } from "../components/extensions";
+import type { OTelComponent } from "../define";
+import { Pipeline, type PipelineEntity } from "../pipeline";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Exporter = OTelComponent<"exporter", string, any>;
+type Component<K extends "receiver" | "processor" | "extension"> = OTelComponent<K, string, object>;
+
+export interface NodeAgentProps {
+  /**
+   * Where traces and logs go: usually the gateway (the k8s lexicon's
+   * `gatewayExporter()`), or an OTLP backend. Also where metrics go, unless
+   * `metricExporters` is set.
+   */
+  exporters: Exporter[];
+  /** Where metrics go, e.g. a `prometheus` exporter for a scrape on each node. Default: `exporters`. */
+  metricExporters?: Exporter[];
+  /** Sets `k8s.cluster.name` on everything the agent sends. */
+  clusterName?: string;
+  /** The environment variable holding this node's name, set from `spec.nodeName` (default `K8S_NODE_NAME`). */
+  nodeNameEnv?: string;
+  /** Node CPU, memory, load, filesystem and network from the host root at `/hostfs` (default: on, every 30s). */
+  hostMetrics?: boolean | { interval?: Duration; rootPath?: string };
+  /**
+   * Container logs from `/var/log/pods` (default: on). The agent's own
+   * container is left out so the agent doesn't read its own log lines; name
+   * it with `selfContainer` (default `otel-collector`, the k8s
+   * `OtelCollector`'s default).
+   */
+  containerLogs?: boolean | { selfContainer?: string };
+  /** Pod and container resource metrics from this node's kubelet (default: off). The service account then needs get on `nodes/stats`. */
+  kubeletStats?: boolean | { interval?: Duration };
+  /** `memory_limiter`'s hard limit in MiB (default 400; the spike limit is a quarter of it). */
+  memoryLimitMib?: number;
+  /** Serve `health_check` on 0.0.0.0:13133 (default: on). */
+  healthCheck?: boolean;
+}
+
+// A type alias, not an interface: a composite's members type needs the implicit index signature.
+export type NodeAgentMembers = {
+  otlp: Component<"receiver">;
+  hostMetrics?: Component<"receiver">;
+  containerLogs?: Component<"receiver">;
+  kubeletStats?: Component<"receiver">;
+  memoryLimiter: Component<"processor">;
+  k8sAttributes: Component<"processor">;
+  resourceDetection: Component<"processor">;
+  cluster?: Component<"processor">;
+  batch: Component<"processor">;
+  health?: Component<"extension">;
+  traces: PipelineEntity;
+  metrics: PipelineEntity;
+  logs: PipelineEntity;
+};
+
+export type NodeAgentInstance = CompositeInstance<NodeAgentMembers> & NodeAgentMembers;
+
+const HOST_SCRAPERS: HostMetricsReceiverConfig["scrapers"] = { cpu: {}, memory: {}, load: {}, filesystem: {}, network: {} };
+
+/** Pod metadata for every signal. `k8s.pod.uid` is what the `container` log parser sets on log records. */
+const POD_METADATA: K8sAttributesProcessorConfig["extract"] = {
+  metadata: ["k8s.namespace.name", "k8s.pod.name", "k8s.pod.uid", "k8s.deployment.name", "k8s.node.name"],
+};
+const POD_ASSOCIATION: K8sAttributesProcessorConfig["pod_association"] = [
+  { sources: [{ from: "resource_attribute", name: "k8s.pod.ip" }] },
+  { sources: [{ from: "resource_attribute", name: "k8s.pod.uid" }] },
+  { sources: [{ from: "connection" }] },
+];
+
+function option<T extends object>(value: boolean | T | undefined, onByDefault: boolean): T | undefined {
+  if (value === undefined) return onByDefault ? ({} as T) : undefined;
+  if (value === false) return undefined;
+  return value === true ? ({} as T) : value;
+}
+
+/** Why a set of `NodeAgent` props can't build, or undefined when they can. */
+export function nodeAgentPropsProblem(props: NodeAgentProps): string | undefined {
+  if (!Array.isArray(props.exporters) || props.exporters.length === 0) return "exporters must name at least one exporter";
+  if (props.metricExporters !== undefined && props.metricExporters.length === 0) return "metricExporters must name at least one exporter when set";
+  if (props.memoryLimitMib !== undefined && !(Number.isInteger(props.memoryLimitMib) && props.memoryLimitMib > 0)) {
+    return "memoryLimitMib must be a positive whole number";
+  }
+  if (props.nodeNameEnv !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(props.nodeNameEnv)) {
+    return `nodeNameEnv "${props.nodeNameEnv}" is not an environment variable name`;
+  }
+  return undefined;
+}
+
+/**
+ * The collector config of a per-node Kubernetes agent: OTLP from the node's
+ * pods, host metrics and container logs from the node itself, Kubernetes
+ * metadata on everything, sent on to the given exporters.
+ *
+ * @example
+ * ```ts
+ * import { NodeAgent, OtlpExporter } from "@intentius/chant-lexicon-otel";
+ *
+ * const gateway = new OtlpExporter({ name: "gateway", endpoint: "otel-gateway.observability.svc:4317", tls: { insecure: true } });
+ * export const agent = NodeAgent({ exporters: [gateway], clusterName: "prod-eu-1" });
+ * ```
+ */
+export const NodeAgent = Composite<NodeAgentProps, NodeAgentMembers>((props) => {
+  const problem = nodeAgentPropsProblem(props);
+  if (problem) throw new Error(`NodeAgent: ${problem}`);
+
+  const nodeNameEnv = props.nodeNameEnv ?? "K8S_NODE_NAME";
+  const limit = props.memoryLimitMib ?? 400;
+  const host = option(props.hostMetrics, true);
+  const logFiles = option(props.containerLogs, true);
+  const kubelet = option(props.kubeletStats, false);
+
+  const otlp = new OtlpReceiver({
+    protocols: { grpc: { endpoint: "0.0.0.0:4317" }, http: { endpoint: "0.0.0.0:4318" } },
+  });
+  const hostMetrics = host
+    ? new HostMetricsReceiver({ collection_interval: host.interval ?? "30s", root_path: host.rootPath ?? "/hostfs", scrapers: HOST_SCRAPERS })
+    : undefined;
+  const containerLogs = logFiles
+    ? new FileLogReceiver({
+        include: ["/var/log/pods/*/*/*.log"],
+        exclude: [`/var/log/pods/*/${logFiles.selfContainer ?? "otel-collector"}/*.log`],
+        start_at: "end",
+        include_file_path: true,
+        operators: [{ type: "container", id: "container-parser" }],
+      })
+    : undefined;
+  const kubeletStats = kubelet
+    ? new KubeletStatsReceiver({
+        collection_interval: kubelet.interval ?? "30s",
+        auth_type: "serviceAccount",
+        endpoint: `https://\${env:${nodeNameEnv}}:10250`,
+        insecure_skip_verify: true,
+        node: `\${env:${nodeNameEnv}}`,
+      })
+    : undefined;
+
+  const memoryLimiter = new MemoryLimiterProcessor({ check_interval: "1s", limit_mib: limit, spike_limit_mib: Math.ceil(limit / 4) });
+  const k8sAttributes = new K8sAttributesProcessor({
+    auth_type: "serviceAccount",
+    filter: { node_from_env_var: nodeNameEnv },
+    extract: POD_METADATA,
+    pod_association: POD_ASSOCIATION,
+  });
+  const resourceDetection = new ResourceDetectionProcessor({ detectors: ["env", "system"], timeout: "5s", override: false });
+  const cluster = props.clusterName
+    ? new ResourceProcessor({ attributes: [{ key: "k8s.cluster.name", value: props.clusterName, action: "upsert" }] })
+    : undefined;
+  const batch = new BatchProcessor({ timeout: "10s" });
+  const processors = [memoryLimiter, k8sAttributes, resourceDetection, ...(cluster ? [cluster] : []), batch];
+
+  const exporters = props.exporters;
+  const metricExporters = props.metricExporters ?? exporters;
+  const traces = new Pipeline({ signal: "traces", receivers: [otlp], processors, exporters });
+  const metrics = new Pipeline({
+    signal: "metrics",
+    receivers: [otlp, ...(hostMetrics ? [hostMetrics] : []), ...(kubeletStats ? [kubeletStats] : [])],
+    processors,
+    exporters: metricExporters,
+  });
+  const logs = new Pipeline({ signal: "logs", receivers: [...(containerLogs ? [containerLogs] : []), otlp], processors, exporters });
+
+  const health = props.healthCheck === false ? undefined : new HealthCheckExtension({ endpoint: "0.0.0.0:13133" });
+
+  // A composite member must be a declarable, so the components that are off are left out rather than undefined.
+  const members: NodeAgentMembers = { otlp, memoryLimiter, k8sAttributes, resourceDetection, batch, traces, metrics, logs };
+  if (hostMetrics) members.hostMetrics = hostMetrics;
+  if (containerLogs) members.containerLogs = containerLogs;
+  if (kubeletStats) members.kubeletStats = kubeletStats;
+  if (cluster) members.cluster = cluster;
+  if (health) members.health = health;
+  return members;
+}, "NodeAgent");

package/src/configmap.ts

@@ -0,0 +1,67 @@
+/**
+ * Collector configs held in Kubernetes ConfigMaps (chant #2930).
+ *
+ * `OtelCollector`, `OtelCollectorGateway`, `GkeOtelCollector` and most
+ * hand-written manifests carry the collector config as a YAML string under a
+ * ConfigMap data key, usually `config.yaml`. The otel config checks
+ * (OTEL101-OTEL106, OTEL112) and the k8s placement checks (WK8601-WK8603)
+ * both read configs from there, through these two functions.
+ *
+ * Values are parsed with js-yaml rather than core's YAML reader, which keeps
+ * flow lists (`[otlp, batch]`) as strings (chant #2925, #3006).
+ */
+
+import { load } from "js-yaml";
+import type { CollectorConfig } from "./model";
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Parse a ConfigMap value as a collector config: YAML with a
+ * `service.pipelines` map. Undefined for anything else.
+ */
+export function parseCollectorConfig(text: unknown): CollectorConfig | undefined {
+  if (typeof text !== "string") return undefined;
+  let value: unknown;
+  try {
+    value = load(text);
+  } catch {
+    return undefined;
+  }
+  if (!isRecord(value) || !isRecord(value.service) || !isRecord(value.service.pipelines)) return undefined;
+  return value as unknown as CollectorConfig;
+}
+
+/** One collector config found in a ConfigMap. */
+export interface ConfigMapCollectorConfig {
+  /** `metadata.namespace`, or `default` when unset. */
+  namespace: string;
+  name: string;
+  /** The data key that holds the config, e.g. `config.yaml`. */
+  key: string;
+  config: CollectorConfig;
+}
+
+/**
+ * The collector configs in one parsed manifest: every `data` value of a
+ * ConfigMap that parses as a collector config. Empty for any other document.
+ */
+export function configMapCollectorConfigs(doc: unknown): ConfigMapCollectorConfig[] {
+  if (!isRecord(doc) || doc.kind !== "ConfigMap" || !isRecord(doc.data)) return [];
+  const metadata = isRecord(doc.metadata) ? doc.metadata : {};
+  if (typeof metadata.name !== "string") return [];
+  const namespace = typeof metadata.namespace === "string" && metadata.namespace.length > 0 ? metadata.namespace : "default";
+  const out: ConfigMapCollectorConfig[] = [];
+  for (const [key, text] of Object.entries(doc.data)) {
+    const config = parseCollectorConfig(text);
+    if (config) out.push({ namespace, name: metadata.name, key, config });
+  }
+  return out;
+}
+
+/** How a ConfigMap config is named in a message: `ConfigMap observability/otel-agent-config, key config.yaml`. */
+export function describeConfigMapConfig(c: Pick<ConfigMapCollectorConfig, "namespace" | "name" | "key">): string {
+  return `ConfigMap ${c.namespace}/${c.name}, key ${c.key}`;
+}

package/src/connectors.test.ts

@@ -15,8 +15,11 @@ import {
   PrometheusExporter,
   RoutingConnector,
   ServiceGraphConnector,
+  SignalToMetricsConnector,
   SpanMetricsConnector,
   SumConnector,
+  signalToMetricsEntries,
+  type SignalToMetricsConnectorConfig,
 } from "./components";
 import { collectorYaml } from "./collector";
 import { COLLECTOR_PIN, componentEntityType, defineComponent } from "./define";
@@ -62,7 +65,15 @@ describe("connector as a component kind", () => {
   });
 
   test("the built-ins are connectors pinned to the collector release", () => {
-    for (const Cls of [SpanMetricsConnector, ServiceGraphConnector, RoutingConnector, ForwardConnector, CountConnector, SumConnector]) {
+    for (const Cls of [
+      SpanMetricsConnector,
+      ServiceGraphConnector,
+      RoutingConnector,
+      ForwardConnector,
+      CountConnector,
+      SumConnector,
+      SignalToMetricsConnector,
+    ]) {
       expect(Cls.definition.kind).toBe("connector");
       expect(Cls.definition.builtin).toBe(true);
       expect(Cls.definition.pin).toEqual(COLLECTOR_PIN);
@@ -332,6 +343,180 @@ describe("connector config rules (OTEL107)", () => {
   });
 });
 
+/** Spans into a duration histogram and logs into a count, both feeding one metrics pipeline through signaltometrics. */
+function signalToMetricsCollector(): Declarable[] {
+  const otlp = new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:4317" } } });
+  const s2m = new SignalToMetricsConnector({
+    name: "genai",
+    spans: [
+      {
+        name: "gen_ai.client.operation.duration",
+        description: "GenAI operation duration",
+        unit: "s",
+        conditions: ['attributes["gen_ai.operation.name"] != nil'],
+        attributes: [{ key: "gen_ai.operation.name" }, { key: "gen_ai.request.model", default_value: "unknown" }, { key: "error.type", optional: true }],
+        histogram: { buckets: [0.01, 0.1, 1, 10], value: "Double(Microseconds(end_time - start_time)) / 1000000.0" },
+      },
+    ],
+    logs: [{ name: "logrecord.count", sum: { value: "1" } }],
+  });
+  const debug = new DebugExporter({ verbosity: "basic" });
+  const prom = new PrometheusExporter({ endpoint: "0.0.0.0:8889" });
+  return [
+    otlp,
+    s2m,
+    debug,
+    prom,
+    new Pipeline({ signal: "traces", receivers: [otlp], exporters: [debug, s2m] }),
+    new Pipeline({ signal: "logs", receivers: [otlp], exporters: [s2m] }),
+    new Pipeline({ signal: "metrics", name: "genai", receivers: [s2m], exporters: [prom] }),
+  ];
+}
+
+describe("signaltometrics", () => {
+  const problems = (config: SignalToMetricsConnectorConfig) =>
+    validateCollectorEntities([new SignalToMetricsConnector(config)]).map((i) => i.message);
+
+  test("is typed against the pinned release and reads every signal into metrics", () => {
+    expect(SignalToMetricsConnector.definition.type).toBe("signaltometrics");
+    expect(SignalToMetricsConnector.definition.pin).toBe(COLLECTOR_PIN);
+    expect(SignalToMetricsConnector.definition.connects).toEqual([
+      { from: "traces", to: "metrics" },
+      { from: "metrics", to: "metrics" },
+      { from: "logs", to: "metrics" },
+      { from: "profiles", to: "metrics" },
+    ]);
+  });
+
+  test("serializes each signal's metric list, and the pipelines it joins pass every check", () => {
+    const entities = signalToMetricsCollector();
+    const config = load(collectorYaml(entities)) as CollectorConfig;
+    expect(config.connectors?.["signaltometrics/genai"]).toEqual({
+      spans: [
+        {
+          name: "gen_ai.client.operation.duration",
+          description: "GenAI operation duration",
+          unit: "s",
+          conditions: ['attributes["gen_ai.operation.name"] != nil'],
+          attributes: [
+            { key: "gen_ai.operation.name" },
+            { key: "gen_ai.request.model", default_value: "unknown" },
+            { key: "error.type", optional: true },
+          ],
+          histogram: { buckets: [0.01, 0.1, 1, 10], value: "Double(Microseconds(end_time - start_time)) / 1000000.0" },
+        },
+      ],
+      logs: [{ name: "logrecord.count", sum: { value: "1" } }],
+    });
+    expect(validateCollectorConfig(config)).toEqual([]);
+    expect(validateCollectorEntities(entities)).toEqual([]);
+    expect(collectorTopologyOf(entities).edges.map((e) => [e.from, e.to])).toEqual([
+      ["traces", "metrics/genai"],
+      ["logs", "metrics/genai"],
+    ]);
+  });
+
+  test("OTEL112: it cannot feed a traces pipeline", () => {
+    const yaml = `receivers:
+  otlp: {protocols: {grpc: {}}}
+exporters:
+  debug: {}
+connectors:
+  signaltometrics:
+    spans: [{name: n, sum: {value: "1"}}]
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      exporters: [signaltometrics]
+    traces/out:
+      receivers: [signaltometrics]
+      exporters: [debug]
+`;
+    expect(otel112.check(ctxFor(yaml)).map((d) => d.entity)).toEqual(["signaltometrics", "signaltometrics"]);
+  });
+
+  test("entries list each metric with the types it names", () => {
+    const entries = signalToMetricsEntries({
+      spans: [{ name: "a", sum: { value: "1" } }],
+      datapoints: [{ name: "b", gauge: { value: "value_double" } }],
+    });
+    expect(entries.map((e) => [e.signal, e.index, e.metric.name, e.types])).toEqual([
+      ["spans", 0, "a", ["sum"]],
+      ["datapoints", 0, "b", ["gauge"]],
+    ]);
+  });
+
+  test("OTEL107 passes valid entries of every metric type", () => {
+    expect(
+      problems({
+        spans: [
+          { name: "s.sum", sum: { value: "Int(AdjustedCount())" } },
+          { name: "s.hist", histogram: { value: "Milliseconds(end_time - start_time)", count: "1" } },
+          { name: "s.exp", exponential_histogram: { max_size: 160, value: "Microseconds(end_time - start_time)" } },
+        ],
+        logs: [{ name: "l.gauge", gauge: { value: 'ExtractGrokPatterns(body, "Memory usage %{NUMBER:memory_mb:int}MB")["memory_mb"]' } }],
+        profiles: [{ name: "p.count", sum: { value: "1" } }],
+      }),
+    ).toEqual([]);
+  });
+
+  test("OTEL107: each entry names exactly one metric type, with a value", () => {
+    const bad = {
+      spans: [
+        { name: "none" },
+        { name: "two", sum: { value: "1" }, histogram: { value: "1" } },
+        { name: "nohistvalue", histogram: { count: "1" } },
+        { name: "nosumvalue", sum: {} },
+      ],
+    } as unknown as SignalToMetricsConnectorConfig;
+    expect(problems(bad)).toEqual([
+      'connector "signaltometrics": spans[0] (none): name exactly one metric type (sum, gauge, histogram or exponential_histogram); found none',
+      'connector "signaltometrics": spans[1] (two): name exactly one metric type (sum, gauge, histogram or exponential_histogram); found sum and histogram',
+      'connector "signaltometrics": spans[2] (nohistvalue): histogram.value is missing',
+      'connector "signaltometrics": spans[3] (nosumvalue): sum.value is missing',
+    ]);
+  });
+
+  test("OTEL107: names, attributes, buckets, max_size and grok selectors", () => {
+    const bad = {
+      logs: [
+        { name: "", sum: { value: "1" } },
+        {
+          name: "attrs",
+          attributes: [{ key: "a", default_value: "x", optional: true }, { key: "b" }, { key: "b" }, { key: "" }],
+          histogram: { buckets: [1, 5, 5], value: "1" },
+        },
+        { name: "exp", exponential_histogram: { max_size: 1, value: "1" } },
+        { name: "grok", gauge: { value: 'ExtractGrokPatterns(body, "%{NUMBER:n:int}")' } },
+      ],
+    } as unknown as SignalToMetricsConnectorConfig;
+    expect(problems(bad)).toEqual([
+      'connector "signaltometrics": logs[0]: name is missing',
+      'connector "signaltometrics": logs[1] (attrs): histogram.buckets must increase',
+      'connector "signaltometrics": logs[1] (attrs): attributes "a": set default_value or optional, not both',
+      'connector "signaltometrics": logs[1] (attrs): attributes "b" is listed twice',
+      'connector "signaltometrics": logs[1] (attrs): attributes[3]: key is missing',
+      'connector "signaltometrics": logs[2] (exp): exponential_histogram.max_size must be between 2 and 16384',
+      'connector "signaltometrics": logs[3] (grok): gauge.value with ExtractGrokPatterns needs one key selector, ExtractGrokPatterns(...)["key"]',
+    ]);
+  });
+
+  test("OTEL107: a connector with no metrics", () => {
+    expect(problems({})).toEqual([
+      'connector "signaltometrics": no metric is configured under spans, datapoints, logs or profiles; the collector refuses the connector',
+    ]);
+  });
+
+  test("the type allows exactly one metric type per entry", () => {
+    // @ts-expect-error: two metric types
+    const two: SignalToMetricsConnectorConfig = { spans: [{ name: "x", sum: { value: "1" }, gauge: { value: "1" } }] };
+    // @ts-expect-error: no metric type
+    const none: SignalToMetricsConnectorConfig = { spans: [{ name: "x" }] };
+    expect([two, none]).toHaveLength(2);
+  });
+});
+
 // `otelcol validate` is the acceptance test for the emitted YAML. CI has no
 // collector binary, so this runs only when one is on PATH (the contrib build,
 // which ships the connectors) and is skipped, with the reason shown, when not.
@@ -365,6 +550,17 @@ describe.skipIf(!otelcol)(
       }
     });
 
+    test("the signaltometrics example validates", () => {
+      const dir = mkdtempSync(join(tmpdir(), "chant-otel-connectors-"));
+      try {
+        const file = join(dir, "config.yaml");
+        writeFileSync(file, collectorYaml(signalToMetricsCollector()));
+        expect(() => execFileSync(otelcol!, ["validate", `--config=${file}`], { stdio: "pipe" })).not.toThrow();
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    });
+
     test("a spanmetrics signal mismatch is refused by the collector too", () => {
       const dir = mkdtempSync(join(tmpdir(), "chant-otel-connectors-"));
       try {