gplay-vitals-monitoring

アプリのバイタル指標のモニタリング

gplay vitals は Play Developer Reporting API（ほとんどの他のコマンドで使用する Android Publisher API とは別の API）を呼び出します。すべてのサブコマンドはデフォルトで JSON を出力します。人間が読みやすい形式にするには --output table|markdown を、JSON をインデントするには --pretty を追加します。日付は ISO 8601（YYYY-MM-DD）形式です。

前提条件

• 認証情報が設定されていること（gplay auth login または GPLAY_SERVICE_ACCOUNT）。
• サービスアカウントに「アプリ情報の閲覧と一括レポートのダウンロード」権限が必要です。
• バイタルデータが生成されるだけのインストール数がアプリにあること（小規模なアプリでは結果が空になります）。

実際に使えるコマンド

コマンドグループは正確に 3 つあります。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）です。

パフォーマンス指標

3 つのサブコマンドがあり、いずれも --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 — スタックトレースとデバイス情報を含む個別レポートです。イシューから詳細を確認します。

どちらも、単一の AIP-160 式を指定する --filter でフィルタリングします。対応フィールド：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

--order-by（issues のみ）では、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