Spring integration guide

Add Bugsnag to your Java Spring and Spring Boot 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:

SLF4J

Bugsnag Java uses SLF4J for internal logging, which provides a facade to several popular logging libraries. If you do not specify which logging library you wish to use, a no-operation implementation which outputs a build warning will be used.

To suppress this build warning, you should add one of the SLF4J bindings as either a Gradle/Maven dependency in your project, or as a Jar file.

Basic configuration

Using Spring annotations

The simplest way to configure Bugsnag for Spring is to use Spring Annotations.

Create a Spring Configuration class which exposes the Bugsnag as a Spring bean to begin capturing exceptions:

import com.bugsnag.Bugsnag;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class BugsnagConfig {
    @Bean
    public Bugsnag bugsnag() {
        return new Bugsnag("your-api-key-here");
    }
}

Using XML configuration

If you’re using an XML configuration for your Spring beans you can configure a Bugsnag bean to begin capturing exceptions:

<bean id="bugsnag" class="com.bugsnag.Bugsnag">
  <constructor-arg name="apiKey" value="your-api-key-here"/>
</bean>

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);

Various Spring libraries create separate threads and may handle exceptions before they get to Thread.UncaughtExceptionHandler on the main thread. These need to be configured differently in order to notify Bugsnag. The most common of these are Spring MVC, Async tasks and Scheduled tasks.

Spring MVC exception handling

To handle exceptions in Spring MVC, you need to use a HandlerExceptionResolver or the @ExceptionHandler annotation. For more information, see the Spring MVC docs. In the exception handler you will need to call bugsnag.notify(exception).

Async task exception handling

To handle exceptions sent from @Async annotated methods, you will need to use the AsyncUncaughtExceptionHandler. For more information, see the Spring docs. In the exception handler you will need to call bugsnag.notify(exception).

Scheduled task exception handling

To handle exceptions sent from @Scheduled annotated methods, you will need to wrap everything in a try..catch block and manually notify Bugsnag in the catch as you would do with a handled exception.

@Scheduled
public void scheduledTask() {
    try {
        // Scheduled code
    } catch (Throwable exception) {
        bugsnag.notify(exception);
        throw exception;
    }
}

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.

You will need to inject Bugsnag into your Spring managed bean to report handled exceptions:

Injecting via annotations

import com.bugsnag.Bugsnag;
import org.springframework.beans.factory.annotation.Autowired;

@Autowired
private Bugsnag bugsnag;

Injecting via XML

  1. Add a setter for the Bugsnag bean into your managed bean:

    import com.bugsnag.Bugsnag;
    
    private Bugsnag bugsnag;
    
    public void setBugsnag(Bugsnag bugsnag) {
      this.bugsnag = bugsnag;
    }
    
  2. Inject Bugsnag into your bean:

    <bean id="example" class="com.example.ExampleBean">
      <property name="bugsnag" ref="bugsnag"/>
    </bean>
    

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.

Session tracking

Bugsnag can track the number of “sessions” that happen in your application. This enables Bugsnag to provide and compare crash rates between releases to help you understand the quality of your releases.

Session tracking is coming soon to this platform.

Tracking releases

Configure your app version to see the release that each error was introduced in.

bugsnag.setAppVersion("1.0.0");

Then set up a build tool integration to enable linking to code in your source control provider from the releases dashboard, timeline annotations, and stack traces.