faulty 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0712dd797dfe2922e4e52a792f48c5ac72c4b9766d218dfa597e7ad630f9fd0
-  data.tar.gz: fb4a787507006131f34a301fc164466fd8befb72051550ca0a63fc2d69ec949c
+  metadata.gz: 7e68341d29ccefb2a4fa4c265f3f2d5ec37371d37cb41d5a186b3f25d2130b46
+  data.tar.gz: 56e659d66871738e8818c4874102de04ef97873cb0d1c444d58259c875b21378
 SHA512:
-  metadata.gz: 5381dd13f058045906330c67ff80aeefac55ae81077eb4552d5461d743344fa097e205b8ac3a39b385c52976e64315aec4e903c1a0c298a05452fab7788d1df2
-  data.tar.gz: af31cbf86cac54226189f8f63b1d8b0bcf82f9023085e98d07e4e9db65e402883c2219dbf255e21427c40b0c0a66ec71bd4dc9dfdd94fb9bc7b574ddf8426674
+  metadata.gz: 7db7b915923132bd1e5d234245cc5a3adb5988013f4baf8fadc59f89bacfde6828310954f0d6ea9da59ed18c97b9224e3d0f9e02ce2700ef9f6240e8b14d3706
+  data.tar.gz: 578d4f0473ff58b1a9f6aeb3d2eab4be158de92943d6147e1521212068578ecd190094e17b02838919561d43b477b197344804478aa8288e70d0c30b26f85fd9

data/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+---
+name: CI
+on:
+  push:
+    tags: ['v*']
+    branches: [master]
+  pull_request:
+    branches: ['**']
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        redis: [4]
+        ruby: [2.3, 2.4, 2.5, 2.6, 2.7, 3.0, jruby-9.2.10, truffleruby-20.2.0]
+        include:
+          - redis: 3
+            ruby: 2.7
+    services:
+      redis:
+        image: redis
+        ports:
+          - 6379:6379
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - run: bundle exec rubocop
+        if: matrix.ruby == '2.7'
+      - run: bundle exec rspec --format doc
+      - name: Run codacy-coverage-reporter
+        uses: codacy/codacy-coverage-reporter-action@master
+        with:
+          project-token: ${{ secrets.CODACY_PROJECT_TOKEN }}
+          coverage-reports: coverage/lcov/faulty.lcov
+      - run: bin/check-version
+
+  release:
+    needs: test
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: dawidd6/action-publish-gem@v1
+        with:
+          api_key: ${{secrets.RUBYGEMS_API_KEY}}

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## Release v0.4.0
+
+* Switch from Travis CI to GitHub actions #11 justinhoward
+* Only run rubocop for Ruby 2.7 in CI #12 justinhoward
+* Explicitly add support for Redis 3 and 4 #15 justinhoward
+* Allow setting default circuit options on Faulty instances #16 justinhoward
+* Switch to codacy for quality metrics #17 justinhoward
+* Small logic fix to README #19 silasb
+* Fix Redis storage dependency on ConnectionPool #21 justinhoward
+* Allow passing custom circuit to AutoWire #22 justinhoward
+
+### Breaking Changes
+
+AutoWire.new is replaced with AutoWire.wrap and no longer creates an instance
+of AutoWire.
+
 ## Release v0.3.0
 
 * Add tools for backend fault-tolerance #10

data/Gemfile

@@ -16,7 +16,12 @@ gem 'byebug', platforms: not_jruby
 gem 'irb', '~> 1.0'
 gem 'redcarpet', '~> 3.5', platforms: not_jruby
 gem 'rspec_junit_formatter', '~> 0.4'
-# For now, code climate doesn't support simplecov 0.18
-# https://github.com/codeclimate/test-reporter/issues/413
-gem 'simplecov', '>= 0.17.1', '< 0.18'
+gem 'simplecov', '>= 0.17.1'
+# 0.8 is incompatible with simplecov < 0.18
+# https://github.com/fortissimo1997/simplecov-lcov/pull/25
+gem 'simplecov-lcov', '~> 0.7', '< 0.8'
 gem 'yard', '~> 0.9.25', platforms: not_jruby
+
+if ENV['REDIS_VERSION']
+  gem 'redis', "~> #{ENV['REDIS_VERSION']}"
+end

data/README.md

