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 at https://github.com/backtrace-labs/backtrace-android.

Setup and Installation

Configure your Backtrace Instance

If you don't have a Backtrace instance yet, create one at https://backtrace.io/create

You will be provided a Backtrace instance with a domain in the following form:

https://<your organization>.sp.backtrace.io

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

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. Find more information about using the library in the README 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
  • 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
6e5552ef-cca0-578f-8259-bef23a9566d3
$ 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 format=proguard, and symbolication_id equal to your UUID. For example (for version 1.0.1 above):

https://<universe>.sp.backtrace.io:6098/post?format=proguard&token=<symbol_upload_token>&universe=<universe>&project=<project>&symbolication_id=39642ed9-5a75-5186-9649-71a893e00340

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, attaching additional custom attributes, or attaching file attachments.

Did this answer your question?