Skip to content

Latest commit

 

History

History
285 lines (180 loc) · 8.96 KB

tars-logs.md

File metadata and controls

285 lines (180 loc) · 8.96 KB
Raw

@tars/logs

@tars/logs

基于 winston 与 winston-tars 开发，符合 TARS 框架规范的日志组件，其中包含染色日志、滚动（大小、时间）日志。

安装

npm install @tars/logs

例子

输出滚动日志

var logger = new tarsLogs("TarsRotate");

输出名为 access 的按天日志

var logger = new tarsLogs("TarsDate", "access");

输出名为 access 的按天日志，只写本地不写远程日志

var logger = new tarsLogs("TarsDate", "access", {
  logTo: tarsLogs.LogTo.Local,
});

输出名为 access 的按小时日志

var logger = new tarsLogs("TarsDate", "access", {
  format: tarsLogs.DateFormat.LogByHour,
});

输出名为 access 的按 20 分钟 滚动的日志，文件名为 2015-01-01_10:00 这样的格式

var logger = new tarsLogs("TarsDate", "access", {
  format: new tarsLogs.DateFormat.LogByMinute(20, "%Y-%m-%d_%H:%M"),
});

指定输出 INFO 级别的日志信息

logger.info("data");
logger.info("data1", "data2", "data3");

指定当前 INFO 级别的日志输出需要染色

logger.info("data", logger.getDyeingObj(true));

初始化

如果服务在 TARS平台 上运行，则无需配置此项

如果服务在 本地环境 中调试，所有日志类型都将输出至 Console

可通过调用 tarsLogs.setConfig(data) 静态方法进行初始化

data(String|Object) 可以为 tars 配置文件路径 或 已配置的 (@tars/utils).Config 实例。

使用

实例化

var tarsLogs = require("@tars/logs");

var logger = new tarsLogs(type, [name, options]);

type(String) 日志类型：

  • TarsRotate: 按大小滚动日志
  • TarsDate: 按时间滚动日志
  • TarsRemote: 远程日志

name(String) 用户自定义的文件名（可不填）

options(Object) 根据不同的日志类型，存在不同的参数，但下面的参数是各类型共享的：

  • hasSufix: 日志文件名是否带.log 后缀， 默认值为 true
  • hasAppNamePrefix: 是否允许框架在日志文件名上增加业务相关的标识， 默认值为 true
  • concatStr: 日志文件名中字符间的连接符， _默认值为 __
  • separ: 日志内容项之间的分隔符， 默认值为 |

options 中的其它参数，请详见不同日志类型的说明项。

在正常情况下，相同一个日志文件应该共享相同的一个 logger，而不是多次进行实例化

日志输出

在 TARS 中存在有 4 种日志级别 INFO、DEBUG、WARN、ERROR 可用对应的方法进行输出

logger.info([data], [...]);
logger.debug([data], [...]);
logger.warn([data], [...]);
logger.error([data], [...]);

方法支持多重参数， 详情可见 util.format()

如需要染色，请详见 染色 节

文件名与行号

默认情况下，输出的日志中包含调用输出方法的代码所在的 文件名:行号。

可通过如下示例进行自定义（用于封装模块）或者关闭（以提高性能）。

关闭文件名与行号输出：

logger.info("data", {
  lineno: false,
});

自定义文件名与行号输出：

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

更多详细信息，请参考 @tars/winston-tars.Metadata

日志级别

日志级别的优先级为： INFO < DEBUG < WARN < ERROR < NONE

其中，除了按大小滚动日志（TarsRotate）默认级别为 DEBUG，其它均为 INFO。

如需变更日志级别，可调用 logger.setLevel(level) 方法，传入需要的日志级别即可：

logger.setLevel('info');
logger.setLevel（'none'); // none 为一种特殊的日志级别，所有日志均不输出

如果服务在 TARS平台 上运行：

  • 模块会接收 日志级别变更 的管理命令，自动变更当前日志级别。
  • 模块会读取 TARS 配置文件中 tars.application.server.logLevel 节，以配置日志级别。
  • 以上两项日志级别的配置仅针对 按大小滚动日志（TarsRotate） 生效。

日志内容格式（Formatter）

模块提供精简 Formatter.Simple() 与复杂 Formatter.Detail() 两种日志处理方法：

  • 复杂： 日期 时间|PID|日志级别|文件名与行号|内容
  • 精简： 日期 时间|内容

