ExResilience.Chaos (ex_resilience v0.4.0)

Copy Markdown View Source

Stateless fault injection for testing resilience pipelines.

Injects errors and/or latency into function calls based on configurable probabilities. Useful for verifying that upstream resilience layers (retry, circuit breaker, etc.) handle failures correctly.

Options

  • :name -- optional atom for telemetry metadata. Default :chaos.
  • :error_rate -- probability of injecting an error (0.0 to 1.0). Default 0.0.
  • :error_fn -- 0-arity function returning the error value. Default: ExResilience.Chaos.default_error/0.
  • :latency_rate -- probability of injecting latency (0.0 to 1.0). Default 0.0.
  • :latency_min -- minimum injected latency in milliseconds. Default 0.
  • :latency_max -- maximum injected latency in milliseconds. Default 100.
  • :seed -- optional integer RNG seed for deterministic behavior.

Execution Order

  1. If :seed is provided, seed the process RNG.
  2. Roll for latency injection. If triggered, sleep for a random duration in [latency_min, latency_max].
  3. Roll for error injection. If triggered, return error_fn.() without calling the wrapped function.
  4. Otherwise, call the wrapped function and return its result.

Examples

iex> ExResilience.Chaos.call(fn -> {:ok, 1} end, error_rate: 0.0, latency_rate: 0.0)
{:ok, 1}

iex> ExResilience.Chaos.call(fn -> {:ok, 1} end, error_rate: 1.0)
{:error, :chaos_fault}

Summary

Types

option()

Functions

call(fun, opts \\ [])

Executes fun with optional fault injection.

default_error()

Returns the default error value used when no :error_fn is provided.

Types

option()

@type option() ::
  {:name, atom()}
  | {:error_rate, float()}
  | {:error_fn, (-> term())}
  | {:latency_rate, float()}
  | {:latency_min, non_neg_integer()}
  | {:latency_max, non_neg_integer()}
  | {:seed, integer()}

Functions

call(fun, opts \\ [])

@spec call((-> term()), [option()]) :: term()

Executes fun with optional fault injection.

See module documentation for available options and execution order.

Examples

iex> ExResilience.Chaos.call(fn -> :ok end, error_rate: 0.0)
:ok

iex> ExResilience.Chaos.call(fn -> :ok end, error_rate: 1.0, error_fn: fn -> {:error, :boom} end)
{:error, :boom}

default_error()

@spec default_error() :: {:error, :chaos_fault}

Returns the default error value used when no :error_fn is provided.