@diveinto/obs 1.0.1

package/dist/metrics.js

@@ -0,0 +1,111 @@
+/**
+ * First-party metrics surface - a facade that currently exports NOTHING.
+ *
+ * The start path deliberately registers traces + logs only: registerOTel is
+ * called WITHOUT a metricReader, so no MeterProvider exists and
+ * @opentelemetry/api's `metrics.getMeter` hands back no-op instruments. Every
+ * call below therefore records into the void - kept as an API so call sites
+ * stay in place, but nothing metric-shaped leaves the process regardless of
+ * env vars (@vercel/otel does not read OTEL_METRICS_EXPORTER). Before ever
+ * wiring a metricReader: each metric needs a named consumer plus an export
+ * allowlist, and every unbounded attribute needs a cardinality cap. See the
+ * note in otel-start.ts for the incident that made this rule.
+ *
+ * CARDINALITY IS LOAD-BEARING. A metric attribute becomes a separate time series
+ * per distinct value, so attributes MUST be LOW-cardinality: kind / outcome /
+ * backend / route-template and the like - a small fixed vocabulary. NEVER pass a
+ * lab id, task id, dv_uuid, vm name, enduser, or any per-entity id: those are
+ * exactly right on spans and logs (where you want to find the one bad request)
+ * but toxic on metrics (they explode the series count and can OOM the backend).
+ * Because that judgement is the CALLER's, this helper takes an EXPLICIT attrs
+ * dict and deliberately does NOT auto-attach the obs baggage (trace ids, action
+ * name as a field, operator, ...) the way the log sink does - the baggage is
+ * high-cardinality by nature and would defeat the whole point.
+ *
+ * Node-only (imported via the obs facade); never reached by the Edge middleware.
+ */
+import { obsConfig } from "./config.js";
+import { metrics } from "@opentelemetry/api";
+import { otelEnabled } from "./otel.js";
+// Same meter name as the tracer/logger so all three signals file under one
+// instrumentation scope in the backend.
+// The meter name is the service's own, set by configure().
+function meterName() {
+    return obsConfig().service;
+}
+// Instruments are meant to be created once and reused for the process lifetime
+// (the SDK keys aggregation state by the instrument object). We lazily build
+// each one on first use and cache it under its name so repeated calls from hot
+// paths do not re-create instruments. Separate maps keep the types honest -
+// a name is only ever one kind of instrument in practice.
+const counters = new Map();
+const histograms = new Map();
+function getCounter(name) {
+    let c = counters.get(name);
+    if (!c) {
+        c = metrics.getMeter(meterName()).createCounter(name);
+        counters.set(name, c);
+    }
+    return c;
+}
+function getHistogram(name, unit) {
+    let h = histograms.get(name);
+    if (!h) {
+        // unit is advisory metadata (e.g. "ms") the backend can display; it is not a
+        // cardinality dimension, so it is safe and useful to set once at creation.
+        h = metrics.getMeter(meterName()).createHistogram(name, unit ? { unit } : undefined);
+        histograms.set(name, h);
+    }
+    return h;
+}
+/**
+ * Add to a monotonic counter (default +1). No-op when export is off. `attrs` must
+ * be low-cardinality (see the file header) - the type is OTel's Attributes, but
+ * the cardinality contract is on the caller, not the type system.
+ */
+export function metricCounter(name, value = 1, attrs) {
+    if (!otelEnabled())
+        return;
+    getCounter(name).add(value, attrs);
+}
+/**
+ * Record one value into a histogram (latency, size, ...). No-op when export is
+ * off. Pass `unit` (e.g. "ms") on the first call to label the instrument; same
+ * low-cardinality rule applies to `attrs`.
+ */
+export function metricHistogram(name, value, attrs, unit) {
+    if (!otelEnabled())
+        return;
+    getHistogram(name, unit).record(value, attrs);
+}
+/**
+ * Time `fn`, recording its elapsed milliseconds into the `name` histogram (unit
+ * "ms") with an `outcome` attribute of "ok" or "error". The outcome is folded
+ * into the histogram's own attributes (not a separate counter) so a single
+ * instrument carries both the latency distribution and the success/failure split
+ * - which is the standard RED-style shape an alert can read directly.
+ *
+ * When export is off this is a thin passthrough: it still runs `fn` (so callers
+ * can wrap unconditionally) but records nothing and adds no measurable overhead.
+ * It never swallows the error - it re-throws after stamping outcome="error", so
+ * the caller's control flow is unchanged.
+ */
+export async function timed(name, attrs, fn) {
+    if (!otelEnabled())
+        return fn();
+    const start = Date.now();
+    // `finally` rather than a call in each branch: a throw of
+    // something that is not an Error, or a cancellation, still records a
+    // duration, and the histogram call exists once instead of twice.
+    let outcome = "ok";
+    try {
+        return await fn();
+    }
+    catch (err) {
+        outcome = "error";
+        throw err;
+    }
+    finally {
+        metricHistogram(name, Date.now() - start, { ...attrs, outcome }, "ms");
+    }
+}

