@diveinto/obs 1.0.3 → 1.0.5

package/README.md

@@ -27,7 +27,20 @@ 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.
+  A single file also has a **ceiling** (256 MB by default,
+  `<PREFIX>_LOG_JSON_MAX_MB` / `_TEXT_MAX_MB`, 0 to remove): daily rotation
+  bounds how many files there are, not how large one can get, and a service
+  that drops to DEBUG or loops on an error can write more in an afternoon
+  than the fortnight around it. Worst case per service is now a number an
+  operator can reason about rather than the free space on the disk.
 - **Trace context** on `AsyncLocalStorage`, continuing an inbound W3C
   `traceparent` and propagating it outbound, so one `trace_id` spans every
   hop.
@@ -93,8 +106,10 @@ Generic, never prefixed: `LOG_LEVEL` (`trace`/`debug`/`info`/`warn`/`error`/
 `OTEL_*` set.
 
 Per service, prefixed: `<PREFIX>_VAR_DIR`, `<PREFIX>_LOG_TEXT_FILE`,
-`_TEXT_ROTATION`, `_TEXT_RETENTION`, and the same three for `_JSON_`. A
-`*_FILE` value is a path, or `1` for the default path, or `0`/`off`.
+`_TEXT_ROTATION`, `_TEXT_RETENTION`, `_TEXT_MAX_MB`, and the same four for
+`_JSON_`. A `*_FILE` value is a path, or `1` for the default path, or
+`0`/`off`; `*_MAX_MB` is the per-file ceiling, 256 by default and 0 for
+none.
 
 ## Cardinality
 

package/dist/setup.d.ts

@@ -5,6 +5,8 @@ export type FileTarget = {
     path: string;
     rotation: string;
     retention: number;
+    /** Hard ceiling on one file, bytes; 0 for none. See maxMB below. */
+    maxBytes: number;
 };
 /**
  * Resolve where the two files go, as a pure function of the environment so it

package/dist/setup.js

@@ -42,6 +42,17 @@ function stateDir(env) {
     const cfg = obsConfig();
     return env[`${cfg.envPrefix}_VAR_DIR`] || cfg.defaultVarDir;
 }
+/**
+ * The default ceiling on a single log file, in megabytes.
+ *
+ * Daily rotation bounds the NUMBER of files, not the size of one. A service
+ * that drops to DEBUG or loops on an error can write more in an afternoon
+ * than the fortnight around it, and the first thing to notice would be the
+ * disk. 256 MB a file, times fourteen days, times two files is about 7 GB
+ * worst case per service, which is a bound an operator can reason about.
+ * `<PREFIX>_LOG_JSON_MAX_MB` / `_TEXT_MAX_MB` change it; 0 removes it.
+ */
+const DEFAULT_MAX_MB = 256;
 /**
  * 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
@@ -60,6 +71,7 @@ export function resolveFileTargets(env = process.env) {
                 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),
+                maxBytes: toInt(env[`${p}_LOG_TEXT_MAX_MB`], DEFAULT_MAX_MB) * 1024 * 1024,
             }
             : null,
         json: jsonFile
@@ -67,6 +79,7 @@ export function resolveFileTargets(env = process.env) {
                 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),
+                maxBytes: toInt(env[`${p}_LOG_JSON_MAX_MB`], DEFAULT_MAX_MB) * 1024 * 1024,
             }
             : null,
     };
@@ -130,10 +143,10 @@ export function setupLogging() {
     if (!serverless && isConfigured()) {
         const targets = resolveFileTargets();
         if (targets.text) {
-            sinks.push(makeFileSink(targets.text.path, "pretty", renderPretty, targets.text.rotation, targets.text.retention));
+            sinks.push(makeFileSink(targets.text.path, "pretty", renderPretty, targets.text.rotation, targets.text.retention, targets.text.maxBytes));
         }
         if (targets.json) {
-            sinks.push(makeFileSink(targets.json.path, "json", renderJson, targets.json.rotation, targets.json.retention));
+            sinks.push(makeFileSink(targets.json.path, "json", renderJson, targets.json.rotation, targets.json.retention, targets.json.maxBytes));
         }
     }
     // When OTLP export is on, also ship logs to the backend's Logs view

package/dist/sinks.d.ts

@@ -24,11 +24,33 @@ export declare class RotatingFileWriter {
     private readonly rotation;
     private readonly retention;
     private readonly render;
+    /**
+     * A hard ceiling on ONE file, in bytes, on top of time rotation.
+     *
+     * Daily rotation bounds how many files there are, not how big one can
+     * get: a service that starts logging at DEBUG, or loops on an error,
+     * can write far more in a day than the fourteen quiet days around it,
+     * and nothing stops it before the disk does. With this, the day rolls
+     * early instead. Zero disables it, which is what a size-based
+     * `rotation` already means.
+     */
+    private readonly maxBytes;
     private stream;
     private bytes;
     private periodKey;
     private disabled;
-    constructor(path: string, rotation: string, retention: number, render: (rec: ObsRecord) => string);
+    constructor(path: string, rotation: string, retention: number, render: (rec: ObsRecord) => string, 
+    /**
+     * A hard ceiling on ONE file, in bytes, on top of time rotation.
+     *
+     * Daily rotation bounds how many files there are, not how big one can
+     * get: a service that starts logging at DEBUG, or loops on an error,
+     * can write far more in a day than the fourteen quiet days around it,
+     * and nothing stops it before the disk does. With this, the day rolls
+     * early instead. Zero disables it, which is what a size-based
+     * `rotation` already means.
+     */
+    maxBytes?: number);
     private open;
     /** The bucket key for time-based rotation (empty for size-based). */
     private currentPeriod;
@@ -36,11 +58,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`. */
-export declare function makeFileSink(path: string, format: string, render: (rec: ObsRecord) => string, rotation: string, retention: number): Sink;
+/**
+ * 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, maxBytes?: 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 {
@@ -91,15 +126,28 @@ export class RotatingFileWriter {
     rotation;
     retention;
     render;
+    maxBytes;
     stream = null;
     bytes = 0;
     periodKey = "";
     disabled = false;
-    constructor(path, rotation, retention, render) {
+    constructor(path, rotation, retention, render, 
+    /**
+     * A hard ceiling on ONE file, in bytes, on top of time rotation.
+     *
+     * Daily rotation bounds how many files there are, not how big one can
+     * get: a service that starts logging at DEBUG, or loops on an error,
+     * can write far more in a day than the fourteen quiet days around it,
+     * and nothing stops it before the disk does. With this, the day rolls
+     * early instead. Zero disables it, which is what a size-based
+     * `rotation` already means.
+     */
+    maxBytes = 0) {
         this.path = path;
         this.rotation = rotation;
         this.retention = retention;
         this.render = render;
+        this.maxBytes = maxBytes;
         try {
             mkdirSync(dirname(path), { recursive: true });
             this.open();
@@ -149,17 +197,24 @@ export class RotatingFileWriter {
             const maxBytes = (parseInt(this.rotation, 10) || 100) * 1024 * 1024;
             if (this.bytes > 0 && this.bytes + incoming > maxBytes)
                 this.rotateSize();
+            return;
         }
-        else {
-            const now = this.currentPeriod();
-            if (this.periodKey && now !== this.periodKey)
-                this.rotateTime(this.periodKey);
+        const now = this.currentPeriod();
+        if (this.periodKey && now !== this.periodKey) {
+            this.rotateTime(this.periodKey);
+            return;
+        }
+        // The day has not rolled, but this file has outgrown its ceiling. Roll
+        // it under today's key; rotatedName() keeps the earlier part rather
+        // than renaming over it, so the day survives as .<key>, .<key>.1, ...
+        if (this.maxBytes > 0 && this.bytes > 0 && this.bytes + incoming > this.maxBytes) {
+            this.rotateTime(now);
         }
     }
     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 +222,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 +303,21 @@ export class RotatingFileWriter {
         }
     }
 }
-/** Build a file `Sink` wrapping a `RotatingFileWriter`. */
-export function makeFileSink(path, format, render, rotation, retention) {
-    const writer = new RotatingFileWriter(path, rotation, retention, render);
+/**
+ * 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, maxBytes = 0) {
+    const open = writers();
+    let writer = open.get(path);
+    if (!writer) {
+        writer = new RotatingFileWriter(path, rotation, retention, render, maxBytes);
+        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.5",
   "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,