bigquery-troubleshooting

BigQuery のトラブルシューティング

アトリビューション

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、使用状況のアトリビューションを必ずお読みください。ターミナルで直接実行するコマンド（生成されたスクリプト、Terraform、ユーザーコード内では実行しないでください）では、gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:bigquery-troubleshooting)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:bigquery-troubleshooting) を追加してください。

前提条件と環境設定

診断クエリを実行したり、インシデントのテレメトリーを調査したりする前に、次の手順を行ってください。

1. Google Cloud SDK： Google Cloud SDK がインストールされ、設定されていることを確認します。

2. プロジェクトの選択：アクティブな Google Cloud プロジェクトを設定します。

   gcloud config set project {project_id}
   

3. API の有効化：BigQuery API と Cloud Monitoring API が有効になっていることを確認します。

   gcloud services enable bigquery.googleapis.com monitoring.googleapis.com
   

4. 認証：環境を認証します。

   • CLI コマンド（bq show -j）：gcloud auth login
   • SDK と自動診断スクリプト： gcloud auth application-default login
   • サービスアカウント：GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json" を設定します。

5. 請求と IAM ロール：

   • 有効な Google Cloud Billing アカウントが {project_id} に関連付けられていることを確認します。
   • 適切な IAM ロールが設定されていることを確認します。
     • roles/bigquery.jobUser：診断クエリの実行。
     • roles/bigquery.resourceViewer または roles/bigquery.admin： 予約とジョブ実行のテレメトリーの調査。
     • roles/monitoring.viewer：Cloud Monitoring のメトリクス。
     • roles/billing.viewer：Cloud Billing のレポートとコストのアトリビューション。

6. 関連スキルのインストール： このスキルは、3 本柱の運用スイート（bigquery-observability、bigquery-optimization、bigquery-troubleshooting）の一部です。関連スキルが環境にインストールされていない場合は、スイート全体をインストールしてください。

   npx skills add google/skills --skill bigquery-observability --skill bigquery-optimization --skill bigquery-troubleshooting
   

   （bigquery-observability がインストールされていない場合は、以下のリファレンスセクションに直接記載されている、単独で使用できる基本の数式とクエリテンプレートを使用してください。）

ワークフロー

1. 範囲と症状の特定： 主な症状、対象となる project_id、region、reservation_id、または job_id、およびドメイン （パフォーマンス、コンピューティングコスト、ストレージコスト）を特定します。リクエストが インシデント診断の範囲外である場合、または関連する別のドメインについて尋ねている場合は、以下の ルーティングの境界 に従います。
2. テレメトリーツールの選択： bigquery-observability のツール選択ガイダンス（bigquery_observability）に従って、適切なテレメトリーインターフェース （単一ジョブのステージボトルネックには REST API bq show --location={location} -j {project_id}:{job_id}、システム全体の要因には INFORMATION_SCHEMA）を選択します。診断ワークフロー、症状と原因の対応関係、主要な テーブル／フィールド、CLI トリアージコマンド、改善策は、このスキルで定義されています。 あらかじめ作成された SQL クエリテンプレートと完全なスキーマ辞書については、 bigquery-observability を参照してください。
3. 自由形式のトリアージ（ステージ 1 のベースラインスキャンと対話による確認）： ユーザーの問い合わせが自由形式または曖昧な場合（例：「今日は BigQuery が遅いのはなぜですか？」、または 「請求額が急増したのはなぜですか？」）は、詳細な診断に進む前に、対象ドメインを特定するため、範囲を限定した高レベルのベースラインスキャンを実行します。
   • 範囲を限定した初期スキャン： ドメイン別リファレンスに記載された該当ドメインのリファレンスにあるベースラインスキャンのガイダンスに従います。診断テレメトリーのオーバーヘッドを最小限に抑えるため、初期クエリの範囲を厳密に限定します（例：パーティションとジョブタイプでフィルタリングした 7 日間の期間比較。コストの急増要因が不明な場合は、オンデマンドの TiB、容量のスロット時間、ストレージの GiB という 3 つの主要なベクトルをスキャンします）。
   • 対話による確認： 高レベルのベースラインの所見を事実に基づいて先に要約し、下位のサブベクトルクエリを求められていないのに一括で提示するのではなく、焦点を絞った掘り下げの選択肢を 2～3 個提案します。
4. ドメインの詳細分析と比較分析： 以下の ドメイン別リファレンスに記載された該当ドメインのリファレンスファイルで定義されている手順に沿って診断ワークフローを実行し、次に bigquery-observability の対応するクエリを、その INFORMATION_SCHEMA のベストプラクティスに従って実行します。正常時のベースラインと比較分析を行い、根本原因を特定します。

パフォーマンスのコンテキスト：「遅い」は相対的

パフォーマンスは相対的なものです。パフォーマンスのトラブルシューティングは、常に比較分析として行ってください。比較可能な過去の実行を特定して統計情報を比較し、高速なベースラインと低速な実行の間でどの要素が変化したかを切り分けます。

