木曜日の夕方、CapacitorJSのショッピングアプリはAndroid 14ユーザー向けに空白のダッシュボードを表示し始めました。iOSユーザーは通常のブラウジングを続けています。Electronデスクトップユーザーは何も報告していません。オンコールエンジニアはWebViewのレンダリングバグを想定し、Android Studioを開き、数時間をかけてデバイス間のレンダリング動作を比較しました。最終的な原因はレンダリングバグではありませんでした。ステージングAPIキーがCDNキャッシュの無効化に失敗したため、モバイルクライアントに到達しなかったからです。
そのインシデントは、リポジトリの境界を尊重しないモバイルエラーの典型的な例です。新しいJavaScriptの変更は無害なのに、デプロイ、構成値、許可状態、サービス依存関係、ネットワークパスがユーザージャーニーを破壊する可能性があります。マイクロソフトのインシデント分析では 40%の生産事故はcodeまたは構成エラーから、60%はインフラ、展開、サービス依存関係から。 実践的な教訓は単純です:. (アプリのトラブルシューティングは、スタックトレースではなく、全体の障害領域から始まる必要があります)
This playbook follows the workflow I use after shipping CapacitorJS and Electron releases: establish exactly what the user ran, inspect production telemetry before attempting reproduction, verify non-code causes, then debug the narrowest layer that matches the symptom. The seven moves are incident scoping, layered logs, web and native debugging, networking and state checks, CI guardrails, live-update recovery, and a post-incident review that assigns prevention work.
このプレイブックは、CapacitorJSとElectronのリリースを出荷した後、使用するワークフローに従っています:ユーザーが実行したものを正確に特定する、生産時計測値を検査する前に再現を試みる、__CAPGO_KEEP_0__以外の原因を検証する、症状に合致する最も狭いレイヤーをデバッグする。7つの動作は、インシデントスコープ、層化されたログ、Webとネイティブのデバッグ、ネットワーキングとステートチェック、CIガードレール、ライブアップデートの回復、インシデント後のレビューで、防止の作業を割り当てることです。
- 目次
- 変数を除去して再現する
- Web層とネイティブ層のデバッグ
- ネットワーク、ストレージ、パーミッションのチェックから始める
- CIと自動テストを早期の警告システムとして
- ライブアップデートを緊急回復チャンネルとして
- 次のインシデントを防ぐためにインシデント後の分析
ダッシュボードが暗くなる夜
By Thursday evening, Android users were reporting a blank dashboard while Electron desktop users continued working normally. The first assumption was an Android 14 or WebView regression. That clue narrowed the search, but it did not identify the failure. The affected users also shared a release channel, a cached configuration path, an API environment, and a particular sequence of dashboard requests.
オンコールエンジニアはWebViewのバージョンを比較し始めました。結果は妥当に見えましたが、どこにもつながらませんでした。ダッシュボードが空白になるのはレンダリング例外、空のAPIレスポンス、却下された要求、無効なトークン、機能フラグ、またはセッションの復元を阻害するストレージの読み取りによるものです。codeを変更する前に、影響を受けたユーザーが受け取ったバイナリ、ウェブバンドル、構成、バックエンドパスを確定する必要があります。
特定の障害の範囲を確定する
生産環境のテレメトリから始めましょう。開発用のラップトップではありません。GoogleのAndroidのクラッシュとANRガイドラインでは、イベントを次の要素で絞り込むことを推奨しています。 デバイス、オペレーティングシステム、時間ウィンドウイベントの位置が不明の場合、再現中にログキャットを使用します。GoogleのAndroidのビタルのトラブルシューティングガイド)
次のフィールドを1つの影響を受けたセッションからキャプチャします:
- ビルドの識別子 ネイティブアプリのバージョン、ビルドID、ウェブバンドルハッシュ、リリースタイムスタンプを記録します。
- Distribution Channel: ユーザーがキャニバリ、ベータ、ステージング、または安定版のコンテンツを受け取ったかどうかを確認します。
- 実行環境: AndroidまたはiOSのバージョン、デバイスモデル、ネットワークタイプ、パーミッション状態、およびアプリがバックグラウンドから復帰したかどうかを記録します。
- 最後の成功アクション: タップシーケンス、リクエスト、レスポンスステータス、表示結果を厳密に保存します。
- 構成スナップショット: APIのベースURL、機能フラグ、認証設定、プラグイン構成を知られている良いデバイスと比較します。
Capacitorはネイティブ版とWebView内で実行されているWebコンテンツを別々に維持します。2つのユーザーは、異なるJavaScriptバンドルを受け取ることができるインストール済みのバイナリを共有することができ、Webバンドルを共有することもできます。ネイティブプラグインを使用することができます。Electronでは、リリースマニフェスト、メインプロセスバージョン、レンダラーのバンドル、更新チャネルを含むすべてのチェックが必要です。レンダラーのパッケージメタデータだけでは、ユーザーが実行したものを確立できません。
再現するには変数を削除します。
収集した識別子を分類して、インシデントを キャニバリのみ、ステージング、または完全にロールアウトしたものとして分類します。. Canary-only failure points to a specific bundle, flag, or channel setting. A staged failure suggests issues with audience or device selection logic. A fully rolled-out failure indicates a priority issue with shared configuration, backend behavior, and native compatibility.
Compare the affected device with a known-good one. Check native plugin versions, web hash, channel, API environment, authentication state, and permission grants. Replay the user’s last action sequence locally before using an emulator. If one flag controls the failure, keep other variables constant and bisect that flag’s behavior.
Practical rule: Do not call a reproduction ‘the same bug’ until the build ID, channel, web bundle, operating system, and configuration match.
The Android dashboard incident was caused by configuration correction. The team compared snapshots, confirmed that the native binary was valid, and verified that the WebView and dashboard code were unchanged. Production clients were requesting an environment with a staging credential because the earlier cache invalidation had not reached every mobile client. The recovery work therefore focused on correcting the configuration, setting appropriate cache invalidation headers, and verifying the CDN purge from affected regions and client paths.
そのシーケンスは重要です。成功したパージ コマンドは、すべてのユーザーが修正された値を取得できることを証明しないからです。CDN の応答、キャッシュの古さ、バンドルまたは構成ハッシュ、そして新しいクライアント セッションを確認する前に、回復を宣言することは避けるべきです。ネイティブ リビルドは、失敗したアーティファクトを変更せずにロールアウト時間を追加するだけです。
将来のインシデントのために同じ規範を維持してください: ユーザーのアーティファクトを特定し、失敗の表面を検出し、環境の差異を排除し、次に code をデバッグしてください。. モバイル チームのための書面のインシデント レスポンス ガイド インシデント レスポンス ガイドは、オンコール ルックアップ、テレメトリ クエリ、パージ バリデーション、ネイティブ バイナリが失敗したコンポーネントでない場合にライブ アップデートを使用する決定を含めるべきです。
Webview、ネイティブ、OS からログを読む
CapacitorJS または Electron アプリケーションは、複数のレイヤーで証拠を生成し、各レイヤーは異なる質問に答えます。Webview は JavaScript の例外と失敗した要求を表示できますが、プラグインの失敗をすべて説明することはできません。ネイティブ ログはブリッジとライフサイクル ビヘイビアを公開し、OS はメモリ プレス、パーミッション ディニール、プロセス終了を記録しますが、アプリケーション code はそれらを観測することはできません。
症状を証拠と照合する
Webview レイヤー 層、コンソールエラー、未処理のPromiseの拒否、ナビゲーションイベント、リクエストURL、レスポンスステータス、リクエストタイミングを収集します。特に、プラグインの静的な拒否は危険です。UIはカメラ、ファイルシステム、セキュアストレージ、または通知の操作がすでに失敗している場合でも、レンダリングを続行する可能性があります。
The ネイティブレイヤー ネイティブレイヤーにはAndroidのlogcat出力、iOS os_log レコード、プラグインブリッジの例外、活動またはビューコントローラーのライフサイクルイベント、ネイティブクラッシュトレースが含まれます。Electronはメインプロセスのログストリーム、自動更新イベント、ウィンドウの作成失敗、IPCメッセージを追加します。レンダラーのエラーは必ずしもメインプロセスに出現せず、メインプロセスのクラッシュはレンダラーのコンソール出力に表示されない可能性があります。
The OSレイヤー アプリケーションの制御外のイベントを説明します。メモリの圧力、バックグラウンドの終了、バッテリーの制限、拒否された権限、プロセスの殺害、システムレベルのクラッシュレポートを探します。このレイヤーは、有用なJavaScriptスタックを持たない「ランダムなクラッシュ」が見られることがよくあります。
関連付ける前にフィルタリングする
共有リクエストまたはオペレーションIDをWebView、ネイティブブリッジ、バックエンド、中央のログシンクに渡します。ユーザーアクションが始まる前にIDを追加し、ネットワークリクエストとネイティブコールバックを通してIDを保持します。タイムスタンプを一貫した形式で関連付け、デバイスの時計のズレを考慮し、フレームワークのノイズをフィルタリングするのは、元のイベントを保持した後のみです。
すべてのレイヤーで同じコンテキストフィールドを保存する: アプリバージョン、ウェブバンドルハッシュ、チャネル、デバイス、OS、セッション、機能フラグの状態。集中化された収集により、再現試行はユーザーの証拠と比較できるようになり、仮定に置き換える必要がなくなります。実用的な モバイルデバッグ用のログ分析ツール ウェブレイヤーとネイティブレイヤーのデバッグ
症状を所有するレイヤーをデバッグする。フリーズした画面がネイティブライフサイクルイベントに反応する場合、ウェブビューで始まることが多い。プロセステルミネーション、プラグイン例外、起動失敗はネイティブツールまたはElectronのメインプロセスに属する。レイヤー間を移動するルーティングルールなしでは、活動が増えるだけであり、原因を絞り込むことはできない。
ウェブビューから始める
Androidの場合、デバッグ可能な__CAPGO_KEEP_0__ビルドをChromeに接続し、
On Android, connect a debuggable Capacitor build to Chrome and open chrome://inspectを呼び出す。 BrowserWindow.webContents.openDevTools() Android
生産スタックトレースは、ソースにマップされる場合にのみ有用です。各ウェブバンドルにソースマップをアップロードして保持し、シンボリケーションアーティファクトがバンドルハッシュと一致することを確認します。重要な操作のために制御されたコンソールインターセプターを追加しますが、クレデンシャル、トークン、または個人データをログに記録しないでください。操作名、リクエストID、レスポンスクラス、状態遷移をキャプチャします。
ネイティブツールに移行するには、証拠がそこに指示している必要があります。
Android StudioのLogcatをアプリケーションパッケージでフィルタリングし、最小限の可能なアクションシーケンスで再現します。 npx cap run android --livereload WebViewの変更を短縮しますが、パッケージされたネイティブアーティファクトを検証しません。iOSでは、Xcodeから実行し、デバイスログのためにデバイスウィンドウを使用します。 InstrumentsのTime Profilerは、継続的なCPU作業に役立ちます。 Allocationsは、メモリの増加を特定するのに役立ちます。
Electronには2つのデバッグ対象があります。レンダラーDevToolsを使用してDOM、JavaScript、ネットワークの動作を確認します。主プロセスでは --inspect または --inspect-brk 主プロセスでは、起動と自動更新テストの間の標準エラー出力を保存します。
症状に基づいてルーティングします。UIの動作はWebViewから始まります。ネイティブの終了はAndroid StudioまたはXcodeから始まります。Electronの起動失敗は主プロセスから始まります。
この分割がなぜ重要であるかを説明する有益な説明は CapacitorのWebViewとネイティブブリッジモデル。橋は境界であり、単一のデバッグ画面ではありません。そう扱うことで、各ログ行が答えを求める質問に答える可能性が高くなります。
ネットワーク、ストレージ、パーミッションのチェック
チームはAPIを最初にチェックすることが多いです。なぜなら、ネットワークエラーは技術的で馴染みのあるものだからです。その習慣は、古い状態、許可の宣言変更、プラットフォームアップグレードによるサンドボックス動作の変更によって引き起こされる失敗を無視します。失敗ドメインによって最速のチェックが決まります。
| 失敗ドメイン | 共通症状パターン | 最速のチェック |
|---|---|---|
| ネットワーク | データが空白、ログインループ、タイムアウト、失敗したアップロード、あるネットワークで動作するリクエストが別のネットワークでは動作しない | Run curl 同じネットワークから実行し、失敗したWebViewリクエストを検査し、CORSのプリフライト、証明書ピンニング、キャプティブポータル、プロキシの動作を確認 |
| ストレージ | 更新、再起動、またはオペレーティングシステムの変更後、機能が以前は動作していたが失敗する | ストレージのエストイメートを検査し、IndexedDBのクォータエラーを確認し、暗号化キーを比較し、Electronの userData パスを検証し、クリーンなサンドボックスをテスト |
| 権限 | カメラ、ファイル、通知、位置、またはバックグラウンドの動作が、明確なアプリケーション例外なしで失敗する | iOSの使用説明を確認し、Android ACCESS_* の宣言、Electronの許可ハンドラー、そして冷スタートの許可タイミング |
ストレージの問題については、 storage.estimate() クォータの圧力を明らかにすることができますが、すべてのデータベースの問題を診断することはできません。手動でクリーンなアプリケーションサンドボックスをテストし、次に既存のプロファイルと比較して、動作を確認してください。 Capacitor userData 設定の暗号化キーを回転すると、以前の有効な値が読み取れなくなる可能性があります。SQLiteの書き込み先頭ロギングは、突然の終了後に損傷した状態を残す可能性があります。Electronアプリケーションは、オペレーティングシステムのアップグレードによって解決された
Permissions deserve the same attention. iOS usage descriptions must match the capability being requested. Android permission behavior can drift after SDK changes, and notification prompts can race with cold-start initialization. Electron’s permission handler may reject a request before the renderer receives a useful explanation.
権限も同じ注意を払う価値があります。iOSの使用説明は、要求されている機能と一致する必要があります。Androidの許可動作は、__CAPGO_KEEP_0__の変更後も変化する可能性があり、通知の促しは冷スタートの初期化と競合する可能性があります。Electronの許可ハンドラーは、レンダラーが有用な説明を受け取る前に、要求を拒否する可能性があります。
ユーザーが「昨日は動いた」と言う場合、ストレージと権限を検査し、ネットワークが変わったと仮定するのではなく、検査してください。
CIは、ユーザーが実行するアーティファクトをテストすることで、最も安価にレグレッションを検出します。開発サーバーに対するグリーンなテストスイートは、署名されたAndroidパッケージ、iOSアーカイブ、またはElectronインストーラーが起動、バンドルを読み込み、実際の認証済みオペレーションを完了できることを証明するものではありません。
共有ロジックとシェルをテストする
使用する Vitest 共有Webロジックと Jest Electronメインプロセスの動作用に。Capacitor プラグインの場合、JavaScriptコントラクトとネイティブ実装を別々にテストし、パーミッションの拒否、利用できないハードウェア、不正なレスポンス、ライフサイクル中断の統合カバレッジを追加します。
Playwrightは、ビルドされたWebバンドルを実行できます。Electronの場合、Playwright Electronまたは同等のシェルテストを使用して、パッケージされたバイナリに対してテストし、ローカル開発プロセスによってサーバーされたレンダラーのみでテストするのではなく。パッケージテストは、ブラウザテストが隠すミッシングアセット、不正なパス、署名ミス、起動仮定を検出できます。
デバイスカバレッジは、実際のインストールベースを反映する必要があります。BrowserStackまたはSauce Labsを使用して、意図的に選択されたデバイスプロファイル、オペレーティングシステム、パーミッション状態、ネットワーク条件をテストできます。目標は、最大の行列サイズではなく、代表的な失敗カバレッジです。
失敗をマージブロックする
明示的なチェックを追加する:
- バンドル変更: 不正のバンドルサイズの差分とソースマップの欠如を拒否する。
- ネイティブの配置: プラグインのバージョン遅れと不互換な設定を検出する。
minSdkVersionアーティファクトの整合性: - 署名、パッケージの識別、埋め込まれたアセット、リリースマニフェストの検証。 起動の動作:
- パッケージされたアプリを起動し、認証済みのエンドポイントの1つの要求を完了する。 更新の動作:
- 古いバンドルをインストールし、候補の更新を適用し、再起動し、ロールバックの動作を確認する。 1つの__CAPGO_KEEP_0__ステータスチェックを通じて、赤い信号がマージをブロックするように、すべての結果を公開する。ユニットテストを通過したビルドが署名されたアーティファクトの検証に失敗した場合、失敗とみなす。完全に緑の「」ではなく。
Publish every result through one GitHub status check so a red signal blocks the merge. A build that passes unit tests but fails signed-artifact verification should be treated as failed, not “mostly green.”
The 継続的インテグレーションのセットアップはCapacitorのリリース用 は、繰り返しパイプラインにこれらのチェックを組み込むときに便利です。CIは、生産性の向上に役立つものではありませんが、ステージングに到達する欠陥の数を減らし、インシデントの際にオンコールエンジニアが不明な点を減らすことができます。
ライブアップデートを緊急回復チャネルとして
生産性の低下は、常に新しいネイティブビルドが必要ではありません。JavaScript、CSS、コピー、構成、または他のWebアセットに欠陥がある場合、ライブアップデートはユーザー体験を回復させ、チームが適切なリリースを準備するまで待つ必要があります。そのため、ライブアップデートの配信は 運用回復チャネル、ではなく、単に外観の変更のための便宜的なものではありません。
安全性の要件は、制御です。カニラ、ベータ、安定したユーザーに分離された名前のチャネルを維持し、ネイティブアプリIDと互換性のあるランタイム制約を明示し、各ユーザーが受け取るバンドルの記録を残す必要があります。ライブアップデートはネイティブの許可を追加することはできません、ネイティブのプラグインを置き換えることはできません、Electronのメインプロセスを変更することはできません、初期化が完了する前にアップデータが失敗した場合の修復はできません。そのようなケースは、ストアまたはインストーラー リリースが必要です。
ガード付きのロールアウト
緊急フローは次のようになります:
- 確認範囲: 影響を受けるネイティブバージョン、チャネル、バンドルハッシュ、失敗信号を特定する
- 最小のパッチを準備する: 失敗するパスを修復するために必要なWebの動作のみを変更する。
- ターゲットとなるカニアードアウディエンスを設定する: 失敗するパスを修復するために必要なWebの動作のみを変更する。
- テレメトリを監視する: クラッシュ、ロード、リクエスト、更新失敗のシグナルを影響を受けたコホートと比較する。
- プロモートまたはロールバックする: シグナルが健康である限り、拡大するのみ。新しい失敗を導入したパッチがロールバックされるように、直ちにロールバックする。
__CAPGO_KEEP_0__はCapacitorJSおよびElectronアプリケーション向けに署名されたWebバンドル配信、ターゲットチャンネル、デバイスごとのログ、採用率と失敗率のメトリクス、バージョン履歴、自動ロールバック保護を提供します。実際の決定ルールは直接です:
Capgo provides signed web-bundle delivery, targeted channels, per-device logs, adoption and failure metrics, version history, and automatic rollback protection for CapacitorJS and Electron applications. The practical decision rule is direct: 。. The Capacitor ライブアップデートフロー __CAPGO_KEEP_0__ ライブアップデートフローは、2 つのパス間の境界を説明します。
インシデント後の分析が次のインシデントを防ぐ
リトロスペクティブはシステムを変更することで、自分の位置を獲得します。ログ、デプロイメントコンテキスト、オペレーターの決定が利用可能な状態で書きましょう。記録は事実に基づいて、非難のないもので、もう一度インシデントを再構築することなく、もう一度エンジニアが欠けているガードレールを特定できるようにする程度の具体性が必要です。
5 つのコンクリートブロックを使用
タイムラインにタイムスタンプを付けたテレメトリ 最初の失敗したリクエスト、影響を受けたリリース、警告の作成、調査ステップ、対策、回復を記録します。Android ダッシュボード インシデントの場合、タイムラインは、iOS が有効なレスポンスを受け続けているのに対し、配置ロールアウト後に空白のビューが表示されたことを示すかもしれません。
ユーザーに視覚化された障害モード 顧客が経験したことを説明するのではなく、code が何をしたかを説明しないようにします。「Android ユーザーは、認証後に空白のダッシュボードを表示した」という説明は、リスポンダーに方向性を与えるのではなく、「API キー不一致」などの説明はそうではありません。最初の説明は、破損した旅と、検出できなかった信号を指します。
検出のギャップ チームが遅れて学んだ理由を記録します。クラッシュモニタリングは、成功したアプリのレンダリングが緑色のままだったかもしれませんが、認証済みのリクエストの失敗や空白のダッシュボード ペイロードの警告が追跡されていなかったため、検出が遅れました。欠けている信号と、そこで発生するべきだった信号を記録します。
code 以外の要因 アプリケーション構成の漂流、キャッシュの動作、デプロイのタイミング、サービス依存関係、権限の変更、またはElectronの自動更新競争。これらのドメインは、エラーがアプリケーションcodeにない場合でも、生産性の低下が発生する可能性があるため、早期のチェックが必要です。
予防的なガードレール。 問題を発見したテストまたはコントロールを割り当てます。例として、デプロイ時に生産環境のクレデンシャルを検証する、代表的なクライアントから配信された構成を確認する、またはパッケージ化されたElectronの起動テストを追加するなどです。ガードレールには、単にリトロスペクティブに記述した文だけではなく、オーナーと失敗条件が必要です。
通知パスは同じレビューに含まれます。チームにメールアラートが届かない場合は、Gmailでメールがスパムに送られないようにするための実用的なリソースを参照してください。 メールアラートが届かない場合は、通知パスの確認を実行し、成功したメッセージの作成はオペレータがメッセージを受け取ったことを証明するものではありません。 インシデントを閉じる前に、作業を割り当てます。
各ブロックに、オーナー、期限、検証方法を指定します。24時間以内にインシデントを再度レビューします。
24時間 エンジニアは、調査から仮定を挑戦することができます。新しいテスト、ダッシュボード、構成チェック、またはロールアウトルールが正常に実行された後のみ、アイテムを閉じます。この最終チェックリストを使用します。
正しいネイティブビルドとWebバンドルを特定しましたか?
- Did we identify the exact native build and web bundle?
- Capgoでは、code、構成、展開、インフラ、依存関係の原因を区別しましたか?
- テレメトリは、ユーザーに表示されるエラーだけでなく、クラッシュも表示しましたか?
- 影響を受けたチャンネルと知られている良いチャンネルをテストしましたか?
- 生産前に失敗するガードレールを追加しましたか?
- ライブアップデートまたはネイティブリリースが適切だったかどうか、ドキュメントに記載しましたか?
- 1人の所有者が修正を確認しましたか?
ユーザーの苦情は、レビューがクラッシュのみをカバーする必要があることを示しています。6,634アプリの調査で、 支払い失敗がアプリデバイスの互換性 28.6% UIとUXの摩擦 28.4%サブスクリプションのトラブル 25.4%6,634アプリの調査で 21.8%エラー、ログインエラー 17.2%、クラッシュは7位で 10.3%. (モバイルアプリケーションに関する苦情の調査) アプリケーションがクラッシュした理由を問うのみのトラブルシューティングプロセスは、支払い、サインイン、または通常の製品使用の障壁を逃す可能性があります。
安定性データは、同じ運用モデルを裏付けています。ベンチマークでは、メディアンアプリは 99.95%のクラッシュフリーのセッション、トップパフォーマンスアプリは 99.99% 、弱いアプリは 99.77%以下。 また、メディアンANR率は10,000セッションあたり2.62です、 10万回のセッションあたりのOOMレートは1.12、およびアプリハングレートは 64から103までの10万回のセッションあたり 品質レベルに応じて(モバイル安定性ベンチマーク) 高い安定性でも意味のあるエラーが残っている。チームは失敗したリクエスト、空白の状態、ハング、更新エラー、そして他のユーザー向け症状についてのテレメトリが必要です。
2026年の報告書によると、ユーザーは 基本的な機能が壊れたことについて6倍の苦情を提出し、新機能のリクエストよりも多くした、そして報告書によると 1回のクラッシュ後15.4%のユーザーがアンインストールし、2-3回のクラッシュ後半数以上のユーザーが放棄した. (2026年の報告書による壊れたアプリの基本的な機能) 実用的な対応は、広く検出すること、迅速に回復すること、そしてすべてのインシデントをテスト可能なコントロールに変えることです。
使用 Capgo Capgoにプルリクエストを送信する
