@diveinto/obs 1.0.4 → 1.1.0

package/dist/spans.js

@@ -0,0 +1,387 @@
+/**
+ * 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 { context as otelContext, ROOT_CONTEXT, SpanKind, SpanStatusCode, trace, TraceFlags, } from "@opentelemetry/api";
+import { obsConfig } from "./config.js";
+import { newSpanId, newTraceId, runWithTrace } from "./context.js";
+import { emitWith } from "./record.js";
+/** The instrumentation scope of the spans this library opens itself. */
+export const LIBRARY_SCOPE = "@diveinto/obs";
+// ---- what may leave the process ---------------------------------------------------------------
+// Keys whose values identify a person, a machine on a network, or a credential, or carry a query
+// string or a full URL (which can hold any of those). Exact OpenTelemetry semantic-convention keys
+// first, then a rule for the rest by their last word.
+const DENY_EXACT = new Set([
+    "url.full",
+    "url.query",
+    "url.path",
+    "http.url",
+    "http.target",
+    "http.path",
+    "client.address",
+    "client.port",
+    "network.peer.address",
+    "net.peer.ip",
+    "net.sock.peer.addr",
+    "http.client_ip",
+    "user_agent.original",
+    "http.user_agent",
+    "enduser.id",
+    "user.id",
+    "user.email",
+    "user.name",
+]);
+// A user agent in any spelling (`user_agent`, `user-agent`, `useragent`, `http.user.agent`).
+const DENY_LAST_WORD = /(^|[._-])(token|password|passwd|secret|authorization|cookie|kubeconfig|email|sub|subject|ip|referer|referrer|user[._-]?agent|query)$/i;
+/**
+ * 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 function exportable(key) {
+    if (DENY_EXACT.has(key) || DENY_LAST_WORD.test(key))
+        return false;
+    return !obsConfig().exportDenyKeys.includes(key);
+}
+function exportableAttributes(attrs) {
+    const out = {};
+    if (!attrs)
+        return out;
+    for (const [k, v] of Object.entries(attrs)) {
+        if (exportable(k))
+            out[k] = v;
+    }
+    return out;
+}
+/**
+ * The span as it may leave the process: the same span with every attribute `exportable` refuses
+ * removed, on the span, its events and its links. A plain object rather than a wrapper around the
+ * SDK's span, so nothing in the exporter reaches back into the original's private state.
+ */
+function forExport(span) {
+    const sc = span.spanContext();
+    return {
+        name: span.name,
+        kind: span.kind,
+        spanContext: () => sc,
+        parentSpanContext: span.parentSpanContext,
+        parentSpanId: span.parentSpanId,
+        startTime: span.startTime,
+        endTime: span.endTime,
+        duration: span.duration,
+        status: span.status,
+        attributes: exportableAttributes(span.attributes),
+        links: span.links.map((l) => ({ ...l, attributes: exportableAttributes(l.attributes) })),
+        events: span.events.map((e) => ({ ...e, attributes: exportableAttributes(e.attributes) })),
+        resource: span.resource,
+        instrumentationScope: span.instrumentationScope,
+        instrumentationLibrary: span.instrumentationLibrary,
+        ended: span.ended,
+        droppedAttributesCount: span.droppedAttributesCount,
+        droppedEventsCount: span.droppedEventsCount,
+        droppedLinksCount: span.droppedLinksCount,
+    };
+}
+const counters = {
+    spansWritten: 0,
+    spansExported: 0,
+    spansFailed: 0,
+    logsExported: 0,
+    logsFailed: 0,
+};
+/** The counters as they stand, a copy. */
+export function exportCounters() {
+    return { ...counters };
+}
+// The process's own trace, for the records this module writes outside any request: the heartbeat
+// and an export failure. A record with no trace id at all reads as a component that lost its
+// tracing, so they carry this one. Minted on first use, never at import: this module sits in an
+// import cycle (records, context, the tracer), and must do nothing while it loads.
+let processTrace;
+function processIds() {
+    processTrace ??= { traceId: newTraceId(), spanId: newSpanId(), parentSpanId: "" };
+    return processTrace;
+}
+const FAILURE_EVERY_MS = 60_000;
+let lastFailureAt = 0;
+/**
+ * Note an export failure in the files, at most once a minute, and never over OTLP: a failure
+ * logged through the exporter that failed would only make another.
+ */
+function noteFailure(signal, error) {
+    const now = Date.now();
+    if (now - lastFailureAt < FAILURE_EVERY_MS)
+        return;
+    lastFailureAt = now;
+    emitWith(processIds(), {}, "WARNING", "obs", "obs.export_failed", `exporting ${signal} failed; the files are complete and export carries on trying`, { "obs.local": true, signal, ...counters }, error);
+}
+let heartbeat;
+/**
+ * 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 function startExportHeartbeat(exportOn, everyMs = 60_000) {
+    const beat = () => emitWith(processIds(), {}, "INFO", "obs", "obs.export", exportOn
+        ? `export on: ${counters.spansExported} span(s) and ${counters.logsExported} log(s) sent, ${counters.spansFailed + counters.logsFailed} failed`
+        : `export off: ${counters.spansWritten} span(s) written to the files only`, { "obs.export": exportOn ? "on" : "off", ...counters });
+    if (heartbeat)
+        clearInterval(heartbeat);
+    beat();
+    if (!exportOn)
+        return;
+    heartbeat = setInterval(beat, everyMs);
+    heartbeat.unref?.();
+}
+/** Test seam: stop the heartbeat and zero the counters. */
+export function resetExportForTests() {
+    if (heartbeat)
+        clearInterval(heartbeat);
+    heartbeat = undefined;
+    lastFailureAt = 0;
+    for (const k of Object.keys(counters))
+        counters[k] = 0;
+}
+/**
+ * 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 class GuardedSpanExporter {
+    inner;
+    constructor(inner) {
+        this.inner = inner;
+    }
+    export(spans, done) {
+        const settle = (r) => {
+            if (r.code === 0)
+                counters.spansExported += spans.length;
+            else {
+                counters.spansFailed += spans.length;
+                noteFailure("spans", r.error);
+            }
+            done(r);
+        };
+        try {
+            this.inner.export(spans.map(forExport), settle);
+        }
+        catch (e) {
+            settle({ code: 1, error: e });
+        }
+    }
+    shutdown() {
+        return this.inner.shutdown();
+    }
+    forceFlush() {
+        return this.inner.forceFlush?.() ?? Promise.resolve();
+    }
+}
+/** A log exporter that counts what it sent and what failed, as GuardedSpanExporter does. */
+export class GuardedLogExporter {
+    inner;
+    constructor(inner) {
+        this.inner = inner;
+    }
+    export(records, done) {
+        const settle = (r) => {
+            if (r.code === 0)
+                counters.logsExported += records.length;
+            else {
+                counters.logsFailed += records.length;
+                noteFailure("logs", r.error);
+            }
+            done(r);
+        };
+        try {
+            this.inner.export(records, settle);
+        }
+        catch (e) {
+            settle({ code: 1, error: e });
+        }
+    }
+    shutdown() {
+        return this.inner.shutdown();
+    }
+    forceFlush() {
+        return this.inner.forceFlush?.() ?? Promise.resolve();
+    }
+}
+// ---- spans into the files ---------------------------------------------------------------------
+const KIND_NAMES = {
+    [SpanKind.INTERNAL]: "internal",
+    [SpanKind.SERVER]: "server",
+    [SpanKind.CLIENT]: "client",
+    [SpanKind.PRODUCER]: "producer",
+    [SpanKind.CONSUMER]: "consumer",
+};
+const STATUS_NAMES = {
+    [SpanStatusCode.UNSET]: "unset",
+    [SpanStatusCode.OK]: "ok",
+    [SpanStatusCode.ERROR]: "error",
+};
+/** The most attributes a span.end record carries, so one span never makes a huge line. */
+const RECORD_ATTRIBUTES = 20;
+function hrMillis(t) {
+    return t[0] * 1000 + t[1] / 1e6;
+}
+/** A W3C traceparent for a span context, always marked sampled: every trace is kept. */
+export function traceparentOf(sc) {
+    return `00-${sc.traceId}-${sc.spanId}-01`;
+}
+function scopeOf(span) {
+    return span.instrumentationScope?.name ?? span.instrumentationLibrary?.name ?? "";
+}
+/**
+ * Whether a span is written to the files: every span at a process boundary (server, client,
+ * producer, consumer), and the internal spans this service and this library open. A framework's
+ * own internal spans (a page render, a module resolution) stay in the backend: they are many, and
+ * not the story of the request.
+ */
+function writtenToFile(span) {
+    if (span.kind !== SpanKind.INTERNAL)
+        return true;
+    const scope = scopeOf(span);
+    return scope === obsConfig().service || scope === LIBRARY_SCOPE;
+}
+/**
+ * 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 class FileSpanProcessor {
+    onStart() { }
+    onEnd(span) {
+        try {
+            if (!writtenToFile(span))
+                return;
+            const sc = span.spanContext();
+            const parent = span.parentSpanContext?.spanId ?? span.parentSpanId ?? "";
+            const ms = Math.round(hrMillis(span.duration) * 10) / 10;
+            const status = STATUS_NAMES[span.status.code] ?? "unset";
+            const fields = {
+                "span.name": span.name,
+                "span.kind": KIND_NAMES[span.kind] ?? "internal",
+                "span.status": status,
+                dur_ms: ms,
+                "span.scope": scopeOf(span),
+            };
+            if (span.links.length > 0) {
+                fields["span.links"] = span.links.map((l) => traceparentOf(l.context)).join(",");
+            }
+            const exception = span.events.find((e) => e.name === "exception");
+            if (status === "error") {
+                fields["error.type"] = String(exception?.attributes?.["exception.type"] ?? "error");
+                fields["error.message"] = String(exception?.attributes?.["exception.message"] ?? span.status.message ?? "");
+            }
+            let n = 0;
+            for (const [k, v] of Object.entries(span.attributes)) {
+                if (n >= RECORD_ATTRIBUTES)
+                    break;
+                if (k in fields || v === undefined || typeof v === "object")
+                    continue;
+                fields[k] = v;
+                n++;
+            }
+            counters.spansWritten++;
+            emitWith({ traceId: sc.traceId, spanId: sc.spanId, parentSpanId: parent }, {}, status === "error" ? "ERROR" : "INFO", "span", "span.end", `${span.name} ${status} in ${ms} ms`, fields);
+        }
+        catch {
+            /* a span the processor cannot read is not the request's problem */
+        }
+    }
+    forceFlush() {
+        return Promise.resolve();
+    }
+    shutdown() {
+        return Promise.resolve();
+    }
+}
+// ---- context for work that outlives its request -----------------------------------------------
+const TRACEPARENT = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+/**
+ * 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 function spanContextFromTraceparent(value) {
+    if (!value || value.length > 55)
+        return null;
+    const m = TRACEPARENT.exec(value.trim());
+    const traceId = m?.[1];
+    const spanId = m?.[2];
+    if (!traceId || !spanId || /^0+$/.test(traceId) || /^0+$/.test(spanId))
+        return null;
+    return { traceId, spanId, traceFlags: TraceFlags.SAMPLED, isRemote: true };
+}
+/** The traceparent of the span in force, to store on a row or an object for later work; "" outside one. */
+export function currentTraceparent() {
+    const span = trace.getActiveSpan();
+    if (span?.isRecording())
+        return traceparentOf(span.spanContext());
+    return "";
+}
+const KINDS = {
+    internal: SpanKind.INTERNAL,
+    server: SpanKind.SERVER,
+    client: SpanKind.CLIENT,
+    producer: SpanKind.PRODUCER,
+    consumer: SpanKind.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 async function continueFrom(parent, name, fn, opts) {
+    const sc = spanContextFromTraceparent(parent);
+    const ctx = sc ? trace.setSpanContext(ROOT_CONTEXT, sc) : ROOT_CONTEXT;
+    const links = [];
+    for (const l of opts?.links ?? []) {
+        const lc = spanContextFromTraceparent(l);
+        if (lc)
+            links.push({ context: lc });
+    }
+    const attributes = {};
+    for (const [k, v] of Object.entries(opts?.attributes ?? {})) {
+        if (v !== undefined && v !== null && typeof v !== "object")
+            attributes[k] = v;
+    }
+    const tracer = trace.getTracer(LIBRARY_SCOPE);
+    return otelContext.with(ctx, () => tracer.startActiveSpan(name, { kind: KINDS[opts?.kind ?? "internal"], links, attributes }, async (span) => {
+        // Without a tracer provider (a test, an edge runtime) the span does not record; the work
+        // still gets ids of its own, continuing the parent's trace.
+        const run = () => fn();
+        const body = span.isRecording()
+            ? run
+            : () => runWithTrace({ traceId: sc?.traceId, parentSpanId: sc?.spanId }, run);
+        try {
+            const out = await body();
+            span.end();
+            return out;
+        }
+        catch (e) {
+            span.recordException(e);
+            span.setStatus({ code: SpanStatusCode.ERROR, message: e?.message });
+            span.end();
+            throw e;
+        }
+    }));
+}

package/dist/types.js

@@ -9,7 +9,7 @@
  */
 // Severity vocabulary + numeric ordering. Matches the agent's stdlib levels
 // (DEBUG < INFO < WARNING < ERROR < CRITICAL) so a LOG_LEVEL floor means the
-// same thing on both sides of the fleet.
+// same thing in either language.
 export const LEVELS = {
     DEBUG: 10,
     INFO: 20,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diveinto/obs",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "Structured logging, tracing and metrics for Next.js and Node services: one record shape, rotating files, W3C trace context, optional OpenTelemetry export",
   "license": "MIT",
   "private": false,
@@ -39,11 +39,12 @@
   },
   "peerDependencies": {
     "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/api-logs": "^0.219.0",
-    "@opentelemetry/exporter-logs-otlp-proto": "^0.219.0",
+    "@opentelemetry/api-logs": ">=0.200.0 <0.300.0",
+    "@opentelemetry/exporter-logs-otlp-proto": ">=0.200.0 <0.300.0",
     "@opentelemetry/resources": "^2.0.0",
-    "@opentelemetry/sdk-logs": "^0.219.0",
-    "@vercel/otel": "^2.1.3"
+    "@opentelemetry/sdk-logs": ">=0.200.0 <0.300.0",
+    "@vercel/otel": "^2.1.3",
+    "@opentelemetry/sdk-trace-base": "^2.0.0"
   },
   "peerDependenciesMeta": {
     "@opentelemetry/exporter-logs-otlp-proto": {
@@ -57,6 +58,9 @@
     },
     "@opentelemetry/resources": {
       "optional": true
+    },
+    "@opentelemetry/sdk-trace-base": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -68,7 +72,8 @@
     "@types/node": "^22.10.2",
     "@vercel/otel": "^2.1.3",
     "typescript": "^5.7.2",
-    "vitest": "^3.0.5"
+    "vitest": "^3.0.5",
+    "@opentelemetry/sdk-trace-base": "^2.11.0"
   },
   "allowScripts": {
     "esbuild@0.28.2": true