OpenTelemetry-js 中如何正确设置活动 Span 的实践指南

在分布式追踪系统中，Span 是表示单个操作的基本单元。OpenTelemetry-js 提供了强大的 API 来创建和管理 Span，但很多开发者在实际应用中会遇到如何正确设置活动 Span 的问题。本文将深入探讨这个问题，并提供最佳实践方案。

核心问题分析

在 OpenTelemetry-js 应用中，开发者经常会遇到 trace.getActiveSpan() 返回 undefined 的情况。这通常是由于上下文管理器的配置不当导致的。上下文管理器负责维护当前执行上下文中的 Span 状态，是 OpenTelemetry 能够追踪调用链的关键组件。

正确的 SDK 初始化方式

初始化 OpenTelemetry NodeSDK 时，关于上下文管理器的配置有以下要点：

1. 自动初始化：如果不显式提供上下文管理器，NodeSDK 会自动创建并启用一个 AsyncHooksContextManager。这是推荐的做法，因为 SDK 会处理好所有内部细节。

2. 手动配置：如果确实需要自定义上下文管理器，应该在 NodeSDK 构造函数中直接提供，而不是在初始化后单独设置。双重初始化会导致不可预测的行为。

最佳实践代码示例

以下是推荐的 Fastify 集成方案：

// 正确的 SDK 初始化
const sdk = new NodeSDK({
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: `your-service-name`,
  }),
  traceExporter: new OTLPTraceExporter()
});

sdk.start();

// Fastify 集成
server.addHook("onRequest", async (req, res) => {
  return tracer.startActiveSpan(req.routerPath, (span) => {
    span.setAttributes({
      hostname: req.hostname,
      path: req.routerPath,
      method: req.method,
      ip: req.ip,
    });

    res.raw.on("close", () => {
      span.end();
    });

    // 确保返回 Promise 以维持异步上下文
    return Promise.resolve();
  });
});

关键注意事项

1. 上下文保持：确保所有异步操作都在 startActiveSpan 回调中执行，这样才能保持上下文链。

2. Promise 处理：在异步函数中，必须正确处理 Promise 链，否则会导致上下文丢失。

3. Span 生命周期：确保每个创建的 Span 都会被正确结束，避免内存泄漏。

4. 错误处理：考虑添加适当的错误处理逻辑，确保即使请求处理出错，Span 也能被正确结束并记录错误信息。

常见问题排查

如果仍然遇到活动 Span 不可见的问题，可以检查以下几点：

1. 确认 SDK 初始化成功且没有错误
2. 验证是否在正确的异步上下文中访问活动 Span
3. 检查是否有其他中间件可能干扰了 OpenTelemetry 的上下文传播
4. 考虑增加日志输出，跟踪 Span 的创建和结束过程

通过遵循这些最佳实践，开发者可以确保 OpenTelemetry-js 在 Fastify 或其他 Node.js 框架中正确追踪请求链路，为分布式系统提供可靠的观测能力。