@@ -1,19 +1,100 @@
 # Faulty
 
 [![Gem Version](https://badge.fury.io/rb/faulty.svg)](https://badge.fury.io/rb/faulty)
-[![Build Status](https://travis-ci.org/ParentSquare/faulty.svg?branch=master)](https://travis-ci.org/ParentSquare/faulty)
-[![Code Climate](https://codeclimate.com/github/ParentSquare/faulty/badges/gpa.svg)](https://codeclimate.com/github/ParentSquare/faulty)
-[![Test Coverage](https://codeclimate.com/github/ParentSquare/faulty/badges/coverage.svg)](https://codeclimate.com/github/ParentSquare/faulty)
+[![CI](https://github.com/ParentSquare/faulty/workflows/CI/badge.svg)](https://github.com/ParentSquare/faulty/actions?query=workflow%3ACI+branch%3Amaster)
+[![Code Quality](https://app.codacy.com/project/badge/Grade/16bb1df1569a4ddba893a866673dac2a)](https://www.codacy.com/gh/ParentSquare/faulty/dashboard?utm_source=github.com&utm_medium=referral&utm_content=ParentSquare/faulty&utm_campaign=Badge_Grade)
+[![Code Coverage](https://app.codacy.com/project/badge/Coverage/16bb1df1569a4ddba893a866673dac2a)](https://www.codacy.com/gh/ParentSquare/faulty/dashboard?utm_source=github.com&utm_medium=referral&utm_content=ParentSquare/faulty&utm_campaign=Badge_Coverage)
 [![Inline docs](http://inch-ci.org/github/ParentSquare/faulty.svg?branch=master)](http://inch-ci.org/github/ParentSquare/faulty)
 
 Fault-tolerance tools for ruby based on [circuit-breakers][martin fowler].
 
+**Without Faulty**
+
+External dependencies like APIs can start failing at any time When they do, it
+could cause cascading failures in your application.
+
 ```ruby
-users = Faulty.circuit(:api).try_run do
+# The application will always try to execute this even if the API
+# fails repeatedly
+api.users
+```
+
+**With Faulty**
+
+Faulty monitors errors inside this block and will "trip" a circuit if your
+threshold is passed. Once a circuit is tripped, Faulty stops executing this
+block until it recovers. Your application can detect external failures, and
+prevent their effects from degrading overall performance.
+
+```ruby
+users = Faulty.circuit('api').try_run do
+
+  # If this raises an exception, it counts towards the failure rate
+  # The exceptions that count as failures are configurable
+  # All failures will be sent to your event listeners for monitoring
   api.users
+
 end.or_default([])
+# Here we return a stubbed value so the app can continue to function
+# Another strategy is just to re-raise the exception so the app can handle it
+# or use its default error handler
 ```
 
+See [What is this for?](#what-is-this-for) for a more detailed explanation.
+Also see "Release It!: Design and Deploy Production-Ready Software" by
+[Michael T. Nygard][michael nygard] and the
+[Martin Fowler Article][martin fowler] post on circuit breakers.
+
+## Contents
+
+* [Installation](#installation)
+* [API Docs](#api-docs)
+* [Setup](#setup)
+* [Basic Usage](#basic-usage)
+* [What is this for?](#what-is-this-for-)
+* [Configuration](#configuration)
+  + [Configuring the Storage Backend](#configuring-the-storage-backend)
+    - [Memory](#memory)
+    - [Redis](#redis)
+    - [FallbackChain](#fallbackchain)
+    - [Storage::FaultTolerantProxy](#storagefaulttolerantproxy)
+    - [Storage::CircuitProxy](#storagecircuitproxy)
+  + [Configuring the Cache Backend](#configuring-the-cache-backend)
+    - [Null](#null)
+    - [Rails](#rails)
+    - [Cache::FaultTolerantProxy](#cachefaulttolerantproxy)
+    - [Cache::CircuitProxy](#cachecircuitproxy)
+  + [Multiple Configurations](#multiple-configurations)
+    - [The default instance](#the-default-instance)
+    - [Multiple Instances](#multiple-instances)
+    - [Standalone Instances](#standalone-instances)
+* [Working with circuits](#working-with-circuits)
+  + [Running a Circuit](#running-a-circuit)
+    - [With Exceptions](#with-exceptions)
+    - [With Faulty::Result](#with-faultyresult)
+  + [Specifying the Captured Errors](#specifying-the-captured-errors)
+  + [Using the Cache](#using-the-cache)
+  + [Configuring the Circuit Threshold](#configuring-the-circuit-threshold)
+    - [Rate Threshold](#rate-threshold)
+    - [Sample Threshold](#sample-threshold)
+    - [Cool Down](#cool-down)
+  + [Circuit Options](#circuit-options)
+  + [Listing Circuits](#listing-circuits)
+  + [Locking Circuits](#locking-circuits)
+* [Event Handling](#event-handling)
+  + [CallbackListener](#callbacklistener)
+  + [Other Built-in Listeners](#other-built-in-listeners)
+  + [Custom Listeners](#custom-listeners)
+* [How it Works](#how-it-works)
+  + [Caching](#caching)
+  + [Fault Tolerance](#fault-tolerance)
+* [Implementing a Cache Backend](#implementing-a-cache-backend)
+* [Implementing a Storage Backend](#implementing-a-storage-backend)
+* [Alternatives](#alternatives)
+  + [Currently Active](#currently-active)
+  + [Previous Work](#previous-work)
+  + [Faulty's Unique Features](#faulty-s-unique-features)
+
 ## Installation
 
 Add it to your `Gemfile`:
@@ -28,8 +109,10 @@ Or install it manually:
 gem install faulty
 ```
 
-During your app startup, call `Faulty.init`. For Rails, you would do this in
-`config/initializers/faulty.rb`. See [Setup](#setup) for details.
+During your app startup, call
+[`Faulty.init`](https://www.rubydoc.info/gems/faulty/Faulty.init).
+For Rails, you would do this in `config/initializers/faulty.rb`. See
+[Setup](#setup) for details.
 
 ## API Docs
 
@@ -64,66 +147,31 @@ Faulty.init do |config|
 end
 ```
 
-For a full list of configuration options, see the
-[Global Configuration](#global-configuration) section.
-
-## What is this for?
-
-Circuit breakers are a fault-tolerance tool for creating separation between your
-application and external dependencies. For example, your application may call an
-external API to send a text message:
-
-```ruby
-TextApi.send(message)
-```
-
-In normal operation, this API call is very fast. However what if the texting
-service started hanging? Your application would quickly use up a lot of
-resources waiting for requests to return from the service. You could consider
-adding a timeout to your request:
-
-```ruby
-TextApi.send(message, timeout: 5)
-```
-
-Now your application will terminate requests after 5 seconds, but that could
-still add up to a lot of resources if you call this thousands of times. Circuit
-breakers solve this problem.
+Or use a faulty instance instead for an object-oriented approach
 
 ```ruby
-Faulty.circuit(:text_api).run do
-  TextApi.send(message, timeout: 5)
+faulty = Faulty.new do
+  config.storage = Faulty::Storage::Redis.new
 end
 ```
 
-Now, when the text API hangs, the first few will run and start timing out. This
-will trip the circuit. After the circuit trips
-(see [How it Works](#how-it-works)), calls to the text API will be paused for
-the configured cool down period. Your application resources are not overwhelmed.
-
-You are free to implement a fallback or error handling however you wish, for
-example, in this case, you might add the text message to a failure queue:
-
-```ruby
-Faulty.circuit(:text_api).run do
-  TextApi.send(message, timeout: 5)
-rescue Faulty::CircuitError => e
-  FailureQueue.enqueue(message)
-end
-```
+For a full list of configuration options, see the
+[Configuration](#configuration) section.
 
 ## Basic Usage
 
-To create a circuit, call `Faulty.circuit`. This can be done as you use the
-circuit, or you can set it up beforehand. Any options passed to the `circuit`
-method are synchronized across threads and saved as long as the process is alive.
+To create a circuit, call
+[`Faulty.circuit`](https://www.rubydoc.info/gems/faulty/Faulty.circuit).
+This can be done as you use the circuit, or you can set it up beforehand. Any
+options passed to the `circuit` method are synchronized across threads and saved
+as long as the process is alive.
 
 ```ruby
-circuit1 = Faulty.circuit(:api, cache_refreshes_after: 1800)
+circuit1 = Faulty.circuit(:api, rate_threshold: 0.6)
 
 # The options from above are also used when called here
 circuit2 = Faulty.circuit(:api)
-circuit2.options.cache_refreshes_after == 1800 # => true
+circuit2.options.rate_threshold == 0.6 # => true
 
 # The same circuit is returned on each consecutive call
 circuit1.equal?(circuit2) # => true
@@ -140,11 +188,12 @@ end
 See [How it Works](#how-it-works) for more details about how Faulty handles
 circuit failures.
 
-If the `run` block above fails, a `Faulty::CircuitError` will be raised. It is
-up to your application to handle that error however necessary or crash. Often
-though, you don't want to crash your application when a circuit fails, but
-instead apply a fallback or default behavior. For this, Faulty provides the
-`try_run` method:
+If the `run` block above fails, a
+[`Faulty::CircuitError`](https://www.rubydoc.info/gems/faulty/Faulty/CircuitError)
+will be raised. It is up to your application to handle that error however
+necessary or crash. Often though, you don't want to crash your application when
+a circuit fails, but instead apply a fallback or default behavior. For this,
+Faulty provides the `try_run` method:
 
 ```ruby
 result = Faulty.circuit(:api).try_run do
@@ -158,11 +207,13 @@ else
 end
 ```
 
-The `try_run` method returns a result type instead of raising errors. See the
-API docs for `Result` for more information. Here we use it to check whether the
-result is `ok?` (not an error). If it is we set the users variable, otherwise we
-set a default of an empty array. This pattern is so common, that `Result` also
-implements a helper method `or_default` to do the same thing:
+The [`try_run`](https://www.rubydoc.info/gems/faulty/Faulty/Circuit:try_run)
+method returns a result type instead of raising errors. See the API docs for
+[`Result`](https://www.rubydoc.info/gems/faulty/Faulty/Result) for more
+information. Here we use it to check whether the result is `ok?` (not an error).
+If it is we set the users variable, otherwise we set a default of an empty
+array. This pattern is so common, that `Result` also implements a helper method
+`or_default` to do the same thing:
 
 ```ruby
 users = Faulty.circuit(:api).try_run do
@@ -170,40 +221,54 @@ users = Faulty.circuit(:api).try_run do
 end.or_default([])
 ```
 
-## How it Works
+See [Running a Circuit](#running-a-circuit) for more in-depth examples. Also,
+make sure you have proper [Event Handlers](#event-handling) setup so that you
+can monitor your circuits for failures.
 
-Faulty implements a version of circuit breakers inspired by "Release It!: Design
-and Deploy Production-Ready Software" by [Michael T. Nygard][michael nygard] and
-[Martin Fowler's post][martin fowler] on the subject. A few notable features of
-Faulty's implementation are:
+## What is this for?
 
-- Rate-based failure thresholds
-- Integrated caching inspired by Netflix's [Hystrix][hystrix] with automatic
-  cache jitter and error fallback.
-- Event-based monitoring
-- Flexible fault-tolerant storage with optional fallbacks
+Circuit breakers are a fault-tolerance tool for creating separation between your
+application and external dependencies. For example, your application may call an
+external API to send a text message:
 
-Following the principals of the circuit-breaker pattern, the block given to
-`run` or `try_run` will always be executed as long as it never raises an error.
-If the block _does_ raise an error, then the circuit keeps track of the number
-of runs and the failure rate.
+```ruby
+TextApi.send(message)
+```
 
-Once both thresholds are breached, the circuit is opened. Once open, the
-circuit starts the cool-down period. Any executions within that cool-down are
-skipped, and a `Faulty::OpenCircuitError` will be raised.
+In normal operation, this API call is very fast. However what if the texting
+service started hanging? Your application would quickly use up a lot of
+resources waiting for requests to return from the service. You could consider
+adding a timeout to your request:
 
-After the cool-down has elapsed, the circuit enters the half-open state. In this
-state, Faulty allows a single execution of the block as a test run. If the test
-run succeeds, the circuit is fully opened and the circuit state is reset. If the
-test run fails, the circuit is closed and the cool-down is reset.
+```ruby
+TextApi.send(message, timeout: 5)
+```
 
-Each time the circuit changes state or executes the block, events are raised
-that are sent to the Faulty event notifier. The notifier should be used to track
-circuit failure rates, open circuits, etc.
+Now your application will terminate requests after 5 seconds, but that could
+still add up to a lot of resources if you call this thousands of times. Circuit
+breakers solve this problem.
 
-In addition to the classic circuit breaker design, Faulty implements caching
-that is integrated with the circuit state. See [Caching](#caching) for more
-detail.
+```ruby
+Faulty.circuit('text_api').run do
+  TextApi.send(message, timeout: 5)
+end
+```
+
+Now, when the text API hangs, the first few will run and start timing out. This
+will trip the circuit. After the circuit trips
+(see [How it Works](#how-it-works)), calls to the text API will be paused for
+the configured cool down period. Your application resources are not overwhelmed.
+
+You are free to implement a fallback or error handling however you wish, for
+example, in this case, you might add the text message to a failure queue:
+
+```ruby
+Faulty.circuit('text_api').run do
+  TextApi.send(message, timeout: 5)
+rescue Faulty::CircuitError => e
+  FailureQueue.enqueue(message)
+end
+```
 
 ## Configuration
 
@@ -222,6 +287,10 @@ Faulty.init do |config|
   # AutoWire API docs for more details.
   config.cache = Faulty::Cache::Default.new
 
+  # A hash of default options to be used when creating new Circuits.
+  # See Circuit Options below for a full list of these
+  config.circuit_defaults = {}
+
   # The storage backend. By default, Faulty uses an in-memory store. For most
   # production applications, you'll want a more robust backend. Faulty also
   # provides Faulty::Storage::Redis for this.
@@ -269,384 +338,537 @@ hash. For example, `Faulty.init` could be called like this:
 Faulty.init(cache: Faulty::Cache::Null.new)
 ```
 
-## Circuit Options
+### Configuring the Storage Backend
 
-A circuit can be created with the following configuration options. Those options
-are only set once, synchronized across threads, and will persist in-memory until
-the process exits. If you're using [multiple configurations](#multiple-configurations),
-the options are retained within the context of each instance. All options given
-after the first call to `Faulty.circuit` (or `Faulty#circuit`) are ignored.
+A storage backend is required to use Faulty. By default, it uses in-memory
+storage, but Redis is also available, along with a number of wrappers used to
+improve resiliency and fault-tolerance.
 
-This is because the circuit objects themselves are internally memoized, and are
-read-only once created.
+#### Memory
 
-The following example represents the defaults for a new circuit:
+The
+[`Faulty::Storage::Memory`](https://www.rubydoc.info/gems/faulty/Faulty/Storage/Memory)
+backend is the default storage backend. You may prefer this implementation if
+you want to avoid the complexity and potential failure-mode of cross-network
+circuit storage. The trade-off is that circuit state is only contained within a
+single process and will not be saved across application restarts. Locks will
+also be cleared on restart.
+
+The default configuration:
 
 ```ruby
-Faulty.circuit(:api) do |config|
-  # The cache backend for this circuit. Inherits the global cache by default.
-  config.cache = Faulty.options.cache
+Faulty.init do |config|
+  config.storage = Faulty::Storage::Memory.new do |storage|
+    # The maximum number of circuit runs that will be stored
+    storage.max_sample_size = 100
+  end
+end
+```
 
-  # The number of seconds before a cache entry is expired. After this time, the
-  # cache entry may be fully deleted. If set to nil, the cache will not expire.
-  config.cache_expires_in = 86400
+#### Redis
 
-  # The number of seconds before a cache entry should be refreshed. See the
-  # Caching section for more detail. A value of nil disables cache refreshing.
-  config.cache_refreshes_after = 900
+The [`Faulty::Storage::Redis`](https://www.rubydoc.info/gems/faulty/Faulty/Storage/Redis)
+backend provides distributed circuit storage using Redis. Although Faulty takes
+steps to reduce risk (See [Fault Tolerance](#fault-tolerance)), using
+cross-network storage does introduce some additional failure modes. To reduce
+this risk, be sure to set conservative timeouts for your Redis connection.
+Setting high timeouts will print warnings to stderr.
 
-  # The number of seconds to add or subtract from cache_refreshes_after
-  # when determining whether a cache entry should be refreshed. Helps mitigate
-  # the "thundering herd" effect
-  config.cache_refresh_jitter = 0.2 * config.cache_refreshes_after
+The default configuration:
 
-  # After a circuit is opened, the number of seconds to wait before moving the
-  # circuit to half-open.
-  config.cool_down = 300
+```ruby
+Faulty.init do |config|
+  config.storage = Faulty::Storage::Redis.new do |storage|
+    # The Redis client. Accepts either a Redis instance, or a ConnectionPool
+    # of Redis instances. A low timeout is highly recommended to prevent
+    # cascading failures when evaluating circuits.
+    storage.client = ::Redis.new(timeout: 1)
 
-  # The errors that will be captured by Faulty and used to trigger circuit
-  # state changes.
-  config.errors = [StandardError]
+    # The prefix to prepend to all redis keys used by Faulty circuits
+    storage.key_prefix = 'faulty'
 
-  # Errors that should be ignored by Faulty and not captured.
-  config.exclude = []
+    # A string to separate the parts of the redis key
+    storage.key_separator = ':'
 
-  # The event notifier. Inherits the global notifier by default
-  config.notifier = Faulty.options.notifier
+    # The maximum number of circuit runs that will be stored
+    storage.max_sample_size = 100
 
-  # The minimum failure rate required to trip a circuit
-  config.rate_threshold = 0.5
+    # The maximum number of seconds that a circuit run will be stored
+    storage.sample_ttl = 1800
 
-  # The minimum number of runs required before a circuit can trip
-  config.sample_threshold = 3
+    # The maximum number of seconds to store a circuit. Does not apply to
+    # locks, which are indefinite.
+    storage.circuit_ttl = 604_800 # 1 Week
 
-  # The storage backend for this circuit. Inherits the global storage by default
-  config.storage = Faulty.options.storage
+    # The number of seconds between circuit expirations. Changing this setting
+    # is not recommended. See API docs for more implementation details.
+    storage.list_granularity = 3600
+
+    # If true, disables warnings about recommended client settings like timeouts
+    storage.disable_warnings = false
+  end
 end
 ```
 
-Following the same convention as `Faulty.init`, circuits can also be created
-with an options hash:
+#### FallbackChain
 
-```ruby
-Faulty.circuit(:api, cache_expires_in: 1800)
-```
+The [`Faulty::Storage::FallbackChain`](https://www.rubydoc.info/gems/faulty/Faulty/Storage/FallbackChain)
+backend is a wrapper for multiple prioritized storage backends. If the first
+backend in the chain fails, consecutive backends are tried until one succeeds.
+The recommended use-case for this is to fall back on reliable storage if a
+networked storage backend fails.
 
-## Caching
+For example, you may configure Redis as your primary storage backend, with an
+in-memory storage backend as a fallback:
 
-Faulty integrates caching into it's circuits in a way that is particularly
-suited to fault-tolerance. To make use of caching, you must specify the `cache`
-configuration option when initializing Faulty or creating a new Faulty instance.
-If you're using Rails, this is automatically set to the Rails cache.
+```ruby
+Faulty.init do |config|
+  config.storage = Faulty::Storage::FallbackChain.new([
+    Faulty::Storage::Redis.new,
+    Faulty::Storage::Memory.new
+  ])
+end
+```
 
-Once your cache is configured, you can use the `cache` parameter when running
-a circuit to specify a cache key:
+Faulty instances will automatically use a fallback chain if an array is given to
+the `storage` option, so this example is equivalent to the above:
 
 ```ruby
-feed = Faulty.circuit(:rss_feeds)
-  .try_run(cache: "rss_feeds/#{feed}") do
-    fetch_feed(feed)
-  end.or_default([])
+Faulty.init do |config|
+  config.storage = [
+    Faulty::Storage::Redis.new,
+    Faulty::Storage::Memory.new
+  ]
+end
 ```
 
-By default a circuit has the following options:
+If the fallback chain fails-over to backup storage, circuit states will not
+carry over, so failover could be temporarily disruptive to your application.
+However, any calls to `#lock` or `#unlock` will always be persisted to all
+backends so that locks are maintained during failover.
 
-- `cache_expires_in`: 86400 (1 day). This is sent to the cache backend and
-  defines how long the cache entry should be stored. After this time elapses,
-  queries will result in a cache miss.
-- `cache_refreshes_after`: 900 (15 minutes). This is used internally by Faulty
-  to indicate when a cache should be refreshed. It does not affect how long the
-  cache entry is stored.
-- `cache_refresh_jitter`: 180 (3 minutes = 20% of `cache_refreshes_after`). The
-  maximum number of seconds to randomly add or subtract from
-  `cache_refreshes_after` when determining whether to refresh a cache entry.
-  This mitigates the "thundering herd" effect caused by many processes
-  simultaneously refreshing the cache.
+#### Storage::FaultTolerantProxy
 
-This code will attempt to fetch an RSS feed protected by a circuit. If the feed
-is within the cache refresh period, then the result will be returned from the
-cache and the block will not be executed regardless of the circuit state.
+This wrapper is applied to all non-fault-tolerant storage backends by default
+(see the [API docs for `Faulty::Storage::AutoWire`](https://www.rubydoc.info/gems/faulty/Faulty/Storage/AutoWire)).
 
-If the cache is hit, but outside its refresh period, then Faulty will check the
-circuit state. If the circuit is closed or half-open, then it will run the
-block. If the block is successful, then it will update the circuit, write to the
-cache and return the new value.
+[`Faulty::Storage::FaultTolerantProxy`](https://www.rubydoc.info/gems/faulty/Faulty/Storage/FaultTolerantProxy)
+is a wrapper that suppresses storage errors and returns sensible defaults during
+failures. If a storage backend is failing, all circuits will be treated as
+closed regardless of locks or previous history.
 
-However, if the cache is hit and the block fails, then that failure is noted
-in the circuit and Faulty returns the cached value.
+If you wish your application to use a secondary storage backend instead of
+failing closed, use [`FallbackChain`](#storagefallbackchain).
 
-If the circuit is open and the cache is hit, then Faulty will always return the
-cached value.
+#### Storage::CircuitProxy
 
-If the cache query results in a miss, then faulty operates as normal. In the
-code above, if the circuit is closed, the block will be executed. If the block
-succeeds, the cache is refreshed. If the block fails, the default of `[]` will
-be returned.
+This wrapper is applied to all non-fault-tolerant storage backends by default
+(see the [API docs for `Faulty::Storage::AutoWire`](https://www.rubydoc.info/gems/faulty/Faulty/Cache/AutoWire)).
 
-## Fault Tolerance
+[`Faulty::Storage::CircuitProxy`](https://www.rubydoc.info/gems/faulty/Faulty/Storage/CircuitProxy)
+is a wrapper that uses an independent in-memory circuit to track failures to
+storage backends. If a storage backend fails continuously, it will be
+temporarily disabled and raise `Faulty::CircuitError`s.
 
-Faulty backends are fault-tolerant by default. Any `StandardError`s raised by
-the storage or cache backends are captured and suppressed. Failure events for
-these errors are sent to the notifier.
+Typically this is used inside a [`FaultTolerantProxy`](#storagefaulttolerantproxy) or
+[`FallbackChain`](#storagefallbackchain) so that these storage failures are handled
+gracefully.
 
-In case of a flaky storage or cache backend, Faulty also uses independent
-in-memory circuits to track failures so that we don't keep calling a backend
-that is failing. See the API docs for `Cache::AutoWire`, and `Storage::AutoWire`
-for more details.
+### Configuring the Cache Backend
 
-If the storage backend fails, circuits will default to closed. If the cache
-backend fails, all cache queries will miss.
+#### Null
 
-## Event Handling
+The [`Faulty::Cache::Null`](https://www.rubydoc.info/gems/faulty/Faulty/Cache/Null)
+cache disables caching. It is the default if Rails and ActiveSupport are not
+present.
 
-Faulty uses an event-dispatching model to deliver notifications of internal
-events. The full list of events is available from `Faulty::Events::EVENTS`.
+#### Rails
 
-- `cache_failure` -  A cache backend raised an error. Payload: `key`, `action`, `error`
-- `circuit_cache_hit` -  A circuit hit the cache. Payload: `circuit`, `key`
-- `circuit_cache_miss` -  A circuit hit the cache. Payload: `circuit`, `key`
-- `circuit_cache_write` - A circuit wrote to the cache. Payload: `circuit`, `key`
-- `circuit_closed` - A circuit closed. Payload: `circuit`
-- `circuit_failure` - A circuit execution raised an error. Payload: `circuit`,
-  `status`, `error`
-- `circuit_opened` - A circuit execution caused the circuit to open. Payload
-  `circuit`, `error`
-- `circuit_reopened` - A circuit execution cause the circuit to reopen from
-  half-open. Payload: `circuit`, `error`.
-- `circuit_skipped` - A circuit execution was skipped because the circuit is
-  closed. Payload: `circuit`
-- `circuit_success` - A circuit execution was successful. Payload: `circuit`,
-  `status`
-- `storage_failure` - A storage backend raised an error. Payload `circuit` (can
-  be nil), `action`, `error`
+[`Faulty::Cache::Rails`](https://www.rubydoc.info/gems/faulty/Faulty/Cache/Rails)
+is the default cache if Rails or ActiveSupport are present. If Rails is present,
+it uses `Rails.cache` as the backend. If ActiveSupport is present, but Rails is
+not, it creates a new `ActiveSupport::Cache::MemoryStore` by default.  This
+backend can be used with any `ActiveSupport::Cache`.
 
-By default events are logged using `Faulty::Events::LogListener`, but that can
-be replaced, or additional listeners can be added.
+```ruby
+Faulty.init do |config|
+  config.cache = Faulty::Cache::Rails.new(
+    ActiveSupport::Cache::RedisCacheStore.new
+  )
+end
+```
 
-### CallbackListener
+#### Cache::FaultTolerantProxy
+
+This wrapper is applied to all non-fault-tolerant cache backends by default
+(see the API docs for `Faulty::Cache::AutoWire`).
 
-The callback listener is useful for ad-hoc handling of events. You can specify
-an event handler by calling a method on the callback handler by the same name.
+[`Faulty::Cache::FaultTolerantProxy`](https://www.rubydoc.info/gems/faulty/Faulty/Cache/FaultTolerantProxy)
+is a wrapper that suppresses cache errors and acts like a null cache during
+failures. Reads always return `nil`, and writes are no-ops.
+
+#### Cache::CircuitProxy
+
+This wrapper is applied to all non-fault-tolerant circuit backends by default
+(see the API docs for `Faulty::Circuit::AutoWire`).
+
+[`Faulty::Cache::CircuitProxy`](https://www.rubydoc.info/gems/faulty/Faulty/Cache/CircuitProxy)
+is a wrapper that uses an independent in-memory circuit to track failures to
+cache backends. If a cache backend fails continuously, it will be
+temporarily disabled and raise `Faulty::CircuitError`s.
+
+Typically this is used inside a
+[`FaultTolerantProxy`](#cachefaulttolerantproxy) so that these cache failures
+are handled gracefully.
+
+### Multiple Configurations
+
+It is possible to have multiple configurations of Faulty running within the same
+process. The most common setup is to simply use `Faulty.init` to
+configure Faulty globally, however it is possible to have additional
+configurations.
+
+#### The default instance
+
+When you call [`Faulty.init`](https://www.rubydoc.info/gems/faulty/Faulty.init),
+you are actually creating the default instance of `Faulty`. You can access this
+instance directly by calling
+[`Faulty.default`](https://www.rubydoc.info/gems/faulty/Faulty.default).
 
 ```ruby
-Faulty.init do |config|
-  # Replace the default listener with a custom callback listener
-  listener = Faulty::Events::CallbackListener.new do |events|
-    events.circuit_opened do |payload|
-      MyNotifier.alert("Circuit #{payload[:circuit].name} opened: #{payload[:error].message}")
-    end
-  end
-  config.listeners = [listener]
-end
+# We create the default instance
+Faulty.init
+
+# Access the default instance
+faulty = Faulty.default
+
+# Alternatively, access the instance by name
+faulty = Faulty[:default]
 ```
 
-### Other Built-in Listeners
+You can rename the default instance if desired:
 
-In addition to the log and callback listeners, Faulty intends to implement
-built-in service-specific handlers to make it easy to integrate with monitoring
-and reporting software.
+```ruby
+Faulty.init(:custom_default)
 
-- `Faulty::Events::HoneybadgerListener`: Reports circuit and backend errors to
-  the Honeybadger error reporting service.
+instance = Faulty.default
+instance = Faulty[:custom_default]
+```
 
-### Custom Listeners
+#### Multiple Instances
 
-You can implement your own listener by following the documentation in
-`Faulty::Events::ListenerInterface`. For example:
+If you want multiple instance, but want global, thread-safe access to
+them, you can use
+[`Faulty.register`](https://www.rubydoc.info/gems/faulty/Faulty.register):
 
 ```ruby
-class MyFaultyListener
-  def handle(event, payload)
-    MyNotifier.alert(event, payload)
-  end
+api_faulty = Faulty.new do |config|
+  # This accepts the same options as Faulty.init
 end
+
+Faulty.register(:api, api_faulty)
+
+# Now access the instance globally
+Faulty[:api]
 ```
 
+When you call [`Faulty.circuit`](https://www.rubydoc.info/gems/faulty/Faulty.circuit),
+that's the same as calling `Faulty.default.circuit`, so you can apply the same
+principal to any other registered Faulty instance:
+
 ```ruby
-Faulty.init do |config|
-  config.listeners = [MyFaultyListener.new]
-end
+Faulty[:api].circuit('api_circuit').run { 'ok' }
 ```
 
-## Configuring the Storage Backend
+#### Standalone Instances
 
-A storage backend is required to use Faulty. By default, it uses in-memory
-storage, but Redis is also available, along with a number of wrappers used to
-improve resiliency and fault-tolerance.
+If you choose, you can use Faulty instances without registering them globally by
+simply calling [`Faulty.new`](https://www.rubydoc.info/gems/faulty/Faulty:initialize).
+This is more object-oriented and is necessary if you use dependency injection.
 
-### Memory
+```ruby
+faulty = Faulty.new
+faulty.circuit('standalone_circuit')
+```
 
-The `Faulty::Storage::Memory` backend is the default storage backend. You may
-prefer this implementation if you want to avoid the complexity and potential
-failure-mode of cross-network circuit storage. The trade-off is that circuit
-state is only contained within a single process and will not be saved across
-application restarts. Locks will also be cleared on restart.
+Calling `#circuit` on the instance still has the same memoization behavior that
+`Faulty.circuit` has, so subsequent calls to the same circuit will return a
+memoized circuit object.
 
-The default configuration:
+
+## Working with circuits
+
+A circuit can be created by calling the `#circuit` method on `Faulty`, or on
+your Faulty instance:
 
 ```ruby
-Faulty.init do |config|
-  config.storage = Faulty::Storage::Memory.new do |storage|
-    # The maximum number of circuit runs that will be stored
-    storage.max_sample_size = 100
+# With global Faulty configuration
+circuit = Faulty.circuit('api')
+
+# Or with a Faulty instance
+circuit = faulty.circuit('api')
+```
+
+### Running a Circuit
+
+You can handle circuit errors either with exceptions, or with a Faulty
+[`Result`](https://www.rubydoc.info/gems/faulty/Faulty/Result). They both have
+the same behavior, but you can choose whatever syntax is more convenient for
+your use-case.
+
+#### With Exceptions
+
+If we want exceptions to be raised, we use the
+[`#run`](https://www.rubydoc.info/gems/faulty/Faulty/Circuit:run) method. This
+does not suppress exceptions, only monitors them. If `api.users` raises an
+exception here, it will bubble up to the caller. The exception will be a
+sub-class of [`Faulty::CircuitError`](https://www.rubydoc.info/gems/faulty/Faulty/CircuitError),
+and the error `cause` will be the original error object.
+
+```ruby
+begin
+  Faulty.circuit('api').run do
+    api.users
   end
+rescue Faulty::CircuitError => e
+  e.cause # The original error
 end
 ```
 
-### Redis
+#### With Faulty::Result
 
-The `Faulty::Storage::Redis` backend provides distributed circuit storage using
-Redis. Although Faulty takes steps to reduce risk
-(See [Fault Tolerance](#fault-tolerance)), using cross-network storage does
-introduce some additional failure modes. To reduce this risk, be sure to set
-conservative timeouts for your Redis connection. Setting high timeouts will
-print warnings to stderr.
+Sometimes exception handling is awkward to deal with, and could cause a lot of
+extra boilerplate code. In simple cases, it's can be more concise to allow
+Faulty to capture exceptions. Use the
+[`#try_run`](https://www.rubydoc.info/gems/faulty/Faulty/Circuit:try_run) method
+for this.
 
-The default configuration:
+```ruby
+  result = Faulty.circuit('api').try_run do
+    api.users
+  end
+```
+
+The `result` variable is an instance of
+[`Faulty::Result`](https://www.rubydoc.info/gems/faulty/Faulty/Result). A result
+can either be an error if the circuit failed, or an "ok" value if it succeeded.
+
+You can check whether it's an error with the `ok?` or `error?` method.
 
 ```ruby
-Faulty.init do |config|
-  config.storage = Faulty::Storage::Redis.new do |storage|
-    # The Redis client. Accepts either a Redis instance, or a ConnectionPool
-    # of Redis instances. A low timeout is highly recommended to prevent
-    # cascading failures when evaluating circuits.
-    storage.client = ::Redis.new(timeout: 1)
+if result.ok?
+  users = result.get
+else
+  error = result.error
+end
+```
 
-    # The prefix to prepend to all redis keys used by Faulty circuits
-    storage.key_prefix = 'faulty'
+Sometimes you want your application to crash when a circuit fails, but other
+times, you might want to return a default or fallback value. The `Result` object
+has a method [`#or_default`](https://www.rubydoc.info/gems/faulty/Faulty/Result:or_default)
+to do that.
 
-    # A string to separate the parts of the redis key
-    storage.key_separator = ':'
+```ruby
+# Users will be nil if the result is an error
+users = result.or_default
 
-    # The maximum number of circuit runs that will be stored
-    storage.max_sample_size = 100
+# Users will be an empty array if the result is an error
+users = result.or_default([])
 
-    # The maximum number of seconds that a circuit run will be stored
-    storage.sample_ttl = 1800
+# Users will be the return value of the block
+users = result.or_default do
+  # ...
+end
+```
 
-    # The maximum number of seconds to store a circuit. Does not apply to
-    # locks, which are indefinite.
-    storage.circuit_ttl = 604_800 # 1 Week
+As we showed in the [Basic Usage](#basic-usage) section, you can put this
+together in a nice one-liner.
 
-    # The number of seconds between circuit expirations. Changing this setting
-    # is not recommended. See API docs for more implementation details.
-    storage.list_granularity = 3600
+```ruby
+Faulty.circuit('api').try_run { api.users }.or_default([])
+```
 
-    # If true, disables warnings about recommended client settings like timeouts
-    storage.disable_warnings = false
-  end
+### Specifying the Captured Errors
+
+By default, Faulty circuits will capture all `StandardError` errors, but
+sometimes you might not want every error to count as a circuit failure. For
+example, an HTTP 404 Not Found response typically should not cause a circuit to
+fail. You can customize the errors that Faulty captures
+
+```ruby
+Faulty.circuit('api', errors: [Net::HTTPServerException]).run do
+  # If this raises any exception other than Net::HTTPServerException
+  # Faulty will not capture it at all, and it will not count as a circuit failure
+  api.find_user(3)
 end
 ```
 
-### FallbackChain
+Or, if you'd instead like to specify errors to be excluded:
 
-The `Faulty::Storage::FallbackChain` backend is a wrapper for multiple
-prioritized storage backends. If the first backend in the chain fails,
-consecutive backends are tried until one succeeds. The recommended use-case for
-this is to fall back on reliable storage if a networked storage backend fails.
+```ruby
+Faulty.circuit('api', exclude: [Net::HTTPClientException]).run do
+  # If this raises a Net::HTTPClientException, Faulty will not capture it
+  api.find_user(3)
+end
+```
 
-For example, you may configure Redis as your primary storage backend, with an
-in-memory storage backend as a fallback:
+Both options can even be specified together.
 
 ```ruby
-Faulty.init do |config|
-  config.storage = Faulty::Storage::FallbackChain.new([
-    Faulty::Storage::Redis.new,
-    Faulty::Storage::Memory.new
-  ])
+Faulty.circuit(
+  'api',
+  errors: [ActiveRecord::ActiveRecordError]
+  exclude: [ActiveRecord::RecordNotFound, ActiveRecord::RecordNotUnique]
+).run do
+  # This only captures ActiveRecord::ActiveRecordError errors, but not
+  # ActiveRecord::RecordNotFound or ActiveRecord::RecordNotUnique errors
+  user = User.find(3)
+  user.save!
 end
 ```
 
-Faulty instances will automatically use a fallback chain if an array is given to
-the `storage` option, so this example is equivalent to the above:
+### Using the Cache
+
+Circuit runs can be given a cache key, and if they are, the result of the circuit
+block will be cached. Calls to that circuit block will try to fetch from the
+cache, and only execute the block if the cache misses.
 
 ```ruby
-Faulty.init do |config|
-  config.storage = [
-    Faulty::Storage::Redis.new,
-    Faulty::Storage::Memory.new
-  ]
+Faulty.circuit('api').run(cache: 'all_users') do
+  api.users
 end
 ```
 
-If the fallback chain fails-over to backup storage, circuit states will not
-carry over, so failover could be temporarily disruptive to your application.
-However, any calls to `#lock` or `#unlock` will always be persisted to all
-backends so that locks are maintained during failover.
+The cache will be refreshed (meaning the circuit will be allowed to execute)
+after `cache_refreshes_after` (default 900 second). However, the value remains
+stored in the cache for `cache_expires_in` (default 86400 seconds, 1 day). If
+the circuit fails, the last cached value will be returned even if
+`cache_refreshes_after` has passed.
 
-### Storage::FaultTolerantProxy
+See the [Caching](#caching) section for more details on Faulty's caching
+strategy.
 
-This wrapper is applied to all non-fault-tolerant storage backends by default
-(see the [API docs for `Faulty::Storage::AutoWire`](https://www.rubydoc.info/gems/faulty/Faulty/Storage/AutoWire)).
+### Configuring the Circuit Threshold
 
-`Faulty::Storage::FaultTolerantProxy` is a wrapper that suppresses storage
-errors and returns sensible defaults during failures. If a storage backend is
-failing, all circuits will be treated as closed regardless of locks or previous
-history.
+To configure how a circuit responds to error, use the `cool_down`,
+`rate_threshold` and `sample_threshold` options.
 
-If you wish your application to use a secondary storage backend instead of
-failing closed, use `FallbackChain`.
+#### Rate Threshold
 
-### Storage::CircuitProxy
+The first option to look at is `rate_threshold`. This specifies the percentage
+of circuit runs that must fail before a circuit is opened.
 
-This wrapper is applied to all non-fault-tolerant storage backends by default
-(see the [API docs for `Faulty::Storage::AutoWire`](https://www.rubydoc.info/gems/faulty/Faulty/Cache/AutoWire)).
+```ruby
+# This circuit must fail 70% of the time before the circuit will be tripped
+Faulty.circuit('api', rate_threshold: 0.7).run { api.users }
+```
 
-`Faulty::Storage::CircuitProxy` is a wrapper that uses an independent in-memory
-circuit to track failures to storage backends. If a storage backend fails
-continuously, it will be temporarily disabled and raise `Faulty::CircuitError`s.
+#### Sample Threshold
 
-Typically this is used inside a `FaultTolerantProxy` or `FallbackChain` so that
-these storage failures are handled gracefully.
+We typically don't want circuits to trip immediately if the first execution
+fails. This is why we have the `sample_threshold` option. The circuit will never
+be tripped until we record at least this number of executions.
 
-## Configuring the Cache Backend
+```ruby
+# This circuit must run 10 times before it is allowed to trip. Those 10 runs
+# can be successes or fails. If at least 70% of them are failures, the circuit
+# will be opened.
+Faulty.circuit('api', sample_threshold: 10, rate_threshold: 0.7).run { api.users }
+```
+
+#### Cool Down
 
-### Null
+The `cool_down` option specifies how much time to wait after a circuit is
+opened. During this period, the circuit will not be executed. After the cool
+down elapses, the circuit enters the "half open" state, and execution can be
+retried. See [How it Works](#how-it-works).
 
-The `Faulty::Cache::Null` cache disables caching. It is the default if Rails and
-ActiveSupport are not present.
+```ruby
+# If this circuit trips, it will skip executions for 120 seconds before retrying
+Faulty.circuit('api', cool_down: 120).run { api.users }
+```
 
-### Rails
+### Circuit Options
 
-`Faulty::Cache::Rails` is the default cache if Rails or ActiveSupport are
-present. If Rails is present, it uses `Rails.cache` as the backend. If
-ActiveSupport is present, but Rails is not, it creates a new
-`ActiveSupport::Cache::MemoryStore` by default.  This backend can be used with
-any `ActiveSupport::Cache`.
+A circuit can be created with the following configuration options. Those options
+are only set once, synchronized across threads, and will persist in-memory until
+the process exits. If you're using [multiple configurations](#multiple-configurations),
+the options are retained within the context of each instance. All options given
+after the first call to `Faulty.circuit` (or `Faulty#circuit`) are ignored.
 
 ```ruby
-Faulty.init do |config|
-  config.cache = Faulty::Cache::Rails.new(
-    ActiveSupport::Cache::RedisCacheStore.new
-  )
-end
+Faulty.circuit('api', rate_threshold: 0.7)
+
+# These options are ignored since with already initialized the circuit
+circuit = Faulty.circuit('api', rate_threshold: 0.3)
+circuit.options.rate_threshold # => 0.7
 ```
 
-### Cache::FaultTolerantProxy
+This is because the circuit objects themselves are internally memoized, and are
+read-only once created.
 
-This wrapper is applied to all non-fault-tolerant cache backends by default
-(see the API docs for `Faulty::Cache::AutoWire`).
+The following example represents the defaults for a new circuit:
 
-`Faulty::Cache::FaultTolerantProxy` is a wrapper that suppresses cache errors
-and acts like a null cache during failures. Reads always return `nil`, and
-writes are no-ops.
+```ruby
+Faulty.circuit('api') do |config|
+  # The cache backend for this circuit. Inherits the global cache by default.
+  config.cache = Faulty.options.cache
 
-### Cache::CircuitProxy
+  # The number of seconds before a cache entry is expired. After this time, the
+  # cache entry may be fully deleted. If set to nil, the cache will not expire.
+  config.cache_expires_in = 86400
 
-This wrapper is applied to all non-fault-tolerant circuit backends by default
-(see the API docs for `Faulty::Circuit::AutoWire`).
+  # The number of seconds before a cache entry should be refreshed. See the
+  # Caching section for more detail. A value of nil disables cache refreshing.
+  config.cache_refreshes_after = 900
 
-`Faulty::Circuit::CircuitProxy` is a wrapper that uses an independent in-memory
-circuit to track failures to circuit backends. If a circuit backend fails
-continuously, it will be temporarily disabled and raise `Faulty::CircuitError`s.
+  # The number of seconds to add or subtract from cache_refreshes_after
+  # when determining whether a cache entry should be refreshed. Helps mitigate
+  # the "thundering herd" effect
+  config.cache_refresh_jitter = 0.2 * config.cache_refreshes_after
 
-Typically this is used inside a `FaultTolerantProxy` so that these cache
-failures are handled gracefully.
+  # After a circuit is opened, the number of seconds to wait before moving the
+  # circuit to half-open.
+  config.cool_down = 300
 
-## Listing Circuits
+  # The number of seconds of history that is considered when calculating
+  # the circuit failure rate. The length of the sliding window.
+  config.evaluation_window = 60
+
+  # The errors that will be captured by Faulty and used to trigger circuit
+  # state changes.
+  config.errors = [StandardError]
+
+  # Errors that should be ignored by Faulty and not captured.
+  config.exclude = []
+
+  # The event notifier. Inherits the Faulty instance notifier by default
+  config.notifier = Faulty.options.notifier
+
+  # The minimum failure rate required to trip a circuit
+  config.rate_threshold = 0.5
+
+  # The minimum number of runs required before a circuit can trip
+  config.sample_threshold = 3
+
+  # The storage backend for this circuit. Inherits the Faulty instance storage
+  # by default
+  config.storage = Faulty.options.storage
+end
+```
+
+Following the same convention as `Faulty.init`, circuits can also be created
+with an options hash:
+
+```ruby
+Faulty.circuit(:api, cache_expires_in: 1800)
+```
+
+### Listing Circuits
 
 For monitoring or debugging, you may need to retrieve a list of all circuit
-names. This is possible with `Faulty.list_circuits` (or `Faulty#list_circuits`
+names. This is possible with [`Faulty.list_circuits`](https://www.rubydoc.info/gems/faulty/Faulty.list_circuits)
+(or [`Faulty#list_circuits`](https://www.rubydoc.info/gems/faulty/Faulty:list_circuits)
 if you're using an instance).
 
 You can get a list of all circuit statuses by mapping those names to their
@@ -659,7 +881,7 @@ statuses = Faulty.list_circuits.map do |name|
 end
 ```
 
-## Locking Circuits
+### Locking Circuits
 
 It is possible to lock a circuit open or closed. A circuit that is locked open
 will never execute its block, and always raise an `Faulty::OpenCircuitError`.
@@ -667,8 +889,12 @@ This is useful in cases where you need to manually disable a dependency
 entirely. If a cached value is available, that will be returned from the circuit
 until it expires, even outside its refresh period.
 
+* [`lock_open!`](https://www.rubydoc.info/gems/faulty/Faulty/Circuit:lock_open!)
+* [`lock_closed!`](https://www.rubydoc.info/gems/faulty/Faulty/Circuit:lock_closed!)
+* [`unlock!`](https://www.rubydoc.info/gems/faulty/Faulty/Circuit:unlock!)
+
 ```ruby
-Faulty.circuit(:broken_api).lock_open!
+Faulty.circuit('broken_api').lock_open!
 ```
 
 A circuit that is locked closed will never trip. This is useful in cases where a
@@ -676,94 +902,205 @@ circuit is continuously tripping incorrectly. If a cached value is available, it
 will have the same behavior as an unlocked circuit.
 
 ```ruby
-Faulty.circuit(:false_positive).lock_closed!
+Faulty.circuit('false_positive').lock_closed!
 ```
 
 To remove a lock of either type:
 
 ```ruby
-Faulty.circuit(:fixed).unlock!
+Faulty.circuit('fixed').unlock!
 ```
 
 Locking or unlocking a circuit has no concurrency guarantees, so it's not
 recommended to lock or unlock circuits from production code. Instead, locks are
 intended as an emergency tool for troubleshooting and debugging.
 
-## Multiple Configurations
+## Event Handling
 
-It is possible to have multiple configurations of Faulty running within the same
-process. The most common setup is to simply use `Faulty.init` to
-configure Faulty globally, however it is possible to have additional
-configurations.
+Faulty uses an event-dispatching model to deliver notifications of internal
+events. The full list of events is available from
+[`Faulty::Events::EVENTS`](https://www.rubydoc.info/gems/faulty/Faulty/Events).
 
-### The default instance
+- `cache_failure` -  A cache backend raised an error. Payload: `key`, `action`, `error`
+- `circuit_cache_hit` -  A circuit hit the cache. Payload: `circuit`, `key`
+- `circuit_cache_miss` -  A circuit hit the cache. Payload: `circuit`, `key`
+- `circuit_cache_write` - A circuit wrote to the cache. Payload: `circuit`, `key`
+- `circuit_closed` - A circuit closed. Payload: `circuit`
+- `circuit_failure` - A circuit execution raised an error. Payload: `circuit`,
+  `status`, `error`
+- `circuit_opened` - A circuit execution caused the circuit to open. Payload
+  `circuit`, `error`
+- `circuit_reopened` - A circuit execution cause the circuit to reopen from
+  half-open. Payload: `circuit`, `error`.
+- `circuit_skipped` - A circuit execution was skipped because the circuit is
+  closed. Payload: `circuit`
+- `circuit_success` - A circuit execution was successful. Payload: `circuit`,
+  `status`
+- `storage_failure` - A storage backend raised an error. Payload `circuit` (can
+  be nil), `action`, `error`
 
-When you call `Faulty.init`, you are actually creating the default instance of
-`Faulty`. You can access this instance directly by calling `Faulty.default`.
+By default events are logged using `Faulty::Events::LogListener`, but that can
+be replaced, or additional listeners can be added.
 
-```ruby
-# We create the default instance
-Faulty.init
+### CallbackListener
 
-# Access the default instance
-faulty = Faulty.default
+The [`CallbackListener`](https://www.rubydoc.info/gems/faulty/Faulty/Events/CallbackListener)
+is useful for ad-hoc handling of events. You can specify an event handler by
+calling a method on the callback handler by the same name.
 
-# Alternatively, access the instance by name
-faulty = Faulty[:default]
+```ruby
+Faulty.init do |config|
+  # Replace the default listener with a custom callback listener
+  listener = Faulty::Events::CallbackListener.new do |events|
+    events.circuit_opened do |payload|
+      MyNotifier.alert("Circuit #{payload[:circuit].name} opened: #{payload[:error].message}")
+    end
+  end
+  config.listeners = [listener]
+end
 ```
 
-You can rename the default instance if desired:
+### Other Built-in Listeners
 
-```ruby
-Faulty.init(:custom_default)
+In addition to the log and callback listeners, Faulty intends to implement
+built-in service-specific handlers to make it easy to integrate with monitoring
+and reporting software.
 
-instance = Faulty.default
-instance = Faulty[:custom_default]
-```
+* [`Faulty::Events::LogListener`](https://www.rubydoc.info/gems/faulty/Faulty/Events/LogListener):
+  Logs all circuit events to a specified `Logger` or `$stderr` by default. This
+  is enabled by default if no listeners are specified.
+* [`Faulty::Events::HoneybadgerListener`](https://www.rubydoc.info/gems/faulty/Faulty/Events/HoneybadgerListener):
+  Reports circuit and backend errors to the Honeybadger error reporting service.
 
-### Multiple Instances
+If your favorite monitoring software is not supported here, please open a PR
+that implements a listener for it.
 
-If you want multiple instance, but want global, thread-safe access to
-them, you can use `Faulty.register`:
+### Custom Listeners
+
+You can implement your own listener by following the documentation in
+[`Faulty::Events::ListenerInterface`](https://www.rubydoc.info/gems/faulty/Faulty/Events/ListenerInterface).
+For example:
 
 ```ruby
-api_faulty = Faulty.new do |config|
-  # This accepts the same options as Faulty.init
+class MyFaultyListener
+  def handle(event, payload)
+    MyNotifier.alert(event, payload)
+  end
 end
-
-Faulty.register(:api, api_faulty)
-
-# Now access the instance globally
-Faulty[:api]
 ```
 
-When you call `Faulty.circuit`, that's the same as calling
-`Faulty.default.circuit`, so you can apply the same principal to any other
-registered Faulty instance:
-
 ```ruby
-Faulty[:api].circuit(:api_circuit).run { 'ok' }
+Faulty.init do |config|
+  config.listeners = [MyFaultyListener.new]
+end
 ```
 
-### Standalone Instances
+## How it Works
 
-If you choose, you can use Faulty instances without registering them globally.
-This is more object-oriented and is necessary if you use dependency injection.
+Faulty implements a version of circuit breakers inspired by "Release It!: Design
+and Deploy Production-Ready Software" by [Michael T. Nygard][michael nygard] and
+[Martin Fowler's post][martin fowler] on the subject. A few notable features of
+Faulty's implementation are:
+
+- Rate-based failure thresholds
+- Integrated caching inspired by Netflix's [Hystrix][hystrix] with automatic
+  cache jitter and error fallback.
+- Event-based monitoring
+- Flexible fault-tolerant storage with optional fallbacks
+
+Following the principals of the circuit-breaker pattern, the block given to
+`run` or `try_run` will always be executed as long as it never raises an error.
+If the block _does_ raise an error, then the circuit keeps track of the number
+of runs and the failure rate.
+
+Once both thresholds are breached, the circuit is opened. Once open, the
+circuit starts the cool-down period. Any executions within that cool-down are
+skipped, and a `Faulty::OpenCircuitError` will be raised.
+
+After the cool-down has elapsed, the circuit enters the half-open state. In this
+state, Faulty allows a single execution of the block as a test run. If the test
+run succeeds, the circuit is fully closed and the circuit state is reset. If the
+test run fails, the circuit is opened and the cool-down is reset.
+
+Each time the circuit changes state or executes the block, events are raised
+that are sent to the Faulty event notifier. The notifier should be used to track
+circuit failure rates, open circuits, etc.
+
+In addition to the classic circuit breaker design, Faulty implements caching
+that is integrated with the circuit state. See [Caching](#caching) for more
+detail.
+
+### Caching
+
+Faulty integrates caching into it's circuits in a way that is particularly
+suited to fault-tolerance. To make use of caching, you must specify the `cache`
+configuration option when initializing Faulty or creating a new Faulty instance.
+If you're using Rails, this is automatically set to the Rails cache.
+
+Once your cache is configured, you can use the `cache` parameter when running
+a circuit to specify a cache key:
 
 ```ruby
-faulty = Faulty.new
-faulty.circuit(:standalone_circuit)
+feed = Faulty.circuit('rss_feeds')
+  .try_run(cache: "rss_feeds/#{feed}") do
+    fetch_feed(feed)
+  end.or_default([])
 ```
 
-Calling `#circuit` on the instance still has the same memoization behavior that
-`Faulty.circuit` has, so subsequent calls to the same circuit will return a
-memoized circuit object.
+By default a circuit has the following options:
+
+- `cache_expires_in`: 86400 (1 day). This is sent to the cache backend and
+  defines how long the cache entry should be stored. After this time elapses,
+  queries will result in a cache miss.
+- `cache_refreshes_after`: 900 (15 minutes). This is used internally by Faulty
+  to indicate when a cache should be refreshed. It does not affect how long the
+  cache entry is stored.
+- `cache_refresh_jitter`: 180 (3 minutes = 20% of `cache_refreshes_after`). The
+  maximum number of seconds to randomly add or subtract from
+  `cache_refreshes_after` when determining whether to refresh a cache entry.
+  This mitigates the "thundering herd" effect caused by many processes
+  simultaneously refreshing the cache.
+
+This code will attempt to fetch an RSS feed protected by a circuit. If the feed
+is within the cache refresh period, then the result will be returned from the
+cache and the block will not be executed regardless of the circuit state.
+
+If the cache is hit, but outside its refresh period, then Faulty will check the
+circuit state. If the circuit is closed or half-open, then it will run the
+block. If the block is successful, then it will update the circuit, write to the
+cache and return the new value.
+
+However, if the cache is hit and the block fails, then that failure is noted
+in the circuit and Faulty returns the cached value.
+
+If the circuit is open and the cache is hit, then Faulty will always return the
+cached value.
+
+If the cache query results in a miss, then faulty operates as normal. In the
+code above, if the circuit is closed, the block will be executed. If the block
+succeeds, the cache is refreshed. If the block fails, the default of `[]` will
+be returned.
+
+### Fault Tolerance
+
+Faulty backends are fault-tolerant by default. Any `StandardError`s raised by
+the storage or cache backends are captured and suppressed. Failure events for
+these errors are sent to the notifier.
+
+In case of a flaky storage or cache backend, Faulty also uses independent
+in-memory circuits to track failures so that we don't keep calling a backend
+that is failing. See the API docs for [`Cache::AutoWire`](https://www.rubydoc.info/gems/faulty/Faulty/Cache/AutoWire),
+and [`Storage::AutoWire`](https://www.rubydoc.info/gems/faulty/Faulty/Storage/AutoWire)
+for more details.
+
+If the storage backend fails, circuits will default to closed. If the cache
+backend fails, all cache queries will miss.
 
 ## Implementing a Cache Backend
 
 You can implement your own cache backend by following the documentation in
-`Faulty::Cache::Interface`. It is a fairly simple API, with only get/set
-methods. For example:
+[`Faulty::Cache::Interface`](https://www.rubydoc.info/gems/faulty/Faulty/Cache/Interface).
+It is a fairly simple API, with only get/set methods. For example:
 
 ```ruby
 class MyFaultyCache
@@ -792,10 +1129,11 @@ users.
 ## Implementing a Storage Backend
 
 You can implement your own storage backend by following the documentation in
-`Faulty::Storage::Interface`. Since the storage has some tricky requirements
-regarding concurrency, the `Faulty::Storage::Memory` can be used as a reference
-implementation. Feel free to open a pull request if your storage backend
-would be useful for other users.
+[`Faulty::Storage::Interface`](https://www.rubydoc.info/gems/faulty/Faulty/Storage/Interface).
+Since the storage has some tricky requirements regarding concurrency, the
+[`Faulty::Storage::Memory`](https://www.rubydoc.info/gems/faulty/Faulty/Storage/Memory)
+can be used as a reference implementation. Feel free to open a pull request if
+your storage backend would be useful for other users.
 
 ## Alternatives
 
@@ -806,7 +1144,7 @@ but there are and have been many other options:
 
 - [semian](https://github.com/Shopify/semian): A resiliency toolkit that
   includes circuit breakers. It uses adapters to auto-wire circuits, and it has
-  only host-local storage by design.
+  only in-memory storage by design.
 - [circuitbox](https://github.com/yammer/circuitbox): Similar in design to
   Faulty, but with a different API. It uses Moneta to abstract circuit storage
   to allow any key-value store.