@intentius/chant-lexicon-otel 0.95.1 → 0.96.0

package/src/components/filtering.test.ts

@@ -0,0 +1,192 @@
+import { describe, expect, test } from "vitest";
+import { load } from "js-yaml";
+import type { Declarable } from "@intentius/chant/declarable";
+import { otelSerializer } from "../serializer";
+import { collectorYaml } from "../collector";
+import { validateCollectorEntities } from "../validate-config";
+import { COLLECTOR_PIN } from "../define";
+import { DebugExporter } from "./exporters";
+import { OtlpReceiver } from "./receivers";
+import { FilterProcessor, RedactionProcessor, TransformProcessor } from "./filtering";
+import { Pipeline } from "../pipeline";
+
+function entities(record: Record<string, unknown>): Map<string, Declarable> {
+  return new Map(Object.entries(record) as Array<[string, Declarable]>);
+}
+
+function primary(out: ReturnType<typeof otelSerializer.serialize>): string {
+  return typeof out === "string" ? out : out.primary;
+}
+
+function problems(component: Declarable): string[] {
+  return validateCollectorEntities([component])
+    .filter((i) => i.code === "OTEL107")
+    .map((i) => i.message.replace(/^\w+ "[^"]+": /, ""));
+}
+
+describe("filter, transform and redaction are built-ins pinned to the collector release", () => {
+  test.each([
+    [FilterProcessor, "filter"],
+    [TransformProcessor, "transform"],
+    [RedactionProcessor, "redaction"],
+  ] as const)("%o", (Cls, type) => {
+    expect(Cls.definition.kind).toBe("processor");
+    expect(Cls.definition.type).toBe(type);
+    expect(Cls.definition.builtin).toBe(true);
+    expect(Cls.definition.pin).toBe(COLLECTOR_PIN);
+  });
+});
+
+describe("filter processor", () => {
+  test("serializes OTTL conditions per signal and context as strings", () => {
+    const filter = new FilterProcessor({
+      error_mode: "ignore",
+      traces: { span: ['attributes["http.route"] == "/healthz"'], spanevent: ['name == "debug"'] },
+      metrics: { datapoint: ['metric.name == "rpc.duration" and value_double < 0'] },
+      logs: { log_record: ["severity_number < SEVERITY_NUMBER_WARN"] },
+    });
+    expect(primary(otelSerializer.serialize(entities({ filter })))).toBe(`processors:
+  filter:
+    error_mode: ignore
+    traces:
+      span: ["attributes[\\"http.route\\"] == \\"/healthz\\""]
+      spanevent: [name == "debug"]
+    metrics:
+      datapoint: [metric.name == "rpc.duration" and value_double < 0]
+    logs:
+      log_record: [severity_number < SEVERITY_NUMBER_WARN]
+`);
+    const parsed = load(primary(otelSerializer.serialize(entities({ filter })))) as any;
+    expect(parsed.processors.filter.traces.spanevent).toEqual(['name == "debug"']);
+    expect(parsed.processors.filter.metrics.datapoint).toEqual(['metric.name == "rpc.duration" and value_double < 0']);
+  });
+
+  test("a named instance renders under filter/name in a pipeline, conditions intact", () => {
+    const otlp = new OtlpReceiver({ protocols: { grpc: {} } });
+    const drop = new FilterProcessor({ name: "health", traces: { span: ['attributes["http.route"] == "/healthz"'] } });
+    const debug = new DebugExporter({});
+    const parsed = load(
+      collectorYaml([otlp, drop, debug, new Pipeline({ signal: "traces", receivers: [otlp], processors: [drop], exporters: [debug] })]),
+    ) as any;
+    expect(parsed.processors["filter/health"]).toEqual({ traces: { span: ['attributes["http.route"] == "/healthz"'] } });
+    expect(parsed.service.pipelines.traces.processors).toEqual(["filter/health"]);
+  });
+
+  test("a filter with no condition drops nothing, and says so", () => {
+    expect(problems(new FilterProcessor({}))).toEqual([
+      "no condition is set for any signal, so the processor drops nothing",
+    ]);
+    expect(problems(new FilterProcessor({ logs: { log_record: [" "] } }))).toContain(
+      "logs.log_record[0] is an empty condition",
+    );
+    expect(problems(new FilterProcessor({ logs: { log_record: ["true"] } }))).toEqual([]);
+  });
+});
+
+describe("transform processor", () => {
+  test("serializes statement groups per context, and bare statements", () => {
+    const transform = new TransformProcessor({
+      error_mode: "ignore",
+      trace_statements: [
+        {
+          context: "span",
+          conditions: ["kind == SPAN_KIND_SERVER"],
+          statements: ['set(attributes["tier"], "edge")'],
+          error_mode: "propagate",
+        },
+        'delete_key(span.attributes, "http.request.header.cookie")',
+      ],
+      metric_statements: [{ context: "datapoint", statements: ['delete_key(attributes, "pod_ip")'] }],
+      log_statements: [{ statements: ['set(log.severity_text, "WARN") where log.severity_number == 13'] }],
+    });
+    const parsed = load(primary(otelSerializer.serialize(entities({ transform })))) as any;
+    expect(parsed.processors.transform).toEqual({
+      error_mode: "ignore",
+      trace_statements: [
+        {
+          context: "span",
+          conditions: ["kind == SPAN_KIND_SERVER"],
+          statements: ['set(attributes["tier"], "edge")'],
+          error_mode: "propagate",
+        },
+        'delete_key(span.attributes, "http.request.header.cookie")',
+      ],
+      metric_statements: [{ context: "datapoint", statements: ['delete_key(attributes, "pod_ip")'] }],
+      log_statements: [{ statements: ['set(log.severity_text, "WARN") where log.severity_number == 13'] }],
+    });
+  });
+
+  test("the rendered text keeps each statement as one quoted string", () => {
+    const transform = new TransformProcessor({
+      log_statements: [{ context: "log", statements: ['set(attributes["a"], "b")'] }],
+    });
+    expect(collectorYaml([transform])).toBe(`processors:
+  transform:
+    log_statements:
+      - context: log
+        statements: ["set(attributes[\\"a\\"], \\"b\\")"]
+`);
+  });
+
+  test("a context from another signal, an empty group and no statements are reported", () => {
+    const wrong = new TransformProcessor({
+      // @ts-expect-error: "log" is not a trace context; the check catches it for untyped callers too
+      trace_statements: [{ context: "log", statements: ["set(attributes[\"a\"], 1)"] }, { context: "span", statements: [] }],
+    });
+    expect(problems(wrong)).toEqual([
+      'trace_statements[0] has context "log"; trace_statements runs in resource, scope, span, spanevent',
+      "trace_statements[1] has no statements",
+    ]);
+    expect(problems(new TransformProcessor({}))).toEqual([
+      "no statement is set for any signal, so the processor changes nothing",
+    ]);
+  });
+});
+
+describe("redaction processor", () => {
+  test("serializes allow and block lists and the hash function", () => {
+    const redaction = new RedactionProcessor({
+      allow_all_keys: false,
+      allowed_keys: ["http.method", "http.route"],
+      ignored_keys: ["service.name"],
+      blocked_key_patterns: [".*token.*"],
+      blocked_values: ["4[0-9]{12}(?:[0-9]{3})?"],
+      allowed_values: [".+@example\\.com"],
+      hash_function: "sha3",
+      summary: "debug",
+    });
+    expect(collectorYaml([redaction])).toBe(`processors:
+  redaction:
+    allow_all_keys: false
+    allowed_keys: [http.method, http.route]
+    ignored_keys: [service.name]
+    blocked_key_patterns: [.*token.*]
+    blocked_values: ["4[0-9]{12}(?:[0-9]{3})?"]
+    allowed_values: [.+@example\\.com]
+    hash_function: sha3
+    summary: debug
+`);
+    const parsed = load(collectorYaml([redaction])) as any;
+    expect(parsed.processors.redaction.blocked_values).toEqual(["4[0-9]{12}(?:[0-9]{3})?"]);
+    expect(parsed.processors.redaction.allowed_values).toEqual([".+@example\\.com"]);
+    expect(problems(redaction)).toEqual([]);
+  });
+
+  test("with neither allow_all_keys nor allowed_keys every attribute would be deleted", () => {
+    expect(problems(new RedactionProcessor({ blocked_values: ["secret"] }))).toEqual([
+      "neither allow_all_keys nor allowed_keys is set, so every attribute is deleted; set allow_all_keys: true to keep keys, or allowed_keys: [] if deleting all is intended",
+    ]);
+    expect(problems(new RedactionProcessor({ allowed_keys: [] }))).toEqual([]);
+    expect(problems(new RedactionProcessor({ allow_all_keys: true, blocked_values: ["secret"] }))).toEqual([]);
+  });
+
+  test("contradictions and no-ops are reported", () => {
+    expect(problems(new RedactionProcessor({ allow_all_keys: true, allowed_keys: ["a"], hash_function: "md5" }))).toEqual([
+      "allowed_keys has no effect while allow_all_keys is true",
+      "hash_function is set but nothing is blocked, so nothing is hashed",
+    ]);
+    expect(problems(new RedactionProcessor({ allow_all_keys: true, blocked_values: [""] }))).toEqual([
+      "blocked_values[0] is an empty pattern",
+    ]);
+  });
+});

package/src/components/filtering.ts

@@ -0,0 +1,192 @@
+/**
+ * Built-in processors that drop, rewrite or redact telemetry: filter,
+ * transform, redaction.
+ *
+ * `filter` and `transform` take OTTL. chant types the structure around it
+ * (which signal, which context, which list) and keeps each OTTL condition or
+ * statement as a string; the collector parses them when it loads the config.
+ */
+
+import { defineBuiltin } from "../define";
+
+/** What an OTTL processor does when a condition or statement errors at run time. */
+export type OttlErrorMode = "ignore" | "silent" | "propagate";
+
+// ── filter ───────────────────────────────────────────────────────────
+
+/** OTTL conditions per context. Telemetry matching any condition is dropped. */
+export interface FilterProcessorConfig {
+  /** Default `propagate`: an erroring condition fails the batch. `ignore` logs and moves on. */
+  error_mode?: OttlErrorMode;
+  traces?: {
+    /** Drops the span, e.g. `attributes["http.route"] == "/healthz"`. */
+    span?: string[];
+    /** Drops the span event. */
+    spanevent?: string[];
+  };
+  metrics?: {
+    /** Drops the whole metric, e.g. `name == "http.server.duration" and type == METRIC_DATA_TYPE_HISTOGRAM`. */
+    metric?: string[];
+    /** Drops the data point. */
+    datapoint?: string[];
+  };
+  logs?: {
+    /** Drops the log record, e.g. `severity_number < SEVERITY_NUMBER_WARN`. */
+    log_record?: string[];
+  };
+}
+
+/** Drops spans, span events, metrics, data points and log records that match OTTL conditions. */
+export const FilterProcessor = defineBuiltin<FilterProcessorConfig, "processor", "filter">({
+  kind: "processor",
+  type: "filter",
+  description: "Drops spans, metrics and logs that match OTTL conditions",
+  validate: (c) => {
+    const lists: Array<[string, string[] | undefined]> = [
+      ["traces.span", c.traces?.span],
+      ["traces.spanevent", c.traces?.spanevent],
+      ["metrics.metric", c.metrics?.metric],
+      ["metrics.datapoint", c.metrics?.datapoint],
+      ["logs.log_record", c.logs?.log_record],
+    ];
+    const problems: string[] = [];
+    for (const [path, list] of lists) {
+      (list ?? []).forEach((cond, i) => {
+        if (typeof cond !== "string" || cond.trim() === "") problems.push(`${path}[${i}] is an empty condition`);
+      });
+    }
+    if (lists.every(([, list]) => !list || list.length === 0)) {
+      problems.push("no condition is set for any signal, so the processor drops nothing");
+    }
+    return problems;
+  },
+});
+
+// ── transform ────────────────────────────────────────────────────────
+
+/** OTTL contexts a trace statement group can run in. */
+export type TraceStatementContext = "resource" | "scope" | "span" | "spanevent";
+/** OTTL contexts a metric statement group can run in. */
+export type MetricStatementContext = "resource" | "scope" | "metric" | "datapoint";
+/** OTTL contexts a log statement group can run in. */
+export type LogStatementContext = "resource" | "scope" | "log";
+
+/**
+ * A group of OTTL statements run in one context. `conditions` gate every
+ * statement in the group; each statement may also carry its own `where`.
+ */
+export interface TransformStatementGroup<Ctx extends string = string> {
+  /** The OTTL context. Leave it out and the collector infers it from the paths the statements use. */
+  context?: Ctx;
+  conditions?: string[];
+  statements: string[];
+  /** Overrides the processor's `error_mode` for this group. */
+  error_mode?: OttlErrorMode;
+}
+
+/** Each entry is a group, or a bare statement whose context the collector infers. */
+export type TransformStatements<Ctx extends string> = Array<string | TransformStatementGroup<Ctx>>;
+
+export interface TransformProcessorConfig {
+  /** Default `propagate`. */
+  error_mode?: OttlErrorMode;
+  trace_statements?: TransformStatements<TraceStatementContext>;
+  metric_statements?: TransformStatements<MetricStatementContext>;
+  log_statements?: TransformStatements<LogStatementContext>;
+}
+
+const TRANSFORM_CONTEXTS: Record<"trace_statements" | "metric_statements" | "log_statements", readonly string[]> = {
+  trace_statements: ["resource", "scope", "span", "spanevent"],
+  metric_statements: ["resource", "scope", "metric", "datapoint"],
+  log_statements: ["resource", "scope", "log"],
+};
+
+/** Rewrites telemetry with OTTL statements, grouped per signal and context. */
+export const TransformProcessor = defineBuiltin<TransformProcessorConfig, "processor", "transform">({
+  kind: "processor",
+  type: "transform",
+  description: "Rewrites spans, metrics and logs with OTTL statements, grouped by context",
+  validate: (c) => {
+    const problems: string[] = [];
+    let total = 0;
+    for (const field of Object.keys(TRANSFORM_CONTEXTS) as Array<keyof typeof TRANSFORM_CONTEXTS>) {
+      const allowed = TRANSFORM_CONTEXTS[field];
+      (c[field] ?? []).forEach((entry, i) => {
+        if (typeof entry === "string") {
+          if (entry.trim() === "") problems.push(`${field}[${i}] is an empty statement`);
+          else total++;
+          return;
+        }
+        if (entry.context !== undefined && !allowed.includes(entry.context)) {
+          problems.push(`${field}[${i}] has context "${entry.context}"; ${field} runs in ${allowed.join(", ")}`);
+        }
+        if (!entry.statements || entry.statements.length === 0) {
+          problems.push(`${field}[${i}] has no statements`);
+        }
+        total += entry.statements?.length ?? 0;
+      });
+    }
+    if (total === 0) problems.push("no statement is set for any signal, so the processor changes nothing");
+    return problems;
+  },
+});
+
+// ── redaction ────────────────────────────────────────────────────────
+
+/**
+ * Attribute keys and values to keep, mask or hash. Applies to span, span
+ * event, log record and metric data point attributes (not resource
+ * attributes).
+ *
+ * Keys: with `allow_all_keys` false, any attribute whose key is not in
+ * `allowed_keys` or `ignored_keys` is deleted. Values: a value matching a
+ * `blocked_values` pattern, or any value of a key matching a
+ * `blocked_key_patterns` pattern, is masked with `****`, or replaced by its
+ * hash when `hash_function` is set; `allowed_values` exempts a value from
+ * masking. Patterns are Go (RE2) regular expressions.
+ */
+export interface RedactionProcessorConfig {
+  /** Keep every key, so only values are masked. Default false. */
+  allow_all_keys?: boolean;
+  /** The keys that survive when `allow_all_keys` is false. */
+  allowed_keys?: string[];
+  /** Keys never touched: not deleted, not masked. */
+  ignored_keys?: string[];
+  /** Regexes on keys; every value of a matching key is masked. */
+  blocked_key_patterns?: string[];
+  /** Regexes on values; the matching part is masked. */
+  blocked_values?: string[];
+  /** Regexes on values that are never masked, even when they match a blocked pattern. */
+  allowed_values?: string[];
+  /** Hash blocked values with this function instead of masking them. */
+  hash_function?: "md5" | "sha1" | "sha3";
+  /** How much the processor records about what it redacted, as span attributes. Default `info`. */
+  summary?: "debug" | "info" | "silent";
+}
+
+/** Deletes attributes whose keys aren't allowed, and masks or hashes values that match blocked patterns. */
+export const RedactionProcessor = defineBuiltin<RedactionProcessorConfig, "processor", "redaction">({
+  kind: "processor",
+  type: "redaction",
+  description: "Deletes attributes not on an allow list and masks or hashes values that match block patterns",
+  validate: (c) => {
+    const problems: string[] = [];
+    if (c.allow_all_keys !== true && c.allowed_keys === undefined) {
+      problems.push(
+        "neither allow_all_keys nor allowed_keys is set, so every attribute is deleted; set allow_all_keys: true to keep keys, or allowed_keys: [] if deleting all is intended",
+      );
+    }
+    if (c.allow_all_keys === true && c.allowed_keys !== undefined && c.allowed_keys.length > 0) {
+      problems.push("allowed_keys has no effect while allow_all_keys is true");
+    }
+    for (const field of ["blocked_key_patterns", "blocked_values", "allowed_values"] as const) {
+      (c[field] ?? []).forEach((p, i) => {
+        if (typeof p !== "string" || p === "") problems.push(`${field}[${i}] is an empty pattern`);
+      });
+    }
+    if (c.hash_function !== undefined && !c.blocked_values?.length && !c.blocked_key_patterns?.length) {
+      problems.push("hash_function is set but nothing is blocked, so nothing is hashed");
+    }
+    return problems;
+  },
+});

package/src/components/index.ts

@@ -1,5 +1,9 @@
 export * from "./common";
 export * from "./receivers";
+export * from "./k8s-receivers";
 export * from "./processors";
+export * from "./filtering";
 export * from "./exporters";
+export * from "./connectors";
 export * from "./extensions";
+export * from "./sampling";

package/src/components/k8s-receivers.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, test } from "vitest";
+import { load } from "js-yaml";
+import type { Declarable } from "@intentius/chant/declarable";
+import { otelSerializer } from "../serializer";
+import { collectorYaml } from "../collector";
+import { collectorTopology } from "../topology";
+import { validateCollectorEntities } from "../validate-config";
+import { COLLECTOR_PIN } from "../define";
+import { DebugExporter } from "./exporters";
+import { K8sClusterReceiver, KubeletStatsReceiver } from "./k8s-receivers";
+import { Pipeline } from "../pipeline";
+
+function problems(component: Declarable): string[] {
+  return validateCollectorEntities([component])
+    .filter((i) => i.code === "OTEL107")
+    .map((i) => i.message.replace(/^\w+ "[^"]+": /, ""));
+}
+
+function primary(out: ReturnType<typeof otelSerializer.serialize>): string {
+  return typeof out === "string" ? out : out.primary;
+}
+
+describe("k8s_cluster and kubeletstats are built-ins pinned to the collector release", () => {
+  test.each([
+    [K8sClusterReceiver, "k8s_cluster"],
+    [KubeletStatsReceiver, "kubeletstats"],
+  ] as const)("%o", (Cls, type) => {
+    expect(Cls.definition.kind).toBe("receiver");
+    expect(Cls.definition.type).toBe(type);
+    expect(Cls.definition.builtin).toBe(true);
+    expect(Cls.definition.pin).toBe(COLLECTOR_PIN);
+  });
+});
+
+describe("k8s_cluster receiver", () => {
+  test("serializes", () => {
+    const cluster = new K8sClusterReceiver({
+      auth_type: "serviceAccount",
+      collection_interval: "30s",
+      node_conditions_to_report: ["Ready", "MemoryPressure"],
+      allocatable_types_to_report: ["cpu", "memory"],
+      k8s_leader_elector: "k8s_leader_elector",
+      metrics: { "k8s.pod.status_reason": { enabled: true } },
+    });
+    const out = primary(otelSerializer.serialize(new Map([["cluster", cluster as unknown as Declarable]])));
+    expect(out).toBe(`receivers:
+  k8s_cluster:
+    auth_type: serviceAccount
+    collection_interval: 30s
+    node_conditions_to_report: [Ready, MemoryPressure]
+    allocatable_types_to_report: [cpu, memory]
+    k8s_leader_elector: k8s_leader_elector
+    metrics:
+      k8s.pod.status_reason:
+        enabled: true
+`);
+    expect(problems(cluster)).toEqual([]);
+  });
+
+  test("renders in a metrics pipeline and reports no endpoint", () => {
+    const cluster = new K8sClusterReceiver({});
+    const debug = new DebugExporter({});
+    const yaml = collectorYaml([cluster, debug, new Pipeline({ signal: "metrics", receivers: [cluster], exporters: [debug] })]);
+    const parsed = load(yaml) as any;
+    expect(parsed.receivers).toEqual({ k8s_cluster: {} });
+    expect(parsed.service.pipelines.metrics.receivers).toEqual(["k8s_cluster"]);
+    const topo = collectorTopology(parsed);
+    expect(topo.components.find((c) => c.id === "k8s_cluster")?.endpoints ?? []).toEqual([]);
+  });
+
+  test("an unknown distribution is reported", () => {
+    // @ts-expect-error: not a distribution
+    expect(problems(new K8sClusterReceiver({ distribution: "eks" }))).toEqual([
+      'distribution "eks" is not kubernetes or openshift',
+    ]);
+  });
+});
+
+describe("kubeletstats receiver", () => {
+  test("serializes the usual per-node agent shape, and reports the kubelet as its endpoint", () => {
+    const kubelet = new KubeletStatsReceiver({
+      auth_type: "serviceAccount",
+      endpoint: "https://${env:K8S_NODE_NAME}:10250",
+      insecure_skip_verify: true,
+      collection_interval: "20s",
+      metric_groups: ["node", "pod", "container"],
+      extra_metadata_labels: ["container.id"],
+      node: "${env:K8S_NODE_NAME}",
+    });
+    const yaml = collectorYaml([kubelet]);
+    expect(yaml).toBe(`receivers:
+  kubeletstats:
+    auth_type: serviceAccount
+    endpoint: https://\${env:K8S_NODE_NAME}:10250
+    insecure_skip_verify: true
+    collection_interval: 20s
+    metric_groups: [node, pod, container]
+    extra_metadata_labels: [container.id]
+    node: \${env:K8S_NODE_NAME}
+`);
+    const topo = collectorTopology(load(yaml) as any);
+    expect(topo.components.find((c) => c.id === "kubeletstats")?.endpoints).toEqual([
+      "https://${env:K8S_NODE_NAME}:10250",
+    ]);
+    expect(problems(kubelet)).toEqual([]);
+  });
+
+  test("tls auth, the default, needs a client certificate", () => {
+    expect(problems(new KubeletStatsReceiver({}))).toEqual([
+      "auth_type defaults to tls, which needs cert_file and key_file; in a pod set auth_type: serviceAccount",
+    ]);
+    expect(problems(new KubeletStatsReceiver({ auth_type: "tls", cert_file: "/c" }))).toEqual([
+      "auth_type tls needs cert_file and key_file; in a pod set auth_type: serviceAccount",
+    ]);
+    expect(problems(new KubeletStatsReceiver({ auth_type: "tls", cert_file: "/c", key_file: "/k" }))).toEqual([]);
+  });
+
+  test("an empty metric_groups collects nothing", () => {
+    expect(problems(new KubeletStatsReceiver({ auth_type: "none", metric_groups: [] }))).toEqual([
+      "metric_groups is empty, so no kubelet metric is collected",
+    ]);
+  });
+});

package/src/components/k8s-receivers.ts

@@ -0,0 +1,107 @@
+/**
+ * Built-in Kubernetes receivers: k8s_cluster (cluster-level object metrics,
+ * one instance per cluster) and kubeletstats (node, pod and container
+ * resource metrics from each node's kubelet, one instance per node).
+ */
+
+import { defineBuiltin } from "../define";
+import type { Duration } from "./common";
+
+/** How a receiver authenticates to the Kubernetes API or the kubelet. */
+export type K8sAuthType = "none" | "serviceAccount" | "kubeConfig" | "tls";
+
+/** Turns one generated metric or resource attribute on or off. */
+export interface MetricToggle {
+  enabled: boolean;
+}
+
+// ── k8s_cluster ──────────────────────────────────────────────────────
+
+export type K8sAllocatableType = "cpu" | "memory" | "ephemeral-storage" | "storage" | "pods";
+
+export type K8sNodeCondition = "Ready" | "MemoryPressure" | "DiskPressure" | "PIDPressure" | "NetworkUnavailable";
+
+export interface K8sClusterReceiverConfig {
+  /** Default `serviceAccount`. */
+  auth_type?: K8sAuthType;
+  /** Default `10s`. */
+  collection_interval?: Duration;
+  /** Default `[Ready]`. */
+  node_conditions_to_report?: Array<K8sNodeCondition | (string & {})>;
+  allocatable_types_to_report?: K8sAllocatableType[];
+  /** Default `kubernetes`. `openshift` adds cluster quota metrics. */
+  distribution?: "kubernetes" | "openshift";
+  /** Exporter ids that receive entity metadata updates. */
+  metadata_exporters?: string[];
+  metadata_collection_interval?: Duration;
+  /** The id of a `k8s_leader_elector` extension, so only the leader among replicas collects. */
+  k8s_leader_elector?: string;
+  /** Watch one namespace instead of the whole cluster. */
+  namespace?: string;
+  metrics?: Record<string, MetricToggle>;
+  resource_attributes?: Record<string, MetricToggle>;
+}
+
+/**
+ * Cluster-level metrics and entity events from the Kubernetes API. Run one
+ * instance per cluster (a single-replica Deployment, or behind
+ * `k8s_leader_elector`); on every node it reports each object once per node.
+ */
+export const K8sClusterReceiver = defineBuiltin<K8sClusterReceiverConfig, "receiver", "k8s_cluster">({
+  kind: "receiver",
+  type: "k8s_cluster",
+  description: "Cluster-level metrics from the Kubernetes API; run one instance per cluster",
+  validate: (c) =>
+    c.distribution !== undefined && c.distribution !== "kubernetes" && c.distribution !== "openshift"
+      ? [`distribution "${String(c.distribution)}" is not kubernetes or openshift`]
+      : [],
+});
+
+// ── kubeletstats ─────────────────────────────────────────────────────
+
+export type KubeletMetricGroup = "container" | "pod" | "node" | "volume";
+
+export interface KubeletStatsReceiverConfig {
+  /** Default `10s`. */
+  collection_interval?: Duration;
+  initial_delay?: Duration;
+  /** Default `tls`, which needs `cert_file` and `key_file`. In a pod, use `serviceAccount`. */
+  auth_type?: K8sAuthType;
+  /** The kubelet, e.g. `https://${env:K8S_NODE_NAME}:10250`. */
+  endpoint?: string;
+  insecure_skip_verify?: boolean;
+  ca_file?: string;
+  cert_file?: string;
+  key_file?: string;
+  /** Default `[container, pod, node]`. */
+  metric_groups?: KubeletMetricGroup[];
+  /** Extra labels on container and volume metrics. */
+  extra_metadata_labels?: Array<"container.id" | "k8s.volume.type">;
+  /** Kubernetes API access, for persistent volume claim metadata. */
+  k8s_api_config?: { auth_type: K8sAuthType; context?: string };
+  /** The node name, for the limit and request utilization metrics; usually `${env:K8S_NODE_NAME}`. */
+  node?: string;
+  collect_all_network_interfaces?: { pod?: boolean; node?: boolean };
+  metrics?: Record<string, MetricToggle>;
+  resource_attributes?: Record<string, MetricToggle>;
+}
+
+/** Node, pod, container and volume resource metrics from the local kubelet. Run one instance per node. */
+export const KubeletStatsReceiver = defineBuiltin<KubeletStatsReceiverConfig, "receiver", "kubeletstats">({
+  kind: "receiver",
+  type: "kubeletstats",
+  description: "Node, pod and container resource metrics from the kubelet; run one instance per node",
+  validate: (c) => {
+    const problems: string[] = [];
+    if ((c.auth_type ?? "tls") === "tls" && (!c.cert_file || !c.key_file)) {
+      problems.push(
+        `auth_type ${c.auth_type ? "tls" : "defaults to tls, which"} needs cert_file and key_file; in a pod set auth_type: serviceAccount`,
+      );
+    }
+    if (c.metric_groups !== undefined && c.metric_groups.length === 0) {
+      problems.push("metric_groups is empty, so no kubelet metric is collected");
+    }
+    return problems;
+  },
+  endpoints: (c) => (c.endpoint ? [c.endpoint] : []),
+});