マイクロサービスのログ設計とベストプラクティス
ログ形式とイベント時刻をそろえ、二重収集を防ぎ、OpenTelemetry と Guance でリクエストのログとトレースを関連付ける方法を解説します。
注文の確定リクエストがタイムアウトした。ゲートウェイはエラーを記録したが、その直後に決済サービスでは処理が完了している。ゲートウェイ側のログが遅延し、決済の記録が先に保存先へ届いた。到着順で並べても、分かるのは配送の順序だけだ。調査には、各イベントが発生した時刻と、同じリクエストの記録を見分ける手掛かりがいる。
マイクロサービスのログ設計では、チーム間でイベントの形式をそろえ、各ログをどの経路で集めるか決める。リクエストに関わるログには、書き出す時点のトレースコンテキストを付ける。そのうえで、保存期間とアクセス権限を用途ごとに設計する。
発生時刻と観測時刻を分ける
保存先を決める前に、最低限のフィールドをそろえる。発生時刻には、UTC の RFC 3339 などタイムゾーンを明示した表記を使う。サービス名、環境、リリースバージョンを保持し、イベント名とログレベルの意味もそろえる。サーバーの時計を同期しても時刻のずれは残り得るため、サービス間の前後関係を判断するときはその影響も考える。
次は架空のリクエストについて、アプリケーションが出力する JSON ログの例だ。ロガーは出力時にアクティブな Span から ID を取得できる。
{"event_time":"2026-10-01T12:00:00.425Z","service":"payments","env":"production","version":"1.8.4","severity":"INFO","event":"payment.completed","event_id":"evt_payment_01","trace_id":"4bf92f3577b34da6a3ce929d0e0e4736","span_id":"00f067aa0ba902b7"}
OpenTelemetry のログデータモデルでは、イベントが起きた Timestamp と収集側が観測した ObservedTimestamp を区別する。Body、重大度、発生元の Resource、任意のトレースコンテキストもそれぞれ別の情報だ。JSON ログを OpenTelemetry に変換する場合は、たとえばサービスやデプロイ環境を Resource 属性に割り当て、取得できるなら元の重大度表記と正規化した重大度番号を残す。例の JSON はアプリケーション側の形式であり、OTLP のペイロード形式とは異なる。OpenTelemetry のログデータモデル(英語)
Guance では ログ Pipeline でイベント時刻を time に、ログレベルを status に割り当てる。時刻、タイムゾーン、重大度が分かっているサンプルを送り、保存された値を確認する。到着時刻が代わりに記録されると、遅れて届いたログが調査対象の時間帯から外れることがある。
同じログを二つの経路で送らない
Kubernetes では、ノードで動くコレクターがコンテナランタイムに記録されたアプリケーションの標準出力と標準エラー出力を収集できる。サイドカーを置く場合は、たとえばアプリケーションのファイルを読み取って転送したり、サイドカー自身の標準出力に流したりする。同じ記録が二つの経路から送られないよう、どちらが収集を担当するか決めておく。Kubernetes のログアーキテクチャ(英語)
バックエンドがバッチを受理したあとに応答が失われると、再送で同じイベントが再び届くことがある。重複排除が必要なら、送信元で同じイベントに同じ ID を付け、受信側に処理ルールを設ける。一つのリクエストから複数のログが出るため、トレース ID で重複を判定すると別々のイベントまで消えてしまう。OTLP の重複データに関する制約(英語)
Guance の複数の通常のログインデックスを使う場合は、ログの種類ごとに必要な保存期間とアクセス範囲を決めてから、振り分け条件を設定する。ルールで振り分けるログは、最初に一致した通常のインデックスに書き込まれる。順番を変える前に、二つの条件に一致するサンプルで振り分けを確かめる。保存先の振り分けと参照権限は別々に確認する。
ログにアクティブなトレースコンテキストを載せる
ゲートウェイで付けるリクエスト ID は、アプリケーション側の問い合わせに使える。トレース ID は分散トレース全体、Span ID はその中の一つの処理を識別する。両方を使うなら別のフィールドに保存する。
着信時にトレースコンテキストを抽出し、別のサービスを呼ぶときに対応するヘッダーなどへ注入する。ログを書くときは、アクティブなコンテキストから trace_id と、取得できる場合は span_id を載せる。OpenTelemetry の非 OTLP ログの規約に従う JSON では、トレース ID は小文字の 16 進数で 32 桁、Span ID は 16 桁だ。トレースの外で出るログには、対応するフィールドを入れなくてよい。アプリケーションで付けていないコンテキストは、コレクターがログを受け取るだけでは復元できない。非 OTLP ログのトレースコンテキスト(英語) · OpenTelemetry のコンテキスト伝播
トレースとログのどちらからでも追う
注文の例なら、時間帯とサービスでトレースを絞り、異常が出た Span を見る。同じトレース ID でログを探し、Span ID があれば決済処理の記録まで絞り込む。ゲートウェイのログから始める場合は、そこに記録されたトレース ID を使って逆向きに探す。タイムアウトと決済成功は同じリクエストで両方起こり得る。発生時刻と Span の関係を照らし合わせて判断する。
Guance のトレース詳細では、関連ログの既定の照合フィールドは trace_id だ。トレースの service、env、version などに基づくマッピングによって検索対象のインデックスが決まる。期待したログが見つからなければ、そのインデックスを直接検索し、保存されている値とトレースの値を比較する。ログとトレースはそれぞれ収集され、参照できる状態である必要がある。サンプリングのため、ログが残っていてもトレースが保存されていないことがある。
保存するログの範囲を決める
アプリケーションで記録してよいフィールドを決め、パスワード、アクセストークン、加工していない決済情報は出力から外す。必要な値のマスキングは、その値を受け取るべきでない保存先へ送る前に行う。正常な入力に加えて、不正な形式や複数行のサンプルも試す。抽出したフィールドをマスクしても、元の本文に値が残ることがある。閲覧やエクスポートの権限を絞り、設定の変更も監査する。Guance のインデックス監査画面では、そのインデックスに対する操作を確認できる。OWASP のログ指針(英語) · Collector での機密データのマスキング
保存期間は、調査でどこまでさかのぼるか、適用される要件、費用を基に決める。アーカイブに移す前に、取り出して検索する手順も試しておく。短期の障害調査ログと監査ログを同じ期間にそろえる必要はない。
サービスメッシュからプロキシのテレメトリーを取得できても、「決済を送信した」といった業務イベントはアプリケーションが記録する。まずゲートウェイから決済サービスまで一つのリクエストを通し、各段階の発生時刻、ID、保存先を確かめる。そこから他の経路にも広げる。
関連記事 · ログ監視
