correlation-tracing

关联与分布式追踪

目录

• 概述
• 适用场景
• 快速开始
• 参考指南
• 最佳实践

概述

实现关联 ID 和分布式追踪，以跨多个服务跟踪请求并了解系统行为。

适用场景

• 微服务架构
• 调试分布式系统
• 性能监控
• 请求流可视化
• 跨服务错误追踪
• 依赖关系分析
• 延迟优化

快速开始

最简可运行示例：

import express from "express";
import { v4 as uuidv4 } from "uuid";

// Async local storage for context
import { AsyncLocalStorage } from "async_hooks";

const traceContext = new AsyncLocalStorage<Map<string, any>>();

interface TraceContext {
  traceId: string;
  spanId: string;
  parentSpanId?: string;
  serviceName: string;
}

function correlationMiddleware(serviceName: string) {
  return (
    req: express.Request,
    res: express.Response,
    next: express.NextFunction,
  ) => {
    // Extract or generate trace ID
    const traceId = (req.headers["x-trace-id"] as string) || uuidv4();
    const parentSpanId = req.headers["x-span-id"] as string;
    const spanId = uuidv4();
// ... (see reference guides for full implementation)

参考指南

references/ 目录中的详细实现：

指南	内容
Correlation ID Middleware (Express)	Correlation ID Middleware (Express)
OpenTelemetry Integration	OpenTelemetry Integration
Python Distributed Tracing	Python Distributed Tracing
Manual Trace Propagation	Manual Trace Propagation

最佳实践

✅ 应该

• 在入口点生成追踪 ID
• 在服务间传播追踪上下文
• 在日志中包含关联 ID
• 使用结构化日志
• 设置适当的 span 属性
• 在高流量系统中对追踪进行采样
• 监控追踪收集的开销
• 实现上下文传播

❌ 不应该

• 跳过追踪传播
• 在没有关联上下文的情况下记录日志
• 创建过多 span
• 在 span 中存储敏感数据
• 因追踪上报而阻塞
• 忘记错误追踪