今週まで、うちのアプリがクラッシュしたことを知る手段は、誰かが教えてくれることだけでした。ほとんどの人は教えてくれません。アプリを開き直し、また落ちたら、もう開かなくなるだけです。API側は把握できていました（ERRORログはすべてチームのチャットチャンネルに流れます）。でも、スマートフォン上でのクラッシュは、私に見える場所には何の痕跡も残していませんでした。

実は、アプリにはすでに報告の仕組みがひとつありました。アプリが誰かの前にエラーメッセージを表示すると、そのメッセージをAPIの小さなエンドポイントに送り、サーバーがERRORでログに残すので、これもチャットチャンネルに届きます。きっかけは、削除が 成功していた のに行がリストに残り、もう一度タップすると「No Item matches the given query」と表示された件でした。サーバーはごく普通の404を2回記録しただけで、何も言いませんでした。この仕組みでカバーできるのは、アプリが捕まえて表示したエラーです。クラッシュは事情が違います。報告を送るはずのJavaScriptそのものが、たった今死んだのですから。

素直な解決策はSentryです。SentryのSDKはとても気に入っていて、React Nativeのクラッシュレポートが「解決済みの問題」になっているのはこのSDKのおかげです。ただ、ユーザーデータを預ける業者がまたひとつ増え、プライバシーポリシーの行がまたひとつ増え、うちの規模なら多くても1日数件のレポートのためにまた請求書が増えるのは避けたいところでした。そこでSDKはそのままに、サービスの方を置き換えました。アプリのDSNは自前のAPIを指していて、そこのDjangoアプリの小さな一部分が、送られてきたものを受け取り、グルーピングし、アラートを出し、保存します。

この記事では、その仕組みと、本物のネイティブクラッシュが実際に届くことをどう確かめたかを紹介します。

DSNのからくり

#

Sentry の DSN は https://<public-key>@<host>/<project-id> という形をしています。SDKはこれを https://<host>/api/<project-id>/envelope/ へのPOSTに変換し、キーは X-Sentry-Auth ヘッダーに入れます。sentry.io固有の要素はどこにもありません。なので、アプリに埋め込むDSNはこうなります。

https://<CRASH_REPORT_KEY>@api.example.com/1

そしてDjango側には、SDKが呼び出すパスに一致するルートを用意します。

path("api/<int:project_id>/envelope/", crash_envelope, name="crash_envelope"),

キーはすべてのバイナリに含まれるので、秘密ではありません。キーがある理由は二つで、エンドポイントにゴミが集まり始めたら変更できるようにするため、そしてサーバー側でキーが未設定なら、何でも受け入れるのではなくすべて拒否するためです。

def crash_envelope(request, project_id):
    expected = settings.CRASH_REPORT_KEY
    if not expected:
        return Response({"detail": "Crash reporting is not configured"}, status=503)
    if not hmac.compare_digest(_key(request).encode(), expected.encode()):
        return Response({"detail": "Unknown key"}, status=401)
    ...

_key は X-Sentry-Auth ヘッダーから sentry_key= を読み取り、なければクエリ文字列を見ます。SDKによってはそちらを使うためです。

SDKが送ってくるもの：エンベロープ

#

Sentryの通信フォーマットはエンベロープです。JSONのヘッダー行が1行あり、その後に任意の数のアイテムが続きます。各アイテムはJSONのヘッダー行とペイロードの組です。アイテムヘッダーに length があればペイロードはちょうどそのバイト数、なければ次の改行までです。

{"event_id":"9ec79c33...","dsn":"https://...@api.example.com/1"}
{"type":"event","length":4123}
{ ...the event JSON, 4123 bytes... }
{"type":"client_report"}
{"timestamp":1791400000.5,"discarded_events":[]}

引っかかった点が二つあります。

• ネイティブSDKは本文をgzipしますが、JavaScriptのSDKはしません。 @sentry/react-native が捕捉したJSエラーはプレーンテキストで届き、sentry-cocoaやsentry-androidからのネイティブクラッシュは Content-Encoding: gzip 付きで届きます。デコーダーはgzip、zlibでラップされたdeflate、生のdeflateに対応し、展開は1MBで打ち切ります。クラッシュイベントは数KBなので、それより大きいものはクラッシュイベントではありません。
• 長さ指定のペイロードは改行を含むことがあります。 \n で分割すると、ネイティブSDKが送るイベントがすべて壊れます。length があるときは必ずそれに従う必要があります。

パーサーは短いものです。残すのは event アイテムだけで、セッション、トランザクション、添付ファイル、クライアントレポートは受け取ったうえで捨てます。

SDKが理解できる形で応答する

#

これは思っていたより大事でした。SDKはディスク上にキューを持ち、届いたか確信が持てないものはすべて再送します。なので、サーバーの応答次第で、SDKが送り続けるかどうかが決まります。

• 200：保存できたとき、 または意図的に捨てたとき 。セッションアイテムに4xxを返すと、SDKはそれを保持したまま永遠に再送します。
• 429と Retry-After ：スロットリングしたとき。エンドポイントにはIPごとの制限（1時間に120件）があります。クラッシュループに入ったスマートフォンは起動のたびに1件送ってくるからです。SDKは429を受けると、期待どおりに間隔を空けてくれます。
• 400：壊れたエンベロープ。ログはエラーではなく警告にしています。壊れたレポートが教えてくれるのは「どこかのクライアントがおかしい」ということで、次のまともなレポートが何がクラッシュしたかを教えてくれます。

