在 Node.js 应用中，如何利用 Async Hooks 实现全链路追踪？

新闻中心 NEWS CENTER

您当前位置：首页 > 新闻中心 > 网络学院

在 Node.js 应用中，如何利用 Async Hooks 实现全链路追踪？

2025-10-07

浏览次数：次

返回列表

全链路追踪通过 AsyncLocalStorage 在请求进入时创建上下文并生成 traceId，利用 Async Hooks 保持异步调用链中上下文的连续性，确保日志输出及异步操作中可访问 traceId，从而串联请求流程。

在 node.js 应用中，如何利用 async hooks 实现全链路追踪？

在 Node.js 应用中，全链路追踪的核心是跨异步上下文保持请求级别的唯一标识（如 traceId），以便将一次请求在多个异步操作中的行为串联起来。Async Hooks 模块提供了监听异步资源创建与执行的机制，是实现这一目标的关键工具。

什么是 Async Hooks？

Async Hooks 是 Node.js 内置模块，允许你注册回调来跟踪异步资源的生命周期。它能捕获异步操作的创建、执行和销毁过程，最关键的能力是保持异步上下文之间的关联。

通过 executionAsyncId() 可获取当前执行上下文 ID，而 triggerAsyncId() 可知道是谁触发了当前异步操作。这些信息可用于构建上下文继承关系。

使用 AsyncLocalStorage 实现上下文传递

虽然 Async Hooks API 较底层，但 AsyncLocalStorage（Node.js 14+）基于它封装了更易用的接口，是目前推荐的方式。

以下是实现全链路追踪的基本步骤：

创建一个 AsyncLocalStorage 实例用于存储请求上下文
在请求进入时（如 Express 中间件）初始化上下文并设置 traceId
在日志输出或其他异步操作中读取当前上下文中的 traceId

示例代码：

const { AsyncLocalStorage } = require('async_hooks');
const asyncLocalStorage = new AsyncLocalStorage();

function generateTraceId() {
  return Math.random().toString(36).substr(2, 9);
}

// Express 中间件
function traceMiddleware(req, res, next) {
  const traceId = generateTraceId();
  asyncLocalStorage.run({ traceId }, () => {
    console.log(`[START] Request ${traceId}`);
    next();
  });
}

// 带 traceId 的日志函数
function log(message) {
  const store = asyncLocalStorage.getStore();
  const traceId = store ? store.traceId : 'unknown';
  console.log(`[TRACE:${traceId}] ${message}`);
}

// 使用示例
app.use(traceMiddleware);
app.get('/user', (req, res) => {
  log('Fetching user data'); // 自动带上 traceId
  setTimeout(() => {
    log('User data fetched'); // 异步中仍可访问 traceId
    res.json({ id: 1, name: 'John' });
  }, 100);
});