@diveinto/obs 1.0.2 → 1.0.4

package/README.md

@@ -27,7 +27,14 @@ of the four, and each of those behaviours is pinned by a test.
   follow a trace across services written in either language.
 - **Three sinks**: stdout (always), and two rotating files that are
   format-locked, so `<stem>.log` is always text and `<stem>.jsonl` is always
-  JSON regardless of `LOG_FORMAT`. Daily rotation, 14 kept, both configurable.
+  JSON regardless of `LOG_FORMAT`. Daily rotation, 14 kept, both
+  configurable. **One writer per path per process**, shared across module
+  contexts on `globalThis` along with the sink registry and the level floor
+  (v1.0.4): a framework that runs your instrumentation hook in a different
+  module context from your route handlers will otherwise build a second
+  writer on the same file, and the two then rename it out from under each
+  other at the rotation boundary. Rotation also refuses to overwrite an
+  existing rotated file, so a day of records cannot be lost to a rename.
 - **Trace context** on `AsyncLocalStorage`, continuing an inbound W3C
   `traceparent` and propagating it outbound, so one `trace_id` spans every
   hop.

package/dist/config.d.ts

@@ -71,11 +71,17 @@ type Resolved = Required<Pick<ObsConfig, "service" | "envPrefix" | "defaultVarDi
 };
 export declare function configure(cfg: ObsConfig): void;
 /**
- * The live config. Falling back rather than throwing is deliberate: a log
- * line emitted before `configure()` (an import-time warning, say) should
- * still come out, named honestly, instead of taking the process down.
+ * The live configuration, or a fallback.
+ *
+ * Falling back rather than throwing is deliberate: a log line emitted before
+ * `configure()` (an import-time warning, say) should still come out, named
+ * honestly, instead of taking the process down. The fallback is NOT cached,
+ * so a later `configure()` still wins, and `isConfigured()` lets the file
+ * sinks refuse to invent a path from it.
  */
 export declare function obsConfig(): Resolved;
+/** Whether `configure()` has actually run. See `setupLogging()`. */
+export declare function isConfigured(): boolean;
 /** Test seam: forget the configuration so a test can set a different one. */
 export declare function resetConfigForTests(): void;
 /** Read one of this service's own prefixed variables. */

package/dist/config.js

@@ -14,7 +14,26 @@
  * service name is a no-op and a call with a DIFFERENT one is a mistake worth
  * hearing about.
  */
