Gpc Vitals Monitoring

GPC Vitals Monitoring

When to use

Use this skill when the task involves:

• Real-time rollout monitoring with gpc watch (multi-metric, auto-actions)
• Monitoring crash rates, ANR rates, and other Android Vitals metrics
• Setting up threshold-based alerting for CI/CD
• Tracking app startup times, frame rates, battery, and memory
• Reviewing and responding to user reviews
• Building monitoring pipelines with GPC output
• Comparing vitals across time periods
• Investigating error issues and anomalies

Inputs required

• Package name (or configured default)
• Metric type(s) to monitor (crashes, ANR, startup, rendering, battery, memory)
• Version code (optional — for filtering by release)
• Threshold values (for CI alerting)

Procedure

0) Unified health snapshot — start here

The fastest way to see the full picture: releases, vitals, and reviews in one command.

gpc status

Output:

App: com.example.myapp · My App  (fetched 10:42:01 AM)

RELEASES
  production   v1.4.2   completed    —
  beta         v1.5.0   inProgress  10%

VITALS  (last 7 days)
  crashes     0.80%  ✓    anr         0.20%  ✓
  slow starts 2.10%  ✓    slow render 4.30%  ⚠

REVIEWS  (last 30 days)
  ★ 4.6   142 new   89% positive   ↑ from 4.4

6 parallel API calls, result in under 3 seconds. Cached for 1 hour.

gpc status --days 14          # Wider vitals window
gpc status --cached           # Instant — no API calls (uses last fetch)
gpc status --refresh          # Force live fetch, ignore cache
gpc status --output json      # Full structured output for scripts

Exit code 6 if any vitals threshold is breached — use as a deployment gate.

1) Per-metric vitals dashboard

For per-metric details beyond what gpc status shows:

gpc vitals overview

2) Crash monitoring

# Crash rate and top clusters
gpc vitals crashes

# Filter by version code
gpc vitals crashes --version 142

# CI threshold alerting — exit code 6 if crash rate exceeds threshold
gpc vitals crashes --threshold 2.0

Exit code 6 means threshold was breached — use this to gate deployments.

3) ANR monitoring

gpc vitals anr
gpc vitals anr --version 142
gpc vitals anr --threshold 0.47  # Google's bad behavior threshold

4) Performance metrics

# Cold/warm startup times (auto-includes startType as a required dimension)
gpc vitals startup

# Frame rate / rendering
gpc vitals rendering

# Battery usage
gpc vitals battery

# Low memory killer rate
gpc vitals memory

# Wakeup time metric (low-memory killer)
gpc vitals wakeup

# Low memory killer stats (LMK)
gpc vitals lmk

gpc vitals wakeup shows the wakeup rate from low-memory kills (LMK events). Supports the same flags as other vitals subcommands: --days <n>, --threshold <value>, --json.

Low-Memory-Killer rate (gpc vitals lmk, v0.9.58+, corrected in v0.9.59)

Background: v0.9.58 shipped a misnamed resource (lowMemoryKillerRateMetricSet) that 404'd. v0.9.59 is the working build — the real Google resource is lmkRateMetricSet with metrics userPerceivedLmkRate, userPerceivedLmkRate7dUserWeighted, userPerceivedLmkRate28dUserWeighted, and distinctUsers. Use v0.9.59+ for LMK queries.

gpc vitals lmk --app com.example.app --since 7d

Supports the same flags as other vitals subcommands: --days <n>, --threshold <value>, --json.

Note: Vitals memory data accuracy was improved in v0.9.41 (Bug H: metric field names corrected from stuckBackground to stuckBg).

Count of error occurrences (gpc vitals error-count, v0.9.57+)

gpc vitals error-count returns a time-windowed count of error-issue occurrences from the Play Developer Reporting API. Use for CI gates when you want an absolute count rather than a rate.

gpc vitals error-count --app com.example.app --since 7d
gpc vitals error-count --app com.example.app --since 7d --threshold 100

Exits 6 if the count exceeds --threshold (same CI convention as other vitals commands).

