@intentius/chant-lexicon-otel 0.100.0 → 0.102.0

package/src/components/connectors.ts

@@ -1,5 +1,6 @@
 /**
- * Built-in connectors: spanmetrics, servicegraph, routing, forward, count, sum.
+ * Built-in connectors: spanmetrics, servicegraph, routing, forward, count, sum,
+ * signaltometrics.
  *
  * 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
@@ -274,3 +275,210 @@ export const SumConnector = defineBuiltin<SumConnectorConfig, "connector", "sum"
     return problems;
   },
 });
+
+// ── signaltometrics ──────────────────────────────────────────────────
+//
+// Typed against connector/signaltometricsconnector at COLLECTOR_PIN
+// (collector-contrib v0.130.0): config/config.go and README.md at that tag,
+// https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.130.0/connector/signaltometricsconnector
+// The collector type is `signaltometrics`. Upstream marks every signal pair
+// alpha. At v0.130.0 there is no span event section; spans, data points,
+// logs and profiles each take a list of metrics.
+
+/** The input sections of a `signaltometrics` connector, one per signal it reads. */
+export const SIGNAL_TO_METRICS_SIGNALS = ["spans", "datapoints", "logs", "profiles"] as const;
+export type SignalToMetricsSignal = (typeof SIGNAL_TO_METRICS_SIGNALS)[number];
+
+/** The metric types a `signaltometrics` entry can produce. Each entry names exactly one. */
+export const SIGNAL_TO_METRICS_TYPES = ["sum", "gauge", "histogram", "exponential_histogram"] as const;
+export type SignalToMetricsType = (typeof SIGNAL_TO_METRICS_TYPES)[number];
+
+/**
+ * The connector's default explicit histogram bounds, used when `histogram`
+ * sets no `buckets`. They are plain numbers in whatever unit `value` returns,
+ * not durations.
+ */
+export const SIGNAL_TO_METRICS_DEFAULT_BUCKETS: readonly number[] = Object.freeze([
+  2, 4, 6, 8, 10, 50, 100, 200, 400, 800, 1000, 1400, 2000, 5000, 10_000, 15_000,
+]);
+
+/**
+ * An attribute of the produced metric.
+ *
+ * In `attributes`: without `default_value` or `optional`, an item lacking the
+ * attribute is not counted at all; with `default_value`, it is counted under
+ * that value; with `optional: true`, it is counted without the attribute.
+ * Set at most one of the two.
+ *
+ * In `include_resource_attributes`: an include list. `default_value` fills a
+ * missing resource attribute; `optional` changes nothing.
+ */
+export interface SignalToMetricsAttribute {
+  key: string;
+  default_value?: string | number | boolean;
+  optional?: boolean;
+}
+
+/** A delta sum of `value` over the items in each batch. */
+export interface SignalToMetricsSum {
+  /** OTTL value expression; its result type (int or double) is the sum's. A constant is a string: `"1"`. */
+  value: string;
+}
+
+/** The last `value` seen in each batch. */
+export interface SignalToMetricsGauge {
+  /** OTTL value expression. With `ExtractGrokPatterns`, select one key: `ExtractGrokPatterns(...)["key"]`. */
+  value: string;
+}
+
+/** An explicit-bucket histogram of `value`. */
+export interface SignalToMetricsHistogram {
+  /** Upper bounds, increasing, in the unit `value` returns. Default `SIGNAL_TO_METRICS_DEFAULT_BUCKETS`. */
+  buckets?: number[];
+  /** OTTL value expression for how many observations each item counts as. Default: one per item. */
+  count?: string;
+  /** OTTL value expression for the observed value, e.g. `Seconds(end_time - start_time)` or an attribute. */
+  value: string;
+}
+
+/** A base-2 exponential histogram of `value`. */
+export interface SignalToMetricsExponentialHistogram {
+  /** Buckets per positive or negative range, 2 to 16384. Default 160. */
+  max_size?: number;
+  /** OTTL value expression for how many observations each item counts as. Default: one per item. */
+  count?: string;
+  /** OTTL value expression for the observed value. */
+  value: string;
+}
+
+/** What every `signaltometrics` entry has, whatever metric type it produces. */
+export interface SignalToMetricsMetricBase {
+  /** The OTLP metric name, used as written. */
+  name: string;
+  description?: string;
+  /** The metric's unit, e.g. `s` or `{token}`. */
+  unit?: string;
+  /** Resource attributes the metric keeps. Unset or empty keeps them all. */
+  include_resource_attributes?: SignalToMetricsAttribute[];
+  /** Attributes of the item (span, data point, log record) the metric is split by. Unset: no attributes. */
+  attributes?: SignalToMetricsAttribute[];
+  /** OTTL conditions, ORed; an item counts when any matches. Unset counts every item. */
+  conditions?: string[];
+}
+
+type OneMetricType<K extends SignalToMetricsType, V> = { [P in K]: V } & { [P in Exclude<SignalToMetricsType, K>]?: never };
+
+/** One metric a `signaltometrics` connector produces: a name and exactly one metric type. */
+export type SignalToMetricsMetric = SignalToMetricsMetricBase &
+  (
+    | OneMetricType<"sum", SignalToMetricsSum>
+    | OneMetricType<"gauge", SignalToMetricsGauge>
+    | OneMetricType<"histogram", SignalToMetricsHistogram>
+    | OneMetricType<"exponential_histogram", SignalToMetricsExponentialHistogram>
+  );
+
+/**
+ * The metrics to produce, per input signal. The connector emits delta
+ * temporality and aggregates only within each batch it receives, so an
+ * exporter that needs cumulative input (Prometheus remote write) wants a
+ * `deltatocumulative` processor in front of it.
+ */
+export interface SignalToMetricsConnectorConfig {
+  spans?: SignalToMetricsMetric[];
+  datapoints?: SignalToMetricsMetric[];
+  logs?: SignalToMetricsMetric[];
+  profiles?: SignalToMetricsMetric[];
+}
+
+/** One entry of a `signaltometrics` config, with where it sits. */
+export interface SignalToMetricsEntry {
+  signal: SignalToMetricsSignal;
+  index: number;
+  metric: SignalToMetricsMetric;
+  /** The metric types the entry names. A valid entry names exactly one. */
+  types: SignalToMetricsType[];
+}
+
+/** Every metric entry of a `signaltometrics` config, in section order. Reads untyped config too. */
+export function signalToMetricsEntries(config: SignalToMetricsConnectorConfig): SignalToMetricsEntry[] {
+  const out: SignalToMetricsEntry[] = [];
+  for (const signal of SIGNAL_TO_METRICS_SIGNALS) {
+    const list = (config as Record<string, unknown>)?.[signal];
+    if (!Array.isArray(list)) continue;
+    list.forEach((metric, index) => {
+      const m = (metric ?? {}) as Record<string, unknown>;
+      const types = SIGNAL_TO_METRICS_TYPES.filter((t) => m[t] !== undefined && m[t] !== null);
+      out.push({ signal, index, metric: m as unknown as SignalToMetricsMetric, types });
+    });
+  }
+  return out;
+}
+
+const GROK_KEY_SELECTOR = /ExtractGrokPatterns\([^)]*\)\s*\[[^\]]+\]/;
+
+/** The checks config/config.go makes at v0.130.0 that need no OTTL parser, plus increasing buckets. */
+function validateSignalToMetrics(c: SignalToMetricsConnectorConfig): string[] {
+  const problems: string[] = [];
+  const entries = signalToMetricsEntries(c);
+  if (entries.length === 0) {
+    problems.push("no metric is configured under spans, datapoints, logs or profiles; the collector refuses the connector");
+  }
+  for (const { signal, index, metric, types } of entries) {
+    const m = metric as unknown as SignalToMetricsMetricBase & Partial<Record<SignalToMetricsType, Record<string, unknown>>>;
+    const at = m.name ? `${signal}[${index}] (${m.name})` : `${signal}[${index}]`;
+    if (!m.name) problems.push(`${at}: name is missing`);
+    if (types.length !== 1) {
+      problems.push(
+        `${at}: name exactly one metric type (sum, gauge, histogram or exponential_histogram); ${types.length === 0 ? "found none" : `found ${types.join(" and ")}`}`,
+      );
+    }
+    for (const t of types) {
+      const body = m[t];
+      if (typeof body?.value !== "string" || body.value === "") problems.push(`${at}: ${t}.value is missing`);
+    }
+    const buckets = m.histogram?.buckets;
+    if (Array.isArray(buckets) && buckets.some((b, i) => i > 0 && !((b as number) > (buckets[i - 1] as number)))) {
+      problems.push(`${at}: histogram.buckets must increase`);
+    }
+    const maxSize = m.exponential_histogram?.max_size;
+    if (typeof maxSize === "number" && maxSize !== 0 && (maxSize < 2 || maxSize > 16384)) {
+      problems.push(`${at}: exponential_histogram.max_size must be between 2 and 16384`);
+    }
+    const gauge = m.gauge?.value;
+    if (typeof gauge === "string" && gauge.includes("ExtractGrokPatterns") && !GROK_KEY_SELECTOR.test(gauge)) {
+      problems.push(`${at}: gauge.value with ExtractGrokPatterns needs one key selector, ExtractGrokPatterns(...)["key"]`);
+    }
+    const seen = new Set<string>();
+    (m.attributes ?? []).forEach((a, i) => {
+      if (!a?.key) {
+        problems.push(`${at}: attributes[${i}]: key is missing`);
+        return;
+      }
+      if (a.default_value !== undefined && a.optional) {
+        problems.push(`${at}: attributes "${a.key}": set default_value or optional, not both`);
+      }
+      if (seen.has(a.key)) problems.push(`${at}: attributes "${a.key}" is listed twice`);
+      seen.add(a.key);
+    });
+  }
+  return problems;
+}
+
+/**
+ * Builds metrics from spans, data points, logs or profiles, each with the
+ * name, type, unit, attributes and conditions you choose. A histogram, sum or
+ * gauge takes its value from an OTTL expression, such as an attribute or the
+ * span's duration.
+ */
+export const SignalToMetricsConnector = defineBuiltin<SignalToMetricsConnectorConfig, "connector", "signaltometrics">({
+  kind: "connector",
+  type: "signaltometrics",
+  description: "Builds named sum, gauge and histogram metrics from spans, data points, logs or profiles, with values and conditions in OTTL",
+  connects: [
+    { from: "traces", to: "metrics" },
+    { from: "metrics", to: "metrics" },
+    { from: "logs", to: "metrics" },
+    { from: "profiles", to: "metrics" },
+  ],
+  validate: validateSignalToMetrics,
+});

