構造化ログとは?項目と発生時刻をそろえて検索する
ログの項目、型、発生時刻をそろえ、旧形式を取り込み時に正規化して、サービス別にエラーを集計する方法を解説します。
決済エラーが増え、「connection refused」でログを探すと、複数のサービスのメッセージが出てきます。知りたいのは、どのサービスがそのログを出したのか、同じエラーコードなのか、処理がどのくらい続いてから失敗したのかです。
構造化ログでは、その情報を項目ごとに記録します。人はメッセージを読み、バックエンドで項目を抽出して対応付けた後は、クエリでサービス別に集計したり、処理時間で絞り込んだりできます。JSON は記録形式の一つです。メッセージ全体を JSON に包むだけでは、必要な項目はまだ取り出す必要があります。
検索できるイベントを一つ作る
次は正規化後のサンプルです。決済処理の失敗一件を表します。
{
"time": "2026-08-25T08:55:01Z",
"status": "error",
"message": "database connection failed",
"service": "order",
"event": "checkout.failed",
"error_code": "DB_CONNECT_ERROR",
"duration_ms": 1200,
"trace_id": "00000000000000000000000000000001"
}
メッセージは人に失敗の内容を伝え、event と error_code は文言を直しても同じ条件で検索するために使います。duration_ms は数値です。送信元が文字列の "1200" を出す場合は、duration_ms > 900 のような数値条件で使う前に、取り込み時の型を確認または変換します。スキーマには、各項目の意味、型、単位と、値がない場合の扱いを決めておきます。欠損をそのまま残せば、計測した値がゼロだった場合と区別できます。
イベントが発生した時刻と、コレクターが観測した時刻は分けます。バッファリングによって送信が2分遅れても、有効な発生時刻があれば障害時の検索に使えます。取り込みの遅れも調べるなら、観測時刻を別に残します。OpenTelemetry ではそれぞれ Timestamp と ObservedTimestamp です。 OpenTelemetry のログデータモデル(英語)
出力元で構造化する
コレクターが安定して読める形式を選び、その形式で出力するようロガーを設定します。型付きの値や入れ子のデータには JSON が使えます。単純なキーと値の組なら Logfmt も候補です。開発環境と本番環境で形式を変える場合は、両方の取り込みを確認します。
次は Go 1.21 以降の標準ライブラリで動く例です。log.go に保存し、go run log.go を実行します。
package main
import (
"log/slog"
"os"
)
func main() {
logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
logger.Error("database connection failed",
"service", "order",
"event", "checkout.failed",
"error_code", "DB_CONNECT_ERROR",
"duration_ms", 1200,
)
}
JSON ハンドラーは、イベントの項目とともに time、level、msg を一行で出力します。時刻は実行時の値です。この単独のプログラムにはアクティブなトレースがありません。最初の例に合わせるには、取り込み時に level と msg を status と message に対応付け、レベルの値も正規化します。 Go slog のドキュメント(英語)
基盤コンポーネントでも同じ確認が必要です。PostgreSQL 15 以降で log_destination に jsonlog を指定するには、サーバー起動時に有効になる logging_collector が必要です。形式を変える前に、出力先、ローテーション、収集設定を確認します。 PostgreSQL のログ設定(英語)
稼働中の旧形式も取り込む
変更できないサービスが決まった形式のテキストを出しているなら、Guance Pipeline(英語) で発生時刻やレベルなどを取り出せます。正常な行だけでなく、値が欠けた行と形式が崩れた行も試します。データの取り扱い方針に従って調査に必要な原文を残し、解析に失敗したことが分かるようにします。設定した処理は Pipeline を通るログに適用されます。保存済みのデータには、別途移行するか、両方の形式を扱うクエリが必要です。
一緒に調べたいサービスから、項目の意味と型をそろえます。ビューアーで展開できる JSON オブジェクトでも、内側の値を集計するには抽出やマッピングが必要な場合があります。保存先と保存期間はログインデックスのルールに沿って設定します。 Guance のログインデックス
正規化した項目で集計する
以下の DQL では、コレクターが source=checkout を設定し、正規化したログを default ログインデックスに書き込み、time をイベント時刻として解析しているとします。
L("default")::checkout:(count(*) AS error_events)
{ `status` = "error" AND `event` = "checkout.failed" }
[1787648100000:1787648400000] BY service
期間は 2026 年 8 月 25 日の 08:55〜09:00 UTC です。実データでは、収集元、インデックス、期間を実際の設定に合わせます。上のサンプルだけが条件に一致するなら、order の件数は 1 です。再試行で複数のログが出る場合や、このログを出さずに失敗するリクエストもあるので、これはエラーログの件数です。リクエストのエラー率を出すときは、対象リクエストの総数が分かる計測を使います。 Guance DQL リファレンス
Guance のログエクスプローラーでは、抽出結果を見て、インデックスで検索できる項目を使って絞り込みます。似たメッセージは、選んだ範囲でクラスタリングして例を見つけられます。総数や推移が必要なら、範囲を明示して集計し、通知が必要ならモニターを設定します。
トレースと照合できる情報を残す
リクエストにトレースコンテキストがある場合は、実際のトレース ID を記録します。特定の処理を区別したいときはスパン ID も残します。アプリケーションのリクエスト ID とトレース ID は別の識別子です。Guance のトレース詳細では、トレース全体のログを既定で trace_id で関連付けます。service、env、version などはログインデックスの選択に使います。確認するには、両方のデータが収集、保存され、アクセスできる必要があります。
人が読めるメッセージと、調査に使う項目を残し、認証情報や不要な個人情報は記録から外します。項目を増やす前に、実際の負荷でシリアライズ、解析、保存への影響を測ります。まずは、同じ障害を必要なサービスのログから、正しい発生時刻と項目で見つけられるか確かめます。
