View Source BreakerBox.BreakerConfiguration behaviour (BreakerBox v0.5.0)
Structure and behaviour for configuring circuit breakers.
Link to this section Summary
Callbacks
Retrieve the name and configuration map of a circuit breaker.
Functions
Get a friendlier representation of the breaker configuration.
Configure a breaker's reset window using milliseconds.
Configure a breaker's reset window using minutes.
Configure a breaker's reset window using seconds.
Converts our BreakerBox.BreakerConfiguration struct type to the format Fuse
expects.
Configure a breaker to trip on the Nth failure within the configured
failure_window.
Configure a breaker's failure window using milliseconds.
Configure a breaker's failure window using minutes.
Configure a breaker's failure window using seconds.
Link to this section Types
Specs
t() :: %BreakerBox.BreakerConfiguration{
failure_window: pos_integer(),
max_failures: pos_integer(),
reset_window: pos_integer()
}
Options for controlling circuit breaker behavior.
Defaults were chosen from external_service/fuse examples, and are open to change. By default, breakers will trip on the 5th failure within 1 second, resetting automatically after 5 seconds.
Defaults
| Field | Value |
| max_failures | 5 |
| failure_window | 1000 |
| reset_window | 5000 |
Link to this section Callbacks
Specs
Retrieve the name and configuration map of a circuit breaker.
Called by BreakerBox.start_link/1 on every module passed in from
Application.start.
Implementations should return a 2-tuple containing the name of the breaker
and the BreakerBox.BreakerConfiguration options for registering the
breaker.
This is only required and useful for breakers that should be automatically
registered at startup. You can still manually call BreakerBox.register/2 if
you don't need to make use of supervision.
_MODULE_ is a good default breaker name, but can be a string, atom, or anything you want. Re-using a breaker name in multiple places will overwrite with the last configuration.
@impl true
def registration do
breaker_config =
%BreakerBox.BreakerConfiguration{}
|> BreakerBox.BreakerConfiguration.trip_on_failure_number(10) # Trip after 10th failure
|> BreakerBox.BreakerConfiguration.within_seconds(1) # within 1 second
|> BreakerBox.BreakerConfiguration.reset_after_seconds(5) # Automatically reset breaker after 5s
{__MODULE__, breaker_config}
endLink to this section Functions
Specs
Get a friendlier representation of the breaker configuration.
Examples
iex> %BreakerBox.BreakerConfiguration{} |> BreakerBox.BreakerConfiguration.human_readable()
"Trip on 5th error within 1000ms, resetting after 5000ms."Specs
reset_after_milliseconds(config :: t(), reset_window :: pos_integer()) :: t()
Configure a breaker's reset window using milliseconds.
A tripped breaker that hasn't been manually disabled will automatically reset
to untripped after reset_window milliseconds.
If attempted to set with a non-positive-integer value, it will use the default value of 5000 milliseconds.
Specs
reset_after_minutes(config :: t(), reset_window :: pos_integer()) :: t()
Configure a breaker's reset window using minutes.
A tripped breaker that hasn't been manually disabled will automatically reset
to untripped after reset_window 60 seconds 1000 milliseconds.
If attempted to set with a non-positive-integer value, it will use the default value of 5000 milliseconds.
Specs
reset_after_seconds(config :: t(), reset_window :: pos_integer()) :: t()
Configure a breaker's reset window using seconds.
A tripped breaker that hasn't been manually disabled will automatically reset
to untripped after reset_window * 1000 milliseconds.
If attempted to set with a non-positive-integer value, it will use the default value of 5000 milliseconds.
Specs
to_fuse_options(config :: t()) :: {{:standard, pos_integer(), pos_integer()}, {:reset, pos_integer()}}
Converts our BreakerBox.BreakerConfiguration struct type to the format Fuse
expects.
NOTE: The underlying Fuse library treats maximum failures as the number of
errors per time window the breaker can tolerate, which can lead to some
confusion. If you're setting the breaker expecting it to fail after 5 errors
in one second, you may be surprised that it doesn't actually trip until the
6th error in the same time window. This package's API tries to account for
that by insisting max_failures be greater than zero, so we can always
subtract one, and trip_on_failure_number will behave as a user would
expect.
Specs
trip_on_failure_number(config :: t(), max_failures :: pos_integer()) :: t()
Configure a breaker to trip on the Nth failure within the configured
failure_window.
The underlying Fuse library tolerates N failures before tripping the breaker on failure N+1. We've gone with the more user-friendly behaviour of having it trip after N errors by telling Fuse to tolerate N-1 errors.
Specs
within_milliseconds(config :: t(), failure_window :: pos_integer()) :: t()
Configure a breaker's failure window using milliseconds.
Breaker will trip on Nth error within failure_window milliseconds.
If attempted to set with a non-positive-integer value, it will use the default value of 1000
Specs
within_minutes(config :: t(), failure_window :: pos_integer()) :: t()
Configure a breaker's failure window using minutes.
Breaker will trip on Nth error within failure_window 60 seconds 1000 milliseconds.
If attempted to set with a non-positive-integer value, it will use the default value of 1000 milliseconds.
Specs
within_seconds(config :: t(), failure_window :: pos_integer()) :: t()
Configure a breaker's failure window using seconds.
Breaker will trip on Nth error within failure_window * 1000 milliseconds.
If attempted to set with a non-positive-integer value, it will use the default value of 1000 milliseconds.