Skip to content

README.md

Latest commit

 

History

History
107 lines (76 loc) · 3.08 KB

README.md

File metadata and controls

107 lines (76 loc) · 3.08 KB

batch-stdout

Small batch stdout logger built on top of Sonic Boom.

Features

  • Batching: Buffers logs up to a configurable size before writing, reducing stdout overhead.
  • Log Levels: Supports debug, info, warning, error, and disabled.
  • Injection: Easily inject metadata (like timestamps, trace IDs).
  • Pretty Printing: Optional pretty-printed log outputs.

Installation

npm install batch-stdout

Usage

Basic Setup

import { logger } from "batch-stdout";

const log = logger({
    batchSizeMb: 1,
});

log.info("Hello, world!");
log.error("Something went wrong.");

Custom Options

const log = logger({
    batchSizeMb: 1, // maximum batch size in MB
    logLevel: "info", // "debug" | "info" | "warning" | "error" | "disabled"
    inject: () => ({
        timestamp: new Date().toISOString(),
        traceId: "abc123"
    }),
    isPrettyPrint: true, // pretty print output
    batchWindowMs: 10 // ms to flush logs if no new logs are added within timeframe
});

// You can add contextual data:
log.info("Processed user", { userId: 42, user: "alice" });
log.warning("Slow request", { ms: 5123 });
log.debug("Debug details", { meta: { ... } });

Log Levels

  • debug, info, warning, error
    Only messages at or above the set logLevel are logged.
  • Use disabled to turn off all logging.

API

logger(options?) → Logger

Options

Name Type Default Description
batchLimitType string "size" Whether to limit batch to megabytes ("size") or item count ("count")
batchLimit number 0.25 Depending on limit type either megabytes or count of items
logLevel string "debug" Log level filter
inject function undefined Injected metadata for every log
isPrettyPrint boolean false Use JSON pretty printing
batchWindowMs number 0 Flush logs after timeframe. 0 is disabled

Logger methods

  • log.debug(...args)
  • log.info(...args)
  • log.warning(...args)
  • log.error(...args)

Each accepts any serializable argument(s).

Benchmark

Benchmark done using a benchmark script, comparing console.log, process.stdout.write, pino, and raw sonic-boom to this library. 1000 iterations of a log fixture

"batch-stdout": "2.06ms",
"batch-stdout with injection & pretty-print": "5.15ms",
"console.log": "196.62ms",
"process.stdout.write": "51.83ms",
"process.stdout.write with pretty-print": "154.57ms",
"sonic-boom": "1.59ms",
"pino": "3.86ms"

License

MIT @OkayestDev