planetscale-query-insights-and-tags

クエリの分析情報とタグ

目的

PlanetScale Insights を使用してクエリの動作を把握し、将来の診断や Traffic Control を可能にする、SQLCommenter 互換のタグを提案します。承認なしにデータベースの設定やリポジトリのコードを変更しないでください。

調査する内容

クエリの動作

選択したデータベースとブランチについて、以下を調査します。

• 合計時間が長いクエリ。
• 1 回の実行あたりの時間が長いクエリ。
• 読み取り行数が多いクエリ。
• 実行回数が多いクエリ。
• Postgres の場合、CPU 使用率が高いクエリ（Insights API で sort=cpuTime または sort=percentCpuTime を指定します）。
• エラーが発生しているクエリ。
• 注目すべきクエリと、現在発生している異常。
• 最近のデプロイの影響を受けたクエリパターン。
• スキーマの推奨事項に関連付けられたクエリパターン。
• シャーディングされた Vitess データベースの場合、各クエリパターンの vindex 使用状況：関連する vindex を使用しているトラフィックの割合と、時間経過に伴う vindex 使用率の推移。API ではパターンごとの index_usages と routing_index_usages が公開されています。推移はダッシュボードの Vindexes タブで確認するか、API のウィンドウを比較して取得します。関連する vindex の使用率が取得できない、または低下している場合は、インデックス作成やルーティングの調査のきっかけとして扱い、新しいインデックスが必要だという証拠とはみなさないでください。

Insights API の概要

Query Insights はパブリック API です。organizations/{org}/databases/{db}/branches/{branch} 配下の読み取り専用 GET エンドポイントで、read_databases/read_database 権限を持つサービス トークンまたは OAuth トークンで認証します。

• /insights — 指定したウィンドウ内のクエリパターンごとの集計統計です。from/to（ISO 8601）または period（例：1h、24h）でウィンドウを設定します。q で SQL パターンを検索し、sort と dir でサーバー側の並べ替えを指定します。並べ替えキーには count、errorCount、rowsRead、totalTime、cpuTime、ioTime、percentTime、percentCpuTime、p50Latency、p99Latency、maxLatency、egressBytes、および trafficControlWarnings/trafficControlThrottled 系のキーが含まれます。tablet_type（primary、replica、rdonly）と type（SELECT、INSERT、UPDATE、DELETE）で絞り込み、fields でレスポンスを簡潔にし、page/per_page でページネーションを行います。
• /insights/{fingerprint} — パターンについて収集された個々の実行データ（タイムスタンプ、実行時間、行数、ユーザー名、クライアントアドレス、エラーメッセージ）です。生クエリの収集設定に関係なく利用できます。生クエリ収集を有効にすると、これらの記録にリテラルのパラメーター値が追加されます。 /insights/{fingerprint}/summary は単一パターンの集計を返し、/insights/queries/{id} は 1 件の実行データを取得します。
• /insights/errors — エラーフィンガープリントと、その件数およびメッセージです（q でエラーメッセージを検索し、count、lastRun、totalTime、timePerQuery で並べ替えます）。/insights/errors/{fingerprint} は、1 つのエラーフィンガープリントに該当する失敗した実行を一覧表示します。
• /insights/anomalies と /insights/anomalies/{id} — 異常の発生ウィンドウと、その異常とともに変動したパターンを特定するクエリごとの相関係数です。
• /insights/tags — 観測された値を持つタグキーです（values_limit、literal_values_only、および fingerprint/keyspace フィルターを使用します）。単一のキーには /insights/tags/{tag} を使用します。/insights/tags/summaries は tags パラメーターを使って、完全な統計スキーマを 1 つ以上のタグキーごとにグループ化します。クライアント側で集計せずに、ルート、ジョブ、機能別に負荷を特定するために使用します。
• /insights/{fingerprint}/traffic/budgets — フィンガープリントに影響する Traffic Control の予算とルールです（Postgres）。

集計値は指定したウィンドウを対象とします。時間のフィールド名は sum_total_duration_millis のようになっており、ウィンドウに対する割合を明示する sum_total_duration_percent フィールドもあります。指定したウィンドウについて、合計値と割合のどちらも信頼できます。

レスポンススキーマはエンジン間で共通ですが、一部のフィールドはエンジン固有です。CPU/IO 時間とブロックキャッシュ統計（sum_cpu_duration_millis、blocks_read、block_cache_hit_ratio、…）は Postgres で取得されます。シャードクエリ、キースペース、tablet_type、ルーティングインデックス（vindex）の使用状況は Vitess で取得されます。

タグのカバレッジ

負荷の高いクエリや異常なクエリごとに、次の点を確認します。

• タグが付いていますか？
• どのサービスがクエリを生成しましたか？
• どのルート、ジョブ、コントローラー、アクションがクエリを生成しましたか？
• どのデプロイ SHA がクエリを生成しましたか？
• タグのカーディナリティは安全ですか？
• フレームワークや言語が異なっても、タグに一貫性がありますか？
• タグ API を使って、これらの質問に回答します。/insights/tags では、存在するキーと値を確認できます。また、/insights/tags/summaries?tags=... では、タグ値ごとの負荷を確認できます。Vitess ダッシュボードでは、クエリテーブルを tag:key:value で絞り込み、クエリの詳細を開くと個々の実行に付いたタグを確認できます。組み込みのクエリメタデータと SQLCommenter タグは、どちらも有効なアトリビューション情報源です。

生クエリの収集

