定義
構造化されたログ管理の変更内容
従来のアプリケーション ログは、ローカルでの実行を説明するのに貴重ですが、通常、重要な質問は多くのメッセージにまたがります: チェックアウトは終了しましたか?どのアカウントが影響を受けましたか?再試行で回復しましたか？新しいリリースによりレイテンシーは変更されましたか? 構造化イベントは、成果と分析コンテキストを1つの型付きオブジェクトとして記録します.
構造化ログ管理とは、これらのオブジェクトを定義し、そのスキーマとプライバシーの境界を制御し、それらをクエリ可能なテーブルとして保持し、結果の検索、SQL クエリ、視覚化、ダッシュボード、およびアラートを操作する実践です。これはトレースとメトリクスを補完します。すべてのデバッグ メッセージがビジネス イベントになる必要はありません。
有用なイベントはフィールドを獲得します
質問と決定から始めてください。すべてのフィールドは、ワークフローのフィルター、グループ化、関連付け、計算、保護、または説明に役立つ必要があります。無制限のペイロードは、より良い回答を保証することなく、コストとプライバシーのリスクを生み出します。
テキストログと構造化イベント
さまざまな作業に応じたさまざまな形状
| 懸念 | メッセージ指向のログ | 正規の構造化イベント |
|---|---|---|
| 親機 | ローカル コード パスに関する 1 つのメッセージ | 1 つの完了したワークフローまたは意味のある状態変化 |
| コンテキスト | 多くの場合、多くの回線やサービスにまたがる | 安定した識別子、結果、期間、および次元をまとめたもの |
| 分析 | パターンの検索と解析 | 型指定されたフィルター、グループ、結合、パーセンタイル、ファネル、およびコホート |
| スキーマ | 散文とフォーマットに暗黙的に含まれる | 明示的な型、単位、および許可された値を持つ名前付きフィールド |
正規の完了イベント
{
"event": "checkout_completed",
"timestamp": "2026-07-28T18:42:16Z",
"request_id": "req_01K1A9",
"account_id": "acct_812",
"plan": "growth",
"status": "success",
"duration_ms": 842,
"amount_usd": 129.00,
"payment": {
"provider": "stripe",
"attempt": 1
}
}イベント契約
分析の耐久性を維持する設計ルール
決定境界を選択する
リクエスト、ジョブ、Webhook、エージェントの実行、請求の変更、または製品マイルストーンが誰かが説明する必要がある結果に達したときにイベントを発行します。
一度十分なコンテキストをキャプチャする
安定したイベント名、UTC 時間、ステータス、期間、環境、リリース、安全な識別子、既知の質問で必要な制限されたディメンションを含めます。
型と単位を保持する
数値は数値として、ブール値はブール値として、フィールド名の単位はそのままにしておきます。後でメッセージ文字列からレイテンシー、金額、またはカウントを解析することは避けてください。
機密性の高いコンテンツを制限する
シークレット、認証情報、認証ヘッダー、生のプロンプト、支払い詳細、不要な個人データを除外します。分類されたエラー コンテキストを優先します。
イベントを運用上の回答に変える
SELECT
date_trunc('hour', timestamp_utc) AS hour,
COUNT(*) AS checkouts,
SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END) AS succeeded,
ROUND(
100.0 * SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END)
/ NULLIF(COUNT(*), 0),
2
) AS success_rate_pct,
approx_percentile_cont(duration_ms, 0.95) AS p95_duration_ms
FROM checkout_events
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY date_trunc('hour', timestamp_utc)
ORDER BY hour;傾向と分母を合わせて読む
チャートは 16:00 の変化を明らかにします。同じクエリでは、解釈のためにチェックアウト数と p95 期間が保存されます。分母が十分に大きいことを確認した後でのみ、影響を受ける時間をリリース、プロバイダー、プラン、またはアカウントごとに分類します。
調査順序
- 1.レート、レイテンシー、コスト、またはボリュームの意味のある変化を検出します。
- 2.時間枠、分母、イベントの鮮度を確認します。
- 3.変更を、制限された所有権またはロールアウトのディメンションごとに分類します。
- 4.影響を受けるリクエストまたはアカウントの相関イベントを検査します。
- 5.検証されたクエリを保存し、応答を文書化します。
計測
構造化されたログとスキーマのガイドを使用して、安全な型付きイベント コントラクトを定義します。
計測ガイドを開く分析する
信頼性、雇用、製品、収益、AI、またはデータ品質についてテストされた SQL パターンから開始します。
SQL レシピを参照する操作する
結果をダッシュボードまたはアラートにプロモートする前に、取り込みとクエリの動作を確認します。
取り込みのトラブルシューティング1 つのワークフローから始める
合成イベントを送信し、最初の質問に回答します
アプリケーション全体にインストルメンテーションを拡張する前に、安全なテスト データを使用してイベント コントラクトを証明します。