默认情况下，不同日志类型会使用不同的处理方法。

关于 Formatter 的详情，请访问 @tars/winston-tars.Formatter

按大小滚动日志（TarsRotate）

在初始化类型为 TarsRotate 的 logger 时， options 还接受如下参数：

  • maxFiles: 最大的文件总数（也就是例子中的 n）， 默认值为 10
  • maxSize: 单文件最大大小（单位为 bytes）， 默认值为 10M
  • formatter: 定义日志内容格式化方法， 默认值为 Formatter.Detail()

关于 TarsRotate 的详情，请访问 @tars/winston-tars.TarsRotate

时间相关（DateFormat）

定义了与时间相关的日志（TarsDate、TarsRemote）滚动的处理方法：

  • 按 1 天日志：LogByDay([interval, pattern])
  • 按 1 小时日志：LogByHour([interval, pattern])
  • 按 10 分钟日志：LogByMinute([interval, pattern])
  • 自定义格式日志：LogByCustom(pattern)

其中， interval 为日志滚动间隔， pattern 为日志文件名中时间的格式

一般情况下，可直接使用字面量：

var logger = new tarsLogs("TarsDate", "access", {
  format: tarsLogs.DateFormat.LogByDay,
});

但如果需要自定义间隔或日志文件名，则需要实例化：

var logger = new tarsLogs('TarsDate', 'access', {
	format : new tarsLogs.DateFormat.LogByDay(3, '%Y-%m-%d');
});

关于 DateFormat 的详情，请访问 @tars/winston-tars.DateFormat

按时间滚动日志（TarsDate）

在初始化类型为 TarsDate 的 logger 时， options 还接受如下参数：

  • format: 创建新文件的间隔，为 DateFormat 对象， 默认值为 FORMAT.LogByDay
  • formatter: 定义日志内容格式化方法， 默认值为 Formatter.Simple()
  • logTo: 日志发送的目标，为 LogTo 枚举， 默认值为 LogTo.Both

LogTo 枚举中有 3 项可选：

  • LogTo.Remote: 仅打远程日志（tars.tarslog.LogObj）
  • LogTo.Local: 仅打本地日志
  • LogTo.Both: 远程 + 本地

请注意：仅当 LogTo.Local 时，options.format 才可为 DateFormat.LogByCustom

关于 TarsDate 的详情，请访问 @tars/winston-tars.TarsDate

远程日志（TarsRemote）

由于远程日志实现（与参数）较为复杂，请访问 winston-tars.TarsRemote 获取详细信息。

染色

在每一条日志写入时可以指定是否需要对此日志进行染色（也就是说，染色的开关并不在初始化的时而在日志写入时）。

仅有 按大小滚动（TarsRotate） 与 按时间滚动（TarsDate） 输出的日志可以进行染色。

染色的日志不仅按照之前逻辑进行输出，也会按照相同的逻辑会多输出一份放在 $LOG_PATH$/tars_dyeing/ 目录下。

染色日志总是全量输出（忽略当前日志级别进行输出）。

染色对象

染色对象标识了当前染色的状态（是否需要染色 及 附加信息）。

染色对象需要通过 @tars/dyeing 提供的方法生成。

为了便于使用，本模块封装了染色对象的生成方式。可通过 logger.getDyeingObj() 来获取染色对象。

打开染色

logger.getDyeingObj(true);

打开染色并设置染色的 val 为 guid，key 为 guid|sn

logger.getDyeingObj(true, "guid", "guid|sn");

实际应用中，不应调用此方法生成染色对象，而应直接使用其他模块提供的染色对象

符合染色标准的其它模块，均会提供 Object.getDyeingObj() 方法，可通过调用它获取染色对象，而不是使用此模块的方法。

关于染色的详细信息，请访问 @tars/dyeing 获取。

使用

需要对某条日志进行染色时，需在调用 logger 特定方法（日志级别）的最后一个参数传入 染色对象。

输出日志内容为 data1 data2 并 强制染色的日志

logger.info("data1", "data2", logger.getDyeingObj(true));

输出日志内容为 data 并根据 rpc.server 调用链上的染色信息进行染色的日志

tars.TestImp.prototype.echo = function (current, i) {
  logger.info("data", current.getDyeingObj());
};

rpc 具体获取染色对象的方式，请详见 @tars/rpc__