4a) Compare vitals across versions

Side-by-side comparison of two version codes across all key metrics:

gpc vitals compare-versions <v1> <v2>

# Example
gpc vitals compare-versions 141 142

# Wider time window
gpc vitals compare-versions 141 142 --days 14

# JSON output for scripting
gpc vitals compare-versions 141 142 --json

# Markdown table (for GitHub comments, Slack, etc.)
gpc vitals compare-versions 141 142 --format markdown

Compares: crash rate, ANR rate, startup time, rendering, battery, and memory. Uses non-overlapping 7-day windows for each version. Regressions are highlighted in red in terminal output.

Note: gpc vitals compare-versions uses non-overlapping 7-day windows, both capped 2 days before today to account for API data lag.

Freshness clamping (v0.9.70+): Google's vitals data typically lags 3-4 days behind real-time. GPC now queries the freshness endpoint for each metric set before running any vitals query and automatically clamps the date range. This prevents 400 INVALID_ARGUMENT errors that previously occurred when the requested date range exceeded Google's available data window. No configuration needed.

4b) Real-time rollout monitoring (gpc watch, v0.9.67+)

gpc watch is the unified rollout monitoring command. It polls rollout status (near real-time) and vitals data (24-48h delayed) on an interval, checks thresholds, and takes action on breach.

# Basic: monitor crashes + ANR on production, poll every 15 minutes
gpc watch

# Watch a beta rollout with tighter thresholds
gpc watch --track beta --crash-threshold 0.015 --anr-threshold 0.005

# Auto-halt the rollout on any threshold breach
gpc watch --on-breach halt

# Notify + halt + send webhook on breach
gpc watch --on-breach notify,halt,webhook \
  --webhook-url https://hooks.slack.com/services/XXX

# CI mode: 3 rounds, 5-minute interval, NDJSON output
gpc watch --rounds 3 --interval 300 --json

# Monitor all 6 metrics
gpc watch --metrics crashes,anr,lmk,slowStarts,slowRender,errorCount

Six metrics: crashes, anr, lmk, slowStarts, slowRender, errorCount.

Three breach actions (combinable with --on-breach):

• notify — OS notification (macOS, Linux, Windows)
• halt — halt the active rollout via Google Play API
• webhook — POST breach event as JSON to --webhook-url

Thresholds resolve in priority order: CLI flags > .gpcrc.json vitals.thresholds.* > defaults (crash 2%, ANR 1%, LMK 3%, slow start 5%, slow render 10%).

Auto-stop: the watch loop stops when the rollout reaches 100%, a breach triggers halt, --rounds limit is hit, or Ctrl+C.

Exit codes: 0 = clean, 6 = at least one threshold breached.

Webhook payload:

{
  "type": "breach",
  "round": 3,
  "rollout": { "track": "production", "versionCode": "142", "userFraction": 0.1 },
  "vitals": { "crashes": { "value": 0.025, "threshold": 0.02, "breached": true } },
  "breaches": ["crashes"],
  "halted": true
}

Set the webhook URL in config to avoid passing it every time:

{
  "webhooks": { "watch": "https://hooks.slack.com/services/XXX" }
}

Note: gpc vitals watch (single-metric watcher) still works but gpc watch is the recommended command for rollout monitoring as of v0.9.67.

5) Error tracking and anomalies

# Detected anomalies
gpc vitals anomalies

# Error issues and reports
gpc vitals errors search

New in v0.9.47: If the Reporting API is not enabled for your GCP project, vitals and anomalies commands now show a helpful message with the enable URL instead of a raw 403 error. Non-vitals commands continue to work normally.

6) Review sentiment analysis

Local NLP-based sentiment analysis of reviews — no external API required:

gpc reviews analyze

# Filter by date range
gpc reviews analyze --since 2026-01-01
gpc reviews analyze --days 30

# Filter by language
gpc reviews analyze --lang en

# JSON output
gpc reviews analyze --json

# Markdown report (for GitHub, Confluence, etc.)
gpc reviews analyze --format markdown

Output includes:

