Spring Boot

The Raygun Spring Boot client adds Raygun-based error handling to your Spring Boot code.It catches all occuring errors, extracts as much information as possible and sends the error to Raygun where it is viewable in the Crash Reporting dashboard.

Requirements

The artifact has currently been tested in Spring Boot on the following versions -

Usage with Spring Boot version below 2.5.x and above 2.7.x should work, but has not been tested.

Installation

Step 1

Add the Raygun dependency in the implementation configuration and rebuild your project.

dependencies {
    implementation 'com.midtrans:raygun-spring-boot-starter:0.7.3'
}

Step 2

Set the API key property raygun.api-key within the application.properties file of your project in order to authorize sending data to your application.

raygun.api-key={paste_your_api_key_here}

Step 3

A RaygunTemplate bean is auto-configured and can be autowired.

@Component
class UserService {
    private final RaygunTemplate;

    UserService(RaygunTemplate raygunTemplate) {
        this.raygunTemplate = raygunTemplate;
    }

    void businessLogic() {
        try {
            // some business logic...
        } catch (Exception ex) {
            raygunTemplate.send(ex);
        }
    }
}

Release

Deploy Raygun into your production environment for best results, or raise a test exception. Once we detect your first error event, the Raygun app will automatically update.

The Javadoc can be accessed here.

Integrations

Web MVC Servlet Integration

Web MVC Servlet Integration in Main

Uncaught exceptions thrown from @Controller and @RestController methods are logged and sent to Raygun.

Responses can be built using Spring Web MVC exception handling mechanism using exception annotated with @ResponseStatus or using @ExceptionHandler method in a @Controller or a @ControllerAdvice as documented in the reference documentation.

If the uncaught exceptions are sent in @ExceptionHandler methods, the uncaught exceptions will be sent to Raygun twice.

@RestController
class UserRestController {

    // The IndexOutOfBoundsException will be sent to Raygun once
    @GetMapping("/uncaught")
    void uncaught() {
        throw new IndexOutOfBoundsException();
    }

    // The NullPointerException will be sent to Raygun twice
    @GetMapping("/controllerAdvice")
    void controllerAdvice() {
        throw new NullPointerException();
    }

    // The response will be depends on the annotation and the custom Exception will be sent to Raygun
    @GetMapping("/responseStatus")
    void responseStatus() {
        throw new ResponseStatusException();
    }
}

@ControllerAdvice
class UserControllerAdvice {

    @Autowired
    RaygunTemplate raygunTemplate;

    @ExceptionHandler
    ResponseEntity<?> handle(NullPointerException ex) {
        raygunTemplate.send(ex);
        return ResponseEntity.internalServerError().build();
    }
}

@ResponseStatus(code = HttpStatus.BAD_GATEWAY, reason = "Bad Gateway")
class ResponseStatusException extends RuntimeException {

}

Web MVC Servlet Integration in Tests

The Web MVC integration is configured when using the @WebMvcTest annotation.

Uncaught exceptions will still be caught and logged, but they are not sent to Raygun. Please refer to the testing section.

@WebMvcTest
class UserWebMvcTest {

    @Autowired
    MockMvc mockMvc;

    // Exceptions thrown by controller methods are caught and logged, but not sent to Raygun
    @Test
    void responseStatus() throws Exception {
        mockMvc.perform(get("/responseStatus"))
            .andExpect(status().isBadGateway());
    }
}

Web Services Integration

Web Services Integration in Main

Uncaught exceptions thrown from @Endpoint methods are logged and sent to Raygun.

By default, responses for uncaught exceptions are SOAP Fault with the exception's message as the fault string. Custom responses for uncaught exceptions can be built using Spring Web Services exception handling mechanism using exceptions annotated with @SoapFault as documented in the reference documentation.

@Endpoint
class UserEndpoint {

    //The Fault response reason will be the exception message.
    @PayloadRoot(localPart = "uncaught")
    void uncaught() {
        throw new IndexOutOfBoundsException();
    }

    // The Fault response reason will be the annotation's faultStringOrReason if set or the exception message if not set.
    @PayloadRoot(localPart = "soapFault")
    void soapFault() {
        throw new SoapFaultException();
    }
}

@SoapFault(faultCode = FaultCode.SERVER, faultStringOrReason = "soapFault")
class SoapFaultException extends RuntimeException {

}

Web Services Integration in Tests

The Web Services integration is configured when using the @WebServiceServerTest annotation

Uncaught exceptions will still be caught and logged, but they are not sent to Raygun. Please refer to the testing section.

@WebServiceServerTest
class UserWebServiceServerTest {

    @Autowired
    MockWebServiceClient mockWebServiceClient;

    @Test // Exceptions thrown by endpoint methods are caught and logged, but not sent to Raygun
    void uncaught() {
        mockWebServiceClient
            .sendRequest(RequestCreators.withPayload(new StringSource("<uncaught></uncaught>")))
            .andExpect(ResponseMatchers.serverOrReceiverFault());
    }
}

Exceptions Exclusion

To exclude exceptions being sent, register exception types through a RaygunExceptionExcludeRegistrar bean.

@Component
class UserRaygunExcludeExceptionRegistrar implements RaygunExceptionExcludeRegistrar {

    @Override
    public void registerExceptions(RaygunExceptionExcludeRegistry registry) {
        registry.registerException(RuntimeException.class);
    }
}

Messages Sending

RaygunTemplate will use a TaskExecutor to send the Raygun mesages.

In an idiomatic Spring Boot application, a ThreadPoolTaskExecutor bean is auto-configured with a sensible defaults and can be customized as documented in the reference documentation.

Depending on how many TaskExecutor beans configured in the ApplicationContext, the behavior is different as below:

• no TaskExecutor bean configured, RaygunTemplate will use a SyncTaskExecutor to send the messages synchronously,
• one TaskExecutor bean configured, RaygunTemplate will use the configured TaskExecutor bean,
• multiple TaskExecutor beans configured
  • no bean named raygunTaskExecutor configured, RaygunTemplate will use a SyncTaskExecutor to send the messages synchronously,
  • one TaskExecutor bean named raygunTaskExecutor configured, RaygunTemplate will use the raygunTaskExecutor bean.

To know the behaviors and tradeoffs of using ThreadPoolTaskExecutor please refer to RaygunTemplateMessagesSendingTest and RaygunTemplateMessagesRejectionTest.

Testing

In tests, RaygunTemplate bean is mocked and does not send exceptions to Raygun.

This will apply to @SpringBootTest and test slices.

@SpringBootTest
class UserTest {

    @Autowired
    RaygunTemplate raygunTemplate;

    // The RaygunTemplate does not send the exception to Raygun
    @Test
    void contextLoads() {
        raygunTemplate.send(new IllegalArgumentException());
    }
}