@intentius/chant-lexicon-otel 0.106.4 → 0.108.0

package/src/composites/otlp-collector.test.ts

@@ -0,0 +1,43 @@
+/**
+ * `OtlpCollector`: the composite declares the config `otlpCollector()`
+ * returns, with each part under a member name.
+ */
+import { describe, expect, test } from "vitest";
+import { load } from "js-yaml";
+import type { Declarable } from "@intentius/chant/declarable";
+import { OtlpCollector, otlpCollectorPropsProblem, type OtlpCollectorProps } from "./index";
+import { otlpCollector } from "../platform";
+import { OtlpExporter } from "../components/exporters";
+import { collectorYaml } from "../collector";
+import { validateCollectorConfig } from "../validate-config";
+import type { CollectorConfig, Signal } from "../model";
+
+const backend = new OtlpExporter({ name: "backend", endpoint: "collector.example.com:4317" });
+
+describe("OtlpCollector", () => {
+  const cases: Array<[string, OtlpCollectorProps]> = [
+    ["the defaults", {}],
+    ["an exporter and two signals", { exporters: [backend], signals: ["traces", "logs"] }],
+    ["no health check", { healthCheck: false }],
+  ];
+
+  test.each(cases)("%s: the same config as otlpCollector(), and it passes the config checks", (_label, props) => {
+    const yaml = collectorYaml(Object.values(OtlpCollector(props).members) as Declarable[]);
+    expect(yaml).toBe(collectorYaml(otlpCollector(props)));
+    expect(validateCollectorConfig(load(yaml) as CollectorConfig)).toEqual([]);
+  });
+
+  test("members: the default debug exporter only when no exporters are given, a pipeline per signal", () => {
+    expect(Object.keys(OtlpCollector({}).members).sort()).toEqual(["batch", "debug", "health", "logs", "memoryLimiter", "metrics", "otlp", "traces"]);
+    const c = OtlpCollector({ exporters: [backend], signals: ["traces"], healthCheck: false });
+    expect(Object.keys(c.members).sort()).toEqual(["batch", "memoryLimiter", "otlp", "traces"]);
+    expect(c.traces?.props.exporters).toEqual([backend]);
+  });
+
+  test("bad props are refused", () => {
+    expect(otlpCollectorPropsProblem({})).toBeUndefined();
+    expect(() => OtlpCollector({ exporters: [] })).toThrow(/OtlpCollector: exporters must name at least one exporter/);
+    expect(() => OtlpCollector({ signals: [] })).toThrow(/signals must name at least one signal/);
+    expect(() => OtlpCollector({ signals: ["profiles" as Signal] })).toThrow(/"profiles" is not traces, metrics or logs/);
+  });
+});

package/src/composites/otlp-collector.ts