package/dist/otel-start.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Start OTLP export iff an endpoint is configured. Called once from
+ * instrumentation.ts on the Node runtime. Idempotent; returns whether export is
+ * live. Never throws - on any failure we stay first-party only.
+ */
+export declare function startOtel(serviceName: string): Promise<boolean>;

package/dist/otel-start.js

@@ -0,0 +1,106 @@
+/**
+ * Starting OTLP export, kept in its own module on purpose.
+ *
+ * `startOtel()` dynamically imports @vercel/otel and the OTel SDK. Those are
+ * heavy and Node-only, and a static import would drag them into every bundle
+ * that touches the library, including the edge middleware bundle where they
+ * cannot load at all. Keeping the start path here means an app imports it once,
+ * from `instrumentation.ts`, and nothing else ever pulls it in.
+ *
+ * Published as the `@diveinto/obs/start` subpath for the same reason.
+ *
+ * Never throws: on any failure the service stays first-party only, still
+ * writing stdout and its two files. Losing export is not worth losing logs.
+ */
+import { logs } from "@opentelemetry/api-logs";
+// Module-local to the start path: `otelEnabled()` in otel.ts reads the env
+// instead, because Next can run instrumentation.ts in a different module
+// context from the route handlers, where a flag set here would read false.
+let enabled = false;
+let started = false;
+/**
+ * Start OTLP export iff an endpoint is configured. Called once from
+ * instrumentation.ts on the Node runtime. Idempotent; returns whether export is
+ * live. Never throws - on any failure we stay first-party only.
+ */
+export async function startOtel(serviceName) {
+    if (started)
+        return enabled;
+    started = true;
+    if (!process.env.OTEL_EXPORTER_OTLP_ENDPOINT)
+        return false;
+    try {
+        const { registerOTel } = await import("@vercel/otel");
+        // registerOTel reads OTEL_EXPORTER_OTLP_* (endpoint/headers/protocol) and
+        // OTEL_RESOURCE_ATTRIBUTES from the env. serviceName is the fallback label.
+        // TRACES + LOGS only, on purpose: no metricReader is passed here, so no
+        // metrics leave the process regardless of env vars. This is a scar, not a
+        // preference: auto-exporting metrics alongside traces once produced tens
+        // of millions of samples a month that nobody read. Do not add a
+        // metricReader without a named consumer, an export allowlist, and a
+        // cardinality cap on every attribute.
+        registerOTel({ serviceName });
+        await startLogExport(serviceName);
+        enabled = true;
+        return true;
+    }
+    catch (e) {
+        process.stderr.write(`[obs] OTel init failed (${String(e)}); staying first-party only\n`);
+        return false;
+    }
+}
+/**
+ * Set up the OTLP LOGS signal (separate from traces, which @vercel/otel owns).
+ * Installs a global LoggerProvider + OTLP/protobuf log exporter, so the log sink
+ * (makeOtelLogSink) can ship each record to the backend's Logs view, correlated
+ * to the active span. Best-effort; traces still work if this fails.
+ */
+async function startLogExport(serviceName) {
+    try {
+        const { LoggerProvider, BatchLogRecordProcessor } = await import("@opentelemetry/sdk-logs");
+        const { OTLPLogExporter } = await import("@opentelemetry/exporter-logs-otlp-proto");
+        const { resourceFromAttributes, defaultResource } = await import("@opentelemetry/resources");
+        // Merge precedence matters: in OTel JS the merge ARGUMENT wins. defaultResource()
+        // carries the SDK's "unknown_service:node" default for service.name, so it must
+        // be the BASE and our attributes the argument - otherwise the backend files
+        // these logs under "unknown_service:node" (the original bug). Our attributes
+        // also pull service.version etc. from OTEL_RESOURCE_ATTRIBUTES so the LOGS
+        // resource matches the TRACES resource registerOTel builds.
+        const resource = defaultResource().merge(resourceFromAttributes(logResourceAttrs(serviceName)));
+        const provider = new LoggerProvider({
+            resource,
+            processors: [new BatchLogRecordProcessor(new OTLPLogExporter())],
+        });
+        logs.setGlobalLoggerProvider(provider);
+    }
+    catch (e) {
+        process.stderr.write(`[obs] OTel log export init failed (${String(e)}); traces still export\n`);
+    }
+}
+/**
+ * Resource attributes for the LOGS provider. defaultResource() supplies the SDK
+ * defaults (telemetry.sdk.*) plus a placeholder service.name of
+ * "unknown_service:node"; we override service.name and add anything in
+ * OTEL_RESOURCE_ATTRIBUTES (service.version, deployment.environment, ...) so the
+ * LOGS land under the same service identity as the TRACES. These win the merge
+ * because they are passed as the merge argument (see startLogExport).
+ */
+function logResourceAttrs(serviceName) {
+    const attrs = {};
+    const raw = process.env.OTEL_RESOURCE_ATTRIBUTES;
+    if (raw) {
+        for (const pair of raw.split(",")) {
+            const eq = pair.indexOf("=");
+            if (eq <= 0)
+                continue;
+            const k = pair.slice(0, eq).trim();
+            const v = pair.slice(eq + 1).trim();
+            if (k && v)
+                attrs[k] = v;
+        }
+    }
+    // Explicit env service name wins; else whatever the env attrs carried; else our
+    // label. Never the SDK's "unknown_service:node".
+    attrs["service.name"] = process.env.OTEL_SERVICE_NAME || attrs["service.name"] || serviceName;
+    return attrs;
+}

