New Relicでは、Flutterアプリ向けのエージェントを提供しており、Dartで発生したエラーをスタックトレース付きで収集できます。一方で、リリースビルドで --split-debug-info や --obfuscate を指定している場合、送られてくるスタックトレースは関数名や行番号ではなくメモリアドレスの羅列になり、どこでエラーが起きたのか読み取れません。

このような場合に、ビルド時に生成されたシンボルファイルをNew RelicのUIでアップロードすると、ブラウザ上でスタックトレースをシンボル化できます。手順はSymbolicate Flutter Dart errorsとしてドキュメントにまとめられています。

本記事では、Flutterエージェントのサンプルアプリを使い、AndroidとiOSそれぞれでシンボル化までの流れを確認していきます。

検証環境

  • Flutter: 3.41.3
  • newrelic_mobile(Flutterエージェント): 1.3.5

サンプルアプリには、newrelic-flutter-agent リポジトリの example を使用します。

シンボルファイルの生成

スタックトレースのシンボル化が必要になるのは、リリースビルド時に --split-debug-info を指定した場合です。このオプションを指定すると、Dartのデバッグ情報がアプリ本体から切り離され、指定したディレクトリに .symbols ファイルとして出力されます。その結果、アプリから送られるスタックトレースは、関数名・ファイル名・行番号の代わりにメモリアドレスが並ぶ形になります(--obfuscate を併用した場合も同様です)。

それでは、実際に --split-debug-info と --obfuscate を指定してリリースビルドを行い、シンボルファイルを生成してみましょう。 今回は管理しやすくするため、--build-name と --build-number も引数で指定します。出力先をバージョンとビルド番号ごとに分けておくと、後からどのファイルを使えばよいか迷わずに済みます。

# Android
flutter build apk --release --obfuscate \
  --split-debug-info=build/symbols/android/1.0.3+1 \
  --build-name=1.0.3 --build-number=1

# iOS
flutter build ios --release --obfuscate \
  --split-debug-info=build/symbols/ios/1.0.3+1 \
  --build-name=1.0.3 --build-number=1

ビルドが終わると、指定したディレクトリに .symbols ファイルが出力されます。

$ ls build/symbols/android/1.0.3+1/
app.android-arm.symbols   app.android-arm64.symbols app.android-x64.symbols

$ ls build/symbols/ios/1.0.3+1/
app.ios-arm64.symbols

AndroidはAPKに複数のアーキテクチャ用のコードが含まれるため、アーキテクチャごとにファイルが作られます。一方、iOSはFlutterのリリースビルドが実機(arm64)でのみ動作するため、ファイルは1つです。

エラーの送信

次に、ビルドしたアプリを端末にインストールし、エラーを発生させます。サンプルアプリの「Go To page 2」をタップし、「Error Demo」画面に遷移。「Record Error with Attributes」ボタンをタップすることで、エラーが発生し、UI上のHandled exceptionsにエラーが表示されます。

対象のエラーを選択し、スタックトレースを見てみるとシンボル化前は、すべての行が unparsed と表示されています。

先頭の6行はスタックフレームではなく、プロセスやビルドに関するヘッダー情報です。このうち、シンボル化の際に見ておきたいのは次の2行です。

  • arch: 端末のCPUアーキテクチャです。アップロードするファイルを選ぶ際に使います(arm64 なら app.android-arm64.symbols)。
  • build_id: エラーを発生させたビルドのIDです。アップロードするファイルのbuild IDと一致している必要があります。

Androidの場合、.symbols ファイルのbuild IDは file コマンドで確認できます。

$ file build/symbols/android/1.0.3+1/app.android-arm64.symbols
build/symbols/android/1.0.3+1/app.android-arm64.symbols: ELF 64-bit LSB shared object, ARM aarch64, version 1 (SYSV), dynamically linked, BuildID[md5/uuid]=7a3ef930b78595063fa36f0744766f22, with debug_info, not stripped

New Relic UIでのシンボル化

では、実際にシンボル化してみます。スタックトレースの上にある「Not seeing what you expected?」のバナーから Upload .symbols file をクリックし、app.android-arm64.symbols を選択します。

14087-android-symbolicate

バナーが「Symbolicated your trace」に変わり、スタックトレースにファイル名・行番号・関数名が表示されました。たとえば main.dart line 427 in .Page2Screen.foo() と表示されており、foo() の中で recordError を呼んでいる箇所であることがわかります。

iOSでも同様に、app.ios-arm64.symbols をアップロードすることでシンボル化が行えます。

シンボル化の際に気をつけたい箇所

シンボル化の処理はブラウザ内で行われ、シンボルファイルやシンボル化されたスタックトレースはNew Relic側には保存されません。そのため、シンボルファイルは開くエラーごとに個別にアップロードする必要があり、ページを再読み込みしたり、後で再度アクセスしたりするたびにアップロードし直す必要があります。

シンボルファイルの保存についてのベストプラクティスはドキュメントにも記載されているので、あわせてご確認ください(Best practice: Store symbols for every release)。

まとめ

本記事では、--split-debug-info や --obfuscate を指定してビルドしたFlutterアプリのDartエラーを、New Relic UI上でシンボル化する流れを確認しました。ビルド時に出力される .symbols ファイルを保管しておけば、エラーが発生したファイルや行番号を特定できます。

また、公式ドキュメントには、シンボルファイルの種類ごとの役割や、flutter symbolize を使ってローカルでシンボル化する方法もまとめられていますので、あわせて確認してみてください。