日志记录器（Logger）

AdonisJS 拥有一个内置的日志记录器，支持将日志写入文件、标准输出 和 外部日志服务。在底层，我们使用 pino。Pino 是 Node.js 生态系统中最快的日志库之一，它以 NDJSON 格式生成日志。

用法

首先，你可以导入 Logger 服务，从而在应用中的任何地方写入日志。日志会被写入 stdout 并出现在终端上。

import logger from '@adonisjs/core/services/logger'

logger.info('this is an info message')
logger.error({ err: error }, 'Something went wrong')

建议在 HTTP 请求期间使用 ctx.logger 属性。HTTP 上下文持有一个请求感知（request-aware）的日志记录器实例，它会将当前请求 ID 添加到每一条日志语句中。

import router from '@adonisjs/core/services/router'
import User from '#models/user'

router.get('/users/:id', async ({ logger, params }) => {
  logger.info('Fetching user by id %s', params.id)
  const user = await User.find(params.id)
})

配置

日志记录器的配置存储在 config/logger.ts 文件中。默认情况下，只配置了一个日志记录器。不过，如果你想在应用中使用多个日志记录器，可以为它们分别定义配置。

config/logger.ts

import env from '#start/env'
import { defineConfig } from '@adonisjs/core/logger'

export default defineConfig({
  default: 'app',
  
  loggers: {
    app: {
      enabled: true,
      name: env.get('APP_NAME'),
      level: env.get('LOG_LEVEL', 'info')
    },
  }
})

default

default 属性是对同一文件中 loggers 对象下某个已配置日志记录器的引用。

除非你在使用日志记录器 API 时选择了特定的日志记录器，否则将使用默认日志记录器来写入日志。

loggers

loggers 对象是一个键值对，用于配置多个日志记录器。键是日志记录器的名称，值是 pino 所接受的配置对象。

传输目标（Transport targets）

pino 中的传输（transport）扮演着至关重要的角色，因为它们将日志写入目的地。你可以在配置文件中配置多个目标，pino 会将日志分发给所有目标。每个目标还可以指定它希望从哪个级别开始接收日志。

如果你没有在目标配置中定义 level，配置的目标将从父日志记录器继承该级别。

此行为与 pino 不同。在 Pino 中，目标不会从父日志记录器继承级别。

{
  loggers: {
    app: {
      enabled: true,
      name: env.get('APP_NAME'),
      level: env.get('LOG_LEVEL', 'info'),
      
      transport: {
        targets: [
          {
            target: 'pino/file',
            level: 'info',
            options: {
              destination: 1
            }
          },
          {
            target: 'pino-pretty',
            level: 'info',
            options: {}
          },
        ]
      }
    }
  }
}

File target
: pino/file 目标将日志写入一个文件描述符。destination = 1 表示将日志写入 stdout（这是文件描述符的标准 unix 约定）。
Pretty target
: pino-pretty 目标使用 pino-pretty npm 模块将日志美化输出到一个文件描述符。

有条件地定义目标

根据代码运行的环境注册目标是很常见的做法。例如，在开发环境中使用 pino-pretty 目标，在生产环境中使用 pino/file 目标。

如下所示，用条件语句来构造 targets 数组会让配置文件看起来杂乱无章。

import app from '@adonisjs/core/services/app'

loggers: {
  app: {
    transport: {
      targets: [
        ...(!app.inProduction
          ? [{ target: 'pino-pretty', level: 'info' }]
          : []
        ),
        ...(app.inProduction
          ? [{ target: 'pino/file', level: 'info' }]
          : []
        ),
      ]
    }
  } 
}

因此，你可以使用 targets helper，通过流式（fluent）API 来定义有条件的数组项。在以下示例中，我们使用 targets.pushIf 方法表达了相同的条件。

import { targets, defineConfig } from '@adonisjs/core/logger'

loggers: {
  app: {
    transport: {
      targets: targets()
       .pushIf(
         !app.inProduction,
         { target: 'pino-pretty', level: 'info' }
       )
       .pushIf(
         app.inProduction,
         { target: 'pino/file', level: 'info' }
       )
       .toArray()
    }
  } 
}

为了进一步简化代码，你可以使用 targets.pretty 和 targets.file 方法为 pino/file 和 pino-pretty 目标定义配置对象。

import { targets, defineConfig } from '@adonisjs/core/logger'

loggers: {
  app: {
    transport: {
      targets: targets()
       .pushIf(app.inDev, targets.pretty())
       .pushIf(app.inProduction, targets.file())
       .toArray()
    }
  }
}

使用多个日志记录器

AdonisJS 对配置多个日志记录器提供了一等支持。日志记录器的唯一名称和配置在 config/logger.ts 文件中定义。

