Chaos Engineering — Communication is key

The new ‘report` command in the Chaos Toolkit for greater communication and collaboration in your chaos experiments

Sample PDF produced from the Chaos Toolkit’s new `chaos report` command.
“So what have we learned…?” — using ‘chaos report’ to collaborate and communicate on what has been learned in your chaos experiments.

The key characteristic for any chaos engineer, above the innate care and attention and curiosity necessary to experiment and improve complex, distributed systems in order to attain better availability, is in fact a personality trait.

That key personality trait is empathy, and the mechanism by which a successful chaos engineer applies it is through constant communication about the chaos being run and the results of those experiments.

With great power…comes the need for great collaboration

“Chaos engineering is a highly collaborative endeavour”

Chaos engineers have the potential to cause great harm in their work, and nothing amplifies that harm better than if it comes as a surprise to the teams involved.

“I’ve run chaos monkey on your system, hope that’s ok?” is not a question a successful chaos engineering should be making.

Chaos engineering is a highly collaborative endeavour. Chaos engineers work closely with, and sometimes in, the teams that are affected by the experiments being run. Often the teams themselves come up with the experiments they want to run to build their own confidence in their services and systems’s availability.

Extending the Chaos Toolkit’s Workflow for Greater Collaboration

From its inception the Chaos Toolkit has tried to enable a higher-level workflow for creating and running chaos experiments to enable widespread learning on how to improve the systems that are under stress.

Initially the Chaos Toolkit’s declarative json experiment format provided a great way to discuss and build your experiments without getting bogged down in the particulars of various chaos-creating systems.

Then the toolkit was extended with the discover and init commands so we could also suggest and help you work through what is available and detectable in your systems to bootstrap your experiments quickly.

With discover and init the Chaos Toolkit had a workflow that helped collaboration on chaos experiments right through to running the experiments themselves with discover->init->run.

Adding ‘chaos report’ to Complete the Collaborative Workflow

Now the discover->init->run workflow has been extended again with the report command: discover->init->run->report.

Currently the chaos report command supports exporting to a number of useful formats, for example HTML:

$ chaos report — export-format=html5 chaos-report.json report.html

And also PDF:

$ chaos report — export-format=pdf chaos-report.json report.pdf

With the report command you can now generate great reports that can be provided to everyone interested in the outcomes and findings from your chaos experiments, closing the loop of continuous discovery and improvement in your systems through the collaborative discipline of chaos engineering.

You can use ‘chaos report’ right now!

The new report command is a plugin to the Chaos Toolkit’s command line, which you can install by executing:

$ pip install -U chaostoolkit-reporting

NOTE: You will need to install some supporting libraries for the various formats for your operating system. At the moment Linux support is completed and we are working on other operating systems.

Also if you’d like to see the report command in action without installing anything locally, you can give it a spin using the free Chaos Toolkit tutorials now available on the awesome Katacoda system.


With chaos report we now have the full workflow for the Chaos Toolkit: discover->init->run->report.

As always though, this is a community-driven project and we’d love to get your feedback and input into the Chaos Toolkit. Whether you’re interested in new extensions, correcting bugs you see, or even just up-voting the issues and projects to let us know you find them interesting or useful, it’s your engagement with the projects that makes things happen.

To get involved you can join our community Slack team and chat to other contributors, raise issues, or just peruse the projects or reference documentation. All input is valuable and we are dedicated to maintaining an open and friendly environment for everyone to contribute into.