package/src/components/exporters.ts

@@ -16,6 +16,7 @@ export const OtlpExporter = defineBuiltin<OtlpExporterConfig, "exporter", "otlp"
   description: "Sends traces, metrics and logs over OTLP gRPC",
   validate: (c) => (c.endpoint ? [] : ["endpoint is empty"]),
   endpoints: (c) => (c.endpoint ? [c.endpoint] : []),
+  protocols: () => ["grpc"],
 });
 
 // ── otlphttp ─────────────────────────────────────────────────────────
@@ -39,6 +40,7 @@ export const OtlpHttpExporter = defineBuiltin<OtlpHttpExporterConfig, "exporter"
       : ["set endpoint, or at least one of traces_endpoint, metrics_endpoint and logs_endpoint"],
   endpoints: (c) =>
     [c.endpoint, c.traces_endpoint, c.metrics_endpoint, c.logs_endpoint].filter((e): e is string => typeof e === "string" && e !== ""),
+  protocols: (c) => [c.encoding === "json" ? "http/json" : "http/protobuf"],
 });
 
 // ── debug ────────────────────────────────────────────────────────────

package/src/components/extensions.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "vitest";
+import { load } from "js-yaml";
+import type { Declarable } from "@intentius/chant/declarable";
+import { collectorYaml } from "../collector";
+import { validateCollectorEntities } from "../validate-config";
+import { COLLECTOR_PIN } from "../define";
+import { Pipeline, Service } from "../pipeline";
+import { DebugExporter } from "./exporters";
+import { K8sClusterReceiver } from "./k8s-receivers";
+import { K8sLeaderElectorExtension, type K8sLeaderElectorExtensionConfig } from "./extensions";
+
+function problems(component: Declarable): string[] {
+  return validateCollectorEntities([component])
+    .filter((i) => i.code === "OTEL107")
+    .map((i) => i.message.replace(/^\w+ "[^"]+": /, ""));
+}
+
+const lease = { lease_name: "otel-k8s-cluster", lease_namespace: "observability" };
+
+describe("k8s_leader_elector extension", () => {
+  test("is a built-in pinned to the collector release", () => {
+    expect(K8sLeaderElectorExtension.definition.kind).toBe("extension");
+    expect(K8sLeaderElectorExtension.definition.type).toBe("k8s_leader_elector");
+    expect(K8sLeaderElectorExtension.definition.builtin).toBe(true);
+    expect(K8sLeaderElectorExtension.definition.pin).toBe(COLLECTOR_PIN);
+  });
+
+  test("a k8s_cluster receiver names it by componentId", () => {
+    const elector = new K8sLeaderElectorExtension({ name: "cluster", auth_type: "serviceAccount", ...lease, lease_duration: "20s" });
+    const cluster = new K8sClusterReceiver({ k8s_leader_elector: elector.componentId });
+    const debug = new DebugExporter({});
+    const yaml = collectorYaml([
+      cluster,
+      elector,
+      debug,
+      new Pipeline({ signal: "metrics", receivers: [cluster], exporters: [debug] }),
+      new Service({ extensions: [elector] }),
+    ]);
+    expect(load(yaml)).toMatchObject({
+      receivers: { k8s_cluster: { k8s_leader_elector: "k8s_leader_elector/cluster" } },
+      extensions: {
+        "k8s_leader_elector/cluster": { auth_type: "serviceAccount", lease_name: "otel-k8s-cluster", lease_namespace: "observability", lease_duration: "20s" },
+      },
+      service: { extensions: ["k8s_leader_elector/cluster"] },
+    });
+    expect(problems(elector)).toEqual([]);
+  });
+
+  test("needs lease_name and lease_namespace", () => {
+    expect(problems(new K8sLeaderElectorExtension({ lease_name: "", lease_namespace: "obs" }))).toEqual([
+      "lease_name and lease_namespace must be set",
+    ]);
+    expect(problems(new K8sLeaderElectorExtension({} as K8sLeaderElectorExtensionConfig))).toEqual([
+      "lease_name and lease_namespace must be set",
+    ]);
+  });
+
+  test("checks the durations the way client-go's leader elector does", () => {
+    expect(problems(new K8sLeaderElectorExtension({ ...lease, lease_duration: "10s" }))).toEqual([
+      "lease_duration must be greater than renew_deadline",
+    ]);
+    expect(problems(new K8sLeaderElectorExtension({ ...lease, renew_deadline: "2400ms" }))).toEqual([
+      "renew_deadline must be greater than 1.2 times retry_period",
+    ]);
+    expect(problems(new K8sLeaderElectorExtension({ ...lease, retry_period: "0s" }))).toEqual(["retry_period must be positive"]);
+    expect(problems(new K8sLeaderElectorExtension({ ...lease, lease_duration: "1m30s", renew_deadline: "1m", retry_period: "5s" }))).toEqual([]);
+    // A value this can't read (an env reference) is left to the collector.
+    expect(problems(new K8sLeaderElectorExtension({ ...lease, lease_duration: "${env:LEASE}" }))).toEqual([]);
+  });
+});

package/src/components/extensions.ts

@@ -1,9 +1,10 @@
 /**
- * Built-in extensions: health_check, pprof, zpages.
+ * Built-in extensions: health_check, pprof, zpages, k8s_leader_elector.
  */
 
 import { defineBuiltin } from "../define";
-import type { TLSServerSettings } from "./common";
+import { goDurationMs, type Duration, type TLSServerSettings } from "./common";
+import type { K8sAuthType } from "./k8s-receivers";
 
 export interface HealthCheckExtensionConfig {
   /** Default `localhost:13133`. */
@@ -49,3 +50,60 @@ export const ZPagesExtension = defineBuiltin<ZPagesExtensionConfig, "extension",
   description: "Serves zPages for live debugging of receivers and exporters",
   endpoints: (c) => [c.endpoint ?? "localhost:55679"],
 });
+
+// ── k8s_leader_elector ───────────────────────────────────────────────
+//
+// Typed against extension/k8sleaderelector at COLLECTOR_PIN
+// (collector-contrib v0.130.0): config.go, factory.go, leader_elector.go and README.md at that tag,
+// https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.130.0/extension/k8sleaderelector
+// The config squashes internal/k8sconfig's APIConfig (`auth_type`, `context`).
+// Upstream marks it alpha. It ships in the otelcol-contrib and otelcol-k8s
+// distributions at v0.130.0.
+
+export interface K8sLeaderElectorExtensionConfig {
+  /** How to reach the Kubernetes API. Default `serviceAccount`. */
+  auth_type?: K8sAuthType;
+  /** With `auth_type: kubeConfig`, the kubeconfig context to use instead of the current one. */
+  context?: string;
+  /** The Lease object the replicas compete for. Required. */
+  lease_name: string;
+  /** The namespace of the Lease. Required. */
+  lease_namespace: string;
+  /** How long a lease is held without renewal. Default `15s`. */
+  lease_duration?: Duration;
+  /** How long the leader keeps retrying a renewal before giving up the lease; less than `lease_duration`. Default `10s`. */
+  renew_deadline?: Duration;
+  /** How long to wait between attempts to acquire or renew. Default `2s`. */
+  retry_period?: Duration;
+}
+
+/**
+ * Elects one leader among collector replicas through a Kubernetes Lease, so a
+ * receiver that names it (`k8s_cluster`'s `k8s_leader_elector`) collects only
+ * in the replica holding the lease. The collector's ServiceAccount needs
+ * access to `leases` in `coordination.k8s.io` in `lease_namespace`.
+ */
+export const K8sLeaderElectorExtension = defineBuiltin<K8sLeaderElectorExtensionConfig, "extension", "k8s_leader_elector">({
+  kind: "extension",
+  type: "k8s_leader_elector",
+  description: "Elects one leader among collector replicas through a Kubernetes Lease",
+  validate: (c) => {
+    const problems: string[] = [];
+    // config.go Validate.
+    if (!c.lease_name || !c.lease_namespace) problems.push("lease_name and lease_namespace must be set");
+    // client-go's leaderelection.NewLeaderElector, which leader_elector.go calls when the extension starts.
+    const lease = goDurationMs(c.lease_duration, 15_000);
+    const renew = goDurationMs(c.renew_deadline, 10_000);
+    const retry = goDurationMs(c.retry_period, 2_000);
+    for (const [key, ms] of [["lease_duration", lease], ["renew_deadline", renew], ["retry_period", retry]] as const) {
+      if (ms !== undefined && ms <= 0) problems.push(`${key} must be positive`);
+    }
+    if (lease !== undefined && renew !== undefined && lease > 0 && renew > 0 && lease <= renew) {
+      problems.push("lease_duration must be greater than renew_deadline");
+    }
+    if (renew !== undefined && retry !== undefined && renew > 0 && retry > 0 && renew <= 1.2 * retry) {
+      problems.push("renew_deadline must be greater than 1.2 times retry_period");
+    }
+    return problems;
+  },
+});

