Log Levels

控制日志详细程度

用 Elogs 的级别系统控制日志输出的详细程度。Elogs 用 白名单过滤,不是层级阈值 —— 数组里列出的级别才会输出。

可用级别

import type { LogLevel } from '@eastgold15/elogs'

LogLevel 是 4 个字面量:

logFilter.level: ['ERROR'] 只输出 ERROR;['ERROR', 'WARNING'] 输出这两个。数组里的顺序无关紧要,白名单匹配。

配置

单个级别

import { createElogs } from '@eastgold15/elogs'

createElogs({
  config: {
    logFilter: { level: ['ERROR'] },
  },
})

多个级别

createElogs({
  config: {
    logFilter: { level: ['INFO', 'ERROR'] },
  },
})

根级简写

logLevel 是 options 根级字段,等价于 config.logFilter.level:

import type { LogLevel } from '@eastgold15/elogs'

createElogs({ logLevel: ['ERROR', 'WARNING'] satisfies LogLevel[] })

两种形式都生效。同时设置时,两者取并集(shouldLogForOptions 各自独立检查,任一通过即放行)—— 根级简写不会覆盖 config.logFilter.level。

按环境配置

createElogs({
  config: {
    logFilter: {
      level:
        process.env.NODE_ENV === 'production'
          ? ['ERROR', 'WARNING']
          : ['DEBUG', 'INFO', 'WARNING', 'ERROR'],
    },
  },
})

状态派生的级别

每条 access log 会按 HTTP 状态码派生一个起始级别(由内部 getLogLevelForStatus 决定):

派生出来的级别也会被 logFilter.level(或 logLevel)过滤 —— level: ['ERROR'] 时 404 请求不会产生输出。

想自己派生级别?levelForStatus(status) 是从 @eastgold15/elogs 导出的纯函数,在自定义 Transport 里可以直接用。

Pino 的级别

pino 配置有自己独立的级别字段,跟 logFilter.level 互不影响:

createElogs({
  config: {
    pino: {
      enabled: true,
      level: 'debug', // pino 内部门槛
      prettyPrint: true,
    },
  },
})

pino.level 控制 Pino 自己日志方法的门槛(logger.debug / logger.info 等),而 logFilter.level 控制 Elogs 的 emit 管道 是否放行。两者可以独立设置:

• pino.level: 'info' —— logger.debug(...) 调用在 Pino 层就被吞
• logFilter.level: ['ERROR'] —— 即使 Pino 输出了,Elogs 也不发到 console / file / transports

Pino logger 通过 lazy proxy 实现,首次访问时按需构造。把 config.pino 设为对象可以让错误的 Pino 选项在启动时 fail-fast;不设置时使用默认的 lazy 构造。

最佳实践

API 参考

• LogLevel — 4 个字面量
• LogFilter — { level?: LogLevel[] }
• ElogsConfig.logFilter — 配置字段
• CreateElogsOptions.logLevel — 根级别名
• levelForStatus(status) — 公开工具函数,从 @eastgold15/elogs 直接 import