@diveinto/obs 1.0.4 → 1.0.5

package/README.md

@@ -35,6 +35,12 @@ of the four, and each of those behaviours is pinned by a test.
   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.
@@ -100,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;
@@ -63,4 +85,4 @@ export declare class RotatingFileWriter {
  * 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;
+export declare function makeFileSink(path: string, format: string, render: (rec: ObsRecord) => string, rotation: string, retention: number, maxBytes?: number): Sink;

package/dist/sinks.js

@@ -126,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();
@@ -184,11 +197,18 @@ export class RotatingFileWriter {
             const maxBytes = (parseInt(this.rotation, 10) || 100) * 1024 * 1024;
             if (this.bytes > 0 && this.bytes + incoming > maxBytes)
                 this.rotateSize();
+            return;
+        }
+        const now = this.currentPeriod();
+        if (this.periodKey && now !== this.periodKey) {
+            this.rotateTime(this.periodKey);
+            return;
         }
-        else {
-            const now = this.currentPeriod();
-            if (this.periodKey && now !== this.periodKey)
-                this.rotateTime(this.periodKey);
+        // 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) {
@@ -291,11 +311,11 @@ export class RotatingFileWriter {
  * 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) {
+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);
+        writer = new RotatingFileWriter(path, rotation, retention, render, maxBytes);
         open.set(path, writer);
     }
     return {

package/package.json

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