@diveinto/obs 1.0.5 → 1.1.0

package/dist/otel.js

@@ -1,26 +1,26 @@
 /**
- * Optional OpenTelemetry export. Off unless OTEL_EXPORTER_OTLP_ENDPOINT is set.
+ * OpenTelemetry: the trace engine, always; OTLP export, when an endpoint is configured.
  *
- * 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).
+ * The first-party stdout and file records are the source of truth and need no collector. The
+ * tracer runs whether or not anything is exported (otel-start.ts registers it either way), so a
+ * span's ids are the same with export on and off, and the files hold the span tree either way
+ * (spans.ts writes each span's record when it ends):
+ *   - withOtelServerSpan() makes the request's SERVER span, continuing an inbound W3C
+ *     traceparent, or names and annotates the one the framework already opened.
+ *   - withOtelSpan() opens a span for a unit of work.
+ *   - context.ts reads the active span's ids, so every record carries the ids the backend shows,
+ *     and traceHeaders() sends them on outbound calls (one trace across every hop).
+ *   - makeOtelLogSink() exports records, with their own ids, when export is on.
  *
- * @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.
+ * @opentelemetry/api is imported at module top (a small, side-effect-free facade); the SDK is
+ * imported lazily by otel-start.ts. Without a registered provider (a test, the edge runtime) the
+ * API's spans do not record and the AsyncLocalStorage ids in context.ts stand in. This file is
+ * Node-only and must never be imported by the Edge middleware.
  */
