@diveinto/obs 1.0.3 → 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/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.3",
+  "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,