@@ -0,0 +1,70 @@
+/**
+ * `OtlpCollector`: `otlpCollector()` as a composite.
+ *
+ * The small OTLP collector the docker, k8s and fly platform composites start
+ * from: an `otlp` receiver on 4317 (gRPC) and 4318 (HTTP), `memory_limiter`
+ * then `batch`, the given exporters (default: one `debug` exporter), one
+ * pipeline per signal, and a `health_check` extension on 0.0.0.0:13133.
+ * Each part is a member, so a project exports one declaration and hands
+ * the parts on by name.
+ */
+
+import { Composite, type CompositeInstance } from "@intentius/chant/composite";
+import type { OTelComponent } from "../define";
+import type { PipelineEntity } from "../pipeline";
+import { otlpCollectorParts, type OtlpCollectorOptions } from "../platform";
+
+export type OtlpCollectorProps = OtlpCollectorOptions;
+
+// A type alias, not an interface: a composite's members type needs the implicit index signature.
+export type OtlpCollectorMembers = {
+  otlp: OTelComponent<"receiver", "otlp", object>;
+  memoryLimiter: OTelComponent<"processor", "memory_limiter", object>;
+  batch: OTelComponent<"processor", "batch", object>;
+  /** The default `debug` exporter, when no `exporters` are given. */
+  debug?: OTelComponent<"exporter", string, object>;
+  health?: OTelComponent<"extension", "health_check", object>;
+  traces?: PipelineEntity;
+  metrics?: PipelineEntity;
+  logs?: PipelineEntity;
+};
+
+export type OtlpCollectorInstance = CompositeInstance<OtlpCollectorMembers> & OtlpCollectorMembers;
+
+/** Why a set of `OtlpCollector` props can't build, or undefined when they can. */
+export function otlpCollectorPropsProblem(props: OtlpCollectorProps = {}): string | undefined {
+  if (props.exporters !== undefined && props.exporters.length === 0) return "exporters must name at least one exporter when set";
+  if (props.signals !== undefined) {
+    if (props.signals.length === 0) return "signals must name at least one signal when set";
+    const bad = props.signals.find((s) => s !== "traces" && s !== "metrics" && s !== "logs");
+    if (bad !== undefined) return `signals: "${String(bad)}" is not traces, metrics or logs`;
+  }
+  return undefined;
+}
+
+/**
+ * A small OTLP collector config: OTLP in, `memory_limiter` and `batch`, the
+ * given exporters out, for each signal.
+ *
+ * @example
+ * ```ts
+ * import { OtlpCollector, OtlpExporter } from "@intentius/chant-lexicon-otel";
+ *
+ * const backend = new OtlpExporter({ name: "backend", endpoint: "collector.example.com:4317" });
+ * export const collector = OtlpCollector({ exporters: [backend], signals: ["traces", "logs"] });
+ * ```
+ */
+export const OtlpCollector = Composite<OtlpCollectorProps, OtlpCollectorMembers>((input) => {
+  const props = input ?? {};
+  const problem = otlpCollectorPropsProblem(props);
+  if (problem) throw new Error(`OtlpCollector: ${problem}`);
+  const p = otlpCollectorParts(props);
+  // A composite member must be a declarable, so the parts that are off are left out rather than undefined.
+  const members: OtlpCollectorMembers = { otlp: p.otlp, memoryLimiter: p.memoryLimiter, batch: p.batch };
+  if (props.exporters === undefined) members.debug = p.exporters[0];
+  if (p.health) members.health = p.health;
+  if (p.pipelines.traces) members.traces = p.pipelines.traces;
+  if (p.pipelines.metrics) members.metrics = p.pipelines.metrics;
+  if (p.pipelines.logs) members.logs = p.pipelines.logs;
+  return members;
+}, "OtlpCollector");

package/src/composites/red-metrics.test.ts

