This is a conversion of the [log4js](http://log4js.berlios.de/index.html)
framework to work with [node](http://nodejs.org). I've mainly stripped out the browser-specific code and tidied up some of the javascript.
This was a conversion of the [log4js](http://log4js.berlios.de/index.html)
framework to work with [node](http://nodejs.org). 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
* replacement of node's console.log functions (optional)
* file appender, with log rolling based on file size
* SMTP appender
* GELF appender
* hook.io appender
* multiprocess appender (useful when you've got worker processes)
* a logger for connect/express servers
* 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: from log4js 0.5 onwards you'll need to explicitly enable replacement of node's console.log functions. Do this either by calling `log4js.replaceConsole()` or configuring with an object or json file like this:
```javascript
{
appenders: [
{ type: "console" }
],
replaceConsole: true
}
```
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](http://github.com/nomiddlename/log4js-node/0.7-changes)
## installation
npm install log4js
npm install log4js
## usage
Minimalist version:
```javascript
var log4js = require('log4js');
var logger = log4js.getLogger();
logger.debug("Some debug messages");
```
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](http://github.com/masylum)), so for the above you would see:
```bash
[2010-01-17 11:43:37.987] [DEBUG] [default] - Some debug messages
```
See example.js for a full example, but here's a snippet (also in fromreadme.js):
```javascript
var log4js = require('log4js');
//console log is loaded by default, so you won't normally need to do this
An example file can be found in `test/log4js.json`. An example config file with log rolling is in `test/with-log-rolling.json`.
By default, the configuration file is checked for changes every 60 seconds, and if changed, reloaded. This allows changes to logging levels to occur without restarting the application.
To turn off configuration file change checking, configure with:
If you have already defined an absolute path for one of the FileAppenders in the configuration file, you could add a "absolute": true to the particular FileAppender to override the cwd option passed. Here is an example configuration file:
```json
#### my_log4js_configuration.json ####
{
"appenders": [
{
"type": "file",
"filename": "relative/path/to/log_file.log",
"maxLogSize": 20480,
"backups": 3,
"category": "relative-logger"
},
[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
Documentation for most of the core appenders can be found on the [wiki](https://github.com/nomiddlename/log4js-node/wiki/Appenders), otherwise take a look at the tests and the examples.
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
Gareth Jones
11 years ago