全链路追踪通过 AsyncLocalStorage 在请求进入时创建上下文并生成 traceId，利用 Async Hooks 保持异步调用链中上下文的连续性，确保日志输出及异步操作中可访问 traceId，从而串联请求流程。
什么是 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);
});
原理与注意事项
AsyncLocalStorage 利用 Async Hooks 在每次异步切换时恢复对应的存储实例，确保即使在 setTimeout、Promise、数据库调用等异步操作中，也能访问到原始请求的上下文。
关键点：
- 每个请求调用 asyncLocalStorage.run() 创建独立上下文
- getStore() 返回当前异步链路上绑定的数据
- 避免在 run 外部修改 store，它是只读的
- 不适用于 worker threads 或跨进程场景
扩展为完整追踪系统
可在基础 traceId 上增加更多字段，如 spanId、开始时间、调用栈等，形成结构化追踪数据。
结合日志收集系统（如 ELK、Prometheus + Grafana），可实现可视化追踪分析。
对于微服务架构，还需在 HTTP 请求头中透传 traceId，实现跨服务联动。
基本上就这些。利用 AsyncLocalStorage 配合中间件和统一日志，就能在 Node.js 中低成本实现有效的全链路追踪。关键是抓住“上下文继承”这个核心，Async Hooks 正是解决异步上下文丢失问题的底层支撑。
