Fatal Issues and Crashes¶
The Capture SDK can automatically detect, capture, and upload fatal issues and crashes that affect your app.
See the Product > Issues Feature Guide to learn more about how to navigate this information in the product.
Note
Fatal issue reports on iOS are uploaded only for actual devices and not simulators
Info
Fatal issue reports and their session information are uploaded automatically and do not require a workflow to be running.
Setup¶
Fatal issue reporting is enabled by default in the Capture SDK since 0.18.7 version.
Enable Android Native Crash Reporting¶
Native (NDK) Crashes are now supported by passing enableNativeCrashReporting = true to the Configuration. This feature still experimental.
Logger.start(
configuration = Configuration(enableNativeCrashReporting = true),
)
Disable Fatal Issue Reporting¶
Fatal issue reporting is enabled by default in the Capture SDK since 0.18.7 version. If you want to disable it, you can set enableFatalIssueReporting = false in Configuration Logger.start().
Logger.start(
configuration = Configuration(enableFatalIssueReporting = false),
)
boolean enableFatalIssueReporting = false;
Logger.start(
new Configuration(
new SessionReplayConfiguration(),
enableFatalIssueReporting);
);
Logger.start(
configuration: Capture.Configuration(enableFatalIssueReporting: false),
)
#import <Capture/Capture.h>
CAPConfiguration *config = [[CAPConfiguration alloc]
initWithEnableFatalIssueReporting:NO
enableURLSessionIntegration:YES];
[CAPLogger
startWithAPIKey:@"your-api-key"
sessionStrategy: [CAPSessionStrategy activityBased]
configuration:config];
Note
Fatal issue reports on iOS are uploaded only for actual devices and not simulators
Uploading Debug Information Files¶
To generate human readable stack traces, bitdrift needs your apps' debug information files.
bd cli tool¶
Our command-line tool makes it easy to upload debug information files to bitdrift.
Installation¶
Homebrew (macOS)¶
To install the CLI directly on your Mac, use Homebrew:
brew tap bitdriftlabs/bd
brew install bd
Direct Download¶
Direct downloads for other platforms are also available, which are especially useful for integrating into your CI or release process.
Info
Latest version of bd-cli is 0.1.33-rc.1
Usage¶
bd debug-files upload-proguard
--api-key <API_KEY>
--app-id <APP_ID>
--app-version <APP_VERSION>
--version-code <VERSION_CODE>
<PROGUARD_MAPPING_FILE>
bd debug-files upload
--api-key <API_KEY>
<FILE_OR_DIRECTORY> # MACH-O, ELF
Automatic Uploads¶
Bitdrift supports build-time integration to upload the required Debug Information Files automatically.
Gradle Plugin (Android)¶
Debug information files (proguard mappings, native symbols) can be automatically located and uploaded via gradle tasks.
Info
The following requires the usage of the Capture Gradle Plugin, learn how to configure it in Android Quickstart Guide.
After a project sync, the Capture Gradle Plugin will automatically generate the bdUpload+ gradle tasks under the "Upload" group:
- bdUpload - Upload all symbol and mapping files to Bitdrift
- bdUploadMapping - Upload mapping to Bitdrift
- bdUploadSymbols - Upload symbols to Bitdrift
You must set the API_KEY environment variable to call these tasks
e.g.
API_KEY=MY-API-KEY ./gradlew bdUploadMapping
export API_KEY=MY-API-KEY
./gradlew bdUploadMapping
Xcode Build Phase Script (iOS)¶
In the "Build Phases" tab of your Xcode build target, add a run script phase (click the "+" symbol in the top-left, then select "New Run Script Phase"), and use the following script:
Build Script
########################################
# Configuration
########################################
UPLOAD_ON_CONFIGURATIONS=(
# Debug
Release
)
########################################
# Script
########################################
set -eu -o pipefail
if [[ ! " ${UPLOAD_ON_CONFIGURATIONS[*]} " =~ [[:space:]]${CONFIGURATION}[[:space:]] ]]; then
echo "This build step is not configured to upload symbols when using build configuration \"$CONFIGURATION\", so doing nothing."
exit 0
fi
if [[ "$(uname -m)" == arm64 ]]; then
BD_ARCH=arm64
else
BD_ARCH=x86_64
fi
BD_URL="https://dl.bitdrift.io/bd-cli/latest/bd-cli-mac-${BD_ARCH}.tar.gz/bd"
BD="$TEMP_DIR/bd"
dsym_files=()
if [ $ENABLE_USER_SCRIPT_SANDBOXING == "YES" ]; then
if [ $SCRIPT_INPUT_FILE_COUNT -le 0 ]; then
echo 'ENABLE_USER_SCRIPT_SANDBOXING is enabled. All dSYMs must be declared in the "Input Files" section of this run script when sandboxing is enabled.'
echo 'Please either disable ENABLE_USER_SCRIPT_SANDBOXING, or add the following into the "Input Files" section of this run script:'
echo ' ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${TARGET_NAME}'
exit 1
fi
for ((n=0;n<$SCRIPT_INPUT_FILE_COUNT;n++)); do
declare name=SCRIPT_INPUT_FILE_${n}
if [ -f "${!name}" ]; then
dsym_files+="${!name}"
fi
done
else
dsym_files+="${DWARF_DSYM_FOLDER_PATH}"
fi
if [ ${#dsym_files[@]} -eq 0 ]; then
echo "Did not find any dSYM files to upload to Bitdrift. By default, Debug builds don't include dSYM files."
echo "If you want to generate dSYM files in a debug build, modify your 'Debug Information Format' build setting and set it to 'DWARF with dSYM File'."
exit 0
fi
if [ -z ${API_KEY+x} ]; then
echo "Bitdrift requires the 'API_KEY' environment value to be set."
echo "Please set API_KEY to your Bitdrift API key value, then launch xcode or xcodebuild from that environment."
exit 1
fi
if [ ! -f "$BD" ]; then
curl $BD_URL -o "$BD"
chmod a+x "$BD"
fi
for path in "${dsym_files[@]]}"; do
echo "Uploading to Bitdrift: $path"
"$BD" debug-files upload "$path"
done
Info
You will need to set the API_KEY environment variable to your Bitdrift API key, and run your build under that environment
Info
If you have script sandboxing enabled on your build, you'll need to expose the symbol files so that the script can see them. This can be done by adding an entry with ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${TARGET_NAME} to the "Input Files" section of the run script build phase.