Mutineer

A chaos engineering library for Elixir inspired by Netflix's Chaos Monkey. Mutineer allows you to inject controlled, random failures into your functions to test resilience and error handling.

Features

• Wrap functions to randomly trigger failures at configurable rates
• Multiple failure types: errors, exceptions, timeouts, nil returns, and process exits
• Minimal runtime overhead when disabled
• Two flexible APIs: attribute-based decorators or explicit macros
• Disabled by default for safety

Installation

Add mutineer to your list of dependencies in mix.exs:

defdepsdo[{:mutineer,"~> 0.2.0"}]end

Configuration

Configure Mutineer in your config/config.exs (or environment-specific config):

config:mutineer,Mutineer,enabled: true,default_failure_rate: 0.1,default_failure_types: :error

Usage

Attribute-based API

Add the use Mutineer statement to your module. You can then use the @chaos attribute to mark functions for chaos injection:

defmoduleMyApp.DatabasedouseMutineer@chaosfailure_rate: 0.2defquery(sql)do# Your database query logicend@chaosfailure_type: :timeout,delay: 3000defslow_query(sql)do# This will randomly timeoutendend

Macro-based API

Use defchaos or defchaosp (for private functions) for explicit chaos wrapping:

defmoduleMyApp.ExternalServicedouseMutineerdefchaoscall_api(endpoint),failure_rate: 0.3,failure_type: :raisedo# Your API call logicenddefchaospinternal_helper(data),failure_rate: 0.1do# Private function with chaosendend

Global configuration options

• enabled - Enables or disables chaos globally (default: false)
• default_failure_types - Sets the default failure types for all functions, can be a list of failure types or a single failure type (default: :error)
• default_failure_rate - Sets the default failure rate for all functions (default: 0.1)

Failure Types

• :error - Returns {:error, :mutineer_chaos} (default) or a random error from the errors option
• :raise - Raises either a Mutineer.ChaosError exception (default) or a custom error specified in the raised_errors option
• :delay - Introduces a random delay (1-5 seconds) before executing function
• :timeout - Same as :raise, but with a random delay before raising the exception
• :nil - Returns nil
• :exit - Calls exit(:mutineer_chaos); the atom can be specified in the exit_errors option

Failure Options

Options can be passed to @chaos, defchaos, or defchaosp:

• failure_rate is the probability of failure for a given function (0.0 - 1.0), where 1.0 or above will always fail
• failure_types (or failure_type) is either a list of failure types to trigger (e.g. [:error, :delay]) or a single failure type (e.g. :error)
• errors (or error) is either a list of objects to be randomly selected from or a single object to return when the :error type is triggered
• raised_errors (or raised_error) is a list of errors to be randomly selected from or a single error to be raised when the :raise type is triggered
• exit_errors (or exit_error) is a list of errors to be randomly selected from or a single error to be raised when the :exit type is triggered
• delay is the upperbound of the delay in milliseconds or a range of milliseconds for :timeout and :delay types

Example

defmoduleMyApp.PaymentGatewaydouseMutineer@chaosfailure_rate: 0.1,failure_type: :errordefprocess_payment(amount,card)do# Payment processing logic{:ok,%{transaction_id: "txn_123",amount: amount}}end@chaosfailure_rate: 0.05,failure_type: :raise,message: "Gateway timeout"defverify_card(card)do# Card verification logic{:ok,:valid}endend# In your tests or staging environment:caseMyApp.PaymentGateway.process_payment(100,card)do{:ok,result}->handle_success(result){:error,reason}->handle_error(reason)end

# config/dev.exsconfig:mutineer,Mutineer,enabled: true,default_failure_rate: 0.1# config/prod.exsconfig:mutineer,Mutineer,enabled: false