Bunyan is a simple and fast a JSON Logger for node.js services (and a bunyan CLI tool for nicely viewing those logs).

Server logs should be structured. JSON's a good format. Let's do that: a log record is one line of JSON.stringify'd output. Let's also specify some common names for the requisite and common fields for a log record (see below).

Also: log4j is way more than you need.

Current Status

Basic functionality there. Still a fair amount of planned work, but I'm using it for some production services.

Currently supports node 0.4+, but I'll probably make the jump to node 0.6+ as a base soonish.

Follow @trentmick for updates to Bunyan.

Installation

npm install bunyan

Usage

The usual. All loggers must provide a "name". This is somewhat akin to log4j logger "name", but Bunyan doesn't do hierarchical logger names.

$ cat hi.js
var Logger = require('bunyan');
var log = new Logger({name: "myapp"});
log.info("hi");

Log records are JSON. "hostname", "time" and "v" (the Bunyan log format version) are added for you.

$ node hi.js
{"name":"myapp","hostname":"banana.local","level":2,"msg":"hi","time":"2012-01-31T00:07:44.216Z","v":0}

The full log.{trace|debug|...|fatal}(...) API is:

log.info();     // Returns a boolean: is the "info" level enabled?

log.info('hi');                     // Log a simple string message.
log.info('hi %s', bob, anotherVar); // Uses `util.format` for msg formatting.

log.info({foo: 'bar'}, 'hi');       // Adds "foo" field to log record.

log.info(err);  // Special case to log an `Error` instance, adds "err"
                // key with exception details (including the stack) and
                // sets "msg" to the exception message.
log.info(err, 'more on this: %s', more);
                // ... or you can specify the "msg".

bunyan tool

A bunyan tool is provided for pretty-printing bunyan logs and, eventually, for filtering (e.g. | bunyan -c 'level>3'). This shows the default output (which is fluid right now) and indented-JSON output. More output formats will be added, including support for custom formats.

$ node hi.js | ./bin/bunyan  # CLI tool to filter/pretty-print JSON logs.
[2012-01-31T00:08:11.387Z] INFO: myapp on banana.local: hi

$ node hi.js | ./bin/bunyan -o json
{
  "name": "myapp",
  "hostname": "banana.local",
  "level": 2,
  "msg": "hi",
  "time": "2012-01-31T00:10:00.676Z",
  "v": 0
}

streams

By default, log output is to stdout (stream) and at the "info" level. Explicitly that looks like:

var log = new Logger({name: "myapp", stream: process.stdout,
  level: "info"});

That is an abbreviated form for a single stream. You can defined multiple streams at different levels.

var log = new Logger({
  name: "amon",
  streams: [
    {
      level: "info",
      stream: process.stdout, // log INFO and above to stdout
    },
    {
      level: "error",
      path: "tmp/error.log"   // log ERROR and above to a file
    }
  ]
});

More on streams in the "Streams" section below.

log.child

A log.child(...) is provided to specialize a logger for a sub-component. The following will have log records from "Wuzzle" instances use exactly the same config as its parent, plus include the "component" field.

var log = new Logger(...);

...

function Wuzzle(options) {
  this.log = options.log;
  this.log.info("creating a wuzzle")
}
Wuzzle.prototype.woos = function () {
  this.log.warn("This wuzzle is woosey.")
}

var wuzzle = new Wuzzle({log: log.child({component: "wuzzle"})});
wuzzle.woos();
log.info("done with the wuzzle")

The node-restify framework integrates bunyan. One feature of its integration, is that each restify request handler includes a req.log logger that is:

log.child({req_id: <unique request id>}, true)

Apps using restify can then use req.log and have all such log records include the unique request id (as "req_id"). Handy.

serializers

Bunyan has a concept of "serializers" to produce a JSON-able object from a JavaScript object, so you can easily do the following:

log.info({req: <request object>}, "something about handling this request");

Association is by log record field name, "req" in this example, so this requires a registered serializer something like this:

function reqSerializer(req) {
  return {
    method: req.method,
    url: req.url,
    headers: req.headers
  }
}
var log = new Logger({
  ...
  serializers: {
    req: reqSerializer
  }
});

Or this:

var log = new Logger({
  ...
  serializers: {req: Logger.stdSerializers.req}
});

because Buyan includes a small set of standard serializers. To use all the standard serializers you can use:

