@intentius/chant-lexicon-otel 0.124.31 → 0.124.33

package/dist/genai.js

@@ -0,0 +1,569 @@
+/**
+ * A collector preset for workloads that emit OpenTelemetry GenAI spans:
+ * content removal, and agent RED and token metrics.
+ *
+ * Attribute keys follow `GENAI_SEMCONV_PIN`. Content (prompts, completions,
+ * system instructions, tool-call arguments and results, retrieval queries and
+ * documents) is deleted from spans, span events and log records unless the
+ * caller passes `keepContent: true`. A `transform` processor deletes the keys;
+ * `redaction` cannot delete one named key while keeping the rest, so it runs
+ * after the transform as a masking backstop on the same keys and for any
+ * value patterns the caller adds.
+ *
+ * Metrics come from a branch taken before any sampling: the traces pipeline
+ * forwards every span to `traces/genai`, which keeps only spans with a
+ * `gen_ai.operation.name`, and feeds `spanmetrics` (calls, errors and
+ * duration by operation, model, tool and error type) and `sum` (input and
+ * output tokens by model). `spanmetrics` counts spans and
+ * cannot sum an attribute, which is why token usage comes from the `sum`
+ * connector.
+ *
+ * With `clientMetrics: "derive"`, a `signaltometrics` connector on the same
+ * branch also emits the two client metrics the conventions define at the pin,
+ * `gen_ai.client.operation.duration` and `gen_ai.client.token.usage`, under
+ * their own names, attributes, units and buckets. `clientMetrics:
+ * "passthrough"` derives nothing and relies on the SDK to send them. Either
+ * way a `metrics` pipeline passes the SDK's OTLP metrics through. Without the
+ * option the output is what it was before the option existed.
+ *
+ * `sum` emits delta sums. The `prometheus` exporter accumulates them itself,
+ * but `prometheusremotewrite` drops them, and some OTLP backends store only
+ * cumulative data; `signaltometrics` emits delta histograms too.
+ * `deltaToCumulative` puts a `deltatocumulative` processor on `metrics/genai`
+ * for those. It is on by default only with `clientMetrics: "derive"`, so a
+ * config built without either option is unchanged.
+ */
+import { GENAI_SEMCONV_PIN } from "./define.js";
+import { OtlpReceiver } from "./components/receivers.js";
+import { BatchProcessor, DeltaToCumulativeProcessor, MemoryLimiterProcessor } from "./components/processors.js";
+import { DebugExporter } from "./components/exporters.js";
+import { HealthCheckExtension } from "./components/extensions.js";
+import { FilterProcessor, RedactionProcessor, TransformProcessor, } from "./components/filtering.js";
+import { ForwardConnector, SignalToMetricsConnector, SpanMetricsConnector, SumConnector, } from "./components/connectors.js";
+import { Pipeline } from "./pipeline.js";
+import { prometheusMetricName, SPANMETRICS_DEFAULT_DIMENSIONS } from "./metric-names.js";
+// ── The GenAI attribute vocabulary, at GENAI_SEMCONV_PIN ─────────────
+/** GenAI attributes the preset reads. */
+export const GENAI_ATTRIBUTES = Object.freeze({
+    operationName: "gen_ai.operation.name",
+    providerName: "gen_ai.provider.name",
+    requestModel: "gen_ai.request.model",
+    responseModel: "gen_ai.response.model",
+    agentName: "gen_ai.agent.name",
+    toolName: "gen_ai.tool.name",
+    inputTokens: "gen_ai.usage.input_tokens",
+    outputTokens: "gen_ai.usage.output_tokens",
+    /** From the general conventions; GenAI spans set it on failure. */
+    errorType: "error.type",
+    /** A metric attribute only: `input` or `output` on `gen_ai.client.token.usage`. */
+    tokenType: "gen_ai.token.type",
+    /** From the general conventions: the GenAI server's host and port. */
+    serverAddress: "server.address",
+    serverPort: "server.port",
+});
+/**
+ * Attributes that carry content: what users and models said, and what tools
+ * were given and returned. The conventions mark each opt-in and sensitive.
+ * `gen_ai.prompt` and `gen_ai.completion` are deprecated, but older
+ * instrumentation still sets them.
+ */
+export const GENAI_CONTENT_ATTRIBUTES = Object.freeze([
+    "gen_ai.system_instructions",
+    "gen_ai.input.messages",
+    "gen_ai.output.messages",
+    "gen_ai.tool.call.arguments",
+    "gen_ai.tool.call.result",
+    "gen_ai.retrieval.query.text",
+    "gen_ai.retrieval.documents",
+    "gen_ai.prompt",
+    "gen_ai.completion",
+]);
+/**
+ * Indexed content keys some instrumentation libraries write outside the
+ * conventions (`gen_ai.prompt.0.content`, `gen_ai.completion.1.role`). The
+ * index keeps `gen_ai.prompt.name`, a convention attribute, out of it.
+ */
+export const GENAI_INDEXED_CONTENT_PATTERN = "^gen_ai\\.(prompt|completion)\\.[0-9]+\\..+$";
+/**
+ * Attributes that take a new value per response, tool call, conversation,
+ * session or user. As a metric attribute, each one starts new time series
+ * for every value, so OTEL116 reports them (and the content keys above)
+ * wherever a connector splits a metric by one.
+ *
+ * At `GENAI_SEMCONV_PIN` (semantic-conventions v1.41.1) the conventions
+ * define `gen_ai.conversation.id`, `gen_ai.response.id` and
+ * `gen_ai.tool.call.id` in `model/gen-ai/registry.yaml`, `session.id` in
+ * `model/session/registry.yaml`, `user.id` in `model/user/registry.yaml` and
+ * `enduser.id` in `model/enduser/registry.yaml`. None of them is an attribute
+ * of any GenAI metric there (`model/gen-ai/metrics.yaml`).
+ * `gen_ai.request.previous_response.id` and `gen_ai.memory.record.id` are
+ * not at the pin: they come from the unreleased main of
+ * github.com/open-telemetry/semantic-conventions-genai, and are listed
+ * because instrumentation already sets them. Keys added with that pin
+ * (chant #3044) go here too.
+ */
+export const GENAI_HIGH_CARDINALITY_ATTRIBUTES = Object.freeze([
+    "gen_ai.conversation.id",
+    "gen_ai.response.id",
+    "gen_ai.tool.call.id",
+    "gen_ai.request.previous_response.id",
+    "gen_ai.memory.record.id",
+    "session.id",
+    "user.id",
+    "enduser.id",
+]);
+const INDEXED_CONTENT = new RegExp(GENAI_INDEXED_CONTENT_PATTERN);
+/**
+ * Why a key must not be a metric attribute: `"identifier"` for a key in
+ * `GENAI_HIGH_CARDINALITY_ATTRIBUTES`, `"content"` for a content key
+ * (`GENAI_CONTENT_ATTRIBUTES` or the indexed pattern), which is unbounded
+ * and sensitive too. Undefined for any other key.
+ */
+export function genAiCardinalityRisk(key) {
+    if (GENAI_HIGH_CARDINALITY_ATTRIBUTES.includes(key))
+        return "identifier";
+    if (GENAI_CONTENT_ATTRIBUTES.includes(key) || INDEXED_CONTENT.test(key))
+        return "content";
+    return undefined;
+}
+/**
+ * Deprecated content events. Their content is in the log record body, not in
+ * attributes, so the preset deletes `content`, `message` and `tool_calls`
+ * from the body of these events.
+ */
+export const GENAI_CONTENT_EVENTS = Object.freeze([
+    "gen_ai.system.message",
+    "gen_ai.user.message",
+    "gen_ai.assistant.message",
+    "gen_ai.tool.message",
+    "gen_ai.choice",
+]);
+// ── Metrics ──────────────────────────────────────────────────────────
+/** The spanmetrics dimensions the preset adds to service.name, span.name, span.kind and status.code. */
+export const GENAI_SPAN_METRIC_DIMENSIONS = Object.freeze([
+    GENAI_ATTRIBUTES.operationName,
+    GENAI_ATTRIBUTES.requestModel,
+    GENAI_ATTRIBUTES.toolName,
+    GENAI_ATTRIBUTES.errorType,
+]);
+/**
+ * The attribute token sums are split by. One only: the pinned `sum`
+ * connector adds each value once per attribute, so a second one would double
+ * every sum.
+ */
+export const GENAI_TOKEN_DIMENSIONS = Object.freeze([GENAI_ATTRIBUTES.requestModel]);
+/** The model label on token sums for a span that names no model, so its tokens are counted rather than skipped. */
+export const GENAI_UNKNOWN_MODEL = "unknown";
+/** Default duration buckets, sized for model and tool calls rather than HTTP handlers. */
+export const GENAI_DURATION_BUCKETS = Object.freeze([
+    "100ms",
+    "250ms",
+    "500ms",
+    "1s",
+    "2s",
+    "5s",
+    "10s",
+    "20s",
+    "40s",
+    "80s",
+]);
+/**
+ * Dimensions `providerDimensions: true` adds to `genai.calls` and
+ * `genai.duration`. The token sums keep the model alone (see
+ * `GENAI_TOKEN_DIMENSIONS`); `gen_ai.client.token.usage` splits tokens by both.
+ */
+export const GENAI_PROVIDER_DIMENSIONS = Object.freeze([
+    GENAI_ATTRIBUTES.providerName,
+    GENAI_ATTRIBUTES.responseModel,
+]);
+// ── The conventions' client metrics, at GENAI_SEMCONV_PIN ────────────
+/** The client metrics the conventions define that one span carries enough to derive. */
+export const GENAI_CLIENT_METRIC_NAMES = Object.freeze({
+    operationDuration: "gen_ai.client.operation.duration",
+    tokenUsage: "gen_ai.client.token.usage",
+});
+/** The values of `gen_ai.token.type` on `gen_ai.client.token.usage`. */
+export const GENAI_TOKEN_TYPES = Object.freeze({ input: "input", output: "output" });
+/**
+ * The attributes the conventions give both client metrics: required
+ * (`gen_ai.operation.name`, `gen_ai.provider.name`), conditionally required
+ * (`gen_ai.request.model`, `error.type`) and recommended
+ * (`gen_ai.response.model`, `server.address`, `server.port`).
+ * `gen_ai.client.token.usage` adds `gen_ai.token.type`.
+ */
+export const GENAI_CLIENT_METRIC_ATTRIBUTES = Object.freeze([
+    GENAI_ATTRIBUTES.operationName,
+    GENAI_ATTRIBUTES.providerName,
+    GENAI_ATTRIBUTES.requestModel,
+    GENAI_ATTRIBUTES.responseModel,
+    GENAI_ATTRIBUTES.serverAddress,
+    GENAI_ATTRIBUTES.serverPort,
+    GENAI_ATTRIBUTES.errorType,
+]);
+/** The bucket boundaries the conventions advise for `gen_ai.client.operation.duration`, in seconds. */
+export const GENAI_CLIENT_DURATION_BUCKETS = Object.freeze([
+    0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56, 5.12, 10.24, 20.48, 40.96, 81.92,
+]);
+/** The bucket boundaries the conventions advise for `gen_ai.client.token.usage`, in tokens. */
+export const GENAI_CLIENT_TOKEN_BUCKETS = Object.freeze([
+    1, 4, 16, 64, 256, 1024, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864,
+]);
+const DEFAULT_NAMESPACE = "genai";
+/**
+ * The metrics `genAiPipeline()` emits for the given options: names,
+ * Prometheus names and dimensions. A dashboard reads this instead of
+ * repeating the names, so renaming the namespace moves the panels with it.
+ */
+export function genAiMetrics(options = {}) {
+    const ns = options.namespace ?? DEFAULT_NAMESPACE;
+    const spanDims = [
+        ...SPANMETRICS_DEFAULT_DIMENSIONS,
+        ...spanMetricDimensions(options).map((d) => d.name),
+    ];
+    const tokenDims = [...GENAI_TOKEN_DIMENSIONS];
+    const source = clientMetricsSource(options);
+    return {
+        calls: { name: `${ns}.calls`, prometheus: prometheusMetricName(`${ns}.calls`, "sum"), type: "sum", dimensions: spanDims },
+        duration: {
+            name: `${ns}.duration`,
+            prometheus: prometheusMetricName(`${ns}.duration`, "histogram", "s"),
+            type: "histogram",
+            unit: "s",
+            dimensions: spanDims,
+        },
+        inputTokens: {
+            name: `${ns}.tokens.input`,
+            prometheus: prometheusMetricName(`${ns}.tokens.input`, "sum"),
+            type: "sum",
+            dimensions: tokenDims,
+        },
+        outputTokens: {
+            name: `${ns}.tokens.output`,
+            prometheus: prometheusMetricName(`${ns}.tokens.output`, "sum"),
+            type: "sum",
+            dimensions: tokenDims,
+        },
+        ...(source ? { client: clientMetrics(source) } : {}),
+    };
+}
+function clientMetricsSource(options) {
+    const source = options.clientMetrics;
+    if (source === undefined)
+        return undefined;
+    if (source !== "derive" && source !== "passthrough") {
+        throw new Error(`genAi: clientMetrics must be "derive" or "passthrough", got ${JSON.stringify(source)}`);
+    }
+    return source;
+}
+function clientMetrics(source) {
+    const { operationDuration, tokenUsage } = GENAI_CLIENT_METRIC_NAMES;
+    return {
+        source,
+        operationDuration: {
+            name: operationDuration,
+            prometheus: prometheusMetricName(operationDuration, "histogram", "s"),
+            type: "histogram",
+            unit: "s",
+            dimensions: [...GENAI_CLIENT_METRIC_ATTRIBUTES],
+        },
+        tokenUsage: {
+            name: tokenUsage,
+            prometheus: prometheusMetricName(tokenUsage, "histogram", "{token}"),
+            type: "histogram",
+            unit: "{token}",
+            dimensions: [...GENAI_CLIENT_METRIC_ATTRIBUTES, GENAI_ATTRIBUTES.tokenType],
+        },
+    };
+}
+/** The spanmetrics dimensions beyond the connector's defaults, in config order. */
+function spanMetricDimensions(options) {
+    return [
+        ...GENAI_SPAN_METRIC_DIMENSIONS.map((name) => ({ name })),
+        ...(options.providerDimensions ? GENAI_PROVIDER_DIMENSIONS.map((name) => ({ name })) : []),
+        ...(options.dimensions ?? []),
+    ];
+}
+function quote(s) {
+    return JSON.stringify(s);
+}
+function escapeRe2(s) {
+    return s.replace(/[\\^$.|?*+()[\]{}]/g, "\\$&");
+}
+/** OTTL that deletes the content keys from one context's attributes. */
+function deleteStatements(target, keys) {
+    return [
+        ...keys.map((k) => `delete_key(${target}, ${quote(k)})`),
+        `delete_matching_keys(${target}, ${quote(GENAI_INDEXED_CONTENT_PATTERN)})`,
+    ];
+}
+/** The pieces of the GenAI preset, for wiring into pipelines you declare yourself. */
+export function genAiComponents(options = {}) {
+    const keepContent = options.keepContent === true;
+    const contentKeys = [...GENAI_CONTENT_ATTRIBUTES, ...(options.contentAttributes ?? [])];
+    const metrics = genAiMetrics(options);
+    let contentRemoval;
+    if (!keepContent) {
+        // Older SDKs name the event in an `event.name` attribute instead of the record's event_name.
+        const events = quote(`^(${GENAI_CONTENT_EVENTS.map(escapeRe2).join("|")})$`);
+        const eventMatch = `IsMatch(log.event_name, ${events}) or IsMatch(log.attributes["event.name"], ${events})`;
+        const traceGroups = [
+            { context: "span", statements: deleteStatements("span.attributes", contentKeys) },
+            { context: "spanevent", statements: deleteStatements("spanevent.attributes", contentKeys) },
+        ];
+        const logGroups = [
+            {
+                context: "log",
+                statements: [
+                    ...deleteStatements("log.attributes", contentKeys),
+                    `delete_matching_keys(log.body, "^(content|message|tool_calls)$") where IsMap(log.body) and (${eventMatch})`,
+                    `set(log.body, "") where IsString(log.body) and (${eventMatch})`,
+                ],
+            },
+        ];
+        contentRemoval = new TransformProcessor({
+            name: "genai_content",
+            error_mode: "ignore",
+            trace_statements: traceGroups,
+            log_statements: logGroups,
+        });
+    }
+    const blockedKeys = keepContent
+        ? []
+        : [`^(${contentKeys.map(escapeRe2).join("|")})$`, GENAI_INDEXED_CONTENT_PATTERN];
+    const maskValues = options.maskValues ?? [];
+    let redaction;
+    if (blockedKeys.length > 0 || maskValues.length > 0) {
+        redaction = new RedactionProcessor({
+            name: "genai_content",
+            allow_all_keys: true,
+            ...(blockedKeys.length > 0 ? { blocked_key_patterns: blockedKeys } : {}),
+            ...(maskValues.length > 0 ? { blocked_values: maskValues } : {}),
+            ...(options.hashFunction ? { hash_function: options.hashFunction } : {}),
+        });
+    }
+    const forward = new ForwardConnector({ name: "genai" });
+    const genAiSpans = new FilterProcessor({
+        name: "genai_spans",
+        error_mode: "ignore",
+        traces: { span: [`attributes[${quote(GENAI_ATTRIBUTES.operationName)}] == nil`] },
+    });
+    const flush = options.metricsFlushInterval ?? "15s";
+    const spanMetrics = new SpanMetricsConnector({
+        name: "genai",
+        namespace: options.namespace ?? DEFAULT_NAMESPACE,
+        dimensions: spanMetricDimensions(options),
+        histogram: { unit: "s", explicit: { buckets: [...(options.buckets ?? GENAI_DURATION_BUCKETS)] } },
+        metrics_flush_interval: flush,
+    });
+    // An in-process invoke_agent or invoke_workflow span may carry the usage of
+    // the model calls under it, which are counted on their own spans.
+    const notAggregate = `not (kind == SPAN_KIND_INTERNAL and (attributes[${quote(GENAI_ATTRIBUTES.operationName)}] == "invoke_agent" or attributes[${quote(GENAI_ATTRIBUTES.operationName)}] == "invoke_workflow"))`;
+    const tokenAttributes = GENAI_TOKEN_DIMENSIONS.map((key) => ({ key, default_value: GENAI_UNKNOWN_MODEL }));
+    const tokenUsage = new SumConnector({
+        name: "genai_tokens",
+        spans: {
+            [metrics.inputTokens.name]: {
+                source_attribute: GENAI_ATTRIBUTES.inputTokens,
+                description: "Input tokens used by GenAI operations",
+                conditions: [`attributes[${quote(GENAI_ATTRIBUTES.inputTokens)}] != nil and ${notAggregate}`],
+                attributes: tokenAttributes,
+            },
+            [metrics.outputTokens.name]: {
+                source_attribute: GENAI_ATTRIBUTES.outputTokens,
+                description: "Output tokens used by GenAI operations",
+                conditions: [`attributes[${quote(GENAI_ATTRIBUTES.outputTokens)}] != nil and ${notAggregate}`],
+                attributes: tokenAttributes,
+            },
+        },
+    });
+    let clientMetricsConnector;
+    let sdkClientMetricsFilter;
+    if (metrics.client?.source === "derive") {
+        clientMetricsConnector = deriveClientMetrics(metrics.client, notAggregate);
+        const names = [metrics.client.operationDuration.name, metrics.client.tokenUsage.name];
+        sdkClientMetricsFilter = new FilterProcessor({
+            name: "genai_sdk_client",
+            error_mode: "ignore",
+            metrics: { metric: names.map((n) => `name == ${quote(n)}`) },
+        });
+    }
+    const processors = [];
+    if (contentRemoval)
+        processors.push(contentRemoval);
+    if (redaction)
+        processors.push(redaction);
+    return {
+        ...(contentRemoval ? { contentRemoval } : {}),
+        ...(redaction ? { redaction } : {}),
+        processors,
+        forward,
+        genAiSpans,
+        spanMetrics,
+        tokenUsage,
+        ...(clientMetricsConnector ? { clientMetrics: clientMetricsConnector } : {}),
+        ...(sdkClientMetricsFilter ? { sdkClientMetricsFilter } : {}),
+        metrics,
+        semconv: GENAI_SEMCONV_PIN,
+    };
+}
+/**
+ * The `signaltometrics` connector for the conventions' client metrics. Every
+ * GenAI span records its duration. Token usage is one histogram fed by two
+ * entries, input and output, each setting `gen_ai.token.type` through the
+ * attribute's `default_value` (spans don't carry that key); the connector
+ * merges entries with the same name, unit and description into one metric.
+ * Token entries skip the in-process agent and workflow spans the `sum`
+ * connector skips, and spans whose count is not a number, which would
+ * otherwise fail the batch.
+ */
+function deriveClientMetrics(client, notAggregate) {
+    const [operation, ...rest] = GENAI_CLIENT_METRIC_ATTRIBUTES;
+    // Spans always have the operation (filter/genai_spans keeps no other); the
+    // rest are optional, so a span that lacks one, such as a tool call without
+    // a provider, is still counted.
+    const attributes = [{ key: operation }, ...rest.map((key) => ({ key, optional: true }))];
+    const duration = {
+        name: client.operationDuration.name,
+        description: "GenAI operation duration.",
+        unit: client.operationDuration.unit,
+        attributes,
+        histogram: {
+            buckets: [...GENAI_CLIENT_DURATION_BUCKETS],
+            value: "Double(Microseconds(end_time - start_time)) / 1000000.0",
+        },
+    };
+    const tokens = (tokenType, source) => {
+        const attr = `attributes[${quote(source)}]`;
+        return {
+            name: client.tokenUsage.name,
+            description: "Number of input and output tokens used.",
+            unit: client.tokenUsage.unit,
+            attributes: [...attributes, { key: GENAI_ATTRIBUTES.tokenType, default_value: tokenType }],
+            conditions: [`(IsInt(${attr}) or IsDouble(${attr})) and ${notAggregate}`],
+            histogram: { buckets: [...GENAI_CLIENT_TOKEN_BUCKETS], value: attr },
+        };
+    };
+    return new SignalToMetricsConnector({
+        name: "genai_client",
+        spans: [
+            duration,
+            tokens(GENAI_TOKEN_TYPES.input, GENAI_ATTRIBUTES.inputTokens),
+            tokens(GENAI_TOKEN_TYPES.output, GENAI_ATTRIBUTES.outputTokens),
+        ],
+    });
+}
+// ── The whole collector ──────────────────────────────────────────────
+/**
+ * Metric exporters that take delta sums and histograms as they are: the
+ * `prometheus` exporter accumulates them itself, and `debug` prints them.
+ * Any other exporter gets cumulative data under `deltaToCumulative: "auto"`.
+ * `prometheusremotewrite`, for one, drops non-cumulative monotonic sums,
+ * histograms and summaries (its README at collector-contrib v0.130.0).
+ */
+export const DELTA_READY_EXPORTERS = Object.freeze(["prometheus", "debug"]);
+/** Whether `deltaToCumulative` puts a `deltatocumulative` processor on `metrics/genai` for these exporters. */
+export function genAiNeedsDeltaToCumulative(setting, metricExporters) {
+    if (setting === true)
+        return true;
+    if (setting === "auto")
+        return metricExporters.some((e) => !DELTA_READY_EXPORTERS.includes(e.componentType));
+    if (setting === undefined || setting === false)
+        return false;
+    throw new Error(`genAiPipeline: deltaToCumulative must be true, false or "auto", got ${JSON.stringify(setting)}`);
+}
+/**
+ * The entities of an OTLP collector for GenAI workloads: an `otlp` receiver
+ * on 4317 and 4318; `memory_limiter`, content removal and `batch` on traces
+ * and logs; a `traces/genai` branch that turns GenAI spans into metrics
+ * before any sampling; and a `metrics/genai` pipeline that exports them. Pass
+ * the result to `collectorYaml`, or use `genAiComponents()` to wire the
+ * pieces into pipelines of your own.
+ */
+export function genAiPipeline(options = {}) {
+    return Object.values(genAiPipelineParts(options));
+}
+/** `genAiPipeline()`'s entities by name, in the order it returns them. */
+export function genAiPipelineParts(options = {}) {
+    const debug = new DebugExporter({ verbosity: "basic" });
+    const { traceExporters = [debug], metricExporters = [debug], logExporters = [debug], logs = true, sampling = [], healthCheck = true } = options;
+    const parts = genAiComponents(options);
+    const client = parts.metrics.client;
+    // derive mode is opt-in and newer than the option, so it can default to "auto".
+    const cumulativeSetting = options.deltaToCumulative ?? (client?.source === "derive" ? "auto" : false);
+    const cumulative = genAiNeedsDeltaToCumulative(cumulativeSetting, metricExporters)
+        ? [new DeltaToCumulativeProcessor({ name: "genai" })]
+        : [];
+    const otlp = new OtlpReceiver({
+        protocols: {
+            grpc: { endpoint: "0.0.0.0:4317" },
+            http: { endpoint: "0.0.0.0:4318" },
+        },
+    });
+    const memoryLimiter = new MemoryLimiterProcessor({
+        check_interval: "1s",
+        limit_percentage: 80,
+        spike_limit_percentage: 20,
+    });
+    const batch = new BatchProcessor({});
+    // Insertion order is the order genAiPipeline() has always returned.
+    const out = { otlp };
+    if (sampling.length === 0) {
+        out.traces = new Pipeline({
+            signal: "traces",
+            receivers: [otlp],
+            processors: [memoryLimiter, ...parts.processors, batch],
+            exporters: [...traceExporters, parts.forward],
+        });
+    }
+    else {
+        const sampled = new ForwardConnector({ name: "sampled" });
+        out.traces = new Pipeline({
+            signal: "traces",
+            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.
+        out.sdkMetrics = new Pipeline({
+            signal: "metrics",
+            receivers: [otlp],
+            processors: [memoryLimiter, ...(parts.sdkClientMetricsFilter ? [parts.sdkClientMetricsFilter] : []), batch],
+            exporters: metricExporters,
+        });
+    }
+    if (logs) {
+        out.logs = new Pipeline({
+            signal: "logs",
+            receivers: [otlp],
+            processors: [memoryLimiter, ...parts.processors, batch],
+            exporters: logExporters,
+        });
+    }
+    if (healthCheck)
+        out.health = new HealthCheckExtension({ endpoint: "0.0.0.0:13133" });
+    return out;
+}

package/dist/import/embedded.js

@@ -0,0 +1,57 @@
+/**
+ * A collector config embedded in another lexicon's resource, e.g. the
+ * `config.yaml` of a k8s ConfigMap, for `chant import` (#2962).
+ *
+ * The config is imported exactly as `chant import config.yaml` would import
+ * 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 { exportedNames } from "@intentius/chant/import/embedded";
+import { looksLikeCollectorConfig } from "../model.js";
+import { emitCollectorYaml } from "../yaml.js";
+import { OtelCollectorParser } from "./parser.js";
+import { OtelCollectorGenerator } from "./generator.js";
+const PACKAGE = "@intentius/chant-lexicon-otel";
+/** The module holding `defineComponent` classes: types, not config entities. */
+const CUSTOM_COMPONENTS = "custom-components.ts";
+function selectedConfig(content) {
+    const doc = content.document;
+    return typeof doc === "object" && doc !== null ? doc.config : undefined;
+}
+/** The text a `{ config, header }` document prints as: the header lines as comments, then the config. */
+function objectConfigText(content) {
+    const header = content.document.header;
+    const lines = Array.isArray(header) ? header.filter((l) => typeof l === "string") : [];
+    return emitCollectorYaml(selectedConfig(content), { header: lines });
+}
+export const collectorConfigImporter = {
+    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) {
+        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: asObject ? "collectorConfig" : "collectorYaml" } },
+            warnings: ir.warnings ?? [],
+        };
+    },
+};