可観測性とイベント分析のための SQL

SQL 可観測性とは、構造化イベントからの運用上および製品上の質問に、目に見えるレビュー可能なクエリで答えることを意味します。無制限のメッセージを検索し、すべてのプロデューサーが同じ方法でフォーマットすることを期待する代わりに、次のような便利なフィールドを定義します。 route, status_code, latency_ms, account_id, release、そして outcome、それらの列を直接集計します。

これによって、テキスト ログ、メトリクス、またはトレースが時代遅れになるわけではありません。これにより、ソフトウェア チームは、信頼性、製品の動作、コスト、顧客への影響を横断する質問に対するリレーショナル分析レイヤーを得ることができます。

ショートバージョン

便利な SQL 可観測性ワークフローは 5 つの部分で構成されます。

1. 意味のある操作については、1 つの端末イベントを記録します。
2. ディメンション、メジャー、相関識別子の小規模で安定したセットを保持します。
3. 信頼できるタイムスタンプを持つ型付きテーブルにイベントを保存します。
4. 読み取り専用の SQL を使用して、行のフィルタリング、グループ化、結合、比較を行います。
5. 結果を、意思決定に関連付けられたチャート、ダッシュボード、アラート、またはスケジュールされたレポートに変換します。

Telemetry はその形状に従います。JSON イベントを送信し、推論されたテーブルを検査し、DataFusion SQL を実行し、結果をパブリッシュします。の SQL レシピ ライブラリ 型指定されたコントラクト、合成入力、期待される出力、チャート、エッジ ケースを使用して完全なパスを検査可能にします。

SQL が可観測性に役立つ理由

運用上の質問は、ログとして始まった場合でも、多くの場合、リレーショナルなものになります。

• リリース後に遅くなったルートはどれですか 2026.07.28?
• どのアカウントが支払いインシデントの影響を受けましたか?
• 再試行により Webhook 配信が回復しましたか、それとも負荷が増加しただけですか?
• 受け入れられた出力あたりのコストが最も高い AI 機能はどれですか?
• 可視性タイムアウト後に繰り返し失敗するキュー ジョブはどれですか?

これらの質問には、グループ化、条件付き集計、結合、安定したアイデンティティ、および明示的な時間枠が必要です。 SQL は、それらの選択肢を可視化します。レビュー担当者は、レートで行または一意のリクエストが使用されているかどうか、最新の部分バケットが含まれているかどうか、内部結合によって一致しないデータがサイレントに削除されたかどうかを確認できます。

SQL もスキルとして移植可能です。関数名とタイムスタンプ構文はエンジンによって異なりますが、 SELECT, WHERE, GROUP BY, CASE、結合、およびウィンドウ関数は、耐久性のあるメンタル モデルを形成します。

操作をメッセージではなくイベントとしてモデル化する

API リクエスト、チェックアウト試行、バックグラウンド ジョブ、Webhook 配信、モデル応答などの意味のある操作から始めます。結果がわかっている場合は、ターミナル イベントを 1 つ発行します。

{
  "event_name": "api_request_completed",
  "request_id": "req_01J...",
  "account_id": "acct_42",
  "route": "/v1/orders/:id",
  "method": "GET",
  "status_code": 503,
  "latency_ms": 842,
  "release": "2026.07.28",
  "region": "us-west",
  "outcome": "error",
  "error_type": "upstream_timeout"
}

これは幅広いイベントです。一連の脆弱なメッセージ解析を必要とせずに、操作を説明するために必要なコンテキストが保持されます。次のようなフィールドには、境界付きカテゴリを使用します。 route, error_type、そして outcome。デフォルトでは、シークレット、生のリクエスト本文、プロンプト テキスト、およびプライベートな顧客コンテンツを外部に残します。

Telemetry が追加 timestamp_utc 取り込み中。ビジネス タイムスタンプも送信する場合は、その意味に応じた名前を付けます (例: scheduled_at, completed_at、または invoice_period_start—第二の曖昧さを作り出す代わりに timestamp.

寸法、メジャー、およびアイデンティティ

実際の契約では、次の 3 種類のフィールドが分離されます。

アイデンティティを慎重に選択してください。行のカウントは、1 つの行がカウントする単位と等しい場合にのみ正しく行われます。再試行テレメトリ、複数ステップのワークフロー、および定期的なスナップショットでは、通常、1 つの論理操作に対して複数の行が生成されます。

スキーマ設計の詳細については、次を使用してください。 イベントスキーマの設計, 相関ID、そして 高カーディナリティのフィールド.

5 つの SQL パターンで多くの調査をカバー

1. 決定ウィンドウにフィルターをかける

SELECT *
FROM api_request_completed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
  AND route = '/v1/orders/:id'
ORDER BY timestamp_utc DESC
LIMIT 200;

生の行から始めます。集計を構築する前に、単位、NULL 値の許容性、ルートの正規化、および結果の値を確認してください。

2. 明示的な分母を使用してレートを計算する

SELECT
  route,
  COUNT(*) AS requests,
  SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END) AS errors,
  ROUND(
    100.0 * SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END)
      / NULLIF(COUNT(*), 0),
    2
  ) AS error_rate_pct
