improved the readme
This commit is contained in:
Gareth Jones
parent
6dabcf5ee5
commit
245b2e3b1a
193
README.md
193
README.md
@ -1,134 +1,121 @@
|
||||
# log4js-node [](http://travis-ci.org/nomiddlename/log4js-node)
|
||||
|
||||
|
||||
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
|
||||
//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');
|
||||
logger.setLevel('ERROR');
|
||||
[2010-01-17 11:43:37.987] [DEBUG] default - Some debug messages
|
||||
|
||||
logger.trace('Entering cheese testing');
|
||||
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' }
|
||||
]
|
||||
});
|
||||
```
|
||||
See the examples directory for lots of sample setup and usage code.
|
||||
|
||||
## 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
|
||||
configuration file (`log4js.configure('path/to/file.json')`), or a configuration object. The
|
||||
configuration file location may also be specified via the environment variable
|
||||
LOG4JS_CONFIG (`export LOG4JS_CONFIG=path/to/file.json`).
|
||||
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.
|
||||
### 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:
|
||||
|
||||
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
|
||||
var log4js = require('log4js');
|
||||
log4js.configure('my_log4js_configuration.json', {});
|
||||
```
|
||||
To specify a different period:
|
||||
The default configuration for log4js, the one used if `configure` is
|
||||
not called, looks like this:
|
||||
|
||||
```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": [
|
||||
{
|
||||
"type": "file",
|
||||
"filename": "relative/path/to/log_file.log",
|
||||
"maxLogSize": 20480,
|
||||
"backups": 3,
|
||||
"category": "relative-logger"
|
||||
},
|
||||
{
|
||||
"type": "file",
|
||||
"absolute": true,
|
||||
"filename": "/absolute/path/to/log_file.log",
|
||||
"maxLogSize": 20480,
|
||||
"backups": 10,
|
||||
"category": "absolute-logger"
|
||||
"appenders": {
|
||||
"console": { "type": "console" }
|
||||
},
|
||||
"categories": {
|
||||
"default": { level: "TRACE", appenders: [ "console" ] }
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
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
|
||||
See the [wiki](https://github.com/nomiddlename/log4js-node/wiki). Improve the [wiki](https://github.com/nomiddlename/log4js-node/wiki), please.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user