Android client for Sentry
Latest commit 296de80 Nov 24, 2016 @marcomorain marcomorain committed on GitHub Merge pull request #109 from ruudk/patch-1
Add import to readme

Sentry-Android - Sentry Client for Android

It does what every Sentry client needs to do

Below is an example of how to register Sentry-Android to handle uncaught exceptions

<!-- REQUIRED to send captures to Sentry -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- OPTIONAL but makes Sentry-Android smarter -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
import com.joshdholtz.sentry.Sentry;

public class MainActivity extends Activity {

    public void onCreate(Bundle savedInstanceState) {

        // Sentry will look for uncaught exceptions from previous runs and send them
        Sentry.init(this, "YOUR-SENTRY-DSN");


Sentry-Android has two features that make it easy to use.

First, Sentry-Android will, by default, install an uncaught exception handler that will catch and report any uncaught exceptions (crashes) in your app. You only need to add a single line of code to set up Sentry-Android.

Second, since Sentry-Android is written specifically for Android, we can automatically associate device and OS information to error-reports. The table below shows an example of what the data will look like in Sentry.

Modelbullhead (Nexus 5X)
Version7.0 (24)
Kernel Version3.10.73-g76d746e


Version Changes
1.5.2 Send stack-frames to Sentry in the correct order. #95.
Use the versionName, rather than versionCode, as the default value for the release field of events (thanks to FelixBondarenko).
1.5.1 Revert accidental API removal of captureException(Throwable, SentryEventLevel).
1.5.0 Add Breadcrumb support #70.
Add release tracking by default #78.
Add the ability to attach a stack-trace to any event #81.
Use a fixed-size thread-pool for sending events #80.
Make it easier to add a message when capturing an exception #77.
Added helper methods for addExtra and addTag #74.
(thanks to marcomorain)
1.4.4 Sends up device, app, and OS context by default (thanks to marcomorain)
1.4.3 Fixes for a Google Play warning and added option to not use crash reporting (thanks to ZeroStride)
1.4.1 Fixes for a potential memory leak and a crash (thanks to Syhids and woostrowski)
1.4.0 Fixes issues when using self-hosted Sentry server
1.2.1 Sends up data to Sentry as UTF-8
1.2.0 Added support for Android version 23 and made library avaiable to install via gradle
1.1.4 Added support for verify_ssl on DSN (thanks Kras4ooo)
1.1.3 Exceptions appear super mega awesome in Sentry now (thanks doapp-jeremiah)
1.1.2 Bug fixed - Setting a captureListener was required to send a report (thanks mathzol)
1.1.1 Uncaught exception handler now calls SentryEventCaptureListener
1.1.0 Saves requests that were captured offline or failed and tries to resend them when it can
1.0.0 Removed dependency to Protocol; allows capture of message from background thread
0.1.0 Initial release

How To Get Started


Available in jCenter

compile 'com.joshdholtz.sentry:sentry-android:1.5.0'


JAR can be downloaded here

This Is How We Do It

Permissions in manifest

The AndroidManifest.xml requires the permission android.permission.INTERNET and would like the permission android.permission.ACCESS_NETWORK_STATE even though optional.

<!-- REQUIRED to send captures to Sentry -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- OPTIONAL but makes Sentry-Android smarter -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Capture a message

Sentry.captureMessage("Something significant may have happened");

Capture a caught exception

try {
    JSONObject obj = new JSONObject();
} catch (JSONException e) {

Capture custom event

Sentry.captureEvent(new Sentry.SentryEventBuilder()
    .setMessage("Being awesome")
    .setCulprit("Josh Holtz")

Capture Breadcrumbs

You can record breadcrumbs to track what happened in your application leading up to an error.

There are 3 ways to log a breadcrumb.

// Record that a user sent a HTTP POST to and it was successful.
Sentry.addHttpBreadcrumb("", "POST", 200);

// Record the fact that user clicked a button to go from the main menu to the
// settings menu.
Sentry.addNavigationBreadcrumb("", "main menu", "settings");

// Record a general,  application specific event
Sentry.addBreadcrumb("user.state_change", "logged in");

Release Tracking

The SDK will automatically tag events with a release. The release is set to the app's versionName by default. You can override the release easily by using the setRelease(String release) function from inside a SentryEventCaptureListener.

Set a listener to intercept the SentryEventBuilder before each capture

// Sets a listener to intercept the SentryEventBuilder before
// each capture to set values that could change state
Sentry.setCaptureListener(new SentryEventCaptureListener() {

    public SentryEventBuilder beforeCapture(SentryEventBuilder builder) {

        // Needs permission - <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
        ConnectivityManager connManager = (ConnectivityManager) getSystemService(CONNECTIVITY_SERVICE);
        NetworkInfo mWifi = connManager.getNetworkInfo(ConnectivityManager.TYPE_WIFI);

        // Sets extra key if wifi is connected
        return builder
            .addExtra("wifi", String.valueOf(mWifi.isConnected()))
            .addTag("tag_1", "value_1");

Use for self hosted Sentry

Init with your base url

Sentry.init(this, "" "YOUR-SENTRY-DSN");


Twitter: @joshdholtz


Sentry-Android is available under the MIT license.