SDKは最初の送信が届いたか確信が持てないと同じイベントを再送するので、event_id にはユニーク制約を付けてあり、重複は何も言わずに無視されます。

ソースマップなしでのグルーピング

#

ここは、自作の受信側がSentryなら代わりにやってくれる判断を自分でしなければならない部分です。Sentryはスタックトレースでクラッシュをグルーピングします。でも、リリース版のHermesバンドルは難読化されているので、フレーム名は1文字になり、行や列の位置はビルドのたびに変わります。フレームでグルーピングすると、同じバグがリリースのたびに新しいissueになってしまいます。

ソースマップがない状態（最後に詳しく書きます）では、JavaScriptのエラーで一番安定しているのは型とメッセージです。そこでフィンガープリントは、例外の型とメッセージを組み合わせ、発生ごとに変わる部分をマスクしたものにしました。

_MASKS = [
    (re.compile(r"0x[0-9a-fA-F]+"), "<addr>"),
    (re.compile(r"\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b"), "<uuid>"),
    (re.compile(r"\b[0-9a-fA-F]{16,}\b"), "<hex>"),
    (re.compile(r"\d+"), "<n>"),
]

Cannot read property 'title' of undefined (reading index 3) と (reading index 17) は同じissueになります。SDKが {{ default }} を含まない独自の fingerprint を送ってきたらそちらを優先するので、デフォルトのグルーピングが合わないときはクライアント側から強制できます。例外を持たないイベントはマスクしたログメッセージで、どちらもないイベントはアプリ内の一番上のフレームでグルーピングします。ネイティブのシグナルクラッシュではメッセージが Signal 6, Code 0 のようになるので、シグナル単位でまとまります。粗いですが、シンボリケーションができるまでは正直なやり方です。

チャンネルを埋め尽くさないアラート

#

フィンガープリントごとにissueが1つでき、各レポートはその下にイベントとして保存されます。issueがERRORでログを出す（チャットのアラートが待ち受けているのはこれです）のは、次の場合だけです。

• 新しい issue
• 解決済み のissueが 再発 したとき（issueは再オープンされます）
• 10回目、100回目、1,000回目、10,000回目 の発生

通常の繰り返しはカウンターを増やすだけです。 無視 にしたissueはカウントは続けますが、アラートは一切出しません。その上にチャットのハンドラー自体のレート制限があるので、ダメなリリースでクラッシュループが起きても、届くのは壁のような大量のメッセージではなく、数件で済みます。

保存量も同じように上限を設けています。各issueは 直近50件 のイベントだけを残し、新しいものが来るたびに古いものを削除します。これで最初のグラフが壊れました。50件のイベントでは、先週どれくらいの頻度で起きていたかは分からないからです。そこで各issueに90日分の日ごとの件数も持たせ、カウンターを増やすのと同じトランザクションの中で更新するようにしました。グラフはこの件数から描き、イベントは読むためだけのものです。

自分で作るなら、小さな競合状態が二つ気にかける価値があります。まったく新しいクラッシュが同時に何台ものスマートフォンで起きると、二つのレポートが両方ともissueを作ろうとすることがあるので、フィンガープリントをユニークにして、負けた方が既存の行を読み直すようにします。また、90日の範囲は一番新しいレポートからではなく、サーバーの今日から数えます。時計がずれたスマートフォンは、来年の日付も含めてどんな日付のレポートでも送ってくる可能性があるからです。

ペイロードは128KBが上限です。超えたイベントはまずパンくずリストとデバッグ用のメタデータを削り、それでも大きければ例外、メッセージ、リリース、プラットフォームだけを残して、削ったことが分かる印を付けます。

データの除去

#

SDKは sendDefaultPii: false で動いているので、原理的にはIPアドレスもCookieもリクエストボディも送られません。それでもサーバーはこれに頼りません。保存する前に user からは id と username だけを残し、request は丸ごと捨てます。将来のSDKのバージョンや設定でこれらが送られ始めたときのためです。

実機でテストしたところ、除去すべきものがさらに二つ見つかりました。

• パンくずリストはクエリ文字列も含めたURL全体を記録します。 アプリの検索リクエストは検索語をクエリ文字列に載せて送るので、検索直後にクラッシュすると、その人が何を検索したかまで保存されていたことになります。今はサーバーがパンくずリストのURLをすべて ? で切っています。
• コンソールのパンくずリストには console.log に渡された生の引数が入っています。 アプリがたまたまログに出した任意のオブジェクトが入りうるということです。メッセージ本文は役に立つので残し、引数は捨てます。

どちらも実際のレポートを見て初めて気づいたもので、これが次の節の一番の動機です。

クライアント側

#

アプリでは、すべてが小さなモジュール1つを通ります。OTAアップデートのSDKをラップしているのと同じ理由で、OTAバンドルはネイティブモジュールが存在する前にビルドされたバイナリの上でも動くからです。RNSentry を持たないバイナリでトップレベルに import * as Sentry from "@sentry/react-native" と書くとimportの時点で例外が投げられ、画面が真っ白になります。なので、SDKは遅延して require し、それもネイティブモジュールが本当にあることを確認してからにしています。

