@intentius/chant-lexicon-otel 0.106.4 → 0.108.0

package/src/composites/tail-sampling-tier.ts

@@ -0,0 +1,182 @@
+/**
+ * `TailSamplingTier`: the collector config of a tail sampling tier on any
+ * host (VMs, Docker, Fly, ECS), for where the k8s lexicon's
+ * `OtelCollectorGateway` does not run.
+ *
+ * Tail sampling needs every span of a trace in one collector. The agents in
+ * front send to this tier through a `loadbalancing` exporter that routes by
+ * trace id (`tailSamplingLoadBalancer()` declares it), and each replica of
+ * the tier holds a trace for `decisionWait`, then keeps it when a policy
+ * says so:
+ *
+ * - `errors`: any span ended in error (default: on);
+ * - `slowerThanMs`: the trace took at least this long (default 1000 ms);
+ * - `percentage`: a baseline share of everything else (default 10%);
+ * - `policies`: more `tail_sampling` policies of your own, after those.
+ *
+ * The pipeline is `otlp` in, `memory_limiter`, `tail_sampling`, `batch`, the
+ * given exporters out. Compute span metrics before this tier (the agents, or
+ * `RedMetrics`), or they count only the traces kept.
+ */
+
+import { Composite, type CompositeInstance } from "@intentius/chant/composite";
+import { goDurationMs, type Duration } from "../components/common";
+import { OtlpReceiver } from "../components/receivers";
+import { BatchProcessor, MemoryLimiterProcessor } from "../components/processors";
+import { DebugExporter } from "../components/exporters";
+import { HealthCheckExtension } from "../components/extensions";
+import {
+  LoadBalancingExporter,
+  TailSamplingProcessor,
+  type LoadBalancingExporterConfig,
+  type LoadBalancingResolver,
+  type TailSamplingPolicy,
+  type TailSamplingProcessorConfig,
+} from "../components/sampling";
+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>;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type TraceSource = OTelComponent<"receiver" | "connector", string, any>;
+type Component<K extends "receiver" | "processor" | "exporter" | "extension"> = OTelComponent<K, string, object>;
+
+export interface TailSamplingTierProps {
+  /** Where the kept traces go. Default: one `debug` exporter at `basic` verbosity. */
+  exporters?: Exporter[];
+  /** Where spans come from. Default: an `otlp` receiver on 4317 (gRPC) and 4318 (HTTP). */
+  receivers?: TraceSource[];
+  /** How long after a trace's first span the decision is made (default `10s`). */
+  decisionWait?: Duration;
+  /** Keep every trace with a span ended in error (default: on). */
+  errors?: boolean;
+  /** Keep every trace that took at least this many milliseconds (default 1000; `false` for none). */
+  slowerThanMs?: number | false;
+  /** Keep this percentage of all other traces, by trace id hash (default 10; `false` for none). */
+  percentage?: number | false;
+  /** More policies, evaluated after the ones above. */
+  policies?: TailSamplingPolicy[];
+  /** How many traces to hold in memory at once (default: the collector's 50000). */
+  numTraces?: number;
+  /** `memory_limiter`'s hard limit in MiB (default: 80% of the container's memory, with a 20% spike limit). */
+  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 TailSamplingTierMembers = {
+  otlp?: Component<"receiver">;
+  memoryLimiter: Component<"processor">;
+  tailSampling: OTelComponent<"processor", "tail_sampling", TailSamplingProcessorConfig>;
+  batch: Component<"processor">;
+  /** The default `debug` exporter, when no `exporters` are given. */
+  debug?: Component<"exporter">;
+  health?: Component<"extension">;
+  traces: PipelineEntity;
+};
+
+export type TailSamplingTierInstance = CompositeInstance<TailSamplingTierMembers> & TailSamplingTierMembers;
+
+/** Why a set of `TailSamplingTier` props can't build, or undefined when they can. */
+export function tailSamplingTierPropsProblem(props: TailSamplingTierProps = {}): string | undefined {
+  if (props.exporters !== undefined && props.exporters.length === 0) return "exporters must name at least one exporter when set";
+  if (props.receivers !== undefined && props.receivers.length === 0) return "receivers must name at least one receiver when set";
+  if (props.decisionWait !== undefined) {
+    const ms = goDurationMs(props.decisionWait, 0);
+    if (ms === undefined || ms <= 0) return `decisionWait ${JSON.stringify(props.decisionWait)} is not a positive duration`;
+  }
+  const s = props.slowerThanMs;
+  if (s !== undefined && s !== false && !(Number.isInteger(s) && s > 0)) return "slowerThanMs must be a positive whole number of milliseconds, or false";
+  const pc = props.percentage;
+  if (pc !== undefined && pc !== false && !(typeof pc === "number" && pc > 0 && pc <= 100)) return "percentage must be above 0 and at most 100, or false";
+  if (props.numTraces !== undefined && !(Number.isInteger(props.numTraces) && props.numTraces > 0)) return "numTraces must be a positive whole number";
+  if (props.memoryLimitMib !== undefined && !(Number.isInteger(props.memoryLimitMib) && props.memoryLimitMib > 0)) {
+    return "memoryLimitMib must be a positive whole number";
+  }
+  if (tierPolicies(props).length === 0) return "every policy is off, so no trace would ever be kept";
+  return undefined;
+}
+
+function tierPolicies(props: TailSamplingTierProps): TailSamplingPolicy[] {
+  const out: TailSamplingPolicy[] = [];
+  if (props.errors !== false) out.push({ name: "errors", type: "status_code", status_code: { status_codes: ["ERROR"] } });
+  const slow = props.slowerThanMs ?? 1000;
+  if (slow !== false) out.push({ name: "slow", type: "latency", latency: { threshold_ms: slow } });
+  const pc = props.percentage ?? 10;
+  if (pc !== false) out.push({ name: "baseline", type: "probabilistic", probabilistic: { sampling_percentage: pc } });
+  return [...out, ...(props.policies ?? [])];
+}
+
+/**
+ * The collector config of a tail sampling tier: whole traces in, the ones
+ * a policy keeps out.
+ *
+ * @example
+ * ```ts
+ * import { TailSamplingTier, OtlpExporter } from "@intentius/chant-lexicon-otel";
+ *
+ * const tempo = new OtlpExporter({ name: "tempo", endpoint: "tempo:4317", tls: { insecure: true } });
+ * export const sampler = TailSamplingTier({ exporters: [tempo], slowerThanMs: 500, percentage: 5 });
+ * ```
+ */
+export const TailSamplingTier = Composite<TailSamplingTierProps, TailSamplingTierMembers>((input) => {
+  const props = input ?? {};
+  const problem = tailSamplingTierPropsProblem(props);
+  if (problem) throw new Error(`TailSamplingTier: ${problem}`);
+
+  const otlp = props.receivers
+    ? undefined
+    : new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:4317" }, http: { endpoint: "0.0.0.0:4318" } } });
+  const memoryLimiter = new MemoryLimiterProcessor(
+    props.memoryLimitMib !== undefined
+      ? { check_interval: "1s", limit_mib: props.memoryLimitMib, spike_limit_mib: Math.ceil(props.memoryLimitMib / 4) }
+      : { check_interval: "1s", limit_percentage: 80, spike_limit_percentage: 20 },
+  );
+  const tailSampling = new TailSamplingProcessor({
+    decision_wait: props.decisionWait ?? "10s",
+    ...(props.numTraces !== undefined ? { num_traces: props.numTraces } : {}),
+    policies: tierPolicies(props),
+  });
+  const batch = new BatchProcessor({});
+  const debug = props.exporters ? undefined : new DebugExporter({ verbosity: "basic" });
+  const traces = new Pipeline({
+    signal: "traces",
+    receivers: props.receivers ?? [otlp!],
+    processors: [memoryLimiter, tailSampling, batch],
+    exporters: props.exporters ?? [debug!],
+  });
+  const health = props.healthCheck === false ? undefined : new HealthCheckExtension({ endpoint: "0.0.0.0:13133" });
+
+  // A composite member must be a declarable, so the parts that are off are left out rather than undefined.
+  const members: TailSamplingTierMembers = { memoryLimiter, tailSampling, batch, traces };
+  if (otlp) members.otlp = otlp;
+  if (debug) members.debug = debug;
+  if (health) members.health = health;
+  return members;
+}, "TailSamplingTier");
+
+/**
+ * The exporter the agents in front of a `TailSamplingTier` send traces with:
+ * a `loadbalancing` exporter that routes every span of a trace to the same
+ * replica of the tier, by trace id.
+ *
+ * @example
+ * ```ts
+ * // TLS by default; pass `{ otlp: { tls: { insecure: true } } }` as `protocol` on a private network.
+ * const toSampler = tailSamplingLoadBalancer({ dns: { hostname: "sampler.internal" } }, "sampler");
+ * ```
+ */
+export function tailSamplingLoadBalancer(
+  resolver: LoadBalancingResolver,
+  name?: string,
+  protocol?: LoadBalancingExporterConfig["protocol"],
+): OTelComponent<"exporter", "loadbalancing", LoadBalancingExporterConfig> {
+  return new LoadBalancingExporter({
+    ...(name !== undefined ? { name } : {}),
+    routing_key: "traceID",
+    ...(protocol !== undefined ? { protocol } : {}),
+    resolver,
+  });
+}

package/src/configmap-operator.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "vitest";
+import { collectorConfig, describeOperatorCollectorConfig, operatorCollectorConfig } from "./index";
+import { OtlpReceiver, DebugExporter, Pipeline } from "./index";
+
+const config = {
+  receivers: { otlp: { protocols: { grpc: {} } } },
+  exporters: { debug: {} },
+  service: { pipelines: { traces: { receivers: ["otlp"], exporters: ["debug"] } } },
+};
+
+const cr = (spec: unknown, apiVersion = "opentelemetry.io/v1beta1") => ({
+  apiVersion,
+  kind: "OpenTelemetryCollector",
+  metadata: { name: "gw", namespace: "obs" },
+  spec,
+});
+
+describe("operatorCollectorConfig (#3367)", () => {
+  test("reads spec.config as an object (v1beta1) or as YAML text (v1alpha1)", () => {
+    expect(operatorCollectorConfig(cr({ config }))).toEqual({ namespace: "obs", name: "gw", config });
+    const text = "receivers: { otlp: {} }\nexporters: { debug: {} }\nservice:\n  pipelines:\n    traces: { receivers: [otlp], exporters: [debug] }\n";
+    const old = operatorCollectorConfig(cr({ config: text }, "opentelemetry.io/v1alpha1"));
+    expect(old?.config.service?.pipelines?.traces).toEqual({ receivers: ["otlp"], exporters: ["debug"] });
+  });
+
+  test("defaults the namespace and skips other kinds, other groups and configs without pipelines", () => {
+    expect(operatorCollectorConfig({ ...cr({ config }), metadata: { name: "x" } })?.namespace).toBe("default");
+    expect(operatorCollectorConfig({ ...cr({ config }), kind: "Deployment" })).toBeUndefined();
+    expect(operatorCollectorConfig(cr({ config }, "example.com/v1"))).toBeUndefined();
+    expect(operatorCollectorConfig(cr({ config: { receivers: {} } }))).toBeUndefined();
+    expect(operatorCollectorConfig(cr({}))).toBeUndefined();
+  });
+
+  test("describes the CR in a message", () => {
+    expect(describeOperatorCollectorConfig({ namespace: "obs", name: "gw" })).toBe("OpenTelemetryCollector obs/gw, spec.config");
+  });
+});
+
+describe("collectorConfig", () => {
+  test("is the config object collectorYaml prints", () => {
+    const entities = [new Pipeline({ signal: "traces", receivers: [new OtlpReceiver({ protocols: { grpc: {} } })], exporters: [new DebugExporter({})] })];
+    expect(collectorConfig(entities).service?.pipelines?.traces).toEqual({ receivers: ["otlp"], exporters: ["debug"] });
+  });
+});

package/src/configmap.ts

@@ -65,3 +65,38 @@ export function configMapCollectorConfigs(doc: unknown): ConfigMapCollectorConfi
 export function describeConfigMapConfig(c: Pick<ConfigMapCollectorConfig, "namespace" | "name" | "key">): string {
   return `ConfigMap ${c.namespace}/${c.name}, key ${c.key}`;
 }
+
+/** One collector config found in an OpenTelemetry Operator `OpenTelemetryCollector`. */
+export interface OperatorCollectorConfig {
+  /** `metadata.namespace`, or `default` when unset. */
+  namespace: string;
+  name: string;
+  config: CollectorConfig;
+}
+
+/**
+ * The collector config in one parsed manifest when it is an OpenTelemetry
+ * Operator `OpenTelemetryCollector`: `spec.config`, an object in v1beta1 and
+ * YAML text in v1alpha1. Undefined for any other document, and for a config
+ * without a `service.pipelines` map.
+ */
+export function operatorCollectorConfig(doc: unknown): OperatorCollectorConfig | undefined {
+  if (!isRecord(doc) || doc.kind !== "OpenTelemetryCollector") return undefined;
+  if (typeof doc.apiVersion !== "string" || !doc.apiVersion.startsWith("opentelemetry.io/")) return undefined;
+  const metadata = isRecord(doc.metadata) ? doc.metadata : {};
+  if (typeof metadata.name !== "string") return undefined;
+  const raw = isRecord(doc.spec) ? doc.spec.config : undefined;
+  const config = isRecord(raw)
+    ? isRecord(raw.service) && isRecord(raw.service.pipelines)
+      ? (raw as unknown as CollectorConfig)
+      : undefined
+    : parseCollectorConfig(raw);
+  if (!config) return undefined;
+  const namespace = typeof metadata.namespace === "string" && metadata.namespace.length > 0 ? metadata.namespace : "default";
+  return { namespace, name: metadata.name, config };
+}
+
+/** How an operator CR's config is named in a message: `OpenTelemetryCollector observability/gateway, spec.config`. */
+export function describeOperatorCollectorConfig(c: Pick<OperatorCollectorConfig, "namespace" | "name">): string {
+  return `OpenTelemetryCollector ${c.namespace}/${c.name}, spec.config`;
+}

package/src/detect.ts

@@ -7,5 +7,17 @@
 import { looksLikeCollectorConfig } from "./model";
 
 export function detectTemplate(data: unknown): boolean {
-  return looksLikeCollectorConfig(data);
+  return looksLikeCollectorConfig(data) || isObjectConfigOffer(data);
+}
+
+/**
+ * The `{ config, header }` document a host offers for a config it holds as an
+ * object, such as an OpenTelemetryCollector's `spec.config` (#3367). `chant
+ * import` asks this module which lexicons own what a host offered, so the
+ * wrapper has to be recognised here as well as by the importer.
+ */
+function isObjectConfigOffer(data: unknown): boolean {
+  if (typeof data !== "object" || data === null || Array.isArray(data)) return false;
+  const keys = Object.keys(data);
+  return keys.includes("config") && keys.every((k) => k === "config" || k === "header") && looksLikeCollectorConfig((data as { config?: unknown }).config);
 }

package/src/genai.ts

@@ -63,7 +63,7 @@ import {
   type SumConnectorConfig,
 } from "./components/connectors";
 import type { Duration } from "./components/common";
-import { Pipeline } from "./pipeline";
+import { Pipeline, type PipelineEntity } from "./pipeline";
 import { prometheusMetricName, SPANMETRICS_DEFAULT_DIMENSIONS, type CollectorMetric } from "./metric-names";
 
 // ── The GenAI attribute vocabulary, at GENAI_SEMCONV_PIN ─────────────
@@ -677,6 +677,23 @@ export interface GenAiPipelineOptions extends GenAiComponentsOptions {
   deltaToCumulative?: boolean | "auto";
 }
 
+/**
+ * The entities `genAiPipeline()` returns, by name: what the `GenAiPipeline`
+ * composite's members are. A key is absent when its part is off: `sampled`
+ * without `sampling`, `sdkMetrics` without `clientMetrics`, `logs` with
+ * `logs: false`, `health` with `healthCheck: false`.
+ */
+export type GenAiPipelineParts = {
+  otlp: Declarable;
+  traces: PipelineEntity;
+  sampled?: PipelineEntity;
+  genAiTraces: PipelineEntity;
+  genAiMetrics: PipelineEntity;
+  sdkMetrics?: PipelineEntity;
+  logs?: PipelineEntity;
+  health?: Declarable;
+};
+
 /**
  * The entities of an OTLP collector for GenAI workloads: an `otlp` receiver
  * on 4317 and 4318; `memory_limiter`, content removal and `batch` on traces
@@ -686,6 +703,11 @@ export interface GenAiPipelineOptions extends GenAiComponentsOptions {
  * pieces into pipelines of your own.
  */
 export function genAiPipeline(options: GenAiPipelineOptions = {}): Declarable[] {
+  return Object.values(genAiPipelineParts(options)) as Declarable[];
+}
+
+/** `genAiPipeline()`'s entities by name, in the order it returns them. */
+export function genAiPipelineParts(options: GenAiPipelineOptions = {}): GenAiPipelineParts {
   const debug = new DebugExporter({ verbosity: "basic" });
   const { traceExporters = [debug], metricExporters = [debug], logExporters = [debug], logs = true, sampling = [], healthCheck = true } =
     options;
@@ -709,73 +731,64 @@ export function genAiPipeline(options: GenAiPipelineOptions = {}): Declarable[]
     spike_limit_percentage: 20,
   });
   const batch = new BatchProcessor({});
