Observability (OpenTelemetry)

@zuke/otel is a zero-runtime-dependency plugin that exports a run as OpenTelemetry traces and metrics over OTLP/HTTP JSON — hand-rolled, so core stays OTel-free. Register it on a run and each state transition ships to a collector: one run span with a child span per executed target, plus run/suspend/outcome counters.

The otel() plugin

// jsr:@zuke/otel
export function otel(configure?: Configure<OtelSettings>): Plugin

Called with no arguments — or with no endpoint configured, whether by setter or by OTEL_EXPORTER_OTLP_ENDPOINT — the plugin is inert, so it's safe to register unconditionally. Otherwise configure gets an OtelSettings with fluent setters, each returning this:

endpoint(url): this            // base; /v1/traces & /v1/metrics appended
tracesEndpoint(url): this      // verbatim
metricsEndpoint(url): this     // verbatim
serviceName(name): this
header(name, value): this
headers(map): this
resourceAttribute(name, value): this
resourceAttributes(map): this
timeout(duration): this        // "5s"; default 10s

What it exports

The plugin observes onRunStateChange against the durable RunRecord:

Run span attributes: zuke.run.id, zuke.build, zuke.root_target, zuke.actor, zuke.run.status. Target span attributes: zuke.target, zuke.target.status; a failed target's span is marked error with its redacted message. Metrics are OTLP delta Sums. Only executed targets get a span, and a run is exported once (the dedup set is capped at 1024).

Setter ↔ env config

Every setter has an env fallback, so the same registration works locally and in CI; an explicit setter always wins over its env var.

Trace continuity across suspend/resume

A run that suspends and resumes in a different process still lands as one trace: the trace id is SHA-256(runId) truncated to 16 bytes, and each target span id is a stable hash of (runId, target). Every process derives the same ids, so the whole run — including the gap while it was suspended — reassembles into one complete, gap-spanning trace.

Setup examples

import { run } from "jsr:@zuke/core";
import { otel } from "jsr:@zuke/otel";
await run(MyBuild, {
  plugins: [
    otel((s) => s.endpoint("http://localhost:4318").serviceName("my-build").header("authorization", "Bearer …")),
  ],
});

// Config entirely from OTEL_* env — same registration works locally and in CI:
await run(MyBuild, { plugins: [otel()] });