import { NativeModules, Platform, TurboModuleRegistry } from "react-native";
import Constants from "expo-constants";

const DSN = process.env.EXPO_PUBLIC_CRASH_DSN;

function nativeModulePresent(): boolean {
  try {
    return Boolean(TurboModuleRegistry.get("RNSentry") ?? NativeModules.RNSentry);
  } catch {
    return false;
  }
}

export function initCrashReporting(): boolean {
  if (!DSN || Platform.OS === "web" || !nativeModulePresent()) return false;
  const Sentry = require("@sentry/react-native");
  Sentry.init({
    dsn: DSN,
    release: Constants.expoConfig?.version ?? "unknown",
    sendDefaultPii: false,
    tracesSampleRate: 0,
    enableAutoSessionTracking: false,
    // ...turn off the other tracing options the same way
    maxBreadcrumbs: 50,
    beforeSend(event) { /* tag the OTA bundle */ return event; },
  });
  return true;
}

扱うのはエラーだけです。サーバーはトレース、セッション、プロファイル、リプレイを保存しないので、どれも有効にしていません。DSNがなければ（開発時やE2Eのビルド）SDKは起動すらしません。ビルドプロファイルがDSNと環境（staging か production）を設定するので、どちらのビルドも同じエンドポイントに報告しつつ、区別できます。ログイン中のユーザーはアカウントIDで設定し、名前やメールアドレスは一切使いません。

エラーバウンダリには明示的な呼び出しが必要でした。Expo Routerのルートの ErrorBoundary はレンダリングエラーを捕まえて独自の画面を表示するので、そのエラーはSDKがフックしているグローバルハンドラーまで届きません。解決策は小さなラッパーで、useEffect の中で captureException を呼んでから、これまでどおりルーターのバウンダリを描画します。ルートのバウンダリにもルートごとのバウンダリにも同じものを使います。レンダリング中ではなくエフェクトの中で呼んでいるのは、再レンダリングのたびにではなく1回だけ報告するためです。ルートコンポーネントは Sentry.wrap でもラップしていて、それが例外を投げたら素のコンポーネントに戻ります。

Web向けには、全関数を無効にした .web.ts 版のモジュールを置いています。Metroがプラットフォーム別のファイルを選ぶので、SDKがWebのバンドルに入ることはありません。Webアプリには動かすべきネイティブモジュールがないからです。

ネイティブクラッシュが届くことを証明する

#

ユニットテストは手書きのエンベロープをPOSTするもので、証明できるのは、SDKが送ってくると 私が思っている ものをパーサーが処理できる、ということだけです。リリースから2日後、本番のクラッシュレポートはゼロでした。アップデートしたのはまだ3人だけだったので、ゼロでもおかしくはありません。でも「誰もクラッシュしていない」と「クラッシュが届いていない」は、サーバーから見るとまったく同じに見えます。本物を見たいと思いました。

そこで、DSNをポート8000のローカルDjangoと使い捨てのキーに向けた、Releaseビルドのシミュレーター用バイナリを作りました。

EXPO_PUBLIC_CRASH_DSN=http://localcrashtestkey0000@localhost:8000/1 \
EXPO_PUBLIC_CRASH_ENVIRONMENT=local-verify \
xcodebuild -workspace ios/MyApp.xcworkspace -scheme MyApp -configuration Release \
  -destination 'platform=iOS Simulator,id=<udid>' -derivedDataPath /tmp/iosbuild

（Debugではなく Release です。Debugビルドはdev launcherをリンクするので挙動が違いますし、ユーザーが使っているのはReleaseです。）それからインストールして起動し、数秒待ってから、本物の障害と同じやり方で強制終了させました。

xcrun simctl install booted /tmp/iosbuild/Build/Products/Release-iphonesimulator/MyApp.app
xcrun simctl launch booted com.example.myapp      # prints the pid
kill -ABRT <pid>

シミュレーターのアプリは普通のmacOSのプロセスなので、シグナルは実機とまったく同じようにSentryCrashのハンドラーに届きます。ハンドラーはレポートをディスクに書き込むだけで、プロセスが死にかけている間は何も送りません。 次の起動時 にSDKがそれを見つけて送信します。再起動すると、1秒後にシミュレーターのネットワークログに :8000 への接続が出ました。

ところがDjangoのログには何も出ず、少しの間混乱しました。開発サーバーは、私が設定していたログレベルでは2xx以外の応答しかログに出さないのです。データベースにはちゃんと入っていました。

SIGABRT: Signal 6, Code 0 | cocoa 1.4.0 iOS 27.1 iPhone19,4 handled=False
received 09:19:53, crashed 09:19:38
contexts: app, device, os, ota_updates, trace · 24 breadcrumbs

クラッシュから保存まで15秒で、そのほとんどは私が再起動していた時間です。そして本物のペイロードを見たことで、テストでは分からなかったことがいくつも分かりました。