FROM api_request_completed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY route
ORDER BY error_rate_pct DESC, requests DESC;

分母はすべて一致するリクエスト行です。プロデューサーが再試行を新しい行として出力する場合、ダッシュボードに試行または固有の論理リクエストのどちらを表示するかを決定します。

3. リリース境界を比較する

SELECT
  release,
  COUNT(*) AS requests,
  approx_percentile_cont(latency_ms, 0.95) AS p95_latency_ms,
  ROUND(
    100.0 * SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END)
      / NULLIF(COUNT(*), 0),
    2
  ) AS error_rate_pct
FROM api_request_completed
WHERE timestamp_utc >= now() - INTERVAL '7 days'
GROUP BY release
ORDER BY release;

リリースの比較にはトラフィック共有とロールアウト時間が必要です。少量のカナリアを完全な運用展開のように解釈すべきではありません。

4. 技術的な影響を安定したアカウントに結合する

SELECT
  r.account_id,
  a.plan,
  COUNT(*) AS failed_requests
FROM api_request_completed r
LEFT JOIN account_dimension a
  ON r.account_id = a.account_id
WHERE r.timestamp_utc >= now() - INTERVAL '2 hours'
  AND r.status_code >= 500
GROUP BY r.account_id, a.plan
ORDER BY failed_requests DESC;

左結合では、エンリッチメントが遅れた場合でも、影響を受けるアカウントが保持されます。ディメンションの鮮度およびキーごとに 1 行のルールを明示的に保ちます。

5. 相関のあるタイムラインを再構築する

使用する request_id, job_id、またはイベントを時間順に結合または結合するための別のワークフロー識別子。タイムラインには試行、再試行、依存関係の結果、最終状態が表示されるため、インシデント発生時には単一の集計よりも役立つことがよくあります。

の 接続済み SQL ラボ 6 つの合成テーブルと、結合、ファネル、AI コスト、信頼性、リカバリに関するガイド付きレッスンを提供します。完全にブラウザ内で実行されます。

ビジュアライゼーションと質問を一致させる

クエリの結果によってビジュアルが決定される必要があり、その逆ではありません。

結果表は常にグラフの横に用意しておいてください。ツールチップと軸により、基になる行で明らかな丸め、NULL、および小さな分母が非表示になることがあります。

すべてのパブリック Telemetry レシピには、クロール可能な結果テーブル、ビジュアル プレビュー、JSON および CSV フィクスチャ、および静的チャートが含まれています。から始める API ルート別のエラー率, フィンガープリントによるデータベースクエリが遅い、または 機能ごとの LLM コスト.

SQL が他のテレメトリを補完する必要がある場合

メトリクスを使用して、安価で継続的な集約シグナルと、厳密に制御されたラベル付きのアラートを作成します。トレースを使用して、リクエストの分散クリティカル パスを理解します。正確な診断メッセージが重要な場合、または形状が事前に不明な場合は、テキスト ログを使用します。チームが柔軟なディメンション、ビジネス コンテキスト、結合、または監査可能な計算を必要とする場合は、構造化イベント テーブルを使用します。

システムは相関 ID を共有できます。 SQL の結果により、影響を受けるリリースとアカウント コホートを特定できます。トレースにより、代表的な遅いリクエストを説明できます。テキスト ログには、正確な依存関係エラーが表示されます。

サポートする決定なしに、すべてのトレース スパンまたはログ行を 2 番目のストアにコピーしないでください。重複した収集によりコストが発生し、定義の競合が発生します。

安全な導入シーケンス

不確実なワークフローを 1 つ選択し、データが裏付ける必要がある決定を書き留めます。ターミナル イベントを定義し、シャドウ モードでインストルメントし、イベント数を既存のソースと比較し、生の行を検査します。その後でのみ、集計を公開します。

メッセージ検索から段階的に切り替えるには、次の手順を実行します。 アドホック ログから構造化イベントおよび SQL への移行。現在のチームが LogQL、KQL、または SPL を使用している場合、 クエリ言語移行ガイド 言語が互換性があるかのように装うことなく、一般的なパターンをマップします。

チェックリストを確認する

クエリが動作可能になる前に、次のことを行ってください。

• 列粒度と分母を確認します。
• ヌルおよび遅延到着の動作を文書化します。
• 時間範囲を制限します。
• 単位とタイムスタンプのタイムゾーンを検証します。
• エンリッチメントに遅れが生じる可能性がある場合は、一致しない行を保持します。
• 再試行と重複をどのようにカウントするかを決定します。
• 不完全なタイムバケットを除外または注釈を付ける。
• 履歴データまたは合成データのしきい値をテストします。
• チャートから SQL とイベント コントラクトへのリンクを保持します。

の SQL テスト方法 Telemetry の自動チェックが何を証明するのか、そして依然としてビジネス上の判断が必要なものは何かを説明します。