Apache License 2 Build Status codecov Maven Central

Chaos Monkey for Spring Boot

inspired by Chaos Engineering at Netflix

This project provides a Chaos Monkey for Spring Boot and will try to attack your running Spring Boot App.

Chaos Engineering is the discipline of experimenting on a distributed system in order to build confidence in the system’s capability to withstand turbulent conditions in production. principlesofchaos.org



Get familiar with the Chaos Monkey for Spring Boot in the following video, available on YouTube:

Chaos Monkey for Spring Boot
Chaos Monkey for Spring Boot - new features

What is the goal of Chaos Monkey?

Inspired by PRINCIPLES OF CHAOS ENGINEERING and by my work in distributed systems, with a focus on Spring Boot, I wanted to test the resulting applications in more detail and especially during operation.

After writing many unit and integration tests, a code coverage from 70% to 80%, this unpleasant feeling remains, how our baby behaves in production?

Many questions remain unanswered:

As you can see, there are many more questions and open topics you have to deal with.

That was my start to take a deep dive into Chaos Engineering and I started this little project to share my thoughts and experience.

Be social and communicative!

If you start to implement Chaos Engineering at your company, then you must be a very social and communicative person. Why, because you will get to know many of your colleagues personally in a very short time when your chaos experiments strike.

Check your resilience

Are your services already resilient and can handle failures? Don´t start a chaos experiment if not!

Implement active application monitoring

Check your monitoring and check if you can see the overall state of your system. There are many great tools out there to get a pleasant feeling about your entire system.

Define steady states

Define a metric to check a steady state about your service and of course your entire system. Start small with a service that is not so critical.

Do not start in production

Of course, you can start in production, but keep in mind…

The best place on earth is…production!
Josh Long

…so let’s keep production as the best place on earth and look for our first experiences on another stage. If all goes well and your company is further on to you, run it in production.

What does the Chaos Monkey for Spring Boot do?

Spring Boot Chaos Monkey is a small library (30kb) and you have the following options to integrate the Chaos Monkey into your Spring Boot App.

Dependency in your POM


Start your application with the Spring Profile chaos-monkey to initialize the Chaos Monkey. Since version 1.5.0 and 2.0.0 it will not start attacks on your application yet, you can activate this dynamically at runtime.

java -jar your-app.jar --spring.profiles.active=chaos-monkey

As long as you don’t set the property “chaos.monkey.enabled” to “true”, nothing will happen!

As you can see, you don’t have to change the source code!

Dynamic Configuration at runtime

The Chaos Monkey for Spring Boot can be configured at runtime via a Spring Boot Actuator Endpoint.

Take a look at the current snapshots and documentation.

How does it work?

If Spring Boot Chaos Monkey is on your classpath and activated with profile name “chaos-monkey”, it will automatically scan your application for all classes annotated with any of the following Spring annotations:

By configuration you define which assaults and watcher are activated, per default only the @Service watcher and the latency assault are activated.

Example - single Spring Boot application

Following example is based on Chaos Monkey for Spring Boot 1.0.1

Let’s say you built a standalone Spring Boot application. For example, there is a service annotated with Spring @Service annotation and some other components. Now we want to attack our service component.

Let´s activate Chaos Monkey for Spring Boot, only 2 steps are required.

  1. Added Chaos Monkey for Spring Boot to your dependencies.
    <version>[latest version]</version>
  1. Start your app enabling the service using the property below:
java -jar your-app.jar --spring.profiles.active=chaos-monkey

Chaos Monkey for Spring Boot will attack your @Service classes and will randomly add some latency to all public methods.

There are some more assaults and watcher, that can attack your app.


A watcher is a Chaos Monkey for Spring Boot component, that will scan your app for a specific type of annotation.

Following Spring annotation are supported:

With the help of Spring AOP, Chaos Monkey recognizes the execution of a public method and will either not execute any action or start one of its assaults. You can customize the behave by configuration.


The following assaults are being provided:

You can customize the behave by configuration, please take a look at the documentation.

Support for Spring Boot 1.5.x and 2.x

Chaos Monkey for Spring Boot versions will follow the versions of Spring Boot. The first number of the Chaos Monkey release will show you which is the right one for your Spring Boot version.

  Chaos Monkey 1.0.1 Chaos Monkey 1.5.0 Chaos Monkey 2.0.0 Chaos Monkey 2.0.1 Chaos Monkey 2.0.2 Chaos Monkey 2.1.1 Chaos Monkey 2.2+
Spring Boot 1.5.0 - 1.5.19 no yes no no no no no
Spring Boot 2.0.0 - 2.0.8 yes no yes yes yes yes yes
Spring Boot 2.1.0+ no no no no yes yes yes

For Chaos Monkey to work, you need to have the spring-web dependency in your app. You usually get this via spring-boot-starter-web or spring-boot-starter-webflux.


Detailed documentation about the configuration of the Chaos Monkey for Spring Boot.

Before version 2.3.1, documentation was created per-release. This old documentation can be found here:

Legacy Releases


You can access snapshot builds from the sonatype snapshot repository by adding the following to your repositories:

NOTE: The Maven documentation explains how to add a repository to your Maven configuration.

	<name>Sonatype Nexus Snapshots</name>