• ユーザーIDがアカウントIDではありませんでした。 テスト用ビルドは実際にはログインしていないので、sentry-cocoaはインストールごとの独自IDを使っていました。知っておく価値があり、プライバシーの説明にも書くべきことです。レポートには、ログインしていればアカウントのID、していなければランダムなインストールIDが入ります。
• タイムゾーンがありません。 cultureコンテキストがあるものと思い込んでいました。deviceコンテキストには locale、メモリ、画面サイズ、省電力モード、カーネルのバージョンはありますが、タイムゾーンはありません。
• ネイティブクラッシュは beforeSend を通りません。 JSの beforeSend で実行中のOTAバンドルを示す ota タグを付けていますが、ネイティブクラッシュは次の起動時にネイティブSDKが組み立てるので、JSのフックを一度も通りません。ネイティブクラッシュにタグを付けるには、バンドルが分かった時点で setTag を使ってスコープに設定し、ネイティブ層に同期させる必要があります。
• パンくずリストからアプリの動きが見えました。 コンソールの警告、ビューコントローラーのライフサイクル、HTTPの呼び出し。その中には分析SDK自身による収集用エンドポイントへのリクエストも含まれていて、アプリが他にどこと通信しているかを思い出させてくれます。そしてURLにはクエリ文字列が付いていて、これで先ほどの検索語の問題に気づきました。

レポートを読む

#

レポートはDjangoの管理画面で読みます。Sentryをゆるく真似たissueページで、上部に件数とResolve / Ignore / Reopenボタン、日ごとの棒グラフ、リリース・OS・端末・OTAバンドル別の内訳があり、その下でイベントを1件ずつ、例外、フレーム（アプリのフレームは強調し、ライブラリのフレームは折りたたみます）、パンくずリスト、端末のコンテキストと一緒に表示します。新しい依存関係は要りませんでした。

作っている途中で一つ修正が出ました。ネイティブクラッシュでは「原因（culprit）」フレームが端末上のバイナリのパスになっていて、そこにインストールごとのUUIDが含まれるため、同じクラッシュが端末ごとに違って見えていました。今は 0x1000a1b2c (MyApp) のように、アドレスとバイナリ名だけを表示します。

プライバシーポリシーを、まるごと

#

クラッシュレポートは、ほぼ個人情報です。アカウントID、スマートフォンの機種、そしてアプリが死ぬ直前の1分間にその人が何をしていたか。なので、プライバシーポリシーに1段落必要でした。きちんと書くにはレポートに何が入っているかを正確に書く必要があったので、さっき見たばかりのペイロードから列挙しました。エラー、アプリのバージョンとOTAアップデート、機種、OSと言語、空きメモリと画面サイズ、直前の数十ステップ（開いた画面、 ? 以降を取り除いたWebアドレス、アプリ自身のログ）、そしてアカウントIDかランダムなインストールID。ポリシーには、レポートが自社のサーバーに届き、Sentryやその他のクラッシュレポート会社には送られないことも書いています。保存期間は表に専用の行を設けました。問題ごとに直近50件のレポートと、90日分の日ごとの件数です。

一つの段落をコードと突き合わせ始めると、残りを確認しないわけにはいきませんでした。既存のポリシーは耐えられませんでした。アカウント削除ページには、アカウントを閉じるとプッシュ通知のトークンとパスキーは即座に削除され、サーバーログは90日以内に消える、と書かれていました。どれも事実ではありませんでした。アカウントを閉じるとサインイン方法の紐付けが外れてプロフィールは匿名化されますが、プッシュ通知のトークンとパスキーは誰かが手で消すまで残りますし、ログのアーカイブにはまだ有効期限がありません。そこでポリシー全体を、コードが実際に何をしているかの棚卸しから書き直し、それらの行は今は「まだ自動では削除されません。メールでご連絡ください」となっています。安心感は減りますが、正確です。

リポジトリには今、そのためのルールがあります。ポリシーは私たちの意図ではなくコードが何をするかを書くこと、そして個人データを新たに収集・送信・保存する変更は、同じコミットでポリシーも更新すること。対象にはアプリ内の要約画面、アカウント削除ページ、そしてストアのコンソールにしか存在しないアプリストアのプライバシーフォームも含まれます。これを書き留めるきっかけになった変更が、クラッシュレポートでした。

足りないもの

#

シンボリケーション。 これが本当の穴で、sentry.ioがやっていて私がまだ置き換えていない唯一のものです。スタックはJavaScriptでは難読化され、ネイティブコードではシンボル化されていません。

• JavaScript： フレームはHermesバンドルの中を指しています。直すには、ストア向けビルドとOTAバンドルのすべてについて合成済みのHermesソースマップをリリースとバンドルをキーに保存しておき、ページを描画するときにJSのフレームに適用する必要があります。うちのクラッシュの大半はJavaScriptになるはずなので、次に取りかかるのはこれです。
• iOSのネイティブ： 命令アドレスにはビルドのdSYMが必要です。
• Android： 難読化（minification）を有効にするとJavaのフレームはR8で難読化され（mapping.txt が必要）、C++のフレームにはNDKのシンボルが必要です。

先ほど見つけた、もう少し小さな穴もあります。OTAタグは beforeSend でしか付けていないので、ネイティブクラッシュにはまだ付きません。実行中のバンドルが確定した時点でスコープに設定するのは数行ですが、まだ書いていません。

今のところ、issueから分かるのは、 何が クラッシュしたか、どのリリース、OTAバンドル、端末でか、そしてその直前に何をしていたかです。ソースの どこで かは分かりません。週に数回リリースする小さなアプリなら、これまでは型とメッセージとパンくずリストで十分に原因を見つけられています。

