Generic Top

I just announced the new Learn Spring course, focused on the fundamentals of Spring 5 and Spring Boot 2:


1. Introduction

In this tutorial, we’re going to talk about Chaos Monkey for Spring Boot.

This tool helps us introduce some of the principles of chaos engineering into our Spring Boot web applications by adding latency to our REST endpoints, throwing errors, or even killing an app.

2. Setup

To add Chaos Monkey to our application, we need a single Maven dependency in our project:


3. Configuration

Once we have the dependency setup in our project, we need to configure and start our chaos.

We can do this in a couple of ways:

  • At application startup, using chaos-monkey spring profile (recommended)
  • Using chaos.monkey.enabled=true property

By starting the application with chaos-monkey spring profile we don’t have to stop and start the application if we want to enable or disable it while our app is running:

java -jar your-app.jar

Another useful property is management.endpoint.chaosmonkey.enabled. Setting this property to true will enable the management endpoint for our Chaos Monkey:


From this endpoint, we can see our library’s status. Here is the full list of endpoints and their description that will help change configuration, enable or disable Chaos Monkey and other more granular controls.

Using all the available properties, we can have a more fine-grained control over what happens in our generated chaos.

4. How Does It Work

Chaos Monkey consists of Watchers and Assaults. A Watcher is a Spring Boot component. It makes use of Spring AOP to see when a public method is executed in classes annotated with the following Spring annotations:

  • Component
  • Controller
  • RestController
  • Service
  • Repository

Based on the configuration in our app properties file, our public methods will be either assaulted or not, by one of the following:

  • Latency Assault – adds random latency to the request
  • Exception Assault – throws random Runtime Exception
  • AppKiller Assault – um, the app dies

Let’s take a look at how we can configure our watcher and assaults for a more controlled assault.

5. Watcher

By default, Watcher is only enabled for our services. This means that our assaults will be executed only for public methods in our classes annotated with @Service.

But we can easily change that by configuring properties:


Keep in mind that once the application started, we cannot dynamically change the watcher using the Chaos Monkey for Spring Boot management port that we talked about earlier.

6. Assaults

Assaults are basically scenarios that we want to test in our application. Let’s take each type of attack and see what it does and how we can configure it.

6.1. Latency Assault

This type of attack adds latency to our calls. This way our application responds slower and we can monitor how it behaves when for example the database responds slower.

We can configure and turn on or of this type of attack using the properties file of our app:


Another way to configure and switch on and off this type of attack is through the management endpoint of Chaos Monkey.

Let’s turn on the latency attack and add a range of latency between two and five seconds:

curl -X POST http://localhost:8080/chaosmonkey/assaults \
-H 'Content-Type: application/json' \
-d \
	"latencyRangeStart": 2000,
	"latencyRangeEnd": 5000,
	"latencyActive": true,
	"exceptionsActive": false,
	"killApplicationActive": false

6.2. Exception Assault

This tests how well our application can handle exceptions. Based on configuration it will throw a random Runtime Exception once enabled.

We can enable it using a curl call similar to our latency assault:

curl -X POST http://localhost:8080/chaosmonkey/assaults \
-H 'Content-Type: application/json' \
-d \
	"latencyActive": false,
	"exceptionsActive": true,
	"killApplicationActive": false

6.3. AppKiller Assault

This one, well, our app will die at some random point. We can enable or disable it with a simple curl call like the previous two types of assault:

curl -X POST http://localhost:8080/chaosmonkey/assaults \
-H 'Content-Type: application/json' \
-d \
	"latencyActive": false,
	"exceptionsActive": false,
	"killApplicationActive": true

7. Conclusion

In this article, we talked about Chaos Monkey for Spring Boot. We’ve seen that it takes some of the principles of chaos engineering and enables us to apply them to a Spring Boot application.

As always, the full code of the examples can be found over on Github.

Generic bottom

I just announced the new Learn Spring course, focused on the fundamentals of Spring 5 and Spring Boot 2: