NestJS日志中间件与TraceId追踪实现指南

NestJS日志中间件与TraceId追踪实现指南

发布时间：2026/10/14 13:18:52
NestJS日志中间件与TraceId追踪实现指南 1. 项目概述在分布式系统开发中日志记录和请求追踪是保证系统可观测性的两大基石。NestJS作为企业级Node.js框架其日志系统和中间件机制为我们提供了实现这一目标的优雅方式。本文将深入探讨如何构建一个完整的日志中间件系统并实现贯穿整个请求生命周期的TraceId追踪机制。我曾在多个生产级NestJS项目中实施过类似的日志系统最大的体会是一个设计良好的日志系统不仅能帮助快速定位问题还能为系统性能优化提供数据支撑。特别是在微服务架构中当请求需要跨越多个服务时TraceId就像一根看不见的线把分散的日志串联成完整的故事。2. 核心需求解析2.1 为什么需要TraceId想象一下这样的场景用户报告某个API请求失败你需要从海量日志中找到这个特定请求的所有相关日志。没有TraceId的情况下这就像在大海里捞针。TraceId的作用就是为每个请求分配唯一标识使得可以追踪请求在系统中的完整路径能够关联跨服务、跨进程的日志记录便于分析请求在各个节点的处理耗时2.2 日志中间件的核心功能一个完整的日志中间件应该实现以下功能请求到达时生成唯一TraceId记录请求基本信息方法、路径、headers等捕获并记录响应信息和处理时间异常情况下的错误日志记录TraceId的跨中间件传递3. 技术实现详解3.1 基础日志中间件实现首先创建一个基础的日志中间件类// logger.middleware.ts import { Injectable, NestMiddleware } from nestjs/common; import { Request, Response, NextFunction } from express; Injectable() export class LoggerMiddleware implements NestMiddleware { use(req: Request, res: Response, next: NextFunction) { const startTime Date.now(); res.on(finish, () { const duration Date.now() - startTime; console.log(${req.method} ${req.originalUrl} - ${duration}ms); }); next(); } }然后在模块中注册// app.module.ts export class AppModule implements NestModule { configure(consumer: MiddlewareConsumer) { consumer .apply(LoggerMiddleware) .forRoutes(*); } }3.2 TraceId生成与传递我们需要一个更完善的方案来生成和传递TraceId// trace.middleware.ts import { v4 as uuidv4 } from uuid; Injectable() export class TraceMiddleware implements NestMiddleware { use(req: Request, res: Response, next: NextFunction) { const traceId req.headers[x-request-id] || uuidv4(); // 将traceId添加到请求对象和响应头 req[traceId] traceId; res.setHeader(X-Request-ID, traceId); // 使用AsyncLocalStorage保存上下文 const store new Map(); store.set(traceId, traceId); asyncLocalStorage.run(store, () { next(); }); } }3.3 集成Winston日志系统生产环境建议使用Winston这样的专业日志库// logger.service.ts import * as winston from winston; import { AsyncLocalStorage } from async_hooks; const asyncLocalStorage new AsyncLocalStorageMapstring, string(); export class LoggerService { private logger: winston.Logger; constructor() { this.logger winston.createLogger({ format: winston.format.combine( winston.format.timestamp(), winston.format.printf(({ level, message, timestamp }) { const store asyncLocalStorage.getStore(); const traceId store?.get(traceId) || N/A; return [${timestamp}] [${traceId}] [${level}]: ${message}; }) ), transports: [new winston.transports.Console()] }); } log(message: string) { this.logger.info(message); } // 其他日志级别方法... }4. 高级功能实现4.1 请求/响应日志格式化为了更清晰地记录请求信息我们可以实现一个格式化函数function formatRequestLog(req: Request): string { return JSON.stringify({ method: req.method, url: req.originalUrl, headers: { user-agent: req.headers[user-agent], content-type: req.headers[content-type], }, body: req.body, }); } function formatResponseLog(res: Response, duration: number): string { return JSON.stringify({ status: res.statusCode, duration: ${duration}ms, headers: { content-type: res.getHeader(content-type), }, }); }4.2 异常处理增强在异常过滤器中集成日志记录// http-exception.filter.ts Catch() export class HttpExceptionFilter implements ExceptionFilter { constructor(private readonly logger: LoggerService) {} catch(exception: unknown, host: ArgumentsHost) { const ctx host.switchToHttp(); const response ctx.getResponseResponse(); const request ctx.getRequestRequest(); this.logger.error(Request failed: ${formatRequestLog(request)}); // ...异常处理逻辑 } }4.3 性能监控集成利用TraceId可以实现简单的性能监控// performance.interceptor.ts Injectable() export class PerformanceInterceptor implements NestInterceptor { constructor(private readonly logger: LoggerService) {} intercept(context: ExecutionContext, next: CallHandler): Observableany { const start Date.now(); const request context.switchToHttp().getRequest(); return next.handle().pipe( tap(() { const duration Date.now() - start; this.logger.log( Performance: ${request.method} ${request.url} - ${duration}ms ); if (duration 500) { this.logger.warn(Slow request detected: ${duration}ms); } }) ); } }5. 生产环境最佳实践5.1 日志分级策略在生产环境中建议采用以下日志分级策略级别使用场景示例error系统错误数据库连接失败warn潜在问题慢查询警告info业务日志用户登录成功debug调试信息SQL查询语句verbose详细追踪中间件执行顺序5.2 日志存储与轮转配置Winston实现日志文件存储和轮转this.logger winston.createLogger({ transports: [ new winston.transports.DailyRotateFile({ filename: application-%DATE%.log, datePattern: YYYY-MM-DD, zippedArchive: true, maxSize: 20m, maxFiles: 14d, level: info, }), new winston.transports.File({ filename: error.log, level: error, }), ], });5.3 分布式追踪集成在微服务架构中可以集成OpenTelemetryimport { NodeTracerProvider } from opentelemetry/sdk-trace-node; import { SimpleSpanProcessor } from opentelemetry/sdk-trace-base; import { JaegerExporter } from opentelemetry/exporter-jaeger; const provider new NodeTracerProvider(); provider.addSpanProcessor( new SimpleSpanProcessor( new JaegerExporter({ serviceName: nestjs-app, }) ) ); provider.register();6. 常见问题与解决方案6.1 TraceId丢失问题问题现象异步操作中TraceId无法获取解决方案确保所有异步操作都在asyncLocalStorage.run回调中执行对于第三方库的回调使用AsyncResource绑定上下文import { AsyncResource } from async_hooks; someAsyncLibrary.method(param, new AsyncResource(callback).bind(() { // 这里可以获取TraceId }));6.2 日志性能影响问题现象日志记录导致系统性能下降优化方案使用winston-transport-http将日志异步发送到日志服务对高频日志采用采样策略在开发环境使用简单日志生产环境使用结构化日志const transports process.env.NODE_ENV production ? [new HttpTransport({ host: log-service })] : [new ConsoleTransport()];6.3 跨服务TraceId传递实现方案在HTTP请求头中自动添加TraceId对于RabbitMQ等消息队列在消息属性中添加TraceId// http.service.ts Injectable() export class HttpService { constructor(private readonly logger: LoggerService) {} get(url: string) { const traceId this.logger.getTraceId(); return axios.get(url, { headers: { X-Request-ID: traceId, }, }); } }7. 测试策略7.1 单元测试示例测试日志中间件的基本功能describe(TraceMiddleware, () { let middleware: TraceMiddleware; let req: PartialRequest; let res: PartialResponse; let next: jest.Mock; beforeEach(() { middleware new TraceMiddleware(); req { headers: {} }; res { setHeader: jest.fn() }; next jest.fn(); }); it(应该生成TraceId当请求头中不存在时, () { middleware.use(req as Request, res as Response, next); expect(req[traceId]).toBeDefined(); expect(res.setHeader).toHaveBeenCalledWith(X-Request-ID, req[traceId]); }); });7.2 E2E测试验证验证整个请求链路的日志记录describe(Logging Integration, () { let app: INestApplication; beforeAll(async () { const moduleFixture await Test.createTestingModule({ imports: [AppModule], }).compile(); app moduleFixture.createNestApplication(); await app.init(); }); it(GET / 应该记录请求日志, async () { const spy jest.spyOn(console, log); await request(app.getHttpServer()).get(/); expect(spy).toHaveBeenCalledWith(expect.stringContaining(GET /)); }); });8. 部署与监控8.1 ELK日志收集配置生产环境建议使用ELK栈收集和分析日志# filebeat.yml filebeat.inputs: - type: log paths: - /var/log/nestjs/*.log output.logstash: hosts: [logstash:5044]8.2 Prometheus监控集成暴露指标端点供Prometheus采集// metrics.controller.ts import { Controller, Get } from nestjs/common; import { Registry, collectDefaultMetrics } from prom-client; Controller(metrics) export class MetricsController { private readonly registry: Registry; constructor() { this.registry new Registry(); collectDefaultMetrics({ register: this.registry }); } Get() async getMetrics() { return { metrics: await this.registry.metrics(), }; } }9. 性能优化技巧9.1 日志采样策略对于高流量应用可以采用采样策略减少日志量// sampled.logger.ts export class SampledLogger { private readonly sampleRate: number; constructor(private readonly logger: LoggerService, sampleRate 0.1) { this.sampleRate sampleRate; } log(message: string) { if (Math.random() this.sampleRate) { this.logger.log(message); } } }9.2 异步日志写入使用worker线程处理日志写入// async-logger.service.ts import { Worker } from worker_threads; export class AsyncLoggerService { private worker: Worker; constructor() { this.worker new Worker(./logger.worker.js); } log(message: string) { this.worker.postMessage(message); } }10. 扩展思考10.1 与前端日志关联实现前后端日志关联的方案前端在首次加载时生成SessionId所有API请求携带SessionId和TraceId日志系统中建立SessionId和TraceId的关联// 前端代码 axios.interceptors.request.use(config { config.headers[X-Session-ID] getSessionId(); return config; });10.2 日志分析与告警基于日志内容设置智能告警规则错误率超过阈值时触发告警检测到特定异常模式时通知相关人员慢请求比例异常时发出性能警告// log-monitor.service.ts Injectable() export class LogMonitorService { private errorCount 0; private totalCount 0; checkErrorRate(log: string) { this.totalCount; if (log.includes(ERROR)) this.errorCount; const errorRate this.errorCount / this.totalCount; if (errorRate 0.05) { sendAlert(High error rate detected: ${errorRate.toFixed(2)}); } } }在实际项目中我发现一个完善的日志系统往往随着业务发展而不断演进。初期可能只需要简单的请求日志但随着系统复杂度提升分布式追踪、结构化日志、实时分析等功能会逐渐成为必需品。建议在项目早期就建立良好的日志规范为后续扩展打下基础。