@intentius/chant-lexicon-otel 0.101.0 → 0.104.0

package/src/metric-names.test.ts

@@ -1,9 +1,15 @@
 import { describe, expect, test } from "vitest";
-import { PrometheusExporter, SpanMetricsConnector } from "./components";
+import { PrometheusExporter, ServiceGraphConnector, SpanMetricsConnector } from "./components";
 import { genAiComponents, genAiMetrics } from "./genai";
-import { prometheusLabel, prometheusMetricName, spanMetricsNames } from "./metric-names";
+import { prometheusLabel, prometheusMetricName, serviceGraphNames, spanMetricsNames } from "./metric-names";
 
 describe("spanMetricsNames", () => {
+  test("takes a span_metrics declaration, the collector's newer name, as a spanmetrics one", () => {
+    const declared = { componentType: "span_metrics", props: { namespace: "spans" } } as never;
+    expect(spanMetricsNames(declared).namespace).toBe("spans");
+    expect(() => spanMetricsNames({ componentType: "count", props: {} } as never)).toThrow("expected a spanmetrics connector");
+  });
+
   test("defaults: the traces.span.metrics namespace and a millisecond histogram", () => {
     const n = spanMetricsNames(new SpanMetricsConnector({}));
     expect(n.namespace).toBe("traces.span.metrics");
@@ -78,3 +84,19 @@ describe("prometheus naming", () => {
     expect(prometheusMetricName("calls", "sum", "{call}")).toBe("calls_total");
   });
 });
+
+describe("serviceGraphNames", () => {
+  test("the fixed names, in seconds, with the edge labels and the client_/server_ dimensions", () => {
+    const n = serviceGraphNames(new ServiceGraphConnector({ dimensions: ["http.method"], virtual_node_extra_label: true }));
+    expect(n.requests.prometheus).toBe("traces_service_graph_request_total");
+    expect(n.failed.prometheus).toBe("traces_service_graph_request_failed_total");
+    expect(n.serverDuration.prometheus).toBe("traces_service_graph_request_server_seconds");
+    expect(n.clientDuration.prometheus).toBe("traces_service_graph_request_client_seconds");
+    expect(n.requests.dimensions).toEqual(["client", "server", "connection_type", "failed", "client_http.method", "server_http.method", "virtual_node"]);
+  });
+
+  test("the exporter's namespace prefixes the names", () => {
+    expect(serviceGraphNames({}, new PrometheusExporter({ endpoint: "0.0.0.0:8889", namespace: "otel" })).requests.prometheus).toBe("otel_traces_service_graph_request_total");
+    expect(() => serviceGraphNames(new SpanMetricsConnector({}))).toThrow(/expected a servicegraph connector/);
+  });
+});

package/src/metric-names.ts

@@ -19,6 +19,8 @@
  * builds queries from it does not load the collector components.
  */
 
+import { canonicalComponentType } from "./model";
+
 /** A metric a collector component emits, as the collector names it and as Prometheus exposes it. */
 export interface CollectorMetric {
   /** The OTLP metric name. */
@@ -114,7 +116,7 @@ type Declared = { componentType?: unknown; props?: unknown };
 function configOf(connector: SpanMetricsNamingConfig | Declared): SpanMetricsNamingConfig {
   const d = connector as Declared;
   if (typeof d.componentType === "string") {
-    if (d.componentType !== "spanmetrics") throw new Error(`spanMetricsNames: expected a spanmetrics connector, got ${d.componentType}`);
+    if (canonicalComponentType("connector", d.componentType) !== "spanmetrics") throw new Error(`spanMetricsNames: expected a spanmetrics connector, got ${d.componentType}`);
     return (d.props ?? {}) as SpanMetricsNamingConfig;
   }
   return connector as SpanMetricsNamingConfig;
@@ -174,3 +176,66 @@ export function spanMetricsNames(
     errorStatus: SPAN_STATUS_ERROR,
   };
 }
+
+/** The prefix of every metric the `servicegraph` connector emits; the connector takes no namespace. */
+export const SERVICEGRAPH_NAMESPACE = "traces_service_graph";
+
+/** The parts of a servicegraph config the metric labels depend on. */
+export interface ServiceGraphNamingConfig {
+  dimensions?: string[];
+  virtual_node_extra_label?: boolean;
+}
+
+/** The metrics one `servicegraph` connector emits. */
+export interface ServiceGraphNames {
+  /** Requests per edge. */
+  requests: CollectorMetric;
+  /** Failed requests per edge. */
+  failed: CollectorMetric;
+  /** Server-side request duration histogram, in seconds. */
+  serverDuration: CollectorMetric;
+  /** Client-side request duration histogram, in seconds. */
+  clientDuration: CollectorMetric;
+}
+
+/**
+ * The Prometheus names of the metrics a `servicegraph` connector emits at
+ * `COLLECTOR_PIN`, with its default feature gates: latency in seconds, under
+ * `_request_server` and `_request_client`. Every metric carries `client`,
+ * `server`, `connection_type` and `failed`, `client_<d>` and `server_<d>` for
+ * each configured dimension, and `virtual_node` when
+ * `virtual_node_extra_label` is set (connector/servicegraphconnector/connector.go).
+ */
+export function serviceGraphNames(
+  connector: ServiceGraphNamingConfig | Declared,
+  exporter?: PrometheusNaming | { props?: PrometheusNaming },
+): ServiceGraphNames {
+  const d = connector as Declared;
+  if (typeof d.componentType === "string" && d.componentType !== "servicegraph") {
+    throw new Error(`serviceGraphNames: expected a servicegraph connector, got ${d.componentType}`);
+  }
+  const c = (typeof d.componentType === "string" ? (d.props ?? {}) : connector) as ServiceGraphNamingConfig;
+  const naming: PrometheusNaming =
+    exporter && "props" in exporter && typeof exporter.props === "object" ? (exporter.props as PrometheusNaming) : ((exporter ?? {}) as PrometheusNaming);
+  const dimensions = [
+    "client",
+    "server",
+    "connection_type",
+    "failed",
+    ...(c.dimensions ?? []).flatMap((dim) => [`client_${dim}`, `server_${dim}`]),
+    ...(c.virtual_node_extra_label ? ["virtual_node"] : []),
+  ];
+  const metric = (n: string, type: "sum" | "histogram", unit?: string): CollectorMetric => ({
+    name: `${SERVICEGRAPH_NAMESPACE}_${n}`,
+    prometheus: prometheusMetricName(`${SERVICEGRAPH_NAMESPACE}_${n}`, type, unit, naming),
+    type,
+    ...(unit ? { unit } : {}),
+    dimensions,
+  });
+  return {
+    requests: metric("request_total", "sum"),
+    failed: metric("request_failed_total", "sum"),
+    serverDuration: metric("request_server", "histogram", "s"),
+    clientDuration: metric("request_client", "histogram", "s"),
+  };
+}

package/src/model.ts

@@ -108,3 +108,51 @@ export function looksLikeCollectorConfig(value: unknown): value is CollectorConf
   if (typeof pipelines !== "object" || pipelines === null) return false;
   return "receivers" in v || "exporters" in v;
 }
+
+/**
+ * A built-in type the collector renamed, keeping the old name as a
+ * deprecated alias. `type` is the new name and `builtin` the name chant's
+ * class declares and emits. `since` is the first release of `repo` whose
+ * `metadata.yaml` for the component lists `builtin` as `deprecated_type`.
+ */
+export interface ComponentTypeAlias {
+  kind: ComponentKind;
+  type: string;
+  builtin: string;
+  since: string;
+  repo: "core" | "contrib";
+}
+
+/**
+ * The renamed built-ins. chant emits `builtin`, which the pinned collector
+ * (`COLLECTOR_PIN`, v0.130.0) knows and newer ones still accept. A config
+ * written for a newer collector may use `type`, so code that reads a config
+ * (the importer, the checks, the k8s composites) accepts both.
+ */
+export const COMPONENT_TYPE_ALIASES: readonly ComponentTypeAlias[] = [
+  { kind: "exporter", type: "otlp_grpc", builtin: "otlp", since: "v0.148.0", repo: "core" },
+  { kind: "exporter", type: "otlp_http", builtin: "otlphttp", since: "v0.148.0", repo: "core" },
+  { kind: "processor", type: "k8s_attributes", builtin: "k8sattributes", since: "v0.148.0", repo: "contrib" },
+  { kind: "connector", type: "signal_to_metrics", builtin: "signaltometrics", since: "v0.148.0", repo: "contrib" },
+  { kind: "receiver", type: "file_log", builtin: "filelog", since: "v0.149.0", repo: "contrib" },
+  { kind: "connector", type: "span_metrics", builtin: "spanmetrics", since: "v0.151.0", repo: "contrib" },
+  { kind: "connector", type: "service_graph", builtin: "servicegraph", since: "v0.151.0", repo: "contrib" },
+  { kind: "receiver", type: "host_metrics", builtin: "hostmetrics", since: "v0.151.0", repo: "contrib" },
+  { kind: "receiver", type: "kubelet_stats", builtin: "kubeletstats", since: "v0.152.0", repo: "contrib" },
+  { kind: "processor", type: "resource_detection", builtin: "resourcedetection", since: "v0.153.0", repo: "contrib" },
+  { kind: "exporter", type: "load_balancing", builtin: "loadbalancing", since: "v0.153.0", repo: "contrib" },
+  { kind: "processor", type: "delta_to_cumulative", builtin: "deltatocumulative", since: "v0.158.0", repo: "contrib" },
+];
+
+const ALIAS_TO_BUILTIN: ReadonlyMap<string, string> = new Map(COMPONENT_TYPE_ALIASES.map((a) => [`${a.kind}:${a.type}`, a.builtin]));
+
+/** The type chant declares for `kind` + `type`: the old name of a renamed built-in, otherwise `type` itself. */
+export function canonicalComponentType(kind: ComponentKind, type: string): string {
+  return ALIAS_TO_BUILTIN.get(`${kind}:${type}`) ?? type;
+}
+
+/** The type of component id `id`, with a renamed built-in's new name read as the old one: `span_metrics/genai` is `spanmetrics`. */
+export function canonicalTypeOf(kind: ComponentKind, id: string): string {
+  const slash = id.indexOf("/");
+  return canonicalComponentType(kind, slash === -1 ? id : id.slice(0, slash));
+}

package/src/platform.test.ts

@@ -44,6 +44,67 @@ describe("collectorEndpoints", () => {
     expect(collectorEndpoints(config).ports).toEqual([{ name: "otlp-edge-grpc", port: 14317 }]);
   });
 
+  test("a receiver's client endpoint is not a port: kubeletstats and k8s_cluster beside otlp add none (#3102)", () => {
+    const config: CollectorConfig = {
+      receivers: {
+        otlp: { protocols: { grpc: { endpoint: "0.0.0.0:4317" } } },
+        kubeletstats: { auth_type: "serviceAccount", endpoint: "https://${env:K8S_NODE_NAME}:10250" },
+        k8s_cluster: { auth_type: "serviceAccount" },
+        prometheus: { config: { scrape_configs: [] }, target_allocator: { endpoint: "http://ta:8080" } },
+      },
+    };
+    expect(collectorEndpoints(config).ports).toEqual([{ name: "otlp-grpc", port: 4317 }]);
+  });
+
+  test("zipkin and jaeger listeners are ports", () => {
+    const config: CollectorConfig = {
+      receivers: {
+        zipkin: { endpoint: "0.0.0.0:9411" },
+        jaeger: { protocols: { grpc: { endpoint: "0.0.0.0:14250" }, thrift_http: { endpoint: "0.0.0.0:14268" } } },
+      },
+    };
+    expect(collectorEndpoints(config).ports).toEqual([
+      { name: "zipkin", port: 9411 },
+      { name: "jaeger-grpc", port: 14250 },
+      { name: "jaeger-thrift-h", port: 14268 },
+    ]);
+  });
+
+  test("the prometheus exporter's scrape endpoint is a port, after the receivers' (#3122)", () => {
+    const config: CollectorConfig = {
+      receivers: { otlp: { protocols: { grpc: { endpoint: "0.0.0.0:4317" } } } },
+      exporters: { prometheus: { endpoint: "0.0.0.0:8889" }, otlp: { endpoint: "tempo:4317" } },
+    };
+    expect(collectorEndpoints(config).ports).toEqual([
+      { name: "otlp-grpc", port: 4317 },
+      { name: "prometheus", port: 8889 },
+    ]);
+  });
+
+  test("contrib push receivers that listen are ports, and a UDP listener says so (#3122)", () => {
+    const config: CollectorConfig = {
+      receivers: {
+        statsd: { endpoint: "0.0.0.0:8125" },
+        "carbon/tcp": { endpoint: "0.0.0.0:2003" },
+        "carbon/udp": { endpoint: "0.0.0.0:2003", transport: "udp" },
+        syslog: { protocol: "rfc5424", tcp: { listen_address: "0.0.0.0:54526" }, udp: { listen_address: "0.0.0.0:54526" } },
+        fluentforward: { endpoint: "0.0.0.0:8006" },
+        splunk_hec: { endpoint: "0.0.0.0:8088" },
+        influxdb: { endpoint: "0.0.0.0:8086" },
+      },
+    };
+    expect(collectorEndpoints(config).ports).toEqual([
+      { name: "statsd", port: 8125, protocol: "UDP" },
+      { name: "carbon-tcp", port: 2003 },
+      { name: "carbon-udp", port: 2003, protocol: "UDP" },
+      { name: "syslog-tcp", port: 54526 },
+      { name: "syslog-udp", port: 54526, protocol: "UDP" },
+      { name: "fluentforward", port: 8006 },
+      { name: "splunk-hec", port: 8088 },
+      { name: "influxdb", port: 8086 },
+    ]);
+  });
+
   test("port names are cut to 15 characters", () => {
     const config: CollectorConfig = {
       receivers: { "otlp/very_long_name": { protocols: { http: { endpoint: "0.0.0.0:4318" } } } },

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 { listenerPaths } 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/, "")}`;
@@ -65,10 +66,12 @@ export interface CollectorPort {
   /** A name usable as a k8s port name: lowercase, `-` separated, at most 15 characters. */
   name: string;
   port: number;
+  /** Set when the listener is UDP. A port without it is TCP. */
+  protocol?: "UDP";
 }
 
 export interface CollectorEndpoints {
-  /** Ports the receivers listen on, in config order, one entry per port. */
+  /** Ports the receivers, then the exporters, listen on, in config order, one entry per port and protocol. */
   ports: CollectorPort[];
   /**
    * The `health_check` extension, when the service enables one and it listens
@@ -95,36 +98,46 @@ 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`,
- * named after the receiver and the protocol key above it (`otlp-grpc`,
- * `otlp-http`), and the `health_check` port if the service enables it.
+ * The ports a built collector config listens on: the address every receiver
+ * and exporter that listens sets (the types OTEL117 knows: otlp, jaeger,
+ * statsd, syslog, the `prometheus` exporter's scrape endpoint and the rest),
+ * named after the component and the key above the address (`otlp-grpc`,
+ * `syslog-udp`), and the `health_check` port if the service enables it. A
+ * component whose `endpoint` is a server it connects to, such as
+ * kubeletstats' kubelet, adds no port, and neither does a type the table
+ * doesn't list. A UDP listener gets `protocol: "UDP"`.
  */
 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);
-      if (!p || seen.has(p.port)) continue;
-      seen.add(p.port);
-      const protocol = path.filter((k) => k !== "protocols");
-      ports.push({ name: portName([...base, ...protocol]), port: p.port });
+  const seen = new Set<string>();
+  const sections: Array<["receiver" | "exporter", Record<string, unknown> | undefined]> = [
+    ["receiver", config.receivers],
+    ["exporter", config.exporters],
+  ];
+  for (const [kind, section] of sections) {
+    for (const [id, body] of Object.entries(section ?? {})) {
+      const parsed = parseComponentId(id);
+      const base = parsed ? [parsed.type, ...(parsed.name ? [parsed.name] : [])] : [id];
+      for (const { path, transport } of listenerPaths(kind, parsed?.type ?? id, body)) {
+        const p = portOf(valueAt(body, path));
+        if (!p || seen.has(`${p.port}/${transport}`)) continue;
+        seen.add(`${p.port}/${transport}`);
+        const protocol = path.slice(0, -1).filter((k) => k !== "protocols");
+        ports.push({ name: portName([...base, ...protocol]), port: p.port, ...(transport === "udp" ? { protocol: "UDP" as const } : {}) });
+      }
     }
   }
 

package/src/plugin.test.ts

@@ -34,6 +34,16 @@ describe("otel plugin", () => {
       "OTEL115",
       "OTEL116",
       "OTEL117",
+      "OTEL118",
+      "OTEL119",
+      "OTEL120",
+      "OTEL121",
+      "OTEL122",
+      "OTEL123",
+      "OTEL124",
+      "OTEL125",
+      "OTEL126",
+      "OTEL127",
     ]);
     for (const id of ids) expect(id.startsWith("OTEL")).toBe(true);
   });

package/src/semconv.ts

@@ -5,14 +5,15 @@
  * A collector config has no metadata channel, so a config cannot say which
  * semconv version its attribute keys follow. What it can show is that it uses
  * a vocabulary: a `spanmetrics` dimension named `gen_ai.request.model`, an
- * OTTL statement deleting `gen_ai.input.messages`. `semconvUsage()` finds
+ * OTTL statement deleting `gen_ai.input.messages`, a `k8sattributes`
+ * processor extracting `k8s.pod.name`. `semconvUsage()` finds
  * those and pairs each vocabulary with the pin this package's keys follow, the
  * same way `collectorTopology()` pairs a component type with the pin of the
  * definition this process has. Reading a parsed YAML file and reading the
  * declaration give the same answer.
  */
 
-import { GENAI_SEMCONV_PIN, type SchemaPin } from "./define";
+import { GENAI_SEMCONV_PIN, SEMCONV_PIN, type SchemaPin } from "./define";
 import { SECTION_OF, type CollectorConfig, type ComponentKind } from "./model";
 
 /** One attribute vocabulary and the version of its conventions this package follows. */
@@ -26,9 +27,12 @@ export interface SemconvVocabulary {
 
 // `gen_ai.` as a key, in OTTL (`attributes["gen_ai.x"]`) or in an RE2 pattern (`gen_ai\.`).
 const GEN_AI_REF = /(^|[^A-Za-z0-9_])gen_ai(\\\\|\\)?\./;
+// `k8s.` with the dot, so the component types `k8s_cluster` and `k8sattributes` don't count.
+const K8S_REF = /(^|[^A-Za-z0-9_])k8s(\\\\|\\)?\./;
 
 export const SEMCONV_VOCABULARIES: ReadonlyArray<SemconvVocabulary> = Object.freeze([
   { namespace: "gen_ai", pin: GENAI_SEMCONV_PIN, matches: (text: string) => GEN_AI_REF.test(text) },
+  { namespace: "k8s", pin: SEMCONV_PIN, matches: (text: string) => K8S_REF.test(text) },
 ]);
 
 /** A vocabulary a config uses, with the components that use it. */

package/src/skills/chant-otel.md

@@ -17,7 +17,7 @@ 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`.
+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
 
@@ -78,10 +78,14 @@ It deletes prompt, completion, system-instruction and tool-call content from spa
 
 - Reference components by entity where you can. A string id (`"otlp/backend"`) is allowed for a component declared elsewhere, and OTEL101 fails the build if nothing declares it.
 - Put `memory_limiter` first in `processors` (OTEL105).
-- Never write a credential literally. Use `"${env:NAME}"` and the collector reads it at start-up (OTEL002).
+- Never write a credential literally. Use `"${env:NAME}"` and the collector reads it at start-up (OTEL002 in source, OTEL120 in the config). Don't send one over `http://` or `tls.insecure: true` (OTEL121).
 - 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).
+- Keep `zpages` and `pprof` on localhost (OTEL122). `health_check` may listen on 0.0.0.0 for probes.
+- Put `batch` in every pipeline that sends to a remote `otlp` or `otlphttp` exporter (OTEL125), and leave the exporter's `sending_queue` and `retry_on_failure` on (OTEL124).
+- Use a `drop` policy rather than `invert_match`, and `readers` rather than `service.telemetry.metrics.address` (OTEL119).
+- In a workspace, or with `telemetry.attribution: true`, leave `service.name`, `service.version`, `deployment.environment.name`, `vcs.ref.head.revision` and `chant.*` resource attributes alone: `insert` rather than `upsert`, and `override: false` on `resourcedetection` (OTEL118).
 - Declared extensions are enabled in declaration order unless a `Service` lists `extensions` itself.
 
 ## Starting from an existing config
@@ -97,4 +101,4 @@ The importer writes `receivers.ts`, `processors.ts`, `exporters.ts`, `connectors
 
 ## Reading the result
 
-`collectorTopologyOf(entities)` returns the pipelines, each component's endpoints and schema pin, for each exporter the signals it carries, the connector `edges` between pipelines, and under `semconv` the semantic-conventions version (`GENAI_SEMCONV_PIN`) the config's `gen_ai.` keys follow, as plain data.
+`collectorTopologyOf(entities)` returns the pipelines, each component's endpoints and schema pin, for each exporter the signals it carries, the connector `edges` between pipelines, and under `semconv` the semantic-conventions version the config's `gen_ai.` keys (`GENAI_SEMCONV_PIN`) and `k8s.` keys (`SEMCONV_PIN`) follow, as plain data.

package/src/validate-config.ts

@@ -11,11 +11,12 @@
 import type { Declarable } from "@intentius/chant/declarable";
 import { definitionFor, definitionOf, isOTelComponent, isUsablePin, runValidator } from "./define";
 import { componentConfig } from "./collector";
-import { isComponentId, parseComponentId, pipelineSignal, SIGNALS, type CollectorConfig, type ConnectorSignalPair } from "./model";
+import { canonicalComponentType, isComponentId, parseComponentId, pipelineSignal, SIGNALS, type CollectorConfig, type ConnectorSignalPair } from "./model";
 import { isPipelineEntity } from "./pipeline";
 import { signalToMetricsEntries, type SignalToMetricsConnectorConfig } from "./components/connectors";
 import { genAiCardinalityRisk } from "./genai";
 import { collectorTopology, type TopologyEdge } from "./topology";
+import { configHygieneIssues } from "./config-hygiene";
 // OTEL112 reads the built-in connectors' signal pairs from the registry.
 import "./components/connectors";
 
@@ -34,7 +35,17 @@ export type CollectorIssueCode =
   | "OTEL114"
   | "OTEL115"
   | "OTEL116"
-  | "OTEL117";
+  | "OTEL117"
+  | "OTEL118"
+  | "OTEL119"
+  | "OTEL120"
+  | "OTEL121"
+  | "OTEL122"
+  | "OTEL123"
+  | "OTEL124"
+  | "OTEL125"
+  | "OTEL126"
+  | "OTEL127";
 
 export interface CollectorIssue {
   code: CollectorIssueCode;
@@ -67,8 +78,9 @@ function describePairs(pairs: ReadonlyArray<ConnectorSignalPair>): string {
  * each connector's signals against its definition (OTEL112), cycles through
  * connectors (OTEL113), connector ids shared with a receiver or exporter
  * (OTEL114), `routing` connector targets (OTEL115), the attributes
- * connectors split metrics by (OTEL116), and started components that listen
- * on the same address (OTEL117).
+ * connectors split metrics by (OTEL116), started components that listen
+ * on the same address (OTEL117), and the deprecation, exposure, delivery and
+ * name-list checks in `config-hygiene.ts` (OTEL119-OTEL127).
  */
 export function validateCollectorConfig(config: CollectorConfig): CollectorIssue[] {
   const issues: CollectorIssue[] = [];
@@ -229,6 +241,7 @@ export function validateCollectorConfig(config: CollectorConfig): CollectorIssue
     ...routingTargetIssues(config),
     ...metricAttributeIssues(config),
     ...listenerIssues(config),
+    ...configHygieneIssues(config),
   );
 
   return issues;
@@ -449,7 +462,7 @@ function metricAttributeUses(type: string, config: Record<string, unknown>): Met
 function metricAttributeIssues(config: CollectorConfig): CollectorIssue[] {
   const issues: CollectorIssue[] = [];
   for (const [id, raw] of Object.entries(config.connectors ?? {})) {
-    const type = parseComponentId(id)?.type ?? id;
+    const type = canonicalComponentType("connector", parseComponentId(id)?.type ?? id);
     const body = typeof raw === "object" && raw !== null ? (raw as Record<string, unknown>) : {};
     for (const { key, field } of metricAttributeUses(type, body)) {
       const risk = genAiCardinalityRisk(key);
@@ -470,7 +483,7 @@ function metricAttributeIssues(config: CollectorConfig): CollectorIssue[] {
 }
 
 /** One address a started component listens on. */
-interface Listener {
+export interface Listener {
   /** Who listens: `receiver "otlp" (protocols.grpc.endpoint)`. */
   owner: string;
   component?: string;
@@ -486,12 +499,14 @@ interface Listener {
  * default applies only when the key's parent is in the config: an otlp or
  * jaeger protocol that isn't listed doesn't start. A type not listed here is
  * not checked, since its `endpoint` may be a server it connects to (the
- * kubeletstats receiver's is the kubelet).
+ * kubeletstats receiver's is the kubelet). `transportKey` names a sibling key
+ * that switches the transport (`transport: udp` on carbon).
  */
 interface ListenerSpec {
   path: string[];
   default?: string;
   transport?: "udp";
+  transportKey?: string;
   present?: boolean;
 }
 
@@ -508,6 +523,38 @@ const LISTENERS: Record<"receiver" | "exporter" | "extension", Record<string, Li
       { path: ["protocols", "thrift_binary", "endpoint"], default: "localhost:6832", present: true, transport: "udp" },
       { path: ["protocols", "thrift_compact", "endpoint"], default: "localhost:6831", present: true, transport: "udp" },
     ],
+    opencensus: [{ path: ["endpoint"], default: "localhost:55678" }],
+    otelarrow: [{ path: ["protocols", "grpc", "endpoint"], default: "0.0.0.0:4317" }],
+    skywalking: [
+      { path: ["protocols", "grpc", "endpoint"], default: "localhost:11800", present: true },
+      { path: ["protocols", "http", "endpoint"], default: "localhost:12800", present: true },
+    ],
+    loki: [
+      { path: ["protocols", "grpc", "endpoint"], default: "localhost:3600", present: true },
+      { path: ["protocols", "http", "endpoint"], default: "localhost:3500", present: true },
+    ],
+    statsd: [{ path: ["endpoint"], default: "localhost:8125", transport: "udp", transportKey: "transport" }],
+    carbon: [{ path: ["endpoint"], default: "localhost:2003", transportKey: "transport" }],
+    awsxray: [{ path: ["endpoint"], default: "localhost:2000", transport: "udp", transportKey: "transport" }],
+    collectd: [{ path: ["endpoint"], default: "localhost:8081" }],
+    datadog: [{ path: ["endpoint"], default: "localhost:8126" }],
+    influxdb: [{ path: ["endpoint"], default: "localhost:8086" }],
+    signalfx: [{ path: ["endpoint"], default: "localhost:9943" }],
+    splunk_hec: [{ path: ["endpoint"], default: "localhost:8088" }],
+    sapm: [{ path: ["endpoint"], default: "localhost:7276" }],
+    wavefront: [{ path: ["endpoint"], default: "localhost:2003" }],
+    prometheusremotewrite: [{ path: ["endpoint"], default: "localhost:9090" }],
+    awsfirehose: [{ path: ["endpoint"], default: "localhost:4433" }],
+    faro: [{ path: ["endpoint"], default: "localhost:8080" }],
+    libhoney: [{ path: ["http", "endpoint"], default: "localhost:8080" }],
+    fluentforward: [{ path: ["endpoint"] }],
+    webhookevent: [{ path: ["endpoint"] }],
+    tcplog: [{ path: ["listen_address"] }],
+    udplog: [{ path: ["listen_address"], transport: "udp" }],
+    syslog: [
+      { path: ["tcp", "listen_address"], present: true },
+      { path: ["udp", "listen_address"], present: true, transport: "udp" },
+    ],
   },
   exporter: {
     prometheus: [{ path: ["endpoint"] }],
@@ -519,6 +566,34 @@ const LISTENERS: Record<"receiver" | "exporter" | "extension", Record<string, Li
   },
 };
 
+/** A config key path a component listens on, and the transport it listens with. */
+export interface ListenerPath {
+  path: string[];
+  transport: "tcp" | "udp";
+}
+
+/** The transport a spec listens with in this component config: its `transportKey` value, else its default. */
+function specTransport(spec: ListenerSpec, body: unknown): "tcp" | "udp" {
+  if (spec.transportKey && typeof body === "object" && body !== null) {
+    const value = (body as Record<string, unknown>)[spec.transportKey];
+    if (typeof value === "string" && /^udp[46]?$/.test(value)) return "udp";
+    if (typeof value === "string" && /^tcp[46]?$/.test(value)) return "tcp";
+  }
+  return spec.transport ?? "tcp";
+}
+
+/**
+ * The config key paths to the addresses a receiver or exporter of this type
+ * listens on, from the table OTEL117 checks, with the transport each listens
+ * with in `body`. Empty for a type not in the table, whose `endpoint` may be
+ * a server it connects to. `collectorEndpoints` reads the ports from here, so
+ * the ports a platform composite publishes and the listeners OTEL117 compares
+ * are the same set.
+ */
+export function listenerPaths(kind: "receiver" | "exporter", type: string, body: unknown): ListenerPath[] {
+  return (LISTENERS[kind][type] ?? []).map((spec) => ({ path: spec.path, transport: specTransport(spec, body) }));
+}
+
 /** The collector's own metrics endpoint when `service.telemetry.metrics` names no reader. */
 const DEFAULT_TELEMETRY_METRICS = { host: "localhost", port: 8888 };
 
@@ -540,7 +615,8 @@ function at(value: unknown, path: string[]): { found: boolean; value: unknown }
   return { found: true, value: cur };
 }
 
-function componentListeners(kind: "receiver" | "exporter" | "extension", id: string, body: unknown): Listener[] {
+/** The addresses a component of this kind listens on, from the OTEL117 table and its defaults. */
+export function componentListeners(kind: "receiver" | "exporter" | "extension", id: string, body: unknown): Listener[] {
   const type = parseComponentId(id)?.type ?? id;
   const out: Listener[] = [];
   for (const spec of LISTENERS[kind][type] ?? []) {
@@ -548,7 +624,7 @@ function componentListeners(kind: "receiver" | "exporter" | "extension", id: str
     const { found, value } = at(body, spec.path);
     const address = splitAddress(found && value !== undefined && value !== null ? value : spec.default);
     if (!address) continue;
-    out.push({ owner: `${kind} "${id}" (${spec.path.join(".")})`, component: id, ...address, transport: spec.transport ?? "tcp" });
+    out.push({ owner: `${kind} "${id}" (${spec.path.join(".")})`, component: id, ...address, transport: specTransport(spec, body) });
   }
   return out;
 }