-
Notifications
You must be signed in to change notification settings - Fork 59
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #196 from matthewshafer/2-0-upgrade
2.0 Upgrade guide
- Loading branch information
Showing
6 changed files
with
207 additions
and
58 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,59 @@ | ||
| # Circuitbox 2.0 Upgrade Guide | ||
|
|
||
| ## Requirements | ||
|
|
||
| Circuitbox 2.0 is tested against Ruby 2.6 through 3.2. | ||
| Since ruby 2.6 and 2.7 are EOL it's likely we'll drop support for those versions in future releases. | ||
|
|
||
| ## Changes | ||
|
|
||
| * The `timeout_seconds` option when initializing a circuit has been removed. | ||
| * Circuitbox does not wrap the block to run with Ruby's `Timeout` anymore. | ||
| * If you would like to use Ruby's `Timeout` you would need to do this yourself. | ||
| * A `CircuitBreaker`'s `run` method has been changed and the `run!` method has been removed. | ||
| * Calling `run` is now like calling `run!` in circuitbox 1.x. | ||
| * If you were using `run` in circuitbox 1.x you can call `run(exception: false)` to have the same behavior. | ||
| * The `logger` option when initializing a circuit has been removed. | ||
| * If you would like to use a logger you can either | ||
| * If using the `ActiveSupport` notifier subscribe to it's notifications to add your own logger | ||
| * Implement your own notifier using the same interface, see the `ActiveSupport` or `Null` notifier. | ||
| * The `exceptions` option when initializing a circuit must be an array. | ||
| * The `exceptions` option when initializing a circuit does not default to `[Timeout::Error]` when the array is empty. | ||
| * The `cache` option when initializing a circuit as been renamed to `circuit_store`. | ||
| * A circuits defaults sleep_window has changed from 300 seconds to 90 seconds. | ||
| * The `partition` option when running a circuit has been removed. | ||
| * attr_accessor's on `CircuitBreaker` have been changed to attr_reader, or in some cases removed. | ||
| * `partition` has been removed | ||
| * `logger` has been removed (see above about logger option) | ||
| * `time_class` has been added | ||
| * The class level `reset` method on `Circuitbox` has been removed. | ||
| * If you need to reset circuits before/after running a test you can reconfigure circuitbox | ||
| ```ruby | ||
| Circuitbox.configure do |config| | ||
| # Reset persisted state in the memory store so it doesn't leak between tests | ||
| # if using a store through moneta and want to reset it between tests you may need to do something else | ||
| config.default_circuit_store = Circuitbox::MemoryStore.new | ||
| end | ||
| ``` | ||
| * The class level `reset` method on `Circuitbox::CircuitBreaker` has been removed. | ||
| * This method would call `reset` on `Circuitbox`, see above about `Circuitbox.reset`. | ||
| * `Circuitbox.circuit` does not parse a host name out of a uri and use that as the circuit's service_name. | ||
| * If you rely on this functionality parse the host from the uri before calling `Circuitbox.circuit` | ||
| * Accessing/creating a circuit through `Circuitbox[:circuit_identifier]` has been removed. | ||
| * Circuitbox's notifications sent through `ActiveSupport::Notifications` have had their names changed. | ||
| * `circuit_open` changes to `open.circuitbox` | ||
| * `circuit_close` changes to `close.circuitbox` | ||
| * `circuit_success` changes to `success.circuitbox` | ||
| * `circuit_failure` changes to `failure.circuitbox` | ||
| * `circuit_skipped` changes to `skipped.circuitbox` | ||
| * `circuit_gauge` removed | ||
| * `circuit_warning` changes to `warning.circuitbox` | ||
| * add `run.circuitbox` to track runtime of the block the circuit is running | ||
| * Circuit's don't emit their error rate, success counts, failure counts through `ActiveSupport::Notifications` anymore. | ||
| * The methods `error_rate`, `success_count`, `failure_count` on a circuit instance can be used to obtain this information. | ||
| * During circuit initialization if `sleep_window` is less than `time_window` it is not set to `time_window`. | ||
| * Circuitbox warns about, and only checks this during circuit initialization | ||
| * Circuitbox's default circuit store has changed from `Moneta`'s memory store to `Circuitbox::MemoryStore`. | ||
| * `Circuitbox::MemoryStore` periodically removes expired keys from the store, allowing Ruby to reclaim memory | ||
| * When `Circuitbox::MemoryStore` is used a circuits time class is `Circuitbox::TimeHelper::Monotonic` | ||
| * If using `Moneta` as a circuit store, only adapters that support bulk read functionality are supported. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,80 @@ | ||
| # Circuit Notifications | ||
|
|
||
| Circuitbox supports sending notifications when various events occur. | ||
| The following events are sent to the notifier: | ||
|
|
||
| * Circuit block runs (this is where notifiers do timing) | ||
| * Circuit is skipped | ||
| * Circuit run is successful | ||
| * Circuit run is failed | ||
| * Circuit is opened | ||
| * Circuit is closed | ||
| * Circuit is not configured correctly | ||
|
|
||
| There are two types of notifiers built into circuitbox, null and active support. | ||
| The null notifier does not send notifications. | ||
| The active support notifier sends notifications through `ActiveSupport::Notifications`. | ||
|
|
||
| ## Active Support Notifications | ||
|
|
||
| There are three different types of notification payloads which are defined below | ||
|
|
||
| All notifications contain `:circuit` in the payload. | ||
| The value of `:circuit` is the name of the circuit. | ||
|
|
||
| The first type of notifications are: | ||
|
|
||
| * `open.circuitbox` - Sent when the circuit moves to the open state. | ||
| * `close.circuitbox` - Sent when the circuit moves to the closed state. | ||
| * `skipped.circuitbox` - Sent when the circuit is run and in the open state. | ||
| * `success.circuitbox` - Sent when the circuit is run and the run succeeds. | ||
| * `failure.circuitbox` - Sent when the circuit is run and the run fails. | ||
|
|
||
| The second type of notifications are contain a `:message` in the payload, in addition to `:circuit`. | ||
| The value of `:message` is a string. | ||
|
|
||
| * `warning.circuitbox` - Sent when there is a misconfiguration of the circuit. | ||
|
|
||
| The third type of notifications can be used for timing of the circuit. | ||
| The timing is done by `ActiveSupport::Notifications`. | ||
|
|
||
| * `run.circuitbox` - Sent after the circuit is run. | ||
|
|
||
| ### Examples | ||
|
|
||
| #### Open/Close/Skipped/Success/Failure | ||
|
|
||
| ```ruby | ||
| ActiveSupport::Notifications.subscribe('open.circuitbox') do |*args| | ||
| event = ActiveSupport::Notifications::Event.new(*args) | ||
| circuit_name = event.payload[:circuit] | ||
| Rails.logger.warn("Open circuit for: #{circuit_name}") | ||
| end | ||
|
|
||
| ActiveSupport::Notifications.subscribe('close.circuitbox') do |*args| | ||
| event = ActiveSupport::Notifications::Event.new(*args) | ||
| circuit_name = event.payload[:circuit] | ||
| Rails.logger.info("Close circuit for: #{circuit_name}") | ||
| end | ||
| ``` | ||
|
|
||
| #### Warning | ||
|
|
||
| ```ruby | ||
| ActiveSupport::Notifications.subscribe('warning.circuitbox') do |*args| | ||
| event = ActiveSupport::Notifications::Event.new(*args) | ||
| circuit_name = event.payload[:circuit] | ||
| warning = event.payload[:message] | ||
| Rails.logger.warning("Circuit warning for: #{circuit_name} Message: #{warning}") | ||
| end | ||
| ``` | ||
|
|
||
| #### Timing | ||
| ```ruby | ||
| ActiveSupport::Notifications.subscribe('run.circuitbox') do |*args| | ||
| event = ActiveSupport::Notifications::Event.new(*args) | ||
| circuit_name = event.payload[:circuit_name] | ||
|
|
||
| Rails.logger.info("Circuit: #{circuit_name} Runtime: #{event.duration}") | ||
| end | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters