jlog

Description

jlog is a log4j alike logging framework using the concept of handlers, appenders, loggers, log levels and filters. the configuration can be done by a configuration file assigned via an ENV var or directly in the code. The Logging Handlers can be wrappers around any other node logging library like winston or debug.

Motivation

• Configuration by ENV vars for certain environments.
• log4j alike flexibility to configure logger names to certain logging handlers and log levels.
• Easy extentibility by Handlers that are wrapping third party logging modules

Usage

logger = require('jlog')('logger.name')

logger.debug('debug msg')
logger.error('error msg')

find the log levels at lib/levels.coffee

find implemented handlers at lib/handlers.coffee

Configuration

if the ENV var JLOG_CONFIG points to an existing file, this configuration is used, otherwise the first file found backwards in the directory tree starting from process cwd with the name jlog_config.json or etc/jlog_config.json is used, otherwise the first file found backwards in the directory tree starting from jlog __dirname with the name jlog_config.json or etc/jlog_config.json is used, otherwise the default configuration is used, that is logging just errors to the console

programmatic configuration is possible by the log manager

logManager = require('jlog/api').logManager
logManager.reConfig({ someConfig })

Configuration File Handler section

in the configuration handler part the handlers are configured. each key needs at least a class attribute that is found in lib/handlers

example:

"handler": {
    "console": {
        "class": "ConsoleHandler",
        "formatter": "SimpleFormatter"
    },
    "winstonFile": {
        "class": "WinstonHandler",
        "config": {
            "file": {
                "filename": "winston.log",
                "level": "all"
            }
        }
    },
    "debug": {
        "class": "DebugHandler"
    }

The DebugHandler is a wrapper for npm 'debug', the WinstonHandler is a wrapper for npm 'winston' module. the winston config attribute takes any winston configuration.

Configuration File Handler section

example:

"logger": [
    {"name": "*", "handler": "debug", "level": "debug" },
    {"name": "*", "handler": "console", "level": "error" },
    {"name": "foo", "handler": "console", "level": "warn" },
    {"name": "foo", "handler": "winstonFile", "level": "info" },
    {"name": "foo.bar", "handler": "console", "level": "info" },
    {"name": "foo.bar.foo.file", "handler": "winstonFile", "level": "debug" }
]

the logger section defines a list of logger names that are assigned to a log handler and a log level. it is logger used, that bests matched the logger name. the matching starts form the beginning of the logger name. if there are more then one best matching loggers found, all matched handlers are used. if no matching logger name is found, the fallback is the logger with the asteriks.

logger1 = require('jlog')('bar.foo')
logger1.debug('is matching the first two entries, logging to handler debug')
logger1.error('is matching the first two entries, logging to handler debug and handler error')

logger2 = require('jlog')('foo.foo.bar')
logger2.info('is matching the 3. and 4. entries, logging to handler winstonFile')
logger2.error('dito, logging to handler console and winstonFile')

logger3 = require('jlog')('foo.bar.foo.file')
logger3.info('is matching the last entries, logging to handler winstonFile')

convention

as convention for logger names it is recommended to use a pattern like

<projectname>.<dirname>[.<filename>]

runninung tests and samples

# run "npm install" once after checkout

# run mocha tests:
npm test

# run samples:
JLOG_CONFIG=<absolute_path_to_dir>/examples/jlog_sample.json  coffee examples/jlog_sample.coffee

development

development is taking place in the coffee files in the src folder. the javascript files are generated into the lib directory with the command:

cake build