排查Pub/Sub至BigQuery订阅数据未写入问题

核心排查方向 #

• 核对订阅与BigQuery表的配置匹配度

  • 确认订阅指定的BQ表架构和消息格式完全一致：字段名、数据类型（如字符串对应STRING、数字对应INT64）、嵌套结构都要严格匹配，哪怕单个字段不匹配都会导致消息无法写入且无明显错误提示。
  • 检查订阅的错误处理策略：若未配置死信主题，格式错误的消息会持续重试但不会被确认，也不会在BQ作业历史留痕。可临时配置死信主题，观察是否有消息被转发，以此判断是否为格式问题。
  • 验证订阅服务账号权限：Pub/Sub的BigQuery订阅默认使用service-${PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com，需确保该账号拥有bigquery.tables.updateData、bigquery.tables.get和bigquery.jobs.create权限，权限不足会导致无法发起写入BQ的请求。

• 排查消息本身的有效性

  • 发布极简测试消息：比如BQ表是id INT64, name STRING，就发送{"id":1,"name":"test"}这类完全匹配架构的消息，排除复杂结构或特殊内容的干扰。
  • 检查消息编码与格式：确保消息是UTF-8编码，用Base64解码消息内容，确认无乱码、无JSON格式错误（若使用JSON格式）。

• 查看细粒度日志

  • Pub/Sub后台依赖DataFlow实现BQ写入，可通过Cloud Logging查看相关日志：
    • 过滤条件：resource.type="pubsub_subscription" AND resource.labels.subscription_id="你的订阅名称"，查看dataflow.googleapis.com相关条目，能找到投递过程中的异常信息。
    • 查看DataFlow Worker日志：过滤logName="projects/你的项目ID/logs/dataflow.googleapis.com%2Fworker"，这里会记录写入BQ时的具体错误，比如格式不匹配、权限拒绝等。
  • 检查BigQuery审计日志：在Cloud Logging过滤resource.type="bigquery_dataset" AND protoPayload.methodName="tables.updateData"，确认是否有Pub/Sub服务账号发起的写入请求，以及是否存在拒绝记录。

• 验证资源区域与状态一致性

  • 确认Pub/Sub主题、订阅和BQ表的区域完全匹配：跨区域配置可能导致投递失败，即使允许跨区域也会增加风险。
  • 检查BQ表状态：确保表处于“正常”状态，无锁定、删除恢复等异常情况。

• 重置订阅测试

  • 临时创建全新的Pub/Sub到BQ订阅，使用同一目标表并发布测试消息，验证是否能正常写入，排除原有订阅的隐性配置问题。

Pub/Sub日志说明 #

Pub/Sub本身的操作日志和后台投递日志都可以通过Cloud Logging查看，重点关注DataFlow相关的日志条目，因为Pub/Sub到BigQuery的订阅是通过后台托管的DataFlow作业实现的，大部分写入失败的细节都会在DataFlow Worker日志中体现。

内容的提问来源于stack exchange，提问作者John Velonis