cartodb4/log4js-node
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

improved the readme

Browse Source
This commit is contained in:
Gareth Jones 2013-09-13 08:17:22 +10:00
parent 6dabcf5ee5
commit 245b2e3b1a
1 changed files with 90 additions and 103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

181
README.md
View File

@ -1,32 +1,18 @@
# log4js-node [![Build Status](https://secure.travis-ci.org/nomiddlename/log4js-node.png?branch=master)](http://travis-ci.org/nomiddlename/log4js-node) # log4js-node [![Build Status](https://secure.travis-ci.org/nomiddlename/log4js-node.png?branch=master)](http://travis-ci.org/nomiddlename/log4js-node)
This is a conversion of the [log4js](http://log4js.berlios.de/index.html) This was 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. 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: Out of the box it supports the following features:
* coloured console logging * coloured console logging
* replacement of node's console.log functions (optional) * file appender, with log rolling based on file size or date
* file appender, with log rolling based on file size * multi-process logging (works fine with node's clusters)
* SMTP appender
* GELF appender
* hook.io appender
* multiprocess appender (useful when you've got worker processes)
* a logger for connect/express servers
* configurable log message layout/patterns * 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.) * 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: 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)
```javascript
{
appenders: [
{ type: "console" }
],
replaceConsole: true
}
```
## installation ## installation
@ -36,99 +22,100 @@ npm install log4js
## usage ## usage
Minimalist version: Minimalist version:
```javascript
var log4js = require('log4js'); var log4js = require('log4js');
var logger = log4js.getLogger(); var logger = log4js.getLogger();
logger.debug("Some debug messages"); 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: 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
//log4js.loadAppender('console');
log4js.loadAppender('file');
//log4js.addAppender(log4js.appenders.console());
log4js.addAppender(log4js.appenders.file('logs/cheese.log'), 'cheese');
var logger = log4js.getLogger('cheese'); [2010-01-17 11:43:37.987] [DEBUG] default - Some debug messages
logger.setLevel('ERROR');
logger.trace('Entering cheese testing'); See the examples directory for lots of sample setup and usage code.
logger.debug('Got cheese.');
logger.info('Cheese is Gouda.');
logger.warn('Cheese is quite smelly.');
logger.error('Cheese is too ripe!');
logger.fatal('Cheese was breeding ground for listeria.');
```
Output:
```bash
[2010-01-17 11:43:37.987] [ERROR] cheese - Cheese is too ripe!
[2010-01-17 11:43:37.990] [FATAL] cheese - Cheese was breeding ground for listeria.
```
The first 5 lines of the code above could also be written as:
```javascript
var log4js = require('log4js');
log4js.configure({
appenders: [
{ type: 'console' },
{ type: 'file', filename: 'logs/cheese.log', category: 'cheese' }
]
});
```
## configuration ## 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](http://github.com/nomiddlename/log4js-node/writing-appenders.md).
You can configure the appenders and log levels manually (as above), or provide a ### log4js.configure(config)
configuration file (`log4js.configure('path/to/file.json')`), or a configuration object. The Configure takes a single argument. If that argument is a string, it is
configuration file location may also be specified via the environment variable considered the path to a JSON file containing the configuration
LOG4JS_CONFIG (`export LOG4JS_CONFIG=path/to/file.json`). object. If the argument is an object, it must have the following
An example file can be found in `test/log4js.json`. An example config file with log rolling is in `test/with-log-rolling.json`. fields:
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: * `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
```javascript The default configuration for log4js, the one used if `configure` is
var log4js = require('log4js'); not called, looks like this:
log4js.configure('my_log4js_configuration.json', {});
```
To specify a different period:
```javascript
log4js.configure('file.json', { reloadSecs: 300 });
```
For FileAppender you can also pass the path to the log directory as an option where all your log files would be stored.
```javascript
log4js.configure('my_log4js_configuration.json', { cwd: '/absolute/path/to/log/dir' });
```
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": [ "appenders": {
{ "console": { "type": "console" }
"type": "file",
"filename": "relative/path/to/log_file.log",
"maxLogSize": 20480,
"backups": 3,
"category": "relative-logger"
}, },
{ "categories": {
"type": "file", "default": { level: "TRACE", appenders: [ "console" ] }
"absolute": true,
"filename": "/absolute/path/to/log_file.log",
"maxLogSize": 20480,
"backups": 10,
"category": "absolute-logger"
} }
]
} }
```
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
available as separate modules:
* [log4js-gelf](http://github.com/nomiddlename/log4js-gelf)
* [log4js-smtp](http://github.com/nomiddlename/log4js-smtp)
* [log4js-hookio](http://github.com/nomiddlename/log4js-hookio)
There's also
[log4js-connect](http://github.com/nomiddlename/log4s-connect), for
logging http access in connect-based servers, like express.
## Documentation ## Documentation
See the [wiki](https://github.com/nomiddlename/log4js-node/wiki). Improve the [wiki](https://github.com/nomiddlename/log4js-node/wiki), please. See the [wiki](https://github.com/nomiddlename/log4js-node/wiki). Improve the [wiki](https://github.com/nomiddlename/log4js-node/wiki), please.