受信側、管理画面、テストを合わせてもコードは多くなく、すでに動いていたAPIの上に追加のコストはかかっていません。難しい部分はSDKがやってくれます。スマートフォン上でクラッシュを捕まえ、次の起動時にレポートを送り出すことです。

デバッグには本当に時間を取られます。誰でもそうだと思います。最近は自分のアプリのバグ追いでXcodeとシミュレータにこもる日が多く、そのたびに思うのは、Xcodeにはほとんど誰も触らない強力なデバッグ機能が山ほどある、ということです。この記事では、長年かけて落ち着いた自分のデバッグ手順のうち、実際に時間の節約になっている部分をまとめます。

ブレークポイントは思っているより強力

#

ほとんどの人は、ガターをクリックしてブレークポイントを置いて終わりです。でも右クリックしてみると、デバッグのやり方が変わるくらいのオプションが出てきます。

条件付きブレークポイント

#

1000件を処理するループで、347番目だけがおかしいとします。346回もブレークポイントで止まるのは時間の無駄です。

for i in 0..<users.count {
    processUser(users[i])  // ここにブレークポイントを設定、条件: i == 347
}

ブレークポイントを右クリックして条件に i == 347 を入れれば、Xcodeは条件が真のときだけ止まります。userId == "abc123" や error != nil のような条件でも同じです。

シンボリックブレークポイント

#

メソッドがどこから呼ばれているのか分からないときに使います。ブレークポイントナビゲータ（Cmd+8）で「+」ボタンをクリックし、「Symbolic Breakpoint」を選びます。

どのビューコントローラがいつロードされるか全部見たければ、シンボルを viewDidLoad にします。Xcodeがすべての呼び出しで止まります。うるさすぎるなら MyViewController.viewDidLoad のように絞り込みましょう。

私が常設しているのはこの3つです。

• UIViewAlertForUnsatisfiableConstraints：Auto Layoutの競合をその場で捕まえる
• objc_exception_throw：クラッシュする前にObjective-Cの例外で止まる
• malloc_error_break：メモリ割り当ての問題を見つける

例外ブレークポイント

#

新しいプロジェクトで最初にやるべき設定だと思います。ブレークポイントナビゲータで「+」→「Exception Breakpoint」を追加しておくと、アプリが落ちた後ではなく、何かがスローされた瞬間にXcodeが止まってくれます。

コンソールに謎のクラッシュとしてしか出てこないnilアンラップの問題を、これで何度も捕まえてきました。

ブレークポイントアクション

#

ブレークポイントは実行を止めなくてもいいんです。ブレークポイントを編集して「Add Action」をクリックすると、こんなことができます。

• 止めずに変数を出力する："User count: @(users.count)@"
• LLDBコマンドを自動実行する
• シェルスクリプトを実行する
• 音を鳴らす（めったに通らないコードパスの確認に使っています）

「Automatically continue after evaluating actions」にチェックを入れれば、ブレークポイントはフローを止めないロガーになります。

LLDB：実際に使うコンソールコマンド

#

ブレークポイントで止まったとき、下のコンソールはクラッシュログを眺めるだけの場所ではありません。あれはLLDBで、本当に便利です。

基本

#

(lldb) po user
▿ User
  - id: "123"
  - name: "John Doe"
  - email: "john@example.com"

po はオブジェクトを読みやすい形で出力します。私のLLDB利用の9割はこれです。

もう少し詳しく見たいときは p を使います。

(lldb) p user.name
(String) $R0 = "John Doe"

ローカル変数を一度に全部見るなら、こうです。

(lldb) frame variable

実行中に値を変える

#

LLDBの本領はここです。再コンパイルせずに変数を書き換えられます。

(lldb) expr user.name = "Jane Doe"
(lldb) expr index = 0

バグを見つけて、リビルドせずに修正を試したい。そんなときは変数を変えてそのまま続行すればいいわけです。エッジケースを絞り込むとき、いつもこれで値を差し替えています。

メソッドの呼び出しもできます。

(lldb) po self.refreshUI()
(lldb) expr navigationController?.popViewController(animated: true)

ナビゲーション

#

(lldb) bt              # コールスタックを表示
(lldb) frame select 3  # 別のスタックフレームにジャンプ
(lldb) continue        # 実行を続ける（または単に 'c'）
(lldb) n               # ステップオーバー（次の行）
(lldb) s               # 関数にステップイン

ウォッチポイント

#

変数がいつ変わるのか知りたければウォッチポイントです。

(lldb) watchpoint set variable user.isLoggedIn

コードのどこから変更されても、その瞬間に実行が止まります。想定外の状態変更を追うときには手放せません。

Console.app：隠れたデバッグツール

#

Xcodeのコンソールで十分な場面は多いですが、システムログもクラッシュレポートも全部見たい、となったらConsole.appの出番です。

OSLogを使っていれば（使うべきです）、Console.appでログを検索したりフィルタしたりできます。

import os.log

let logger = Logger(subsystem: "com.example.app", category: "networking")

logger.info("Starting API request")
logger.debug("Request URL: \(url.absoluteString)")
logger.error("Failed to decode: \(error.localizedDescription)")