-  const entities: Declarable[] = [otlp];
+  // Insertion order is the order genAiPipeline() has always returned.
+  const out: Partial<GenAiPipelineParts> = { otlp };
 
   if (sampling.length === 0) {
-    entities.push(
-      new Pipeline({
-        signal: "traces",
-        receivers: [otlp],
-        processors: [memoryLimiter, ...parts.processors, batch],
-        exporters: [...traceExporters, parts.forward],
-      }),
-    );
+    out.traces = new Pipeline({
+      signal: "traces",
+      receivers: [otlp],
+      processors: [memoryLimiter, ...parts.processors, batch],
+      exporters: [...traceExporters, parts.forward],
+    });
   } else {
     const sampled = new ForwardConnector({ name: "sampled" });
-    entities.push(
-      new Pipeline({
-        signal: "traces",
-        receivers: [otlp],
-        processors: [memoryLimiter, ...parts.processors],
-        exporters: [parts.forward, sampled],
-      }),
-      new Pipeline({
-        signal: "traces",
-        name: "sampled",
-        receivers: [sampled],
-        processors: [...sampling, batch],
-        exporters: traceExporters,
-      }),
-    );
-  }
-  entities.push(
-    new Pipeline({
+    out.traces = new Pipeline({
       signal: "traces",
-      name: "genai",
-      receivers: [parts.forward],
-      processors: [parts.genAiSpans],
-      exporters: [parts.spanMetrics, parts.tokenUsage, ...(parts.clientMetrics ? [parts.clientMetrics] : [])],
-    }),
-    new Pipeline({
-      signal: "metrics",
-      name: "genai",
-      receivers: [parts.spanMetrics, parts.tokenUsage, ...(parts.clientMetrics ? [parts.clientMetrics] : [])],
-      processors: [...cumulative, batch],
-      exporters: metricExporters,
-    }),
-  );
+      receivers: [otlp],
+      processors: [memoryLimiter, ...parts.processors],
+      exporters: [parts.forward, sampled],
+    });
+    out.sampled = new Pipeline({
+      signal: "traces",
+      name: "sampled",
+      receivers: [sampled],
+      processors: [...sampling, batch],
+      exporters: traceExporters,
+    });
+  }
+  out.genAiTraces = new Pipeline({
+    signal: "traces",
+    name: "genai",
+    receivers: [parts.forward],
+    processors: [parts.genAiSpans],
+    exporters: [parts.spanMetrics, parts.tokenUsage, ...(parts.clientMetrics ? [parts.clientMetrics] : [])],
+  });
+  out.genAiMetrics = new Pipeline({
+    signal: "metrics",
+    name: "genai",
+    receivers: [parts.spanMetrics, parts.tokenUsage, ...(parts.clientMetrics ? [parts.clientMetrics] : [])],
+    processors: [...cumulative, batch],
+    exporters: metricExporters,
+  });
   if (client) {
     // The SDK's own metrics: the client metrics in passthrough, and the
     // ones no span carries (time to first chunk, gen_ai.server.*) either way.
-    entities.push(
-      new Pipeline({
-        signal: "metrics",
-        receivers: [otlp],
-        processors: [memoryLimiter, ...(parts.sdkClientMetricsFilter ? [parts.sdkClientMetricsFilter] : []), batch],
-        exporters: metricExporters,
-      }),
-    );
+    out.sdkMetrics = new Pipeline({
+      signal: "metrics",
+      receivers: [otlp],
+      processors: [memoryLimiter, ...(parts.sdkClientMetricsFilter ? [parts.sdkClientMetricsFilter] : []), batch],
+      exporters: metricExporters,
+    });
   }
   if (logs) {
-    entities.push(
-      new Pipeline({
-        signal: "logs",
-        receivers: [otlp],
-        processors: [memoryLimiter, ...parts.processors, batch],
-        exporters: logExporters,
-      }),
-    );
+    out.logs = new Pipeline({
+      signal: "logs",
+      receivers: [otlp],
+      processors: [memoryLimiter, ...parts.processors, batch],
+      exporters: logExporters,
+    });
   }
