iOS Crash Reporting と Error Tracking

Docs > RUM & セッションリプレイ > モバイルおよび TV モニタリング > iOS と tvOS のモニタリング > iOS Crash Reporting と Error Tracking

概要

iOS Crash Reporting と Error Tracking を有効にすると、包括的なクラッシュレポートとエラーのトレンドを取得できます。この機能により、以下にアクセスできます:

集約された iOS クラッシュダッシュボードと属性
シンボリケート済みの iOS クラッシュレポート
iOS Error Tracking によるトレンド分析

スタックトレースをシンボリケートするには、.dSYM ファイルを見つけて Datadog にアップロードします。次に、テストクラッシュを実行してアプリケーションを再起動し、構成を検証します。

クラッシュレポートは Error Tracking に表示されます。

セットアップ

iOS SDK をまだセットアップしていない場合は、アプリ内セットアップ手順に従うか、iOS セットアップドキュメントを参照してください。

クラッシュレポーティングを追加

Crash Reporting を有効にするには、使用している依存関係マネージャに応じてパッケージを追加し、初期化スニペットを更新します。

CocoaPods を使用して dd-sdk-ios をインストールできます:

pod 'DatadogCrashReporting'

Apple の Swift Package Manager を使用して統合するには、Package.swift に次を依存関係として追加します:

.package(url: "https://github.com/Datadog/dd-sdk-ios.git", .upToNextMajor(from: "2.0.0"))

プロジェクトで、次のライブラリをリンクします:

DatadogCrashReporting

Carthage を使用して dd-sdk-ios をインストールできます:

github "DataDog/dd-sdk-ios"

Xcode で、次のフレームワークをリンクします:

DatadogCrashReporting.xcframework
CrashReporter.xcframework

初期化スニペットを更新して Crash Reporting を含める

import DatadogCore
import DatadogCrashReporting

Datadog.initialize(
  with: Datadog.Configuration(
    clientToken: "<client token>",
    env: "<environment>",
    service: "<service name>"
  ), 
  trackingConsent: trackingConsent
)

CrashReporting.enable()

アプリハングレポーティングを追加

アプリハングは、アプリケーションが長時間応答しないときに発生する iOS 固有のエラータイプです。

既定ではアプリハングのレポーティングは無効ですが、初期化パラメータ appHangThreshold を使用すると有効化でき、指定した時間を超えるアプリハングを監視するための独自のしきい値を設定できます。しきい値を調整できることで、きめ細かな観測性とノイズの多さのバランスを最適化できます。設定の詳細はアプリハングのしきい値を構成するを参照してください。

アプリハングは iOS SDK を通じてレポートされます (Logs ではありません)。

有効化すると、指定した appHangThreshold より長いメインスレッドの一時停止は、Error Tracking で ハング と見なされます。ハングには 2 種類あります:

致命的なアプリハング: ハングから回復せず、アプリが終了された場合のレポート方法です。致命的なアプリハングには、Error Tracking と RUM Explorer で「Crash」のマークが付きます。
非致命的なアプリハング: 比較的短いハングからアプリが回復し、実行を継続した場合のレポート方法です。非致命的なアプリハングには、Error Tracking と RUM Explorer で「Crash」のマークは付きません。

アプリハング監視を有効化

アプリハング監視を有効にするには:

Crash Reporting を有効化

初期化スニペットに appHangThreshold パラメータを追加して更新します:

RUM.enable(
    with: RUM.Configuration(
        applicationID: "<application id>",
        appHangThreshold: 0.25
    )
)

アプリハングをレポートしたい最小の継続時間に appHangThreshold を設定します。たとえば、少なくとも 250 ms のハングをレポートするには 0.25 を指定します。設定の考え方はアプリハングのしきい値を構成するを参照してください。
必ず、以下の手順に従って難読化解除済みのスタックトレースを取得できるようにしてください。

アプリハングのしきい値を構成する

Apple は Xcode Organizer のハング率メトリクスで 250 ms を超えるハングのみを対象とします。Datadog は、appHangThreshold の初期値として同様に 0.25 を設定し、その後、適切な設定が見つかるまで段階的に下げるまたは上げることを推奨します。
ノイズとなるハングの大半をふるい落とすには、appHangThreshold を 2～3 秒に設定することをおすすめします。
appHangThreshold に設定できる最小値は 0.1 秒 (100 ms) です。ただし、しきい値を極端に小さくすると、ハングの過剰なレポートにつながる可能性があります。
SDK はアプリハングを監視するためのセカンダリスレッドを実装しています。CPU 使用率を抑えるため、2.5% の許容誤差でハングを追跡します。そのため、appHangThreshold に近い長さの一部のハングはレポートされない場合があります。

