Neutral Pork Motel


    1.3.3 • Public • Published

    book Build Status

    book is a flexible and extensible logging library for node.js

    Instead of trying to solve the problem of figuring out what and how you want to do logging in your project, book provides some basic functions for you to customize and create the logging system you want. Think of it like middleware, except for logging.


    npm install book


    To get started with basic logging, just require('book') and start logging!

    var log = require('book');
    // You can now log using the methods: panic, error, warn, info, debug, trace'haters be loggin');

    Will output (on stdout):

    [info] haters be loggin

    how to log

    Below are the basics of logging using the default logger.

    There are 6 log levels ( panic | error | warn | info | debug | trace ). See the examples.

    The arguments you pass to the logging functions will determine how they are processed.

    // if the first argument is a string, it is assumed to be a format string
    // it will consume all of the remaining arguments when formatting'hello world');
    [info] hello world
'secret: %d', 42);
    [info] secret 42
'json: %j', { secret: 42 });
    [info] { "secret": 42 }
    // if the first argument is an Error
    // the logger will capture the stacktrace into error.stack of the final log entry
    log.error(new Error('fail!'));
    [error] fail!
    // any arguments after the first Error arg are processed as if they appeared as the first
    // you can capture an error and print other messages
    log.error(new Error('again?'), 'another %s', 'cat');
    [error] another cat
    // lastly, the first argument can be an object
    // this will cause the fields of the object to the added to the fields of the final log entry
    // after the first arguments, remaining arguments are again treated as if they were the first
    log.warn({ something: 'bad' }, 'foo %s', 'bar');
    // will print the message 'foo bar', however the {something: 'bad'} object can be accessed in your custom middleware as you please.
    [warn] foo bar

    Note: Only when a string is encountered are all of the remaining arguments consumed. Until then, each argument is processed independently as if it appeared first.

    If you want your logs to go to a file, use the book-file module.


    The default logging setup will write logs to stdout. If you would like to disable this behavior use the following:

    var log = require('book').default({
      stdout: false

    This will give you a new default logger with no output to stdout. For more flexible configuration read about middleware below.


    The entire functionality of the default logger is built using middleware. These create pipeline of 'features' for the logger. You can customize loggers to include/exclude any features you want. Middleware can add fields to the logging output our it can act as a transport to send the log entry someplace else.

    The 'default' logger is simply a certain selection of middleware provided with the library. You are not required to use it and can roll your own custom solution.

    make your own

    Middleware is simply a function which will do some processing on the logging entry. It is passed all of the arguments of the original log call (info, error, etc) and the 'this' is set to the logging entry. Your middleware should modify the fields of 'this' to add or remove relevant entries.

    // simple middleware that adds a timestamp to the entry
    function sample_middleware() {
      var entry = this;
      // this is the only provided field
      // set to [0..5] 0=panic, by the called log functions
      // usually you won't change this
      // add a new field to our entry
      entry.timestamp =;

    Decorators are processed in the order you push them onto a logger.

    using your middleware

    // book.blank creates a logging object with no middleware
    var log = require('book').blank();
    // remember, middleware is processed in the order you use it
    // you can now call any of the logging functions'hello');
    // output will depend on any middleware you have added
    // use any of the provided middleware to build up your own logger

    attaching middleware

    You can add middleware to the default logger similar to the blank logger above. Lets say we want to provide out own middleware to print to stdout. We can disable the default stdout and provide out own.

    // create a default logger with no stdout middleware
    var log = require('book').default({
      stdout: false
    log.use(function() {
      var entry = this;
      // our own code for printing to stdout
      // console.log(...);
    // this will use our own stdout middleware'hello world!');

    provided middleware

    Book ships with some builtin middleware. You can access it with:

    var book_middleware = require('book').middleware;

    The default logger is composed from this middleware. Use a blank logger if you want to pick and choose which ones to use.


    provides the basic argument processing outlined above


    provides tracing where the log line was called. Adds 'filename' and 'lineno' fields to the log entry. This is different from the stack trace of Errors. This is the filename and lineno of the call site of the log line.


    basic printing to console


    inserts a 'hostname' field into the entry


    inserts a 'timestamp' entry (seconds using

    middleware modules

    There are a number of npm modules which provide various transports and other logging features.


    book-file records your log entries to a file.

    You can add the file transport to your logger using the following:

          filename: '/path/to/file.log'


    book-email sends your log messages over email.


    book-git adds a commit field to your log entry which has the deployed git commit id.


    npm i book

    DownloadsWeekly Downloads






    Last publish


    • defunctzombie