-  if (healthCheck) entities.push(new HealthCheckExtension({ endpoint: "0.0.0.0:13133" }));
-  return entities;
+  if (healthCheck) out.health = new HealthCheckExtension({ endpoint: "0.0.0.0:13133" });
+  return out as GenAiPipelineParts;
 }

package/src/import/embedded.test.ts

@@ -53,4 +53,40 @@ describe("a collector config embedded in another lexicon's resource (#2962)", ()
       through: { from: "@intentius/chant-lexicon-otel", name: "collectorYaml" },
     });
   });
+
+  describe("an object config, from an OpenTelemetryCollector's spec.config (#3367)", () => {
+    const object = (header?: string[]): EmbeddedContent => {
+      const config = embeddedDocument(CONFIG);
+      return site(CONFIG, {
+        hostType: "K8s::OpenTelemetry::OpenTelemetryCollector",
+        location: "OpenTelemetryCollector agent spec.config",
+        text: undefined,
+        document: { config, header },
+        select: "config",
+      });
+    };
+
+    test("matches a { config } document selected as config, and nothing without a collector config in it", () => {
+      expect(collectorConfigImporter.matches(object())).toBe(true);
+      expect(collectorConfigImporter.matches(site(CONFIG, { text: undefined, document: { config: { groups: [] } }, select: "config" }))).toBe(false);
+      expect(collectorConfigImporter.matches(site(CONFIG, { text: undefined, document: { nope: 1 }, select: "config" }))).toBe(false);
+    });
+
+    test("is referenced through collectorConfig, which gives an object", () => {
+      const out = collectorConfigImporter.import(object());
+      expect(out.value.through).toEqual({ from: "@intentius/chant-lexicon-otel", name: "collectorConfig" });
+      expect(out.value.bindings.map((b) => b.name)).toEqual(["otlp", "mycorp", "debug", "traces"]);
+    });
+
+    test("puts the header lines back, so the custom component keeps its pin", () => {
+      const pin = "chant: receiver mycorp schema github.com/mycorp/otel@v1.2.3";
+      const out = collectorConfigImporter.import(object([pin]));
+      const custom = out.files.find((f) => f.path === "custom-components.ts")!.content;
+      expect(custom).toContain("github.com/mycorp/otel");
+      expect(custom).toContain("v1.2.3");
+      const bare = collectorConfigImporter.import(object()).files.find((f) => f.path === "custom-components.ts")!.content;
+      expect(bare).not.toContain("github.com/mycorp/otel");
+    });
+  });
 });