• Sentiment trend over time (positive/neutral/negative)
• Topic clustering (what users talk about most)
• Keyword frequency table
• Rating distribution broken down by version

All processing is local — no third-party NLP service is called.

7) Review monitoring

# Recent reviews
gpc reviews list

# Filter by rating
gpc reviews list --stars 1-2

# Filter by language
gpc reviews list --lang en

# Filter by time
gpc reviews list --since 7d

# Single review details
gpc reviews get <review-id>

# Reply to a review (max 350 chars — validated before sending)
gpc reviews reply <review-id> --text "Thank you for your feedback"

# Auto-paginate all reviews (API returns max 10 per page by default)
gpc reviews list --all

# Start from a specific index (for manual pagination)
gpc reviews list --start-index 20

# Export reviews
gpc reviews export --format csv --output reviews.csv

New in v0.9.47: --all auto-paginates through all review pages. Reply text is validated against the 350-character Google Play limit before sending — exceeding the limit exits code 2 immediately. Note: the Reviews API only returns production reviews from the last 7 days.

Read:

• references/review-management.md

8) Threshold-based CI gating

Use --threshold to gate rollouts on vitals quality:

# Gate on crash rate (exits with code 6 if breached)
gpc vitals crashes --threshold 2.0

# Gate on ANR rate
gpc vitals anr --threshold 0.47

# Combine in a script
gpc vitals crashes --threshold 2.0 && \
gpc vitals anr --threshold 0.47 && \
echo "Vitals OK — safe to promote"

In CI, use exit code 6 to block promotion:

- name: Check vitals before promotion
  run: |
    gpc vitals crashes --threshold 2.0
    gpc vitals anr --threshold 0.47
- name: Promote to production
  if: success()
  run: gpc releases promote --from beta --to production --rollout 10

Read:

• references/ci-gating.md

8a) Vitals gate on rollout increase (--vitals-gate, v0.9.74+)

The --vitals-gate flag on rollout commands checks crash and ANR thresholds before increasing the rollout percentage. If any threshold is breached, the increase is skipped entirely and GPC exits with code 6. No users are exposed to the higher percentage while metrics are failing.

Previous behavior (before v0.9.74): GPC increased the rollout percentage first, then checked vitals and halted if thresholds were breached. This left users on the new, higher percentage during the breach window.

New behavior (v0.9.74+): GPC checks vitals first. If thresholds are breached, the rollout increase never happens.

# Increase rollout only if crash and ANR rates are within thresholds
gpc releases rollout --track production --rollout 50 \
  --vitals-gate --crash-threshold 2.0 --anr-threshold 0.47

# Use in a staged rollout script
gpc releases rollout --track production --rollout 10 --vitals-gate
gpc releases rollout --track production --rollout 25 --vitals-gate
gpc releases rollout --track production --rollout 50 --vitals-gate
gpc releases rollout --track production --rollout 100 --vitals-gate

Exit code 6 means a vitals threshold was breached and the rollout increase was not applied. Exit code 0 means vitals passed and the rollout was increased.

In CI, use if: success() guards to stop the pipeline at the first failing gate:

- name: Ramp to 25%
  run: gpc releases rollout --track production --rollout 25 --vitals-gate \
       --crash-threshold 2.0 --anr-threshold 0.47

- name: Ramp to 50%
  if: success()
  run: gpc releases rollout --track production --rollout 50 --vitals-gate \
       --crash-threshold 2.0 --anr-threshold 0.47

- name: Full rollout
  if: success()
  run: gpc releases rollout --track production --rollout 100 --vitals-gate \
       --crash-threshold 2.0 --anr-threshold 0.47

Threshold defaults (if flags are omitted): crash 2%, ANR 0.47%. Override via .gpcrc.json vitals.thresholds.*.

Read:

• references/ci-gating.md

8b) Vitals gate crash-rate fix (v0.9.82)

The vitals gate crash-rate check on rollout increase (the --vitals-gate flag) was silently skipping the check in earlier versions. The root cause: GPC was accessing a .data field on the MetricSetResponse shape returned by the Reporting API, but that field does not exist. As a result, the gate always passed regardless of crash rate.

The fix in v0.9.82 reads rows[last].metrics[firstMetric].decimalValue.value, which matches how gpc train reads crash rates from the same API. Upgrading to v0.9.82+ is required for the --vitals-gate crash-rate check to work correctly.

8c) VitalsThresholds in config (v0.9.82)

VitalsThresholds is now a formally typed field in GpcConfig and ResolvedConfig in @gpc-cli/config. Set thresholds project-wide in .gpcrc.json:

{
  "vitals": {
    "thresholds": {
      "crashRate": 2.0,
      "anrRate": 0.5
    }
  }
}

These values are used as defaults by --vitals-gate, gpc watch, and gpc vitals crashes/anr --threshold. CLI flags still take priority over config.

9) Reporting API rate limit

The Play Developer Reporting API is rate-limited to 10 queries per second. GPC handles this automatically — if you hit the limit, requests are queued and retried with backoff. No configuration needed.

10) Monitoring pipelines

Pipe JSON output to your monitoring stack:

# Send crash data to your monitoring tool
gpc vitals crashes --output json | jq '.data' | curl -X POST ...

# Periodic check (cron)
gpc vitals overview --output json >> /var/log/gpc-vitals.jsonl

11) Reports

# List available reports
gpc reports list financial --month 2026-02
gpc reports list stats --month 2026-02

# Download reports
gpc reports download financial --month 2026-02
gpc reports download stats --month 2026-02 --type installs --output-file installs.csv

Report types — financial: earnings, estimated_sales, play_balance. Stats: installs, crashes, ratings, reviews, store_performance.

Verification

• gpc status shows all three sections (releases, vitals, reviews) without errors
• gpc watch --rounds 1 completes one polling round without errors
• gpc vitals overview returns data (requires sufficient install volume)
• Threshold commands return exit code 0 (OK) or 6 (breached)
• gpc reviews list returns recent reviews
• JSON output is parseable: gpc vitals crashes --output json | jq .

Failure modes / debugging

Related skills

• gpc-setup: Authentication and configuration
• gpc-release-flow: Upload and rollout management
• gpc-ci-integration: Automated vitals checks in CI

CI Vitals Gating

Concept

Use GPC's --threshold flag to gate deployments on app quality. If crash rate or ANR rate exceeds the threshold, GPC exits with code 6, failing the CI job.

Google Play Thresholds

Google Play has official "bad behavior" thresholds that can affect app visibility:

Basic Gating

# Fail if crash rate exceeds 2%
gpc vitals crashes --threshold 2.0

# Fail if ANR rate exceeds 0.47%
gpc vitals anr --threshold 0.47

Exit codes:

• 0 — Below threshold (safe to proceed)
• 6 — Threshold breached (block promotion)

GitHub Actions Pattern

jobs:
  check-and-promote:
    runs-on: ubuntu-latest
    env:
      GPC_SERVICE_ACCOUNT: ${{ secrets.PLAY_SERVICE_ACCOUNT }}
      GPC_APP: com.example.app
    steps:
      - name: Install GPC
        run: npm install -g @gpc-cli/cli

      - name: Check crash rate
        run: gpc vitals crashes --threshold 2.0

      - name: Check ANR rate
        run: gpc vitals anr --threshold 0.47

      - name: Promote to production
        run: gpc releases promote --from beta --to production --rollout 10

If either check fails (exit code 6), the "Promote" step is skipped.

Advanced: Scheduled Vitals Check

Run vitals checks on a schedule to catch regressions:

name: Vitals Monitor
on:
  schedule:
    - cron: '0 */6 * * *'  # Every 6 hours

jobs:
  monitor:
    runs-on: ubuntu-latest
    env:
      GPC_SERVICE_ACCOUNT: ${{ secrets.PLAY_SERVICE_ACCOUNT }}
      GPC_APP: com.example.app
    steps:
      - name: Install GPC
        run: npm install -g @gpc-cli/cli

      - name: Check vitals
        run: |
          gpc vitals crashes --threshold 2.0
          gpc vitals anr --threshold 0.47

      - name: Alert on failure
        if: failure()
        run: |
          # Send Slack/Discord notification
          curl -X POST ${{ secrets.SLACK_WEBHOOK }} \
            -d '{"text":"Vitals threshold breached for com.example.app"}'

Comparing Vitals Over Time

# Compare this week vs last week
gpc vitals compare crashes --days 7

Use this in post-release monitoring to detect regressions.

Vitals gate on rollout increase (v0.9.74+)

The --vitals-gate flag on rollout commands checks thresholds before applying the rollout increase. If a threshold is breached the increase is skipped and GPC exits 6. This prevents users from being exposed to a higher rollout percentage while metrics are failing.

# Safe ramp: only increases if vitals are within thresholds
gpc releases rollout --track production --rollout 50 \
  --vitals-gate --crash-threshold 2.0 --anr-threshold 0.47

Staged pipeline pattern:

- name: Ramp to 25%
  run: gpc releases rollout --track production --rollout 25 --vitals-gate \
       --crash-threshold 2.0 --anr-threshold 0.47

- name: Ramp to 50%
  if: success()
  run: gpc releases rollout --track production --rollout 50 --vitals-gate \
       --crash-threshold 2.0 --anr-threshold 0.47

- name: Full rollout
  if: success()
  run: gpc releases rollout --track production --rollout 100 --vitals-gate \
       --crash-threshold 2.0 --anr-threshold 0.47

Behavior difference from standalone threshold checks:

Use --vitals-gate for rollout safety. Use standalone --threshold for post-deploy monitoring or CI promotion gates.

Considerations

• Data lag: Vitals data may be delayed by 24-48 hours
• Volume requirements: Small apps may not have enough data for meaningful metrics
• New releases: Crash data for a new version takes time to accumulate
• False positives: A single bad device/OS can spike crash rates temporarily

Review Management

Listing Reviews

# All recent reviews
gpc reviews list

# Filter by star rating
gpc reviews list --stars 1-2     # 1 and 2 star reviews
gpc reviews list --stars 5       # 5 star reviews only

# Filter by language
gpc reviews list --lang en       # English reviews
gpc reviews list --lang ja       # Japanese reviews

# Filter by time
gpc reviews list --since 7d     # Last 7 days
gpc reviews list --since 30d    # Last 30 days

# Combine filters
gpc reviews list --stars 1-2 --since 7d --lang en

# Pagination
gpc reviews list --limit 50

# Start from a specific index (skip first N reviews)
gpc reviews list --start-index 20

Viewing a Single Review

gpc reviews get <review-id>

Shows full review text, user info, star rating, and device info.

Replying to Reviews

# Inline reply (max 350 characters — validated before sending)
gpc reviews reply <review-id> --text "Thank you for your feedback"

Reply Best Practices

• Respond within 24 hours — faster responses lead to higher rating updates
• Max 350 characters — GPC validates this before sending
• Be helpful, not defensive — acknowledge the issue, offer a solution
• Don't include personal info — review replies are public

Reply Templates

Bug report:

Thanks for reporting this. We've identified the issue and a fix is coming in the next update. Sorry for the inconvenience.

Feature request:

Great suggestion! We've added this to our roadmap. Stay tuned for updates.

Generic positive:

Thank you for the kind review! We're glad you're enjoying the app.

Exporting Reviews

# Export to CSV
gpc reviews export --format csv --output reviews.csv

# Export to JSON
gpc reviews export --format json --output reviews.json

Rate Limits

The Reviews API has stricter rate limits than other endpoints:

GPC handles rate limiting automatically with exponential backoff, but be aware of these limits when processing large volumes of reviews.

Monitoring Reviews in CI

# Check for new negative reviews in CI
NEW_REVIEWS=$(gpc reviews list --stars 1-2 --since 1d --output json | jq '.data | length')
if [ "$NEW_REVIEWS" -gt 0 ]; then
  echo "Warning: $NEW_REVIEWS new negative reviews in the last 24 hours"
fi