Documentation has moved! Visit acra.ch for versions 5.8 forward

This is ACRA's Advanced Usage Guide. You need to set up your project before using all the features described here.

If you have any question or comment regarding ACRA, post a message on the Discussion Group.

• Customizing the Content of the Reports
  • Adding your own custom variables or traces in crash reports ("Breadcrumbs")
  • Adding logcat, eventlog or radiolog extracts to reports
  • Adding your own log file extracts to reports
  • Adding file attachments to reports
  • Adding DropBoxManager events to your reports
  • Adding the Device Unique ID to your reports
  • Choosing which fields to be included in reports
  • Adding custom SharedPreferences names
  • Exclude SharedPreferences keys
  • Exclude Settings keys
• Letting your users control ACRA
  • Enable/disable ACRA
  • Enable/disable system logs
  • Enable/disable including DeviceID
  • Set an email address to be added to reports
  • Enable/disable auto accept reports
• Sending reports for caught exceptions or for unexpected application state without any exception
• Configuring a KeyStore
• Catching Application Not Responding Errors (ANR)
• Catching Native Code Errors

ACRA provides lots of data about the device and the state of your application. There are some options to let you add even more data to help debugging.

To help you track some specific issue, you can add custom data to reports.

Simply use the following method when certain events happen in your code:

ACRA.getErrorReporter().putCustomData("myKey", "myValue");

All your custom data (key/value pairs) will be added in the report column CUSTOM just before the crash (stack trace). Each key/value pair will be shown on one line. Note that each key is a set that can only be used once, without duplicates. So if you re-use the same key for a different value, then the old value will be deleted and replaced with the new value.

If you want the report to show "Breadcrumbs" to indicate which events happened in time order, just before a crash, then you need to track events using unique keys. Here's an example:

public static void trackBreadcrumb(String event) {
    ACRA.getErrorReporter().putCustomData("Event at " + System.currentTimeMillis(), event);
}

protected void onCreate(Bundle savedInstanceState) {
    super.onCreate();
    trackBreadcrumb("MyActivity.onCreate()");
    ...
}

You can also use getCustomData("myVariable") and removeCustomData("myVariable") to get/remove data from the custom data map.

You can enable adding a logcat extract to your reports by simply adding the READ_LOGS permission:

<manifest ...>
    ...
    <uses-permission android:name="android.permission.READ_LOGS"></uses-permission>
</manifest>

The default behavior is to include the result of the following command:

    adb logcat -t 200 -v time

This results to 200 lines of logcat with date, invocation time, priority/tag, and PID of the originating process.

If this is not what you want, you can change this with your own command line using the logcatArguments in the @AcraCore annotation. For example, if you prefer using:

    adb logcat -t 100 -v long ActivityManager:I MyApp:D *:S

then add this to your @AcraCore config:

    logcatArguments = { "-t", "100", "-v", "long", "ActivityManager:I", "MyApp:D", "*:S" }

As you can see, you just have to split your command line arguments to a String array on each white space.

Note: you can find further information about how to use logcat here, logcat (used in the backend by ACRA) will be able to filter by tag, that you will need to keep constant in your application.

In addition to the main default buffer, ACRA can retrieve the 2 other alternative buffers event and radio. If these data are of any use for you, you have to activate their collection:

• add EVENTSLOG and RADIOLOG fields to @AcraCore.reportContent.