export default defineConfig({
  default: 'app',
  
  loggers: {
    app: {
      enabled: true,
      name: env.get('APP_NAME'),
      level: env.get('LOG_LEVEL', 'info')
    },
    payments: {
      enabled: true,
      name: 'payments',
      level: env.get('LOG_LEVEL', 'info')
    },
  }
})

配置完成后，你可以使用 logger.use 方法访问指定名称的日志记录器。

import logger from '@adonisjs/core/services/logger'

logger.use('payments')
logger.use('app')

// Get an instance of the default logger
logger.use()

依赖注入

在使用依赖注入时，你可以将 Logger 类作为依赖进行类型提示，IoC 容器将解析出配置文件中定义的默认日志记录器的实例。

如果该类是在 HTTP 请求期间构造的，那么容器将注入请求感知的 Logger 实例。

import { inject } from '@adonisjs/core'
import { Logger } from '@adonisjs/core/logger'

@inject()
class UserService {
  constructor(protected logger: Logger) {}

  async find(userId: string | number) {
    this.logger.info('Fetching user by id %s', userId)
    const user = await User.find(userId)
  }
}

日志记录方法

Logger API 与 Pino 几乎完全相同，只是 AdonisJS 日志记录器不是 Event emitter 的实例（而 Pino 是）。除此之外，日志记录方法与 pino 具有相同的 API。

import logger from '@adonisjs/core/services/logger'

logger.trace(config, 'using config')
logger.debug('user details: %o', { username: 'virk' })
logger.info('hello %s', 'world')
logger.warn('Unable to connect to database')
logger.error({ err: Error }, 'Something went wrong')
logger.fatal({ err: Error }, 'Something went wrong')

可以将一个额外的合并对象作为第一个参数传递。然后，该对象的属性会被添加到输出的 JSON 中。

logger.info({ user: user }, 'Fetched user by id %s', user.id)

要显示错误，你可以使用 err 键来指定错误值。

logger.error({ err: error }, 'Unable to lookup user')

有条件地记录日志

日志记录器只会为配置文件中所配置级别及以上的级别生成日志。例如，如果级别设置为 warn，那么 info、debug 和 trace 级别的日志将被忽略。

如果为某条日志消息计算数据的开销很大，你应该在计算数据之前先检查给定的日志级别是否已启用。

import logger from '@adonisjs/core/services/logger'

if (logger.isLevelEnabled('debug')) {
  const data = await getLogData()
  logger.debug(data, 'Debug message')
}

你可以使用 ifLevelEnabled 方法表达相同的条件。该方法接受一个回调作为第 2 个参数，当指定的日志级别启用时该回调会被执行。

logger.ifLevelEnabled('debug', async () => {
  const data = await getLogData()
  logger.debug(data, 'Debug message')
})

子日志记录器（Child logger）

子日志记录器是一个隔离的实例，它从父日志记录器继承配置和绑定（bindings）。

可以使用 logger.child 方法创建子日志记录器的实例。该方法接受绑定作为第一个参数，以及一个可选的配置对象作为第二个参数。

import logger from '@adonisjs/core/services/logger'

const requestLogger = logger.child({ requestId: ctx.request.id() })

子日志记录器也可以在不同的日志级别下记录日志。

logger.child({}, { level: 'warn' })

Pino 静态成员

Pino 静态方法和属性由 @adonisjs/core/logger 模块导出。

import { 
  multistream,
  destination,
  transport,
  stdSerializers,
  stdTimeFunctions,
  symbols,
  pinoVersion
} from '@adonisjs/core/logger'

将日志写入文件

Pino 自带一个 pino/file 目标，你可以用它将日志写入文件。在目标选项中，你可以指定日志文件的目的地路径。

app: {
  enabled: true,
  name: env.get('APP_NAME'),
  level: env.get('LOG_LEVEL', 'info')

  transport: {
    targets: targets()
      .push({
         transport: 'pino/file',
         level: 'info',
         options: {
           destination: '/var/log/apps/adonisjs.log'
         }
      })
      .toArray()
  }
}

文件轮转（File rotation）

Pino 没有内置的文件轮转支持，因此你要么必须使用像 logrotate 这样的系统级工具，要么使用像 pino-roll 这样的第三方包。

npm i pino-roll

app: {
  enabled: true,
  name: env.get('APP_NAME'),
  level: env.get('LOG_LEVEL', 'info')

  transport: {
    targets: targets()
      .push({
        target: 'pino-roll',
        level: 'info',
        options: {
          file: '/var/log/apps/adonisjs.log',
          frequency: 'daily',
          mkdir: true
        }
      })
     .toArray()
  }
}

隐藏敏感值

日志可能成为敏感数据泄露的来源。因此，建议你观察你的日志，并从输出中移除/隐藏敏感值。

在 Pino 中，你可以使用 redact 选项从日志中隐藏/移除敏感的键值对。在底层，它使用了 fast-redact 包，你可以查阅其文档以查看可用的表达式。