package/src/components/processors.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "vitest";
+import { load } from "js-yaml";
+import type { Declarable } from "@intentius/chant/declarable";
+import { collectorYaml } from "../collector";
+import { validateCollectorEntities } from "../validate-config";
+import { COLLECTOR_PIN } from "../define";
+import { Pipeline } from "../pipeline";
+import { DebugExporter } from "./exporters";
+import { SumConnector } from "./connectors";
+import { OtlpReceiver } from "./receivers";
+import { DeltaToCumulativeProcessor, type DeltaToCumulativeProcessorConfig } from "./processors";
+
+function problems(component: Declarable): string[] {
+  return validateCollectorEntities([component])
+    .filter((i) => i.code === "OTEL107")
+    .map((i) => i.message.replace(/^\w+ "[^"]+": /, ""));
+}
+
+describe("deltatocumulative processor", () => {
+  test("is a built-in pinned to the collector release", () => {
+    expect(DeltaToCumulativeProcessor.definition.kind).toBe("processor");
+    expect(DeltaToCumulativeProcessor.definition.type).toBe("deltatocumulative");
+    expect(DeltaToCumulativeProcessor.definition.builtin).toBe(true);
+    expect(DeltaToCumulativeProcessor.definition.pin).toBe(COLLECTOR_PIN);
+  });
+
+  test("sits in a metrics pipeline after a delta-emitting connector", () => {
+    const otlp = new OtlpReceiver({ protocols: { grpc: {} } });
+    const sum = new SumConnector({ spans: { "tokens": { source_attribute: "gen_ai.usage.input_tokens" } } });
+    const d2c = new DeltaToCumulativeProcessor({ max_stale: "10m", max_streams: 1000 });
+    const debug = new DebugExporter({});
+    const config = load(
+      collectorYaml([
+        otlp,
+        new Pipeline({ signal: "traces", receivers: [otlp], exporters: [sum] }),
+        new Pipeline({ signal: "metrics", receivers: [sum], processors: [d2c], exporters: [debug] }),
+      ]),
+    ) as any;
+    expect(config.processors.deltatocumulative).toEqual({ max_stale: "10m", max_streams: 1000 });
+    expect(config.service.pipelines.metrics.processors).toEqual(["deltatocumulative"]);
+  });
+
+  test.each<[string, DeltaToCumulativeProcessorConfig, string[]]>([
+    ["defaults", {}, []],
+    ["set", { max_stale: "1h", max_streams: 0 }, []],
+    ["zero max_stale", { max_stale: "0s" }, ['max_stale must be a positive duration (got "0s")']],
+    ["bare zero max_stale", { max_stale: "0" }, ['max_stale must be a positive duration (got "0")']],
+    ["negative max_stale", { max_stale: "-5m" }, ['max_stale must be a positive duration (got "-5m")']],
+    ["negative max_streams", { max_streams: -1 }, ["max_streams must be a whole number, 0 or more (got -1)"]],
+    ["fractional max_streams", { max_streams: 1.5 }, ["max_streams must be a whole number, 0 or more (got 1.5)"]],
+  ])("checks what config.go Validate checks: %s", (_label, config, expected) => {
+    expect(problems(new DeltaToCumulativeProcessor(config))).toEqual(expected);
+  });
+});

package/src/components/processors.ts

@@ -1,10 +1,10 @@
 /**
  * Built-in processors: batch, memory_limiter, resource, attributes,
- * k8sattributes, resourcedetection.
+ * k8sattributes, resourcedetection, deltatocumulative.
  */
 
 import { defineBuiltin } from "../define";
-import type { AttributeAction, Duration } from "./common";
+import { goDurationMs, type AttributeAction, type Duration } from "./common";
 
 // ── batch ────────────────────────────────────────────────────────────
 
@@ -210,3 +210,42 @@ export const ResourceDetectionProcessor = defineBuiltin<
   description: "Detects cloud, container and host resource attributes",
   validate: (c) => (c.detectors?.length ? [] : ["detectors is empty, so nothing is detected"]),
 });
