ログフォーマットのベストプラクティス|JSON・時刻・相関 ID

本番ログを検索しやすくするために、JSON のイベント区切り、発生時刻、ログレベル、トレース ID、機密情報の扱いを整理します。

ベストプラクティス
ログ、メトリクス、トレースを示すイラスト

UTC 03:14 に決済リクエストがタイムアウトしたとします。ゲートウェイはルートと処理時間を記録しています。一方、決済サービスは上流でタイムアウトした旨を出力し、スタックトレースを複数行に分けて書きました。どちらのログも保存先には届いています。それでも、ルートで絞り込めるのは片方だけで、スタックの各行が別イベントになり、照合に使える ID も揃っていません。

ログフォーマットは、イベントの区切り方と、読み手が頼れる項目を決める取り決めです。 同じ JSON でも、あるサービスが処理時間を数値の duration_ms で、別のサービスが文字列の "900ms" で出すと、同じ条件で検索や集計ができません。

どこまでを一件として扱うか決める

自由形式のテキストは、開発時に一つのプロセスを追うには便利です。半構造化ログでは一定の接頭辞やキーと値の並びを使い、構造化ログでは項目と型を定義します。同じタイムアウトでも、取り込み側で必要な処理は変わります。

形式 記録例 取り込み時に必要なこと
自由形式 Upstream timed out after 900 ms メッセージから時間と単位を抽出する
半構造化 level=ERROR duration_ms=900 msg="Upstream timed out" キーと値の区切りや引用符の規則を解釈する
構造化 {"level":"error","duration_ms":900,"message":"Upstream timed out"} JSON を解析し、合意したスキーマに当てはめる

ファイルや標準出力を行単位で収集するなら、JSON エンコーダーで一行に一イベントを書き出します。メッセージ内の引用符、バックスラッシュ、改行はエスケープします。整形表示した複数行の JSON をそのまま渡す場合は、別の区切り方が必要です。開発用コンソールは読みやすい表示にして、本番のファイルでは同じイベント項目を JSON で残せます。JSON の文字列とエスケープ

Go の slog.JSONHandler はイベントを一行ずつ JSON で出力します。Nginx では log_format で JSON オブジェクトを定義し、変数の値に escape=json を指定して、access_log でその形式を選びます。PostgreSQL 15 以降で log_destination = 'jsonlog' を使うには、logging_collector の有効化も必要です。出力される項目はそれぞれ異なるので、共通スキーマへの変換は実際のレコードを見て決めます。Go slog · Nginx ログモジュール · PostgreSQL のログ設定

ログレベルと発生時刻をそろえる

debug、info、warning、error など、検索に使うレベル名を決め、各ライブラリの出力を対応付けます。同じ意味で使われる WARN と warning は、同じ条件で抽出できるようにします。数値レベルはライブラリによって意味が異なります。OpenTelemetry の SeverityNumber も独自の尺度で、文字列の SeverityText とは別の項目です。OpenTelemetry のログデータモデル

タイムアウトを調べるときに使いたいのは発生時刻です。RFC 3339 なら Z や UTC オフセットを明示し、Unix 時刻なら秒、ミリ秒、ナノ秒のどれかをスキーマに定めます。観測時刻や取り込み時刻が得られる場合は、別の項目に残します。転送に 30 秒かかったイベントも、本来発生した時間帯で検索できるようにするためです。UTC に統一してもホストの時計のずれは直りません。RFC 3339

検索範囲を絞れる項目を残す

サービス名と環境名を共通項目にします。複数のレプリカを見分ける必要があればインスタンス ID も加えます。ビルドのバージョンやコミット ID は、ログ本体または取り込み後も参照できるリソース属性に残します。新旧バージョンが同時に稼働していても、タイムアウトが片方のリリースに偏っているか調べられます。ファイル名、関数名、行番号は、調査に必要な箇所でロガーやハンドラーから付けます。

たとえばルートは /orders/{order_id} のようなテンプレートで、処理時間は数値の duration_ms で記録します。名前、型、単位はサービスをまたいでそろえます。注文番号や HTTP ヘッダー名を使って動的に項目名を作ると、項目の種類が増え続けます。識別子は固定した項目の値に入れ、欠損や型の変更を取り込み側でどう扱うかも確認します。

リクエスト ID とトレース ID の使い分け

アプリケーションの request_id は、同じ値を引き継いでいるコンポーネントのログを探すのに使えます。トレース ID は分散トレース全体、スパン ID はその中の操作を指します。有効なスパンがあるときは、計装ライブラリから現在の識別子を取り出してログに記録します。次のサービスにもトレースコンテキストを伝播させます。スパンがない処理でもリクエスト ID は使えます。検索できるのは収集されて保管期間内にあるログで、対応するトレースはサンプリングや保管期間によって見つからないことがあります。W3C Trace Context

次は一行にまとめた合成イベントです。スタック内の改行はエスケープされ、一件の中に収まります。

{"time":"2026-11-09T03:14:00Z","level":"error","service":"payments","env":"prod","version":"v2.3.1","route":"/orders/{order_id}","duration_ms":900,"request_id":"req-example-42","trace_id":"4bf92f3577b34da6a3ce929d0e0e4736","span_id":"00f067aa0ba902b7","message":"Upstream returned \"timeout\"","error_type":"UpstreamTimeout","stack_trace":"UpstreamTimeout\n  at capture (payments.go:71)"}

スタックは呼び出し経路が調査に役立つ例外で残します。見積もり期限切れのように想定している業務上の拒否なら、エラーコードと必要な情報で足りる場合があります。ファイルや関数で集計するなら、スタックのフレームを項目に分けます。旧来のロガーがスタックを複数の行に出す場合は、コレクターにイベントの先頭行を認識させ、後続の行が元のエラーに付くか確かめます。DataKit の複数行ログ収集

プロセスの外へ出す情報を選ぶ

オブジェクトはログ出力を許可する項目を決めてから記録します。利用者オブジェクト全体、リクエスト本文、ヘッダー一覧よりも、種類を絞ったエラー名や調査に必要な識別子を優先します。Go の slog.LogValuer を実装すると、その値がロガーに渡されたときの出力を指定できます。別の出力経路やエラーメッセージ、スタックに秘密情報が残ることもあるため、シリアライズ後のログを確認します。OWASP のログ指針(英語)

本番に適用する前に、通常のイベント、引用符や改行を含む例外、項目が欠けたイベントを同じパーサーに通します。Guance では DataKit でファイルを収集し、Pipeline でアプリケーションのログレベルを status に対応付けられます。ログ画面で発生時刻と項目の型を見て、元のメッセージにも機密値が残っていないか確認します。APM とログ収集を設定済みであれば、抽出した trace_id と検索できるトレースの ID を突き合わせます。DataKit ログコレクター · Guance のログとトレースの関連付け(英語)

形式が固まったら、ログ集約で複数システムから同じ保存先へ集める方法を確認できます。より広い考え方は構造化ログの解説(簡体字中国語)にまとめています。

最適なプランを相談する

お問い合わせ

コミュニティに参加

WeChatでスキャンして
コミュニティに参加

Guanceを試す

オンラインですぐに始めて、使った分だけお支払いください。

利用を開始

Guanceのプランを選択

コードリポジトリ