Java integration guide

Add Bugsnag to your Java projects to automatically capture and report exceptions on production.

Installation

Using Gradle

Add bugsnag to the dependencies section in your build.gradle:

compile 'com.bugsnag:bugsnag:3.+'

Using Maven

Add bugsnag as a dependency in your pom.xml

<dependency>
  <groupId>com.bugsnag</groupId>
  <version>[3.0,4.0)</version>
  <artifactId>bugsnag</artifactId>
</dependency>

Then run mvn install to install the library.

Manual JAR installation

Download the latest release and place it in your app’s classpath.

The following dependencies are also required in your app’s classpath:

Basic configuration

Import the Bugsnag class in your code and create an instance to begin capturing exceptions:

import com.bugsnag.Bugsnag;

Bugsnag bugsnag = new Bugsnag("your-api-key-here");

Further configuration

If you’d like to configure Bugsnag further, check out the configuration options reference.

Reporting unhandled exceptions

Bugsnag attaches a Thread.UncaughtExceptionHandler, so after completing installation and basic configuration, unhandled exceptions will be automatically reported to your Bugsnag dashboard.

If you do not want Bugsnag to automatically report unhandled exceptions, set the sendUncaughtExceptions parameter to false when instantiating Bugsnag:

Bugsnag bugsnag = new Bugsnag("your-api-key-here", false);

Reporting handled exceptions

If you would like to send handled exceptions to Bugsnag, you can pass any Throwable object to the bugsnag.notify method:

try {
    // Some potentially crashy code
} catch (Throwable exception) {
    bugsnag.notify(exception);
}

For more information see reporting handled exceptions.

Sending diagnostic data

It can often be helpful to attach application-specific diagnostic data to exception reports. This can be accomplished as follows:

bugsnag.addCallback((report) -> {
    // Will appear as the 'name' in the 'subsystem' tab
    report.addToTab("subsystem", "name", "Your subsystem name");
});

Or without using the Java 8 lambda syntax:

import com.bugsnag.callbacks.Callback;
import com.bugsnag.Report;

bugsnag.addCallback(new Callback() {
    @Override
    public void beforeNotify(Report report) {
        // Will appear as the 'name' in the 'subsystem' tab
        report.addToTab("subsystem", "name", "Your subsystem name");
    }
});

For more information, see customizing error reports.

Identifying users

In order to correlate errors with customer reports, or to see a list of users who experienced each error, it is helpful to capture and display user information on your Bugsnag dashboard.

bugsnag.addCallback((report) -> {
    report.setUserName("User Name");
    report.setUserEmail("user@example.com");
    report.setUserId("12345");
});

Or without using the Java 8 lambda syntax:

import com.bugsnag.callbacks.Callback;
import com.bugsnag.Report;

bugsnag.addCallback(new Callback() {
    @Override
    public void beforeNotify(Report report) {
        report.setUserName("User Name");
        report.setUserEmail("user@example.com");
        report.setUserId("12345");
    }
});

For more information, see customizing error reports.

Java Servlet API

If you are using the javax.servlet API then Bugsnag will automatically populate details of the request such as the client IP address, request URL and parameters.

To report exceptions thrown by servlets you should implement your own error handler and call bugsnag.notify() from within it.

Tracking deploys

For server side applications, by sending your source revision or application version to us when you deploy a new version of your app, you’ll be able to see which deploy each error was introduced in, or seen in.

Integrate a call to our deploy tracking API into your deployment process.