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 和 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 角色：

   • 确认 {project_id} 已关联有效的 Google Cloud 结算账号。
   • 确保具备相应的 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 天的同期对比，并按分区和作业类型筛选；对于未指明原因的成本激增，扫描 3 个主要指标：按需 TiB、容量槽小时数和存储 GiB），从而将诊断遥测开销降至最低。
   • 对话关口： 先如实总结高层基线发现，然后提出 2–3 个有针对性的深入调查选项，而不是主动罗列后续的子向量查询。
4. 深入分析领域并进行对比： 执行下方领域参考中相应领域参考文件定义的分步诊断工作流，然后遵循其 INFORMATION_SCHEMA 最佳实践，运行 bigquery-observability 中相应的查询，通过与正常基线进行对比分析来确定根本原因。

性能背景：“慢”的相对性

性能是相对的。排查性能问题时，务必进行对比分析：找出一次可比的历史执行，对比统计数据，并确定快速基线与慢速执行之间发生变化的维度：

• 处理的数据： 数据量增加、分区/聚簇裁剪变化、数据倾斜、输入记录扩增。
• 底层定义： 视图变更、架构修改。
• 系统争用： 邻近工作负载干扰、容量饱和（槽利用率 >95%）、空闲槽可用性、并发查询激增。
• 配置变更： 槽容量/自动扩缩容最大槽数变更、容量承诺到期、空闲槽设置变更或预留重新分配。

成本背景：4 步诊断漏斗

成本问题排查需要追踪物理资源消耗（槽位小时数、计费 TiB、存储 GiB），而不是波动的合同费率：

1. 收集： 确定范围并提取 7 天 PoP（或明确指定的 MoM / 180 天） 基线指标。
2. 隔离： 查明支出激增是否源于查询量、单个“霸凌查询”、BQML 50x 倍率、未覆盖的 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）、诊断 JOIN 膨胀（records_written >> records_read、high_cardinality_joins）、排查 Shuffle 溢出（shuffle_output_bytes_spilled）和分区倾斜、消除子步骤中间变量的歧义（$1、$2）、修正必需扫描字节数与已读取记录数之间的差异，以及理解 UI 执行图基础概念的诊断工作流。

成本问题排查

• 按需计算成本（references/cost_compute_ondemand.md）： 用于排查未分区数据的失控扫描（“霸凌查询”）、隐藏的行级安全性（RLS）数据遮蔽缺口、BigQuery ML（BQML）50x 模型训练费率倍率，以及用户/服务账号查询配额的诊断工作流。
• 容量（版本）计算成本 (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。