@intentius/chant-lexicon-otel 0.124.30 → 0.124.32

package/dist/components/k8s-receivers.js

@@ -0,0 +1,36 @@
+/**
+ * Built-in Kubernetes receivers: k8s_cluster (cluster-level object metrics,
+ * one instance per cluster) and kubeletstats (node, pod and container
+ * resource metrics from each node's kubelet, one instance per node).
+ */
+import { defineBuiltin } from "../define.js";
+/**
+ * Cluster-level metrics and entity events from the Kubernetes API. Run one
+ * instance per cluster (a single-replica Deployment, or behind
+ * `k8s_leader_elector`); on every node it reports each object once per node.
+ */
+export const K8sClusterReceiver = defineBuiltin({
+    kind: "receiver",
+    type: "k8s_cluster",
+    description: "Cluster-level metrics from the Kubernetes API; run one instance per cluster",
+    validate: (c) => c.distribution !== undefined && c.distribution !== "kubernetes" && c.distribution !== "openshift"
+        ? [`distribution "${String(c.distribution)}" is not kubernetes or openshift`]
+        : [],
+});
+/** Node, pod, container and volume resource metrics from the local kubelet. Run one instance per node. */
+export const KubeletStatsReceiver = defineBuiltin({
+    kind: "receiver",
+    type: "kubeletstats",
+    description: "Node, pod and container resource metrics from the kubelet; run one instance per node",
+    validate: (c) => {
+        const problems = [];
+        if ((c.auth_type ?? "tls") === "tls" && (!c.cert_file || !c.key_file)) {
+            problems.push(`auth_type ${c.auth_type ? "tls" : "defaults to tls, which"} needs cert_file and key_file; in a pod set auth_type: serviceAccount`);
+        }
+        if (c.metric_groups !== undefined && c.metric_groups.length === 0) {
+            problems.push("metric_groups is empty, so no kubelet metric is collected");
+        }
+        return problems;
+    },
+    endpoints: (c) => (c.endpoint ? [c.endpoint] : []),
+});

package/dist/components/processors.js

