feat(symbolication): upload dart symbol mapping file

.github/workflows/integration-test.yml

@@ -58,6 +58,9 @@ jobs:
           path: temp/testapp-${{ matrix.target }}
           key: integration-test-${{ matrix.host }}-${{ matrix.target }}-${{ hashFiles('flutter.version') }}
 
+      - run: sudo xcode-select --switch /Applications/Xcode_16.4.app
+        if: ${{ matrix.target == 'ios' || matrix.target == 'ios-framework' || matrix.target == 'ipa' }}
+
       - run: dart test --tags integration
 
       - uses: actions/upload-artifact@v4

CHANGELOG.md

@@ -2,11 +2,15 @@
 
 ## Unreleased
 
-### Dependencies
+### Features
 
-- Bump CLI from v2.41.1 to v2.52.0 ([#327](https://github.com/getsentry/sentry-dart-plugin/pull/327))
-  - [changelog](https://github.com/getsentry/sentry-cli/blob/master/CHANGELOG.md#2520)
-  - [diff](https://github.com/getsentry/sentry-cli/compare/2.41.1...2.52.0)
+- Upload Dart symbol mapping file ([#347](https://github.com/getsentry/sentry-dart-plugin/pull/347))
+    - Enables symbolication of Flutter issue titles for obfuscated builds.
+    - Supported: Android and iOS
+    - Not supported (yet): macOS, Linux and Windows.
+    - Generate the mapping file: Add `--extra-gen-snapshot-options=--save-obfuscation-map=<path>` when building. Example: `flutter build apk --obfuscate --split-debug-info=build/symbols --extra-gen-snapshot-options=--save-obfuscation-map=build/mapping.json`
+    - Configure the plugin: Set `dart_symbol_map_path: build/mapping.json`
+    - Important: `dart_symbol_map_path` must point directly to the mapping file (absolute or relative path), not a directory.
 
 ## 3.1.1
 

README.md

@@ -57,6 +57,12 @@ sentry:
   build_path: ...
   web_build_path: ...
   symbols_path: ...
+  # Path to the Dart obfuscation map (opt-in)
+  # Example generation flags:
+  #   flutter build apk --obfuscate --split-debug-info=symbols \\
+  #     --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json
+  # Then set the path below to the generated obfuscation map file
+  dart_symbol_map_path: build/app/obfuscation.map.json
   commits: auto
   ignore_missing: true
 ```
@@ -95,30 +101,31 @@ ignore_missing=true
 
 ### Available Configuration Fields
 
-| Configuration Name | Description | Default Value And Type | Required | Alternative Environment variable |
-| - | - | - | - | - |
-| upload_debug_symbols | Enables or disables the automatic upload of debug symbols | true (boolean) | no | - |
-| upload_source_maps | Enables or disables the automatic upload of source maps | false (boolean) | no | - |
-| upload_sources | Does or doesn't include the source code of native code | false (boolean) | no | - |
-| legacy_web_symbolication | Uses legacy symbolication method for Flutter Web instead of Debug IDs | false (boolean) | no | - |
-| project | Project's name | e.g. sentry-flutter (string) | yes | SENTRY_PROJECT |
-| org | Organization's slug | e.g. sentry-sdks (string) | yes | SENTRY_ORG |
-| auth_token | Auth Token | e.g. 64 random characteres (string)  | yes | SENTRY_AUTH_TOKEN |
-| url | URL | e.g. https<area>://mysentry.invalid/ (string)  | no | SENTRY_URL |
-| url_prefix | URL prefix for JS source maps | e.g. ~/app/ (string) | no | - |
-| wait_for_processing | Wait for server-side processing of uploaded files | false (boolean)  | no | - |
-| log_level | Configures the log level for sentry-cli | warn (string)  | no | SENTRY_LOG_LEVEL |
-| release | The release version for source maps, it should match the release set by the SDK | name@version from pubspec (string)  | no | SENTRY_RELEASE |
-| dist | The dist/build number for source maps, it should match the dist set by the SDK | the number after the '+' char from 'version' pubspec (string)  | no | SENTRY_DIST |
-| build_path | The build folder of debug files for upload | `build` (string)  | no | - |
-| web_build_path | The web build folder of debug files for upload relative to build_path | `web` (string) | no | - |
-| symbols_path | The directory containing debug symbols (i.e. the `--split-debug-info=` parameter value you pass to `flutter build`) | `.` (string) | no | - |
-| commits | Release commits integration | auto (string) | no | - |
-| ignore_missing | Ignore missing commits previously used in the release | false (boolean) | no | - |
-| bin_dir | The folder where the plugin downloads the sentry-cli binary | .dart_tool/pub/bin/sentry_dart_plugin (string) | no | - |
-| bin_path | Path to the sentry-cli binary to use instead of downloading. Make sure to use the correct version. | null (string) | no | - |
-| sentry_cli_cdn_url | Alternative place to download sentry-cli | https://downloads.sentry-cdn.com/sentry-cli (string) | no | SENTRYCLI_CDNURL |
-| sentry_cli_version | Override the sentry-cli version that should be downloaded. | (string) | no | - |
+| Configuration Name       | Description                                                                                                                                                                                                                                                                                         | Default Value And Type                                        | Required | Alternative Environment variable |
+| ------------------------ |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ------------------------------------------------------------- | -------- | -------------------------------- |
+| upload_debug_symbols     | Enables or disables the automatic upload of debug symbols                                                                                                                                                                                                                                           | true (boolean)                                                | no       | -                                |
+| upload_source_maps       | Enables or disables the automatic upload of source maps                                                                                                                                                                                                                                             | false (boolean)                                               | no       | -                                |
+| upload_sources           | Does or doesn't include the source code of native code                                                                                                                                                                                                                                              | false (boolean)                                               | no       | -                                |
+| legacy_web_symbolication | Uses legacy symbolication method for Flutter Web instead of Debug IDs                                                                                                                                                                                                                               | false (boolean)                                               | no       | -                                |
+| project                  | Project's name                                                                                                                                                                                                                                                                                      | e.g. sentry-flutter (string)                                  | yes      | SENTRY_PROJECT                   |
+| org                      | Organization's slug                                                                                                                                                                                                                                                                                 | e.g. sentry-sdks (string)                                     | yes      | SENTRY_ORG                       |
+| auth_token               | Auth Token                                                                                                                                                                                                                                                                                          | e.g. 64 random characteres (string)                           | yes      | SENTRY_AUTH_TOKEN                |
+| url                      | URL                                                                                                                                                                                                                                                                                                 | e.g. https<area>://mysentry.invalid/ (string)                 | no       | SENTRY_URL                       |
+| url_prefix               | URL prefix for JS source maps                                                                                                                                                                                                                                                                       | e.g. ~/app/ (string)                                          | no       | -                                |
+| wait_for_processing      | Wait for server-side processing of uploaded files                                                                                                                                                                                                                                                   | false (boolean)                                               | no       | -                                |
+| log_level                | Configures the log level for sentry-cli                                                                                                                                                                                                                                                             | warn (string)                                                 | no       | SENTRY_LOG_LEVEL                 |
+| release                  | The release version for source maps, it should match the release set by the SDK                                                                                                                                                                                                                     | name@version from pubspec (string)                            | no       | SENTRY_RELEASE                   |
+| dist                     | The dist/build number for source maps, it should match the dist set by the SDK                                                                                                                                                                                                                      | the number after the '+' char from 'version' pubspec (string) | no       | SENTRY_DIST                      |
+| build_path               | The build folder of debug files for upload                                                                                                                                                                                                                                                          | `build` (string)                                              | no       | -                                |
+| web_build_path           | The web build folder of debug files for upload relative to build_path                                                                                                                                                                                                                               | `web` (string)                                                | no       | -                                |
+| symbols_path             | The directory containing debug symbols (i.e. the `--split-debug-info=` parameter value you pass to `flutter build`)                                                                                                                                                                                 | `.` (string)                                                  | no       | -                                |
+| dart_symbol_map_path     | Absolute or relative path to a Dart obfuscation map file to upload. This allows symbolication of Flutter issue titles for Android and iOS. The map file is generated by adding the following arguments to your Flutter build command: `--extra-gen-snapshot-options=--save-obfuscation-map=<path>`. | null (string)                                                 | no       | -                                |
+| commits                  | Release commits integration                                                                                                                                                                                                                                                                         | auto (string)                                                 | no       | -                                |
+| ignore_missing           | Ignore missing commits previously used in the release                                                                                                                                                                                                                                               | false (boolean)                                               | no       | -                                |
+| bin_dir                  | The folder where the plugin downloads the sentry-cli binary                                                                                                                                                                                                                                         | .dart_tool/pub/bin/sentry_dart_plugin (string)                | no       | -                                |
+| bin_path                 | Path to the sentry-cli binary to use instead of downloading. Make sure to use the correct version.                                                                                                                                                                                                  | null (string)                                                 | no       | -                                |
+| sentry_cli_cdn_url       | Alternative place to download sentry-cli                                                                                                                                                                                                                                                            | https://downloads.sentry-cdn.com/sentry-cli (string)          | no       | SENTRYCLI_CDNURL                 |
+| sentry_cli_version       | Override the sentry-cli version that should be downloaded.                                                                                                                                                                                                                                          | (string)                                                      | no       | -                                |
 
 ## Breaking Changes in v3.0.0
 
@@ -200,4 +207,6 @@ The `--split-debug-info` option requires setting a output directory, the directo
 
 Flutter's `build web` command requires setting the `--source-maps` parameter to generate source maps, See [Issue](https://github.com/flutter/flutter/issues/72150#issuecomment-755541599)
 
+If you opt into uploading a Dart obfuscation map (`dart_symbol_map_path`), ensure you build with both `--obfuscate` and `--extra-gen-snapshot-options=--save-obfuscation-map=<path>`. The map path you configure must point to the generated file.
+
 If a previous release could not be found in the git history, please make sure you set `ignore_missing: true` in the configuration if you want to ignore such errors, See [Issue](https://github.com/getsentry/sentry-dart-plugin/issues/153)

lib/sentry_dart_plugin.dart

@@ -2,11 +2,13 @@ import 'dart:convert';
 
 import 'package:file/file.dart';
 import 'package:process/process.dart';
-import 'package:sentry_dart_plugin/src/utils/extensions.dart';
 
 import 'src/configuration.dart';
+import 'src/utils/flutter_debug_files.dart';
+import 'src/symbol_maps/dart_symbol_map.dart';
 import 'src/utils/injector.dart';
 import 'src/utils/log.dart';
+import 'src/utils/extensions.dart';
 
 /// Class responsible to load the configurations and upload the
 /// debug symbols and source maps
@@ -86,7 +88,8 @@ class SentryDartPlugin {
     _addWait(params);
 
     final fs = injector.get<FileSystem>();
-    final debugSymbolPaths = _enumerateDebugSymbolPaths(fs);
+    final debugSymbolPaths =
+        enumerateDebugSearchRoots(fs: fs, config: _configuration);
     await for (final path in debugSymbolPaths) {
       if (await fs.directory(path).exists() || await fs.file(path).exists()) {
         await _executeAndLog('Failed to upload symbols', [...params, path]);
@@ -97,59 +100,9 @@ class SentryDartPlugin {
       await _executeAndLog('Failed to upload symbols', [...params, path]);
     }
 
-    Log.taskCompleted(taskName);
-  }
-
-  Stream<String> _enumerateDebugSymbolPaths(FileSystem fs) async* {
-    final buildDir = _configuration.buildFilesFolder;
-    final projectRoot = fs.currentDirectory.path;
-
-    // Android (apk, appbundle)
-    yield '$buildDir/app/outputs';
-    yield '$buildDir/app/intermediates';
-
-    // Windows
-    for (final subdir in ['', '/x64', '/arm64']) {
-      yield '$buildDir/windows$subdir/runner/Release';
-    }
-    // TODO we should delete this once we have windows symbols collected automatically.
-    // Related to https://github.com/getsentry/sentry-dart-plugin/issues/173
-    yield 'windows/flutter/ephemeral/flutter_windows.dll.pdb';
-
-    // Linux
-    for (final subdir in ['/x64', '/arm64']) {
-      yield '$buildDir/linux$subdir/release/bundle';
-    }
-
-    // macOS
-    yield '$buildDir/macos/Build/Products/Release';
-
-    // macOS (macOS-framework)
-    yield '$buildDir/macos/framework/Release';
-
-    // iOS
-    yield '$buildDir/ios/iphoneos/Runner.app';
-    if (await fs.directory('$buildDir/ios').exists()) {
-      final regexp = RegExp(r'^Release(-.*)?-iphoneos$');
-      yield* fs
-          .directory('$buildDir/ios')
-          .list()
-          .where((v) => regexp.hasMatch(v.basename))
-          .map((e) => e.path);
-    }
+    await _tryUploadDartSymbolMap();
 
-    // iOS (ipa)
-    yield '$buildDir/ios/archive';
-
-    // iOS (ios-framework)
-    yield '$buildDir/ios/framework/Release';
-
-    // iOS in Fastlane
-    if (projectRoot == '/') {
-      yield 'ios/build';
-    } else {
-      yield '$projectRoot/ios/build';
-    }
+    Log.taskCompleted(taskName);
   }
 
   Future<Set<String>> _enumerateSymbolFiles() async {
@@ -194,6 +147,22 @@ class SentryDartPlugin {
     return params;
   }
 
+  /// Upload Dart symbol map(s) if configured.
+  /// This is needed to symbolicate Flutter issue titles for obfuscated builds.
+  Future<void> _tryUploadDartSymbolMap() async {
+    const taskName = 'uploading Dart symbol map(s)';
+    Log.startingTask(taskName);
+
+    try {
+      final fs = injector.get<FileSystem>();
+      await uploadDartSymbolMap(fs: fs, config: _configuration);
+    } catch (e) {
+      Log.error('Dart symbol map upload failed: $e');
+    } finally {
+      Log.taskCompleted(taskName);
+    }
+  }
+
   Future<void> _executeNewRelease(String release) async {
     await _executeAndLog('Failed to create a new release',
         [..._releasesCliParams(), 'new', release]);