-import { context as otelContext, propagation, SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
+import { context as otelContext, propagation, ROOT_CONTEXT, SpanKind, SpanStatusCode, trace, TraceFlags, } from "@opentelemetry/api";
 import { logs, SeverityNumber } from "@opentelemetry/api-logs";
 import { obsConfig } from "./config.js";
+import { exportable } from "./spans.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
@@ -28,13 +28,13 @@ import { LEVELS } from "./types.js";
 function otelName() {
     return obsConfig().service;
 }
+/**
+ * Whether OTLP export is configured: what the log sink and the metrics read. Spans never ask; the
+ * tracer runs either way. Env-based (process-global) on purpose: Next can run instrumentation.ts in
+ * a different module context than the route handlers, so a per-module flag set by startOtel would
+ * read false in handlers.
+ */
 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.
@@ -58,10 +58,14 @@ const SEVERITY_TEXT = {
     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.
+ * A Sink that ships each obs record to the OTLP backend as a log carrying the record's own trace
+ * and span ids, not only an active span's: a record written for a span after it ended, or in work
+ * continued from a stored traceparent, still sits in its trace. Returns null when export is off.
+ *
+ * Two kinds of record stay in the files: a span's own record (the span itself is exported) and one
+ * marked `obs.local` (an export failure, which would otherwise travel over the failing exporter).
+ * What does leave passes `exportable`, and the message passes the service's `exportScrub`. The
+ * internal export fetch does not pass back through our sinks, so there is no feedback loop.
  */
 export function makeOtelLogSink() {
     if (!otelEnabled())
@@ -71,21 +75,42 @@ export function makeOtelLogSink() {
         name: "otlp",
         minLevel: LEVELS.DEBUG,
         write: (rec) => {
+            if (rec.event === "span.end" || rec.fields["obs.local"] === true)
+                return;
             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);
+                for (const [k, v] of Object.entries(src)) {
+                    if (exportable(k))
+                        attributes[k] = otelAttr(v);
+                }
             }
+            const scrub = obsConfig().exportScrub;
+            // An error's type and message ride as attributes, as they end the record in the files; the
+            // message passes the scrub the body does, since an error can quote what it failed on.
+            if (rec.error) {
+                attributes["error.type"] = rec.error.type;
+                attributes["error.message"] = scrub ? scrub(rec.error.message) : rec.error.message;
+            }
+            const ids = rec.trace;
+            const context = ids.traceId.length === 32 && ids.spanId.length === 16
+                ? trace.setSpanContext(ROOT_CONTEXT, {
+                    traceId: ids.traceId,
+                    spanId: ids.spanId,
+                    traceFlags: TraceFlags.SAMPLED,
+                    isRemote: false,
+                })
+                : undefined;
             logger.emit({
+                context,
                 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 || "",
+                body: scrub ? scrub(rec.msg || rec.event || "") : rec.msg || rec.event || "",
                 attributes,
             });
         },
@@ -96,11 +121,13 @@ export function makeOtelLogSink() {
  *  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))
+    // A span that does not record (no provider registered: a test, the edge runtime) carries its
+    // parent's ids, not ids of its own, so the AsyncLocalStorage ids stand in.
+    if (!span?.isRecording())
+        return null;
+    const sc = span.spanContext();
+    if (!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 /
@@ -122,13 +149,25 @@ function setAttrs(span, 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.
+ * The request's SERVER span. When the framework has already opened one for this request (Next.js
+ * does, continuing an inbound traceparent itself), that span is named `name` and given `attrs`,
+ * and `fn` runs in it: one SERVER span per request, never two siblings. Otherwise a SERVER span is
+ * opened here, continuing the inbound W3C traceparent extracted from the headers.
  */
 export async function withOtelServerSpan(name, headers, attrs, fn) {
-    if (!otelEnabled())
-        return fn();
+    const active = trace.getActiveSpan();
+    if (active?.isRecording() && active.kind === SpanKind.SERVER) {
+        active.updateName(name);
+        setAttrs(active, attrs);
+        try {
+            return await fn();
+        }
+        catch (e) {
+            active.recordException(e);
+            active.setStatus({ code: SpanStatusCode.ERROR });
+            throw e;
+        }
+    }
     const carrier = {};
     headers.forEach((v, k) => {
         carrier[k] = v;
@@ -150,13 +189,17 @@ export async function withOtelServerSpan(name, headers, attrs, fn) {
         }
     }));
 }
-/** 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 SPAN_KINDS = {
+    internal: SpanKind.INTERNAL,
+    server: SpanKind.SERVER,
+    client: SpanKind.CLIENT,
+    producer: SpanKind.PRODUCER,
+    consumer: SpanKind.CONSUMER,
+};
+/** Open a child span around a unit of work: internal by default, `kind` for a call out or a message. */
+export async function withOtelSpan(name, attrs, fn, kind = "internal") {
     const tracer = trace.getTracer(otelName());
-    return tracer.startActiveSpan(name, async (span) => {
+    return tracer.startActiveSpan(name, { kind: SPAN_KINDS[kind] }, async (span) => {
         setAttrs(span, attrs);
         try {
             const out = await fn();
@@ -171,3 +214,19 @@ export async function withOtelSpan(name, attrs, fn) {
         }
     });
 }
+/**
+ * Open a span that starts a trace of its own, whatever span is in force: background work, a server
+ * action. `seed` continues a trace whose ids arrived another way (a stored or forwarded context):
+ * its trace id and, as the parent, its span id.
+ */
+export async function withOtelRootSpan(name, attrs, fn, seed, kind = "internal") {
+    const parent = seed?.traceId && /^[0-9a-f]{32}$/.test(seed.traceId) && seed.parentSpanId && /^[0-9a-f]{16}$/.test(seed.parentSpanId)
+        ? trace.setSpanContext(ROOT_CONTEXT, {
+            traceId: seed.traceId,
+            spanId: seed.parentSpanId,
+            traceFlags: TraceFlags.SAMPLED,
+            isRemote: true,
+        })
+        : ROOT_CONTEXT;
+    return otelContext.with(parent, () => withOtelSpan(name, attrs, fn, kind));
+}

package/dist/record.d.ts

@@ -5,6 +5,11 @@ export declare function normalizeLevel(level: LevelInput | undefined): LevelName
 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;
+/**
+ * Emit a record whose ids are given rather than read from the current context: a span's own
+ * record, written when the span ends, wherever that happens.
+ */
+export declare function emitWith(ids: ObsRecord["trace"], baggage: Fields, level: LevelName, logger: string, event: string | undefined, msg: string, fields?: Fields, error?: unknown): void;
 /**
  * Test seam: capture records instead of emitting them.
  *

package/dist/record.js

@@ -46,14 +46,21 @@ 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();
+    emitWith({ traceId: ctx.traceId, spanId: ctx.spanId, parentSpanId: ctx.parentSpanId }, ctx.baggage, level, logger, event, msg, fields, error);
+}
+/**
+ * Emit a record whose ids are given rather than read from the current context: a span's own
+ * record, written when the span ends, wherever that happens.
+ */
+export function emitWith(ids, baggage, level, logger, event, msg, fields, error) {
     const rec = {
         tsMs: Date.now(),
         level,
         logger,
         event,
         msg: msg ?? "",
-        trace: { traceId: ctx.traceId, spanId: ctx.spanId, parentSpanId: ctx.parentSpanId },
-        baggage: ctx.baggage,
+        trace: ids,
+        baggage,
         fields: fields ?? {},
         error: toErrorInfo(error),
     };

package/dist/setup.js

@@ -12,7 +12,7 @@
  * filesystem is ephemeral or read-only.
  *
  * Env. `<PREFIX>` is the service's own `envPrefix`; the rest are generic and
- * shared, so a fleet-wide change is one value everywhere:
+ * shared, so a change across every service is one value everywhere:
  *   LOG_LEVEL                trace|debug|info|warn|error|fatal (default info)
  *   LOG_FORMAT               stdout renderer: pretty (default) | json
  *   <PREFIX>_LOG_TEXT_FILE       pretty file: 1 (default path), 0/off, or a path

package/dist/sinks.d.ts

@@ -64,7 +64,7 @@ export declare class RotatingFileWriter {
      *
      * `renameSync` overwrites without a word, so rotating twice onto the same
      * name destroys the first file. That is not theoretical: it took a whole
-     * day of the commander's records on r2d2 on 2026-09-22, when two writers
+     * day of one service's records in production on 2026-09-22, when two writers
      * in one process both rolled to `.2026-09-21`. The writers are shared now
      * and should not collide, but a second process (a restart overlapping its
      * predecessor) can still reach this line, and losing a day of logs to a

package/dist/sinks.js

@@ -28,10 +28,10 @@ import { LEVELS } from "./types.js";
  * a SECOND set of sinks for that context - a second RotatingFileWriter on
  * the same path, with its own fd and its own rotation bookkeeping.
  *
- * What that does on a real host (r2d2, 2026-09-22): at the day boundary one
- * writer renames `commander.jsonl` to `commander.jsonl.2026-09-21` and opens
- * a fresh file; the other writer's fd still points at the renamed inode, so
- * it goes on appending there. The file an operator greps stops advancing
+ * What that did in production (2026-09-22): at the day boundary one writer
+ * renamed `service.jsonl` to `service.jsonl.2026-09-21` and opened
+ * a fresh file; the other writer's fd still pointed at the renamed inode, so
+ * it went on appending there. The file an operator greps stops advancing
  * while the service is plainly still logging, and the rotated file fills
  * with records from the WRONG day. Worse, `renameSync` overwrites, so the
  * second rotation destroyed the real previous day.
@@ -172,7 +172,8 @@ export class RotatingFileWriter {
             return "";
         const iso = new Date().toISOString();
         // "hourly" -> YYYY-MM-DDTHH ; "daily" (default) -> YYYY-MM-DD. UTC, matching
-        // the agent's utc=True so rolled files are named consistently fleet-wide.
+        // the Python implementation's utc=True, so rolled files are named the same way
+        // by every service that writes this record.
         return this.rotation === "hourly" ? iso.slice(0, 13) : iso.slice(0, 10);
     }
     isSize() {
@@ -228,7 +229,7 @@ export class RotatingFileWriter {
      *
      * `renameSync` overwrites without a word, so rotating twice onto the same
      * name destroys the first file. That is not theoretical: it took a whole
-     * day of the commander's records on r2d2 on 2026-09-22, when two writers
+     * day of one service's records in production on 2026-09-22, when two writers
      * in one process both rolled to `.2026-09-21`. The writers are shared now
      * and should not collide, but a second process (a restart overlapping its
      * predecessor) can still reach this line, and losing a day of logs to a

package/dist/spans.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Spans in the files, export that can be seen, and context for work that outlives its request.
+ *
+ * Three rules shape this module:
+ *
+ *   - Every span the service cares about is written to its own files when it ends, as one
+ *     record (`event: span.end`) carrying the span's own ids, name, kind, status and duration.
+ *     A reader that has only the files (a log tool on the machine, an operator over ssh) can then
+ *     draw the same span tree an OTLP backend shows; without it, a span that logged nothing is
+ *     invisible, and every child of it reads as an orphan.
+ *   - Nothing personal or secret leaves the process. What is exported passes `exportable`; the
+ *     files keep everything, because they stay on the machine.
+ *   - Export is seen, not assumed. Counters track what was sent and what failed, a periodic
+ *     `obs.export` record says so, and a failure is logged to the files at most once a minute,
+ *     never over the exporter that is failing.
+ *
+ * The span tree's ids come from the tracer whether or not anything is exported (see
+ * otel-start.ts), so the files look the same with export on and off.
+ */
+import { SpanKind, SpanStatusCode, type Attributes, type Link, type SpanContext } from "@opentelemetry/api";
+import type { Fields } from "./types.js";
+/** The instrumentation scope of the spans this library opens itself. */
+export declare const LIBRARY_SCOPE = "@diveinto/obs";
+type HrTime = [number, number];
+/** What this module reads of an ended SDK span (sdk-trace-base's ReadableSpan, 1.x and 2.x). */
+export type EndedSpan = {
+    name: string;
+    kind: SpanKind;
+    spanContext(): SpanContext;
+    parentSpanContext?: {
+        spanId?: string;
+    };
+    parentSpanId?: string;
+    startTime: HrTime;
+    endTime: HrTime;
+    duration: HrTime;
+    status: {
+        code: SpanStatusCode;
+        message?: string;
+    };
+    attributes: Attributes;
+    links: Link[];
+    events: {
+        name: string;
+        attributes?: Attributes;
+        time: HrTime;
+        droppedAttributesCount?: number;
+    }[];
+    resource: unknown;
+    instrumentationScope?: {
+        name: string;
+        version?: string;
+    };
+    instrumentationLibrary?: {
+        name: string;
+        version?: string;
+    };
+    ended?: boolean;
+    droppedAttributesCount?: number;
+    droppedEventsCount?: number;
+    droppedLinksCount?: number;
+};
+/** The result an exporter reports: code 0 is success. */
+export type ExportResult = {
+    code: number;
+    error?: Error;
+};
+/** A span exporter, as the SDK's batch processor calls one. */
+export type SpanExporterLike = {
+    export(spans: EndedSpan[], done: (r: ExportResult) => void): void;
+    shutdown(): Promise<void>;
+    forceFlush?(): Promise<void>;
+};
+/** A log record exporter, as the SDK's batch processor calls one. */
+export type LogExporterLike = {
+    export(records: unknown[], done: (r: ExportResult) => void): void;
+    shutdown(): Promise<void>;
+    forceFlush?(): Promise<void>;
+};
+/**
+ * Whether an attribute or field may be exported: not a credential, an address, a user agent, a
+ * query, a full URL or a personal identifier, and not one the service named in `exportDenyKeys`.
+ */
+export declare function exportable(key: string): boolean;
+/** What this process wrote and sent, since it started. */
+export type ExportCounters = {
+    spansWritten: number;
+    spansExported: number;
+    spansFailed: number;
+    logsExported: number;
+    logsFailed: number;
+};
+/** The counters as they stand, a copy. */
+export declare function exportCounters(): ExportCounters;
+/**
+ * Write an `obs.export` record now and then every `everyMs`: whether export is on, and the
+ * counters. A component configured to export that has exported nothing in an hour shows it here.
+ * The timer never holds the process open.
+ */
+export declare function startExportHeartbeat(exportOn: boolean, everyMs?: number): void;
+/** Test seam: stop the heartbeat and zero the counters. */
+export declare function resetExportForTests(): void;
+/**
+ * A span exporter that sends only what may leave the process (`exportable`), counts what it sent
+ * and what failed, and notes a failure in the files. Never throws into the SDK.
+ */
+export declare class GuardedSpanExporter implements SpanExporterLike {
+    private readonly inner;
+    constructor(inner: SpanExporterLike);
+    export(spans: EndedSpan[], done: (r: ExportResult) => void): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}
+/** A log exporter that counts what it sent and what failed, as GuardedSpanExporter does. */
+export declare class GuardedLogExporter implements LogExporterLike {
+    private readonly inner;
+    constructor(inner: LogExporterLike);
+    export(records: unknown[], done: (r: ExportResult) => void): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}
+/** A W3C traceparent for a span context, always marked sampled: every trace is kept. */
+export declare function traceparentOf(sc: {
+    traceId: string;
+    spanId: string;
+}): string;
+/**
+ * A span processor that writes one `span.end` record per span it keeps (see `writtenToFile`), with
+ * the span's own trace, span and parent ids, so the record sits in the tree where the span does.
+ * The record's fields: `span.name`, `span.kind`, `span.status`, `dur_ms`, `span.scope`, the span's
+ * links as traceparents (`span.links`), an error's type and message, and up to twenty of its
+ * attributes. Errors are ERROR records, so a level filter finds a failed span.
+ */
+export declare class FileSpanProcessor {
+    onStart(): void;
+    onEnd(span: EndedSpan): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+/**
+ * The span context a W3C traceparent names, or null for one that is missing, malformed, too long,
+ * or all zeros. A stored or annotated traceparent is untrusted input: it never fails the work that
+ * reads it, it only fails to be a parent.
+ */
+export declare function spanContextFromTraceparent(value: string | null | undefined): SpanContext | null;
+/** The traceparent of the span in force, to store on a row or an object for later work; "" outside one. */
+export declare function currentTraceparent(): string;
+export type SpanKindName = "internal" | "server" | "client" | "producer" | "consumer";
+/**
+ * Run work that another process asked for, or that a request asked for and is done later, as a
+ * span of its own: a child of the stored or annotated `parent` when there is one, else a new trace;
+ * linked to every traceparent in `links` (the other requests a batch serves, the operation an
+ * object was made for). A parent that is missing or malformed starts a new trace and never fails
+ * the work. An error is recorded on the span and thrown on.
+ */
+export declare function continueFrom<T>(parent: string | null | undefined, name: string, fn: () => Promise<T> | T, opts?: {
+    kind?: SpanKindName;
+    links?: (string | null | undefined)[];
+    attributes?: Fields;
+}): Promise<T>;
+export {};