var log = new Logger({
  ...
  serializers: Logger.stdSerializers
});

Note: Your own serializers should never throw, otherwise you'll get an ugly message on stderr from Bunyan (along with the traceback) and the field in your log record will be replaced with a short error message.

src

The source file, line and function of the log call site can be added to log records by using the src: true config option:

var log = new Logger({src: true, ...});

This adds the call source info with the 'src' field, like this:

{
  "name": "src-example",
  "hostname": "banana.local",
  "component": "wuzzle",
  "level": 4,
  "msg": "This wuzzle is woosey.",
  "time": "2012-02-06T04:19:35.605Z",
  "src": {
    "file": "/Users/trentm/tm/node-bunyan/examples/src.js",
    "line": 20,
    "func": "Wuzzle.woos"
  },
  "v": 0
}

WARNING: Determining the call source info is slow. Never use this option in production.

Levels

The log levels in bunyan are:

General level usage suggestions: "debug" should be used sparingly. Information that will be useful to debug errors post mortem should usually be included in "info" messages if it's generally relevant or else with the corresponding "error" event. Don't rely on spewing mostly irrelevant debug messages all the time and sifting through them when an error occurs.

Integers are used for the actual level values (10 for "trace", ..., 60 for "fatal") and constants are defined for the (Logger.TRACE ... Logger.DEBUG). The lowercase level names are aliases supported in the API.

Here is the API for changing levels in an existing logger:

log.level() -> INFO   // gets current level (lowest level of all streams)

log.level(INFO)       // set all streams to level INFO
log.level("info")     // set all streams to level INFO

log.levels() -> [DEBUG, INFO]   // get array of levels of all streams
log.levels(0) -> DEBUG          // get level of stream at index 0
log.levels("foo")               // get level of stream with name "foo"

log.levels(0, INFO)             // set level of stream 0 to INFO
log.levels(0, "info")           // can use "info" et al aliases
log.levels("foo", WARN)         // set stream named "foo" to WARN

Log Record Fields

This section will describe rules for the Bunyan log format: field names, field meanings, required fields, etc. However, a Bunyan library doesn't strictly enforce all these rules while records are being emitted. For example, Bunyan will add a time field with the correct format to your log records, but you can specify your own. It is the caller's responsibility to specify the appropriate format.

The reason for the above leniency is because IMO logging a message should never break your app. This leads to this rule of logging: a thrown exception from log.info(...) or equivalent (other than for calling with the incorrect signature) is always a bug in Bunyan.

A typical Bunyan log record looks like this:

{"name":"myserver","hostname":"banana.local","pid":123,"req":{"method":"GET","url":"/path?q=1#anchor","headers":{"x-hi":"Mom","connection":"close"}},"level":3,"msg":"start request","time":"2012-02-03T19:02:46.178Z","v":0}

Pretty-printed:

{
  "name": "myserver",
  "hostname": "banana.local",
  "pid": 123,
  "req": {
    "method": "GET",
    "url": "/path?q=1#anchor",
    "headers": {
      "x-hi": "Mom",
      "connection": "close"
    },
    "remoteAddress": "120.0.0.1",
    "remotePort": 51244
  },
  "level": 3,
  "msg": "start request",
  "time": "2012-02-03T19:02:57.534Z",
  "v": 0
}

Core fields:

Go ahead and add more fields, and nest ones are fine (and recommended) as well. This is why we're using JSON. Some suggestions and best practices follow (feedback from actual users welcome).

Recommended/Best Practice Fields:

Other fields to consider:

Streams

A "stream" is Bunyan's name for an output for log messages (the equivalent to a log4j Appender). Ultimately Bunyan uses a Writable Stream interface, but there are some additional attributes used to create and manage the stream. A Bunyan Logger instance has one or more streams. In general streams are specified with the "streams" option:

var Logger = require('bunyan');
var log = new Logger({
  name: "foo",
  streams: [
    {
        stream: process.stderr,
        level: "debug"
    },
    ...
  ]
})

For convenience, if there is only one stream, it can specified with the "stream" and "level" options (internal converted to a Logger.streams):

var log = new Logger({
  name: "foo",
  stream: process.stderr,
  level: "debug"
})

If none are specified, the default is a stream on process.stdout at the "info" level.

Logger.streams is an array of stream objects with the following attributes:

Supported stream types are:

License

MIT.

Future

See "TODO.md", but basically: