App Vitals Monitoring

gplay vitals hits the Play Developer Reporting API (separate from the Android Publisher API used by most other commands). Every subcommand outputs JSON by default; add --output table|markdown for humans or --pretty to indent JSON. Dates are ISO 8601 (YYYY-MM-DD).

Preconditions

• Credentials set (gplay auth login or GPLAY_SERVICE_ACCOUNT).
• Service account needs "View app information and download bulk reports" permission.
• The app must have enough installs to generate vitals data (small apps return empty sets).

The real surface

There are exactly three groups. There is no crashes list/get, no errors list/get, no performance overview/permissions, no --cluster-id, --version-code, --start-time/--end-time, --severity, or --error-id.

Crash & ANR rate metrics

gplay vitals crashes query returns rate metrics, not a cluster list. Switch metric with --type crash|anr; group with --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

Other valid dimensions include deviceModel, deviceBrand, apiLevel, countryCode. Use --paginate to pull every page.

Anomaly detection — the regression / release gate

gplay vitals crashes anomalies lists automatically detected deviations that likely indicate a regression from a new release. This is the command to run in a post-release watch or a CI gate — it does the "is this worse than baseline?" judgement for you across crash, ANR, error, and performance metric sets.

# 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 accepts crash, anr, errors, performance, or all (default). --limit is 1–1000 (default 50).

Performance metrics

Three subcommands, each with an optional --dimension (e.g. 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

Errors: issues vs. reports, filtered with AIP-160

• errors issues — reports grouped into issues (counts, distinct users). Start here to triage.
• errors reports — individual reports with stack traces and device info. Drill in from an issue.

Both filter via a single --filter AIP-160 expression. Supported fields: errorIssueType (CRASH, ANR, NON_FATAL), apiLevel, versionCode, deviceModel, deviceBrand, deviceType, appProcessState (FOREGROUND, BACKGROUND), isUserPerceived; reports additionally supports errorIssueId and 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

--order-by (issues only) accepts errorReportCount / distinctUsers with asc/desc. Use --paginate for everything.

JSON + jq extraction

Default JSON is meant to be piped:

# 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'

Field names vary by endpoint — inspect once with --pretty before scripting against a path.

Stability workflow

1. Watch after every release. Run vitals crashes anomalies scoped to the rollout window first — it surfaces regressions without you setting thresholds.
2. Confirm the trend. vitals crashes query --type crash and --type anr for the rate; add --dimension versionCode to confirm the new build is the culprit.
3. Triage. vitals errors issues --filter 'errorIssueType = CRASH' --order-by 'errorReportCount desc' to rank by impact.
4. Drill in. Take the issue id and run vitals errors reports --filter 'errorIssueId = <id>' for stack traces and device breakdown.
5. Track ANRs separately — they weigh heavily on Play ranking; always check --type anr distinctly.

CI/CD stability gate

Prefer anomalies over hand-rolled thresholds. Note --rollout is a fraction 0.0–1.0, never a percent.

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