node-bunyan-lite/README.md

Bunyan -- a JSON Logger for node.js servers.

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

Just play stuff here. Don't try to use this for realz yet.

Usage

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

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

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

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

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 (<no-request_id>)

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

By default, log output is to stdout. Explicitly that looks like:

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

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

var log = new Logger({
  service: "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
    }
  ]
});

Support for syslog is planned.

Future

See "TODO.md", but basically:

• "Renderer" support to handle extracting a JSON object for a log record for particular object types, e.g. an HTTP request. So for example we could do:

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

  And the "req" renderer would extract a reasonable JSON object for that request object -- presumably a subset of all attributes on the request object.

  This will key off the field name, IOW by convention, rather than getting into instanceof grossness.

• Spec'ing and enforcing the fields (from dap's section in eng guide).

• Syslog support. Ring-buffer support for storing last N debug messages (or whatever) in memory to support debugability without too much log load.

• More bunyan output formats and filtering features.

• Think about a bunyan dashboard that supports organizing and viewing logs from multiple hosts and services.

Levels

fatal
error
warn
info
debug

TODO: doc these.

Log Record Fields

TODO: from dap and enforce these

• "request_id" (better name?) can't be required because some things don't happen in a per-request context. Startup and background processing stuff for example. Tho for request-y things, it is strongly encouraged because it allows collating logs from multiple services for the same request.

License

MIT.