Backtrace offers integration with Android apps using the backtrace-android library. Your apps written in Kotlin or Java can easily start submitting error reports to your Backtrace instance.
The backtrace-android library is available here.
Setup and Installation
Configure your Backtrace Instance
If you don't have a Backtrace instance yet, create one here.
You will be provided a Backtrace instance with a domain in the following form:
Once you log into your instance, you will need to create a project and a submission token in that project in order to start submitting error reports. Your submission token is accessible under your Project Settings - Error Submission:
You'll use the submission token information to submit error reports to your Backtrace instance and specific project.
Configure your Application
Find more information about using the library in the README file. Use gradle or maven to install the reporting library into your application. You will need to set Internet and File Access permissions in your AndroidManifest.xml file.
You'll find details on how to:
- Use BacktraceClient to initialize and submit simple error reports to your Backtrace instance, including unhandled exceptions
- Configure the offline database and submission retry settings using BacktraceDatabaseSettings
- Make use of Breadcrumbs, which help you track device events leading up to your crash
- Use the BacktraceReport class to populate and submit custom attributes or file attachments alongside the error report
- Make use of advanced settings such as asynchronous Send, custom event handlers
Submit your first Error
Following the information in the README, you should be able to use a BacktraceClient object to send an error report to your Backtrace instance upon encountering an error or crash.
Review the Error in Backtrace
Review the error you submitted using the Backtrace Triage, Explore or Debug tools.
Index Additional Attributes
backtrace-android submits about 25 system level attributes about the device and the application that you can index and make use of in Backtrace.
Goto your Project Settings - Attributes tab to view Attributes. You will see a list of Recommended Attributes based on what's been submitted with crash reports in this project. Learn more about how to setup these Attributes in the Attribute documentation.
Once you create these Attributes, you will need to Reprocess Objects (Project Settings - Object Reprocessing) in order to reindex any crash report that was submitted before these Attributes were added.
You'll notice in the Triage - Details page, you can now add the additional attributes to view, or in the Explore page you'll be able to use those attributes for filtering or aggregation.
ProGuard deobfuscation support
If ProGuard program obfuscation is used in your application, you can let Backtrace debugger deobfuscate your crashing callstacks.
To do this, you need to upload the ProGuard
.mapping file corresponding to the build. Because the ProGuard file format does not offer any way to identify its corresponding build, it needs to be done by the programmer. For Backtrace, a UUID needs to be generated for each build. If you do not know how to generate a UUID, you can use the
uuidgen tool to generate UUID for each version of your software, for example:
$ uuidgen -N '1.0.0-beta' --namespace "f615d933-702b-5c5f-913d-18223dc80788" --sha1
$ uuidgen -N '1.0.0' --namespace "f615d933-702b-5c5f-913d-18223dc80788" --sha1 5a4d2886-fb5d-5d2e-80d8-4bcdf5f5c11b
$ uuidgen -N '1.0.1' --namespace "f615d933-702b-5c5f-913d-18223dc80788" --sha1 39642ed9-5a75-5186-9649-71a893e00340
The mapping file should be uploaded to your universe address, with
symbolication_id equal to your UUID. For example (for version 1.0.1 above):
Crash uploads need to be likewise annotated. To do so, add
symbolication_id and set its value to the UUID corresponding to the mapping file. Additionally, the
symbolication key in the crash upload needs to be set to
proguard. For more information, about our API, look here.
Advanced Configuration of backtrace-android
Once you confirm that simple errors are being submitted, you can go back to the backtrace-android README and setup additional reporting settings, such as modifying the offline settings, enabling breadcrumbs, attaching additional custom attributes, or attaching file attachments.