VonaJS: 基于winston的Logger日志系统

VonaJS 基于winston提供了强大而灵活的日志系统

特性

1. 多Client: 每个 Client 有独立的配置
2. 多Child: 可以为不同的场景创建 Child 日志
3. Rotate: 按指定的规则对日志文件进行轮换
4. 日志分级: 可以基于分级控制写入日志文件的内容

日志目录

针对不同的运行环境默认使用不同的日志目录:

• 测试环境/开发环境: {project path}/.app/logs
• 生产环境: {home}/vona/{project name}/logs

可以在 App Config 或者.env 文件中修改配置

1. App Config

src/backend/config/config/config.ts

// server
config.server = {
  loggerDir: '/new/path',
};

2. .env

env/.env

# server
SERVER_LOGGERDIR = /new/path

App Config配置

可以在 App Config 中进行日志配置：

src/backend/config/config/config.ts

// logger
config.logger = {
  rotate: {},
  base: {},
  clients: {},
};

名称	说明
rotate	日志Rotate
base	基础配置，为所有Client提供通用的基础配置
clients	配置多个Client。系统提供了内置的default Client，实现开箱即用的日志能力

Rotate

系统提供了默认的轮换配置，并且处于开启状态。可以在 App Config 或者.env 文件中修改配置

1. App Config

src/backend/config/config/config.ts

// logger
config.logger = {
  rotate: {
    enable: true,
    options(filename: string) {
      return {
        filename: `${filename}-%DATE%.log`,
        datePattern: 'YYYY-MM-DD',
        maxSize: '20m',
        maxFiles: '7d',
      };
    },
  },
};

名称	说明
enable	是否启用Rotate
options	通过函数返回Rotate配置
options.filename	文件名模版
options.datePattern	日期模式
options.maxSize	每个文件的最大尺寸
options.maxFiles	只保留几天之内的文件

2. .env

env/.env

# logger
LOGGER_ROTATE_ENABLE = true
LOGGER_ROTATE_FILENAME = '{{filename}}-%DATE%.log'
LOGGER_ROTATE_DATEPATTERN = YYYY-MM-DD
LOGGER_ROTATE_MAXSIZE = 20m
LOGGER_ROTATE_MAXFILES = 7d

添加新Client

下面通过添加新 Client 解释 Client 的配置

1. 添加类型定义

采用接口合并机制添加新 Client 的类型定义，比如order，用于输出独立的与订单相关的日志

在 VSCode 编辑器中，输入代码片段recordloggerclient，自动生成代码骨架:

declare module 'vona' {
  export interface ILoggerClientRecord {
    : never;
  }
}

调整代码，然后添加order

declare module 'vona' {
  export interface ILoggerClientRecord {
+   order: never;
  }
}

2. 增加Client配置

src/backend/config/config/config.ts

// logger
config.logger = {
  clients: {
    order(this: VonaApplication, clientInfo) {
      const transports = [
        this.bean.logger.makeTransportFile(clientInfo, 'order'),
        this.bean.logger.makeTransportConsole(clientInfo),
      ].filter(item => !!item);
      return { transports };
    },
  },
};

• order: 通过函数返回 Client 配置。该配置将与系统提供的默认配置进行合并
  • 因此，在一般情况下，只需构造所需的transports即可
• clientInfo: 包含环境信息，用于构造transport
• makeTransportFile: 用于构造文件通道，需要提供日志文件名order
  • 由于文件名模版是${filename}-%DATE%.log，那么实际生成的文件名是order-2025-11-14.log
• makeTransportConsole: 用于构造控制台通道
• filter: 新建的通道实例有可能为 undefined，因此需要进行 filter

获取Logger Client实例

获取 Logger Client 实例有两种方式:

• 方式1

class ControllerStudent extends BeanBase {
  async test() {
    // logger: default
    const loggerDefault = this.bean.logger.default;
    // logger: order
    const loggerOrder = this.bean.logger.get('order');
  }
}

• 方式2

class ControllerStudent extends BeanBase {
  async test() {
    // logger: default
    const loggerDefault = this.$logger;
    // logger: order
    const loggerOrder = this.$loggerClient('order');
  }
}

方式2不仅代码更加简洁，而且还会自动在日志中带上当前 Bean Class 的beanFullName，便于排查问题

• 举例：

const loggerOrder = this.bean.logger.get('order');
loggerOrder.info('test');

// logger: default
this.$logger.info('test');
// logger: order
this.$loggerClient('order').info('test');

图中输出了 beanFullName: [demo-student.controller.student]

获取Logger Child实例

对于同一个 Logger Client，可以生成多个 Child 实例，不同的 Child 对应不同的场景

比如，生成 Child pay，从而在日志中可以明确提示pay信息

// child of logger-default
this.$loggerChild('pay').info('$50');
// child of logger-order
this.$loggerChild('pay', 'order').info('$50');

图中输出了 child name: [pay]

添加类型定义

同样，需要提供pay的类型定义，从而支持类型提示

在 VSCode 编辑器中，输入代码片段recordloggerchild，自动生成代码骨架:

declare module 'vona' {
  export interface ILoggerChildRecord {
    : never;
  }
}

调整代码，然后添加pay

declare module 'vona' {
  export interface ILoggerChildRecord {
+   pay: never;
  }
}