@@ -0,0 +1,103 @@
+/**
+ * Built-in processors: batch, memory_limiter, resource, attributes,
+ * k8sattributes, resourcedetection, deltatocumulative.
+ */
+import { defineBuiltin } from "../define.js";
+import { goDurationMs } from "./common.js";
+/** Batches telemetry before export, to cut request count and compress better. */
+export const BatchProcessor = defineBuiltin({
+    kind: "processor",
+    type: "batch",
+    description: "Groups telemetry into batches before export",
+    validate: (c) => c.send_batch_max_size !== undefined && c.send_batch_max_size !== 0 && c.send_batch_size !== undefined && c.send_batch_max_size < c.send_batch_size
+        ? [`send_batch_max_size (${c.send_batch_max_size}) is below send_batch_size (${c.send_batch_size}); the collector rejects this`]
+        : [],
+});
+/** Refuses data when the collector nears its memory limit. Belongs first in every pipeline. */
+export const MemoryLimiterProcessor = defineBuiltin({
+    kind: "processor",
+    type: "memory_limiter",
+    description: "Refuses data when the collector nears a memory limit; runs first in a pipeline",
+    validate: (c) => {
+        const problems = [];
+        if (c.limit_mib === undefined && c.limit_percentage === undefined) {
+            problems.push("set limit_mib or limit_percentage; with neither the collector refuses to start");
+        }
+        if (c.limit_mib !== undefined && c.spike_limit_mib !== undefined && c.spike_limit_mib >= c.limit_mib) {
+            problems.push(`spike_limit_mib (${c.spike_limit_mib}) must be below limit_mib (${c.limit_mib})`);
+        }
+        if (c.limit_percentage !== undefined && (c.limit_percentage <= 0 || c.limit_percentage > 100)) {
+            problems.push(`limit_percentage (${c.limit_percentage}) must be between 1 and 100`);
+        }
+        return problems;
+    },
+});
+/** Inserts, updates or deletes resource attributes. */
+export const ResourceProcessor = defineBuiltin({
+    kind: "processor",
+    type: "resource",
+    description: "Inserts, updates or deletes resource attributes",
+    validate: (c) => actionProblems(c.attributes, "attributes"),
+});
+/** Inserts, updates, hashes or deletes span, log and metric attributes. */
+export const AttributesProcessor = defineBuiltin({
+    kind: "processor",
+    type: "attributes",
+    description: "Inserts, updates, hashes or deletes span, log and metric attributes",
+    validate: (c) => actionProblems(c.actions, "actions"),
+});
+function actionProblems(actions, field) {
+    if (!actions || actions.length === 0)
+        return [`${field} is empty, so the processor changes nothing`];
+    const problems = [];
+    actions.forEach((a, i) => {
+        if (a.action !== "extract" && !a.key)
+            problems.push(`${field}[${i}] (${a.action}) needs a key`);
+        if (a.action === "extract" && !a.pattern)
+            problems.push(`${field}[${i}] (extract) needs a pattern`);
+        if ((a.action === "insert" || a.action === "update" || a.action === "upsert") &&
+            a.value === undefined &&
+            a.from_attribute === undefined &&
+            a.from_context === undefined) {
+            problems.push(`${field}[${i}] (${a.action}) needs value, from_attribute or from_context`);
+        }
+        if (a.action === "convert" && !a.converted_type)
+            problems.push(`${field}[${i}] (convert) needs converted_type`);
+    });
+    return problems;
+}
+/** Adds Kubernetes pod, namespace and node metadata to telemetry. */
+export const K8sAttributesProcessor = defineBuiltin({
+    kind: "processor",
+    type: "k8sattributes",
+    description: "Adds Kubernetes pod, namespace and node metadata to telemetry",
+});
+/** Detects the host's resource attributes (cloud, container, host) and adds them. */
+export const ResourceDetectionProcessor = defineBuiltin({
+    kind: "processor",
+    type: "resourcedetection",
+    description: "Detects cloud, container and host resource attributes",
+    validate: (c) => (c.detectors?.length ? [] : ["detectors is empty, so nothing is detected"]),
+});
+/**
+ * Turns delta metrics into cumulative ones by keeping a running total per
+ * stream. Exporters that read only cumulative data, such as
+ * `prometheusremotewrite`, need it after connectors that emit deltas (`sum`,
+ * `count`, `signaltometrics`). Cumulative metrics pass through unchanged.
+ */
+export const DeltaToCumulativeProcessor = defineBuiltin({
+    kind: "processor",
+    type: "deltatocumulative",
+    description: "Converts delta metrics to cumulative by keeping a running total per stream",
+    validate: (c) => {
+        // config.go Validate.
+        const problems = [];
+        const stale = goDurationMs(c.max_stale, 5 * 60000);
+        if (stale !== undefined && stale <= 0)
+            problems.push(`max_stale must be a positive duration (got ${JSON.stringify(c.max_stale)})`);
+        if (c.max_streams !== undefined && (!Number.isInteger(c.max_streams) || c.max_streams < 0)) {
+            problems.push(`max_streams must be a whole number, 0 or more (got ${c.max_streams})`);
+        }
+        return problems;
+    },
+});

package/dist/components/receivers.js

@@ -0,0 +1,61 @@
+/**
+ * Built-in receivers: otlp, prometheus, hostmetrics, filelog.
+ */
+import { defineBuiltin } from "../define.js";
+/** Receives OTLP over gRPC (default port 4317) and HTTP (default port 4318). */
+export const OtlpReceiver = defineBuiltin({
+    kind: "receiver",
+    type: "otlp",
+    description: "Receives traces, metrics and logs over OTLP gRPC (4317) and HTTP (4318)",
+    validate: (c) => !c.protocols || (!("grpc" in c.protocols) && !("http" in c.protocols))
+        ? ["protocols enables neither grpc nor http, so the receiver listens on nothing"]
+        : [],
+    endpoints: (c) => {
+        const out = [];
+        if (c.protocols && "grpc" in c.protocols)
+            out.push(c.protocols.grpc?.endpoint ?? "localhost:4317");
+        if (c.protocols && "http" in c.protocols)
+            out.push(c.protocols.http?.endpoint ?? "localhost:4318");
+        return out;
+    },
+    // The HTTP receiver takes protobuf and JSON bodies on the same port.
+    protocols: (c) => [
+        ...(c.protocols && "grpc" in c.protocols ? ["grpc"] : []),
+        ...(c.protocols && "http" in c.protocols ? ["http/protobuf", "http/json"] : []),
+    ],
+});
+/** Scrapes Prometheus endpoints with Prometheus's own scrape config. */
+export const PrometheusReceiver = defineBuiltin({
+    kind: "receiver",
+    type: "prometheus",
+    description: "Scrapes Prometheus endpoints using Prometheus scrape_configs",
+    validate: (c) => {
+        const problems = [];
+        const seen = new Set();
+        for (const job of c.config?.scrape_configs ?? []) {
+            if (seen.has(job.job_name))
+                problems.push(`scrape job "${job.job_name}" is declared twice`);
+            seen.add(job.job_name);
+        }
+        if ((c.config?.scrape_configs ?? []).length === 0 && !c.target_allocator) {
+            problems.push("config.scrape_configs is empty and no target_allocator is set, so nothing is scraped");
+        }
+        return problems;
+    },
+    endpoints: (c) => (c.config?.scrape_configs ?? []).flatMap((job) => (job.static_configs ?? []).flatMap((s) => s.targets)),
+});
+/** Scrapes CPU, memory, disk, filesystem, network and process metrics from the host. */
+export const HostMetricsReceiver = defineBuiltin({
+    kind: "receiver",
+    type: "hostmetrics",
+    description: "Scrapes host metrics (cpu, memory, disk, filesystem, network, processes)",
+    validate: (c) => (Object.keys(c.scrapers ?? {}).length === 0 ? ["scrapers is empty, so no host metric is collected"] : []),
+});
+/** Tails log files and parses them with stanza operators. */
+export const FileLogReceiver = defineBuiltin({
+    kind: "receiver",
+    type: "filelog",
+    description: "Tails log files and parses each line with stanza operators",
+    validate: (c) => (c.include?.length ? [] : ["include is empty, so no file is read"]),
+    endpoints: (c) => c.include ?? [],
+});

