From 245b2e3b1a3108600082d810eba018f96ee2a445 Mon Sep 17 00:00:00 2001 From: Gareth Jones Date: Fri, 13 Sep 2013 08:17:22 +1000 Subject: [PATCH] improved the readme --- README.md | 193 +++++++++++++++++++++++++----------------------------- 1 file changed, 90 insertions(+), 103 deletions(-) diff --git a/README.md b/README.md index 6e479d6..8b6af75 100644 --- a/README.md +++ b/README.md @@ -1,134 +1,121 @@ # 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) -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.