sonic-boom

What is sonic-boom?

The 'sonic-boom' npm package is a fast and efficient logging library designed for Node.js. It is optimized for high-performance logging, making it suitable for applications that require rapid and concurrent log writing. The package provides a simple API for writing logs to files and supports features like file rotation and asynchronous logging.

What are sonic-boom's main functionalities?

Basic Logging

This feature allows you to create a basic logger that writes log messages to a specified file. The example demonstrates how to initialize the logger, write a log message, and close the logger.

const SonicBoom = require('sonic-boom');
const logger = new SonicBoom({ dest: './log.txt' });
logger.write('Hello, World!\n');
logger.end();

Asynchronous Logging

Sonic-boom supports asynchronous logging, which can improve performance by not blocking the event loop. The example shows how to enable asynchronous logging by setting the 'sync' option to false.

const SonicBoom = require('sonic-boom');
const logger = new SonicBoom({ dest: './log.txt', sync: false });
logger.write('This is an async log message.\n');
logger.end();

File Rotation

This feature allows you to rotate log files when they reach a certain size. The example demonstrates how to set a minimum length for log files and how to reopen a new log file for continued logging.

const SonicBoom = require('sonic-boom');
const logger = new SonicBoom({ dest: './log.txt', minLength: 4096 });
logger.write('Log message that triggers rotation.\n');
logger.reopen('./new-log.txt');

Other packages similar to sonic-boom

pino

Pino is a fast and low-overhead logging library for Node.js. It is designed for high-performance logging and offers features like JSON logging, log levels, and log rotation. Compared to sonic-boom, Pino provides a more comprehensive logging solution with additional features like serializers and transport streams.

winston

Winston is a versatile logging library for Node.js that supports multiple transports (e.g., console, file, HTTP). It offers features like log levels, custom formats, and asynchronous logging. While Winston is more feature-rich and flexible, it may not be as performant as sonic-boom for high-throughput logging scenarios.

bunyan

Bunyan is a simple and fast JSON logging library for Node.js. It provides features like log levels, serializers, and log rotation. Bunyan is similar to sonic-boom in terms of performance but focuses on JSON logging and structured log data, making it suitable for applications that require structured logging.

README

sonic-boom

Extremely fast utf8-only stream implementation to write to files and file descriptors.

This implementation is partial, but support backpressure and .pipe() in is here. However, it is 2-3x faster than Node Core fs.createWriteStream():

benchSonic*1000: 1916.904ms
benchSonicSync*1000: 8605.265ms
benchSonic4k*1000: 1965.231ms
benchSonicSync4k*1000: 1588.224ms
benchCore*1000: 5851.959ms
benchConsole*1000: 7605.713ms

Note that sync mode without buffering is slower than a Node Core WritableStream, however this mode matches the expected behavior of console.log().

Note that if this is used to log to a windows terminal (cmd.exe or powershell), it is needed to run chcp 65001 in the terminal to correctly display utf-8 characters, see chcp for more details.

Install

npm i sonic-boom

Example

'use strict'

const SonicBoom = require('sonic-boom')
const sonic = new SonicBoom({ fd: process.stdout.fd }) // or { dest: '/path/to/destination' }

for (let i = 0; i < 10; i++) {
  sonic.write('hello sonic\n')
}

API

SonicBoom(opts)

Creates a new instance of SonicBoom.

The options are:

• fd: a file descriptor, something that is returned by fs.open or fs.openSync.
• dest: a string that is a path to a file to be written to (mode controlled by the append option).
• minLength: the minimum length of the internal buffer that is required to be full before flushing.
• maxLength: the maximum length of the internal buffer. If a write operation would cause the buffer to exceed maxLength, the data written is dropped and a drop event is emitted with the dropped data
• maxWrite: the maximum number of bytes that can be written; default: 16384
• periodicFlush: calls flush every xms.
• sync: perform writes synchronously (similar to console.log).
• fsync: perform a fsyncSync every time a write is completed.
• append: appends writes to dest file instead of truncating it (default true).
• mode: specify the creating file mode (see fs.open() from Node.js core).
• mkdir: ensure directory for dest file exists when true (default false).
• retryEAGAIN(err, writeBufferLen, remainingBufferLen): a function that will be called when sonic-boom write/writeSync/flushSync encounters a EAGAIN or EBUSY error. If the return value is true sonic-boom will retry the operation, otherwise it will bubble the error. err is the error that caused this function to be called, writeBufferLen is the length of the buffer sonic-boom tried to write, and remainingBufferLen is the length of the remaining buffer sonic-boom didn't try to write.

For sync:false a SonicBoom instance will emit the 'ready' event when a file descriptor is available. For sync:true this is not relevant because the 'ready' event will be fired when the SonicBoom instance is created, before it can be subscribed to.

SonicBoom#write(string)

Writes the string to the file. It will return false to signal the producer to slow down.

SonicBoom#flush([cb])

Writes the current buffer to the file if a write was not in progress. Do nothing if minLength is zero or if it is already writing.

call the callback when the flush operation is completed. when failed the callback is called with an error.

SonicBoom#reopen([file])

Reopen the file in place, useful for log rotation.

Example:

const stream = new SonicBoom('./my.log')
process.on('SIGUSR2', function () {
  stream.reopen()
})

SonicBoom#flushSync()

Flushes the buffered data synchronously. This is a costly operation.

SonicBoom#end()

Closes the stream, the data will be flushed down asynchronously

SonicBoom#destroy()

Closes the stream immediately, the data is not flushed.

Events

SonicBoom#close

See Stream#close. The 'close' event when the instance has been closed.

SonicBoom#drain

See Stream#drain. The 'drain' event is emitted when source can resume sending data.

SonicBoom#drop

When destination file maximal length is reached, the 'drop' event is emitted with data that could not be written.

SonicBoom#error

The 'error' event is emitted when the destination file can not be opened, or written.

SonicBoom#finish

See Stream#finish. The 'finish' event after calling end() method and when all data was written.

SonicBoom#ready

The 'ready' event occurs when the created instance is ready to process input.

SonicBoom#write

The 'write' event occurs every time data is written to the underlying file. It emits the number of written bytes.

License

MIT