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

目次

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

概要

相関 ID と分散トレーシングを実装して、複数のサービス間でリクエストを追跡し、システムの動作を理解します。

使用時期

• マイクロサービスアーキテクチャ
• 分散システムのデバッグ
• パフォーマンス監視
• リクエストフローの可視化
• サービス間のエラー追跡
• 依存関係分析
• レイテンシー最適化

クイックスタート

最小限の動作例:

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

// コンテキスト用の Async Local Storage
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,
  ) => {
    // トレース ID を抽出または生成
    const traceId = (req.headers["x-trace-id"] as string) || uuidv4();
    const parentSpanId = req.headers["x-span-id"] as string;
    const spanId = uuidv4();
// ... (完全な実装についてはリファレンスガイドを参照)

リファレンスガイド

references/ ディレクトリの詳細な実装:

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

ベストプラクティス

✅ すべきこと

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

❌ すべきではないこと

• トレース伝播をスキップする
• 相関コンテキストなしでログを出力する
• 過度に多くのスパンを作成する
• 機密データをスパンに格納する
• トレース報告をブロックする
• エラー追跡を忘れる