@intentius/chant-lexicon-otel 0.124.30 → 0.124.32

package/dist/composites/red-metrics.js

@@ -0,0 +1,95 @@
+/**
+ * `RedMetrics`: rate, errors and duration (RED) metrics from traces, served
+ * for Prometheus to scrape.
+ *
+ * Spans come in on an `otlp` receiver (or the receivers given) and go
+ * through `memory_limiter` and `batch` to a `spanmetrics` connector and, by
+ * default, a `servicegraph` connector. Both feed a `metrics` pipeline that
+ * ends at a `prometheus` exporter on 0.0.0.0:8889. Traces can also go on to
+ * a backend through `traceExporters`.
+ *
+ * The metric names follow from the declaration: `redMetricsNames(red)` reads
+ * them back with `spanMetricsNames()` and `serviceGraphNames()`, and the
+ * grafana lexicon's `RedDashboard` and the prometheus lexicon's `RedAlerts`
+ * take the connector and the exporter (`red.spanMetrics`, `red.exporter`),
+ * so a renamed namespace moves every query built from them.
+ */
+import { Composite } from "@intentius/chant/composite";
+import { OtlpReceiver } from "../components/receivers.js";
+import { BatchProcessor, MemoryLimiterProcessor } from "../components/processors.js";
+import { ServiceGraphConnector, SpanMetricsConnector, } from "../components/connectors.js";
+import { PrometheusExporter } from "../components/exporters.js";
+import { Pipeline } from "../pipeline.js";
+import { serviceGraphNames, spanMetricsNames } from "../metric-names.js";
+const NAME = /^[A-Za-z0-9_.-]+$/;
+/** Why a set of `RedMetrics` props can't build, or undefined when they can. */
+export function redMetricsPropsProblem(props = {}) {
+    if (props.receivers !== undefined && props.receivers.length === 0)
+        return "receivers must name at least one receiver when set";
+    if (props.memoryLimitMib !== undefined && !(Number.isInteger(props.memoryLimitMib) && props.memoryLimitMib > 0)) {
+        return "memoryLimitMib must be a positive whole number";
+    }
+    if (props.name !== undefined && !NAME.test(props.name))
+        return `name "${props.name}" must be letters, digits, '.', '_' or '-'`;
+    if (props.exporter !== undefined && props.exporter.componentType !== "prometheus") {
+        return `exporter must be a prometheus exporter, got ${props.exporter.componentType}`;
+    }
+    return undefined;
+}
+/**
+ * RED metrics from traces: `spanmetrics` and `servicegraph` connectors
+ * feeding a `prometheus` exporter.
+ *
+ * @example
+ * ```ts
+ * import { RedMetrics, OtlpExporter } from "@intentius/chant-lexicon-otel";
+ *
+ * const tempo = new OtlpExporter({ name: "tempo", endpoint: "tempo:4317", tls: { insecure: true } });
+ * export const red = RedMetrics({ traceExporters: [tempo], spanMetrics: { namespace: "shop", histogram: { unit: "s" } } });
+ * // RedDashboard({ spanMetrics: red.spanMetrics, exporter: red.exporter, datasource }) in the grafana lexicon
+ * ```
+ */
+export const RedMetrics = Composite((input) => {
+    const props = input ?? {};
+    const problem = redMetricsPropsProblem(props);
+    if (problem)
+        throw new Error(`RedMetrics: ${problem}`);
+    const name = props.name ?? "red";
+    const otlp = props.receivers
+        ? undefined
+        : new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:4317" }, http: { endpoint: "0.0.0.0:4318" } } });
+    const receivers = props.receivers ?? [otlp];
+    const memoryLimiter = new MemoryLimiterProcessor(props.memoryLimitMib !== undefined
+        ? { check_interval: "1s", limit_mib: props.memoryLimitMib, spike_limit_mib: Math.ceil(props.memoryLimitMib / 4) }
+        : { check_interval: "1s", limit_percentage: 80, spike_limit_percentage: 20 });
+    const batch = new BatchProcessor({});
+    const spanMetrics = new SpanMetricsConnector({ name, ...(props.spanMetrics ?? {}) });
+    const graphConfig = props.serviceGraph === undefined || props.serviceGraph === true ? {} : props.serviceGraph === false ? undefined : props.serviceGraph;
+    const serviceGraph = graphConfig ? new ServiceGraphConnector({ name, ...graphConfig }) : undefined;
+    const exporter = props.exporter ?? new PrometheusExporter({ name, endpoint: "0.0.0.0:8889" });
+    const connectors = [spanMetrics, ...(serviceGraph ? [serviceGraph] : [])];
+    const traces = new Pipeline({
+        signal: "traces",
+        name,
+        receivers,
+        processors: [memoryLimiter, batch],
+        exporters: [...connectors, ...(props.traceExporters ?? [])],
+    });
+    const metrics = new Pipeline({ signal: "metrics", name, receivers: connectors, processors: [batch], exporters: [exporter] });
+    // A composite member must be a declarable, so the components that are off are left out rather than undefined.
+    const members = { memoryLimiter, batch, spanMetrics, exporter, traces, metrics };
+    if (otlp)
+        members.otlp = otlp;
+    if (serviceGraph)
+        members.serviceGraph = serviceGraph;
+    return members;
+}, "RedMetrics");
+/** The metric names a `RedMetrics(...)` result serves, read from its connectors and exporter. */
+export function redMetricsNames(red) {
+    if (!red?.spanMetrics || !red.exporter)
+        throw new Error("redMetricsNames: pass a RedMetrics(...) result");
+    return {
+        spans: spanMetricsNames(red.spanMetrics, red.exporter),
+        ...(red.serviceGraph ? { serviceGraph: serviceGraphNames(red.serviceGraph, red.exporter) } : {}),
+    };
+}

