node 通用日志模块

基于 winston 封装的通用日志模块，以便于云上 node 服务接入 cls 做日志落地和检索

使用

安装 npm 包：

yarn add @tencent/gps-logger

项目中引入使用：

const logger = require('@tencent/gps-logger');

// 打印普通日志
logger.info('log info');

// 打印带格式参数的普通日志，格式参数见https://nodejs.org/api/util.html#util_util_format_format_args
logger.info('log info with params: number=%d, string=%s, object=%j', 1, 'string', { key: 'value' });

// 打印警告日志
logger.warn('log warning');

// 打印带格式参数的警告日志，格式参数见https://nodejs.org/api/util.html#util_util_format_format_args
logger.warn('log warning with params: number=%d, string=%s, object=%j', 1, 'string', { key: 'value' });

// 打印错误日志
logger.error('get data from xxx failed');

// 打印带格式参数的错误日志，格式参数见https://nodejs.org/api/util.html#util_util_format_format_args
logger.error('get data from xxx failed: number=%d, string=%s, object=%j', 1, 'string', { key: 'value' });

try {
  throw new Error('network error');
} catch (err) {
  // 打印带堆栈信息的错误日志
  logger.error('get data from xxx failed', { error: err });

  // 打印带格式参数和堆栈信息的错误日志
  logger.error(
    'get data from xxx failed: number=%d, string=%s, object=%j',
    1,
    'string',
    { key: 'value' },
    { error: err },
  );
}

// 打印调试日志，调试日志只会在日志级别被设置为`debug`时才会输出
logger.debug('call api with params: %j, response: %j', { param1, param2, param3, response });

// 启动日志级别动态管理Server，其中5000为需要监听的端口
// 启动后可以通过以下命令来修改日志级别，以便于线上问题定位
// `curl http://127.0.0.1:5000/?level=[error|warn|info|debug]`
logger.startLevelServer(5000);

// 关闭日志级别动态管理Server
logger.stopLevelServer();

日志级别和优先级

默认日志级别为info，可通过环境变量LOGGER_LOG_LEVEL或者logger.level来设置

{
  error: 0,
  warn: 1,
  info: 2,
  debug: 3,
}

日志打印规范

1. 日志信息清晰，避免没有意义的内容

// bad
logger.info(param);

// good
logger.info('call external api with param: %s', param);

2. 打印外部调用的输入输出

const response = callExternalApi(param1, param2, param3);
// 外部调用，打印输入输出以便于排查问题
logger.info('call external api with params: %j, response: %j', { param1, param2, param3, response });

3. 预期内可控的异常使用 warn 日志

// 参数检查时，param1为空是预期内的情况，业务逻辑的处理尚未开始
if (param1 === '') {
  logger.warn('invalid param1: %s', param1);
  return;
}

// 主要的业务逻辑
anotherFunc();

4. 不可控异常使用 error 日志

func1();

try {
  func2();
} catch (err) {
  // func2的调用异常在上下文中是不可逆的，影响后续的业务逻辑的运行
  logger.error('call func2 error', { error: err });
  return;
}

anotherFunc(response);

日志上报和索引配置

1. STKE 上新建日志规则时，日志类型须选择窗口标准输出

2. CLS 上日志主题配置-采集配置-采集规则配置中：键值提取模式须选择JSON，使用采集时间须选择关闭，时间键填写timestamp，时间格式填写%Y-%m-%d %H:%M:%S.%f

3. CLS 上日志主题配置-索引配置中，配置以下索引字段

   | 字段名称 | 字段类型 | | ------------- | -------- | | level | text | | message | text | | timestamp | text | | error.message | text | | error.stack | text |