Implementation of the circuit breaker pattern in Ruby, backed by Redis
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Gem version Build Status

Implementation of the circuit breaker pattern in Ruby, backed by Redis.

Setup circuit breakers wrapping external service calls, be it HTTP, TCP, etc. When a service becomes unavailable the circuit breaker will open and quickly refuse any additional requests to it. After a specific window the breaker closes again, allowing calls to go through.

This pattern makes your application more resilient to third party failures, because it won't exhaust resources trying to make calls to an unresponsive service. This is particularly relevant to apps running on servers susceptible to request queuing, like Unicorn or Puma. It can also help the services you depend on to recover faster, by reducing the load on them.

CB2 tracks errors over a rolling window of time (size configurable), and opens after the error rate hits a certain percentage. The circuit stays open (rejecting calls) for another specified period, and then from there it goes to the half-open state: in which a succesful request will make it close again, but a failure will put it immediatelly back at the open state. Martin Fowler has a nice diagram to further explain these states.


Instantiate a circuit breaker:

breaker =
  service: "aws"       # identify each circuit breaker individually
  duration: 60,        # keep track of errors over a 1 min window
  threshold: 5,        # open the circuit breaker when error rate is at 5%
  reenable_after: 600, # keep it open for 10 mins
  redis:    # redis connection it should use to keep state

Then wrap service calls with it: do

The breaker will open when that block raises enough exceptions to trigger the threshold. Handle these exceptions to react accordingly:

begin do
rescue CB2::BreakerOpen
  alternate_response() # fallback to cached data, or raise a user-friendly exception

Circuit breaker stub

CB2 can also run as a stub. Use it to aid testing, simulations and gradual rollouts:

breaker =
  strategy: "stub",
  allow: true) # set it to false to always block requests

See also

This might be the only percent-based breaker in Ruby so far. For count-based breakers (eg: open after X exceptions) you can also check breaker_box and circuit_breaker.


Created by Pedro Belo.