アプリハング監視を無効化

アプリハング監視を無効にするには、初期化スニペットを更新し、パラメータ appHangThreshold を nil に設定します。

ウォッチドッグターミネーションのレポーティングを追加

Apple エコシステムでは、オペレーティングシステムがウォッチドッグメカニズムを用いてアプリケーションの健全性を監視し、応答しなくなったり、CPU やメモリなどのリソースを過剰に消費した場合に終了させます。これらのウォッチドッグターミネーションは致命的で、復旧できません (詳細は公式の Apple ドキュメントを参照)。

既定ではウォッチドッグターミネーションのレポーティングは無効ですが、初期化パラメータ trackWatchdogTerminations を使用して有効化できます。

有効化すると、次回のアプリケーション起動時に、ヒューリスティックに基づいて前回のユーザーセッションにウォッチドッグターミネーションがレポートされ、紐付けられます:

その間にアプリケーションがアップグレードされていないこと
アプリが exit も abort も呼び出していないこと
例外、または致命的なアプリハングによるクラッシュではないこと
ユーザーによって強制終了されていないこと
デバイスが再起動していないこと (OS のアップグレードを含む)

Error Tracking のサイドパネルに表示されたウォッチドッグターミネーションの例。

ウォッチドッグターミネーションのレポーティングを有効化

ウォッチドッグターミネーションのレポーティングを有効化するには:

Crash Reporting を有効化

初期化スニペットを trackWatchdogTerminations フラグで更新します:

RUM.enable(
    with: RUM.Configuration(
        applicationID: "<application id>",
        trackWatchdogTerminations: true
    )
)

ウォッチドッグターミネーションのレポーティングを無効化

ウォッチドッグターミネーションのレポーティングを無効化するには、初期化スニペットを更新し、パラメータ trackWatchdogTerminations を false に設定します。

難読化解除済みのスタックトレースを取得する

マッピングファイルはスタックトレースの難読化を解除するために使用され、エラーのデバッグに役立ちます。生成される一意のビルド ID を使用して、Datadog は正しいスタックトレースを対応するマッピングファイルに自動的に照合します。これにより、マッピングファイルのアップロード時期がいつであっても (プレプロダクションビルドでもプロダクションビルドでも)、Datadog にレポートされたクラッシュやエラーをレビューする際に、効率的な QA プロセスのための正しい情報を利用できます。

iOS アプリケーションでは、スタックトレースとシンボルファイルの照合は、それぞれの uuid フィールドに基づいて行われます。

クラッシュレポートをシンボリケートする

クラッシュレポートは生の形式で収集され、多くはメモリアドレスを含みます。これらのアドレスを可読なシンボル情報にマップするために、Datadog では dSYM ファイルが必要です。dSYM ファイルはアプリケーションのビルドまたは配布プロセスで生成されます。

.dSYM ファイルを見つける

すべての iOS アプリケーションは、各アプリケーションモジュールごとに .dSYM ファイルを生成します。これらのファイルはアプリケーションのバイナリサイズを最小化し、ダウンロード速度の向上に寄与します。各アプリケーションバージョンには .dSYM ファイル一式が含まれます。

セットアップによっては、.dSYM ファイルを App Store Connect からダウンロードするか、ローカルマシン上で見つける必要があります。

Bitcode Enabled 説明

Yes App Store Connect がアプリケーションのビルド処理を完了した後に、.dSYM ファイルが利用可能になります。

No Xcode は、アプリケーションのビルドの最後に .dSYM ファイルを $DWARF_DSYM_FOLDER_PATH に書き出します。ビルド設定 DEBUG_INFORMATION_FORMAT が DWARF with dSYM File に設定されていることを確認してください。既定では、Xcode プロジェクトは Release プロジェクト構成でのみ DEBUG_INFORMATION_FORMAT を DWARF with dSYM File に設定します。

