README
¶
circuitbreaker
Circuitbreaker provides an easy way to use the Circuit Breaker pattern in a Go program.
Circuit breakers are typically used when your program makes remote calls. Remote calls can often hang for a while before they time out. If your application makes a lot of these requests, many resources can be tied up waiting for these time outs to occur. A circuit breaker wraps these remote calls and will trip after a defined amount of failures or time outs occur. When a circuit breaker is tripped any future calls will avoid making the remote call and return an error to the caller. In the meantime, the circuit breaker will periodically allow some calls to be tried again and will close the circuit if those are successful.
You can read more about this pattern and how it's used at:
Installation
go get github.com/rubyist/circuitbreaker
Examples
Here is a quick example of what circuitbreaker provides
// Creates a circuit breaker that will trip if the function fails 10 times
cb := circuit.NewThresholdBreaker(10)
events := cb.Subscribe()
go func() {
for {
e := <-events
// Monitor breaker events like BreakerTripped, BreakerReset, BreakerFail, BreakerReady
}
}()
cb.Call(func() error {
// This is where you'll do some remote call
// If it fails, return an error
}, 0)
Circuitbreaker can also wrap a time out around the remote call.
// Creates a circuit breaker that will trip after 10 failures
// using a time out of 5 seconds
cb := circuit.NewThresholdBreaker(10)
cb.Call(func() error {
// This is where you'll do some remote call
// If it fails, return an error
}, time.Second * 5) // This will time out after 5 seconds, which counts as a failure
// Proceed as above
Circuitbreaker can also trip based on the number of consecutive failures.
// Creates a circuit breaker that will trip if 10 consecutive failures occur
cb := circuit.NewConsecutiveBreaker(10)
// Proceed as above
Circuitbreaker can trip based on the error rate.
// Creates a circuit breaker based on the error rate
cb := circuit.NewRateBreaker(0.95, 100) // trip when error rate hits 95%, with at least 100 samples
// Proceed as above
If it doesn't make sense to wrap logic in Call(), breakers can be handled manually.
cb := circuit.NewThresholdBreaker(10)
for {
if cb.Ready() {
// Breaker is not tripped, proceed
err := doSomething()
if err != nil {
cb.Fail() // This will trip the breaker once it's failed 10 times
continue
}
cb.Success()
} else {
// Breaker is in a tripped state.
}
}
Circuitbreaker also provides a wrapper around http.Client that will wrap a
time out around any request.
// Passing in nil will create a regular http.Client.
// You can also build your own http.Client and pass it in
client := circuit.NewHTTPClient(time.Second * 5, 10, nil)
resp, err := client.Get("http://example.com/resource.json")
See the godoc for more examples.
Bugs, Issues, Feedback
Right here on GitHub: https://github.com/rubyist/circuitbreaker
Documentation
¶
Overview ¶
Package circuit implements the Circuit Breaker pattern. It will wrap a function call (typically one which uses remote services) and monitors for failures and/or time outs. When a threshold of failures or time outs has been reached, future calls to the function will not run. During this state, the breaker will periodically allow the function to run and, if it is successful, will start running the function again.
Circuit includes three types of circuit breakers:
A Threshold Breaker will trip when the failure count reaches a given threshold. It does not matter how long it takes to reach the threshold and the failures do not need to be consecutive.
A Consecutive Breaker will trip when the consecutive failure count reaches a given threshold. It does not matter how long it takes to reach the threshold, but the failures do need to be consecutive.
When wrapping blocks of code with a Breaker's Call() function, a time out can be specified. If the time out is reached, the breaker's Fail() function will be called.
Other types of circuit breakers can be easily built by creating a Breaker and adding a custom TripFunc. A TripFunc is called when a Breaker Fail()s and receives the breaker as an argument. It then returns true or false to indicate whether the breaker should trip.
The package also provides a wrapper around an http.Client that wraps all of the http.Client functions with a Breaker.
Index ¶
- Constants
- Variables
- func Configure(name string, config *BreakerConfig)
- func GetClientBreakerName(namespace, clientname, resource string) string
- func GetDefaultClientBreakerName(namespace string) string
- func GetDefaultServerBreakerName(namespace string) string
- func GetServerBreakerName(namespace, resource string) string
- func InitBreakers(configs []BreakerConfig)
- func InitDefaultConfig(configs []BreakerConfig)
- func NewError(m string) error
- func ReloadConfig(configs []BreakerConfig)
- type Breaker
- func (cb *Breaker) Break()
- func (cb *Breaker) Broken() bool
- func (cb *Breaker) Call(circuit func() error, timeout time.Duration) error
- func (cb *Breaker) CallContext(ctx context.Context, circuit func() error, timeout time.Duration) error
- func (cb *Breaker) ConsecFailures() int64
- func (cb *Breaker) ErrorRate() float64
- func (cb *Breaker) Fail()
- func (cb *Breaker) Failures() int64
- func (cb *Breaker) Ready() bool
- func (cb *Breaker) Reset()
- func (cb *Breaker) ResetCounters()
- func (cb *Breaker) ShouldTrip() bool
- func (cb *Breaker) Success()
- func (cb *Breaker) Successes() int64
- func (cb *Breaker) Trip()
- func (cb *Breaker) Tripped() bool
- type BreakerConfig
- type Config
- type Error
- type Options
- type TripFunc
Constants ¶
const ( ClientBreakerType = 1 ServerBreakerType = 2 )
Variables ¶
var ( ErrOpen = NewError("breaker: open") ErrTimeout = NewError("breaker: timeout") ErrConsecutiveThreshold = NewError("breaker: consecutive error threshold") ErrPercentThreshold = NewError("breaker: error percent threshold") )
var ( // DefaultWindowTime is the default time the window covers, 10 seconds. DefaultWindowTime = time.Millisecond * 10000 // DefaultWindowBuckets is the default number of buckets the window holds, 10. DefaultWindowBuckets = 10 )
Functions ¶
func GetClientBreakerName ¶
namespace@client@clientname@resource
func GetDefaultClientBreakerName ¶
namespace@client@*
func GetDefaultServerBreakerName ¶
namespace@server@*
func GetServerBreakerName ¶
namespace@server@resource
func InitBreakers ¶
func InitBreakers(configs []BreakerConfig)
func InitDefaultConfig ¶
func InitDefaultConfig(configs []BreakerConfig)
Types ¶
type Breaker ¶
type Breaker struct {
// BackOff is the backoff policy that is used when determining if the breaker should
// attempt to retry. A breaker created with NewBreaker will use an exponential backoff
// policy by default.
BackOff backoff.BackOff
// Clock is used for controlling time in tests.
Clock clock.Clock
// contains filtered or unexported fields
}
Breaker is the base of a circuit breaker. It maintains failure and success counters as well as the event subscribers.
func GetBreaker ¶
func NewBreaker ¶
NewBreaker creates a base breaker with an exponential backoff and no TripFunc
func NewBreakerWithOptions ¶
NewBreakerWithOptions creates a base breaker with a specified backoff, clock and TripFunc
func (*Breaker) Break ¶
func (cb *Breaker) Break()
Break trips the circuit breaker and prevents it from auto resetting. Use this when manual control over the circuit breaker state is needed.
func (*Breaker) Call ¶
Call wraps a function the Breaker will protect. A failure is recorded whenever the function returns an error. If the called function takes longer than timeout to run, a failure will be recorded.
func (*Breaker) CallContext ¶
func (cb *Breaker) CallContext(ctx context.Context, circuit func() error, timeout time.Duration) error
CallContext is same as Call but if the ctx is canceled after the circuit returned an error, the error will not be marked as a failure because the call was canceled intentionally.
func (*Breaker) ConsecFailures ¶
ConsecFailures returns the number of consecutive failures that have occured.
func (*Breaker) ErrorRate ¶
ErrorRate returns the current error rate of the Breaker, expressed as a floating point number (e.g. 0.9 for 90%), since the last time the breaker was Reset.
func (*Breaker) Fail ¶
func (cb *Breaker) Fail()
Fail is used to indicate a failure condition the Breaker should record. It will increment the failure counters and store the time of the last failure. If the breaker has a TripFunc it will be called, tripping the breaker if necessary.
func (*Breaker) Ready ¶
Ready will return true if the circuit breaker is ready to call the function. It will be ready if the breaker is in a reset state, or if it is time to retry the call for auto resetting.
func (*Breaker) Reset ¶
func (cb *Breaker) Reset()
Reset will reset the circuit breaker. After Reset() is called, Tripped() will return false.
func (*Breaker) ResetCounters ¶
func (cb *Breaker) ResetCounters()
ResetCounters will reset only the failures, consecFailures, and success counters
func (*Breaker) ShouldTrip ¶
func (*Breaker) Success ¶
func (cb *Breaker) Success()
Success is used to indicate a success condition the Breaker should record. If the success was triggered by a retry attempt, the breaker will be Reset().
type BreakerConfig ¶
type Config ¶
type Config struct{}
func NewConfig ¶
func NewConfig(configs []BreakerConfig) *Config
func (*Config) AddConfig ¶
func (c *Config) AddConfig(configs []BreakerConfig)
type Options ¶
type Options struct {
BackOff backoff.BackOff
Clock clock.Clock
WindowTime time.Duration
WindowBuckets int
Name string
}
Options holds breaker configuration options.
type TripFunc ¶
TripFunc is a function called by a Breaker's Fail() function and determines whether the breaker should trip. It will receive the Breaker as an argument and returns a boolean. By default, a Breaker has no TripFunc.
func ConsecutiveTripFunc ¶
ConsecutiveTripFunc returns a TripFunc that trips whenever the consecutive failure count meets the threshold.
func ErrorPercentTripFunc ¶
RateTripFunc returns a TripFunc that trips whenever the error rate hits the threshold. The error rate is calculated as such: f = number of failures s = number of successes e = f / (f + s) The error rate is calculated over a sliding window of 10 seconds (by default) This TripFunc will not trip until there have been at least minSamples events.
Source Files