Console.app側の手順はこうです。

1. シミュレータか接続中のデバイスを選ぶ
2. サブシステムで絞る：subsystem:com.example.app
3. レベルで絞る：subsystem:com.example.app AND level:error

よく使うフィルタ述語は保存できます。私はネットワークリクエスト用、データベース操作用、エラーと警告だけを出す用の3つを持っています。

print()ではなくOSLogを使う理由

#

OSLogは、print() をあちこちに撒くよりずっとましです。構造化されているのでレベルやカテゴリで絞り込めますし、ログ自体が最適化されていてアプリを遅くしません。本番では機密データを自動でマスクしてくれて、アプリが落ちた後もログは残ります。

とっさの確認には print() で構いません。後で見返す可能性があるものはOSLogに残しましょう。

Console.appの高度なフィルタリング

#

Console.appはかなり凝った述語クエリに対応しています。私がよく使うのはこのあたりです。

# アプリ内のすべてのエラーと障害
subsystem:com.example.app AND (level:error OR level:fault)

# 失敗したネットワークリクエスト
subsystem:com.example.app AND category:networking AND eventMessage CONTAINS "failed"

# 過去5分間のすべて
subsystem:com.example.app AND timestamp >= now(-5m)

ログはエクスポートしてバグレポートに添付することもできます。Xcodeのコンソールからコピペするよりずっと楽です。

ビューデバッグ

#

UIが壊れているのに原因が分からないとき、いちばん早いのはビューデバッガです。

アプリを実行して壊れた画面まで進み、Xcodeのデバッグバーで「Debug View Hierarchy」をクリックします（またはCmd+Shift+D）。ビュー階層全体が3Dで分解表示されます。

回してみると、いろいろ見えてきます。

• 他のビューの裏でレンダリングされているビュー
• 画面のはるか外にいるビュー
• サイズがゼロのビュー
• 選択したビューの制約チェーン全体

私はこれで、タップイベントを吸い込んでいた透明なボタンや、0x0でレンダリングされていたラベル、いつの間にか幅10,000ピクセルになっていた画像を見つけたことがあります。

Auto Layoutのデバッグ

#

ビュー階層に紫の警告アイコンが出ていたら制約の競合です。クリックすると、どの制約同士がぶつかっているのかXcodeが正確に教えてくれます。

制約には識別子を付けておきましょう。

heightConstraint.identifier = "ProfileImageHeight"

制約が壊れたとき、エラーにメモリアドレスではなく "ProfileImageHeight" が出るようになります。ログの読みやすさが段違いです。

LLDBから制約ツリーを出力することもできます。

(lldb) po view.hasAmbiguousLayout
(lldb) po view._autolayoutTrace()

時間を節約してくれるシミュレータ機能

#

スローアニメーション

#

Debug → Slow Animations で、すべてが1/10の速度になります。トランジション中に何が起きているのか、アニメーションがなぜ変に見えるのかを確かめるのにちょうどいいです。

メモリ警告のシミュレート

#

Debug → Simulate Memory Warning。メモリ不足のときのアプリの挙動をテストできます。これで画像キャッシュのバグをいくつも見つけました。メモリ警告が来るまでは普通に動いているのに、来た途端に画像が全部消えるやつです。

Network Link Conditioner

#

Xcode → Open Developer Tools → Network Link Conditioner

3GやLTE、高パケットロス、完全オフラインをシミュレートできます。WiFiでは平気なAPIリクエストがモバイル回線でタイムアウトする、という経験があるなら、原因はこれで再現できます。

私は遅延500ms・パケットロス10%の「Bad Network」プロファイルを常備しています。速いオフィスWiFiでは絶対に出ない、タイムアウトのバグやローディング表示の問題が引っかかります。

ステータスバーのオーバーライド

#

シミュレータのステータスバーを右クリックすると、時刻、バッテリー残量、電波強度、キャリアを上書きできます。スクリーンショットを揃えたいときや、バッテリー残量ごとのUI確認に便利です。

位置情報のシミュレーション

#

Debug → Location で、机から動かずにいろいろな場所を再現できます。任意の座標、街歩き、高速道路の走行まで一通り揃っています。位置情報を使う機能のテストや、特定の地域でしか起きない不具合の調査で重宝します。

メモリデバッグ

#

Debug Memory Graph

#

Debug Memory Graphボタン（Cmd+Shift+M）を押すと、メモリ上のすべてのオブジェクトとその参照関係、そして肝心の「どれがリークしているか」をXcodeが見せてくれます。

紫のビックリマークがリークです。クリックすると保持サイクルが見えます。

いちばんよく見かけるリークはこれです。

class ViewController: UIViewController {
    var onComplete: (() -> Void)?

    func setupHandler() {
        onComplete = {
            self.dismiss(animated: true)  // ❌ selfを強く参照
        }
    }
}

weak selfで直します。

onComplete = { [weak self] in
    self?.dismiss(animated: true)  // ✓ 保持サイクルなし
}

デリゲートもweakにしておきます。

weak var delegate: ManagerDelegate?  // 単なる 'var' ではなく

Instruments

#

本腰を入れてメモリを調べるならInstrumentsです（Product → Profile、またはCmd+I）。