日志消息

1. 一般用法

this.$logger.info('test');

2. 字符串插值

基于util.format实现字符串插值

this.$logger.info('%s has %d apples', 'Tom', 3);

3. 延迟消息

由于存在日志分级，有些分级的消息并不会写入文件。那么，如果构造消息内容太大，则会浪费系统性能

• 举例

const obj = { data: 'more info' };
this.$logger.debug(JSON.stringify(obj));

如果当前分级是info，那么debug分级的日志就不会写入文件。那么，JSON.stringify就会空耗系统性能

• 解决方案

可以提供回调函数，当需要写入文件时才会执行回调函数，从而生成实际的消息

const obj = { data: 'more info' };
this.$logger.debug(() => {
  return JSON.stringify(obj);
});

4. 多级Child

可以从当前 Logger 实例创建多级 Child Logger，从而向日志消息中传入更多 metadata

this.$logger.child({ requestId: '451' }).child({ extra: 'some info' }).info('test');
this.$logger.child({ requestId: '578', extra: 'some info' }).info('test');

如下图所示：requestId/extra

NPM分级

可以基于分级控制写入日志文件的消息内容

VonaJS 采用 NPM 分级规则，参见: RFC5424

const levels = {
  error: 0,
  warn: 1,
  info: 2,
  http: 3,
  verbose: 4,
  debug: 5,
  silly: 6
};

输出方法

与分级对应的是一组输出方法

this.$logger.error('test');
this.$logger.warn('test');
this.$logger.info('test');
this.$logger.http('test');
this.$logger.verbose('test');
this.$logger.debug('test');
this.$logger.silly('test');

默认分级

VonaJS 的默认分级是info，从而可以控制只有<=info的分级日志才写入文件

1. makeTransportFile

我们在新建order Client，可以通过makeTransportFile方法实现此策略: 只有<=info的分级日志才写入文件

// logger
config.logger = {
  clients: {
    order(this: VonaApplication, clientInfo) {
      const transports = [
+       this.bean.logger.makeTransportFile(clientInfo, 'order'),
        this.bean.logger.makeTransportConsole(clientInfo),
      ].filter(item => !!item);
      return { transports };
    },
  },
};

2. makeTransportFile: 独立文件

如果需要强制某个分级的日志写入独立的文件，可以再增加一个文件通道。比如，将debug分级的日志写入文件order-debug中

// logger
config.logger = {
  clients: {
    order(this: VonaApplication, clientInfo) {
      const transports = [
+       this.bean.logger.makeTransportFile(clientInfo, 'order-debug', 'debug'),
        this.bean.logger.makeTransportFile(clientInfo, 'order'),
        this.bean.logger.makeTransportConsole(clientInfo),
      ].filter(item => !!item);
      return { transports };
    },
  },
};

3. makeTransportConsole

对于控制台通道，有一个特殊约定：凡是silly分级的日志，都会输出到控制台。因此，通过makeTransportConsole方法实现此策略

// logger
config.logger = {
  clients: {
    order(this: VonaApplication, clientInfo) {
      const transports = [
        this.bean.logger.makeTransportFile(clientInfo, 'order'),
+       this.bean.logger.makeTransportConsole(clientInfo),
      ].filter(item => !!item);
      return { transports };
    },
  },
};

默认分级配置

可以通过.env 文件修改默认的分级配置

由于可以配置多个 Clients，因此，Clients 可以单独配置自己的默认分级

1. Client: default

LOGGER_CLIENT_DEFAULT = 

支持如下值：(empty)/true/false/{level}

比如，希望<=debug分级的日志写入文件，那么，配置如下:

LOGGER_CLIENT_DEFAULT = debug

也可以直接在控制台设置环境变量:

LOGGER_CLIENT_DEFAULT=debug npm run dev

2. Client: order

对于新增的 Client order，也可以设置默认分级：

LOGGER_CLIENT_ORDER = verbose

获取当前分级

在系统运行中可以获取当前分级：

class ControllerStudent {
  async test() {
    // logger: default
    const levelDefault = this.bean.logger.getLevel();
    // logger: order
    const levelOrder = this.bean.logger.getLevel('order');
  }
}  

动态修改分级

在系统运行中可以动态修改分级，从而在不停机、不重启的情况下，随时控制基于分级的写入策略

当调用setLevel方法时，系统会自动广播至所有 Workers，从而修改每个工作进程中的当前分级

class ControllerStudent {
  async test() {
    // level: info
    let levelDefault = this.bean.logger.getLevel();
    assert.equal(levelDefault, 'info');
    this.$logger.debug('1: this line will not output');
    // level: debug
    this.bean.logger.setLevel('debug');
    levelDefault = this.bean.logger.getLevel();
    assert.equal(levelDefault, 'debug');
    this.$logger.debug('2: this line will output');
    // disable
    this.bean.logger.setLevel(false);
    levelDefault = this.bean.logger.getLevel();
    assert.equal(levelDefault, false);
    this.$logger.info('3: this line will not output');
    this.$logger.debug('4: this line will not output');
    // enable
    this.bean.logger.setLevel(true);
  }
}

资源

• Github：https://github.com/vonajs/vona
• 文档：https://vona.js.org