bigquery-observability

BigQuery 可观测性

归属信息

必须阅读：在执行任何 gcloud、REST API 或 MCP 命令之前，必须阅读使用归属信息。对于直接在终端中执行的命令（绝不能在生成的脚本、Terraform 或用户代码中执行），请在 gcloud 前添加前缀 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:bigquery-observability)" 并将 agent-skills/1.0 (skill:bigquery-observability) 添加到 User-Agent 标头中。

工具选择

工具	主要用例	优势与功能	应避免的情形 / 局限性
INFORMATION_SCHEMA（I_S）	历史分析、队列比较（normalized_literals）、发现快速/缓慢时段、预留和项目时间线、多作业聚合、成本/账单追踪。	可灵活地跨 JOBS、JOBS_TIMELINE 和 RESERVATIONS 执行 SQL 查询；支持自定义时间范围和分组。	避免用于高频实时轮询或单个作业的点查（可能消耗 slot，且执行需要数秒）。
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）	实时告警、全局仪表板、持续跟踪 slot 利用率、高层级 SLA/SLO 监控。	开箱即用的 slot 利用率、查询吞吐量、PENDING 队列深度和执行延迟图表；无需运行查询即可实现低延迟告警。	避免用于 SQL 级调试、检查单个查询文本或查看阶段级执行详情。

先决条件与环境设置

在检索遥测数据或运行可观测性查询之前，请确保已配置 Google Cloud 环境和项目：

1. Google Cloud SDK：确保已安装并配置 Google Cloud SDK。

2. 选择项目：设置当前 Google Cloud 项目：

   gcloud config set project {project_id}
   

3. 启用 API：确保已启用 BigQuery 和 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 角色：

   • 确认 {project_id} 已关联有效的 Google Cloud Billing 账号。
   • 确保拥有适当的 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、shuffle 溢出）。

   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. **优先使用数据集级视图而非区域级／项目级视图：**查询特定数据集的表元数据、列或视图时，如果项目级元数据访问受限，请使用 {dataset_id} 限定范围，而不是 region-{region}。数据集范围的查询只需要对目标数据集拥有权限。
3. **优先使用项目级视图而非组织／文件夹级视图（_BY_PROJECT）：**始终先使用项目范围的视图，再考虑升级到 _BY_FOLDER 或 _BY_ORGANIZATION。文件夹级和组织级查询需要广泛的文件夹／组织 IAM 权限（在组织／文件夹节点上拥有 bigquery.jobs.listAll 或 bigquery.tables.list）。
4. **优先使用元数据角色而非数据角色：**检查表和存储信息时，如果不需要读取数据的权限（bigquery.tables.getData），优先使用 roles/bigquery.metadataViewer（提供 bigquery.tables.get 和 bigquery.tables.list），而不是 roles/bigquery.dataViewer 或 roles/bigquery.dataOwner。（注意：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 行就表示用量为 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 50x 倍数规则、脚本包装器去重，以及 行级安全（RLS）屏蔽检查。
• 容量计算：可计费槽位与承诺 (references/compute_capacity_billable.md)：用于审计 1-Year/3-Year 承诺、未覆盖的基准 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-second 预留槽位饱和情况的查询。
• 容量与配置查询 (references/capacity_and_configuration_queries.md)：用于评估 每秒基准/最大容量上限、自动扩缩容饱和时间线，以及审计配置变更 （RESERVATION_CHANGES_BY_PROJECT、ASSIGNMENT_CHANGES_BY_PROJECT）的查询。

架构字典（列定义与单位）

• 计算与容量架构字典 (references/schema_compute.md)： 所有计算、作业、会话、预留、容量承诺和分配视图的完整列字典、 物理单位及最小权限 IAM 角色（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）。
• 存储与数据目录架构字典 (references/schema_storage.md)：所有表存储、分区、列、快照、 数据集、约束和复制视图的完整列字典、物理单位及最小权限 IAM 角色 （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）。
• 平台、治理与数据摄取架构字典 (references/schema_others.md)：所有其余视图的完整列字典、物理单位 及最小权限 IAM 角色，包括访问控制（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）。