Feature/client side unwinding (#26)

Add support for client side unwinding

If client side unwinding is enabled, then when there is a native/crashpad crash, the call stack will be resolved by the device (client) before submission to the Backtrace server. This allows better resolution of call stacks
when symbols for native libraries are not available, e.g for syscalls or opaque libraries.

Author: rqbacktrace

.gitmodules

@@ -1,3 +1,6 @@
 [submodule "backtrace-library/src/main/cpp/crashpad-builds"]
 	path = backtrace-library/src/main/cpp/crashpad-builds
 	url = https://github.com/backtrace-labs/crashpad-builds.git
+[submodule "backtrace-library/src/main/cpp/libbun"]
+	path = backtrace-library/src/main/cpp/libbun
+	url = git@github.com:backtrace-labs/libbun.git

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Backtrace Android Release Notes
 
+
+## Version 3.3.0 - 15.07.2021
+- Added support for client side unwinding of native crashes
+
 ## Version 3.2.2 - 10.03.2021
 - Hotfix for crash when user enables native integration without file attachments
 

README.md

@@ -519,6 +519,33 @@ More details about [extractNativeLibs](https://developer.android.com/guide/topic
 ## Uploading symbols to Backtrace
 For an NDK application, debugging symbols are not available to Backtrace by default. You will need to upload the application symbols for your native code to Backtrace. You can do this by uploading the native libraries themselves, which are usually found in the .apk bundle. [Click here to learn more about symbolification](https://support.backtrace.io/hc/en-us/articles/360040517071-Symbolication-Overview)
 
+## Client side unwinding
+For an NDK application, debugging symbols for system functions (for instance in `libc.so`) and other opaque libraries can be difficult to obtain. In these cases, it is better to unwind the callstack on the crashing application (i.e: the client). This may not provide the same callstack quality as with debugging symbols, but will give you debugging information you would otherwise not have if you don't have debugging symbols available.
+
+To enable client side unwinding, you can call the `setupNativeIntegration` method with an additional boolean value.
+```java
+database.setupNativeIntegration(backtraceClient, credentials, true);
+```
+
+**NOTE:** Client side unwinding is only available in API level 23+ (Android 6.0)+
+
+**NOTE:** When viewing a crash in the Backtrace Debugger, it may still show warning messages that symbols are missing from certain frames after client-side unwinding is performed. This warning is expected if these symbols are not available on the Backtrace server, and should have no impact to the end-user's ability to read the call stack.
+
+**NOTE:** Client side unwinding is only available for fatal crashes. Non-fatal Crashpad dumps you generate via `DumpWithoutCrash` for instance will not use client side unwinding.
+
+### Unwinding Modes and Options
+
+You can optionally specify the unwinding mode (`REMOTE_DUMPWITHOUTCRASH` is the default)
+```java
+database.setupNativeIntegration(backtraceClient, credentials, true, UnwindingMode.REMOTE_DUMPWITHOUTCRASH);
+```
+
+- **LOCAL** - Unwinding is done within the same process that has the crash. This is less robust than remote unwinding, but avoids the complexity of creating a child process and IPC. Local unwinding is executed from a signal handler and needs to be signal-safe.
+- **REMOTE** - Unwinding is done by a child process. This means that the unwinding is correct even in case of severe malfunctions in the crashing parent process, and signal-safety is not a concern.
+- **LOCAL_DUMPWITHOUTCRASH** - The same as `LOCAL` unwinding, but instead of using the regular Crashpad signal hander to call the unwinder and regular Crashpad reporting mechanism, Backtrace's custom signal handler will be used to call the unwinder before we send the report using Crashpad's `DumpWithoutCrash()` method.
+- **REMOTE_DUMPWITHOUTCRASH** - This is the default and recommended option. Same as `LOCAL` unwinding, but instead of using the regular Crashpad signal hander to call the unwinder and regular Crashpad reporting mechanism, Backtrace's custom signal handler will be used to call the unwinder before we send the report using Crashpad's `DumpWithoutCrash()` method.
+- **LOCAL_CONTEXT** -  The same as `LOCAL` unwinding, but use `ucontext_t *` from the signal handler to reconstruct the callstack.
+
 # Working with Proguard <a name="working_with_proguard"></a>
 
 ##### 1. Add the following to the `proguard_rules.pro` for your app

backtrace-library/build.gradle

@@ -7,8 +7,8 @@ android {
     defaultConfig {
         minSdkVersion 21
         targetSdkVersion 28
-        versionCode 322
-        versionName "3.2.2"
+        versionCode 330
+        versionName "3.3.0"
 
         testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner"
 

backtrace-library/src/main/cpp/CMakeLists.txt

@@ -32,6 +32,10 @@ set_property(TARGET base PROPERTY IMPORTED_LOCATION ${PROJECT_SOURCE_DIR}/crashp
 # Crashpad Headers
 include_directories(${PROJECT_SOURCE_DIR}/crashpad-builds/headers/ ${PROJECT_SOURCE_DIR}/crashpad-builds/headers/third_party/mini_chromium/mini_chromium/)
 
+# Bun Libraries
+set(LIBUNWINDSTACK_ENABLED TRUE)
+add_subdirectory(libbun)
+
 # Searches for a specified prebuilt library and stores the path as a
 # variable. Because CMake includes system libraries in the search path by
 # default, you only need to specify the name of the public NDK library
@@ -60,4 +64,5 @@ target_link_libraries( # Specifies the target library.
                         crashpad_client
                         crashpad_util
                         base
-        )
+                        bun
+                     )