首页

Home

log4js-node是对log4js做了一些更改，从而可以更好的运行在node环境中。

尽管名称和Java框架log4j很像，但它们的表现并不相同。

Features

Installation

npm install log4js

Usage

一个最简单的示例:

var log4js = require('log4js');
var logger = log4js.getLogger();
logger.level = 'debug'; // default level is OFF - which means no logs at all.
logger.debug("Some debug messages");

License

Apache 2.0 License

API

configuration

log4js.configure(object || string)

如果参数为string类型，则被当做为配置文件路径，则该配置文件必须为JSON文件。

如果参数一个配置对象，则至少要定义一个appender和默认的category。具体参数如下:

Configuration Object

Loggers

log4js.getLogger([category])

返回一个Logger对象，该对象使用指定的category，如果未指定category参数，则使用默认的category。
Logger对象实现了以下方法:

Shutdown

log4js.shutdown(cb)

当log4js关闭所有appender以及所有日志事件都完成写入时，会调用传入的回调函数。
在程序退出时使用该方法，可以保证所有文件写入,socket都已关闭，等等。

Custom Layouts

log4js.addLayout(type, fn)

添加自定义的layout函数。详细查看:layouts。

Appenders

appender用来指定日志的输出，例如写入文件，发送邮件，发送网络数据等。配置项中appenders必须包含type属性，用于确定使用哪一种appender。

const log4js = require('log4js');
log4js.configure({
  appenders: {
    out: { type: 'stdout' },
    app: { type: 'file', filename: 'application.log' }
  },
  categories: {
    default: { appenders: [ 'out', 'app' ], level: 'debug' }
  }
});

该实例定义了两个appender，其中out使用了stdout，用于写入到标准输出中。app使用了file，用于写入到'application.log'文件中。

Core Appenders

一下为log4js内置的appender。其中有的appender需要一些额外依赖但并不内置在Log4js中(例如smtp需要nodemailer)，具体可以查看对应的说明文档。
如果你不需要使用这些appender，则不需要下载额外的依赖。

Optional Appenders

log4js还内置有以下appender，但是在3.x版本之后会移除，如果使用了这些appender，需要显示的声明依赖。

Other Appenders

log4js支持加载外部的appender。在内置appender中没有匹配时，会type作为require的加载路径。例如:

log4js.configure({
  appenders: { gouda: { type: 'cheese/appender', flavour: 'tasty' } },
  categories: { default: { appenders: ['gouda'], level: 'debug' }}
});

以上示例会加载cheese/appender模块，并传递剩余的配置参数。

log4js通过type属性，按照以下的顺序尝试加载appender：

  1. 内置appender,: require('./appenders/' + type)
  2. node_modules: require(type)
  3. 相对于主文件的路径: require(path.dirname(require.main.filename) + '/' + type)
  4. 相对于cwd路径: require(process.cwd() + '/' + type)

如果打算实现一个外部appender，可查看该文档: Writing Appenders。

Console Appender

使用node的console对象输出日志，也可以使用在浏览器环境中。
需要注意的是，当向console写入大量日志(output)时会使应用占用大量内存，建议使用[stdout](#Standard Output Appender)避免该问题。

Configuration

注意，所有日志事件都会使用console.log事件(所以 ERROR events 同样使用console.log，而不是console.error)。

Example

log4js.configure({
  appenders: { console: { type: 'console' } },
  categories: { default: { appenders: [ 'console' ], level: 'info' } }
});

Standard Output Appender

将所有日志事件写入到标准输出流(standard output stream)中。log4js默认使用该appender。

Configuration

Example

log4js.configure({
  appenders: { 'out': { type: 'stdout' } },
  categories: { default: { appenders: ['out'], level: 'info' } }
});

Standard Error Appender

所有日志事件写入到标准错误流(standard error stream)中。

Configuration

Example

log4js.configure({
  appenders: { err: { type: 'stderr' } },
  categories: { default: { appenders: ['err'], level: 'ERROR' } }
});

File Appender

将日志事件写入到文件。当使用文件appender时，需要在应用终止时，调用log4js.shutdown以保证完成剩余的异步操作。

尽管文件appender使用了streamroller库，但是包含在log4js的依赖中，所以不需要在额外加载。

Configuration

剩余其他额外的参数，会被传递给底层的streamroller(参数含义也可查看node.js core file streams)：

Example

log4js.configure({
  appenders: {
    everything: { type: 'file', filename: 'all-the-logs.log' }
  },
  categories: {
    default: { appenders: [ 'everything' ], level: 'debug' }
  }
});

const logger = log4js.getLogger();
logger.debug('I will be logged in all-the-logs.log');

Example with log rolling (and compressed backups)

log4js.configure({
  appenders: {
    everything: { type: 'file', filename: 'all-the-logs.log', maxLogSize: 10485760, backups: 3, compress: true }
  },
  categories: {
    default: { appenders: [ 'everything' ], level: 'debug'}
  }
});

该示例会产生一个当前的日志文件(all-the-logs.log)。当该文件达到10Mb时，会压缩并命名为:all-the-logs.log.1.gz ，并创建一个新文件命名为all-the-logs.log 。
当all-the-logs.log再次达到10Mb时，原all-the-logs.log.1.gz会被改名为all-the-logs.log.2.gz，以此类推。

Synchronous File Appender

同步文件appender，和标准文件appender相比，区别在于所以写入都是同步的。而且不像异步版本，不支持对备份文件进行压缩。

Configuration

-type - "fileSync"
-filename - string - 文件路径
-maxLogSize - integer (optional) - 限制文件大小。
-backups - integer (optional, default value = 5) - 备份文件数量
-layout - (optional, defaults to basic layout) - see layouts

Example

log4js.configure({
  appenders: {
    everything: { type: 'fileSync', filename: 'all-the-logs.log' }
  },
  categories: {
    default: { appenders: [ 'everything' ], level: 'debug' }
  }
});

const logger = log4js.getLogger();
logger.debug('I will be logged in all-the-logs.log');