NestJS-Seq 日志模块配置详解：从入门到精通

2025-06-19 07:00:55作者：幸俭卉

前言

在现代应用开发中，日志记录是系统监控和故障排查的重要工具。NestJS-Seq 是一个专为 NestJS 框架设计的日志模块，它能够将应用日志高效地发送到 Seq 日志服务器。本文将深入解析 NestJS-Seq 的各项配置选项，帮助开发者根据实际需求定制日志记录行为。

核心配置选项解析

1. 基础连接配置

serverUrl 是必须配置的关键参数，它指定了 Seq 服务器的 HTTP/S 端点地址。开发环境通常使用 http://localhost:5341，而生产环境则应使用 HTTPS 协议确保传输安全。

apiKey 为可选参数，当 Seq 服务器启用了 API 密钥认证时，必须配置此参数。它相当于访问 Seq 服务的"密码"，应当妥善保管。

2. 日志传输控制

batchPayloadLimit 和 eventBodyLimit 两个参数共同控制日志传输的大小：

batchPayloadLimit (默认10MB)：限制单次批量发送的日志总大小
eventBodyLimit (默认256KB)：限制单个日志事件的大小

这两个参数对于网络带宽有限或 Seq 服务器性能受限的场景尤为重要。过大的值可能导致传输延迟或服务器压力过大。

maxRetries (默认5次) 和 delay (默认5秒) 构成了重试机制，确保在网络波动或 Seq 服务短暂不可用时不会丢失日志。重试间隔采用固定延迟策略，适合大多数场景。

timeout (默认30秒) 设定了日志发送的超时时间，防止因网络问题导致应用线程长时间阻塞。

3. 元数据与上下文信息

metaFieldName (默认'meta') 定义了自定义元数据字段的名称，开发者可以通过这个字段附加额外的上下文信息。

extendMetaProperties 是一个强大的扩展点，允许开发者注入静态的元数据信息。典型的应用场景包括：

extendMetaProperties: {
  serviceName: 'order-service',
  version: '2.3.1',
  environment: process.env.NODE_ENV,
  region: process.env.AWS_REGION
}

这些元数据会在 Seq 中作为日志事件的属性，极大方便了后续的日志查询和分析。

注意：serviceName 作为独立参数已被弃用，推荐使用 extendMetaProperties 来设置服务名称。

4. 日志级别控制

logLevels 参数支持两种配置方式：

单一日志级别：如 'error'，表示只记录该级别及以上的日志
级别数组：如 ['debug', 'info', 'warn']，精确控制记录的日志级别

NestJS-Seq 支持的日志级别与常规日志级别一致，包括（从低到高）：

verbose
debug
info
warn
error

最佳实践配置示例

以下是一个生产环境推荐的配置示例：

import { Module } from '@nestjs/common';
import { SeqLoggerModule } from '@jasonsoft/nestjs-seq';

@Module({
  imports: [
    SeqLoggerModule.forRoot({
      serverUrl: 'https://seq.yourcompany.com',
      apiKey: process.env.SEQ_API_KEY,
      batchPayloadLimit: 5 * 1024 * 1024, // 5MB
      eventBodyLimit: 128 * 1024, // 128KB
      maxRetries: 3,
      delay: 10,
      timeout: 20,
      metaFieldName: 'context',
      extendMetaProperties: {
        serviceName: 'payment-service',
        version: process.env.APP_VERSION,
        deployment: process.env.DEPLOYMENT_ID
      },
      logLevels: ['info', 'warn', 'error']
    }),
  ],
  // ...其他模块配置
})
export class AppModule {}