调试微服务：关联 ID 如何将我们的调试时间从数小时缩短到数分钟

Source: Dev.to

我又带来一篇新文章，分享我最近学到的东西。今天，我们来聊聊 微服务中的日志记录，以及实施合适的日志记录是如何把我们的调试工作流从噩梦般的状态转变为真正可管理的状态的。🚀

如果你在使用微服务，你一定懂得其中的痛点：生产环境出现故障时，你得在不同的服务之间来回切换，试图弄清到底发生了什么。听起来很熟悉吧？让我们来解决这个问题！

🤔 问题

想象一下：你有 5 个微服务在运行。用户报告了一个错误。你开始调查。

• 你检查 Service A → 没有什么明显的。
• 你检查 Service B → 也许有什么？
• 你检查 Service C → 仍然不确定。

没有明确的答案时，你只能从零散的日志文件中拼凑出一个谜团，尝试匹配时间戳并希望找到关联。时间流逝。 😰

这是一种常见的现实。许多团队都有日志，但它们并不实用。每个服务独立记录日志，无法追踪请求在系统中的整个旅程。

💡 解决方案：关联 ID

改变游戏规则的是什么？关联 ID。

把关联 ID 想象成你包裹的追踪号码 📦。就像你可以追踪包裹在每个运输中心的流转，关联 ID 让你能够追踪请求在每个微服务中的流转。

每个请求都会获得一个唯一的 ID，伴随它穿越整个系统。当出现故障时，你可以：

1. 搜索该 ID
2. 查看完整的请求路径
3. 确定具体的故障点

简单、强大、高效。

🛠️ 如何构建此系统

以下是为微服务实现集中式日志系统的步骤：

• Pino 用于结构化、高性能的日志记录
• Sentry 用于错误追踪和实时警报
• 自定义 NestJS 提供者 确保各服务之间的一致性
• 关联 ID（Correlation IDs） 用于端到端追踪请求

让我一步步演示如何实现！ 👇

📝 第一步：在 NestJS 中设置 Pino

首先，安装必要的包：

npm install pino pino-pretty pino-http
npm install --save-dev @types/pino

为什么选择 Pino？ 它 快速（真的非常快！），生成结构化的 JSON 日志，并且对 NestJS 有很好的支持。

🎯 第 2 步：创建自定义日志提供者

这里就是魔法发生的地方。我们创建一个自定义日志提供者，使每条日志都包含关联 ID（correlation ID）：

// logger.service.ts
import { Injectable, Scope } from '@nestjs/common';
import * as pino from 'pino';

@Injectable({ scope: Scope.TRANSIENT })
export class LoggerService {
  private logger: pino.Logger;
  private context: string;
  private correlationId: string;

  constructor() {
    this.logger = pino({
      level: process.env.LOG_LEVEL || 'info',
      transport: {
        target: 'pino-pretty',
        options: {
          colorize: true,
          translateTime: 'SYS:standard',
          ignore: 'pid,hostname',
        },
      },
    });
  }

  setContext(context: string) {
    this.context = context;
  }

  setCorrelationId(correlationId: string) {
    this.correlationId = correlationId;
  }

  private formatMessage(message: string, data?: any) {
    return {
      message,
      context: this.context,
      correlationId: this.correlationId,
      timestamp: new Date().toISOString(),
      ...data,
    };
  }

  log(message: string, data?: any) {
    this.logger.info(this.formatMessage(message, data));
  }

  error(message: string, trace?: string, data?: any) {
    this.logger.error(this.formatMessage(message, { trace, ...data }));
  }

  warn(message: string, data?: any) {
    this.logger.warn(this.formatMessage(message, data));
  }

  debug(message: string, data?: any) {
    this.logger.debug(this.formatMessage(message, data));
  }
}

这段代码在做什么？

• 我们创建了一个瞬态（transient）作用域的服务（每个请求都会生成一个新实例）
• 每条日志都会包含：message（消息）、context（上下文）、correlationId（关联 ID）、timestamp（时间戳）
• 支持不同的日志级别：info（信息）、error（错误）、warn（警告）、debug（调试）
• 所有日志均以 JSON 结构化，便于检索和分析

🔑 第3步：生成关联 ID

现在我们需要生成并传递关联 ID。我们使用中间件来实现：

// correlation-id.middleware.ts
import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';
import { v4 as uuidv4 } from 'uuid';

@Injectable()
export class CorrelationIdMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    // Check if correlation ID already exists (from previous service)
    const correlationId = (req.headers['x-correlation-id'] as string) || uuidv4();

    // Attach it to the request
    (req as any).correlationId = correlationId;

    // Add it to response headers
    res.setHeader('x-correlation-id', correlationId);

    next();
  }
}