Allocationsを使うと、オブジェクトの割り当てすべて、時間経過に伴うメモリの増え方、どのクラスがメモリを食っているか、割り当てが起きた場所のスタックトレースまで見えます。

私が探すのはだいたい、時間に比例して増え続けるメモリ（ほぼリークです）、想定外に大きい割り当て（画像1000枚をうっかり一気に読んでいないか？）、解放されているはずなのに残っているオブジェクト、この3つです。

操作の前後で世代をマークして（小さな旗のボタン）、残ってはいけないものが残っていないか確認しましょう。

パフォーマンスプロファイリング

#

Time Profiler

#

Product → Profile → Time Profiler。アプリで重い操作をしながら記録して、コールツリーを読みます。

「Self Weight」でソートするとボトルネックが見つかります。ある関数のself weightが40%なら、時間はそこに消えています。

以前、JSONのパース関数が毎秒1000回呼ばれているのを見つけたことがあります。バックグラウンドキューに移したら、UIのカクつきが止まりました。

Main Thread Checker

#

バックグラウンドスレッドでのUI更新は、Xcodeが自動で捕まえてくれます。こんな表示が出たら、

Main Thread Checker: UI API called on a background thread: -[UILabel setText:]

こういうことをやってしまっています。

URLSession.shared.dataTask(with: url) { data, response, error in
    self.label.text = "Loaded"  // ❌ クラッシュ！
}

直すとこうなります。

URLSession.shared.dataTask(with: url) { data, response, error in
    DispatchQueue.main.async {
        self.label.text = "Loaded"  // ✓
    }
}

ランタイム診断

#

Edit Scheme → Run → Diagnostics。ここに並んでいるチェックボックスは、手作業では絶対に見つからないバグを捕まえてくれます。

Address Sanitizer

#

メモリ破壊を見つけます。use-after-free、バッファオーバーフロー、メモリリーク。アプリは2〜3倍遅くなりますが、他の方法ではほぼ追跡不可能なバグを捕まえてくれます。たまにしか起きないクラッシュを追うときにオンにします。

Thread Sanitizer

#

データ競合とスレッド絡みの問題を捕まえます。有効にしてアプリを普通に触っているだけで、競合状態があればThread Sanitizerが見つけてくれます。

Address SanitizerとThread Sanitizerは同時に使えないので、妙なクラッシュを追うときは交互に切り替えています。

Zombie Objects

#

解放済みオブジェクトへのメッセージを捕まえます。有効にしておくと、解放されたメモリに触った瞬間をXcodeが正確に教えてくれます。

*** -[MyViewController viewDidLoad]: message sent to deallocated instance 0x600001234000

つけっぱなしは禁物です。オブジェクトが解放されなくなるので、メモリは増える一方になります。ただ、特定のuse-after-freeバグを突き止めるには最高です。

よくあるデバッグシナリオ

#

起動時にクラッシュする

#

まず例外ブレークポイントを追加します。たいていはこれで捕まります。

だめなら、Info.plistのキー漏れ、初期化コードでの強制アンラップ、依存性注入の失敗あたりを疑います。

UIが更新されない

#

毎回、原因はこのどれかです。

1. 更新がメインスレッドで行われていない
2. アウトレットがつながっていない
3. ビューがそもそも表示されていない（LLDBで po view.window を確認。nilなら階層に入っていません）

テーブルビューやコレクションビューなら、reloadData() の呼び忘れです。

メモリ警告でアプリが落ちる

#

Instruments Allocationsで何がメモリを掴んでいるか確認します。たいていは、キャッシュから解放されない画像、解放されないビューコントローラ（保持サイクル）、際限なく育つ配列や辞書のどれかです。

シミュレータでメモリ警告をシミュレートして、クリーンアップ処理をテストしておきましょう。

原因不明のクラッシュ

#

サニタイザーを全部オンにします。間欠的ならたぶんスレッドの問題なのでThread Sanitizerで、システムフレームワーク内で落ちているならたぶんメモリ破壊なのでAddress Sanitizerで走らせます。

再現できないクラッシュ

#

クラッシュが他人のスマホで起きた場合でも、レポートはたいていどこかに残っています。TestFlightやApp Storeのビルドなら、XcodeのOrganizer（Window → Organizer → Crashes）に、解析データの共有をオンにしているユーザーのクラッシュレポートが集まってきます。ビルドと一緒にdSYMもアップロードしてあれば、シンボル化された状態で見られます。テスターの端末なら、レポートは端末そのものの「設定 → プライバシーとセキュリティ → 解析および改善 → 解析データ」に、アプリ名で始まる .ips ファイルとして残っているので、AirDropで送ってもらいましょう。まずはクラッシュしたスレッドのスタックトレースを読み、そこから上のシナリオを順に当たっていきます。

シミュレータでOTA更新をデバッグする

#

私のアプリはOTA（Over-the-Air）アップデートを配信しているのですが、このフロー全体のデバッグにはシミュレータがいちばん手軽です。

まずネットワークトラフィックを見ます。アプリのサブシステムで絞ったConsole.appに、マニフェストのリクエストとレスポンスがリアルタイムで流れてくるので、どのヘッダーを送っていてサーバーが何を返しているかが正確に分かります。

