Skip to main content

Chaos Engineering Toolkit automation framework

Project description

Chaos Toolkit - An Open API for Chaos Engineering

Version License


Downloads Docker Pulls Python versions Requirements Status Has wheel

Chaos Toolkit is a project whose mission is to provide a free, open and community-driven toolkit and API to all the various forms of chaos engineering tools that the community needs.

Why the Chaos Toolkit?

The Chaos Toolkit has two main purposes:

  • To provide a full chaos engineering implementation that simplifies the adoption of chaos engineering by providing an easy starting point for applying the discipline.
  • To define an open API with the community so that any chaos experiment can be executed consistently using integrations with the many commercial, private and open source chaos implementations that are emerging.

Chaos Toolkit

Simplifying Adoption of Chaos Engineering

Firstly the Chaos Toolkit aims to make it simple and straightforward to run experiments against your live system to build confidence in its behavior and learn about potential weaknesses.

Following the principles of chaos engineering, the Chaos Toolkit aims to be the easiest way to apply these principles to your own complex, and even sometimes chaotic, systems.

An Open API to Chaos Engineering

Secondly the Chaos Toolkit defines an Open API to Chaos Engineering through it's JSON/YAML-format experiment definition. The toolkit can be extended to integrate with any number of commercial, private and open source chaos implementations through probes (to measure steady-state before and after an experiment) and actions (to vary real-world events during an experiment).

Install or Upgrade

Install from Packages

Generally speaking, you can install it as follows:

$ pip install -U chaostoolkit

It is recommended that you create a Python virtual environment for running your chaos experiments. Full instructions for installing chaostoolkit and its requirements are available in the installation documentation.

Download and run the bundle

While installing via packages gives you the most control over what to deploy, you may also be interested in simply dowloading a standalone binary that can be run as-is.

Download a copy from here.

Whenever a new version is released, just download its copy again.

Getting Started

Once you have installed the Chaos Toolkit you can use it through its simple command line tool. The tool's main job is to run your experiment and then generate a report of the findings from the experiment to then share with your team for discussion.

Running an experiment is as simple as:

$ chaos run experiment.json

The Chaos Toolkit takes experiments defined in a JSON format description file, encoded in JSON (YAML is also supported), and runs its steps sequentially. A full specification of this experiment description file can be found in the main project documentation.

Chaos Toolkit Run Sample

Extending the Chaos Toolkit

The Chaos Toolkit plays the experiment description that you provide to it. Experiments are made up of probes and actions (to vary real-world events during an experiment). We are always looking for community contribution and ideas around what probes and actions you might need as you integrate chaos experiments through the Chaos Toolkit, into your own unique context and environment.

If you have an idea for a new set of probes and actions that you'd like to share, please first consider raising a ticket or even joining our community slack to suggest your idea.

In terms of implementation, the Chaos Toolkit currently supports probes and actions implemented as Python functions, separate processes or even remote HTTP calls. As long as your extensions conform to the Chaos Toolkit API you can then specify your own unique extensions in your experiment definitions.

The core implementation of the Chaos Toolkit API can be found in the chaostoolkit-lib project.

Current Known Extensions

The Chaos Toolkit is made of many extensions that you can simply download and add to your environment to use.

Get involved!

Chaos Toolkit's mission is to provide an open API to chaos engineering in all its forms. As such, we encourage and welcome you to join our open community Slack team to discuss and share your experiments and needs with the community. You can also use StackOverflow to ask any questions regarding using the Chaos Toolkit or Chaos Engineering.

If you'd prefer not to use Slack then we welcome the raising of GitHub issues on this repo for any questions, requests, or discussions around the Chaos Toolkit.

Finally you can always email with any questions as well.


Contributors to this project are welcome as this is an open-source effort that seeks discussions and continuous improvement.

From a code perspective, if you wish to contribute, you will need to run a Python 3.7+ environment. Please, fork this project, write unit tests to cover the proposed changes, implement the changes, ensure they meet the formatting standards set out by black, flake8, and isort, add an entry into, and then raise a PR to the repository for review

Please refer to the formatting section for more information on the formatting standards.

The Chaos Toolkit projects require all contributors must sign a Developer Certificate of Origin on each commit they would like to merge into the master branch of the repository. Please, make sure you can abide by the rules of the DCO before submitting a PR.


If you wish to develop on this project, make sure to install the development dependencies. But first, create a virtual environment and then install those dependencies.

$ make install-dev

Now, you can edit the files and they will be automatically be seen by your environment, even when running from the chaos command locally.


To run the tests for the project execute the following:

$ make tests

Formatting and Linting

We use a combination of black, flake8, and isort to both lint and format this repositories code.

Before raising a Pull Request, we recommend you run formatting against your code with:

$ make format

This will automatically format any code that doesn't adhere to the formatting standards.

As some things are not picked up by the formatting, we also recommend you run:

$ make lint

To ensure that any unused import statements/strings that are too long, etc. are also picked up.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

chaostoolkit-1.11.0.tar.gz (601.6 kB view hashes)

Uploaded source

Built Distribution

chaostoolkit-1.11.0-py2.py3-none-any.whl (19.1 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page