@diveinto/obs 1.0.1

package/dist/render.js

@@ -0,0 +1,131 @@
+// Keys the schema owns. A user field that collides with one of these is renamed
+// with a trailing underscore rather than silently clobbering the structural
+// field (a `level` field must not overwrite the record's level).
+const RESERVED = new Set([
+    "ts",
+    "level",
+    "trace_id",
+    "span_id",
+    "parent_span_id",
+    "logger",
+    "event",
+    "msg",
+]);
+// Short, fixed-width-vocabulary level labels for the pretty line. Not padded:
+// every field is separated by exactly one space, so a padded label would make
+// the spacing look uneven. (The JSON renderer keeps the full level name.)
+const LEVEL_LABEL = {
+    DEBUG: "DEBUG",
+    INFO: "INFO",
+    WARNING: "WARN",
+    ERROR: "ERROR",
+    CRITICAL: "CRIT",
+};
+// Separator between the human message and the key=value fields - one clear,
+// consistent break instead of an ambiguous run of spaces. A colon would clash
+// with the "event: message" colon, so a spaced hyphen reads cleanest. This is
+// the same constant the agent uses, so both services' lines break identically.
+const FIELD_SEP = " - ";
+// Placeholder for an empty (missing) id, kept ASCII and 8 chars wide so the
+// trace/span/parent triplet stays column-aligned even on un-traced lines.
+const EMPTY_ID = ".".repeat(8);
+/**
+ * Format an epoch-ms timestamp as ISO8601 UTC with millisecond precision.
+ * `Date.toISOString()` already yields exactly `YYYY-MM-DDTHH:MM:SS.mmmZ`, which
+ * matches the agent's hand-built format byte-for-byte.
+ */
+function tsIso(ms) {
+    return new Date(ms).toISOString();
+}
+/** Baggage + per-call fields flattened, with reserved keys protected. */
+function mergedFields(rec) {
+    const out = {};
+    for (const src of [rec.baggage, rec.fields]) {
+        for (const [k, v] of Object.entries(src)) {
+            out[RESERVED.has(k) ? `${k}_` : k] = v;
+        }
+    }
+    return out;
+}
+/** Render one field value: quote strings only when whitespace would split the
+ *  token, JSON-encode objects/arrays, and stringify everything else. */
+function renderVal(v) {
+    if (typeof v === "string") {
+        return v.includes(" ") || v === "" ? `"${v}"` : v;
+    }
+    if (v !== null && typeof v === "object") {
+        return JSON.stringify(v);
+    }
+    return String(v);
+}
+function renderKv(fields) {
+    return Object.entries(fields)
+        .map(([k, v]) => `${k}=${renderVal(v)}`)
+        .join(" ");
+}
+function errorFields(e) {
+    const out = { "error.type": e.type, "error.message": e.message };
+    if (e.where)
+        out["error.where"] = e.where;
+    if (e.code !== undefined && e.code !== null)
+        out["error.code"] = e.code;
+    if (e.stack)
+        out["error.stack"] = e.stack;
+    return out;
+}
+function renderErrorBlock(e) {
+    const lines = [];
+    let head = `    error: ${e.type}: ${e.message}`;
+    if (e.code !== undefined && e.code !== null)
+        head += ` (code=${e.code})`;
+    lines.push(head);
+    if (e.where)
+        lines.push(`    at ${e.where}`);
+    if (e.stack) {
+        for (const s of e.stack.replace(/\s+$/, "").split("\n"))
+            lines.push(`    ${s}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * 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 function renderPretty(rec) {
+    const t8 = (rec.trace.traceId || "").slice(0, 8) || EMPTY_ID;
+    const s8 = (rec.trace.spanId || "").slice(0, 8) || EMPTY_ID;
+    const p8 = (rec.trace.parentSpanId || "").slice(0, 8) || EMPTY_ID;
+    const level = LEVEL_LABEL[rec.level] ?? rec.level;
+    const body = rec.event && rec.msg ? `${rec.event}: ${rec.msg}` : rec.event || rec.msg;
+    // Exactly one space between every field, so the spacing is uniform across the
+    // whole line (timestamp, level, triplet, logger, event/message, then fields).
+    let line = `${tsIso(rec.tsMs)} ${level} [${t8}/${s8}<${p8}] ${rec.logger} ${body}`;
+    const kv = renderKv(mergedFields(rec));
+    if (kv)
+        line += `${FIELD_SEP}${kv}`;
+    if (rec.error)
+        line += "\n" + renderErrorBlock(rec.error);
+    return line;
+}
+/** One JSON object per line, stable schema, hand-rolled (no extra deps). */
+export function renderJson(rec) {
+    const out = {
+        ts: tsIso(rec.tsMs),
+        level: rec.level,
+        trace_id: rec.trace.traceId,
+        span_id: rec.trace.spanId,
+        parent_span_id: rec.trace.parentSpanId,
+        logger: rec.logger,
+        msg: rec.msg,
+    };
+    if (rec.event)
+        out.event = rec.event;
+    Object.assign(out, mergedFields(rec));
+    if (rec.error)
+        Object.assign(out, errorFields(rec.error));
+    return JSON.stringify(out);
+}

package/dist/setup.d.ts

@@ -0,0 +1,21 @@
+/** True on Vercel / AWS Lambda: no persistent, writable filesystem for files. */
+export declare function isServerless(): boolean;
+/** One file sink's resolved settings, or null when it is switched off. */
+export type FileTarget = {
+    path: string;
+    rotation: string;
+    retention: number;
+};
+/**
+ * Resolve where the two files go, as a pure function of the environment so it
+ * can be tested without touching the filesystem. Defaults land under
+ * <state dir>/logs; every deploy's env points both at
+ * /var/log/<service>/ instead.
+ */
+export declare function resolveFileTargets(env?: NodeJS.ProcessEnv): {
+    text: FileTarget | null;
+    json: FileTarget | null;
+};
+/** Test seam: let a test re-run setupLogging() with a different environment. */
+export declare function resetLoggingForTests(): void;
+export declare function setupLogging(): void;

package/dist/setup.js

@@ -0,0 +1,150 @@
+/**
+ * One-call wiring: setupLogging().
+ *
+ * Called once from the app's `instrumentation.ts` (Next's `register()` boot
+ * hook) on the Node.js runtime, after `configure()`. Idempotent, because Next
+ * calls `register()` more than once across HMR and dev.
+ *
+ * Runtime portability is the load-bearing concern: a service may run
+ * self-hosted under systemd AND on Vercel. stdout is ALWAYS wired (journald
+ * captures it self-hosted; Vercel ships it from its log pipeline). The two
+ * rotating files are wired only when self-hosted, because a serverless
+ * 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:
+ *   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
+ *   <PREFIX>_LOG_TEXT_ROTATION   daily (default) | hourly | <N>MB
+ *   <PREFIX>_LOG_TEXT_RETENTION  rotated files to keep (default 14)
+ *   <PREFIX>_LOG_JSON_FILE / _ROTATION / _RETENTION   same, for the json file
+ *   <PREFIX>_VAR_DIR             state dir (default /var/lib/<service>)
+ */
+import { join } from "node:path";
+import { logEvent } from "./api.js";
+import { obsConfig } from "./config.js";
+import { makeOtelLogSink, otelEnabled } from "./otel.js";
+import { renderJson, renderPretty } from "./render.js";
+import { configureSinks, makeFileSink, makeStdoutSink, setSinkInitializer } from "./sinks.js";
+import { LEVELS } from "./types.js";
+let configured = false;
+// Register lazy self-init: the first log emitted in any module context (Next
+// can isolate the instrumentation hook from the route handlers) runs
+// setupLogging for THAT context, so request and domain logs are never
+// silently dropped.
+setSinkInitializer(() => setupLogging());
+/** True on Vercel / AWS Lambda: no persistent, writable filesystem for files. */
+export function isServerless() {
+    return !!(process.env.VERCEL || process.env.AWS_LAMBDA_FUNCTION_NAME);
+}
+function stateDir(env) {
+    const cfg = obsConfig();
+    return env[`${cfg.envPrefix}_VAR_DIR`] || cfg.defaultVarDir;
+}
+/**
+ * Resolve where the two files go, as a pure function of the environment so it
+ * can be tested without touching the filesystem. Defaults land under
+ * <state dir>/logs; every deploy's env points both at
+ * /var/log/<service>/ instead.
+ */
+export function resolveFileTargets(env = process.env) {
+    const cfg = obsConfig();
+    const p = cfg.envPrefix;
+    const dir = join(stateDir(env), "logs");
+    const text = fileSetting(env[`${p}_LOG_TEXT_FILE`]);
+    const jsonFile = fileSetting(env[`${p}_LOG_JSON_FILE`]);
+    return {
+        text: text
+            ? {
+                path: text === true ? join(dir, `${cfg.fileStem}.log`) : text,
+                rotation: (env[`${p}_LOG_TEXT_ROTATION`] || "daily").trim(),
+                retention: toInt(env[`${p}_LOG_TEXT_RETENTION`], 14),
+            }
+            : null,
+        json: jsonFile
+            ? {
+                path: jsonFile === true ? join(dir, `${cfg.fileStem}.jsonl`) : jsonFile,
+                rotation: (env[`${p}_LOG_JSON_ROTATION`] || "daily").trim(),
+                retention: toInt(env[`${p}_LOG_JSON_RETENTION`], 14),
+            }
+            : null,
+    };
+}
+function resolveLevel() {
+    const raw = (process.env.LOG_LEVEL || "info").trim().toUpperCase();
+    const map = {
+        TRACE: LEVELS.DEBUG,
+        DEBUG: LEVELS.DEBUG,
+        INFO: LEVELS.INFO,
+        WARN: LEVELS.WARNING,
+        WARNING: LEVELS.WARNING,
+        ERROR: LEVELS.ERROR,
+        FATAL: LEVELS.CRITICAL,
+        CRITICAL: LEVELS.CRITICAL,
+    };
+    return map[raw] ?? LEVELS.INFO;
+}
+function toInt(raw, fallback) {
+    const n = parseInt(String(raw ?? ""), 10);
+    return Number.isFinite(n) ? n : fallback;
+}
+/** Resolve a *_FILE env value: false (off), true (default path), or a path. */
+function fileSetting(raw) {
+    const s = (raw ?? "1").trim();
+    const lower = s.toLowerCase();
+    if (["", "0", "off", "no", "false"].includes(lower))
+        return false;
+    if (["1", "on", "yes", "true", "default"].includes(lower))
+        return true;
+    return s;
+}
+/** Test seam: let a test re-run setupLogging() with a different environment. */
+export function resetLoggingForTests() {
+    configured = false;
+}
+export function setupLogging() {
+    if (configured)
+        return;
+    configured = true;
+    const level = resolveLevel();
+    const stdoutFormat = (process.env.LOG_FORMAT || "pretty").trim().toLowerCase() === "json" ? "json" : "pretty";
+    // stdout is always on; its renderer follows LOG_FORMAT.
+    const sinks = [
+        makeStdoutSink(stdoutFormat === "json" ? renderJson : renderPretty, stdoutFormat),
+    ];
+    // The two rotating files are self-hosted only. They are format-locked
+    // (<stem>.log = pretty, <stem>.jsonl = json) regardless of LOG_FORMAT, so
+    // each file is always what its name promises.
+    const serverless = isServerless();
+    if (!serverless) {
+        const targets = resolveFileTargets();
+        if (targets.text) {
+            sinks.push(makeFileSink(targets.text.path, "pretty", renderPretty, targets.text.rotation, targets.text.retention));
+        }
+        if (targets.json) {
+            sinks.push(makeFileSink(targets.json.path, "json", renderJson, targets.json.rotation, targets.json.retention));
+        }
+    }
+    // When OTLP export is on, also ship logs to the backend's Logs view
+    // (trace-correlated), alongside stdout and the files.
+    if (otelEnabled()) {
+        const otelSink = makeOtelLogSink();
+        if (otelSink)
+            sinks.push(otelSink);
+    }
+    configureSinks(sinks, level);
+    const targets = sinks.map((s) => s.describe?.().target ?? s.name).join(", ");
+    // OTLP export is started from instrumentation.ts (registerOTel sets the
+    // global provider process-wide); here we only report whether it is on.
+    const otel = otelEnabled();
+    logEvent("obs.boot", `logging up: service=${obsConfig().service}, ` +
+        `mode=${serverless ? "serverless" : "self-hosted"}, ` +
+        `format=${stdoutFormat}, sinks=[${targets}], otel=${otel ? "on" : "off"}`, {
+        service: obsConfig().service,
+        mode: serverless ? "serverless" : "self-hosted",
+        format: stdoutFormat,
+        sink_count: sinks.length,
+        otel,
+    }, { logger: "obs" });
+}

package/dist/sinks.d.ts

@@ -0,0 +1,46 @@
+import { type ObsRecord, type Sink } from "./types.js";
+export declare function configureSinks(sinks: Sink[], threshold: number): void;
+export declare function setSinkInitializer(fn: () => void): void;
+export declare function setThreshold(threshold: number): void;
+export declare function activeSinks(): Sink[];
+/** Dispatch one record to every eligible sink. Sinks swallow their own I/O
+ *  errors, but we belt-and-brace with a try/catch so logging never throws into
+ *  application code. */
+export declare function emitToSinks(rec: ObsRecord): void;
+/** A stdout sink in the given format. Stdout is always present: journald
+ *  captures it self-hosted, and Vercel ships it serverless. */
+export declare function makeStdoutSink(render: (rec: ObsRecord) => string, format: string): Sink;
+/**
+ * A rotating append-only file writer.
+ *
+ * `rotation` is "daily" (UTC midnight) or "hourly" for time-based rolling, or
+ * "<N>MB" for size-based; `retention` is how many rotated files to keep. Time
+ * rotation renames `path` to `path.<period>` when the period changes; size
+ * rotation shifts `path.{N-1} -> path.N`. On any fs error the writer disables
+ * itself and reports once on stderr.
+ */
+export declare class RotatingFileWriter {
+    private readonly path;
+    private readonly rotation;
+    private readonly retention;
+    private readonly render;
+    private stream;
+    private bytes;
+    private periodKey;
+    private disabled;
+    constructor(path: string, rotation: string, retention: number, render: (rec: ObsRecord) => string);
+    private open;
+    /** The bucket key for time-based rotation (empty for size-based). */
+    private currentPeriod;
+    private isSize;
+    write(rec: ObsRecord): void;
+    private maybeRotate;
+    private rotateTime;
+    private rotateSize;
+    /** Delete rotated files beyond `retention` (time-based keeps the newest by
+     *  their date-sortable suffix). */
+    private prune;
+    private fail;
+}
+/** Build a file `Sink` wrapping a `RotatingFileWriter`. */
+export declare function makeFileSink(path: string, format: string, render: (rec: ObsRecord) => string, rotation: string, retention: number): Sink;

package/dist/sinks.js

@@ -0,0 +1,243 @@
+/**
+ * Sink registry + the zero-dependency rotating file writer.
+ *
+ * A "sink" is one destination for log records: stdout (captured by journald
+ * self-hosted, or shipped by Vercel serverless) or a rotating file. The global
+ * LOG_LEVEL floor is applied here once, then each record is handed to every
+ * sink whose own minimum level it clears.
+ *
+ * The `RotatingFileWriter` is a small port of the agent's
+ * `TimedRotatingFileHandler` / `RotatingFileHandler` behaviour over `node:fs`,
+ * so we keep zero new dependencies. It NEVER crashes the app: a failed mkdir or
+ * write disables that one file and logs a note to stderr, leaving stdout (and
+ * the other file) running - the same degrade-don't-crash contract as the agent.
+ *
+ * This module is Node-only (it imports `node:fs`); it is reached solely through
+ * `setup.ts`, which only runs in the Node runtime.
+ */
+import { createWriteStream, mkdirSync, readdirSync, renameSync, statSync, unlinkSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { LEVELS } from "./types.js";
+// The active sinks and the global level floor. Mutable so a future live-level
+// endpoint can raise/lower the floor without a restart (mirrors the agent's
+// PUT /v1/system/logging).
+let SINKS = [];
+let THRESHOLD = LEVELS.INFO;
+export function configureSinks(sinks, threshold) {
+    SINKS = sinks;
+    THRESHOLD = threshold;
+}
+// Lazy self-initialization. Next.js can bundle instrumentation.ts (which calls
+// setupLogging) in a SEPARATE module graph from the route handlers, so a route
+// handler may reach this module with SINKS still empty. setup.ts registers
+// setupLogging here; the first emit in any context then configures the sinks for
+// THAT context. Without this, only the instrumentation-context boot line is ever
+// written - request/domain logs from the handler context would silently vanish.
+let initializer = null;
+let initAttempted = false;
+export function setSinkInitializer(fn) {
+    initializer = fn;
+}
+export function setThreshold(threshold) {
+    THRESHOLD = threshold;
+}
+export function activeSinks() {
+    return SINKS;
+}
+/** Dispatch one record to every eligible sink. Sinks swallow their own I/O
+ *  errors, but we belt-and-brace with a try/catch so logging never throws into
+ *  application code. */
+export function emitToSinks(rec) {
+    // Configure this module context's sinks on first use (see setSinkInitializer).
+    if (SINKS.length === 0 && initializer && !initAttempted) {
+        initAttempted = true;
+        initializer();
+    }
+    const lvl = LEVELS[rec.level];
+    if (lvl < THRESHOLD)
+        return;
+    for (const sink of SINKS) {
+        if (lvl < sink.minLevel)
+            continue;
+        try {
+            sink.write(rec);
+        }
+        catch {
+            /* a broken sink must not break the request */
+        }
+    }
+}
+/** A stdout sink in the given format. Stdout is always present: journald
+ *  captures it self-hosted, and Vercel ships it serverless. */
+export function makeStdoutSink(render, format) {
+    return {
+        name: "stdout",
+        minLevel: LEVELS.DEBUG,
+        write: (rec) => process.stdout.write(render(rec) + "\n"),
+        describe: () => ({ type: "stdout", target: "stdout", format }),
+    };
+}
+/**
+ * A rotating append-only file writer.
+ *
+ * `rotation` is "daily" (UTC midnight) or "hourly" for time-based rolling, or
+ * "<N>MB" for size-based; `retention` is how many rotated files to keep. Time
+ * rotation renames `path` to `path.<period>` when the period changes; size
+ * rotation shifts `path.{N-1} -> path.N`. On any fs error the writer disables
+ * itself and reports once on stderr.
+ */
+export class RotatingFileWriter {
+    path;
+    rotation;
+    retention;
+    render;
+    stream = null;
+    bytes = 0;
+    periodKey = "";
+    disabled = false;
+    constructor(path, rotation, retention, render) {
+        this.path = path;
+        this.rotation = rotation;
+        this.retention = retention;
+        this.render = render;
+        try {
+            mkdirSync(dirname(path), { recursive: true });
+            this.open();
+        }
+        catch (e) {
+            this.fail(e);
+        }
+    }
+    open() {
+        this.stream = createWriteStream(this.path, { flags: "a" });
+        try {
+            this.bytes = statSync(this.path).size;
+        }
+        catch {
+            this.bytes = 0;
+        }
+        this.periodKey = this.currentPeriod();
+    }
+    /** The bucket key for time-based rotation (empty for size-based). */
+    currentPeriod() {
+        if (this.isSize())
+            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.
+        return this.rotation === "hourly" ? iso.slice(0, 13) : iso.slice(0, 10);
+    }
+    isSize() {
+        return this.rotation.toLowerCase().endsWith("mb");
+    }
+    write(rec) {
+        if (this.disabled || !this.stream)
+            return;
+        try {
+            const line = this.render(rec) + "\n";
+            const size = Buffer.byteLength(line);
+            this.maybeRotate(size);
+            this.stream.write(line);
+            this.bytes += size;
+        }
+        catch (e) {
+            this.fail(e);
+        }
+    }
+    maybeRotate(incoming) {
+        if (this.isSize()) {
+            const maxBytes = (parseInt(this.rotation, 10) || 100) * 1024 * 1024;
+            if (this.bytes > 0 && this.bytes + incoming > maxBytes)
+                this.rotateSize();
+        }
+        else {
+            const now = this.currentPeriod();
+            if (this.periodKey && now !== this.periodKey)
+                this.rotateTime(this.periodKey);
+        }
+    }
+    rotateTime(prevKey) {
+        this.stream?.end();
+        try {
+            renameSync(this.path, `${this.path}.${prevKey}`);
+        }
+        catch {
+            /* if the rename fails we just keep appending to the same file */
+        }
+        this.open();
+        this.prune();
+    }
+    rotateSize() {
+        this.stream?.end();
+        // Shift path.{retention-1} -> path.{retention} ... path.1 -> path.2, then
+        // path -> path.1. renameSync overwrites, so the count stays bounded.
+        for (let i = this.retention - 1; i >= 1; i--) {
+            try {
+                renameSync(`${this.path}.${i}`, `${this.path}.${i + 1}`);
+            }
+            catch {
+                /* a gap is harmless */
+            }
+        }
+        try {
+            renameSync(this.path, `${this.path}.1`);
+        }
+        catch {
+            /* nothing to roll yet */
+        }
+        this.open();
+        this.prune();
+    }
+    /** Delete rotated files beyond `retention` (time-based keeps the newest by
+     *  their date-sortable suffix). */
+    prune() {
+        try {
+            const dir = dirname(this.path);
+            const base = basename(this.path) + ".";
+            const rotated = readdirSync(dir)
+                .filter((f) => f.startsWith(base))
+                .sort();
+            const excess = rotated.length - this.retention;
+            for (let i = 0; i < excess; i++) {
+                const stale = rotated[i];
+                if (!stale)
+                    continue;
+                try {
+                    unlinkSync(join(dir, stale));
+                }
+                catch {
+                    /* best effort */
+                }
+            }
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    fail(e) {
+        this.disabled = true;
+        this.stream = null;
+        try {
+            process.stderr.write(`[obs] file sink ${this.path} disabled (${String(e)}); stdout still active\n`);
+        }
+        catch {
+            /* nothing more we can do */
+        }
+    }
+}
+/** Build a file `Sink` wrapping a `RotatingFileWriter`. */
+export function makeFileSink(path, format, render, rotation, retention) {
+    const writer = new RotatingFileWriter(path, rotation, retention, render);
+    return {
+        name: basename(path),
+        minLevel: LEVELS.DEBUG,
+        write: (rec) => writer.write(rec),
+        describe: () => ({
+            type: "file",
+            target: path,
+            format,
+            rotation,
+            retention,
+        }),
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Shared shapes for the obs logging framework.
+ *
+ * Kept dependency-free and tiny so every other obs module (and the unit
+ * tests) can import these types without pulling in Node-only code. The
+ * field schema here is the contract the renderers and the JSON sink emit;
+ * it mirrors the Python agent's obs framework so logs from both services
+ * share one shape and one set of trace ids.
+ */
+export declare const LEVELS: {
+    readonly DEBUG: 10;
+    readonly INFO: 20;
+    readonly WARNING: 30;
+    readonly ERROR: 40;
+    readonly CRITICAL: 50;
+};
+export type LevelName = keyof typeof LEVELS;
+/** Loose level input we accept from callers: a name (any case) or a number. */
+export type LevelInput = LevelName | Lowercase<LevelName> | "warn" | number;
+/** Arbitrary structured facts attached to a log line (ids, counts, durations). */
+export type Fields = Record<string, unknown>;
+/** The error.* detail rendered on a failed line (built from a thrown value). */
+export type ErrorInfo = {
+    type: string;
+    message: string;
+    where?: string;
+    code?: unknown;
+    stack?: string;
+};
+/**
+ * One fully-resolved log record, the neutral object both renderers read.
+ * `baggage` (ambient trace attributes) and `fields` (per-call facts) are kept
+ * separate and merged at render time, exactly like the agent, so reserved
+ * keys can be protected without the caller thinking about it.
+ */
+export type ObsRecord = {
+    tsMs: number;
+    level: LevelName;
+    logger: string;
+    event?: string;
+    msg: string;
+    trace: {
+        traceId: string;
+        spanId: string;
+        parentSpanId: string;
+    };
+    baggage: Fields;
+    fields: Fields;
+    error?: ErrorInfo;
+};
+/** A destination for records (stdout or a rotating file). */
+export type Sink = {
+    name: string;
+    /** Per-sink minimum level (the global LOG_LEVEL floor is applied first). */
+    minLevel: number;
+    /** Render + write one record; must never throw out (sinks swallow I/O errors). */
+    write: (rec: ObsRecord) => void;
+    /** Optional descriptor for the GET /logging-style introspection. */
+    describe?: () => {
+        type: string;
+        target: string;
+        format?: string;
+        rotation?: string;
+        retention?: number;
+    };
+};

package/dist/types.js

@@ -0,0 +1,19 @@
+/**
+ * Shared shapes for the obs logging framework.
+ *
+ * Kept dependency-free and tiny so every other obs module (and the unit
+ * tests) can import these types without pulling in Node-only code. The
+ * field schema here is the contract the renderers and the JSON sink emit;
+ * it mirrors the Python agent's obs framework so logs from both services
+ * share one shape and one set of trace ids.
+ */
+// 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.
+export const LEVELS = {
+    DEBUG: 10,
+    INFO: 20,
+    WARNING: 30,
+    ERROR: 40,
+    CRITICAL: 50,
+};