bigquery-observability

BigQuery のオブザーバビリティ

帰属情報

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

ツールの選択

ツール	主なユースケース	強みと機能	避けるべき場合／制限事項
INFORMATION_SCHEMA (I_S)	履歴分析、コホート比較（normalized_literals）、高速／低速な時間帯の特定、予約／プロジェクトのタイムライン、複数ジョブの集計、コスト／課金の追跡。	JOBS、JOBS_TIMELINE、RESERVATIONS にわたる柔軟な SQL クエリに対応し、カスタムの時間枠やグループ化をサポートします。	高頻度のリアルタイムポーリングや単一ジョブのピンポイント検索には適しません（スロットを消費し、実行に数秒かかる場合があります）。
REST API（jobs.api／reservation.api）	単一ジョブのピンポイント検索、リアルタイムのステージボトルネック診断、自動化されたパイプラインのステータス確認、予約／容量コミットメント設定の確認（reservations.get、reservations.list）。	SQL のオーバーヘッドがなく、REST／CLI による高速なピンポイント検索（bq show -j、bq show --reservation）が可能で、performanceInsights、queryPlan、構造メタデータに即座にアクセスできます。	数千件のジョブにまたがる集計分析、プロジェクト横断の履歴比較、システムタイムラインの集計には適しません。
Cloud Monitoring（Metrics Explorer／Charts）	リアルタイムのアラート、全体のダッシュボード、継続的なスロット使用率の追跡、概要レベルの SLA／SLO モニタリング。	スロット使用率、クエリスループット、PENDING キューの深さ、実行レイテンシーの標準搭載チャートを利用でき、クエリを実行せずに低レイテンシーのアラートを設定できます。	SQL レベルのデバッグ、個々のクエリテキストの確認、ステージレベルの実行詳細には適しません。

前提条件と環境設定

テレメトリーを取得したり、オブザーバビリティクエリを実行したりする前に、 Google Cloud 環境とプロジェクトが設定されていることを確認してください。

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 コマンド：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 のメトリクス。

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

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

ワークフロー

1. 単一ジョブのポイントルックアップ（SQL オーバーヘッドなし）： 単一ジョブの遅延や調査では、常にまず REST API または CLI（bq show -j）を優先してください。SQL のオーバーヘッドなしで、内部ステージのボトルネック（performanceInsights、queryPlan、シャッフルのスピル）を素早くポイントルックアップできます。

   bq show --location={location} -j {project_id}:{job_id}
   

2. 診断の移行ロジック： ジョブレベルの問題（明確な内部ボトルネックがないなど）が見つからない場合は、調査をシステムレベルの INFORMATION_SCHEMA クエリ（JOBS_TIMELINE や RESERVATIONS_TIMELINE など）に移行し、スロットの競合、キュー待ち時間、ノイジーネイバーといった、より広範な問題を確認します。

INFORMATION_SCHEMA クエリを記述する際のベストプラクティス

BigQuery の INFORMATION_SCHEMA ビューに対するクエリには、リージョン修飾子またはデータセット修飾子を指定する必要があります。プロジェクト修飾子を前に付けることもできます。

修飾構文とスコープの一致

1. リージョン修飾構文：

   `{project_id}`.`region-{region}`.INFORMATION_SCHEMA.{view}
   

   例： `my-project`.`region-us`.INFORMATION_SCHEMA.JOBS

   適用対象： リージョンのテレメトリビュー（JOBS*、JOBS_TIMELINE*、RESERVATIONS*、CAPACITY_COMMITMENTS*、TABLE_STORAGE*、STREAMING_TIMELINE*）。クライアントのクエリ実行ロケーションは、region-{region} 修飾子と一致している必要があります（一致しない場合、BigQuery は次のエラーを返します：Not found: Table {project_id}:region-{region}.INFORMATION_SCHEMA.{view} was not found in location {location}）。

2. データセット修飾構文：

   `{project_id}`.`{dataset_id}`.INFORMATION_SCHEMA.{view}
   

   例： `my-project`.`analytics`.INFORMATION_SCHEMA.TABLES

   適用対象： データセットスコープのビュー（PARTITIONS、SEARCH_INDEXES*、ROW_ACCESS_POLICIES）。データセットのビューには region- を使用しないでください。

3. デュアルスコープのビュー： TABLES、COLUMNS、COLUMN_FIELD_PATHS、VIEWS、ROUTINES、VECTOR_INDEXES などのビューは、データセット全体の分析かリージョン全体の分析かに応じて、{dataset_id} または region-{region} で修飾できます。