+
+// ── deltatocumulative ────────────────────────────────────────────────
+//
+// Typed against processor/deltatocumulativeprocessor at COLLECTOR_PIN
+// (collector-contrib v0.130.0): config.go, factory.go and README.md at that tag,
+// https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.130.0/processor/deltatocumulativeprocessor
+// Upstream marks it alpha for metrics. It ships in the otelcol-contrib and
+// otelcol-k8s distributions at v0.130.0, and keeps every stream's running
+// total in memory, so one collector instance must see all of a stream's
+// deltas for its totals to be right.
+
+export interface DeltaToCumulativeProcessorConfig {
+  /** How long a stream that receives no samples is kept before it is dropped. Positive. Default `5m`. */
+  max_stale?: Duration;
+  /** The most streams tracked at once; samples of new streams past it are dropped. Not negative. Default unlimited. */
+  max_streams?: number;
+}
+
+/**
+ * Turns delta metrics into cumulative ones by keeping a running total per
+ * stream. Exporters that read only cumulative data, such as
+ * `prometheusremotewrite`, need it after connectors that emit deltas (`sum`,
+ * `count`, `signaltometrics`). Cumulative metrics pass through unchanged.
+ */
+export const DeltaToCumulativeProcessor = defineBuiltin<DeltaToCumulativeProcessorConfig, "processor", "deltatocumulative">({
+  kind: "processor",
+  type: "deltatocumulative",
+  description: "Converts delta metrics to cumulative by keeping a running total per stream",
+  validate: (c) => {
+    // config.go Validate.
+    const problems: string[] = [];
+    const stale = goDurationMs(c.max_stale, 5 * 60_000);
+    if (stale !== undefined && stale <= 0) problems.push(`max_stale must be a positive duration (got ${JSON.stringify(c.max_stale)})`);
+    if (c.max_streams !== undefined && (!Number.isInteger(c.max_streams) || c.max_streams < 0)) {
+      problems.push(`max_streams must be a whole number, 0 or more (got ${c.max_streams})`);
+    }
+    return problems;
+  },
+});