+

package/src/import/embedded.ts

@@ -6,11 +6,20 @@
  * it, into a directory of its own, and the host's value becomes
  * `collectorYaml([...])` over every component, pipeline and service the
  * import declares, which renders the same config text at build time.
+ *
+ * A host that holds the config as an object, the OpenTelemetry Operator's
+ * `OpenTelemetryCollector` `spec.config`, offers it as `{ config, header }`
+ * with `select: "config"`. The config is printed back to the text the
+ * standalone import reads, with the `# chant:` header lines the host kept in
+ * an annotation put back on top so custom-component pins and semconv use
+ * survive. The host's value becomes `collectorConfig([...])`, an object, so
+ * the field keeps the type its CRD gives it.
  */
 
-import type { EmbeddedContentImporter, EmbeddedImport } from "@intentius/chant/import/embedded";
+import type { EmbeddedContent, EmbeddedContentImporter, EmbeddedImport } from "@intentius/chant/import/embedded";
 import { exportedNames } from "@intentius/chant/import/embedded";
-import { looksLikeCollectorConfig } from "../model";
+import { looksLikeCollectorConfig, type CollectorConfig } from "../model";
+import { emitCollectorYaml } from "../yaml";
 import { OtelCollectorParser } from "./parser";
 import { OtelCollectorGenerator } from "./generator";
 