• 処理データ： データ量の増加、パーティション／クラスタのプルーニングの変化、データの偏り、入力レコードの増幅。
• 基盤となる定義： ビューの変更、スキーマの変更。
• システムの競合： ノイジーネイバー、容量の飽和（スロット使用率が 95% 超）、アイドルスロットの利用可能性、同時実行クエリの急増。
• 構成の変更： スロット容量／自動スケーリングの最大スロット数の変更、容量コミットメントの期限切れ、アイドルスロット設定の変更、または予約の再割り当て。

コストのコンテキスト：4段階の診断フロー

コストのトラブルシューティングでは、変動する契約料金ではなく、物理的なリソース消費量（スロット時間、課金対象 TiB、保存済み GiB）を追跡する必要があります。

1. 収集： 対象範囲を特定し、7日間の PoP（または明示的に指定された MoM／180日間）のベースライン指標を取得します。
2. 切り分け： コストの急増が、クエリ量、単一の「暴走クエリ」、BQML の 50 倍の乗数、カバーされていない PAYG ベースライン、オートスケーリングの急増、90日間のストレージタイマーのリセット、または物理的な Fail-Safe 保持による消費のいずれに起因するかを特定します。
3. 説明： 管理イベント（INFORMATION_SCHEMA.RESERVATION_CHANGES、INFORMATION_SCHEMA.CAPACITY_COMMITMENT_CHANGES_BY_PROJECT、INFORMATION_SCHEMA.SCHEMATA_OPTIONS、または実行者の user_email／query_hash）と関連付けます。
4. 修正： 実行可能な対策（パーティションフィルターの適用、クエリ上限、コミットメントの購入、Time Travel の削減など）を提示します。

ドメイン別リファレンス

パフォーマンスのトラブルシューティング

• リソース競合とパフォーマンス低下 (references/performance_resource_contention.md)：単一ジョブのステージボトルネック（slot_contention、spill_to_disk）の切り分け、同一コホートのベースライン比較（normalized_literals）、インシデント発生時間帯の特定、1秒単位での予約スロット飽和、時間枠ごとの競合比較、フリート全体のパフォーマンスのばらつき、テーブルレベルの同時実行性に関する診断ワークフローです。
• キャパシティと構成の変更 (references/performance_config_changed.md)：予約の slot_capacity と autoscale.max_slots の編集の監査、有効なキャパシティコミットメントのタイムライン追跡、予約割り当ての変更の診断、オートスケーリングの余力の飽和評価に関する診断ワークフローです。
• 実行グラフとクエリプランのトラブルシューティング (references/query_plan_execution_graph.md)：単一ジョブのステージボトルネックの調査（bq show によるポイント検索）、最も遅いステージの特定（end_ms - start_ms）、結合の肥大化（records_written >> records_read、high_cardinality_joins）の診断、シャッフルのスピル（shuffle_output_bytes_spilled）とパーティションの偏りの特定、サブステップの中間変数の区別（$1、$2）、必須のスキャンバイト数と読み取りレコード数の修正、UI の実行グラフを理解するための概念に関する診断ワークフローです。

コストのトラブルシューティング

• オンデマンドコンピューティングのコスト (references/cost_compute_ondemand.md)： パーティション分割されていないテーブルの暴走スキャン（「暴走クエリ」）、非表示の行レベルセキュリティ（RLS）によるマスキングの抜け、BigQuery ML（BQML）のモデル学習レートの 50 倍の乗数、ユーザー／サービスアカウントのクエリ割り当てに関する診断ワークフローです。
• キャパシティ（エディション）のコンピューティングコスト (references/cost_compute_capacity.md)：ベースラインスロットがコミットメントを上回ることによる未カバー分のペナルティ、予約ベースラインの削減によるオートスケーリング急増（RESERVATION_BASELINE_CHANGED）、バッチ cron の急増によるオートスケーラーの過剰な動作、サーバーレス Apache Spark のストアドプロシージャのスロット時間に関する診断ワークフローです。
• ストレージの使用量と保持コスト (references/cost_storage.md)： 過去のパーティションで90日間のタイマーがリセットされる問題（DML の落とし穴）、パーティション分割されていないテーブルのアクティブデータに関する落とし穴、日次上書きによる物理的な Time Travel と Fail-Safe の入れ替わり、削除されたテーブルの Fail-Safe による消費期間に関する診断ワークフローです。

ルーティングの境界

トラブルシューティング中にユーザーのリクエストがインシデント診断の範囲外に移った場合は、対応する引き継ぎを実行します。

• SQL クエリの最適化： ユーザーが SQL クエリの最適化を求めた場合（例：結合の書き換えや SELECT * の削除）、bigquery-optimization に引き継ぎます。
• 生のテレメトリとスキーマの取得： アクティブなパフォーマンスの低下やインシデントがない状況で、単独の INFORMATION_SCHEMA クエリをユーザーが求めた場合（例：一般的なテレメトリクエリ）、bigquery-observability に引き継ぎます。
• 先を見越した容量とストレージの計画： 将来の予約容量の見積もり、コミットメントの購入、またはストレージの課金モデルの評価をユーザーが求めた場合、bigquery-optimization に引き継ぎます。