package/src/components/receivers.ts

@@ -35,6 +35,11 @@ export const OtlpReceiver = defineBuiltin<OtlpReceiverConfig, "receiver", "otlp"
     if (c.protocols && "http" in c.protocols) out.push(c.protocols.http?.endpoint ?? "localhost:4318");
     return out;
   },
+  // The HTTP receiver takes protobuf and JSON bodies on the same port.
+  protocols: (c) => [
+    ...(c.protocols && "grpc" in c.protocols ? ["grpc"] : []),
+    ...(c.protocols && "http" in c.protocols ? ["http/protobuf", "http/json"] : []),
+  ],
 });
 
 // ── prometheus ───────────────────────────────────────────────────────

package/src/composites/catalog.test.ts

@@ -0,0 +1,38 @@
+/**
+ * The composite catalog matches what this lexicon exports (#2662).
+ *
+ * `catalog.ts` is generated by `npm run generate:composite-catalogs` and is
+ * what `chant serve mcp` lists.
+ */
+
+import { describe, expect, test } from "vitest";
+import { isCompositeDefinition } from "@intentius/chant";
+import * as composites from "./index";
+import { compositeCatalog } from "./catalog";
+import { otelPlugin } from "../plugin";
+
+const exported = Object.entries(composites)
+  .filter(([, value]) => isCompositeDefinition(value))
+  .map(([name]) => name)
+  .sort();
+const catalogued = compositeCatalog.map((entry) => entry.name).sort();
+
+describe("the otel composite catalog", () => {
+  test("every exported composite has an entry, and every entry names an exported composite", () => {
+    expect(exported).toEqual(["NodeAgent"]);
+    expect(catalogued, "regenerate with `npm run generate:composite-catalogs -- otel`").toEqual(exported);
+  });
+
+  test("every entry says what it is and names the components it bundles", () => {
+    for (const entry of compositeCatalog) {
+      expect(entry.lexicon, entry.name).toBe("otel");
+      expect(entry.description.length, entry.name).toBeGreaterThan(0);
+      expect(entry.bundles, entry.name).toContain("Pipeline");
+      expect(entry.bundles, entry.name).toContain("OtlpReceiver");
+    }
+  });
+
+  test("the plugin contributes it", () => {
+    expect(otelPlugin.composites?.()).toBe(compositeCatalog);
+  });
+});

