correlation-tracing

相関 ID と分散トレーシング

目次

• 概要
• 使用する場面
• クイックスタート
• リファレンスガイド
• ベストプラクティス

概要

相関 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/ ディレクトリを参照してください。

ガイド	内容
相関 ID ミドルウェア（Express）	相関 ID ミドルウェア（Express）
OpenTelemetry の統合	OpenTelemetry の統合
Python の分散トレーシング	Python の分散トレーシング
手動でのトレース伝播	手動でのトレース伝播

ベストプラクティス

✅ 推奨事項

• エントリーポイントでトレース ID を生成します
• サービス間でトレースコンテキストを伝播させます
• ログに相関 ID を含めます
• 構造化ログを使用します
• 適切なスパン属性を設定します
• トラフィックの多いシステムではトレースをサンプリングします
• トレース収集のオーバーヘッドを監視します
• コンテキスト伝播を実装します

❌ 禁止事項

• トレース伝播を省略しないでください
• 相関コンテキストなしでログを記録しないでください
• スパンを作りすぎないでください
• スパンに機密データを保存しないでください
• トレースの報告中に処理をブロックしないでください
• エラー追跡を忘れないでください