Flutter Dartエラーのシンボル化

--split-debug-info（--obfuscateの有無にかかわらず）を使用してFlutterアプリをビルドする場合、アプリが報告するDartのスタックトレースには、関数名、ファイル名、行番号の代わりにメモリアドレスが含まれます。そのビルドに一致するデバッグシンボルファイルを提供すると、New Relicはブラウザでこれらのスタックトレースをシンボル化できます。ブラウザ内でのシンボル化は、処理された例外にのみ適用されます。

このページでは、以下について説明します：

• シンボリケーションが必要な場合
• シンボルファイルの生成方法
• New Relic UIでスタックトレースをシンボル化する方法
• Flutter CLIを使用してローカルでシンボル化する方法
• リリースした任意のバージョンのエラーをシンボル化できるようにシンボルファイルを保存する方法

シンボリケーションが必要な場合

この表は、リリースのビルド方法に基づいて、シンボリケーションが必要になるタイミングを示しています：

シンボル化されていないDartのスタックトレースは次のようになります：

*** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
pid: 24564, tid: 532322394208, name 1.ui
os: android arch: arm64 comp: yes sim: no
build_id: '7a3ef930539e62583fa36f07eb2df79c'
isolate_dso_base: 7887a27000, vm_dso_base: 7887a27000
isolate_instructions: 7887b1da40, vm_instructions: 7887b07000
 #00 abs 0000007887d2ea63 virt 0000000000307a63 _kDartIsolateSnapshotInstructions+0x211023
 #01 abs 0000007887d39077 virt 0000000000312077 _kDartIsolateSnapshotInstructions+0x21b637
 #02 abs 0000007887b2d2cf virt 00000000001062cf _kDartIsolateSnapshotInstructions+0xf88f
 #03 abs 0000007887d38eeb virt 0000000000311eeb _kDartIsolateSnapshotInstructions+0x21b4ab

New Relic UIでは、これらの各行はスタックトレース内の個別の行として表示され、unparsedというラベルが付けられます。

スタックトレースヘッダーを理解する

トレースの最初の6行はスタックフレームではありません。これらは、Dartランタイムがすべてのシンボル化されていないトレースの先頭に書き込む、プロセスとビルドに関するメタデータです：

アプリを実行するたびにアドレス値は変わるため、同じエラーが2回発生しても異なる値が表示されることがあります。シンボリケーションは、ビルドIDとこれらのアドレスを使用して、各フレーム（#00、#01、...）のソースの場所を特定します。

ヘッダー行はコード位置ではないため、シンボル化されることはありません。シンボルファイルをアップロードする前後でunparsedというラベルが付けられたままであり、エラーをエクスポートする際にも変更されずに含まれます。その下にある番号付きフレームのみが変更されます。

Flutterのシンボルファイルを理解する

Flutterアプリはコンパイルされたコードの複数のレイヤーで構成されており、各レイヤーには独自のデバッグシンボルファイルがあります。各ファイルは自身のレイヤーからのエラーのみをシンボリケーションするため、Flutterリリースでは複数のシンボルファイルが生成されます：

New Relicは、Dartエラーをシンボリケートするために.symbolsファイルのみを使用します。dSYM、mapping.txt、またはnative-debug-symbols.zipをDartエラーにアップロードしても、シンボリケートされません。ただし、リリースが報告するあらゆる種類のエラーをシンボリケートできるように、リリースごとにそれらをすべて保持してください。

シンボルファイルの生成

リリースをビルドする際、Flutterはシンボルファイルを作成します。すでに出荷されたビルドに対して、後からこれらを作成することはできません。

$
# Android App Bundle
$
flutter build appbundle --release --obfuscate --split-debug-info=build/symbols/1.4.2+57
$

$
# Android APK
$
flutter build apk --release --obfuscate --split-debug-info=build/symbols/1.4.2+57
$

$
# iOS (App Store / TestFlight archive)
$
flutter build ipa --release --obfuscate --split-debug-info=build/symbols/1.4.2+57
$

$
# iOS (app bundle only)
$
flutter build ios --release --obfuscate --split-debug-info=build/symbols/1.4.2+57

New Relicでスタックトレースをシンボリケートする

エラーを開く

いずれかの場所からDartエラーを開いてください：

• one.newrelic.com > Errors Inbox、次にエラーを選択します。
• one.newrelic.com > Mobile > (select your app) > Handled exceptions、次にエラーを選択します。

Stack traceセクションまでスクロールします。

エラーのappVersionとappBuildを確認してください。これらにより、どのリリースのシンボルファイルが必要かがわかります。

一致するシンボルファイルをアップロードする

スタックトレースの上にあるNot seeing what you expected?バナーでは、オンデマンドのシンボル化を利用できます。Upload .symbols fileをクリックし、エラーのビルドIDとアーキテクチャーに一致する.symbolsファイルを選択します。

結果を確認またはエクスポートする

シンボリケーションが完了すると、バナーがSymbolicated your traceに変わり、解決されたフレーム数（例：Symbolicated 4 of 4 unresolved frames）が報告されます。解決された各フレームには、ファイル、行番号、関数が表示されるようになります（例：main.dart line 81 in ._testFetch()）。