4. プロジェクト修飾子（{project_id}）： 省略可能です。省略すると、クエリは実行中のプロジェクトをデフォルトで使用します。組織レベルのビュー（例：JOBS_BY_ORGANIZATION）にプロジェクト修飾子を指定しても、結果には影響しません。

最小権限の原則とスコープの選択

INFORMATION_SCHEMA クエリを作成する際は、分析上のニーズを満たす範囲で、必要な IAM 権限が最も少ないスコープとビューのバリアントを必ず選択してください。

1. プロジェクトレベルよりユーザーレベル（_BY_USER）： 現在のユーザーが実行したクエリやセッションを診断する場合は、_BY_USER（例：JOBS_BY_USER、SESSIONS_BY_USER）を使用します。これに必要なのは bigquery.jobs.list（roles/bigquery.user または roles/bigquery.jobUser を通じて付与）だけであり、bigquery.jobs.listAll や roles/bigquery.admin は不要です。
2. リージョン／プロジェクトレベルよりデータセットレベル： 特定のデータセットのテーブルメタデータ、列、ビューをクエリする場合、プロジェクトレベルのメタデータへのアクセスが制限されているときは、region-{region} ではなく {dataset_id} を指定します。データセットスコープのクエリに必要な権限は、対象のデータセットに対するものだけです。
3. 組織／フォルダレベルよりプロジェクトレベル（_BY_PROJECT）： _BY_FOLDER または _BY_ORGANIZATION にスコープを広げる前に、必ずプロジェクトスコープのビューから開始します。フォルダや組織を対象とするクエリには、広範なフォルダ／組織の IAM 権限（Org／Folder ノードでの bigquery.jobs.listAll または bigquery.tables.list）が必要です。
4. データロールよりメタデータロール： テーブルやストレージの調査では、データの読み取り権限（bigquery.tables.getData）が不要な場合、roles/bigquery.dataViewer や roles/bigquery.dataOwner よりも roles/bigquery.metadataViewer（bigquery.tables.get と bigquery.tables.list を提供）を優先します。（注：INFORMATION_SCHEMA.PARTITIONS のみ、例外として bigquery.tables.getData が必要です。）

実行時のガードレールとクエリの不変条件

• パーティションと時間によるフィルタリングを必須とする： メタデータテーブル全体のスキャンを避けるため、必ず creation_time（例：creation_time >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 3 DAY)）または usage_date でフィルタリングします。
• スクリプトラッパーの除外： コンピューティング費用を集計する際は、親スクリプトと子ジョブの二重計上を避けるため、AND (statement_type != 'SCRIPT' OR statement_type IS NULL) を追加します。
• 列の絞り込み： INFORMATION_SCHEMA に対して SELECT * を使用しないでください。必要な列のみを指定します。
• ドライランとコストの見積もり： 複雑なクエリ、複数ビューの結合、大規模なスキャンを実行する前に、ドライラン（bq query --dry_run --use_legacy_sql=false "{query}" または API の dryRun=true）を使用して、構文を検証し、totalBytesProcessed をコストなしで見積もります。
• リージョンスコープが空の場合（0 行）： 実行ロケーションが修飾子と一致していても、そのリージョンにプロジェクトのデータセットやジョブがなければ、クエリは成功し、0 行を返します。0 行だからといって使用量もゼロだと決めつけず、対象データセットのロケーションを必ず確認してください。
• リージョンスコープは階層的ではない： リージョン修飾子に階層関係はありません。マルチリージョンは単一リージョンを包含しません（例：region-us が返すのはマルチリージョン US のメタデータのみであり、region-us-central1 などの単一リージョンは含まれません）。
• SQL でのマルチリージョン集計は不可： リージョン修飾子を使用して、単一のクエリ内でリージョンをまたいで結合することはできません（例：region-us を region-eu と結合することはできません）。
• キャッシュされない実行と最小スキャンサイズ： INFORMATION_SCHEMA クエリの結果はキャッシュされません。オンデマンドクエリでは、実行ごとに最低 10 MB のデータ処理料金が発生します。

ドメインのリファレンスと SQL クエリ

テレメトリクエリガイド

