構造化ロギングガイド

構造化ログでは、すべての詳細を文に記述するのではなく、イベントを名前付きフィールドとして記録します。次のようなメッセージ checkout failed for account 42 after 812 ms は読み取り可能ですが、SQL は、障害をグループ化したり、レイテンシーを計算したりする前に、それを解析する必要があります。構造化されたイベントストア event_name, account_id, status, error_type、そして latency_ms 別に。

質問から始めましょう

フィールドを選択する前に、運用上または製品に関する質問を書き留めてください。 「最も頻繁に失敗するチェックアウト手順はどれですか?」安定したステップ名、ステータス、エラー カテゴリ、およびタイムスタンプを意味します。 「どの顧客が影響を受けましたか?」安全なアカウント識別子も必要です。フィルター、グループ、計算、またはデバッグで使用される可能性のないフィールドは、おそらくノイズです。

意味のある境界にある 1 つのイベントを優先します。たとえば、リクエストの完了、ジョブの再試行の完了、Webhook の重複排除、ユーザーのアクティベーション マイルストーンの到達などです。同じワークフローのブランチごとに異なるテーブルを生成することは避けてください。一貫した status フィールドでは、成功と失敗を比較できるようになります。

await telemetry.log("checkout_completed", {
  checkout_version: "v2",
  account_id: account.id,
  status: "failed",
  error_type: "payment_declined",
  latency_ms: 812,
  attempt: 1,
});

安定した契約を維持する

使用する snake_case 名前、明示的な単位など _ms そして _bytes、UTC タイムスタンプ。ストアカテゴリーなど payment_declined信頼できるグループ化ディメンションが必要な場合は、完全な例外テキストではありません。リクエスト、アカウント、リリース、またはジョブをシステム全体で追跡できるように、イベント間で識別子の一貫性を保ちます。

フィールドを黙って数値から文字列に変更しないでください。意味が変わった場合は、バージョン フィールドまたは新しいイベント コントラクトを追加します。の イベントスキーマ設計ガイド 命名、所有権、進化について詳しく説明します。

機密データを保護する

すべての新しいフィールドを、クエリ結果、ダッシュボード、またはエクスポートに表示されるデータとして扱います。認証情報、Cookie、認証ヘッダー、完全なリクエスト本文、支払い詳細、または生のプロンプトを送信しないでください。 メールアドレスや自由形式のユーザー内容ではなく、内部識別子と値を制限したカテゴリを使用してください.イベント構築境界でホワイトリストを適用します。 取り込み後のマスキングは補助策であり、主要な制御ではありません.

イベントを確認する

合成データを使用して、成功、失敗、タイムアウト、およびブランチの再試行を実行します。結果のテーブルを検査し、フィールドのタイプを確認し、イベントの原因となったクエリを実行します。次に、結果がビジネス定義と一致した場合にのみ、ビジュアライゼーションまたはアラートを作成します。

続けて、 構造化されたログ管理ガイド, 正規の広域イベント, 構造化イベントとテキスト ログの比較、またはから完全なクエリをコピーします。 SQL レシピ ライブラリ.