README.md

zest / base.logger

base.logger is a basic logger component used throughout zest to create log files or to log onto the node console. It can be used as a zest component or as a standalone module

initialization

the base logger module exports a function which returns a logger object. The logger object can then be used to log messages.

configuring the base logger

To create a logger with all defaults, we just call the exported module function.

// create the logger
var logger = require('base.logger')();
// start logging
logger.debug('hello zest!');

However, additional configurations can also be provided.

If initialized with an array, the logger will assume it to be an array of configuration options.

// create the logger
var logger = require('base.logger')([
    // configuration option
    {
        match: '^.*$', // group patterns matcher
        appender: 'console', // where to log
        level: 'debug', // the log level
        pattern: '%t[HH.mm.ss.SSS]|%-1.1l%20.20g| %m' // the logger pattern
    }
]);
// start logging
logger.debug('hello zest!');

If a string is used for initialization, it is assumed to be the group name. The logger will initialize with default configuration (which makes it log everything to console) and the returned logger will have its group initialized

// create the logger
var logger = require('base.logger')('main');
// start logging
logger.debug('hello zest!');

To initialize the logger with both the group and settings, we use an object form as shown below.

// create the logger
var logger = require('base.logger')({
    group: 'main',
    settings: [
        // configuration option
        {
            match: '^.*$', // group patterns matcher
            appender: 'console', // where to log
            level: 'debug', // the log level
            pattern: '%t[HH.mm.ss.SSS]|%-1.1l%20.20g| %m' // the logger pattern
        }
    ]
});
// start logging
logger.debug('hello zest!');

configuration options

• match will ignore this configuration for group patterns that do not match the regex provided in this property

• appender tells the logger where to log. Possible values are console and file

• appenderOptions is a map of options passed to the appender. For console appenders, this is not required. For file appender, the appender options contain two properties.

  • path which is the path to the file where the logs should be saved. The path should be without extension.

  • roll option if used, defines when new log files should be created and how it should be rolled. roll can be any momentjs date format. the file name of log files will be appended with the time formated in the specified format and whenever the parsed value changes, a new log file will be created.

    For example,

    a value of YYYYM will create one file for each month.

    For Jan 2015, the filename will be <<value of path>>-20151.log.

• level is the log level upto which logging should happen. Possible values are debug, info, warn, error and none.

• pattern is the pattern used for formatting the logs. The value can be a string or an object.

  • If the value is a string, the same pattern will be used for logging debug, info, warn and error messages

  • If the value is an object, it should have keys debug, info, warn and error, each with their pattern strings.

the pattern strings

Pattern Strings are parsed to generate logs. The conversion pattern is closely related to the conversion pattern of the printf function in C. A conversion pattern is composed of literal text and format control expressions called conversion specifiers.

Each conversion specifier starts with a percent sign (%) and is followed by optional format modifiers and a conversion character. The conversion character specifies the type of data, e.g. level, group, message and time. The format modifiers control such things as field width, padding, left and right justification. Any literal text can be inserted within the conversion pattern.

The conversion characters are:

• g for outputting the group name
• l for outputting the log level
• t for outputting the current time
• m for outputting the actual log

A typical conversion specifier will be of the form

%[<<- for left align>>][<<minwidth>>][.][<<max width>>]<<conversion character>>[<<format>>]

format are supported only in case of Dates and is should be moment.js compatible

Example:

%10g | %4.4l - %t[dd/MM/yyyy] - %m

would yield the output

modulename |ebug - [12/12/2014] - Message 1
modulename |warn - [12/12/2014] - Message 1

%15g | %4l - %t[dd/MM/yyyy] - %m

would yield the output

     modulename |debug - [12/12/2014] - Message 1
     modulename |warn - [12/12/2014] - Message 1

grouping logs

Groups are used to aggregate log statements and identify them. Groups can be displayed in the logs by using the %g conversion specifier.

Every Logger object has a group method that creates a new Logger object with the new group name as parentgroup / newGroup

This helps in filtering log statements in configurations. Typically, Every module should log into its own group.