gplay-vitals-monitoring

应用 Vitals 监控

gplay vitals 调用的是 Play Developer Reporting API（不同于大多数其他命令所用的 Android Publisher API）。每个子命令默认都输出 JSON；添加 --output table|markdown 可供人阅读，或添加 --pretty 缩进 JSON。日期采用 ISO 8601 格式（YYYY-MM-DD）。

前置条件

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

实际命令

命令恰好分为三组。没有 crashes list/get、errors list/get、performance overview/permissions、--cluster-id、--version-code、--start-time/--end-time、--severity 或 --error-id。

命令	用途
vitals crashes query	查询日期范围内的崩溃 / ANR 率指标
vitals crashes anomalies	自动检测回归——发布门禁
vitals performance startup|rendering|battery	性能指标细分数据
vitals errors issues	分组后的错误 问题（支持 AIP-160 过滤）
vitals errors reports	单条错误 报告及堆栈跟踪

崩溃与 ANR 率指标

gplay vitals crashes query 返回的是率指标，而不是集群列表。使用 --type crash|anr 切换指标；使用 --dimension 分组。

# Crash rate for a window
gplay vitals crashes query --package com.example.app --from 2026-06-01 --to 2026-06-30 --output table

# ANR rate
gplay vitals crashes query --package com.example.app --type anr --output table

# Break down by version to spot a bad build
gplay vitals crashes query --package com.example.app --dimension versionCode --output table

# By device model
gplay vitals crashes query --package com.example.app --dimension deviceModel --paginate

其他有效维度包括 deviceModel、deviceBrand、apiLevel、countryCode。使用 --paginate 获取所有分页。

异常检测——回归 / 发布门禁

gplay vitals crashes anomalies 会列出自动检测到的偏差，这些偏差可能表明新版本引入了回归。可在发布后的观察阶段或 CI 门禁中运行此命令——它会针对崩溃、ANR、错误和性能指标集，替你判断“情况是否比基线更差”。

# All anomalies in the last 7 days (default window)
gplay vitals crashes anomalies --package com.example.app --output table

# Just ANR regressions, most recent 20
gplay vitals crashes anomalies --package com.example.app --type anr --limit 20

# Scope to a release window
gplay vitals crashes anomalies --package com.example.app --from 2026-06-25 --to 2026-07-02

--type 可接受 crash、anr、errors、performance 或 all（默认值）。--limit 范围为 1–1000（默认值为 50）。

性能指标

有三个子命令，每个都支持可选的 --dimension（例如 apiLevel、deviceModel、country）：

# Cold/warm/hot startup percentiles, broken down by API level
gplay vitals performance startup --package com.example.app --dimension apiLevel --output table

# Slow (16ms) and frozen (700ms) frame rates
gplay vitals performance rendering --package com.example.app --from 2026-06-01 --to 2026-06-30

# Battery: excessive wakeups vs. stuck wake locks (choose with --type)
gplay vitals performance battery --package com.example.app --type wakeup --output table
gplay vitals performance battery --package com.example.app --type wakelock

错误：问题与报告，以及 AIP-160 过滤

• errors issues — 将报告分组为问题（计数、不同用户数）。从这里开始进行分类处理。
• errors reports — 单条报告，包含堆栈跟踪和设备信息。从问题进一步深入查看。

两者都通过单个 --filter AIP-160 表达式进行过滤。支持的字段：errorIssueType（CRASH、ANR、NON_FATAL）、apiLevel、versionCode、deviceModel、deviceBrand、deviceType、appProcessState（FOREGROUND、BACKGROUND）、isUserPerceived；reports 还支持 errorIssueId 和 errorReportId。

# Top crash issues by report count
gplay vitals errors issues --package com.example.app \
  --filter 'errorIssueType = CRASH' \
  --order-by 'errorReportCount desc' --page-size 10 --output table

# ANR issues most impacting distinct users
gplay vitals errors issues --package com.example.app \
  --filter 'errorIssueType = ANR' --order-by 'distinctUsers desc'

# Compound filter: crashes on a specific version, foreground only
gplay vitals errors reports --package com.example.app \
  --filter 'errorIssueType = CRASH AND versionCode = 105 AND appProcessState = FOREGROUND'

# All reports belonging to one issue (drill-down)
gplay vitals errors reports --package com.example.app \
  --filter 'errorIssueId = 1234567890' --page-size 20

仅 issues 的 --order-by 支持 errorReportCount / distinctUsers，以及 asc/desc。使用 --paginate 获取所有结果。

JSON + jq 提取

默认 JSON 适合通过管道传递：

# Pull the errorIssueId of the worst crash issue
WORST=$(gplay vitals errors issues --package com.example.app \
  --filter 'errorIssueType = CRASH' --order-by 'errorReportCount desc' --page-size 1 \
  | jq -r '.errorIssues[0].name')

# Count anomalies flagged in the release window
gplay vitals crashes anomalies --package com.example.app --from 2026-06-25 --to 2026-07-02 \
  | jq '.anomalies | length'

字段名称因端点而异——编写脚本并引用路径前，先用 --pretty 检查一次。

稳定性工作流

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. 深入调查。 取出问题 ID，运行 vitals errors reports --filter 'errorIssueId = <id>'，查看堆栈跟踪和设备细分数据。
5. 单独跟踪 ANR——它们对 Play 排名影响很大；务必单独检查 --type anr。

CI/CD 稳定性门禁

优先使用 anomalies，而不是自行设置阈值。注意，--rollout 表示 0.0–1.0 之间的比例，绝不是百分比。

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