最初の6行（スタックトレースヘッダー）は、unparsedというラベルのままです。これは想定された動作です：これらはプロセスとビルドに関するメタデータであり、コードの場所ではありません。

結果はページが開いている間のみ保持されます。保持するには、Export handled exception detailsをクリックします。エクスポートにはシンボル化されたフレームが含まれるため、チケットに添付したり、チームと共有したりできます。

別のエラーをシンボル化するには、そのエラーを開き、シンボルファイルを再度アップロードしてください。1つのエラーの結果は、他のエラーには引き継がれません。

適切なシンボルファイルを見つける

各シンボルファイルは、1つのビルドと1つのCPUアーキテクチャーにのみ属します。これらを使用して、正しいファイルを選択します：

1. リリース：エラーのappVersionおよびappBuildを、そのリリース用に保存したシンボルフォルダーと一致させてください。

2. アーキテクチャー：スタックトレースヘッダーのarch行目をファイル名と一致させます。たとえば、Androidでのarch: arm64はapp.android-arm64.symbolsを意味します。最新のAndroidスマートフォンのほとんどはarm64です。古いデバイスや低価格のデバイスはarmである場合があります。

3. ビルドID：スタックトレース内のbuild_idは、シンボルファイル内のビルドIDと一致する必要があります。Androidのシンボルファイルの場合、macOSまたはLinuxでfileコマンドを使用してビルドIDを読み取ることができます。これはBuildIDの値です：

   bash

   コピー

   $
   file app.android-arm64.symbols
   $
   # app.android-arm64.symbols: ELF 64-bit LSB shared object, ARM aarch64, ..., BuildID[md5/uuid]=7a3ef930539e62583fa36f07eb2df79c, with debug_info, not stripped

   iOSシンボルファイルではfileの出力にBuildIDが表示されないため、iOSの場合は、リリースと、ファイルをアップロードする際にNew Relicが実行するチェックを頼りにしてください。

New Relicは、AndroidとiOSの両方のエラーについて、ビルドIDを確認します。異なるビルドのシンボルファイルをアップロードした場合、New Relicはフレームをシンボル化できず、ファイルのビルドIDがトレースのビルドと一致しないというメッセージとともにWe couldn't symbolicate this traceが表示されます。エラーが発生した正確なビルドのファイルをアップロードしてください。

次を使用してローカルでシンボリケートする flutter symbolize

New Relic UIを使用できない場合、またはスクリプトで多くのトレースをシンボル化したい場合は、代わりにFlutter CLIを使用できます：

1. ヘッダー行（*** *** ***、pid、os/arch、build_id、isolate_dso_base、およびisolate_instructions）を含めてエラーからスタックトレースをコピーし、たとえばtrace.txtなどのファイルに保存してください。

2. 一致するシンボルファイルを使用してflutter symbolizeを実行します：

   bash

   コピー

   $
   flutter symbolize \
   >
     --input=trace.txt \
   >
     --debug-info=build/symbols/1.4.2+57/app.android-arm64.symbols \
   >
     --output=trace-symbolicated.txt

   長い--debug-infoオプションを使用してください。Flutterのグローバルオプションの中で、-dは"device"を意味するため、短い形式は混同されやすくなります。

ベストプラクティス：すべてのリリースでシンボルを保存する

New Relicはシンボルファイルを保持しないため、ご自身で保存する必要があります。エラーが発生した後ではなく、各リリースをビルドする際に保存してください：すでに出荷したビルド用に再作成することはできません。

• 内部ビルド、ベータビルド、およびストアビルドを含め、配布するすべてのビルドのシンボルファイルを保持してください。
• .symbolsファイルだけでなく、すべての種類のシンボルファイルを保持してください。「Flutterシンボルファイルについて」を参照してください。
• 各ビルドのすべてのアーキテクチャーを保持してください。
• エラーに対して適切なファイルを見つけられるように、アプリが報告するappVersionおよびappBuild属性に合わせて、バージョンとビルド番号でラベル付けしてください。
• そのバージョンが使用されている間は、それらを保持してください。ユーザーは何ヶ月も古いバージョンを使い続けることがよくあります。
• アクセスを制限します。シンボルファイルはコードの構造を明らかにします。ソースコードと同じアクセス制御で保存してください。

どこに保存するかは任意です。たとえば、CIシステムのビルドアーティファクト、ストレージバケット、アーティファクトリポジトリなどです。CIビルドアーティファクトを使用する場合は、CIシステムがそれらを保持する期間を確認してください。多くのシステムでは、一定時間後に自動的に削除されるためです。

トラブルシューティング

制限

• シンボル化はDartエラーに適用されます。ネイティブAndroid（Java/Kotlin）およびiOSのクラッシュでは、AndroidおよびiOSのシンボル化ワークフローを使用します。
• 結果は保存されず、エラー間で共有されることもありません。エラーを表示するたびに、各エラーのシンボルファイルをアップロードする必要があります。