次に、わざとネットワークを悪くします。Network Link Conditionerで、遅い回線やパケットロスのときに更新フローがどう振る舞うかを確かめます。アプリは固まらないか。ローディング表示は出るか。ちゃんとフォールバックするか。

更新チェックの周辺にはログを仕込みます。チェック開始時、更新があったとき、ダウンロード開始時、新しいバンドルのロード時、それぞれで記録しています。

import os.log

let logger = Logger(subsystem: "com.example.app", category: "updates")

logger.info("Checking for updates...")
let update = try await Updates.checkForUpdateAsync()
logger.info("Update available: \(update.isAvailable)")

最後に、マニフェストのエンドポイント単体もテストしておくと安心です。アプリが送るのと同じヘッダーでcurlできます。

curl -H "expo-protocol-version: 1" \
     -H "expo-platform: ios" \
     -H "expo-runtime-version: 1.0.0" \
     https://updates.example.com/manifest

クライアント側を掘り始める前に、サーバーが正しいデータを返しているかをここで確認できます。

サードパーティツール

#

Charles Proxy / Proxyman

#

ネットワークトラフィックの全表示、リクエストとレスポンスの改変、エラー条件のテスト。APIデバッグには欠かせません。

ProxymanはCharlesよりUIがよく、macOSに馴染む感じがします。去年乗り換えて、戻る気はありません。

Reveal

#

Xcodeのビューデバッガに似ていますが、もっと強力です。Xcodeにつながずに実機で動くので、テスターの端末でレイアウト問題を追うのに向いています。

シミュレータと実機の違い

#

デバッグの大半はシミュレータでやっています。ケーブルも署名もいらず、インストールを待つ必要もないので速いからです。とはいえ、シミュレータの正体はMacのプロセッサの上で動くiOSのビルドで、メモリもネットワーク接続もMacのものをそのまま使っています。スマホの上でしか起きないバグは、そこでは出てきません。

なので、ロジックの組み立てとデバッグはシミュレータで済ませ、リリース前にはサポート対象の中でいちばん古いiPhoneでアプリを動かしています。パフォーマンス、メモリの逼迫、ハードウェアに触れる部分は、実機で動かすまでは本当の意味でテストしたことになりません。

実機で動かす

#

iPhoneをつないで実行先に選び、Signing & Capabilities でチームを設定します（自分のスマホで動かすだけなら無料のApple IDで足ります）。iOS 16以降は、スマホ側でも「設定 → プライバシーとセキュリティ」でデベロッパモードをオンにする必要があり、初回は再起動がかかります。オンにすると、スマホ自体の「設定 → デベロッパ」メニューにNetwork Link Conditionerが現れ、Macと同じ悪条件のネットワークプロファイルが使えるようになります。

ワイヤレスデバッグ

#

一度だけUSBでつなぎ、Window → Devices and Simulators で「Connect via network」にチェックを入れて、ケーブルを抜きます。同じWiFiにいる限り、デバイスはXcodeから見え続けます。

Device Console

#

Window → Devices and Simulators → Open Console。システムログ、アプリログ、クラッシュレポートと、何でも見えます。Xcode側のコンソールよりずっと詳細です。

テスターから「アプリが落ちた」と言われたら、必ずデバイスをつないでコンソールログを取らせてもらいます。すべてを説明してくれるシステムレベルのエラーが残っていることが多いんです。

実際のデバッグ手順

#

1. 例外ブレークポイントがなければ追加する
2. バグを再現する
3. 怪しい場所の近くにブレークポイントを置く
4. LLDBの po で値を確認する
5. 変数を書き換えて、再コンパイルせずに修正を試す
6. UI絡みならビュー階層を見る
7. パフォーマンス絡みならInstrumentsでプロファイルする
8. メモリかスレッド絡みならサニタイザーをオンにする

コツは症状から逆算することです。クラッシュ？例外ブレークポイント。遅い？Time Profiler。メモリ？Instruments。UIが変？ビューデバッガ。

もっと早く知りたかったこと

#

アサーションを使いましょう。ロジックの誤りがバグになる前に捕まります。

assert(users.count > 0, "Users array should never be empty here")

デバッグを始める前にコミットしておくこと。仮説を試すためにあちこち書き換え始めると、必ず戻したくなります。

終わったらprint文は消すこと。少なくとも #if DEBUG で囲んでおきましょう。古いデバッグログは、次のバグを見えにくくします。

LLDBはちゃんと覚えること。アプリを20回リビルドするより速いです。

そして、シミュレータは本物の電話ではありません。実機でしか出ないバグは、ほぼ例外なくスレッドかメモリの問題です。あるいはパフォーマンスの問題。シミュレータはiPhoneのチップではなくMacのCPUで動いていますから。

常に開いているツール

#

• Xcode（当然）
• アプリのサブシステムで絞ったConsole.app
• ネットワークデバッグ用のProxyman
• 事態が深刻になってきたらInstruments

どのツールも万能ではありません。ビューデバッガはメモリリークを見つけてくれませんし、InstrumentsはAuto Layoutの競合を解いてくれません。結局のところ、腕の見せどころは症状に合ったツールを選ぶことで、それは回数をこなすうちに身につきます。保持サイクルを何度も踏めば、スタックトレースを見た瞬間に匂いで分かるようになります。デバッグが楽しくなることはたぶんないですが、少なくとも苦行ではなくなります。