生クエリ／完全なクエリの収集が有効かどうかを確認します。Postgres では、有効状態はクラスターパラメーター pginsights.raw_queries で決まります（ブランチごと、ダッシュボードの「Extensions」タブ、デフォルトは false）。データベース API オブジェクトの insights_raw_queries フィールドは別の情報源です。この2つの値が異なる場合は、クラスターパラメーターを有効状態として報告し、その違いを不整合として説明しないでください。Vitess にはクラスターパラメーターがありません。データベース API の insights_raw_queries フィールドが有効状態を示します。

リスクの度合いではなく、機能の状態として報告します。生クエリの収集では、実行ごとのリテラルなパラメーター値が記録されます。パターンレベルの Insights データでは、この情報は得られません。特定のパターンのどの呼び出しが異常なのかを特定する仕組みです。実行レベルのレコードは、生クエリの収集が有効かどうかにかかわらず、/insights/{fingerprint} から取得できます。生クエリの収集を有効にすると、これらのレコードにリテラルなパラメーター値が追加されます。

無効になっている場合、これは機能上のギャップとして報告します。この評価で、パターンレベルのデータでは不十分なクエリパターン（フィンガープリント内の説明できないレイテンシーのばらつき、テナントやパラメーターによる動作の違い）を特定し、生クエリの収集によって解決できることを明記します。運用上の特性は事実として一度だけ述べます。リテラル値がオブザーバビリティパイプラインから見えるようになります。顧客のデータ取り扱い要件に制約がある場合、対象を限定した有効化（インシデント発生中の期間、保持期間の定義）と、収集を無効のままにすることは、どちらも妥当な対応です。どちらか一方を既定の判断とせず、根拠を記録してください。

タグと生クエリの収集は相互に補完する手段です。タグはパターンをコードパスにひも付け、生クエリの収集は特定の呼び出しを特定します。評価では両方を検討してください。

SQLCommenter のタグスキーマ

次の基本タグセットを推奨します。

• application：安定したアプリ名。
• service：サービス名またはプロセス名。
• environment：production、staging、development。
• route：正規化されたルートテンプレート。たとえば、/accounts/:id/orders のような形式です。/accounts/123/orders のような形式は使いません。
• controller：該当する場合は、フレームワークのコントローラー名。
• action：該当する場合は、フレームワークのアクション名。
• job：バックグラウンドジョブのクラス名またはワーカー名。
• queue：バックグラウンドキュー。
• feature：export、report、search、billing、checkout など、トラフィックの分類に使う範囲が限定された機能名。
• release_sha：短縮した git SHA またはデプロイ識別子。
• source：app、worker、script、agent、mcp、bi、integration。
• tenant_tier：範囲が限定されている場合に限り、free、pro、enterprise、internal。

次のタグは、デフォルトでは推奨しません。

• user_id
• request_id
• tenant_id
• email
• session_id
• 生の URL
• 範囲が限定されていない GraphQL 操作テキスト
• アクセストークン
• シークレット

顧客がテナントレベルの分離を必要としている場合は、まずテナントのティア、セル、シャード、顧客クラスなど、範囲が限定された抽象化を推奨します。テナント ID を許容できるのは、カーディナリティとプライバシーを確認したうえで、明示的な承認を得た場合に限ります。

カーディナリティのルール

次のいずれかに該当する場合、そのタグを安全ではないと判断します。

• 値の範囲が限定されていません。
• 値に ID、UUID、メールアドレス、スラッグ、生のパスが含まれています。
• 同じクエリパターンで、多数の一意なタグの組み合わせが出力されます。
• Insights または Traffic Control の集計がノイズの多いものになります。

アプリケーションの境界で正規化することを推奨します。

分析結果

クエリのパターンごとに、以下を出力します。

• フィンガープリントまたは正規化されたクエリ。
• 現在のメトリクス。
• 現在のタグ。
• 不足しているタグ。
• アプリケーションコード内の発生元として考えられる箇所。
• スキーマの推奨候補かどうか。
• Traffic Control の候補かどうか。
• アプリケーション最適化の候補かどうか。

推奨の分類

タグを追加する

クエリの発生元の特定が不十分な場合は、SQLCommenter のインストルメンテーションを推奨します。

タグの正規化を改善する

カーディナリティの高いタグを、値の範囲を限定したタグに置き換えることを推奨します。

Traffic Control の警告予算を追加する

Postgres のみを対象に、コストは高いものの重要なルート、ジョブ、分析、エクスポート、サードパーティ統合について、warn モードの予算を推奨します。

スキーマ推奨のワークフローを追加する

Vitess では、未対応のスキーマ推奨をブランチやデプロイリクエストでの作業に移行することを推奨します。Postgres では、本番以外のブランチに対するレビュー済みのマイグレーションに移行することを推奨します。

コードパスを修正する

コストの高いクエリが N+1、ページネーションの欠如、意図しない Eager Load、上限のないエクスポート、広範囲な検索、ポーリングに起因する場合は、リポジトリへの PR を推奨します。

安全に関するルール

以下は行わないでください。

• 生のクエリ収集を有効にする。
• コードにタグを追加する。
• Traffic Control の予算を変更する。
• スキーマ推奨を適用する。
• コストの高いクエリに対して、本番環境で EXPLAIN ANALYZE を実行する。

明示的な承認がない限り、これらの操作は行わないでください。

出力

以下を返してください。

• クエリリスクの表。
• タグのカバレッジの表。
• 不適切なタグ／カーディナリティの高いタグの表。
• このアプリケーション向けに推奨するタグスキーマ。
• Traffic Control の候補スライス。
• スキーマおよびコード変更の候補。
• 承認が必要な変更案。

最後に、次の文を記載してください。

「Insights、タグ、リポジトリ、Traffic Control への変更は適用されていません。」