package/dist/otel.d.ts

@@ -0,0 +1,26 @@
+import { type Fields, type Sink } from "./types.js";
+export declare function otelEnabled(): boolean;
+/**
+ * A Sink that ships each obs record to the OTLP backend as a log, correlated to
+ * the active span (emit() reads the current context, and our records are emitted
+ * inside the request/domain span). Returns null when export is off. The internal
+ * export fetch does not pass back through our sinks, so there is no feedback loop.
+ */
+export declare function makeOtelLogSink(): Sink | null;
+/** The active OTel span's ids as W3C hex, or null when there is no valid span.
+ *  Includes the span's PARENT id (same OTel id-space as spanId) so log records
+ *  can reconstruct the tree, not just correlate by trace_id. */
+export declare function currentIds(): {
+    traceId: string;
+    spanId: string;
+    parentSpanId: string;
+} | null;
+/**
+ * Open a SERVER span continuing the inbound W3C traceparent (extracted from the
+ * request headers), so this service's span nests under the caller's trace. A
+ * no-op passthrough when export is off.
+ */
+export declare function withOtelServerSpan<T>(name: string, headers: Headers, attrs: Fields, fn: () => Promise<T>): Promise<T>;
+/** Open a child span around a unit of work (domain story / outbound). A no-op
+ *  passthrough when export is off. */
+export declare function withOtelSpan<T>(name: string, attrs: Fields, fn: () => Promise<T>): Promise<T>;

package/dist/otel.js

@@ -0,0 +1,173 @@
+/**
+ * Optional OpenTelemetry export. Off unless OTEL_EXPORTER_OTLP_ENDPOINT is set.
+ *
+ * The first-party stdout/file logs are always the source of truth and work with
+ * no collector. This module is the bolt-on that ships spans to an OTLP backend
+ * (any OTLP-compatible collector). When ENABLED, OTel becomes the trace engine:
+ *   - `@vercel/otel` registers the SDK + OTLP exporter (reading the standard
+ *     OTEL_* env: endpoint, headers, protocol, resource attributes).
+ *   - withOtelServerSpan() opens a SERVER span per request, CONTINUING an inbound
+ *     W3C traceparent, so a trace started upstream continues here.
+ *   - withOtelSpan() opens child spans for the domain story (order.place, ...).
+ *   - context.ts reads the ACTIVE OTel span's ids, so every log line carries the
+ *     same trace_id/span_id the backend shows, and traceHeaders() injects that
+ *     same trace id on outbound calls (one trace across every hop).
+ *
+ * @opentelemetry/api is imported at module top (it is a tiny, side-effect-free
+ * facade); the heavy SDK (@vercel/otel) is imported lazily only when an endpoint
+ * is configured. This file is Node-only (reached via setup/instrumentation) and
+ * must never be imported by the Edge middleware.
+ */
+import { context as otelContext, propagation, SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
+import { logs, SeverityNumber } from "@opentelemetry/api-logs";
+import { obsConfig } from "./config.js";
+import { LEVELS } from "./types.js";
+// The tracer and OTLP logger name is the service's own, set by configure().
+// It was a hardcoded constant in all four copies, which is exactly the kind
+// of thing that makes a library a fork.
+function otelName() {
+    return obsConfig().service;
+}
+export function otelEnabled() {
+    // Env-based (process-global) on purpose: Next can run instrumentation.ts in a
+    // different module context than the route handlers, so a per-module `enabled`
+    // flag set by startOtel would read false in handlers. registerOTel sets the
+    // OTel provider on globalThis (shared across contexts), so if the endpoint is
+    // configured we use the global OTel API everywhere; it degrades cleanly (no-op
+    // span -> currentIds null -> contextvar fallback) if the SDK did not start.
+    return !!process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+}
+// stdlib level name -> OTel severity number.
+const SEVERITY = {
+    DEBUG: SeverityNumber.DEBUG,
+    INFO: SeverityNumber.INFO,
+    WARNING: SeverityNumber.WARN,
+    ERROR: SeverityNumber.ERROR,
+    CRITICAL: SeverityNumber.FATAL,
+};
+// stdlib level name -> OTel CANONICAL severity text. The OTel ecosystem and
+// the common backends use the short names WARN / FATAL, not the Python-style
+// WARNING / CRITICAL this library carries internally. Emitting the short names
+// keeps severity_text uniform across services, so one backend filter for
+// "WARN" matches everything instead of having to also match "WARNING".
+const SEVERITY_TEXT = {
+    DEBUG: "DEBUG",
+    INFO: "INFO",
+    WARNING: "WARN",
+    ERROR: "ERROR",
+    CRITICAL: "FATAL",
+};
+/**
+ * A Sink that ships each obs record to the OTLP backend as a log, correlated to
+ * the active span (emit() reads the current context, and our records are emitted
+ * inside the request/domain span). Returns null when export is off. The internal
+ * export fetch does not pass back through our sinks, so there is no feedback loop.
+ */
+export function makeOtelLogSink() {
+    if (!otelEnabled())
+        return null;
+    const logger = logs.getLogger(otelName());
+    return {
+        name: "otlp",
+        minLevel: LEVELS.DEBUG,
+        write: (rec) => {
+            const attributes = { "logger.name": rec.logger };
+            if (rec.event)
+                attributes.event = rec.event;
+            for (const src of [rec.baggage, rec.fields]) {
+                for (const [k, v] of Object.entries(src))
+                    attributes[k] = otelAttr(v);
+            }
+            logger.emit({
+                severityNumber: SEVERITY[rec.level] ?? SeverityNumber.INFO,
+                severityText: SEVERITY_TEXT[rec.level] ?? rec.level,
+                // Body is the human message only - the event key already rides as its own
+                // attribute, so prefixing it here is redundant and diverges from the
+                // agent, whose OTLP body is the bare message. Fall back to the event when
+                // there is no message (mirrors the agent's `message or event`).
+                body: rec.msg || rec.event || "",
+                attributes,
+            });
+        },
+        describe: () => ({ type: "otlp", target: "otlp/logs", format: "otlp" }),
+    };
+}
+/** The active OTel span's ids as W3C hex, or null when there is no valid span.
+ *  Includes the span's PARENT id (same OTel id-space as spanId) so log records
+ *  can reconstruct the tree, not just correlate by trace_id. */
+export function currentIds() {
+    if (!otelEnabled())
+        return null;
+    const span = trace.getActiveSpan();
+    const sc = span?.spanContext();
+    if (!sc || !sc.traceId || sc.traceId === "0".repeat(32))
+        return null;
+    // Parent isn't on the public Span API - read it defensively off the concrete
+    // SDK span (ReadableSpan). SDK 2.x exposes parentSpanContext.spanId; SDK 1.x /
+    // @vercel/otel exposes parentSpanId. Degrade to "" (root span) if neither is
+    // present, so a missing/renamed field never throws.
+    const s = span;
+    const parentSpanId = s.parentSpanContext?.spanId ?? s.parentSpanId ?? "";
+    return { traceId: sc.traceId, spanId: sc.spanId, parentSpanId };
+}
+function otelAttr(v) {
+    if (typeof v === "string" || typeof v === "number" || typeof v === "boolean")
+        return v;
+    return v === null || v === undefined ? "" : JSON.stringify(v);
+}
+function setAttrs(span, attrs) {
+    if (!span || !attrs)
+        return;
+    for (const [k, v] of Object.entries(attrs))
+        span.setAttribute(k, otelAttr(v));
+}
+/**
+ * Open a SERVER span continuing the inbound W3C traceparent (extracted from the
+ * request headers), so this service's span nests under the caller's trace. A
+ * no-op passthrough when export is off.
+ */
+export async function withOtelServerSpan(name, headers, attrs, fn) {
+    if (!otelEnabled())
+        return fn();
+    const carrier = {};
+    headers.forEach((v, k) => {
+        carrier[k] = v;
+    });
+    const parent = propagation.extract(otelContext.active(), carrier);
+    const tracer = trace.getTracer(otelName());
+    return otelContext.with(parent, () => tracer.startActiveSpan(name, { kind: SpanKind.SERVER }, async (span) => {
+        setAttrs(span, attrs);
+        try {
+            const out = await fn();
+            span.end();
+            return out;
+        }
+        catch (e) {
+            span.recordException(e);
+            span.setStatus({ code: SpanStatusCode.ERROR });
+            span.end();
+            throw e;
+        }
+    }));
+}
+/** Open a child span around a unit of work (domain story / outbound). A no-op
+ *  passthrough when export is off. */
+export async function withOtelSpan(name, attrs, fn) {
+    if (!otelEnabled())
+        return fn();
+    const tracer = trace.getTracer(otelName());
+    return tracer.startActiveSpan(name, async (span) => {
+        setAttrs(span, attrs);
+        try {
+            const out = await fn();
+            span.end();
+            return out;
+        }
+        catch (e) {
+            span.recordException(e);
+            span.setStatus({ code: SpanStatusCode.ERROR });
+            span.end();
+            throw e;
+        }
+    });
+}

package/dist/record.d.ts

@@ -0,0 +1,29 @@
+import { type ErrorInfo, type Fields, type LevelInput, type LevelName, type ObsRecord } from "./types.js";
+/** Normalise a loose level (name in any case, "warn", or a number) to a name. */
+export declare function normalizeLevel(level: LevelInput | undefined): LevelName;
+/** Turn a thrown value into the structured error.* detail (or undefined). */
+export declare function toErrorInfo(err: unknown): ErrorInfo | undefined;
+/** Build a record from the current trace context and emit it to the sinks. */
+export declare function emit(level: LevelName, logger: string, event: string | undefined, msg: string, fields?: Fields, error?: unknown): void;
+/**
+ * Test seam: capture records instead of emitting them.
+ *
+ * A test that asserts on log output should not have to configure sinks,
+ * write files or read stdout. Pass null to restore normal emission.
+ */
+export declare function setObsRecorderForTests(recorder: ((rec: ObsRecord) => void) | null): void;
+/** A trace-aware, event-first logger bound to a module name. */
+export type Logger = {
+    readonly name: string;
+    /** Generic emit with an explicit level/error (the others delegate here). */
+    event(event: string, message: string, fields?: Fields, opts?: {
+        level?: LevelInput;
+        error?: unknown;
+    }): void;
+    debug(event: string, message: string, fields?: Fields): void;
+    info(event: string, message: string, fields?: Fields): void;
+    warn(event: string, message: string, fields?: Fields, error?: unknown): void;
+    error(event: string, message: string, fields?: Fields, error?: unknown): void;
+};
+/** Return a logger for `name` (e.g. "billing.invoice", "http.client"). */
+export declare function getLogger(name: string): Logger;

package/dist/record.js

@@ -0,0 +1,93 @@
+/**
+ * Record assembly + the per-module logger.
+ *
+ * This is where a log call becomes a fully-resolved `ObsRecord`: it reads the
+ * live trace context (so every line carries trace/span ids and any bound
+ * baggage) and hands the record to the sink registry. It is the TypeScript
+ * counterpart of the agent's `obs/record.py` + the emit half of its adapter.
+ *
+ * Modules get a logger with `getLogger("<area>.<thing>")` and call event-first
+ * methods (`log.info("lab.launch.started", "launching lab ...", { lab })`) so
+ * the machine-stable event key and the human sentence always travel together.
+ */
+import { current } from "./context.js";
+import { emitToSinks } from "./sinks.js";
+import { LEVELS } from "./types.js";
+/** Normalise a loose level (name in any case, "warn", or a number) to a name. */
+export function normalizeLevel(level) {
+    if (typeof level === "number") {
+        let best = "DEBUG";
+        for (const [name, value] of Object.entries(LEVELS)) {
+            if (level >= value)
+                best = name;
+        }
+        return best;
+    }
+    const s = String(level ?? "INFO").toUpperCase();
+    if (s === "WARN")
+        return "WARNING";
+    return (s in LEVELS ? s : "INFO");
+}
+/** Turn a thrown value into the structured error.* detail (or undefined). */
+export function toErrorInfo(err) {
+    if (err === undefined || err === null)
+        return undefined;
+    if (err instanceof Error) {
+        return {
+            type: err.name || "Error",
+            message: err.message,
+            stack: err.stack,
+            code: err.code,
+        };
+    }
+    return { type: typeof err, message: String(err) };
+}
+let testRecorder = null;
+/** Build a record from the current trace context and emit it to the sinks. */
+export function emit(level, logger, event, msg, fields, error) {
+    const ctx = current();
+    const rec = {
+        tsMs: Date.now(),
+        level,
+        logger,
+        event,
+        msg: msg ?? "",
+        trace: { traceId: ctx.traceId, spanId: ctx.spanId, parentSpanId: ctx.parentSpanId },
+        baggage: ctx.baggage,
+        fields: fields ?? {},
+        error: toErrorInfo(error),
+    };
+    // Logging must never be the thing that takes a request down. A sink that
+    // throws (a full disk, a revoked permission) is swallowed here; the sink
+    // layer already self-disables a file it cannot write.
+    try {
+        if (testRecorder) {
+            testRecorder(rec);
+            return;
+        }
+        emitToSinks(rec);
+    }
+    catch {
+        /* a broken sink is not the caller's problem */
+    }
+}
+/**
+ * Test seam: capture records instead of emitting them.
+ *
+ * A test that asserts on log output should not have to configure sinks,
+ * write files or read stdout. Pass null to restore normal emission.
+ */
+export function setObsRecorderForTests(recorder) {
+    testRecorder = recorder;
+}
+/** Return a logger for `name` (e.g. "billing.invoice", "http.client"). */
+export function getLogger(name) {
+    return {
+        name,
+        event: (event, message, fields, opts) => emit(normalizeLevel(opts?.level ?? "INFO"), name, event, message, fields, opts?.error),
+        debug: (event, message, fields) => emit("DEBUG", name, event, message, fields),
+        info: (event, message, fields) => emit("INFO", name, event, message, fields),
+        warn: (event, message, fields, error) => emit("WARNING", name, event, message, fields, error),
+        error: (event, message, fields, error) => emit("ERROR", name, event, message, fields, error),
+    };
+}

package/dist/render.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The two log renderers: human-friendly "pretty" and machine "json".
+ *
+ * The line shape is a contract, not a style choice. The pretty form (the
+ * `[trace8/span8<parent8]` triplet, the single-space columns, the ` - `
+ * separator before the key=value block, the ISO8601-millisecond `Z` timestamp,
+ * the level labels) is matched by a sibling Python implementation, so a single
+ * `grep <trace8>` interleaves logs from services in both languages and they
+ * line up column-for-column. The JSON renderer emits the same key schema, so
+ * an aggregator sees one shape from all of them. Changing either is a
+ * breaking change for everything that reads these files.
+ *
+ * The field schema (defined once, here):
+ *   ts              ISO8601 UTC, millisecond precision (2026-06-28T15:42:01.118Z)
+ *   level           DEBUG | INFO | WARNING | ERROR | CRITICAL
+ *   trace_id        32 hex chars, or "" outside a trace
+ *   span_id         16 hex chars, or ""
+ *   parent_span_id  16 hex chars, or ""
+ *   logger          logger name (billing.invoice, http.client, ...)
+ *   event           machine-stable beat name, omitted when not set
+ *   msg             the human sentence
+ *   <fields>        any extra key=value the call passed (includes dur_ms on a span finish)
+ *   error.type / error.message / error.code / error.where / error.stack   on errors
+ *
+ * Rendered punctuation is plain ASCII on purpose (no em/en dashes, no fancy
+ * glyphs) so logs stay clean in journald, files, the Vercel log view, and greps.
+ */
+import type { ObsRecord } from "./types.js";
+/**
+ * Single-line, greppable output for humans, AIs, journald, and the Vercel log
+ * view. One physical line per event (an error appends an indented stack block,
+ * which is inherently multi-line). The triplet is how you read the story: the
+ * `<` points from a child span to its parent, so matching one line's parent8 to
+ * another line's span8 rebuilds the tree - across services, since the agent
+ * emits the same shape.
+ */
+export declare function renderPretty(rec: ObsRecord): string;
+/** One JSON object per line, stable schema, hand-rolled (no extra deps). */
+export declare function renderJson(rec: ObsRecord): string;