@@ -19,22 +28,37 @@ const PACKAGE = "@intentius/chant-lexicon-otel";
 /** The module holding `defineComponent` classes: types, not config entities. */
 const CUSTOM_COMPONENTS = "custom-components.ts";
 
+function selectedConfig(content: EmbeddedContent): unknown {
+  const doc = content.document;
+  return typeof doc === "object" && doc !== null ? (doc as { config?: unknown }).config : undefined;
+}
+
+/** The text a `{ config, header }` document prints as: the header lines as comments, then the config. */
+function objectConfigText(content: EmbeddedContent): string {
+  const header = (content.document as { header?: unknown }).header;
+  const lines = Array.isArray(header) ? header.filter((l): l is string => typeof l === "string") : [];
+  return emitCollectorYaml(selectedConfig(content) as CollectorConfig, { header: lines });
+}
+
 export const collectorConfigImporter: EmbeddedContentImporter = {
   what: "an OpenTelemetry Collector config",
 
   matches(content) {
+    if (content.select === "config") return looksLikeCollectorConfig(selectedConfig(content));
     return typeof content.text === "string" && content.select === undefined && looksLikeCollectorConfig(content.document);
   },
 
   import(content): EmbeddedImport {
-    const ir = new OtelCollectorParser().parse(content.text!);
+    const asObject = content.select === "config";
+    const text = asObject ? objectConfigText(content) : content.text!;
+    const ir = new OtelCollectorParser().parse(text);
     const files = new OtelCollectorGenerator().generate(ir);
     const bindings = files
       .filter((f) => f.path !== CUSTOM_COMPONENTS)
       .flatMap((f) => exportedNames(f.content).map((name) => ({ from: f.path, name })));
     return {
       files,
-      value: { bindings, shape: "list", through: { from: PACKAGE, name: "collectorYaml" } },
+      value: { bindings, shape: "list", through: { from: PACKAGE, name: asObject ? "collectorConfig" : "collectorYaml" } },
       warnings: ir.warnings ?? [],
     };
   },

package/src/index.ts

@@ -46,9 +46,17 @@ export {
 
 // The plain-data model, YAML, checks and topology
 export * from "./model";
-export { buildCollectorConfig, collectorYaml, componentConfig, type BuiltCollector } from "./collector";
+export { buildCollectorConfig, collectorConfig, collectorYaml, componentConfig, type BuiltCollector } from "./collector";
 export { emitCollectorYaml, type EmitOptions } from "./yaml";
-export { configMapCollectorConfigs, describeConfigMapConfig, parseCollectorConfig, type ConfigMapCollectorConfig } from "./configmap";
+export {
+  configMapCollectorConfigs,
+  describeConfigMapConfig,
+  describeOperatorCollectorConfig,
+  operatorCollectorConfig,
+  parseCollectorConfig,
+  type ConfigMapCollectorConfig,
+  type OperatorCollectorConfig,
+} from "./configmap";
 export {
   validateCollectorConfig,
   validateCollectorEntities,
@@ -71,14 +79,40 @@ export { attributionIssues, isProtectedResourceAttribute, PROTECTED_RESOURCE_ATT
 
 // Composites
 export { NodeAgent, nodeAgentPropsProblem, type NodeAgentProps, type NodeAgentMembers, type NodeAgentInstance } from "./composites";
+export {
+  RedMetrics,
+  redMetricsNames,
+  redMetricsPropsProblem,
+  GenAiPipeline,
+  OtlpCollector,
+  otlpCollectorPropsProblem,
+  TailSamplingTier,
+  tailSamplingTierPropsProblem,
+  tailSamplingLoadBalancer,
+  type RedMetricsProps,
+  type RedMetricsMembers,
+  type RedMetricsInstance,
+  type RedMetricsNames,
+  type GenAiPipelineProps,
+  type GenAiPipelineMembers,
+  type GenAiPipelineInstance,
+  type OtlpCollectorProps,
+  type OtlpCollectorMembers,
+  type OtlpCollectorInstance,
+  type TailSamplingTierProps,
+  type TailSamplingTierMembers,
+  type TailSamplingTierInstance,
+} from "./composites";
 
 // What the platform collector composites (docker, k8s, fly) share
 export {
   otlpCollector,
+  otlpCollectorParts,
   collectorEndpoints,
   COLLECTOR_IMAGE,
   COLLECTOR_CONFIG_PATH,
   type OtlpCollectorOptions,
+  type OtlpCollectorParts,
   type CollectorPort,
   type CollectorEndpoints,
 } from "./platform";
@@ -86,6 +120,7 @@ export {
 // The GenAI preset: content removal and agent RED and token metrics
 export {
   genAiPipeline,
+  genAiPipelineParts,
   genAiComponents,
   genAiMetrics,
   GENAI_ATTRIBUTES,
@@ -107,6 +142,7 @@ export {
   DELTA_READY_EXPORTERS,
   genAiNeedsDeltaToCumulative,
   type GenAiPipelineOptions,
+  type GenAiPipelineParts,
   type GenAiComponentsOptions,
   type GenAiComponents,
   type GenAiMetricsOptions,
@@ -132,4 +168,23 @@ export {
   type SpanMetricsNames,
   type SpanMetricsNamingConfig,
   type PrometheusNaming,
+  promSelector,
+  promSumRate,
+  promErrorRatio,
+  promQuantile,
+  promNumber,
+  spanKindMatchers,
+  spanMetricsRedQueries,
+  SPAN_METRICS_KINDS,
+  RED_DEFAULT_SPAN_KINDS,
+  type PromMatcher,
+  type SpanMetricsKind,
+  type RedQueryOptions,
+  type RedQueries,
 } from "./metric-names";
+
+// Op steps (#3369): the collector binary's checks, collectors as resources a
+// ConvergeOp observes, and the pin audit. The activities resolve from
+// `@intentius/chant-lexicon-otel/op/activities`.
+export { otelcolValidate, otelcolComponents, collectorHealthObserve, collectorAudit } from "./op/builders";
+export { CollectorAuditOp, type CollectorAuditOpConfig, type CollectorAuditOpResources } from "./op/audit-op";