126 lines
3.4 KiB
Markdown
126 lines
3.4 KiB
Markdown
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.
|
|
|