Skip to the content.

@tars/winston-tars

@tars/winston-tars 提供基于 winston 的 TARS 扩展,以提供符合 TARS 框架的日志格式与输出。

@tars/winston-tars 中提供 4 种 transport 对象:

并提供一种自定义日志级别:

以及相关的辅助方法:

请注意:如果您的服务在 TARS平台 上运行,应直接使用 @tars/logs 模块,更为便捷

安装

npm install @tars/winston-tars

使用

var winston = require("winston");

// Requiring `@tars/winston-tars` will expose

// transports
// `winston.transport.TarsRotate`
// `winston.transport.TarsDate`

// config
// `winston.config.tars.levels`
// `winston.config.tars.colors`
require("@tars/winston-tars");

日志格式

对于支持 formattertransport 对象,@tars/winston-tars 提供 2 种方法格式化日志内容:

options:

详细日志:

var winston = require("winston");
var winstonTars = require("@tars/winston-tars");

var logger = new winston.Logger({
  transports: [
    new winston.transports.Console({
      formatter: winstonTars.Formatter.Detail(),
    }),
  ],
});

输出日志的格式为:日期 时间|PID|日志级别|文件名与行号|内容

其中 文件名与行号 部分可选(详见 Metadata 节)

精简日志

var winston = require("winston");
var winstonTars = require("@tars/winston-tars");

var logger = new winston.Logger({
  transports: [
    new winston.transports.Console({
      formatter: winstonTars.Formatter.Simple(),
    }),
  ],
});

输出日志的格式为:日期 时间|内容

TarsConfig

winston.config.tars 提供了符合 TARS 框架标准的日志级别(levels)与颜色(colors

TARS 框架的日志级别从低到高(及其对应的颜色)为:

在使用时需要主动引入:

logger.setLevels(winston.config.tars.levels);

winston.addColors(winston.config.tars.colors);

TarsBase

此模块可单独使用,也可作为其他日志模块的基类。

模块实现了与现有 TARS 日志类似的管理方式:

独立使用

winston.add(winston.transports.TarsBase, options);

options:

作为其他类的基类

需要重写如下 2 个对象:

例如:

var TarsFile = function (options) {
  var instance = TarsBase.call(this, options);

  //由于父类存在缓存,所以这里需判断父类是否有返回值,如存在(命中缓存)则直接返回无需继续初始化

  if (instance) {
    return instance;
  }

  //业务代码
};
util.inherits(TarsFile, TarsBase);

TarsFile.prototype.name = "tarsFile";

TarsFile.prototype._checkfile = function (cb) {
  //业务代码
  cb();
};

winston.transports.TarsFile = TarsFile;

TarsRotate

此模块继承于 TarsBase

提供按文件大小输出的滚动日志

当到达设定的最大大小时,会自动向下滚动,并创建一个新的日志文件。

例如:app.log 文件写到最大大小,则会将会执行如下过程:

delete app_n.log
app_n-1.log ===> app_n.log
… …
app_1.log ===> app_2.log
app.log ===> app_1.log
create app.log

  winston.add(winston.transports.TarsRotate, options)

options:

TarsRotate.Master

如果业务脚本通过 Cluster(多进程方式启动的): Worker 则只负写入文件、而移动文件由 Master 完成,以解决多进程资源竞争问题。

当服务进程(Worker)打开日志文件准备写入时会向主进程发送消息,如下:

{
	cmd : 'log:rotate',
	msg : {
		filename : String, //文件名
		interval : Number, //多久打开一回文件
		maxFiles : Number, //最大文件数
		maxSize : Number, //最大单个文件大小
		concatStr  String //日志文件名中字符间的连接符
	}
}

主进程(Master)收到消息后,需透传给 TarsRotate.Master.start 方法,完整的例子如下:

worker.on("message", function (msg) {
  if (msg && typeof msg === "object" && msg.cmd === "log:rotate") {
    var data = msg.msg;
    TarsRotate.Master.start(
      data.filename,
      data.interval,
      data.maxFiles,
      data.maxSize,
      data.concatStr
    );
  }
});

process.on("exit", function () {
  TarsRotate.Master.close();
});

如果服务通过 node-agent (或在 TARS 平台)运行,则无需配置平台)运行,无需显式调用此模块。只需按照平时的写法 console.[log|info|warn|error] 即可正确的输出滚动日志

DateFormat

定义了与时间相关的日志(TarsDate)滚动的处理方法:

其中 pattern 为日志文件名中的时间格式,可参见 linux strftime

例子

每隔 1 天 滚动一份日志

DateFormat.LogByDay
或者
new DateFormat.LogByDay()

每隔 20 分钟 滚动一份日志

new DateFormat.LogByMinute(20)

每隔 20 分钟 滚动一份日志,文件名中时间格式为 %Y-%m-%d_%H:%M

new DateFormat.LogByMinute(20, ‘%Y-%m-%d_%H:%M’)

TarsDate

此模块继承于 TarsBase

提供按日期(年、月、日、小时、分)输出的日志

当到达设定的时间间隔时,会自动创建一个新的日志文件

输出的文件名的格式为:filename_[%Y|%m|%d|%H|%M].log,如:app_20141015.log

  winston.add(winston.transports.TarsDate, options)

options:

为了方便使用 TarsDate.FORMAT = DateFormat

TarsRemote

提供远程日志的功能,会将日志输出至 tars.tarslog.LogObj 服务。

请注意:这里并不是一收到日志就会发送,而是将日志整合在一起定时发送。

var logger = new winston.Logger({
  transports: [new winston.transports.TarsRemote(options)],
});

options:

请注意:在 TarsRemoteoptions.format 不能为 FORMAT.LogByCustom

为了方便使用 TarsRemote.FORMAT = DateFormat

如果服务通过 node-agent (或在 TARS 平台)运行,则无需配置 options.tarsConfig

Metadata

通过指定 Metadata 可输出 2 种附加数据。

pid

通过 pid 属性,可以指定日志输出条目中 进程 id 部分,默认情况下为 process.pid

如:

logger.info("data", {
  pid: 123456,
});

则输出:

2015-01-01 00:00:01| 123456 |INFO|data

lineno

通过 lineno 属性,可以指定日志输出条目中 文件名与行号 部分,默认值为空(也就是不输出这一节)。

如:

logger.info("data", {
  lineno: "app.js:6",
});

则输出:

2015-01-01 00:00:01|123456|INFO| app.js:6 |data