• オンデマンドコンピューティング：課金対象バイト数 （references/compute_ondemand_billable.md）：信頼できる Golden CTE （bytes_billed_cte）、タイムゾーンに合わせた課金日抽出（PST8PDT）、 BQML CREATE_MODEL の 50 倍乗数ルール、スクリプトラッパーの重複排除、 行レベルセキュリティ（RLS）のマスキング確認について説明します。
• 容量コンピューティング：課金対象スロット数とコミットメント （references/compute_capacity_billable.md）：1 年／3 年コミットメント、 カバーされていないベースライン PAYG スロット、動的オートスケーリング時間にわたる 課金対象容量時間を監査するためのクエリテンプレートです。
• ストレージのフットプリントと使用状況（保存バイト数） （references/storage_footprints.md）：ストレージスナップショットクエリ、圧縮率の 計算、Time Travel／Fail-Safe の変動、日次平均 GiB の時間積分、 課金モデルの評価、検索インデックスの網羅状況について説明します。

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

• ジョブパフォーマンスクエリ（references/job_performance_queries.md）： 個々のジョブと全体のジョブパフォーマンスの評価、ステージの ボトルネックフラグ、正規化されたリテラルを使った比較可能なジョブ （query_info.query_hashes.normalized_literals）、BI Engine の高速化、 メタデータキャッシュ（cmeta）による高速化、検索インデックスの使用状況、 マテリアライズドビューの書き換えの使用状況、実行時間の分散における外れ値を 分析するクエリです。
• リソース競合クエリ （references/resource_contention_queries.md）：スロット競合、キューの レイテンシー、分単位の同時実行数／キューの推移、1 秒単位の予約スロットの 飽和状態を診断するクエリです。
• 容量と構成クエリ （references/capacity_and_configuration_queries.md）：秒単位のベースライン／最大 容量上限、オートスケーリングの飽和状況の推移を評価し、構成変更を監査するための クエリです（RESERVATION_CHANGES_BY_PROJECT、ASSIGNMENT_CHANGES_BY_PROJECT）。

スキーマ辞書（列の定義と単位）

• コンピューティングと容量のスキーマ辞書（references/schema_compute.md）： コンピューティング、ジョブ、セッション、予約、容量コミットメント、 割り当てに関するすべてのビュー（JOBS*、JOBS_TIMELINE*、SESSIONS_BY_USER、 SESSIONS_BY_PROJECT、RESERVATIONS*、RESERVATION_CHANGES*、 RESERVATIONS_TIMELINE*、CAPACITY_COMMITMENTS*、 CAPACITY_COMMITMENT_CHANGES_BY_PROJECT、ASSIGNMENTS*、 ASSIGNMENT_CHANGES_BY_PROJECT）について、列の完全な辞書、物理単位、 最小権限の IAM ロールを掲載しています。
• ストレージとデータカタログのスキーマ辞書 （references/schema_storage.md）：テーブルストレージ、パーティション、 列、スナップショット、データセット、制約、レプリケーションに関するすべてのビュー （TABLE_STORAGE*、TABLE_STORAGE_USAGE_TIMELINE*、TABLES*、 TABLE_OPTIONS、COLUMNS、COLUMN_FIELD_PATHS、PARTITIONS、VIEWS、 MATERIALIZED_VIEWS、TABLE_SNAPSHOTS*、TABLE_CONSTRAINTS、 KEY_COLUMN_USAGE、SCHEMATA*、SCHEMATA_OPTIONS、SCHEMATA_REPLICAS*、 SCHEMATA_LINKS、SHARED_DATASET_USAGE）について、列の完全な辞書、物理単位、 最小権限の IAM ロールを掲載しています。
• プラットフォーム、ガバナンス、取り込みのスキーマ辞書 （references/schema_others.md）：アクセス制御 （OBJECT_PRIVILEGES、ROW_ACCESS_POLICIES、 ROW_ACCESS_POLICY_OPTIONS）、ストリーミング取り込み （STREAMING_TIMELINE_BY_PROJECT*、WRITE_API_TIMELINE_BY_PROJECT*）、 構成オプション（PROJECT_OPTIONS*、EFFECTIVE_PROJECT_OPTIONS、 ORGANIZATION_OPTIONS*、ORGANIZATION_OPTIONS_CHANGES）、分析情報と 推奨事項（RECOMMENDATIONS*、INSIGHTS）、インデックス／BI Engine／ルーティン （SEARCH_INDEXES*、SEARCH_INDEX_COLUMNS、SEARCH_INDEX_OPTIONS、 VECTOR_INDEXES*、VECTOR_INDEX_COLUMNS、VECTOR_INDEX_OPTIONS、 BI_CAPACITIES、BI_CAPACITY_CHANGES、ROUTINES*、ROUTINE_OPTIONS、 PARAMETERS）を含む、その他すべてのビューについて、列の完全な辞書、物理単位、 最小権限の IAM ロールを掲載しています。