chaos-monkey-spring-boot: runtime assaults inside a live Spring Boot app

Why a Spring Boot app needs failures it cannot unit test

The question the project was built to answer is stated plainly in its own introduction. After writing many unit and integration tests and reaching a code coverage from 70% to 80%, a team still does not know how the application behaves in production. The README lists the open questions: will the fallbacks work, how does the application behave with network latency, what happens if one of the services breaks down, and whether client side load balancing works once service discovery does.

Those are integration questions about a running system, and a test suite that stops at the process boundary cannot answer them. Chaos Monkey for Spring Boot takes the approach of injecting failures into a live application rather than into a test harness, which means the failure arrives in the same process that will face it in production, with the same wiring, the same configuration and the same runtime context.

The audience is Spring Boot teams that have already done the boring work of resilience: a defined steady state, monitoring in place, and an environment that is not a customer facing production system. The project names this expectation directly in its guidance, telling readers to check that their services are already resilient and not to start a chaos experiment if they are not, and to start small with a service that is not critical.

Classpath plus profile: how the tool attaches itself

The activation mechanism is the part worth remembering because it determines where the tool can and cannot live. According to the README, if Chaos Monkey is on your classpath and is activated with the profile name `chaos-monkey`, it will automatically hook into your application. There is no agent to install, no sidecar to deploy and no separate daemon to operate. It is a library that joins the process when a Spring profile is active.

That design has a direct operational consequence. Because activation is a profile, a build of the same application can carry the dependency and still behave normally when the profile is off. The risk sits in the opposite direction too: if a production deployment ever enables that profile, the application will start attacking itself. A team adopting this needs a control on which environments can activate the profile, and the README does not describe any separate safety interlock beyond the profile itself.

The README also points at the Stack Overflow tag `#spring-boot-chaos-monkey` for usage questions, and the project publishes issue tracking on GitHub for bugs and improvements. Documentation is split: the README is a short orientation, and the full reference, from getting started to advanced usage, lives on the project's documentation site.

Watchers that pick classes, runtime assaults that hit everything

Once the library is attached, damage comes in two shapes, and the difference matters when you plan an experiment. Watchers look for classes to assault. A runtime assault attacks your whole application. In other words, one mode is selective and class oriented, the other is broad and application scoped.

The mechanism behind a watcher is that it inspects the application's classes and decides which of them qualify for attack. The mode you pick determines the blast radius and, just as importantly, the kind of question the run answers. A watcher aimed at a class that talks to a database can answer a fallback question in a narrow way. A runtime assault on the whole application answers a different question, about whether the request path degrades gracefully when something in the process misbehaves, and it can affect traffic that was not the subject of the experiment.

The repository topics list both chaos monkey and chaostoolkit, which tells you the project positions itself in the wider chaos tooling conversation, and the documentation site links the assault and runtime assault pages as the places where the concrete settings live. The README itself does not enumerate the available assault types or their configuration keys, so anyone planning a specific failure mode needs to read that site rather than the README.

A multi module Maven build with a wrapper and a doc module

The repository is a Maven build, and its top level layout explains how the pieces are separated:

chaos-monkey-dependencies/
chaos-monkey-docs/
chaos-monkey-spring-boot-external/
chaos-monkey-spring-boot/
demo-apps/

The project is published to Maven Central under the artifact coordinates de.codecentric:chaos-monkey-spring-boot, which is how most users will consume it as a dependency rather than by cloning and building. The presence of a wrapper, mvnw alongside mvnw.cmd and a.mvn directory, means the build does not require a system Maven install, and the.devcontainer directory plus.gitpod.yml indicate that a containerised development environment is provided for contributors rather than for runtime use.

Two other files are worth reading as signals rather than as instructions. code-style.xml accompanies the contribution guidelines, so the project has a defined code style that pull requests are expected to follow. renovate.json sits at the top level, which usually means dependency updates are automated, a practice that matters when you are pulling in a library that is supposed to attack your application at runtime.

The part that will decide your experiment: people, not configuration

The README has a section titled Be social and communicative, and it is the most unusual part of the documentation. The argument is direct: if you start to implement chaos engineering at your company, you must be a very social and communicative person, because you will get to know many of your colleagues personally in a very short time when your chaos experiments strike.

This is not a joke about the tool being disruptive, though it partly is. It is a statement about what chaos engineering does to an organisation. A deliberately broken service produces alerts, pages and support tickets. Colleagues who did not agree to the experiment find out through their own notification channels. A team that runs experiments without telling anyone else will lose the trust that makes future experiments possible.

The rest of the guidance in that section gives the operational preconditions: check that your services are already resilient and can handle failures, implement active application monitoring so the overall state of the system is visible, define a metric to check a steady state of the service and of the system, and start small with a service that is not critical. The README is unusually direct that production is the best place for these experiments, and just as unusually direct that you should first look for your first experiences on another stage.

Version lines, an Apache licence and a library that changes behaviour

The release history is short but slightly confusing. Version 3.2.2 was published on 2025-05-19, and then both v3.3.0 and v4.0.0 appear with releases on 2026-02-06, the same day. Two version lines published together usually means a major line and a compatibility line maintained side by side, and a team picking a version has to work out which line tracks which Spring Boot generation.

The last push was on 2026-10-08, and the repository is not archived, so work is still landing on the main branch. For a library whose whole purpose is to change the behaviour of a running application, the upgrade question is not only about API compatibility but about whether a new release changes which classes the watchers select or how an assault behaves. The README does not publish a migration guide for the version lines, so the version choice is something to settle with the documentation and the issue tracker rather than by assumption.

The licence is Apache-2.0, and the repository also carries a license.template.txt file, a CODE_OF_CONDUCT.adoc that has adopted the Contributor Covenant v2.0, and a CONTRIBUTING.adoc that the README points to as the starting point for contributors. On the licence question in particular, embedding the library in an internal service carries the standard obligations of that licence, and you should read the LICENSE file for the exact terms rather than take a summary as guidance.

Where Chaos Monkey for Spring Boot is the wrong tool

It is the wrong tool in several fairly ordinary situations, and the project says most of this itself. If your services are not yet resilient, an experiment tells you that they are not resilient, at the cost of a disrupted environment and a conversation with the people who were paged. If you cannot define a steady state metric, there is no way to tell whether the experiment succeeded, which removes the only objective output the tool produces.

It is also the wrong tool when the environment cannot be isolated. The runtime assault mode attacks the whole application, so a system with no separate staging environment has no safe place to try it. The README's guidance to look for first experiences on another stage is not optional in that case, and if the organisation has no other stage, the honest answer is that this project cannot be used safely yet.

Finally, it is the wrong tool for a team that wants measured resilience numbers rather than qualitative discovery. The project reports and measures no latency distribution, no error budget and no recovery time. It produces failures and observations. If what you need is a regression test that runs in CI on every commit and asserts a response time budget, that is a different kind of tool, and this one does not aim to be it.

Editorial conclusion

Adopt chaos-monkey-spring-boot if your team can define a steady state metric, already watches the system, and has somewhere safe to run experiments that is not production. Do not adopt it as a first line of resilience work, because the project itself tells you to check that your services already handle failures before you start. Verify first that the released version you pin matches your Spring Boot generation, since v4.0.0 and v3.3.0 were published on the same day, and read the watchers and runtime assaults pages of the documentation site for the settings your application exposes.

Frequently asked questions

Official sources

1. codecentric/chaos-monkey-spring-boot on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases