@intentius/chant-lexicon-otel 0.124.31 → 0.124.32

package/dist/semconv.js

@@ -0,0 +1,50 @@
+/**
+ * Semantic-convention vocabularies a collector config can depend on, and how
+ * to tell that it does.
+ *
+ * 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`, 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, SEMCONV_PIN } from "./define.js";
+import { SECTION_OF } from "./model.js";
+// `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 = Object.freeze([
+    { namespace: "gen_ai", pin: GENAI_SEMCONV_PIN, matches: (text) => GEN_AI_REF.test(text) },
+    { namespace: "k8s", pin: SEMCONV_PIN, matches: (text) => K8S_REF.test(text) },
+]);
+function mentions(value, test) {
+    if (typeof value === "string")
+        return test(value);
+    if (Array.isArray(value))
+        return value.some((v) => mentions(v, test));
+    if (value && typeof value === "object") {
+        return Object.entries(value).some(([k, v]) => test(k) || mentions(v, test));
+    }
+    return false;
+}
+/** The semconv vocabularies a collector config uses, each with its pin and the components that use it. */
+export function semconvUsage(config) {
+    const out = [];
+    for (const vocab of SEMCONV_VOCABULARIES) {
+        const components = [];
+        for (const kind of Object.keys(SECTION_OF)) {
+            for (const [id, cfg] of Object.entries(config[SECTION_OF[kind]] ?? {})) {
+                if (mentions(cfg, vocab.matches))
+                    components.push(id);
+            }
+        }
+        if (components.length > 0)
+            out.push({ namespace: vocab.namespace, ...vocab.pin, components });
+    }
+    return out;
+}

package/dist/serializer.js

@@ -0,0 +1,26 @@
+/**
+ * OpenTelemetry Collector serializer.
+ *
+ * Emits one collector config file from every otel entity in the build: the
+ * YAML `otelcol --config` reads as it is. Section order is fixed (receivers,
+ * processors, exporters, connectors, extensions, service); components and pipelines keep
+ * the order they are declared in, and each component's config keeps the key
+ * order it was written in, since collector docs and diffs read that way.
+ *
+ * A collector config has no metadata channel, so there is no ownership marker
+ * to stamp. A custom component's schema pin is written as a `# chant:` comment
+ * line above the config (see `define.ts`).
+ */
+import { buildCollectorConfig } from "./collector.js";
+import { emitCollectorYaml } from "./yaml.js";
+export const otelSerializer = {
+    name: "otel",
+    rulePrefix: "OTEL",
+    serialize(entities, _outputs) {
+        const built = buildCollectorConfig(entities);
+        const yaml = emitCollectorYaml(built.config, { header: built.header });
+        if (built.warnings.length === 0)
+            return yaml;
+        return { primary: yaml, warnings: built.warnings };
+    },
+};

package/dist/skill-defs.js

@@ -0,0 +1,34 @@
+import { createSkillsLoader } from "@intentius/chant/lexicon-plugin-helpers";
+/** The otel lexicon's AI skills, read from src/skills/. */
+export const otelSkills = createSkillsLoader(import.meta.url, [
+    {
+        file: "chant-otel.md",
+        name: "chant-otel",
+        description: "Declare OpenTelemetry Collector config (receivers, processors, exporters, pipelines) as typed chant entities and build collector YAML",
+        triggers: [
+            { type: "context", value: "opentelemetry" },
+            { type: "context", value: "otel collector" },
+            { type: "file-pattern", value: "*.otel.ts" },
+        ],
+        examples: [
+            {
+                title: "An OTLP-in, OTLP-out traces pipeline",
+                output: 'const otlp = new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:4317" } } });\n' +
+                    'const backend = new OtlpExporter({ name: "backend", endpoint: "tempo:4317" });\n' +
+                    "export const traces = new Pipeline({ signal: \"traces\", receivers: [otlp], exporters: [backend] });",
+            },
+        ],
+    },
+    {
+        file: "chant-otel-custom-components.md",
+        name: "chant-otel-custom-components",
+        description: "Add a collector component chant doesn't ship (a vendor exporter, an in-house processor) with defineComponent, and pin its schema",
+        triggers: [{ type: "context", value: "otel custom component" }],
+    },
+    {
+        file: "chant-otel-platforms.md",
+        name: "chant-otel-platforms",
+        description: "Run a declared collector config on Kubernetes, GKE, Docker or Fly by rendering it into the platform's own config file",
+        triggers: [{ type: "context", value: "deploy otel collector" }],
+    },
+]);

