roarr

What is roarr?

Roarr is a lightweight and fast logger for Node.js applications. It is designed to be simple, performant, and easy to use, providing structured logging capabilities with minimal overhead.

What are roarr's main functionalities?

Basic Logging

Roarr allows you to create a logger instance and log messages with different severity levels. In this example, an info message is logged.

const Roarr = require('roarr');
const log = Roarr.child({ application: 'my-app' });
log.info('This is an info message');

Child Loggers

Roarr supports creating child loggers that inherit context from their parent loggers. This is useful for adding additional context to logs in different parts of your application.

const Roarr = require('roarr');
const parentLog = Roarr.child({ application: 'my-app' });
const childLog = parentLog.child({ module: 'my-module' });
childLog.debug('This is a debug message from my-module');

Structured Logging

Roarr supports structured logging, allowing you to log additional context as JSON objects. This makes it easier to analyze and search logs.

const Roarr = require('roarr');
const log = Roarr.child({ application: 'my-app' });
log.info({ userId: 123, action: 'login' }, 'User login event');

Log Level Filtering

Roarr allows you to filter logs by severity level using the ROARR_LOG environment variable. In this example, only debug and higher severity logs will be output.

process.env.ROARR_LOG = 'debug';
const Roarr = require('roarr');
const log = Roarr.child({ application: 'my-app' });
log.debug('This is a debug message');
log.info('This is an info message');

Other packages similar to roarr

winston

Winston is a versatile logging library for Node.js with support for multiple transports, log levels, and formats. It is more feature-rich compared to Roarr but also comes with more complexity and overhead.

pino

Pino is a fast and low-overhead logging library for Node.js, similar to Roarr in terms of performance. Pino offers more features out of the box, such as log rotation and serializers, but may be slightly more complex to set up.

bunyan

Bunyan is a JSON logging library for Node.js that provides structured logging and log levels. It is similar to Roarr in its focus on structured logging but includes additional features like log streams and serializers.

README

Roarr

JSON logger for Node.js.

• Usage
  • Prepending context using the global state
  • Filtering logs
    • jq primer
• Transports
• Environment variables

Usage

Roarr logging is disabled by default. To enable logging, you must start program with an environment variable ROARR_LOG set to true, e.g.

ROARR_LOG=true node ./index.js

roarr package exports a function that accepts the following API:

export type LoggerType =
  (
    context: MessageContextType,
    message: string,
    c?: SprintfArgumentType,
    d?: SprintfArgumentType,
    e?: SprintfArgumentType,
    f?: SprintfArgumentType,
    g?: SprintfArgumentType,
    h?: SprintfArgumentType,
    i?: SprintfArgumentType,
    k?: SprintfArgumentType
  ) => void |
  (
    message: string,
    b?: SprintfArgumentType,
    c?: SprintfArgumentType,
    d?: SprintfArgumentType,
    e?: SprintfArgumentType,
    f?: SprintfArgumentType,
    g?: SprintfArgumentType,
    h?: SprintfArgumentType,
    i?: SprintfArgumentType,
    k?: SprintfArgumentType
  ) => void;

Put it into words:

1. First parameter can be either a string (message) or an object.

• If first parameter is an object (context), the second parameter must be a string (message).

1. Arguments after the message parameter are used to enable printf message formatting.

• Printf arguments must be of a primitive type (string | number | boolean | null).
• There can be up to 9 printf arguments (or 8 if the first parameter is the context object).

import log from 'roarr';

log('foo');

log('bar %s', 'baz');

// Creates a child logger appending the provided `context` object
// to the previous logger context.
const debug = log.child({
  level: 'debug'
});

debug('qux');

debug({
  quuz: 'corge'
}, 'quux');

Produces output:

{"context":{},"message":"foo","sequence":0,"time":1506776210001,"version":"1.0.0"}
{"context":{},"message":"bar baz","sequence":1,"time":1506776210002,"version":"1.0.0"}
{"context":{"level":"debug"},"message":"qux","sequence":2,"time":1506776210003,"version":"1.0.0"}
{"context":{"level":"debug","quuz":"corge"},"sequence":3,"message":"quux","time":1506776210004,"version":"1.0.0"}

Prepending context using the global state

Prepending context using the global state will affect all roarr logs.

import log from 'roarr';

log('foo');

global.ROARR.prepend = {
  taskId: 1
};

log('bar');

global.ROARR.prepend = {};

log('baz');

Produces output:

{"context":{},"message":"foo","sequence":0,"time":1506776210001,"version":"1.0.0"}
{"context":{"taskId":1},"message":"bar","sequence":1,"time":1506776210002,"version":"1.0.0"}
{"context":{},"message":"baz","sequence":2,"time":1506776210003,"version":"1.0.0"}

Prepending context using the global state is useful when the desired result is to associate all logs with a specific context for a duration of an operation, e.g. to correlate the main process logs with the dependency logs.

import log from 'roarr';
import foo from 'foo';

const taskIds = [
  1,
  2,
  3
];

for (const taskId of taskIds) {
  global.ROARR = global.ROARR || {};
  global.ROARR.prepend = {
    taskId
  };

  log('starting task ID %d', taskId);

  // In this example, `foo` is an arbitrary third-party dependency that is using
  // roarr logger.
  foo(taskId);

  log('successfully completed task ID %d', taskId);

  global.ROARR.prepend = {};
}

Produces output:

{"context":{"taskId":1},"message":"starting task ID 1","sequence":0,"time":1506776210001,"version":"1.0.0"}
{"context":{"taskId":1},"message":"foo","sequence":1,"time":1506776210002,"version":"1.0.0"}
{"context":{"taskId":1},"message":"successfully completed task ID 1","sequence":2,"time":1506776210003,"version":"1.0.0"}
[...]

Filtering logs

Roarr is designed to print all or none logs (refer to the ROARR_LOG environment variable documentation).

To filter logs you need to use a JSON processor, e.g. jq.

jq primer

jq allows you to filter JSON messages using select(boolean_expression), e.g.

ROARR_LOG=true node ./index.js | jq 'select(.context.level == "warning" or .context.level == "error")'

Transports

A transport in most logging libraries is something that runs in-process to perform some operation with the finalised log line. For example, a transport might send the log line to a standard syslog server after processing the log line and reformatting it.

Roarr does not support in-process transports.

Roarr does not support in-process transports because Node processes are single threaded processes (ignoring some technical details). Given this restriction, Roarr purposefully offloads handling of the logs to external processes so that the threading capabilities of the OS can be used (or other CPUs).

Depending on your configuration, consider one of the following log transports:

• Beats for aggregating at a process level (written in Go).
• logagent for aggregating at a process level (written in JavaScript).
• Fluentd for aggregating logs at a container orchestration level (e.g. Kubernetes) (written in Ruby).

Environment variables

When running the script in a Node.js environment, use environment variables to control roarr behaviour.

Name	Type	Function	Default
ROARR_LOG	Boolean	Enables/ disables logging.	false