From aa1a8963aa33205cb76f36b47d205389be6a9316 Mon Sep 17 00:00:00 2001 From: Alexey Karimov Date: Thu, 12 Nov 2026 14:54:27 +0500 Subject: [PATCH 1/2] Turn the native symbol upload on and document every debug symbol The Bugsee Gradle plugin has ndk.enabled OFF by default, so a native crash in a release build (libflutter.so or any other .so) reached the backend as raw addresses while the README said nothing else was needed. The example now sets `bugsee { ndk { enabled.set(true) } }` (the release build registers uploadBugseeReleaseNative; built and listed), a test keeps it and the README snippet, and the README gains the Install step, a note on why the other published modules (okhttp, ktor, cronet, compose, leak) are not added for a Flutter app, and a "Debug symbols" table: R8 mapping (automatic), native symbols (ndk.enabled), Dart --split-debug-info (manual, 9.x script) and iOS dSYMs (manual in a Flutter app; taken from the Bugsee CLI docs, not measured here). Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01WeiJxNbNUdWru1zs68bYV8 Change-Id: I79d6995a87bfc8c24e7b1f50aded87d6a0b4ae11 --- CHANGELOG.md | 2 ++ README.md | 40 +++++++++++++++++++++++++--- example/android/app/build.gradle.kts | 9 +++++++ test/native_versions_test.dart | 9 +++++++ 4 files changed, 57 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b348d28..3a5c1b0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -47,6 +47,8 @@ should stay on 9.x: there is no compatibility layer (the decision is open), see ### Requirements * Flutter 3.50.0 or newer, Dart 3.14 or newer (the 10.0 major moves the floor to the release with Direct Interop, Android Gradle Plugin 9 and `material_ui`; it was 3.41.0 / 3.11, the first where a SwiftPM-only plugin resolves on Linux and Windows). +* Android: turn on the native symbol upload with `bugsee { ndk { enabled.set(true) } }` (the plugin has it off; without it native crashes + in release builds are unreadable), see README "Debug symbols" (also the Dart and iOS symbols, which are uploaded by hand). * Android: `minSdk` 21, JDK 17 or 21, the Bugsee Gradle plugin 4.1.1 applied by the app (mandatory; no Gradle ordering workaround any more, [bugsee-android-gradle-plugin#33](https://github.com/bugsee/bugsee-android-gradle-plugin/issues/33) is fixed in 4.1.0). * iOS: 15.0 or newer, Swift Package Manager only (no CocoaPods). diff --git a/README.md b/README.md index 96ef50a..cfa153b 100644 --- a/README.md +++ b/README.md @@ -77,9 +77,28 @@ while the core is unpublished. fixed): the ordering snippet that 4.0.x needed on Gradle 8.14 (the old Flutter template) is gone (debug, release and profile builds of the example were measured without it). On an older plugin the build fails Gradle task validation on `injectBugseeBuildId`: use 4.1.1. -Nothing else is needed: the plugin declares `bugsee-android` **and** the separate `bugsee-android-ndk` artefact (native crash -detection), registers its wrapper from a content provider that runs before the SDK can launch, and ships consumer ProGuard -rules. The working example is [`example/android`](example/android). +3. **Turn on the native symbol upload** in `android/app/build.gradle.kts` (the Bugsee plugin has it OFF by default): + + ```kotlin + bugsee { + ndk { enabled.set(true) } + } + ``` + + The native crash detector itself is always present (this package depends on the separate `bugsee-android-ndk` artefact), but a + crash in `libflutter.so` or any other `.so` is only readable (function and file:line) when the backend has that build's + native symbols. With `ndk.enabled` the plugin uploads the unstripped libraries of every **non-debuggable** build (task + `uploadNative`, for example `uploadBugseeReleaseNative`) with the app token (`bugsee.properties` at the root of the + Android project, or `appToken("...")` in the `bugsee { }` block); without a token it skips quietly. The R8 mapping upload + needs no setting. See [Debug symbols](#debug-symbols) for the Dart and iOS symbols too. + +Besides that, the plugin registers this package's wrapper from a content provider that runs before the SDK can launch and the +package ships consumer ProGuard rules. The working example is [`example/android`](example/android). + +**Other Bugsee Android modules** (`bugsee-android-okhttp`, `-ktor-2`, `-ktor-3`, `-cronet`, `-compose`, `-leak`) are not added: they +instrument NATIVE UI and HTTP stacks (OkHttp, Ktor, Cronet, Jetpack Compose, native leak watching), which a Flutter UI and Dart's +`dart:io` network capture do not use. An app that has native code using one of them declares the dependency itself and the plugin +wires it. The feedback chat is the separate package `bugsee_flutter_feedback`. ### iOS @@ -333,6 +352,21 @@ Future contactSupport() async { } ``` +## Debug symbols + +A crash or error report is only readable when the backend holds the symbols of the build that produced it. Keep the symbols of +every build you ship. + +| What | Where it comes from | How it gets to Bugsee | +|---|---|---| +| Android Java/Kotlin frames (R8 mapping) | the Bugsee Gradle plugin | automatic, on every minified build (`uploadMapping`) | +| Android native frames (`libflutter.so`, your `.so` files) | the Bugsee Gradle plugin | **only with `bugsee { ndk { enabled.set(true) } }`** (see Install, Android); non-debuggable builds | +| Dart frames of a release build made with `--split-debug-info` (and `--obfuscate`) | `build/symbols/*.symbols` | **manual**: [doc/exceptions.md](doc/exceptions.md) section 5 (the 9.x `symbols.py` script; `bugsee-cli` has no Flutter type yet) | +| iOS native frames (the app, `Flutter.framework`) | the build's dSYMs | **manual in a Flutter app**: a Run Script phase after "Embed Frameworks" running `bugsee-cli xcode upload-dsyms --app-token "$BUGSEE_APP_TOKEN"` ([Bugsee CLI, Xcode](https://docs.bugsee.com/cli/xcode/)), or `bugsee-cli debug-files upload /dSYMs --type dsym --version --build ` in CI; with Xcode 15 and newer set `ENABLE_USER_SCRIPT_SANDBOXING = NO` on the target | + +Dart symbols and iOS dSYMs are not uploaded for you by this package: nothing in a Flutter build calls the Bugsee uploader. The iOS +row is taken from Bugsee's CLI documentation and has not been measured with a Flutter build here. + ## Privacy model Bugsee records what makes a bug reproducible, so decide what must not be recorded. What is captured, and the control for each: diff --git a/example/android/app/build.gradle.kts b/example/android/app/build.gradle.kts index 071cecd..2e9bd04 100644 --- a/example/android/app/build.gradle.kts +++ b/example/android/app/build.gradle.kts @@ -38,3 +38,12 @@ android { flutter { source = "../.." } + +// Native crash FRAMES are only readable with the native symbols: this uploads the unstripped +// libraries (libflutter.so and every other .so the app ships) of each non-debuggable build, keyed +// by build id. It is OFF by default in the plugin; without it a native crash in a release build +// reaches the backend as raw addresses. It needs the app token (`bugsee.properties` in this +// directory or `appToken("...")` here); with none it skips quietly. +bugsee { + ndk { enabled.set(true) } +} diff --git a/test/native_versions_test.dart b/test/native_versions_test.dart index 0c53d0d..c7d5406 100644 --- a/test/native_versions_test.dart +++ b/test/native_versions_test.dart @@ -139,6 +139,15 @@ void main() { contains('id("com.bugsee.android.gradle")'), ); }); + + test('example turns the native symbol upload on (off by default in the plugin)', () { + // Without it a native crash in a release build reaches the backend as raw addresses. + expect( + read('example/android/app/build.gradle.kts'), + contains('ndk { enabled.set(true) }'), + ); + expect(read('README.md'), contains('ndk { enabled.set(true) }')); + }); }); group('iOS', () { From 937cc626f8d900c40e344e6d8fd4fd58a56b19ec Mon Sep 17 00:00:00 2001 From: Alexey Karimov Date: Tue, 17 Nov 2026 15:23:26 +0500 Subject: [PATCH 2/2] Review findings: the token file lives in the Gradle root, a live-statement guard, the iOS token variable Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01WeiJxNbNUdWru1zs68bYV8 Change-Id: I42ca8df982e0216e9235561cda8c20d8ca12adb5 --- README.md | 6 +++--- example/android/.gitignore | 1 + example/android/app/build.gradle.kts | 10 ++++++---- test/native_versions_test.dart | 13 ++++++++++++- 4 files changed, 22 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index cfa153b..c1acea7 100644 --- a/README.md +++ b/README.md @@ -88,8 +88,8 @@ while the core is unpublished. The native crash detector itself is always present (this package depends on the separate `bugsee-android-ndk` artefact), but a crash in `libflutter.so` or any other `.so` is only readable (function and file:line) when the backend has that build's native symbols. With `ndk.enabled` the plugin uploads the unstripped libraries of every **non-debuggable** build (task - `uploadNative`, for example `uploadBugseeReleaseNative`) with the app token (`bugsee.properties` at the root of the - Android project, or `appToken("...")` in the `bugsee { }` block); without a token it skips quietly. The R8 mapping upload + `uploadNative`, for example `uploadBugseeReleaseNative`) with the app token (`bugsee.properties` in the Gradle root directory, the + `android/` folder of a Flutter app, or `appToken("...")` in the `bugsee { }` block); without a token it skips quietly. The R8 mapping upload needs no setting. See [Debug symbols](#debug-symbols) for the Dart and iOS symbols too. Besides that, the plugin registers this package's wrapper from a content provider that runs before the SDK can launch and the @@ -362,7 +362,7 @@ every build you ship. | Android Java/Kotlin frames (R8 mapping) | the Bugsee Gradle plugin | automatic, on every minified build (`uploadMapping`) | | Android native frames (`libflutter.so`, your `.so` files) | the Bugsee Gradle plugin | **only with `bugsee { ndk { enabled.set(true) } }`** (see Install, Android); non-debuggable builds | | Dart frames of a release build made with `--split-debug-info` (and `--obfuscate`) | `build/symbols/*.symbols` | **manual**: [doc/exceptions.md](doc/exceptions.md) section 5 (the 9.x `symbols.py` script; `bugsee-cli` has no Flutter type yet) | -| iOS native frames (the app, `Flutter.framework`) | the build's dSYMs | **manual in a Flutter app**: a Run Script phase after "Embed Frameworks" running `bugsee-cli xcode upload-dsyms --app-token "$BUGSEE_APP_TOKEN"` ([Bugsee CLI, Xcode](https://docs.bugsee.com/cli/xcode/)), or `bugsee-cli debug-files upload /dSYMs --type dsym --version --build ` in CI; with Xcode 15 and newer set `ENABLE_USER_SCRIPT_SANDBOXING = NO` on the target | +| iOS native frames (the app, `Flutter.framework`) | the build's dSYMs | **manual in a Flutter app**: a Run Script phase after "Embed Frameworks" running `bugsee-cli xcode upload-dsyms --app-token "$BUGSEE_APP_TOKEN"` ([Bugsee CLI, Xcode](https://docs.bugsee.com/cli/xcode/)), or `bugsee-cli debug-files upload /dSYMs --type dsym --version --build ` in CI; with Xcode 15 and newer set `ENABLE_USER_SCRIPT_SANDBOXING = NO` on the target; `$BUGSEE_APP_TOKEN` must exist in the script's environment (a user-defined build setting of the target named `BUGSEE_APP_TOKEN` does that), and the CLI fails the build, exit code 20, when it is missing or empty | Dart symbols and iOS dSYMs are not uploaded for you by this package: nothing in a Flutter build calls the Bugsee uploader. The iOS row is taken from Bugsee's CLI documentation and has not been measured with a Flutter build here. diff --git a/example/android/.gitignore b/example/android/.gitignore index be3943c..aecfe5c 100644 --- a/example/android/.gitignore +++ b/example/android/.gitignore @@ -4,6 +4,7 @@ gradle-wrapper.jar /gradlew /gradlew.bat /local.properties +/bugsee.properties GeneratedPluginRegistrant.java .cxx/ diff --git a/example/android/app/build.gradle.kts b/example/android/app/build.gradle.kts index 2e9bd04..40845e1 100644 --- a/example/android/app/build.gradle.kts +++ b/example/android/app/build.gradle.kts @@ -40,10 +40,12 @@ flutter { } // Native crash FRAMES are only readable with the native symbols: this uploads the unstripped -// libraries (libflutter.so and every other .so the app ships) of each non-debuggable build, keyed -// by build id. It is OFF by default in the plugin; without it a native crash in a release build -// reaches the backend as raw addresses. It needs the app token (`bugsee.properties` in this -// directory or `appToken("...")` here); with none it skips quietly. +// libraries (libflutter.so and the other .so files the app packages) of each non-debuggable build, +// keyed by build id; a library that ships already stripped stays unsymbolicated. It is OFF by default +// in the plugin; without it a native crash in a release build reaches the backend as raw addresses. +// It needs the app token: `bugsee.properties` in the Gradle ROOT directory (`example/android`, the +// plugin reads `/bugsee.properties`; do not commit a real token) or `appToken("...")` +// here; with none it skips quietly. bugsee { ndk { enabled.set(true) } } diff --git a/test/native_versions_test.dart b/test/native_versions_test.dart index c7d5406..c352d16 100644 --- a/test/native_versions_test.dart +++ b/test/native_versions_test.dart @@ -142,9 +142,20 @@ void main() { test('example turns the native symbol upload on (off by default in the plugin)', () { // Without it a native crash in a release build reaches the backend as raw addresses. + // A live statement, not text in a comment or in a disabled block: the line starts with the code. expect( read('example/android/app/build.gradle.kts'), - contains('ndk { enabled.set(true) }'), + matches( + RegExp( + r'^bugsee\s*\{\s*ndk\s*\{\s*enabled\.set\(true\)\s*\}\s*\}', + multiLine: true, + ), + ), + ); + // The token file the comment and the README name is the one the plugin reads and git ignores. + expect( + read('example/android/.gitignore'), + contains('/bugsee.properties'), ); expect(read('README.md'), contains('ndk { enabled.set(true) }')); });