gplay-vitals-monitoring

用途

gplay-vitals-monitoring 是 gplay CLI 中专门用于监控 Android 应用稳定性与性能的技能。它调用 Play Developer Reporting API（与大多数其他命令使用的 Android Publisher API 不同），用于查询崩溃率、ANR 率、性能指标和错误报告，帮助开发者在发布后及时发现回归问题。

主要能力

该技能提供三组命令：

• 崩溃与 ANR 速率指标：gplay vitals crashes query 返回速率指标而非集群列表。可通过 --type crash|anr 切换指标，通过 --dimension 按 versionCode、deviceModel、deviceBrand、apiLevel、countryCode 等维度分组。使用 --paginate 拉取所有分页。
• 异常检测（回归/发布门禁）：gplay vitals crashes anomalies 列出自动检测到的偏差，这些偏差很可能表示新版本引入的回归。该命令跨崩溃、ANR、错误和性能指标集自动判断“是否比基线更差”，适合发布后观察或 CI 门禁。--type 接受 crash、anr、errors、performance 或 all（默认），--limit 为 1–1000（默认 50）。
• 性能指标：三个子命令，每个都支持可选的 --dimension（如 apiLevel、deviceModel、country）：
  • gplay vitals performance startup：冷/温/热启动百分位数。
  • gplay vitals performance rendering：慢帧（16ms）和冻结帧（700ms）速率。
  • gplay vitals performance battery：通过 --type wakeup 或 --type wakelock 选择过度唤醒或卡住唤醒锁。
• 错误：问题与报告：
  • gplay vitals errors issues：将报告分组为问题（计数、去重用户数），用于初步分类。
  • gplay vitals errors reports：单个报告，包含堆栈跟踪和设备信息，用于深入排查。
  • 两者都通过单个 --filter AIP-160 表达式过滤。支持的字段包括 errorIssueType（CRASH、ANR、NON_FATAL）、apiLevel、versionCode、deviceModel、deviceBrand、deviceType、appProcessState（FOREGROUND、BACKGROUND）、isUserPerceived；reports 还额外支持 errorIssueId 和 errorReportId。
  • --order-by（仅 issues）接受 errorReportCount / distinctUsers 及 asc/desc。

使用方式

所有子命令默认输出 JSON，可添加 --output table|markdown 供人类阅读，或 --pretty 缩进 JSON。日期使用 ISO 8601（YYYY-MM-DD）。

前置条件：

• 已设置凭据（gplay auth login 或 GPLAY_SERVICE_ACCOUNT）。
• 服务账号需要“查看应用信息和下载批量报告”权限。
• 应用必须有足够的安装量才能生成 vitals 数据（小型应用返回空集）。

典型工作流：

1. 每次发布后观察：先运行 vitals crashes anomalies 并限定在发布窗口，无需设置阈值即可发现回归。
2. 确认趋势：用 vitals crashes query --type crash 和 --type anr 查看速率，加 --dimension versionCode 确认新构建是元凶。
3. 分类：vitals errors issues --filter 'errorIssueType = CRASH' --order-by 'errorReportCount desc' 按影响排序。
4. 深入：取 issue id 运行 vitals errors reports --filter 'errorIssueId = <id>' 获取堆栈跟踪和设备细分。
5. 单独跟踪 ANR——它们对 Play 排名影响很大，始终单独检查 --type anr。

CI/CD 稳定性门禁示例：

ANOMALIES=$(gplay vitals crashes anomalies \
  --package com.example.app --type all --from "$RELEASE_DATE" \
  | jq '.anomalies | length')

if [ "$ANOMALIES" -gt 0 ]; then
  echo "Vitals anomalies detected ($ANOMALIES). Halting promotion."
  exit 1
fi

# Clean — promote beta to a 10% staged production rollout
gplay promote --package com.example.app --from beta --to production --rollout 0.1

注意 --rollout 是 0.0–1.0 的小数，不是百分比。

JSON 与 jq 提取：默认 JSON 设计用于管道。字段名因端点而异，脚本化前先用 --pretty 检查一次。

适用场景

• 发布后监控崩溃和 ANR 回归。
• CI/CD 中作为稳定性门禁，自动阻止有异常的版本推广。
• 按版本、设备型号、API 级别、国家等维度分析崩溃和性能问题。
• 对错误问题进行分类和深入排查。

限制

• 只有三组命令，没有 crashes list/get、errors list/get、performance overview/permissions，也不支持 --cluster-id、--version-code、--start-time/--end-time、--severity 或 --error-id。
• 需要足够的安装量才能生成 vitals 数据，小型应用可能返回空集。
• 需要正确的服务账号权限。
• 字段名因端点而异，脚本化前需先检查。