Talk: Caterpillar @ SydJS

README.md

Caterpillar @ SydJS

Featured in JavaScript Weekly: Issue #128 - May 3, 2013

Located at bevry/caterpillar

Created by Benjamin Lupton, @balupton

Why should we care?

• Used in production since 2011
• Logging system for DocPad (the most popular Static Site Generator for Node.js) and others
• Log levels are standards compliant so logging across modules can get along
• Will output debugging information such as line, method, and file when using log level 7 (debug level)
• Can filter out uncessary log entries using filter transform
• Can customise the output however you want via your own Transform Streams
• Works in node and in web browsers via browserify

How can I use it?

Install

npm install --save caterpillar caterpillar-filter caterpillar-human

Applications

As seen in DocPad, DocPad Helper, and a bunch of others

// Setup
var level  = process.argv.indexOf('-d') === -1 ? 6 : 7;
var logger = require('caterpillar').createLogger({level:level});
var filter = require('caterpillar-filter').createFilter();
var human  = require('caterpillar-human').createHuman();

// Pipe logger output to filter, then filter output to stdout
logger.pipe(filter).pipe(human).pipe(process.stdout);

// If we are debugging, then write the original logger data to debug.log
if ( level === 7 ) {
    logger.pipe(require('fs').createWriteStream('./debug.log'));
}

// Log messages
logger.log('emergency', 'this is level 0');
logger.log('emerg', 'this is level 0');
logger.log('alert', 'this is level 1');
logger.log('critical', 'this is level 2');
logger.log('crit', 'this is level 2');
logger.log('error', 'this is level 3');
logger.log('err', 'this is level 3');
logger.log('warning', 'this is level 4');
logger.log('warn', 'this is level 4');
logger.log('notice', 'this is level 5');
logger.log('note', 'this is level 5');
logger.log('info', 'this is level 6');
logger.log('default', 'this is level 6');
logger.log('debug', 'this is level 7');
logger.log('this is level 6, the default level');
logger.log('you','can','also','use','as','many','arguments','as','you','want',1,[2,3],{four:5});

Modules

As seen in GetContributors, GetRepos, and Feedr

# As a module
class MyModule
    # Create our module and accept configuration
    constructor: (@config) ->
        @config ?= {}

    # Log some data if a log method has been defined
    log: (args...) ->  @config.log?(args...)

    # Do something awesome
    doSomething: ->
        @log('info', 'about to do something awesome')

# Export our module
module.exports = {
    MyModule
    create: (args...) ->  new MyModule(args...)
}

// Setup
var level  = process.argv.indexOf('-d') === -1 ? 6 : 7;
var logger = require('caterpillar').createLogger({level:level});
var filter = require('caterpillar-filter').createFilter();
var human  = require('caterpillar-human').createHuman();

// Pipe logger output to filter, then filter output to stdout
logger.pipe(filter).pipe(human).pipe(process.stdout);

// If we are debugging, then write the original logger data to debug.log
if ( level === 7 ) {
    logger.pipe(require('fs').createWriteStream('./debug.log'));
}

// Use our module in an application
var myModule = require('./my-module.js').create({
    // log: console.log.bind(console)
    log: logger.log.bind(logger)  // logger defined elsewhere
});
myModule.doSomething();

Future

• Loggly Transform