package/dist/components/sampling.js

@@ -0,0 +1,257 @@
+/**
+ * Built-in sampling components: the tail_sampling and probabilistic_sampler
+ * processors, and the loadbalancing exporter that routes every span of a trace
+ * to the same collector so tail sampling sees whole traces.
+ *
+ * Field shapes follow `processor/tailsamplingprocessor`,
+ * `processor/probabilisticsamplerprocessor` and
+ * `exporter/loadbalancingexporter` at `COLLECTOR_PIN`.
+ */
+import { defineBuiltin } from "../define.js";
+/**
+ * Holds each trace for `decision_wait`, then samples it when a policy says so.
+ * Tail sampling needs every span of a trace in one collector: run it on a
+ * gateway behind the `loadbalancing` exporter, not on a per-node agent.
+ */
+export const TailSamplingProcessor = defineBuiltin({
+    kind: "processor",
+    type: "tail_sampling",
+    description: "Samples whole traces by policy after waiting for their spans: errors, latency, attributes, rate",
+    validate: (c) => {
+        const problems = [];
+        if (!c.decision_wait)
+            problems.push("decision_wait is not set; declare how long to wait for a trace's spans");
+        if (!Array.isArray(c.policies) || c.policies.length === 0) {
+            problems.push("policies is empty, so no trace is ever sampled");
+        }
+        else {
+            policyListProblems(c.policies, "policies", problems);
+        }
+        return problems;
+    },
+});
+const STATUS_CODES = new Set(["OK", "ERROR", "UNSET"]);
+function policyListProblems(policies, path, problems) {
+    const seen = new Set();
+    policies.forEach((p, i) => {
+        const at = `${path}[${i}]`;
+        if (!p || typeof p !== "object") {
+            problems.push(`${at} is not a policy`);
+            return;
+        }
+        if (!p.name)
+            problems.push(`${at} has no name`);
+        else if (seen.has(p.name))
+            problems.push(`${at}: policy name "${p.name}" is repeated`);
+        else
+            seen.add(p.name);
+        const label = p.name ? `${at} (${p.name})` : at;
+        policyProblems(p, label, problems);
+    });
+}
+function policyProblems(p, at, problems) {
+    const cfg = p[p.type];
+    if (p.type !== "always_sample" && (typeof cfg !== "object" || cfg === null)) {
+        problems.push(`${at}: type ${p.type} needs a ${p.type} block`);
+        return;
+    }
+    switch (p.type) {
+        case "latency":
+            if (!(p.latency.threshold_ms > 0) && !(p.latency.upper_threshold_ms && p.latency.upper_threshold_ms > 0)) {
+                problems.push(`${at}: latency needs threshold_ms or upper_threshold_ms above 0`);
+            }
+            if (p.latency.upper_threshold_ms !== undefined && p.latency.upper_threshold_ms <= p.latency.threshold_ms) {
+                problems.push(`${at}: latency upper_threshold_ms must be above threshold_ms`);
+            }
+            break;
+        case "numeric_attribute":
+            if (!p.numeric_attribute.key)
+                problems.push(`${at}: numeric_attribute needs a key`);
+            if (p.numeric_attribute.min_value !== undefined &&
+                p.numeric_attribute.max_value !== undefined &&
+                p.numeric_attribute.max_value < p.numeric_attribute.min_value) {
+                problems.push(`${at}: numeric_attribute max_value is below min_value`);
+            }
+            break;
+        case "probabilistic": {
+            const pct = p.probabilistic.sampling_percentage;
+            if (typeof pct !== "number" || pct <= 0 || pct > 100) {
+                problems.push(`${at}: probabilistic sampling_percentage must be above 0 and at most 100`);
+            }
+            break;
+        }
+        case "status_code": {
+            const codes = p.status_code.status_codes ?? [];
+            if (codes.length === 0)
+                problems.push(`${at}: status_code needs at least one status code`);
+            for (const code of codes) {
+                if (!STATUS_CODES.has(code))
+                    problems.push(`${at}: status code "${code}" is not OK, ERROR or UNSET`);
+            }
+            break;
+        }
+        case "string_attribute":
+            if (!p.string_attribute.key)
+                problems.push(`${at}: string_attribute needs a key`);
+            if (!p.string_attribute.values?.length)
+                problems.push(`${at}: string_attribute needs at least one value`);
+            break;
+        case "rate_limiting":
+            if (!(p.rate_limiting.spans_per_second > 0))
+                problems.push(`${at}: rate_limiting spans_per_second must be above 0`);
+            break;
+        case "span_count":
+            if (p.span_count.max_spans !== undefined && p.span_count.max_spans < p.span_count.min_spans) {
+                problems.push(`${at}: span_count max_spans is below min_spans`);
+            }
+            break;
+        case "trace_state":
+            if (!p.trace_state.key)
+                problems.push(`${at}: trace_state needs a key`);
+            if (!p.trace_state.values?.length)
+                problems.push(`${at}: trace_state needs at least one value`);
+            break;
+        case "boolean_attribute":
+            if (!p.boolean_attribute.key)
+                problems.push(`${at}: boolean_attribute needs a key`);
+            break;
+        case "ottl_condition":
+            if (!p.ottl_condition.span?.length && !p.ottl_condition.spanevent?.length) {
+                problems.push(`${at}: ottl_condition needs a span or spanevent condition`);
+            }
+            break;
+        case "and":
+            subPolicyProblems(p.and.and_sub_policy, `${at}.and.and_sub_policy`, problems);
+            break;
+        case "drop":
+            subPolicyProblems(p.drop.drop_sub_policy, `${at}.drop.drop_sub_policy`, problems);
+            break;
+        case "composite": {
+            const comp = p.composite;
+            if (!(comp.max_total_spans_per_second > 0))
+                problems.push(`${at}: composite max_total_spans_per_second must be above 0`);
+            const subs = comp.composite_sub_policy ?? [];
+            if (subs.length === 0) {
+                problems.push(`${at}: composite has no composite_sub_policy`);
+                break;
+            }
+            policyListProblems(subs, `${at}.composite.composite_sub_policy`, problems);
+            const names = new Set(subs.map((s) => s.name));
+            for (const n of comp.policy_order ?? []) {
+                if (!names.has(n))
+                    problems.push(`${at}: policy_order names "${n}", which is not a composite_sub_policy`);
+            }
+            let total = 0;
+            for (const r of comp.rate_allocation ?? []) {
+                if (!names.has(r.policy))
+                    problems.push(`${at}: rate_allocation names "${r.policy}", which is not a composite_sub_policy`);
+                total += r.percent;
+            }
+            if (total > 100)
+                problems.push(`${at}: rate_allocation percents add up to ${total}, above 100`);
+            break;
+        }
+        default:
+            break;
+    }
+}
+function subPolicyProblems(subs, path, problems) {
+    if (!subs || subs.length === 0) {
+        problems.push(`${path} is empty`);
+        return;
+    }
+    policyListProblems(subs, path, problems);
+}
+/** Head sampling: keeps a fixed percentage of traces or logs, decided per item without waiting for the rest of the trace. */
+export const ProbabilisticSamplerProcessor = defineBuiltin({
+    kind: "processor",
+    type: "probabilistic_sampler",
+    description: "Head sampling: keeps a fixed percentage of traces or logs",
+    validate: (c) => {
+        const problems = [];
+        const pct = c.sampling_percentage;
+        if (typeof pct !== "number" || Number.isNaN(pct)) {
+            problems.push("sampling_percentage is not set; the collector's default of 0 keeps nothing");
+        }
+        else if (pct < 0 || pct > 100) {
+            problems.push(`sampling_percentage (${pct}) must be between 0 and 100`);
+        }
+        if (c.sampling_precision !== undefined && (c.sampling_precision < 1 || c.sampling_precision > 14)) {
+            problems.push(`sampling_precision (${c.sampling_precision}) must be between 1 and 14`);
+        }
+        if (c.attribute_source === "record" && !c.from_attribute) {
+            problems.push("attribute_source is record but from_attribute is not set");
+        }
+        if (c.hash_seed !== undefined && c.mode !== undefined && c.mode !== "hash_seed") {
+            problems.push(`hash_seed is only read in hash_seed mode, not ${c.mode}`);
+        }
+        return problems;
+    },
+});
+const RESOLVER_KEYS = ["static", "dns", "k8s", "aws_cloud_map"];
+/**
+ * Sends each trace (or service, or metric stream) to one backend chosen by a
+ * consistent hash over the resolver's backends. Put it on the agents in front
+ * of a multi-replica gateway that runs `tail_sampling`.
+ */
+export const LoadBalancingExporter = defineBuiltin({
+    kind: "exporter",
+    type: "loadbalancing",
+    description: "Routes all spans of a trace to one backend collector by trace id, for tail sampling behind it",
+    validate: (c) => {
+        const problems = [];
+        const r = (c.resolver ?? {});
+        const set = RESOLVER_KEYS.filter((k) => r[k] !== undefined && r[k] !== null);
+        if (set.length === 0)
+            problems.push("resolver has none of static, dns, k8s or aws_cloud_map");
+        if (set.length > 1)
+            problems.push(`resolver sets ${set.join(" and ")}; the collector takes exactly one`);
+        const res = c.resolver;
+        if (res?.static && !res.static.hostnames?.length)
+            problems.push("resolver.static.hostnames is empty");
+        if (res?.dns && !res.dns.hostname)
+            problems.push("resolver.dns.hostname is empty");
+        if (res?.k8s) {
+            if (!res.k8s.service)
+                problems.push("resolver.k8s.service is empty");
+            if (res.k8s.ports && res.k8s.ports.length === 0)
+                problems.push("resolver.k8s.ports is empty; omit it for the default 4317");
+        }
+        if (res?.aws_cloud_map && (!res.aws_cloud_map.namespace || !res.aws_cloud_map.service_name)) {
+            problems.push("resolver.aws_cloud_map needs namespace and service_name");
+        }
+        if (c.routing_key === "attributes" && !c.routing_attributes?.length) {
+            problems.push("routing_key is attributes but routing_attributes is empty");
+        }
+        if (c.routing_attributes?.length && c.routing_key !== "attributes") {
+            problems.push("routing_attributes is only read with routing_key: attributes");
+        }
+        const otlp = c.protocol?.otlp;
+        if (otlp && "endpoint" in otlp)
+            problems.push("protocol.otlp.endpoint is ignored; backends come from the resolver");
+        return problems;
+    },
+    endpoints: (c) => loadBalancingEndpoints(c.resolver),
+});
+/**
+ * The backends a `loadbalancing` resolver names, as `host:port` where it can:
+ * static hostnames as given, a DNS name with its port, a Kubernetes Service
+ * once per port, a Cloud Map service as `aws-cloud-map://namespace/service`.
+ */
+export function loadBalancingEndpoints(resolver) {
+    if (!resolver)
+        return [];
+    if (resolver.static)
+        return [...(resolver.static.hostnames ?? [])];
+    if (resolver.dns)
+        return resolver.dns.hostname ? [`${resolver.dns.hostname}:${resolver.dns.port ?? "4317"}`] : [];
+    if (resolver.k8s) {
+        if (!resolver.k8s.service)
+            return [];
+        return (resolver.k8s.ports?.length ? resolver.k8s.ports : [4317]).map((p) => `${resolver.k8s.service}:${p}`);
+    }
+    if (resolver.aws_cloud_map) {
+        return [`aws-cloud-map://${resolver.aws_cloud_map.namespace}/${resolver.aws_cloud_map.service_name}`];
+    }
+    return [];
+}