@@ -0,0 +1,131 @@
+/**
+ * `RedMetrics`: the collector config it declares, the names it serves, and
+ * the RED queries `spanMetricsRedQueries()` builds from them for the grafana
+ * and prometheus lexicons.
+ */
+import { describe, expect, test } from "vitest";
+import { load } from "js-yaml";
+import type { Declarable } from "@intentius/chant/declarable";
+import { RedMetrics, redMetricsNames, redMetricsPropsProblem, type RedMetricsProps } from "./index";
+import { ForwardConnector } from "../components/connectors";
+import { OtlpExporter, PrometheusExporter } from "../components/exporters";
+import { collectorYaml } from "../collector";
+import { validateCollectorConfig } from "../validate-config";
+import type { CollectorConfig } from "../model";
+import { spanMetricsNames, spanMetricsRedQueries, RED_DEFAULT_SPAN_KINDS, SPAN_METRICS_KINDS, promErrorRatio } from "../metric-names";
+
+function configOf(props: RedMetricsProps = {}): CollectorConfig {
+  return load(collectorYaml(Object.values(RedMetrics(props).members) as Declarable[])) as CollectorConfig;
+}
+
+describe("RedMetrics defaults", () => {
+  const config = configOf();
+
+  test("the config passes every config check", () => {
+    expect(validateCollectorConfig(config)).toEqual([]);
+  });
+
+  test("OTLP in, spanmetrics and servicegraph out of traces/red, metrics/red to a prometheus exporter on 8889", () => {
+    expect(Object.keys(config.receivers ?? {})).toEqual(["otlp"]);
+    expect(Object.keys(config.connectors ?? {}).sort()).toEqual(["servicegraph/red", "spanmetrics/red"]);
+    expect(config.exporters).toEqual({ "prometheus/red": { endpoint: "0.0.0.0:8889" } });
+    expect(config.service?.pipelines).toEqual({
+      "traces/red": { receivers: ["otlp"], processors: ["memory_limiter", "batch"], exporters: ["spanmetrics/red", "servicegraph/red"] },
+      "metrics/red": { receivers: ["spanmetrics/red", "servicegraph/red"], processors: ["batch"], exporters: ["prometheus/red"] },
+    });
+  });
+
+  test("memory_limiter defaults to a share of the container's memory", () => {
+    expect(config.processors?.memory_limiter).toEqual({ check_interval: "1s", limit_percentage: 80, spike_limit_percentage: 20 });
+  });
+
+  test("the served names are the connector defaults'", () => {
+    const names = redMetricsNames(RedMetrics({}));
+    expect(names.spans.calls.prometheus).toBe("traces_span_metrics_calls_total");
+    expect(names.spans.duration?.prometheus).toBe("traces_span_metrics_duration_milliseconds");
+    expect(names.serviceGraph?.requests.prometheus).toBe("traces_service_graph_request_total");
+  });
+});
+
+describe("RedMetrics options", () => {
+  test("the spanmetrics config, a trace backend and a named exporter are used as given", () => {
+    const tempo = new OtlpExporter({ name: "tempo", endpoint: "tempo:4317", tls: { insecure: true } });
+    const scrape = new PrometheusExporter({ name: "scrape", endpoint: "0.0.0.0:9464", namespace: "edge" });
+    const red = RedMetrics({ traceExporters: [tempo], exporter: scrape, spanMetrics: { namespace: "shop", histogram: { unit: "s" } }, name: "shop" });
+    const config = load(collectorYaml(Object.values(red.members) as Declarable[])) as CollectorConfig;
+    expect(validateCollectorConfig(config)).toEqual([]);
+    expect(config.connectors?.["spanmetrics/shop"]).toEqual({ namespace: "shop", histogram: { unit: "s" } });
+    expect(config.service?.pipelines?.["traces/shop"].exporters).toEqual(["spanmetrics/shop", "servicegraph/shop", "otlp/tempo"]);
+    expect(config.service?.pipelines?.["metrics/shop"].exporters).toEqual(["prometheus/scrape"]);
+    const names = redMetricsNames(red);
+    expect(names.spans.calls.prometheus).toBe("edge_shop_calls_total");
+    expect(names.spans.duration?.prometheus).toBe("edge_shop_duration_seconds");
+    expect(names.spans).toEqual(spanMetricsNames(red.spanMetrics, red.exporter));
+  });
+
+  test("serviceGraph: false leaves the servicegraph connector out", () => {
+    const red = RedMetrics({ serviceGraph: false });
+    expect(red.serviceGraph).toBeUndefined();
+    expect(Object.keys(red.members)).not.toContain("serviceGraph");
+    const config = configOf({ serviceGraph: false });
+    expect(Object.keys(config.connectors ?? {})).toEqual(["spanmetrics/red"]);
+    expect(redMetricsNames(red).serviceGraph).toBeUndefined();
+    expect(validateCollectorConfig(config)).toEqual([]);
+  });
+
+  test("receivers replace the otlp receiver, e.g. a connector from another traces pipeline", () => {
+    const fwd = new ForwardConnector({ name: "red" });
+    const red = RedMetrics({ receivers: [fwd] });
+    expect(red.otlp).toBeUndefined();
+    expect(red.traces.props.receivers).toEqual([fwd]);
+  });
+
+  test("memoryLimitMib sets a hard limit with a quarter of it as spike limit", () => {
+    expect(configOf({ memoryLimitMib: 512 }).processors?.memory_limiter).toEqual({ check_interval: "1s", limit_mib: 512, spike_limit_mib: 128 });
+  });
+
+  test("bad props are refused", () => {
+    expect(redMetricsPropsProblem({})).toBeUndefined();
+    expect(() => RedMetrics({ receivers: [] })).toThrow(/RedMetrics: receivers must name at least one receiver/);
+    expect(() => RedMetrics({ memoryLimitMib: 0 })).toThrow(/memoryLimitMib/);
+    expect(() => RedMetrics({ name: "a b" })).toThrow(/name "a b"/);
+    const notPrometheus = new OtlpExporter({ endpoint: "x:4317" }) as unknown as RedMetricsProps["exporter"];
+    expect(() => RedMetrics({ exporter: notPrometheus })).toThrow(/exporter must be a prometheus exporter/);
+  });
+});
+
+describe("spanMetricsRedQueries", () => {
+  const names = spanMetricsNames({ namespace: "shop", histogram: { unit: "s" } });
+
+  test("rate, error ratio and quantiles per service over server and consumer spans", () => {
+    const q = spanMetricsRedQueries(names, { range: "5m", quantiles: [0.95] });
+    const kinds = `span_kind=~"${RED_DEFAULT_SPAN_KINDS.join("|")}"`;
+    expect(q.service).toBe("service_name");
+    expect(q.rate).toBe(`sum by (service_name) (rate(shop_calls_total{${kinds}}[5m]))`);
+    expect(q.errorRatio).toBe(
+      promErrorRatio(`shop_calls_total{${kinds}, status_code="STATUS_CODE_ERROR"}`, `shop_calls_total{${kinds}}`, ["service_name"], "5m"),
+    );
+    expect(q.duration).toEqual([
+      { quantile: 0.95, expr: `histogram_quantile(0.95, sum by (le, service_name) (rate(shop_duration_seconds_bucket{${kinds}}[5m])))` },
+    ]);
+  });
+
+  test("a service match, extra labels and every span kind", () => {
+    const q = spanMetricsRedQueries(names, { range: "$__rate_interval", serviceMatch: "$service", spanKinds: [], by: ["env"] });
+    expect(q.kindMatchers).toEqual([]);
+    expect(q.rate).toBe('sum by (service_name, env) (rate(shop_calls_total{service_name=~"$service"}[$__rate_interval]))');
+    expect(q.duration.map((d) => d.quantile)).toEqual([0.5, 0.95, 0.99]);
+  });
+
+  test("errors name the caller", () => {
+    expect(() => spanMetricsRedQueries(spanMetricsNames({ exclude_dimensions: ["status.code"] }), { range: "5m", owner: "X" })).toThrow(
+      /^X: the connector excludes status.code/,
+    );
+    expect(() => spanMetricsRedQueries(names, { range: "5m", spanKinds: ["SPAN_KIND_NOPE" as never] })).toThrow(/unknown span kind/);
+    expect(SPAN_METRICS_KINDS).toHaveLength(6);
+  });
+
+  test("no histogram, no duration queries", () => {
+    expect(spanMetricsRedQueries(spanMetricsNames({ histogram: { disable: true } }), { range: "5m" }).duration).toEqual([]);
+  });
+});

