@intentius/chant-lexicon-otel 0.124.45 → 0.124.48

package/dist/distribution.js

@@ -0,0 +1,227 @@
+/**
+ * `Distribution`, the builder manifest `ocb` (the OpenTelemetry Collector
+ * Builder) builds a custom collector from (#3374).
+ *
+ * The fields are the builder's `Config` as read at v0.130.0
+ * (`cmd/builder/internal/builder/config.go` in opentelemetry-collector):
+ * `dist`, a module list per component kind, `providers`,
+ * `converters`, `replaces`, `excludes` and `conf_resolver`. `telemetry`
+ * (v0.146.0) is not in it, and `otelcol_version`, removed in v0.113.0, is
+ * not either.
+ *
+ * A component list takes a module (`{ gomod, import?, name?, path? }`) or a
+ * component class. A built-in class writes its module at `COLLECTOR_PIN`
+ * (`OtlpReceiver` is `go.opentelemetry.io/collector/receiver/otlpreceiver
+ * v0.162.0`), and a `defineComponent` class writes its own pin's source and
+ * version, so the manifest names the same versions the config was typed
+ * against.
+ *
+ * The serializer writes the manifest as `builder-config.yaml` beside the
+ * collector config when a project declares a `Distribution`. OTEL128 then
+ * checks that the collector config uses only components the distribution
+ * builds. A project without one sees no change.
+ */
+import { createResource } from "@intentius/chant/runtime";
+import { dump } from "js-yaml";
+import { COLLECTOR_PIN, isUsablePin } from "./define.js";
+import { canonicalComponentType, canonicalTypeOf, COMPONENT_KINDS, SECTION_OF } from "./model.js";
+export const DISTRIBUTION_TYPE = "OTel::Distribution";
+/** Where the serializer writes the builder manifest, beside the collector config. */
+export const DISTRIBUTION_MANIFEST_FILE = "builder-config.yaml";
+/** A custom collector's builder manifest. Declare at most one per project. */
+export const Distribution = createResource(DISTRIBUTION_TYPE, "otel", {});
+export function isDistributionEntity(value) {
+    return typeof value === "object" && value !== null && value.entityType === DISTRIBUTION_TYPE;
+}
+const CORE = "go.opentelemetry.io/collector";
+const CONTRIB = "github.com/open-telemetry/opentelemetry-collector-contrib";
+/**
+ * The Go module of every built-in, by `kind:type`. The core collector's
+ * components are in opentelemetry-collector, the rest in contrib; both are
+ * released at `COLLECTOR_PIN`'s version. A built-in added to `./components`
+ * needs a row here (distribution.test.ts checks).
+ */
+export const BUILTIN_MODULES = Object.freeze({
+    "receiver:otlp": `${CORE}/receiver/otlpreceiver`,
+    "receiver:filelog": `${CONTRIB}/receiver/filelogreceiver`,
+    "receiver:hostmetrics": `${CONTRIB}/receiver/hostmetricsreceiver`,
+    "receiver:prometheus": `${CONTRIB}/receiver/prometheusreceiver`,
+    "receiver:k8s_cluster": `${CONTRIB}/receiver/k8sclusterreceiver`,
+    "receiver:kubeletstats": `${CONTRIB}/receiver/kubeletstatsreceiver`,
+    "processor:batch": `${CORE}/processor/batchprocessor`,
+    "processor:memory_limiter": `${CORE}/processor/memorylimiterprocessor`,
+    "processor:attributes": `${CONTRIB}/processor/attributesprocessor`,
+    "processor:deltatocumulative": `${CONTRIB}/processor/deltatocumulativeprocessor`,
+    "processor:k8sattributes": `${CONTRIB}/processor/k8sattributesprocessor`,
+    "processor:resourcedetection": `${CONTRIB}/processor/resourcedetectionprocessor`,
+    "processor:resource": `${CONTRIB}/processor/resourceprocessor`,
+    "processor:filter": `${CONTRIB}/processor/filterprocessor`,
+    "processor:redaction": `${CONTRIB}/processor/redactionprocessor`,
+    "processor:transform": `${CONTRIB}/processor/transformprocessor`,
+    "processor:probabilistic_sampler": `${CONTRIB}/processor/probabilisticsamplerprocessor`,
+    "processor:tail_sampling": `${CONTRIB}/processor/tailsamplingprocessor`,
+    "exporter:debug": `${CORE}/exporter/debugexporter`,
+    "exporter:otlp": `${CORE}/exporter/otlpexporter`,
+    "exporter:otlphttp": `${CORE}/exporter/otlphttpexporter`,
+    "exporter:googlecloud": `${CONTRIB}/exporter/googlecloudexporter`,
+    "exporter:prometheus": `${CONTRIB}/exporter/prometheusexporter`,
+    "exporter:loadbalancing": `${CONTRIB}/exporter/loadbalancingexporter`,
+    "exporter:clickhouse": `${CONTRIB}/exporter/clickhouseexporter`,
+    "connector:forward": `${CORE}/connector/forwardconnector`,
+    "connector:count": `${CONTRIB}/connector/countconnector`,
+    "connector:routing": `${CONTRIB}/connector/routingconnector`,
+    "connector:servicegraph": `${CONTRIB}/connector/servicegraphconnector`,
+    "connector:signaltometrics": `${CONTRIB}/connector/signaltometricsconnector`,
+    "connector:spanmetrics": `${CONTRIB}/connector/spanmetricsconnector`,
+    "connector:sum": `${CONTRIB}/connector/sumconnector`,
+    "extension:zpages": `${CORE}/extension/zpagesextension`,
+    "extension:health_check": `${CONTRIB}/extension/healthcheckextension`,
+    "extension:k8s_leader_elector": `${CONTRIB}/extension/k8sleaderelector`,
+    "extension:pprof": `${CONTRIB}/extension/pprofextension`,
+});
+const KIND_OF_LIST = {
+    receivers: "receiver",
+    processors: "processor",
+    exporters: "exporter",
+    connectors: "connector",
+    extensions: "extension",
+};
+const COMPONENT_LISTS = Object.keys(KIND_OF_LIST);
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function isComponentClass(v) {
+    return typeof v === "function" && typeof v.definition === "object";
+}
+/** The module a component class is built from, at the version its config type follows. */
+export function componentModule(def) {
+    if (def.builtin) {
+        const path = BUILTIN_MODULES[`${def.kind}:${def.type}`];
+        if (!path)
+            throw new Error(`otel: no Go module is recorded for the built-in ${def.kind} "${def.type}"`);
+        return { gomod: `${path} ${COLLECTOR_PIN.version}` };
+    }
+    if (!isUsablePin(def.pin)) {
+        throw new Error(`otel: the custom ${def.kind} "${def.type}" has no pin, so its Go module is unknown; list it as { gomod } instead`);
+    }
+    return { gomod: `${def.pin.source} ${def.pin.version}` };
+}
+function copyModule(entry) {
+    const out = { gomod: entry.gomod };
+    if (entry.import !== undefined)
+        out.import = entry.import;
+    if (entry.name !== undefined)
+        out.name = entry.name;
+    if (entry.path !== undefined)
+        out.path = entry.path;
+    return out;
+}
+function moduleOf(entry, list) {
+    if (isComponentClass(entry)) {
+        const def = entry.definition;
+        if (def.kind !== KIND_OF_LIST[list]) {
+            throw new Error(`otel: ${def.type} is a ${def.kind}, listed under the distribution's ${list}`);
+        }
+        return componentModule(def);
+    }
+    return copyModule(entry);
+}
+/** The builder manifest a distribution writes, as the object `ocb --config` reads. */
+export function distributionManifest(dist) {
+    const p = isDistributionEntity(dist) ? dist.props : dist;
+    const out = {};
+    const d = {};
+    for (const [k, v] of Object.entries(p.dist ?? {}))
+        if (v !== undefined)
+            d[k] = v;
+    out.dist = d;
+    for (const list of COMPONENT_LISTS) {
+        const entries = p[list];
+        if (entries && entries.length > 0)
+            out[list] = entries.map((e) => moduleOf(e, list));
+    }
+    if (p.providers && p.providers.length > 0)
+        out.providers = p.providers.map(copyModule);
+    if (p.converters && p.converters.length > 0)
+        out.converters = p.converters.map(copyModule);
+    if (p.replaces && p.replaces.length > 0)
+        out.replaces = [...p.replaces];
+    if (p.excludes && p.excludes.length > 0)
+        out.excludes = [...p.excludes];
+    if (p.conf_resolver && p.conf_resolver.default_uri_scheme !== undefined) {
+        out.conf_resolver = { default_uri_scheme: p.conf_resolver.default_uri_scheme };
+    }
+    return out;
+}
+/** The builder manifest as the YAML `ocb --config` reads. */
+export function distributionYaml(dist) {
+    return dump(distributionManifest(dist), { lineWidth: -1, noRefs: true });
+}
+/** The module path of a `gomod` line: everything before the version. */
+function modulePath(gomod) {
+    return gomod.trim().split(/\s+/)[0];
+}
+const BUILTIN_BY_PATH = new Map(Object.entries(BUILTIN_MODULES).map(([key, path]) => [path, key.split(":")[1]]));
+/**
+ * The component type a module builds, when it can be told: a built-in's
+ * module, or a module path ending `<type><kind>` as contrib's do
+ * (`.../exporter/datadogexporter` is `datadog`). Undefined otherwise.
+ */
+export function moduleComponentType(kind, gomod) {
+    const path = modulePath(gomod);
+    const builtin = BUILTIN_BY_PATH.get(path);
+    if (builtin !== undefined)
+        return builtin;
+    const last = path.split("/").pop() ?? "";
+    return last.endsWith(kind) && last.length > kind.length ? last.slice(0, -kind.length) : undefined;
+}
+export function distributionComponents(dist) {
+    const p = isDistributionEntity(dist) ? dist.props : dist;
+    const types = { receiver: new Set(), processor: new Set(), exporter: new Set(), connector: new Set(), extension: new Set() };
+    const unknown = { receiver: [], processor: [], exporter: [], connector: [], extension: [] };
+    for (const list of COMPONENT_LISTS) {
+        const kind = KIND_OF_LIST[list];
+        for (const entry of p[list] ?? []) {
+            if (isComponentClass(entry)) {
+                types[kind].add(canonicalComponentType(kind, entry.definition.type));
+                continue;
+            }
+            const type = moduleComponentType(kind, entry.gomod);
+            if (type === undefined)
+                unknown[kind].push(entry.gomod);
+            else
+                types[kind].add(canonicalComponentType(kind, type));
+        }
+    }
+    return { types, unknown };
+}
+/**
+ * OTEL128: the components `config` declares that `dist` does not build. A
+ * collector built from the distribution refuses such a config at start with
+ * "unknown type". When a kind lists a module whose type can't be told from
+ * its path, a missing component may be that module, so it is a warning
+ * naming the module rather than an error.
+ */
+export function distributionIssues(config, dist) {
+    const { types, unknown } = distributionComponents(dist);
+    const issues = [];
+    for (const kind of COMPONENT_KINDS) {
+        const section = config[SECTION_OF[kind]];
+        if (typeof section !== "object" || section === null)
+            continue;
+        for (const id of Object.keys(section)) {
+            const type = canonicalTypeOf(kind, id);
+            if (types[kind].has(type))
+                continue;
+            const unsure = unknown[kind];
+            issues.push({
+                code: "OTEL128",
+                severity: unsure.length > 0 ? "warning" : "error",
+                component: id,
+                message: `${kind} "${id}" is not in the Distribution, so a collector built from it does not know the type "${type}"` +
+                    (unsure.length > 0
+                        ? `, unless it is built by ${unsure.map((m) => `"${modulePath(m)}"`).join(", ")}, whose type can't be read from its path`
+                        : `. Add it to the Distribution's ${SECTION_OF[kind]}, or remove it from the config`),
+            });
+        }
+    }
+    return issues;
+}