package/src/composites/catalog.ts

@@ -0,0 +1,81 @@
+// Generated by scripts/generate-composite-catalogs.ts (#2662) from this
+// lexicon's composite exports. Do not edit by hand: run
+// `npm run generate:composite-catalogs`. catalog.test.ts holds it to the exports.
+import type { CompositeEntry } from "@intentius/chant/lexicon";
+
+export const compositeCatalog: CompositeEntry[] = [
+  {
+    "name": "NodeAgent",
+    "lexicon": "otel",
+    "description": "The collector config of a per-node Kubernetes agent.",
+    "bundles": [
+      "BatchProcessor",
+      "FileLogReceiver",
+      "HealthCheckExtension",
+      "HostMetricsReceiver",
+      "K8sAttributesProcessor",
+      "KubeletStatsReceiver",
+      "MemoryLimiterProcessor",
+      "OtlpReceiver",
+      "Pipeline",
+      "ResourceDetectionProcessor",
+      "ResourceProcessor"
+    ],
+    "params": [
+      {
+        "name": "exporters",
+        "type": "Exporter[]",
+        "required": true,
+        "description": "Where traces and logs go: usually the gateway (the k8s lexicon's `gatewayExporter()`), or an OTLP backend."
+      },
+      {
+        "name": "metricExporters",
+        "type": "Exporter[]",
+        "required": false,
+        "description": "Where metrics go, e.g. a `prometheus` exporter for a scrape on each node."
+      },
+      {
+        "name": "clusterName",
+        "type": "string",
+        "required": false,
+        "description": "Sets `k8s.cluster.name` on everything the agent sends."
+      },
+      {
+        "name": "nodeNameEnv",
+        "type": "string",
+        "required": false,
+        "description": "The environment variable holding this node's name, set from `spec.nodeName` (default `K8S_NODE_NAME`)."
+      },
+      {
+        "name": "hostMetrics",
+        "type": "boolean | { interval?: Duration; rootPath?: string }",
+        "required": false,
+        "description": "Node CPU, memory, load, filesystem and network from the host root at `/hostfs` (default: on, every 30s)."
+      },
+      {
+        "name": "containerLogs",
+        "type": "boolean | { selfContainer?: string }",
+        "required": false,
+        "description": "Container logs from `/var/log/pods` (default: on)."
+      },
+      {
+        "name": "kubeletStats",
+        "type": "boolean | { interval?: Duration }",
+        "required": false,
+        "description": "Pod and container resource metrics from this node's kubelet (default: off)."
+      },
+      {
+        "name": "memoryLimitMib",
+        "type": "number",
+        "required": false,
+        "description": "`memory_limiter`'s hard limit in MiB (default 400; the spike limit is a quarter of it)."
+      },
+      {
+        "name": "healthCheck",
+        "type": "boolean",
+        "required": false,
+        "description": "Serve `health_check` on 0.0.0.0:13133 (default: on)."
+      }
+    ]
+  }
+];