BugSnag is now Insight Hub – we're making some changes to how the product looks, but this won't impact the way you use BugSnag or any of your integrations.

Spring integration guide

Add BugSnag to your Java Spring and Spring Boot projects to automatically capture and report exceptions on production.

Installation

Using Gradle

Addbugsnag-spring to thedependencies section in yourbuild.gradle:

implementation'com.bugsnag:bugsnag-spring:3.+'

Using Maven

Addbugsnag-spring as a dependency in yourpom.xml

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

Then runmvn install to install the library.

Manual JAR installation

Download thelatest release and place it with it’s dependencies in your app’s classpath.

SLF4J

BugSnag Spring usesSLF4J 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 theSLF4J bindings as either a Gradle/Maven dependency in your project, or as a Jar file.

Compatibility

The minimum supported version of Spring Boot is1.4.0.

If using Spring without Spring Boot the minimum supported version is4.2.0.

Basic configuration

Using Spring annotations

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

1. Create a SpringConfiguration class which exposesBugsnag as a Spring bean and imports the configuration classBugsnagSpringConfiguration to begin capturing exceptions:

   @Configuration@Import(BugsnagSpringConfiguration.class)publicclassBugsnagConfig{@BeanpublicBugsnagbugsnag(){returnnewBugsnag("your-api-key-here");}}

   You can find your API key in your project’s settings (shortcut:gs) in the dashboard.

2. Inject theBugsnag bean into your Spring managed bean to report handled exceptions:

   @AutowiredprivateBugsnagbugsnag;

Using XML configuration

1. If you’re using XML configuration instead of Spring Annotations, you can configure aBugsnag bean and aBugsnagSpringConfiguration bean to begin capturing exceptions:

   <context:annotation-config/><beanid="bugsnag"class="com.bugsnag.Bugsnag"><constructor-argname="apiKey"value="your-api-key-here"/></bean><beanid="bugsnagSpringConfiguration"class="com.bugsnag.BugsnagSpringConfiguration"/>

2. Add a setter for theBugsnag bean into your managed bean:

   privateBugsnagbugsnag;publicvoidsetBugsnag(Bugsnagbugsnag){this.bugsnag=bugsnag;}

3. InjectBugsnag into your bean:

   <beanid="example"class="com.example.ExampleBean"><propertyname="bugsnag"ref="bugsnag"/></bean>

Logback configuration

If you uselogback you can configure a BugSnag log appender to automatically report logged throwables. Seeconfiguring logback for additional setup instructions.

Further configuration

If you’d like to configure BugSnag further, check out theconfiguration options reference.

Reporting unhandled exceptions

BugSnag attaches aThread.UncaughtExceptionHandler, so after completinginstallation andbasic configuration, unhandled exceptions will be automatically reported to your BugSnag dashboard.

If you do not want BugSnag to automatically report unhandled exceptions, set thesendUncaughtExceptionsparameter tofalse when instantiatingBugsnag:

Bugsnagbugsnag=newBugsnag("your-api-key-here",false);

In addition to exceptions reported fromThread.UncaughtExceptionHandler, unhandled exceptions are automatically reported to BugSnag if you are using:

Spring MVC

Unhandled exceptions thrown when theDispatcherServletprocesses MVC and REST API requests are automatically reported to BugSnag.

Exceptions thrown from@Controller and @RestControllermethods will have a default severity ofERROR.

Exceptions that are automatically assigned an HTTP response status by Spring(seeDefaultHandlerExceptionResolver)will have a default severity ofINFO for4XX responses (bad request) andERROR for500 responses.

Scheduled tasks

Uncaught exceptions thrown in@Scheduledannotated methods will be automatically reported to BugSnag.

Async methods

In order to automatically report uncaught exceptions thrown in@Asyncmethods the following configuration needs to be added to your application:

@ConfigurationpublicclassBugsnagAsyncConfigextendsAsyncConfigurerSupport{@AutowiredprivateBugsnagbugsnag;@OverridepublicAsyncUncaughtExceptionHandlergetAsyncUncaughtExceptionHandler(){returnnewBugsnagAsyncExceptionHandler(bugsnag);}}

If your method returns aFuture, you will need to wrap the call tofuture.get with a try-catch and notify bugsnag of the error:

Future<Data>future=restService.retrieveData();try{Datadata=future.get();}catch(Exceptionexc){bugsnag.notify(exc);}

Reporting handled exceptions

If you would like to send handled exceptions to BugSnag, you can pass anyThrowable object to thebugsnag.notify method:

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

For more information seereporting handled exceptions.

Using the logback appender

If you configure the logback appender exceptions will be sent to BugSnag when you include theThrowable parameter in aLogger call:

privatestaticfinalLoggerlogger=Logger.getLogger(MyClass.class);try{// Some potentially crashy code}catch(Throwableexception){logger.warn("Something went wrong here",exception);}

For configuration instructions seeconfiguring logback.

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' tabreport.addToTab("subsystem","name","Your subsystem name");});

For more information, seecustomizing error reports.

Identifying users

In order to correlate errors with customer reports, or to see a list of userswho experienced each error, it is helpful to capture and display userinformation on your BugSnag dashboard.

bugsnag.addCallback((report)->{report.setUser("User ID","user@example.com","User Name");});

For more information, seecustomizing error reports.

HTTP requests

BugSnag will automatically populate details of requests such as the client IP address and request URL for handled and unhandled exceptions.

Check outthe full list of captured data for more details.

Session tracking

BugSnag tracks the number of “sessions” that happen within your application.This allows you tocompare stability scores between releases and helps you to understand the quality of your releases.

For Spring applications, a session is captured and reported for each HTTP request which uses Spring MVC. This behaviour can be disabled using thesetAutoCaptureSessions configuration option.

If you want full control over what is deemed a session, you can switch off automatic session tracking with thesetAutoCaptureSessions option, and callstartSession() directly.

Tracking releases

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

bugsnag.setAppVersion("1.0.0");

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

Next steps

• Catch and report errors in your client-side JavaScript with theWeb browser JavaScript guide
• Monitor the performance of your web app in your users’ browsers with theWeb performance guide
• View thebugsnag-spring, the library powering this integration, on GitHub
• Getsupport for your questions and feature requests