Skip to main content

Chaos engineering toolkit core library

Project description

Chaos Toolkit Core Library

Version License

Build Status codecov Python versions

The Chaos Toolkit core library implementing the Open Chaos Initiative.

Chaos Toolkit


The purpose of this library is to provide the core of the Chaos Toolkit model and functions it needs to render its services.

Unless you wish to create your own toolkit, you will likely not use directly this library.


The library provides the followings features:

  • discover capabilities from extensions Allows you to explore the support from an extension that would help you initialize an experiment against the system this extension targets

  • validate a given experiment syntax The validation looks at various keys in the experiment and raises errors whenever something doesn't look right. As a nice addition, when a probe calls a Python function with arguments, it tries to validate the given argument list matches the signature of the function to apply.

  • run your steady state before and after the method. The former as a gate to decide if the experiment can be executed. The latter to see if the system deviated from normal.

  • run probes and actions declared in an experiment It runs the steps in a experiment method sequentially, applying first steady probes, then actions and finally close probes.

    A journal, as a JSON payload, is return of the experiment run.

    The library supports running probes and actions defined as Python functions, from importable Python modules, processes and HTTP calls.

  • run experiment's rollbacks when provided

  • Load secrets from the experiments, the environ or vault

  • Provides event notification from Chaos Toolkit flow (although the actual events are published by the CLI itself, not from this library), supported events are:

    • on experiment validation: started, failed or completed
    • on discovery: started, failed or completed
    • on initialization of experiments: started, failed or completed
    • on experiment runs: started, failed or completed

    For each event, the according payload is part of the event as well as a UTC timestamp.


If you are user of the Chaos Toolkit, you probably do not need to install this package yourself as it comes along with the chaostoolkit cli.

However, should you wish to integrate this library in your own Python code, please install it as usual:

$ pip install -U chaostoolkit-lib

Specific dependencies

In addition to essential dependencies, the package can install a couple of other extra dependencies for specific use-cases. They are not mandatory and the library will warn you if you try to use a feature that requires them.


If you need Vault support to read secrets from, run the following command:

$ pip install -U chaostoolkit-lib[vault]

To authenticate with Vault, you can either:

  • Use a token through the vault_token configuration key
  • Use an AppRole via the vault_role_id, vault_secret_id pair of configuration keys
  • Use a service account configured with an appropriate role via the vault_sa_role configuration key. The vault_sa_token_path, vault_k8s_mount_point, and vault_secrets_mount_point configuration keys can optionally be specified to point to a location containing a service account token, a different Kubernetes authentication method mount point, or a different secrets mount point, respectively.


If you need JSON Path support for tolerance probes in the hypothesis, also run the following command:

$ pip install -U chaostoolkit-lib[jsonpath]

When using a process activity, the standard output end error streams are logged into the chaostoolkit.log file. The default encoding used is utf-8 to decode those streams. Sometimes, this is not the right encoding, so you can install the chardet or cchardet packages to attempt the detection of the right encoding.

$ pip install -U chaostoolkit-lib[decoders]


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.5+ environment. Then, fork this repository and submit a PR. The project cares for code readability and checks the code style to match best practices defined in PEP8. Please also make sure you provide tests whenever you submit a PR so we keep the code reliable.

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.

$ pip install -r requirements-dev.txt -r requirements.txt

Then, point your environment to this directory:

$ pip install -e .

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:

$ pytest

Project details

Download files

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

Files for chaostoolkit-lib, version 1.16.0
Filename, size File type Python version Upload date Hashes
Filename, size chaostoolkit_lib-1.16.0-py3-none-any.whl (57.2 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size chaostoolkit-lib-1.16.0.tar.gz (59.3 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page