Bitcode Enabled	説明
Yes	App Store Connect がアプリケーションのビルド処理を完了した後に、`.dSYM` ファイルが利用可能になります。
No	Xcode は、アプリケーションのビルドの最後に `.dSYM` ファイルを `$DWARF_DSYM_FOLDER_PATH` に書き出します。ビルド設定 `DEBUG_INFORMATION_FORMAT` が DWARF with dSYM File に設定されていることを確認してください。既定では、Xcode プロジェクトは Release プロジェクト構成でのみ `DEBUG_INFORMATION_FORMAT` を DWARF with dSYM File に設定します。

.dSYM ファイルをアップロードする

.dSYM ファイルを Datadog にアップロードすると、エラーに関連するスタックトレース内の各フレームのファイルパスと行番号にアクセスできます。

アプリケーションがクラッシュし、再起動されると、iOS SDK がクラッシュレポートを Datadog にアップロードします。

注: バージョンが変更されていない場合、ソースマップを再アップロードしても既存のものは上書きされません。

Datadog CI を使用して .dSYM ファイルをアップロードする

コマンドラインツール @datadog/datadog-ci を使用して、.dSYM ファイルをアップロードできます:

export DATADOG_API_KEY="<API KEY>"

// dSYM ファイルを含む zip ファイルがある場合
npx @datadog/datadog-ci dsyms upload appDsyms.zip

// dSYM ファイルを含むフォルダがある場合
npx @datadog/datadog-ci dsyms upload /path/to/appDsyms/

注: ツールを EU エンドポイントで使用するには、環境変数 DATADOG_SITE を datadoghq.eu に設定します。インテークエンドポイントの完全な URL を上書きするには、環境変数 DATADOG_DSYM_INTAKE_URL を定義します。

あるいは、ワークフローで Fastlane または GitHub Actions を使用している場合は、datadog-ci の代わりに、これらの連携を活用できます:

Fastlane プラグインを使用して .dSYM ファイルをアップロードする

Fastlane プラグインは、Fastlane 構成から Datadog に .dSYM ファイルをアップロードするのに役立ちます。

fastlane-plugin-datadog をプロジェクトに追加します。
```
fastlane add_plugin datadog
```

シンボルをアップロードするように Fastlane を構成します。

# download_dsyms action feeds dsym_paths automatically
lane :upload_dsym_with_download_dsyms do
  download_dsyms
  upload_symbols_to_datadog(api_key: "datadog-api-key")
end

詳細は fastlane-plugin-datadog を参照してください。

GitHub Actions を使用して .dSYM ファイルをアップロードする

Datadog Upload dSYMs GitHub Action を使用すると、GitHub Actions のジョブ内でシンボルをアップロードできます:

name: Upload dSYM Files

jobs:
  build:
    runs-on: macos-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Generate/Download dSYM Files
        uses: ./release.sh

      - name: Upload dSYMs to Datadog
        uses: DataDog/upload-dsyms-github-action@v1
        with:
          api_key: ${{ secrets.DATADOG_API_KEY }}
          site: datadoghq.com
          dsym_paths: |
            path/to/dsyms/folder
            path/to/zip/dsyms.zip

詳細は dSYMs コマンドを参照してください。

制限事項

各 dSYM ファイルのサイズ上限は 2 GB です。

実装をテストする

iOS Crash Reporting と Error Tracking の構成を検証するには、アプリケーションでクラッシュを発生させ、Datadog にエラーが表示されることを確認します。

アプリケーションを iOS シミュレータまたは実機で実行します。デバッガがアタッチされていないことを確認します。そうしないと、 iOS SDK より前に Xcode がクラッシュを捕捉します。

クラッシュを含むコードを実行します:

func didTapButton() {
fatalError("Crash the app")
}

クラッシュ後、アプリケーションを再起動し、 iOS SDK が Error Tracking にクラッシュレポートをアップロードするのを待ちます。

注: Error Tracking は、iOS v14+ の arm64 および arm64e アーキテクチャ向けのシステムシンボルファイルのシンボリケーションをサポートします。

iOS Crash Reporting と Error Tracking

概要

セットアップ

クラッシュ レポーティングを追加

アプリ ハング レポーティングを追加

アプリ ハング監視を有効化

アプリ ハングのしきい値を構成する

アプリ ハング監視を無効化

ウォッチドッグ ターミネーションのレポーティングを追加

ウォッチドッグ ターミネーションのレポーティングを有効化

ウォッチドッグ ターミネーションのレポーティングを無効化

難読化解除済みのスタック トレースを取得する

クラッシュ レポートをシンボリケートする