关键要点：

• 如果已经存在关联 ID（来自其他服务），则使用该 ID
• 如果不存在，则使用 UUID 生成一个新的 ID
• 将其同时附加到请求对象和响应头中

🔗 步骤 4：在服务中使用日志记录器

在主模块中注册中间件：

// app.module.ts
import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
import { CorrelationIdMiddleware } from './correlation-id.middleware';
import { LoggerService } from './logger.service';

@Module({
  providers: [LoggerService],
  exports: [LoggerService],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(CorrelationIdMiddleware).forRoutes('*');
  }
}

现在在控制器中使用它：

// user.controller.ts
import { Controller, Get, Req } from '@nestjs/common';
import { Request } from 'express';
import { LoggerService } from './logger.service';

@Controller('users')
export class UserController {
  constructor(private readonly logger: LoggerService) {
    this.logger.setContext('UserController');
  }

  @Get()
  async getUsers(@Req() req: Request) {
    const correlationId = req['correlationId'];
    this.logger.setCorrelationId(correlationId);

    this.logger.log('Fetching users');

    // Your business logic here

    return users;
  }
}

日志记录愉快！ 🎉

🚨 第5步：集成 Sentry 进行错误跟踪

安装 Sentry

npm install @sentry/node

在主文件中配置它

// main.ts
import * as Sentry from '@sentry/node';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
  tracesSampleRate: 1.0,
});

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Add Sentry error handler
  app.use(Sentry.Handlers.requestHandler());
  app.use(Sentry.Handlers.errorHandler());

  await app.listen(3000);
}
bootstrap();

更新你的日志记录器以将错误发送到 Sentry

// logger.service.ts
import * as Sentry from '@sentry/node';
import { Logger } from 'pino';

export class LoggerService {
  private logger: Logger;

  // ... other methods ...

  error(message: string, trace?: string, data?: any) {
    const errorData = this.formatMessage(message, { trace, ...data });

    this.logger.error(errorData);

    // Also send to Sentry
    Sentry.captureException(new Error(message), {
      extra: errorData,
    });
  }
}

🌐 Step 6: 在服务之间传递关联 ID

在向其他微服务发起 HTTP 调用时，转发关联 ID：

// some.service.ts
import { HttpService } from '@nestjs/axios';
import { Injectable } from '@nestjs/common';
import { LoggerService } from './logger.service';

@Injectable()
export class SomeService {
  constructor(
    private readonly httpService: HttpService,
    private readonly logger: LoggerService,
  ) {}

  async callAnotherService(correlationId: string, data: any) {
    this.logger.log('Calling Service B', { data });

    return this.httpService
      .post('http://service-b/endpoint', data, {
        headers: {
          'x-correlation-id': correlationId, // ← Pass it along!
        },
      })
      .toPromise();
  }
}

📊 实际示例

之前

[2025-01-15 10:30:45] Request received
[2025-01-15 10:30:46] Processing data
[2025-01-15 10:30:47] Error: Operation failed

哪个请求？哪个用户？毫无头绪。 🤷‍♀️

之后

{
  "level": "info",
  "message": "Request received",
  "context": "ApiController",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-01-15T10:30:45.123Z"
}
{
  "level": "info",
  "message": "Processing data",
  "context": "DataService",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-01-15T10:30:46.456Z"
}
{
  "level": "error",
  "message": "Operation failed: Validation error",
  "context": "DataService",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-01-15T10:30:47.789Z"
}

现在你可以搜索 550e8400-e29b-41d4-a716-446655440000，查看跨所有服务的完整请求路径！ 🎯

✨ 影响

🎯 关键要点

• Structure – 使用 JSON（可搜索且可解析）而不是纯文本。
• Context – 关联 ID 跟踪跨服务的每个请求。
• Proper levels – 合理使用 debug/info/error；不要把所有日志都记录为 info。
• Centralization – 在一个地方搜索所有日志（例如 Loki、Elastic、CloudWatch）。
• Real‑time alerts – Sentry（或类似工具）在用户投诉之前捕获错误。

💭 最后思考

建立适当的日志记录需要前期花费几天时间，但此后每一次生产事故都能节省数小时甚至数天。如果你在构建微服务，请把日志视为核心特性，而不是事后补充。未来的你会感谢自己的。 😊

🔗 资源

• Pino Documentation
• Sentry Documentation
• NestJS Logging

你呢？ 🤔 你在微服务中实现了关联 ID 吗？遇到了哪些挑战？在下方分享你的经验吧！

如果你觉得这篇文章有帮助，请关注我，获取更多关于 Web 开发、NestJS 和 DevOps 实践的文章。让我们一起学习 ❤️