構造化イベント vs テキスト ログ

テキスト ログには、プログラムの動作が記述されます。構造化イベントは、ワークフローに関する安定した事実を記録します。どちらも便利ですが、さまざまな質問に最適化されます。

テキスト ログは、起動メッセージ、予期しない分岐、ライブラリ出力、スタック トレースなどのローカル診断に適しています。その自由形式のメッセージは、狭い時間範囲で読んでいる人のためにコンテキストを保持します。構造化イベントは、ルートごとの失敗率、モデルごとのコスト、ソースごとのアクティブ化、キューごとの再試行など、多くのリクエストにわたって同じ質問に繰り返し答える必要がある場合に適しています。

クエリの違い

アプリケーションが次のように書くとします。 invoice sync failed for team_123 in 940ms。検索ではその文を見つけることができますが、グラフではまずチーム、期間、結果を抽出する必要があります。構造化フィールドを使用すると、クエリを直接操作できます。

SELECT
  error_type,
  COUNT(*) AS failures,
  approx_percentile_cont(duration_ms, 0.95) AS p95_duration_ms
FROM billing_syncs
WHERE status = 'failed'
  AND timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY error_type
ORDER BY failures DESC;

イベント コントラクトでは、フィールドのタイプとカテゴリが明示されています。また、小さな文言の変更によって保存されたクエリが壊れるのを防ぎます。

すべてを複製せずに両方を使用する

エンジニアがインシデントを調査する際に、詳細な短期間の診断ログを保存します。ワークフローの境界で耐久性のある構造化イベントの小規模なセットを発行します。この 2 つをリクエスト ID、トレース ID、ジョブ ID、またはその他の安全な相関値でリンクします。フルスタック トレースやリクエスト本文をすべての分析イベントにコピーしないでください。

イベントは、JSON だからといって、自動的に改善されるわけではありません。変更キーと任意の文字列のバッグを分析するのは依然として困難です。この値は、安定した名前、文書化されたフィールド、管理されたカテゴリ、および変更をレビューする所有者といった意図的な契約から得られます。

実用的な選択ルール

データから集計、比較、アラートを作成したり、ダッシュボードを構築したりする場合は、構造化イベントを選択します。特定の調査中に詳細なコンテキストを読み取ることが主な用途の場合は、テキスト ログを選択します。両方が必要な場合は、相関識別子を共有する 1 つのコンパクト イベントと 1 つの診断レコードを発行します。

読む イベントスキーマの設計 大規模なイベントを追加する前に、 構造化されたロギングガイド 計測して検証します。