README.md

justlog

justlog , focus on logging

Features:

• coloured console logging
• file appender, with log rotate based on time
• configurable log message/patterns
• different log levels for different log categories (info debug warn error )
• can use as a connect middleware for access-log

Installation

npm install justlog

Usage

Getting start

// simple.js
var justlog = require('justlog');

var log = justlog(); 
l.info('simple', 'info');
l.debug({a:1, b:2});
l.warn([1,2,3,4]);
l.error('name:%s, number:%d', 'somename', 123);

$ node simple.js

the stdout/stderr is as below

19:01:41 INFO  a.js:4 simple info
19:01:41 DEBUG a.js:5 {"a":1,"b":2}
19:01:41 WARN  a.js:6 1,2,3,4
19:01:41 ERROR a.js:7 name:somename, number:123

and also, you can got a log file on logs/simple-%Y-%M-%D.log

2013-01-06 19:01:41 [WARN] (a.js:6) 1,2,3,4
2013-01-06 19:01:41 [ERROR] (a.js:7) name:somename, number:123

Change log levels

var log = justlog({
  file : {level: justlog.INFO | justlog.WARN} // file log levels
  stdio : {level: justlog.DEBUG | justlog.ERROR} // stdio log levels
});

available levels

• justlog.INFO
• justlog.DEBUG
• justlog.WARN
• justlog.ERROR
• justlog.ALL include all 4 level above
• justlog.EXCEPTION include WARN and ERROR

Log only one way

var stdLog = justlog({file : false}); // not write log file, only use stdio
var fileLog = justlog({stdio : false}); // not use stdio, only write a log file
});

log error & warn messages into stdout

var log = justlog({
  stdio: {
    stderr: process.stdout
  }
});

custom log file path & log file rotate

// write logs into filename.log and never rotate
var log1 = justlog({
  file: {
    path : '[filename.log]'
  }
});

// write logs into filename-%Y-%M-%D.log, and rotate every days
var log2 = justlog({
  file: {
    path : '[filename]-YYYY-MM-DD[.log]'
  }
}); 

time format use moment string-format

rotate will be trigger when log filename changed.

custom log line format

var log = justlog({
  file : {
    pattern : '{fulltime} [{level}] {msg}' // use custom pattern
  }
  stdio : {
    pattern : 'simple-color' // use predefined pattern
  }
});
log.warn('log msg');

All options

{
  file : {
    level           : error | warn, // levels for filelog
    pattern         : 'file', // filelog pattern
    path            : '[logs/%main_script_name]YYYY-MM-DD[.log]', // log file path
    mode            : '0664', // log file mode
    dir_mode        : '2775', // if log dir is not exists, log dir mode when create
    _watcher_timeout : 5007,  // log file renamed watch timeout, DO NOT CHANGE THIS IF YOU REALLY KNOWN WHAT YOU DO.
  },
  stdio : {
    level   : error | warn | debug | info, // levels for stdio
    pattern : 'color', // stdio pattern
    stdout  : process.stdout, // stdout stream (for info & debug log)
    stderr  : process.stderr, // stderr stream (for warn & error log)
  }
}

Middleware

a connect middleware for apache-like accesslog.

middleware's has same options as normally justlog object, but has different default value

var app = connect();
app.use(justlog.middleware({}));

Middleware default options

{
  file: {
    path    : '[logs/%main_script_name-access-]YYYY-MM-DD[.log]',
    pattern : 'accesslog-rt'
  }
  stdio :
    pattern : 'accesslog-color'
}

Buffer Log

you can buffer your log if you have big visits.

var log = justlog({
  duration : 1000, // flush buffer time, default is 1000
  bufferLength : 1000 // max buffer length, default is 0
  //... other options
});

or

var log = justlog.create({
  duration : 1000, // flush buffer time, default is 1000
  bufferLength : 1000 // max buffer length, default is 0
});

default options

{
  duration : 1000,
  bufferLength : 0,
  // file: ...
  // stdio : ...
}

close buffer log

justlog.end(cb);

About log pattern

Justlog has a powerful log line pattern support. You can use variables, objects and functions in you patterns. And you can define ansi color output patterns easily.

Syntax

{var[ args...][@colors...]}

• "{variable_name}": show varaible's value. eg. {remote-address}
• "{object_name.prop_name}": show property value. eg. {headers.accepted-encoding}
• "{function_name "const1", "const2"}": show function's return value with const arguments. eg. {now "YYYY-MM-DD"}
• "{function_name variable_name, object_name.prop_name}": show function's return value with variable arguments. eg. {color.status status-code}
• "{something@color1,color2}": set output ansi color. eg. {url@blue,underline}

Predefine variables

• msg : (all log arguments).toString()
• level : log level text align ("INFO ", "DEBUG", "WARN ", "ERROR")
• levelTrim : log level text without align ("INFO", "DEBUG", "WARN", "ERROR")
• file : log triggered file path
• lineno : log triggered code line number
• stack : alias for "file:lineno"
• stackColored : alias for colored stack
• time : time format as "HH:mm:ss"
• date : time format as "YYYY-MM-DD"
• fulltime : time format as "YYYY-MM-DD HH:mm:ss"
• numbertime : time format as "YYYYMMDDHHmmss"
• mstimestamp : unix timestamp (with milliseconds)
• timestamp : unix timestamp (with seconds)

Predefined functions

• now : now formater function. eg. {now "YYYY-MM-DD"}
• color.status : add color for http status code. eg. {color.status status}
• color.method : add color for http request method. eg. {color.method method}
• color.event : add color for event type. eg. {color.event event}
• color.level : add color for log level. eg. {color.level level}

Predefined patterns

• simple-color: log message and colored level text
• simple-nocolor: like simple without color
• color: tracestack, time, log message and colored level text
• nocolor: like color without color
• event-color: time, log message and colored event
• event-nocolor: like event-color without color
• file : fulltime, tracestack, log message and level text
• accesslog: apache access-log
• accesslog-rt: like access-log with response-time on the end (with microsecond)
• accesslog-color: like accesslog-rt with ansi colored

License

justlog is published under BSD license.