package/dist/composites/tail-sampling-tier.js

@@ -0,0 +1,132 @@
+/**
+ * `TailSamplingTier`: the collector config of a tail sampling tier on any
+ * host (VMs, Docker, Fly, ECS), for where the k8s lexicon's
+ * `OtelCollectorGateway` does not run.
+ *
+ * Tail sampling needs every span of a trace in one collector. The agents in
+ * front send to this tier through a `loadbalancing` exporter that routes by
+ * trace id (`tailSamplingLoadBalancer()` declares it), and each replica of
+ * the tier holds a trace for `decisionWait`, then keeps it when a policy
+ * says so:
+ *
+ * - `errors`: any span ended in error (default: on);
+ * - `slowerThanMs`: the trace took at least this long (default 1000 ms);
+ * - `percentage`: a baseline share of everything else (default 10%);
+ * - `policies`: more `tail_sampling` policies of your own, after those.
+ *
+ * The pipeline is `otlp` in, `memory_limiter`, `tail_sampling`, `batch`, the
+ * given exporters out. Compute span metrics before this tier (the agents, or
+ * `RedMetrics`), or they count only the traces kept.
+ */
+import { Composite } from "@intentius/chant/composite";
+import { goDurationMs } from "../components/common.js";
+import { OtlpReceiver } from "../components/receivers.js";
+import { BatchProcessor, MemoryLimiterProcessor } from "../components/processors.js";
+import { DebugExporter } from "../components/exporters.js";
+import { HealthCheckExtension } from "../components/extensions.js";
+import { LoadBalancingExporter, TailSamplingProcessor, } from "../components/sampling.js";
+import { Pipeline } from "../pipeline.js";
+/** Why a set of `TailSamplingTier` props can't build, or undefined when they can. */
+export function tailSamplingTierPropsProblem(props = {}) {
+    if (props.exporters !== undefined && props.exporters.length === 0)
+        return "exporters must name at least one exporter when set";
+    if (props.receivers !== undefined && props.receivers.length === 0)
+        return "receivers must name at least one receiver when set";
+    if (props.decisionWait !== undefined) {
+        const ms = goDurationMs(props.decisionWait, 0);
+        if (ms === undefined || ms <= 0)
+            return `decisionWait ${JSON.stringify(props.decisionWait)} is not a positive duration`;
+    }
+    const s = props.slowerThanMs;
+    if (s !== undefined && s !== false && !(Number.isInteger(s) && s > 0))
+        return "slowerThanMs must be a positive whole number of milliseconds, or false";
+    const pc = props.percentage;
+    if (pc !== undefined && pc !== false && !(typeof pc === "number" && pc > 0 && pc <= 100))
+        return "percentage must be above 0 and at most 100, or false";
+    if (props.numTraces !== undefined && !(Number.isInteger(props.numTraces) && props.numTraces > 0))
+        return "numTraces must be a positive whole number";
+    if (props.memoryLimitMib !== undefined && !(Number.isInteger(props.memoryLimitMib) && props.memoryLimitMib > 0)) {
+        return "memoryLimitMib must be a positive whole number";
+    }
+    if (tierPolicies(props).length === 0)
+        return "every policy is off, so no trace would ever be kept";
+    return undefined;
+}
+function tierPolicies(props) {
+    const out = [];
+    if (props.errors !== false)
+        out.push({ name: "errors", type: "status_code", status_code: { status_codes: ["ERROR"] } });
+    const slow = props.slowerThanMs ?? 1000;
+    if (slow !== false)
+        out.push({ name: "slow", type: "latency", latency: { threshold_ms: slow } });
+    const pc = props.percentage ?? 10;
+    if (pc !== false)
+        out.push({ name: "baseline", type: "probabilistic", probabilistic: { sampling_percentage: pc } });
+    return [...out, ...(props.policies ?? [])];
+}
+/**
+ * The collector config of a tail sampling tier: whole traces in, the ones
+ * a policy keeps out.
+ *
+ * @example
+ * ```ts
+ * import { TailSamplingTier, OtlpExporter } from "@intentius/chant-lexicon-otel";
+ *
+ * const tempo = new OtlpExporter({ name: "tempo", endpoint: "tempo:4317", tls: { insecure: true } });
+ * export const sampler = TailSamplingTier({ exporters: [tempo], slowerThanMs: 500, percentage: 5 });
+ * ```
+ */
+export const TailSamplingTier = Composite((input) => {
+    const props = input ?? {};
+    const problem = tailSamplingTierPropsProblem(props);
+    if (problem)
+        throw new Error(`TailSamplingTier: ${problem}`);
+    const otlp = props.receivers
+        ? undefined
+        : new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:4317" }, http: { endpoint: "0.0.0.0:4318" } } });
+    const memoryLimiter = new MemoryLimiterProcessor(props.memoryLimitMib !== undefined
+        ? { check_interval: "1s", limit_mib: props.memoryLimitMib, spike_limit_mib: Math.ceil(props.memoryLimitMib / 4) }
+        : { check_interval: "1s", limit_percentage: 80, spike_limit_percentage: 20 });
+    const tailSampling = new TailSamplingProcessor({
+        decision_wait: props.decisionWait ?? "10s",
+        ...(props.numTraces !== undefined ? { num_traces: props.numTraces } : {}),
+        policies: tierPolicies(props),
+    });
+    const batch = new BatchProcessor({});
+    const debug = props.exporters ? undefined : new DebugExporter({ verbosity: "basic" });
+    const traces = new Pipeline({
+        signal: "traces",
+        receivers: props.receivers ?? [otlp],
+        processors: [memoryLimiter, tailSampling, batch],
+        exporters: props.exporters ?? [debug],
+    });
+    const health = props.healthCheck === false ? undefined : new HealthCheckExtension({ endpoint: "0.0.0.0:13133" });
+    // A composite member must be a declarable, so the parts that are off are left out rather than undefined.
+    const members = { memoryLimiter, tailSampling, batch, traces };
+    if (otlp)
+        members.otlp = otlp;
+    if (debug)
+        members.debug = debug;
+    if (health)
+        members.health = health;
+    return members;
+}, "TailSamplingTier");
+/**
+ * The exporter the agents in front of a `TailSamplingTier` send traces with:
+ * a `loadbalancing` exporter that routes every span of a trace to the same
+ * replica of the tier, by trace id.
+ *
+ * @example
+ * ```ts
+ * // TLS by default; pass `{ otlp: { tls: { insecure: true } } }` as `protocol` on a private network.
+ * const toSampler = tailSamplingLoadBalancer({ dns: { hostname: "sampler.internal" } }, "sampler");
+ * ```
+ */
+export function tailSamplingLoadBalancer(resolver, name, protocol) {
+    return new LoadBalancingExporter({
+        ...(name !== undefined ? { name } : {}),
+        routing_key: "traceID",
+        ...(protocol !== undefined ? { protocol } : {}),
+        resolver,
+    });
+}