Note: System logs may contain private data logged by other applications like user email address, calendar events, contacts data... You should consider [#Enable/disable_system_logs adding a user preference item to let your user choose to include system logs or not].

Warning: collecting long system logs might take quite some time and induce a latency right after your application crash. Include them only if you know how to analyze them and avoid collecting more than 100 lines.

Final note: READ_LOG permission is not granted to third-party apps anymore since Android 4.1 (JellyBean). Starting with this version, logcat provides only traces from your own app, without requiring a permission. JellyBean logcat logs are retrieved by ACRA starting with version 4.3.0b2

Since 4.3.0b1

If you chose to log your debug traces to an independent file (using for example android-logging-log4j, slf4j or logback-android), ACRA can get the latest lines from this file and send them in your reports.

Include the field APPLICATION_LOG in your customReportContent and spreadsheet template then configure it with:

• @AcraCore(applicationLogFile = "applog.log") to define the path/name of the log file
• @AcraCore(applicationLogFileDir = Directory.FILES) to define the base path of the log file
• @AcraCore(applicationLogFileLines = 150) to set the number of latest lines you want to be retrieved (default is 100).

Since 4.10.0

You can attach arbitrary files to acra reports (if your backend supports it).

Set one of the following:

• @AcraCore(attachmentUris = "content://your.app.acra/files/yourcustomfile.txt")
• @AcraCore(attachmentUriProvider = YourAttachmentProvider.class)

See AcraCore.attachmentUris for details on how to format your uri strings. Alternatively you can use your own ContentProvider with a respective uri.

DropBoxManager has been introduced in android API level 8 (2.2 - FroYo). This is a new logging system focused on persisting long chunks of text or data for debugging purposes. There is a Q&A on StackOverflow explaining the usage of this system.

As it is a rarely used feature, you need to enable it by including the field DROPBOX in your reportContent.

You need the READ_LOGS permission to collect these data, add it to your manifest with:

<manifest ...>
    ...
    <uses-permission android:name="android.permission.READ_LOGS"></uses-permission>
</manifest>

Note: READ_LOG permission is not granted to third-party apps anymore since Android 4.1 (JellyBean). Starting with this version, logcat provides only traces from your own app, without requiring a permission. JellyBean logcat logs are retrieved by ACRA starting with version 4.3.0b2

A list of DropBox tags has been built by searching for DropBoxManager usage in android source code. All these system tagged events can be retrieved if you set @AcraCore.includeDropBoxSystemTags to true:

• system_app_anr
• system_app_wtf
• system_app_crash
• system_server_anr
• system_server_wtf
• system_server_crash
• BATTERY_DISCHARGE_INFO
• SYSTEM_RECOVERY_LOG
• SYSTEM_BOOT
• SYSTEM_LAST_KMSG
• APANIC_CONSOLE
• APANIC_THREADS
• SYSTEM_RESTART
• SYSTEM_TOMBSTONE
• data_app_strictmode

You can add your own dropbox tags using @AcraCore.additionalDropBoxTags(), and set the max age in minutes for events to be retrieved using @AcraCore.dropboxCollectionMinutes().

@AcraCore {
    inlcudeDropBoxSystemTags = true, // default is false
    additionalDropBoxTags = {"your_own_tag", "another_additional_tag"},
    dropboxCollectionMinutes = 10 // default is 5
    ...

Warning: collecting DropBox events might take quite some time and induce a latency right after your application crash. Increase the dropBoxCollectionMinutes only if you know what you are doing.

In some circumstances, tracking exactly which identified devices throw which report can be necessary. ACRA will include your users Device ID (IMEI for GSM and the MEID or ESN for CDMA phones) if you add the following permission to your application manifest:

<manifest ...>
    ...
    <uses-permission android:name="android.permission.READ_PHONE_STATE"></uses-permission>
</manifest>

Note: This unique device ID is considered as private data as it could let you track users behaviors... You should consider adding a user preference item to let your user choose to include this device id or not.

You can change the default set of fields included in your reports using @AcraCore(reportContent = { array of ReportField }). For example:

import static ReportField.*;

@AcraCore(reportContent = { APP_VERSION, ANDROID_VERSION, PHONE_MODEL, CUSTOM_DATA, STACK_TRACE, LOGCAT })
public class MyApplication extends Application {
...

Limiting your reports to what you really want and really use can help avoiding performance issues when collecting reports data. Only fields which are set in customReportContent are actually processed.

The system default SharedPreferences for your application are automatically collected in the SHARED_PREFERENCES field.

If your app contains multiple SharedPreferences files, or if you are using a non-default name, you can add them by providing their names with:

@AcraCore(additionalSharedPreferences={"my_own_prefs","a_second_prefs"})

Note: your shared preferences file name is set when you open your SharedPreferences:

context.getSharedPreferences("My file name to be used in acra", Context.MODE_PRIVATE);

Since 4.3.0b1

If your SharedPreferences contain private data that you don't want to be transmitted in reports, you can define exclusion rules using Regular Expressions provided in the excludeMatchingSharedPreferencesKeys configuration item.

Every key matching any of these regular expressions will be excluded from reports.

@AcraCore(excludeMatchingSharedPreferencesKeys={"^user.private","password"})

Since 4.5.0

Similarly to SharedPreferences, you may want to exclude some keys from the various settings fields collected by ACRA.

The configuration item to use is excludeMatchingSettingsKeys.

Some ACRA behaviors can be configured by your application users through the use of SharedPreferences items:

• enable/disable ACRA
• enable/disable system logs
• enable/disable including DeviceID
• set an email address to be added to reports
• enable/disable auto accept reports

You can store any ACRA SharedPreferences separately from your application SharedPreferences. To do so use the following @AcraCore parameter:

• sharedPreferencesName: Name of the SharedPreferences that will host the various acra.* preferences.

Add to your preferences xml file a CheckBoxPreference (checking it disables ACRA):

<CheckBoxPreference android:key="acra.disable"
    android:title="@string/pref_disable_acra"
    android:summaryOn="@string/pref_acra_disabled"
    android:summaryOff="@string/pref_acra_enabled"
    android:defaultValue="false"/>

Or if you prefer the opposite (checking it to enable ACRA):

<CheckBoxPreference android:key="acra.enable"
    android:title="@string/pref_enable_acra"
    android:summaryOn="@string/pref_acra_enabled"
    android:summaryOff="@string/pref_acra_disabled"
    android:defaultValue="true"/>

Of course you have to define the matching strings in your strings.xml files.

Including logcat extracts in reports is a great tool for developers, but it can lead to privacy issues as some other applications might log private data like user account names, opened URLs, calendar events...

Giving your users a way to control the inclusion of logcat data make them understand that you care about their privacy. This can be done with the inclusion of the following CheckBoxPreference:

 <CheckBoxPreference android:key="acra.syslog.enable"
    android:summaryOn="@string/pref_acra_syslog_enabled"
    android:summaryOff="@string/pref_acra_syslog_disabled"
    android:title="@string/pref_acra_syslog"
    android:defaultValue="true"/>

Of course you have to define the matching strings in your strings.xml files.

If you added the READ_PHONE_STATE permission to your application but want to let your user be able to disable the inclusion of their Device ID in crash reports, you can include the following CheckBoxPreference:

 <CheckBoxPreference android:key="acra.deviceid.enable"
    android:title="@string/pref_acra_deviceid"
    android:summaryOn="@string/pref_acra_deviceid_enabled"
    android:summaryOff="@string/pref_acra_deviceid_disabled" 
    android:defaultValue="true"/>

Of course you have to define the matching strings in your strings.xml files.

Some users might be willing to help debugging your app. You can ask them to input an email address that will be included in every report to allow you contact them:

 <EditTextPreference android:key="acra.user.email"
    android:title="@string/pref_acra_user_email"
    android:summary="@string/pref_acra_user_email_summary"/>

While in NOTIFICATION or DIALOG mode, you can allow your users to choose to auto-accept sending all reports. This is like letting them switch from NOTIFICATION/DIALOG mode to SILENT mode.

 <CheckBoxPreference android:key="acra.alwaysaccept"
    android:title="@string/pref_acra_alwaysaccept"
    android:summaryOn="@string/pref_acra_alwaysaccept_enabled"
    android:summaryOff="@string/pref_acra_alwaysaccept_disabled"
    android:defaultValue="false"/>

As a good programmer, your code is full of try/catch statements, and sometimes an interesting (unexpected) exception might be caught in one of these.

You could also want your application to send a report without any Exception thrown, just because you know that your application is in an unexpected state.

Both of these needs can be covered by this:

ACRA.getErrorReporter().handleException(caughtException);

You can provide any caught or custom Exception, or even null if you don't have any to provide.

If you need to add silent trace reports whatever interaction mode you configured for your application, you can also use:

ACRA.getErrorReporter().handleSilentException(caughtException);

@AcraCore{
    keyStoreFactoryClass=MyKeyStoreFactory.class
    ...
}
public class MyApp {
        ...
}

public class MyKeyStoreFactory extends BaseKeyStoreFactory {// or KeyStoreFactory for more control
    ...
}

Alternatively you can use the certificatePath, resCertificate and certificateType configuration options to use one of ACRAs default KeyStoreFactories.

ACRA has no integrated system to monitor your app and send reports when it's not responding.

There is an interesting approach provided by Salomon Brys on Github. Its watchdog thread tries to execute a small code every 5 seconds and throws an exception if it failed. This exception will be reported by ACRA.

ACRA does not catch errors occurring in native code. We currently don't know any stable solution to catch native errors with ACRA.