log4js-node

This was a conversion of the log4js framework to work with node. It's changed a lot since then, but there are still plenty of the original parts involved.

Out of the box it supports the following features:

• coloured console logging
• file appender, with log rolling based on file size or date
• multi-process logging (works fine with node's clusters)
• configurable log message layout/patterns
• different log levels for different log categories (make some parts of your app log as DEBUG, others only ERRORS, etc.)

NOTE: There have been a lot of changes in version 0.7.x, if you're upgrading from an older version, you should read 0.7-changes

installation

npm install log4js

usage

Minimalist version:

var log4js = require('log4js');
var logger = log4js.getLogger();
logger.debug("Some debug messages");

By default, log4js outputs to stdout with the coloured layout (thanks to masylum), so for the above you would see:

[2010-01-17 11:43:37.987] [DEBUG] default - Some debug messages

See the examples directory for lots of sample setup and usage code.

API

Log4js exposes two public functions: configure and getLogger. If you're writing your own appender, your code will get access to some internal APIs, see writing-appenders.

log4js.configure(config)

Configure takes a single argument. If that argument is a string, it is considered the path to a JSON file containing the configuration object. If the argument is an object, it must have the following fields:

• appenders (Object) - this should be a map of named appenders to their configuration. At least one appender must be defined.
• categories (Object) - this should be a map of logger categories to their levels and configuration. The "default" logger category must be defined, as this is used to route all log events that do not have an explicit category defined in the config. Category objects have two fields: * level - (String) the log level for that category: "trace", "debug", "info", "warn", "error", "fatal", "off" * appenders - (Array) the list of appender names to which log events for this category should be sent

The default configuration for log4js, the one used if configure is not called, looks like this:

{
  "appenders": {
      "console": { "type": "console" }
  },
  "categories": {
      "default": { level: "TRACE", appenders: [ "console" ] }
  }
}

Use of the default configuration can be overridden by setting the LOG4JS_CONFIG environment variable to the location of a JSON configuration file. log4js will use this file in preference to the defaults, if configure is not called. An example file can be found in test/log4js.json. An example config file with log rolling is in test/with-log-rolling.json.

log4js.getLogger([category])

• category (String), optional. Category to use for log events generated by the Logger.

Returns a Logger instance. Unlike in previous versions, log4js does not hold a reference to Loggers so feel free to use as many as you like.

Logger

Loggers provide the following functions:

• trace
• debug
• info
• warn
• error
• fatal

All can take a variable list of arguments which are used to construct a log event. They work the same way as console.log, so you can pass a format string with placeholders. e.g.

logger.debug("number of widgets is %d", widgets);

Appenders

Log4js comes with file appenders included, which can be configured to roll over based on a time or a file size. Other appenders are available as separate modules:

• log4js-gelf
• log4js-smtp
• log4js-hookio

There's also log4js-connect, for logging http access in connect-based servers, like express.

Documentation

See the wiki. Improve the wiki, please.

Contributing

Contributions welcome, but take a look at the rules first.

License

The original log4js was distributed under the Apache 2.0 License, and so is this. I've tried to keep the original copyright and author credits in place, except in sections that I have rewritten extensively.