Bunyan: Fast Structured JSON Logging for Node.js

Use the tools/timesrc.js script to benchmark the performance cost of enabling source location tracking (src: true) in Bunyan loggers. This script compares the execution time of log.info() calls with and without the src option enabled.

Prerequisites:

• Install the ben benchmarking library: npm install ben

Usage: Run the script from the repository root:

node tools/timesrc.js

Output: The script prints the milliseconds per iteration for:

• log.info with src: true
• log.info without src

This helps you decide if the overhead of capturing call source info (file, line, function) is acceptable for your application's logging performance requirements.

#!/usr/bin/env node
/*
 * Time 'src' fields (getting log call source info). This is expensive.
 */

console.log('Time adding "src" field with call source info:');

var ben = require('ben');  // npm install ben
var Logger = require('../lib/bunyan');

var records = [];
function Collector() {
}
Collector.prototype.write = function (s) {
    //records.push(s);
}
var collector = new Collector();

var logwith = new Logger({
    name: 'with-src',
    src: true,
    stream: collector
});

var ms = ben(1e5, function () {
    logwith.info('hi');
});
console.log(' - log.info with    src:  %dms per iteration', ms);

var logwithout = new Logger({
    name: 'without-src',
    stream: collector
});
var ms = ben(1e5, function () {
    logwithout.info('hi');
});
console.log(' - log.info without src:  %dms per iteration', ms);

Sources: tools/timesrc.js

You can create a custom Bunyan stream to filter out log records based on environment variables. This allows you to mute specific log entries without modifying the core library.

How it works:

1. Define a custom stream class (e.g., MuteByEnvVars) that implements a write method.
2. The stream scans process.env for keys starting with BUNYAN_MUTE_.
3. When a log record is written, the stream checks if any field in the record matches the corresponding environment variable value.
4. If a match is found, the record is suppressed (muted). Otherwise, it is written to the underlying stream.

Usage Pattern:

• Set environment variables in the format BUNYAN_MUTE_<field_path>=<value> before running your script.
• Use dot notation for nested fields (e.g., BUNYAN_MUTE_user.id=123).
• Attach the custom stream to your logger with type: 'raw'.

Example:

var bunyan = require('bunyan');

function MuteByEnvVars(opts) {
    opts = opts || {};
    this.stream = opts.stream || process.stdout;
    var PREFIX = 'BUNYAN_MUTE_';
    this.mutes = {};
    for (var k in process.env) {
        if (k.indexOf(PREFIX) === 0) {
            this.mutes[k.slice(PREFIX.length)] = process.env[k];
        }
    }
}

MuteByEnvVars.prototype._objectFromDotNotation = function (o, s) {
    s = s.replace(/\[(\w+)\]/g, '.$1');
    s = s.replace(/^\./, '');
    var a = s.split('.');
    while (a.length) {
        var n = a.shift();
        if (n in o) {
            o = o[n];
        } else {
            return;
        }
    }
    return o;
}

MuteByEnvVars.prototype.write = function (rec) {
    if (typeof (rec) !== 'object') {
        console.error('error: MuteByEnvVars raw stream got a non-object record: %j', rec);
        return;
    }
    var muteRec = false;
    var keys = Object.keys(this.mutes);
    for (var i = 0; i < keys.length; i++) {
        var k = keys[i];
        var match = this._objectFromDotNotation(rec, k);
        if (match === this.mutes[k]) {
            muteRec = true;
            break;
        }
    }
    if (!muteRec) {
        this.stream.write(JSON.stringify(rec) + '\n');
    }
}

var log = bunyan.createLogger({
    name: 'mute-by-envvars-stream',
    streams: [
        {
            level: 'info',
            stream: new MuteByEnvVars(),
            type: 'raw'
        }
    ]
});

log.info('hi raw stream');
log.info({foo: 'bar'}, 'added "foo" key');

Running with Mute Rules: To mute logs containing {foo: 'bar'}:

BUNYAN_MUTE_foo=bar node mute-by-envvars-stream.js

Notes:

• This is a custom implementation and may not be optimized for performance or edge cases.
• Nested fields must be accessed using dot notation in the environment variable key (e.g., BUNYAN_MUTE_user.name=John).
• The stream treats all environment variable values as strings.

var bunyan = require('bunyan');

function MuteByEnvVars(opts) {
    opts = opts || {};
    this.stream = opts.stream || process.stdout;
    var PREFIX = 'BUNYAN_MUTE_';
    this.mutes = {};
    for (var k in process.env) {
        if (k.indexOf(PREFIX) === 0) {
            this.mutes[k.slice(PREFIX.length)] = process.env[k];
        }
    }
}

MuteByEnvVars.prototype._objectFromDotNotation = function (o, s) {
    s = s.replace(/\[(\w+)\]/g, '.$1');
    s = s.replace(/^\./, '');
    var a = s.split('.');
    while (a.length) {
        var n = a.shift();
        if (n in o) {
            o = o[n];
        } else {
            return;
        }
    }
    return o;
}

MuteByEnvVars.prototype.write = function (rec) {
    if (typeof (rec) !== 'object') {
        console.error('error: MuteByEnvVars raw stream got a non-object record: %j', rec);
        return;
    }
    var muteRec = false;
    var keys = Object.keys(this.mutes);
    for (var i = 0; i < keys.length; i++) {
        var k = keys[i];
        var match = this._objectFromDotNotation(rec, k);
        if (match === this.mutes[k]) {
            muteRec = true;
            break;
        }
    }
    if (!muteRec) {
        this.stream.write(JSON.stringify(rec) + '\n');
    }
}

var log = bunyan.createLogger({
    name: 'mute-by-envvars-stream',
    streams: [
        {
            level: 'info',
            stream: new MuteByEnvVars(),
            type: 'raw'
        }
    ]
});

log.info('hi raw stream');
log.info({foo: 'bar'}, 'added "foo" key');

Sources: examples/mute-by-envvars-stream.js

Create a logger instance by requiring bunyan and calling createLogger with a configuration object. The name field is required.

var bunyan = require('bunyan');
var log = bunyan.createLogger({
    name: 'myapp',
    level: 'info',
    stream: process.stdout
});

Configuration Options:

• name (string, required): The logger name.
• level (string or number, optional): The minimum log level (see Levels).
• stream (node.js stream, optional): A single output stream (e.g., process.stdout).
• streams (array, optional): Multiple streams with different levels.
• serializers (object, optional): Custom serializers for objects.
• src (boolean, optional): Include source location (file, line, function).
• Any other fields are added to all log records.

Example with multiple streams:

var log = bunyan.createLogger({
  name: 'myapp',
  streams: [
    {
      level: 'info',
      stream: process.stdout
    },
    {
      level: 'error',
      path: '/var/tmp/myapp-error.log'
    }
  ]
});

var bunyan = require('bunyan');
var log = bunyan.createLogger({name: 'myapp'});

Sources: README.md