@intentius/chant-lexicon-otel 0.124.31 → 0.124.32

package/dist/define.js

@@ -0,0 +1,204 @@
+/**
+ * `defineComponent()`, the one way a collector component type enters this
+ * lexicon.
+ *
+ * The built-in receivers, processors, exporters, connectors and extensions are
+ * defined through it, and so is a component a team or plugin adds for something
+ * chant doesn't ship (a vendor exporter, an in-house processor). Both produce the
+ * same kind of class, register in the same table, serialize through the same
+ * code and are checked by the same post-synth checks, so there is no second
+ * path for a custom component to fall off.
+ *
+ * ## Schema pinning
+ *
+ * Every definition carries a `pin`: the source its config type was written
+ * against and the version of that source. Built-ins share `COLLECTOR_PIN`,
+ * which moves only when this package does, so the chant lexicon version pins
+ * them. A custom definition must name its own pin, typically the npm package
+ * (or Go module) that ships the component and the release its type follows,
+ * optionally with a digest of the schema document. chant records the pin; it
+ * does not fetch or verify the schema. The pin shows up in three places:
+ *
+ * - `collectorTopology()` reports it for every component, built-in or not.
+ * - The serializer writes a `# chant:` comment line per custom component at
+ *   the top of the emitted YAML, so the file says which schema each
+ *   non-built-in component was checked against. The collector ignores it.
+ * - OTEL109 fails a build whose custom component has no usable pin.
+ *
+ * Semantic-convention pins (`SEMCONV_PIN`, `GENAI_SEMCONV_PIN`) record which version of an
+ * attribute vocabulary a preset's keys follow. They are not tied to a
+ * component type, so `collectorTopology()` reports them under `semconv` for
+ * each component whose config uses that vocabulary, and the serializer writes
+ * one `# chant: semconv` line for them.
+ */
+import { createResource } from "@intentius/chant/runtime";
+import { canonicalComponentType, componentId } from "./model.js";
+/**
+ * The collector distribution the built-in config types follow. Bumping it is a
+ * lexicon change like any other, released with this package.
+ */
+export const COLLECTOR_PIN = Object.freeze({
+    source: "github.com/open-telemetry/opentelemetry-collector-contrib",
+    version: "v0.130.0",
+});
+/**
+ * The semantic-conventions release this package's other attribute keys
+ * follow, today the `k8s.*` keys `NodeAgent` writes. v1.27.0 is the newest
+ * release the Kubernetes components of contrib v0.130.0 import:
+ * `go.opentelemetry.io/otel/semconv/v1.27.0` in the kubeletstats, k8sobjects
+ * and k8sevents receivers. The k8sattributes processor still imports v1.6.1
+ * and v1.8.0, and v1.27.0 keeps the `k8s.*` keys it writes. Like
+ * `COLLECTOR_PIN`, it moves only when this package does, and
+ * `collectorTopology()` reports it for every component whose config names a
+ * `k8s.` attribute.
+ */
+export const SEMCONV_PIN = Object.freeze({
+    source: "github.com/open-telemetry/semantic-conventions",
+    version: "v1.27.0",
+});
+/**
+ * The OpenTelemetry GenAI semantic conventions the GenAI preset
+ * (`genAiPipeline()`) follows: which attributes carry prompt and completion
+ * content, and which name the operation, model, tool and token usage.
+ *
+ * v1.41.1 is the last semantic-conventions release that defines `gen_ai.*`
+ * itself. From v1.42.0 the GenAI conventions live in
+ * github.com/open-telemetry/semantic-conventions-genai, which had published no
+ * release when this pin was set; move the pin there once it does. Like
+ * `COLLECTOR_PIN`, it moves only when this package does, and
+ * `collectorTopology()` reports it for every component whose config names a
+ * `gen_ai.` attribute.
+ */
+export const GENAI_SEMCONV_PIN = Object.freeze({
+    source: "github.com/open-telemetry/semantic-conventions",
+    version: "v1.41.1",
+});
+const KIND_SEGMENT = {
+    receiver: "Receiver",
+    processor: "Processor",
+    exporter: "Exporter",
+    connector: "Connector",
+    extension: "Extension",
+};
+/** The chant entity type for a component, e.g. `OTel::Exporter::otlp`. */
+export function componentEntityType(kind, type) {
+    return `OTel::${KIND_SEGMENT[kind]}::${type}`;
+}
+// One table per process, keyed by entity type. Held on globalThis so a second
+// copy of this module (a test runner and a built dist, say) shares it.
+const REGISTRY_KEY = Symbol.for("chant.otel.componentDefinitions");
+function registry() {
+    const g = globalThis;
+    let table = g[REGISTRY_KEY];
+    if (!table) {
+        table = new Map();
+        g[REGISTRY_KEY] = table;
+    }
+    return table;
+}
+/** The definition behind an entity type, if one has been registered in this process. */
+export function definitionFor(entityType) {
+    return registry().get(entityType);
+}
+/**
+ * The definition for a collector `kind` + `type`, e.g. the built-in
+ * `exporter` `otlp`. A renamed built-in's new name (`otlp_grpc`) finds the
+ * built-in unless a component is registered under the new name itself.
+ */
+export function definitionOf(kind, type) {
+    const reg = registry();
+    return reg.get(componentEntityType(kind, type)) ?? reg.get(componentEntityType(kind, canonicalComponentType(kind, type)));
+}
+/** Every registered definition, built-ins first in registration order. */
+export function registeredDefinitions() {
+    return [...registry().values()];
+}
+const TYPE_PATTERN = /^[A-Za-z0-9_]+$/;
+function makeClass(def) {
+    if (!TYPE_PATTERN.test(def.type)) {
+        throw new Error(`otel: component type "${def.type}" is not a collector type (letters, digits and _ only)`);
+    }
+    const entityType = componentEntityType(def.kind, def.type);
+    const existing = registry().get(entityType);
+    if (existing?.builtin && !def.builtin) {
+        throw new Error(`otel: ${def.kind} "${def.type}" is built in. Declare an instance with a name (${def.type}/<name>) instead of defining it again.`);
+    }
+    registry().set(entityType, def);
+    const Base = createResource(entityType, "otel", {});
+    const Cls = function (props) {
+        const p = props ?? {};
+        Base.call(this, p);
+        const name = typeof p.name === "string" ? p.name : undefined;
+        Object.defineProperty(this, "componentKind", { value: def.kind, enumerable: false });
+        Object.defineProperty(this, "componentType", { value: def.type, enumerable: false });
+        Object.defineProperty(this, "componentId", { value: componentId(def.type, name), enumerable: false });
+    };
+    Object.defineProperty(Cls, "name", { value: `${def.type}${KIND_SEGMENT[def.kind]}` });
+    Object.defineProperty(Cls, "definition", { value: def, enumerable: false });
+    return Cls;
+}
+/** Internal: how the built-ins in `./components` are defined. */
+export function defineBuiltin(def) {
+    return makeClass({ ...def, pin: COLLECTOR_PIN, builtin: true });
+}
+/**
+ * Define a collector component chant doesn't ship.
+ *
+ * @example
+ * ```ts
+ * interface DatadogExporterConfig {
+ *   api: { key: string; site?: string };
+ *   traces?: { span_name_as_resource_name?: boolean };
+ * }
+ *
+ * export const DatadogExporter = defineComponent<DatadogExporterConfig>()({
+ *   kind: "exporter",
+ *   type: "datadog",
+ *   pin: { source: "github.com/open-telemetry/opentelemetry-collector-contrib/exporter/datadogexporter", version: "v0.130.0" },
+ *   validate: (c) => (c.api.key.startsWith("${env:") ? [] : ["api.key should come from ${env:...}"]),
+ *   endpoints: (c) => [`https://api.${c.api.site ?? "datadoghq.com"}`],
+ * });
+ *
+ * export const dd = new DatadogExporter({ api: { key: "${env:DD_API_KEY}" } });
+ * ```
+ *
+ * The curried form lets you name the config type while `kind` and `type` are
+ * still inferred from the literal you pass.
+ */
+export function defineComponent() {
+    return function (options) {
+        return makeClass({ ...options, builtin: false });
+    };
+}
+/** True when `value` is a declared collector component (built-in or custom). */
+export function isOTelComponent(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.componentKind === "string" &&
+        typeof value.componentId === "string" &&
+        value.lexicon === "otel");
+}
+/** Run a definition's validator, normalising both validator forms to a list of messages. */
+export function runValidator(validator, config) {
+    if (!validator)
+        return [];
+    if (typeof validator === "function")
+        return validator(config);
+    const result = validator.safeParse(config);
+    if (result.success)
+        return [];
+    const issues = result.error?.issues ?? [];
+    if (issues.length === 0)
+        return [result.error?.message ?? "config does not match its schema"];
+    return issues.map((i) => {
+        const path = (i.path ?? []).map(String).join(".");
+        return path ? `${path}: ${i.message}` : i.message;
+    });
+}
+/** A pin is usable when it names a source and a version. */
+export function isUsablePin(pin) {
+    if (typeof pin !== "object" || pin === null)
+        return false;
+    const p = pin;
+    return typeof p.source === "string" && p.source.trim() !== "" && typeof p.version === "string" && p.version.trim() !== "";
+}

package/dist/detect.js

@@ -0,0 +1,22 @@
+/**
+ * Template detection for the otel lexicon: a parsed document is a collector
+ * config when it has `service.pipelines` and a receivers or exporters
+ * section. Kept free of the plugin and the TypeScript compiler so it bundles
+ * for edge runtimes, like the other lexicons' `detect` modules.
+ */
+import { looksLikeCollectorConfig } from "./model.js";
+export function detectTemplate(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) {
+    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.config);
+}