アドホック ログから構造化イベントおよび SQL への移行
自由形式のログはローカル デバッグには便利ですが、運用や製品に関する質問が繰り返し発生する場合は、安定したフィールド、明示的な単位、レビュー可能な定義が必要です。移行では、既存のログや可観測性ツールをすべて置き換える必要はありません。 1 つの運用ワークフローから開始し、既存のログの横に 1 つの制限付き完了イベントを発行し、ダッシュボードやアラートを変更する前に、その SQL が意図した質問に答えることを証明します。の 構造化されたログ管理ガイド より大規模な運用モデルについて説明します。
このガイドでは例として API リクエストを使用しますが、同じシーケンスがジョブ、Webhook、AI 実行、請求ワークフロー、およびアプリケーション レベルのデータベース操作に適用されます。
1. ログ ストリーム全体ではなく、1 つの決定を選択します
すでにエンジニアリングに時間を費やしている質問から始めます。
- 意味のある 5xx レートを持つ API ルートはどれですか?
- 再試行後に回復するレート制限リクエストはどれですか?
- どの職種がキューの寿命を延ばしていますか?
- どのプロンプト バージョンが受け入れられる結果を少なくしますか?
- 1 つのリクエスト内で繰り返されるデータベース操作のフィンガープリントはどれですか?
回答がサポートする決定、所有者、レポートウィンドウ、レートを解釈するために必要な最小ボリュームを書き留めます。これにより、イベントがアプリケーション メモリ内で使用可能なすべての値のコピーになるのを防ぎます。
有用な場合は、スタック トレースまたはローカル コンテキストの診断ログを保存してください。構造化イベントは、選択した質問に対する永続的な分析コントラクトです。
2. 現在の意味を棚卸しする
インストルメンテーションを変更する前に、既存の検索またはダッシュボードの定義を保存し、いくつかの実際の結果を検査します。記録:
- どのメッセージまたは属性がワークフローを識別するか。
- 成功、再試行、キャンセル、および端末の失敗を区別する方法。
- 作業の開始または完了をマークするタイムスタンプ。
- 再試行によって追加のレコードが作成されるかどうか。
- どのフィールドにシークレット、個人データ、生のペイロード、または無制限のテキストが含まれるか。
- どの除外ルールと最小量ルールはオペレーターの記憶の中にのみ存在します。
このインベントリは意味論的なベースラインであり、古い結果が正しいことを保証するものではありません。既存の検索で試行と論理リクエストが混在している場合は、その制限を黙って再現するのではなく、文書化してください。
3. 1 つの制限付き完了イベントを定義します。
完了した作業単位に対して 1 つのイベントを優先します。明示的な数値、ブール値、単位、および管理されたカテゴリを使用します。生の URL の代わりにルート テンプレートを使用し、制限のない例外テキストの代わりに分類されたエラーを使用し、相関に必要な場合にのみ内部識別子を使用します。
{
"event_name": "api_request_completed",
"request_id": "req_7d91",
"route_template": "/api/projects/:id/sync",
"method": "POST",
"status_code": 503,
"outcome": "dependency_failed",
"latency_ms": 842,
"attempt_number": 2,
"release": "2026.07.2",
"environment": "production",
"schema_version": 1
}
認証ヘッダー、Cookie、リクエスト本文、接続文字列、生のプロンプト、Webhook ペイロード、支払い詳細、または無制限の顧客コンテンツを送信しないでください。導入前にフィールドのホワイトリストを確認してください。参照 機密データの編集 そして 高カーディナリティのフィールド.
4. 既存のログの横に出力する
時間制限のある二重書き込み期間を実行します。アプリケーションは、チームが依存する診断レコードを生成し続けると同時に、新しいイベントも生成します。中央の境界にインストルメンテーション (ミドルウェア、ジョブ ラッパー、Webhook ディスパッチャー、データベース クライアント ラッパー) を追加すると、成功パスと失敗パスで同じクロック名とフィールド名が使用されます。
インストルメンテーションによってアプリケーションの成功が失敗に変わってはいけません。分析の配信は、明示的なタイムアウトとシステムに適した再試行動作を備えた個別の制限された操作として扱います。欠落している構成を適用する前に、デプロイされたすべての環境で安全にフォールバックすることを確認してください。
二重書き込み中に、イベント取り込みの鮮度、必須フィールドの完全性、スキーマのバージョン、および重複した識別子を監視します。の イベント取り込みの鮮度, 必須フィールドの null 率、そして 重複したイベントID レシピは再利用可能なチェックを提供します。
5. 質問をレビュー済みの SQL に翻訳します。
テキスト検索式を音訳するのではなく、イベント コントラクトから開始します。 API エラーの場合は、カウントと分母の両方を保持します。
SELECT
route_template,
COUNT(*) AS requests,
SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END) AS errors,
100.0 * SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END)
/ NULLIF(COUNT(*), 0) AS error_rate_pct
FROM api_request_completed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
AND environment = 'production'
GROUP BY route_template
HAVING COUNT(*) >= 20
ORDER BY error_rate_pct DESC;
時間境界、ステータスの定義、再試行の粒度、遅延イベントの処理、および最小ボリュームを確認します。少なくとも 1 つの成功、予想される失敗、再試行、重複、NULL、および遅延イベントをテストします。クエリが操作上重要になる場合は、決定論的なフィクスチャと予想される結果をその横に保存します。
の SQL レシピ ライブラリ 型付きスキーマ、読み取り専用 DataFusion SQL、合成出力、視覚化、エッジ ケース、ダッシュボード プラン、およびアラート ガイダンスが含まれます。の ブラウザ SQL プレイグラウンド サンプル行を Telemetry に送信せずに、サポートされているフィクスチャをローカルで実行します。
6. 合計だけでなく意味を比較する
同じ閉じた UTC ウィンドウで古い回答と新しい回答を実行します。任意の完全一致をターゲットにするのではなく、相違点を調査します。
- 新しいカウントが低いということは、再試行が正しく折りたたまれていることを意味している可能性があります。
- カウントが高くなると、メッセージ パターン検索で省略された失敗が明らかになる可能性があります。
- 生の URL を安定したルート テンプレートに置き換えることで、ルート ランキングが異なる場合があります。
- 最近の小さな不一致は、遅延したイベントまたは不完全なタイム バケットによって引き起こされる可能性があります。
- 履歴データには、新しい契約によって導入されたフィールドが含まれない場合があります。
原因、受け入れられた動作、所有者、イベントまたはクエリに変更が必要かどうかなど、相違点ごとに短い調整レコードを作成します。古いバグが再現されるまで、新しい SQL をチューニングしないでください。
7. 段階的に推進する
一度に 1 人のコンシューマを移動します。
- 探索レポートには、新しい SQL を使用してください。
- レビューしたクエリをその所有者と定義とともに保存します。
- 料金以外のボリュームを維持し、完全なバケットを使用するダッシュボードを構築します。
- 提案されたアラートを非ページング モードまたはシャドウ モードで実行します。
- 持続期間ルール、最小ボリューム、および応答リンクを追加します。
- 新しいコンシューマが合意された検証期間を経過した後にのみ、古いコンシューマを廃止します。
ダッシュボードのカットオーバーは元に戻すことができます。古いデータの削除、診断ログの削除、または確立されたアラートの無効化はできない場合があります。これらは、独自の保持とロールバックのレビューを伴う個別の決定として保持してください。
8. 明示的なロールバック パスを保持する
カットオーバーの前に、次のことを記録します。
- 以前の検索、ダッシュボード、およびアラートの識別子。
- イベントを紹介したリリース。
- イベントとスキーマのバージョン。
- 新しい保存されたクエリの識別子。
- コンシューマを以前の定義に戻すための基準。
- 二重書き込みと追加の検証を終了できる日付。
新しいイベントで必須フィールドが失われたり、遅延したり、意味が変わったりした場合は、プロデューサーの診断を続行しながら、影響を受けるコンシューマーを復元します。ロールバックでは、同じインシデント中に新しいインストルメンテーションを削除する必要はありません。
この移行でカバーされないもの
このワークフローは、ネイティブ ホスト メトリック、データベース サーバー統計、分散トレース、または無制限の診断ログを置き換えるものではありません。たとえば、Telemetry のデータベース パターンは、安全なクエリ フィンガープリント、プール待機、トランザクション結果、ロック監視、レプリケーション信号、移行結果など、アプリケーションによって発行されたデータベース テレメトリを分析します。彼らは、 pg_stat_* コレクター。
各シグナルは、答えられる質問に対して使用し、運用上の価値がデータとカーディナリティのコストを正当化する場合にのみ、安定した識別子を使用してシステムを接続します。
実質的な最初の移行
API サービスの場合は、次から始めます API リクエストのスループット, API ルート別のエラー率、そして API 429 回復。彼らは小規模なイベント コントラクトを共有しながら、トラフィック、信頼性、再試行に関するさまざまな粒度の質問に答えます。データベースを利用したワークフローの場合は、次を追加します N+1 クエリの検出 リクエストとクエリのフィンガープリントを安全に関連付けることができるようになって初めて可能になります。
1 つのワークフローが安定したら、元のイベントを何の疑問もなく拡張するのではなく、次の決定のために移行チェックリストを再利用します。