Node.js npm log4js

译自 https://www.npmjs.com/package/log4js

log4js

Port of Log4js to work with node.

工作在 node 下的 Log4js 的接口。

This is a conversion of the log4js framework to work with node. I’ve mainly stripped out the browser-specific code and tidied up some of the javascript.

这里是 log4js 框架运行在 node 环境下的一个转变。我主要剥离出浏览器特定的代码，并且整理了一下 javascript 代码。

Out of the box it supports the following features:

• coloured console logging to stdout or stderr
• replacement of node’s console.log functions (optional)
• file appender, with configurable log rolling based on file size or date
• SMTP appender
• GELF appender
• Loggly appender
• Logstash UDP appender
• logFaces appender
• multiprocess appender (useful when you’ve got worker processes)
• a logger for connect/express servers
• 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.)

它非常好地支持如下特性：

• 将带颜色的控制台日志输出到 stdout 或 stderr
• 替换了 node 的 console.log 函数（可选）
• 文件追加器，根据文件大小或日期滚动的可配置日志
• SMTP 追加器
• GELF 追加器
• Loggly 追加器
• Logstash UDP 追加器
• logFaces 追价齐
• 多进程追加器（当你已经获得多个工作进程时是非常有用的）
• connect 或 express 服务的日志记录器
• 日志消息的布局或模式均是可配置的
• 不同的日志类型采用不同的日志级别（你的应用程序的某些部分使用 DEBUG 打印日志，其它的只使用 ERRORS，等等）

Important changes in 1.0（1.0 版本的重大改变）

The default appender has been changed from console to stdout - this alleviates a memory problem that happens when logging using console. If you’re using log4js in a browser (via browserify), then you’ll probably need to explicitly configure log4js to use the console appender now (unless browserify handles process.stdout).

默认的追加器已经从 console 改为 stdout 这样可以缓解使用控制台打印日志时出现的内存问题。如果你在浏览器中使用 log4js（通过browserify），那么现在你可能需要额外配置 log4js 来使用控制台追加器（除非 browserify 处理了 process.stdout）。

I’m also trying to move away from vows for the tests, and use tape instead. New tests should be added to test/tape, not the vows ones.

我也尝试过在测试项目中远离 vows，并且使用 tape 来取代它。新的测试项目应该被添加到 test/tape 中，而不是 vows。

log4js also no longer supports node versions below 0.12.x.

log4js 也不再支持 node 0.12.x 以下的版本。

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:

注意：log4js 0.5 之后，你将需要额外启用替换 node 的 console.log 函数。可以通过调用 log4js.replaceConsole() 或者使用一个对象进行配置或者使用像这样的 json 文件：

{
  appenders: [
    { type: "console" }
  ],
  replaceConsole: true
}

installation（安装）

npm install log4js

usage（使用）

Minimalist version:

极简的版本：

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), so for the above you would see:

默认的情况下，log4js 会使用彩色的布局输出到 stdout（感谢 masylum），因此上面的你将会看到：

[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):

查看 example.js 来获取一个完整的例子，但是这里是一小段（也在 fromreadme.js）：

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');

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:

输出：

[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:

上面的前 5 行代码可以被写成这样：

var log4js = require('log4js');
log4js.configure({
  appenders: [
    { type: 'console' },
    { type: 'file', filename: 'logs/cheese.log', category: 'cheese' }
  ]
});

configuration（配置）

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/vows/log4js.json. An example config file with log rolling is in test/vows/with-log-rolling.json. You can configure log4js to check for configuration file changes at regular intervals, and if changed, reload. This allows changes to logging levels to occur without restarting the application.

你手动可以配置追加器和日志级别（像上面一样），或者提供一个配置文件（log4js.configure('path/to/file.json')），或者一个配置对象。配置文件的路径也可以通过环境变量 LOG4JS_CONFIG 来指定（export LOG4JS_CONFIG=path/to/file.json）。可以在test/vows/log4js.json中找到一个示例文件。带滚动日志的示例配置文件在test/vows/with-log-rolling.json中。你可以配置 log4js 来定期检查配置文件是否改变，并且如果改变就重新加载。它允许不重启应用的情况下改变日志级别。

To turn it on and specify a period:

可以开启它并指定一个时间段：

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.

对于文件追加器，你也可以传递日志文件夹路径作为一个选项，这样你的所有日志文件都将会存储到这里。

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:

如果你已经在配置文件中为某个 FileAppender 定义了一个绝对路径，你需要添加一个 "absolute": true 来给这个特别的 FileAppender 来覆盖传递的 cwd 选项。这里是一个例子：

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"          
    }
  ]
}

Documentation for most of the core appenders can be found on the wiki, otherwise take a look at the tests and the examples.

大部分核心追加器的文档都可以在 wiki 中找到，其它的可以看看测试项目和示例项目。

Documentation（文档）

See the wiki. Improve the wiki, please.

参考 wiki，请改进 wiki。

There’s also an example application.

这里也有一个示例应用程序。

Contributing（贡献）

Contributions welcome, but take a look at the rules first.

欢迎贡献，但是首先请阅读相应规则。

License（证书）

The original log4js was distributed under the Apache 2.0 License, and so is this. I’ve tried to keep the original copyright and author credits in place, except in sections that I have rewritten extensively.

最开始的 log4js 是在 Apache 2.0 的证书下颁布的，这个也是。除了被我大量重重写的章节，我都尽可能地保持原始的版权信息和作者的身份信息就位。