8000 docs(appenders): made a start on documenting the appenders · commontime/log4js-node@e94a351 · GitHub
[go: up one dir, main page]
Skip to content

Commit e94a351

Browse files
author
Gareth Jones
committed
docs(appenders): made a start on documenting the appenders
1 parent 7536aa2 commit e94a351

File tree

5 files changed

+103
-9
lines changed

5 files changed

+103
-9
lines changed

‎README.md

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,9 @@
66
NOTE: this documentation is for version 2.x, which is a work-in-progress. You probably want to look at [version 1.1.1 docs](https://github.com/nomiddlename/log4js-node/tree/v1.1.1) instead.
77

88
This is a conversion of the [log4js](https://github.com/stritti/log4js)
9-
framework to work with [node](http://nodejs.org). I've mainly stripped out the browser-specific code and tidied up some of the javascript. Although it's got a similar name to the Java library [log4j](https://logging.apache.org/log4j/2.x/), thinking that it will behave the same way will only bring you sorrow and confusion.
9+
framework to work with [node](http://nodejs.org). I started out just stripping out the browser-specific code and tidying up some of the javascript to work better in node. It grew from there. Although it's got a similar name to the Java library [log4j](https://logging.apache.org/log4j/2.x/), thinking that it will behave the same way will only bring you sorrow and confusion.
10+
11+
The full documentation is available [here](https://nomiddlename.github.io/log4js-node/).
1012

1113
Out of the box it supports the following features:
1214

@@ -64,12 +66,8 @@ Output (in `cheese.log`):
6466
[2010-01-17 11:43:37.990] [FATAL] cheese - Cheese was breeding ground for listeria.
6567
```
6668

67-
You can also see a full Express application example in [log4js-example](https://github.com/nomiddlename/log4js-example).
68-
69-
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.
70-
7169
## Documentation
72-
See the [wiki](https://github.com/nomiddlename/log4js-node/wiki). Improve the [wiki](https://github.com/nomiddlename/log4js-node/wiki), please.
70+
Available [here](https://nomiddlename.github.io/log4js-node/).
7371

7472
There's also [an example application](https://github.com/nomiddlename/log4js-example).
7573

‎docs/api.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
## API
22

3-
## configuration - `log4js.configure([object || string])`
3+
## configuration - `log4js.configure(object || string)`
44

5-
There is one entry point for configuring log4js. With no argument, or a falsy argument, log4js will load configuration from the file path given by the environment variable `LOG4JS_CONFIG` or it will use the default config if that environment variable is not present. A string argument is treated as a filename to load configuration from. Config files should be JSON, and contain a configuration object (see format below). You can also pass a configuration object directly to `configure`.
5+
There is one entry point for configuring log4js. A string argument is treated as a filename to load configuration from. Config files should be JSON, and contain a configuration object (see format below). You can also pass a configuration object directly to `configure`.
66

77
Configuration should take place immediately after requiring log4js for the first time in your application. If you do not call `configure`, log4js will use `LOG4JS_CONFIG` (if defined) or the default config. The default config logs everything to stdout using the coloured layout.
88

‎docs/appenders.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Log4js - Appenders
2+
3+
Appenders serialise log events to some form of output. They can write to files, send emails, send data over the network. All appenders have a `type` which determines which appender gets used. For example:
4+
```javascript
5+
const log4js = require('log4js');
6+
log4js.configure({
7+
appenders: {
8+
out: { type: 'stdout' },
9+
app: { type: 'file', filename: 'application.log' }
10+
},
11+
categories: {
12+
default: { appenders: [ 'out', 'app' ], level: 'debug' }
13+
}
14+
});
15+
```
16+
This defines two appenders named 'out' and 'app'. 'out' uses the [stdout](stdout.md) appender which writes to standard out. 'app' uses the [file](file.md) appender, configured to write to 'application.log'.
17+
18+
## Core Appenders
19+
20+
The following appenders are included with log4js. Some require extra dependencies that are not included as part of log4js (the [smtp](smtp.md) appender needs [nodemailer](https://www.npmjs.org/packages/nodemailer) for example), and these will be noted in the docs for that appender. If you don't use those appenders, then you don't need the extra dependencies.
21+
22+
* [categoryFilter](categoryFilter.md)
23+
* [console](console.md)
24+
* [dateFile](file.md)
25+
* [file](file.md)
26+
* [fileSync](fileSync.md)
27+
* [gelf](gelf.md)
28+
* [hipchat](hipchat.md)
29+
* [logFaces-HTTP](logFaces-HTTP.md)
30+
* [logFaces-UDP](logFaces-UDP.md)
31+
* [loggly](loggly.md)
32+
* [logLevelFilter](logLevelFilter.md)
33+
* [logstashUDP](logstashUDP.md)
34+
* [mailgun](mailgun.md)
35+
* [multiprocess](multiprocess.md)
36+
* [recording](recording.md)
37+
* [redis](redis.md)
38+
* [slack](slack.md)
39+
* [smtp](smtp.md)
40+
* [stderr](stderr.md)
41+
* [stdout](stdout.md)
42+
43+
## Other Appenders
44+
45+
Log4js can load appenders from outside the core appenders. The `type` config value is used as a require path if no matching appender can be found. For example, the following configuration will attempt to load an appender from the module 'cheese/appender', passing the rest of the config for the appender to that module:
46+
```javascript
47+
log4js.configure({
48+
appenders: { gouda: { type: 'cheese/appender', flavour: 'tasty' } },
49+
categories: { default: { appenders: ['gouda'], level: 'debug' }}
50+
});
51+
```
52+
If you want to write your own appender, read the [documentation](writing-appenders.md) first.

‎docs/index.md

Lines changed: 44 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,47 @@
11
# log4js-node
22

3+
This is a conversion of the [log4js](https://github.com/stritti/log4js)
4+
framework to work with [node](http://nodejs.org). I started out just stripping out the browser-specific code and tidying up some of the javascript to work better in node. It grew from there. Although it's got a similar name to the Java library [log4j](https://logging.apache.org/log4j/2.x/), thinking that it will behave the same way will only bring you sorrow and confusion.
5+
6+
## Features
7+
8+
* coloured console logging to stdout or stderr
9+
* file appender, with configurable log rolling based on file size or date
10+
* SMTP appender
11+
* GELF appender
12+
* Loggly appender
13+
* Logstash UDP appender
14+
* logFaces (UDP and HTTP) appender
15+
* multiprocess appender (useful when you've got worker processes)
16+
* a logger for connect/express servers
17+
* configurable log message layout/patterns
18+
* different log levels for different log categories (make some parts of your app log as DEBUG, others only ERRORS, etc.)
19+
20+
## Installation
21+
22+
```bash
23+
npm install log4js
24+
```
25+
26+
## Usage
27+
28+
Minimalist version:
29+
```javascript
30+
var log4js = require('log4js');
31+
var logger = log4js.getLogger();
32+
logger.debug("Some debug messages");
33+
```
34+
35+
## Documentation
36+
337
* [Terminology](terms.md)
4-
* [log4js api](api.md)
38+
* [Log4js API](api.md)
39+
* [Appenders](appenders.md)
40+
* [Layouts](layouts.md)
41+
* [Frequently Asked Questions](faq.md)
42+
43+
## License
44+
45+
The original log4js was distributed under the Apache 2.0 License, and so is this. I've tried to
46+
keep the original copyright and author credits in place, except in sections that I have rewritten
47+
extensively.

‎package.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
"name": "log4js",
33
"version": "1.1.0",
44
"description": "Port of Log4js to work with node.",
5+
"homepage": "https://nomiddlename.github.io/log4js-node/",
56
"keywords": [
67
"logging",
78
"log",

0 commit comments

Comments
 (0)
0