package/dist/topology.js

@@ -0,0 +1,104 @@
+/**
+ * Where telemetry goes, as plain data.
+ *
+ * `collectorTopology()` reads a collector config (declared, or parsed from a
+ * YAML file) and returns its pipelines, its components with their endpoints
+ * and schema pins, for each exporter the pipelines and signals it carries,
+ * the edges connectors make from one pipeline to another, and the
+ * semantic-convention versions its attribute keys follow. It is the
+ * surface a reader such as `chant workspace graph` uses to say where a
+ * member's telemetry is sent, and what a declared telemetry endpoint link can
+ * point at.
+ */
+import { buildCollectorConfig } from "./collector.js";
+import { definitionOf } from "./define.js";
+import { parseComponentId, pipelineSignal, SECTION_OF } from "./model.js";
+import { semconvUsage } from "./semconv.js";
+function protocolsOf(kind, type, config) {
+    const def = definitionOf(kind, type);
+    if (!def?.protocols)
+        return [];
+    try {
+        return def.protocols((config ?? {}));
+    }
+    catch {
+        return [];
+    }
+}
+function endpointsOf(kind, type, config) {
+    const def = definitionOf(kind, type);
+    const cfg = config ?? {};
+    if (def?.endpoints) {
+        try {
+            return def.endpoints(cfg);
+        }
+        catch {
+            return [];
+        }
+    }
+    return typeof cfg.endpoint === "string" && cfg.endpoint !== "" ? [cfg.endpoint] : [];
+}
+/** The topology of a collector config. */
+export function collectorTopology(config) {
+    const pipelines = Object.entries(config.service?.pipelines ?? {}).map(([id, p]) => ({
+        id,
+        signal: pipelineSignal(id),
+        receivers: (p?.receivers ?? []).map(String),
+        processors: (p?.processors ?? []).map(String),
+        exporters: (p?.exporters ?? []).map(String),
+    }));
+    const components = [];
+    for (const kind of Object.keys(SECTION_OF)) {
+        const section = SECTION_OF[kind];
+        for (const [id, cfg] of Object.entries(config[section] ?? {})) {
+            const parsed = parseComponentId(id);
+            const type = parsed?.type ?? id;
+            const def = definitionOf(kind, type);
+            const inPipelines = section === "extensions"
+                ? []
+                : section === "connectors"
+                    ? pipelines.filter((p) => p.receivers.includes(id) || p.exporters.includes(id)).map((p) => p.id)
+                    : pipelines.filter((p) => p[section].includes(id)).map((p) => p.id);
+            components.push({
+                id,
+                kind,
+                type,
+                ...(parsed?.name !== undefined ? { name: parsed.name } : {}),
+                builtin: def?.builtin ?? false,
+                ...(def ? { schema: { ...def.pin } } : {}),
+                endpoints: endpointsOf(kind, type, cfg),
+                protocols: protocolsOf(kind, type, cfg),
+                pipelines: inPipelines,
+            });
+        }
+    }
+    const exporters = components
+        .filter((c) => c.kind === "exporter")
+        .map((c) => {
+        const signals = [];
+        for (const pid of c.pipelines) {
+            const s = pipelineSignal(pid);
+            if (!signals.includes(s))
+                signals.push(s);
+        }
+        return { id: c.id, type: c.type, endpoints: c.endpoints, pipelines: c.pipelines, signals };
+    });
+    const edges = [];
+    for (const c of components) {
+        if (c.kind !== "connector")
+            continue;
+        const pairs = definitionOf("connector", c.type)?.connects;
+        for (const from of pipelines.filter((p) => p.exporters.includes(c.id))) {
+            for (const to of pipelines.filter((p) => p.receivers.includes(c.id))) {
+                if (pairs && pairs.length > 0 && !pairs.some((pair) => pair.from === from.signal && pair.to === to.signal))
+                    continue;
+                edges.push({ connector: c.id, from: from.id, fromSignal: from.signal, to: to.id, toSignal: to.signal });
+            }
+        }
+    }
+    return { pipelines, components, exporters, edges, semconv: semconvUsage(config) };
+}
+/** The topology of declared entities, i.e. of the config the serializer would emit for them. */
+export function collectorTopologyOf(entities) {
+    return collectorTopology(buildCollectorConfig(entities).config);
+}

package/dist/validate-cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env tsx
+import { printValidationResult } from "@intentius/chant/codegen/validate";
+import { validate } from "./validate.js";
+const result = await validate();
+printValidationResult(result);
+if (!result.success)
+    process.exit(1);