package/src/composites/red-metrics.ts

@@ -0,0 +1,148 @@
+/**
+ * `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, type CompositeInstance } from "@intentius/chant/composite";
+import { OtlpReceiver } from "../components/receivers";
+import { BatchProcessor, MemoryLimiterProcessor } from "../components/processors";
+import {
+  ServiceGraphConnector,
+  SpanMetricsConnector,
+  type ServiceGraphConnectorConfig,
+  type SpanMetricsConnectorConfig,
+} from "../components/connectors";
+import { PrometheusExporter, type PrometheusExporterConfig } from "../components/exporters";
+import type { OTelComponent } from "../define";
+import { Pipeline, type PipelineEntity } from "../pipeline";
+import { serviceGraphNames, spanMetricsNames, type ServiceGraphNames, type SpanMetricsNames } from "../metric-names";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Exporter = OTelComponent<"exporter", string, any>;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type TraceSource = OTelComponent<"receiver" | "connector", string, any>;
+type Component<K extends "receiver" | "processor" | "exporter" | "connector"> = OTelComponent<K, string, object>;
+
+export interface RedMetricsProps {
+  /** Where spans come from: receivers, or a connector from another traces pipeline. Default: an `otlp` receiver on 4317 (gRPC) and 4318 (HTTP). */
+  receivers?: TraceSource[];
+  /** Where traces go besides the connectors, e.g. a tracing backend. Default: nowhere. */
+  traceExporters?: Exporter[];
+  /** The `prometheus` exporter the metrics are served on. Default: one named after `name`, on 0.0.0.0:8889. */
+  exporter?: OTelComponent<"exporter", "prometheus", PrometheusExporterConfig>;
+  /** The `spanmetrics` connector's config: namespace, dimensions, histogram unit and buckets (default: the connector's defaults). */
+  spanMetrics?: SpanMetricsConnectorConfig;
+  /** Service-to-service edge metrics from a `servicegraph` connector (default: on). */
+  serviceGraph?: boolean | ServiceGraphConnectorConfig;
+  /** `memory_limiter`'s hard limit in MiB (default: 80% of the container's memory, with a 20% spike limit). */
+  memoryLimitMib?: number;
+  /** The instance name of the connectors, the exporter and the two pipelines (default `red`). */
+  name?: string;
+}
+
+// A type alias, not an interface: a composite's members type needs the implicit index signature.
+export type RedMetricsMembers = {
+  otlp?: Component<"receiver">;
+  memoryLimiter: Component<"processor">;
+  batch: Component<"processor">;
+  spanMetrics: OTelComponent<"connector", "spanmetrics", SpanMetricsConnectorConfig>;
+  serviceGraph?: OTelComponent<"connector", "servicegraph", ServiceGraphConnectorConfig>;
+  exporter: OTelComponent<"exporter", "prometheus", PrometheusExporterConfig>;
+  traces: PipelineEntity;
+  metrics: PipelineEntity;
+};
+
+export type RedMetricsInstance = CompositeInstance<RedMetricsMembers> & RedMetricsMembers;
+
+const NAME = /^[A-Za-z0-9_.-]+$/;
+
+/** Why a set of `RedMetrics` props can't build, or undefined when they can. */
+export function redMetricsPropsProblem(props: RedMetricsProps = {}): string | undefined {
+  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<RedMetricsProps, RedMetricsMembers>((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: TraceSource[] = 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: RedMetricsMembers = { memoryLimiter, batch, spanMetrics, exporter, traces, metrics };
+  if (otlp) members.otlp = otlp;
+  if (serviceGraph) members.serviceGraph = serviceGraph;
+  return members;
+}, "RedMetrics");
+
+/** The Prometheus names of what a `RedMetrics` serves: the span metrics, and the service graph's when it is on. */
+export interface RedMetricsNames {
+  spans: SpanMetricsNames;
+  serviceGraph?: ServiceGraphNames;
+}
+
+/** The metric names a `RedMetrics(...)` result serves, read from its connectors and exporter. */
+export function redMetricsNames(red: RedMetricsInstance | RedMetricsMembers): RedMetricsNames {
+  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/src/composites/tail-sampling-tier.test.ts

@@ -0,0 +1,100 @@
+/**
+ * `TailSamplingTier`: the sampling collector's config, its default
+ * policies, the switches, and the load-balancing exporter for the agents in
+ * front of it.
+ */
+import { describe, expect, test } from "vitest";
+import { load } from "js-yaml";
+import type { Declarable } from "@intentius/chant/declarable";
+import { TailSamplingTier, tailSamplingLoadBalancer, tailSamplingTierPropsProblem, type TailSamplingTierProps } from "./index";
+import { OtlpExporter } from "../components/exporters";
+import { collectorYaml } from "../collector";
+import { validateCollectorConfig } from "../validate-config";
+import type { CollectorConfig } from "../model";
+
+type Loose = Record<string, any>; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+function configOf(props: TailSamplingTierProps = {}): CollectorConfig {
+  return load(collectorYaml(Object.values(TailSamplingTier(props).members) as Declarable[])) as CollectorConfig;
+}
+
+const tempo = new OtlpExporter({ name: "tempo", endpoint: "tempo:4317", tls: { insecure: true } });
+
+describe("TailSamplingTier defaults", () => {
+  const config = configOf();
+
+  test("the config passes every config check", () => {
+    expect(validateCollectorConfig(config)).toEqual([]);
+  });
+
+  test("otlp in, memory_limiter, tail_sampling, batch, debug out", () => {
+    expect(config.service?.pipelines).toEqual({
+      traces: { receivers: ["otlp"], processors: ["memory_limiter", "tail_sampling", "batch"], exporters: ["debug"] },
+    });
+    expect(config.service?.extensions).toEqual(["health_check"]);
+  });
+
+  test("keeps errors, traces of a second or more, and 10% of the rest, after 10s", () => {
+    const ts = config.processors?.tail_sampling as Loose;
+    expect(ts.decision_wait).toBe("10s");
+    expect(ts.policies).toEqual([
+      { name: "errors", type: "status_code", status_code: { status_codes: ["ERROR"] } },
+      { name: "slow", type: "latency", latency: { threshold_ms: 1000 } },
+      { name: "baseline", type: "probabilistic", probabilistic: { sampling_percentage: 10 } },
+    ]);
+    expect(ts.num_traces).toBeUndefined();
+  });
+});
+
+describe("TailSamplingTier options", () => {
+  test("exporters, thresholds and extra policies", () => {
+    const config = configOf({
+      exporters: [tempo],
+      slowerThanMs: 500,
+      percentage: 5,
+      decisionWait: "5s",
+      numTraces: 100000,
+      policies: [{ name: "checkout", type: "string_attribute", string_attribute: { key: "service.name", values: ["checkout"] } }],
+    });
+    expect(validateCollectorConfig(config)).toEqual([]);
+    const ts = config.processors?.tail_sampling as Loose;
+    expect(ts.decision_wait).toBe("5s");
+    expect(ts.num_traces).toBe(100000);
+    expect(ts.policies.map((p: Loose) => p.name)).toEqual(["errors", "slow", "baseline", "checkout"]);
+    expect(ts.policies[1].latency).toEqual({ threshold_ms: 500 });
+    expect(config.service?.pipelines?.traces.exporters).toEqual(["otlp/tempo"]);
+    expect(config.exporters?.debug).toBeUndefined();
+  });
+
+  test("each default policy can be turned off", () => {
+    const ts = configOf({ errors: false, percentage: false }).processors?.tail_sampling as Loose;
+    expect(ts.policies.map((p: Loose) => p.name)).toEqual(["slow"]);
+  });
+
+  test("members leave out what is off", () => {
+    const tier = TailSamplingTier({ exporters: [tempo], healthCheck: false });
+    expect(Object.keys(tier.members).sort()).toEqual(["batch", "memoryLimiter", "otlp", "tailSampling", "traces"]);
+  });
+
+  test("bad props are refused", () => {
+    expect(tailSamplingTierPropsProblem({})).toBeUndefined();
+    expect(() => TailSamplingTier({ errors: false, slowerThanMs: false, percentage: false })).toThrow(/TailSamplingTier: every policy is off/);
+    expect(() => TailSamplingTier({ percentage: 0 })).toThrow(/percentage/);
+    expect(() => TailSamplingTier({ percentage: 101 })).toThrow(/percentage/);
+    expect(() => TailSamplingTier({ slowerThanMs: 1.5 })).toThrow(/slowerThanMs/);
+    expect(() => TailSamplingTier({ decisionWait: "soon" })).toThrow(/decisionWait/);
+    expect(() => TailSamplingTier({ exporters: [] })).toThrow(/exporters/);
+  });
+});
+
+describe("tailSamplingLoadBalancer", () => {
+  test("routes by trace id to the resolver's backends", () => {
+    const lb = tailSamplingLoadBalancer({ dns: { hostname: "sampler.internal" } }, "sampler");
+    expect(lb.componentId).toBe("loadbalancing/sampler");
+    expect(lb.props).toMatchObject({ routing_key: "traceID", resolver: { dns: { hostname: "sampler.internal" } } });
+    expect((lb.props as Loose).protocol).toBeUndefined();
+    const insecure = tailSamplingLoadBalancer({ static: { hostnames: ["a:4317", "b:4317"] } }, undefined, { otlp: { tls: { insecure: true } } });
+    expect(insecure.componentId).toBe("loadbalancing");
+    expect((insecure.props as Loose).protocol).toEqual({ otlp: { tls: { insecure: true } } });
+  });
+});