-let current = null;
+/**
+ * The configuration lives on `globalThis`, NOT in a module-level variable.
+ *
+ * This is not defensiveness, it is a scar. Next can run `instrumentation.ts`
+ * in a DIFFERENT module context from the route handlers, so a module-level
+ * `let` set by `configure()` reads as unset in half the process. When that
+ * happened, the lazy sink initialiser re-ran `setupLogging()` in the second
+ * context, got the fallback configuration, tried to open
+ * `/var/lib/unconfigured/logs/...`, and self-disabled both file sinks. Every
+ * request log went to stdout only and the `.jsonl` and `.log` files silently
+ * stopped receiving anything, which is exactly the surface operators grep.
+ *
+ * `globalThis` is shared across those contexts, which is the same reason
+ * @vercel/otel puts its provider there and why `otelEnabled()` reads the
+ * environment rather than a flag.
+ */
+const SLOT = Symbol.for("diveinto.obs.config");
+function slot() {
+    return globalThis;
+}
 function resolve(cfg) {
     const service = cfg.service.trim();
     if (!service)
@@ -35,24 +54,33 @@ function resolve(cfg) {
 }
 export function configure(cfg) {
     const next = resolve(cfg);
-    if (current && current.service !== next.service) {
+    const held = slot()[SLOT];
+    if (held && held.service !== next.service) {
         // Two services in one process is not a thing this library supports, and
         // the symptom (logs filed under the wrong service) is miserable to chase.
-        throw new Error(`[obs] already configured as '${current.service}'; cannot reconfigure as '${next.service}'`);
+        throw new Error(`[obs] already configured as '${held.service}'; cannot reconfigure as '${next.service}'`);
     }
-    current = next;
+    slot()[SLOT] = next;
 }
 /**
- * The live config. Falling back rather than throwing is deliberate: a log
- * line emitted before `configure()` (an import-time warning, say) should
- * still come out, named honestly, instead of taking the process down.
+ * The live configuration, or a fallback.
+ *
+ * Falling back rather than throwing is deliberate: a log line emitted before
+ * `configure()` (an import-time warning, say) should still come out, named
+ * honestly, instead of taking the process down. The fallback is NOT cached,
+ * so a later `configure()` still wins, and `isConfigured()` lets the file
+ * sinks refuse to invent a path from it.
  */
 export function obsConfig() {
-    return current ?? (current = resolve({ service: "unconfigured", envPrefix: "OBS" }));
+    return slot()[SLOT] ?? resolve({ service: "unconfigured", envPrefix: "OBS" });
+}
+/** Whether `configure()` has actually run. See `setupLogging()`. */
+export function isConfigured() {
+    return slot()[SLOT] !== undefined;
 }
 /** Test seam: forget the configuration so a test can set a different one. */
 export function resetConfigForTests() {
-    current = null;
+    delete slot()[SLOT];
 }
 /** Read one of this service's own prefixed variables. */
 export function envVar(name, env = process.env) {

package/dist/setup.js

@@ -23,7 +23,7 @@
  */
 import { join } from "node:path";
 import { logEvent } from "./api.js";
-import { obsConfig } from "./config.js";
+import { isConfigured, obsConfig } from "./config.js";
 import { makeOtelLogSink, otelEnabled } from "./otel.js";
 import { renderJson, renderPretty } from "./render.js";
 import { configureSinks, makeFileSink, makeStdoutSink, setSinkInitializer } from "./sinks.js";
@@ -116,8 +116,18 @@ export function setupLogging() {
     // 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.
+    //
+    // Belt and braces after the globalThis fix: if this ever runs before
+    // configure() again, write to stdout and say so, rather than deriving a
+    // path from the fallback name. The old behaviour opened
+    // /var/lib/unconfigured/logs/, failed, self-disabled both files, and left
+    // an operator with a silently empty .jsonl.
     const serverless = isServerless();
-    if (!serverless) {
+    if (!serverless && !isConfigured()) {
+        process.stderr.write("[obs] setupLogging() ran before configure(); writing to stdout only. " +
+            "Call configure() or createObs() first, from instrumentation.ts.\n");
+    }
+    if (!serverless && isConfigured()) {
         const targets = resolveFileTargets();
         if (targets.text) {
             sinks.push(makeFileSink(targets.text.path, "pretty", renderPretty, targets.text.rotation, targets.text.retention));

package/dist/sinks.d.ts

@@ -36,11 +36,31 @@ export declare class RotatingFileWriter {
     write(rec: ObsRecord): void;
     private maybeRotate;
     private rotateTime;
+    /**
+     * Where `path` goes when the period rolls: `path.<key>`, unless that
+     * already exists.
+     *
+     * `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
+     * 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
+     * rename is a poor trade for a tidy filename.
+     */
+    private rotatedName;
     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`. */
+/**
+ * Build a file `Sink` wrapping a `RotatingFileWriter`.
+ *
+ * One writer per path per process, shared across module contexts. Two
+ * writers on one file is not a harmless duplicate: each owns an fd and its
+ * own rotation state, so they rename the file out from under each other and
+ * the one an operator greps stops advancing. See the slots at the top.
+ */
 export declare function makeFileSink(path: string, format: string, render: (rec: ObsRecord) => string, rotation: string, retention: number): Sink;

package/dist/sinks.js

@@ -15,17 +15,49 @@
  * 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 { createWriteStream, existsSync, 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;
+/**
+ * The active sinks, the level floor, and every open file writer live on
+ * `globalThis`, NOT in module-level variables.
+ *
+ * Same scar as the configuration one layer up, and found the same way. The
+ * config moved to globalThis when a second module context read it as unset;
+ * the SINKS did not move with it, and the lazy initialiser below then built
+ * 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
+ * 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.
+ *
+ * One process, one writer per path. That is what these slots buy.
+ */
+const SINKS_SLOT = Symbol.for("diveinto.obs.sinks");
+const WRITERS_SLOT = Symbol.for("diveinto.obs.writers");
+function holder() {
+    return globalThis;
+}
+function state() {
+    const h = holder();
+    h[SINKS_SLOT] ??= { sinks: [], threshold: LEVELS.INFO };
+    return h[SINKS_SLOT];
+}
+/** Every file writer this process has opened, by absolute path. */
+function writers() {
+    const h = holder();
+    h[WRITERS_SLOT] ??= new Map();
+    return h[WRITERS_SLOT];
+}
 export function configureSinks(sinks, threshold) {
-    SINKS = sinks;
-    THRESHOLD = threshold;
+    const st = state();
+    st.sinks = sinks;
+    st.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
@@ -39,24 +71,27 @@ export function setSinkInitializer(fn) {
     initializer = fn;
 }
 export function setThreshold(threshold) {
-    THRESHOLD = threshold;
+    state().threshold = threshold;
 }
 export function activeSinks() {
-    return SINKS;
+    return state().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) {
+    // Configure on first use if some context has not done it yet (see
+    // setSinkInitializer). The sinks it builds are shared, so this runs at
+    // most once per process however many module contexts reach it.
+    const st = state();
+    if (st.sinks.length === 0 && initializer && !initAttempted) {
         initAttempted = true;
         initializer();
     }
     const lvl = LEVELS[rec.level];
-    if (lvl < THRESHOLD)
+    if (lvl < st.threshold)
         return;
-    for (const sink of SINKS) {
+    for (const sink of st.sinks) {
         if (lvl < sink.minLevel)
             continue;
         try {
@@ -159,7 +194,7 @@ export class RotatingFileWriter {
     rotateTime(prevKey) {
         this.stream?.end();
         try {
-            renameSync(this.path, `${this.path}.${prevKey}`);
+            renameSync(this.path, this.rotatedName(prevKey));
         }
         catch {
             /* if the rename fails we just keep appending to the same file */
@@ -167,6 +202,29 @@ export class RotatingFileWriter {
         this.open();
         this.prune();
     }
+    /**
+     * Where `path` goes when the period rolls: `path.<key>`, unless that
+     * already exists.
+     *
+     * `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
+     * 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
+     * rename is a poor trade for a tidy filename.
+     */
+    rotatedName(key) {
+        const base = `${this.path}.${key}`;
+        if (!existsSync(base))
+            return base;
+        for (let i = 1; i < 100; i++) {
+            const candidate = `${base}.${i}`;
+            if (!existsSync(candidate))
+                return candidate;
+        }
+        return `${base}.${Date.now()}`;
+    }
     rotateSize() {
         this.stream?.end();
         // Shift path.{retention-1} -> path.{retention} ... path.1 -> path.2, then
@@ -225,9 +283,21 @@ export class RotatingFileWriter {
         }
     }
 }
-/** Build a file `Sink` wrapping a `RotatingFileWriter`. */
+/**
+ * Build a file `Sink` wrapping a `RotatingFileWriter`.
+ *
+ * One writer per path per process, shared across module contexts. Two
+ * writers on one file is not a harmless duplicate: each owns an fd and its
+ * own rotation state, so they rename the file out from under each other and
+ * the one an operator greps stops advancing. See the slots at the top.
+ */
 export function makeFileSink(path, format, render, rotation, retention) {
-    const writer = new RotatingFileWriter(path, rotation, retention, render);
+    const open = writers();
+    let writer = open.get(path);
+    if (!writer) {
+        writer = new RotatingFileWriter(path, rotation, retention, render);
+        open.set(path, writer);
+    }
     return {
         name: basename(path),
         minLevel: LEVELS.DEBUG,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diveinto/obs",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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,