README
¶
breaker
Go implementation of the circuit breaker design pattern.
Documentation
¶
Overview ¶
Package breaker implements an observable circuit breaker.
A circuit breaker stops requests if a service is not working. It has three states:
- Closed: all requests go through. After a configurable number of errors, the circuit breaker opens.
- Open: the circuit breaker stops all requests from reaching the service.
- Half-Open: after a configurable duration, the circuit moves to 'half-open' state. It allows requests to go through, but any error open the circuit again. After a configurable number of successful calls, the circuit breaker closes fully.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrCircuitOpen = errors.New("circuit is open")
ErrCircuitOpen is the error returned by CircuitBreaker.Do when the circuit is open.
Functions ¶
This section is empty.
Types ¶
type CircuitBreaker ¶
type CircuitBreaker struct {
// contains filtered or unexported fields
}
CircuitBreaker implements the circuit breaker design pattern.
func (*CircuitBreaker) Do ¶
func (c *CircuitBreaker) Do(f func() error) error
Do executes f() in line with the circuit breaker's state. If the circuit breaker is open, Do does not call f() and returns ErrCircuitOpen.
Example ¶
cfg := Configuration{ErrorThreshold: 2}
cb := New(cfg)
for i := range cfg.ErrorThreshold + 1 {
err := cb.Do(func() error {
return errors.New("error")
})
fmt.Printf("%d: err: %v\n", i, err)
}
Output: 0: err: error 1: err: error 2: err: circuit is open
func (*CircuitBreaker) GetCounters ¶
func (c *CircuitBreaker) GetCounters() Counters
GetCounters returns the Counters of the circuit breaker.
func (*CircuitBreaker) GetState ¶
func (c *CircuitBreaker) GetState() State
GetState returns the State of the circuit breaker.
type Configuration ¶
type Configuration struct {
// ShouldOpen overrides when a circuit breaker opens. If nil, the circuit breaker opens after ErrorThreshold consecutive errors.
ShouldOpen func(Counters) bool
// ShouldClose overrides when a circuit breaker opens. If nil, the circuit breaker closes after SuccessThreshold consecutive successful calls.
ShouldClose func(Counters) bool
// Metrics contains the Prometheus metrics to export. Use NewMetrics() to create them and register them with a Prometheus registry. If nil, no metrics are exported.
Metrics *Metrics
// Logger specifies the logger to log every state change (at debug level). If nil, state changes aren't logged.
Logger *slog.Logger
// ErrorThreshold is the number of errors before the circuit breaker opens.
ErrorThreshold int
// OpenDuration is how long the circuit breaker stays open before moving to 'half-open' state. Default is 10 seconds.
OpenDuration time.Duration
// SuccessThreshold is the number of successful calls that will close the half-open circuit breaker.
SuccessThreshold int
// HalfOpenDuration is currently not used.
HalfOpenDuration time.Duration
// HalfOpenThrottle limits the number of parallel requests while the circuit is half-open. Default is zero (no throttling).
HalfOpenThrottle int
}
Configuration for the circuit breaker.
type Counters ¶
type Counters struct {
// Calls is the number of calls performed (successfully or unsuccessfully).
Calls int
// Successes is the total number of successful calls.
Successes int
// ConsecutiveSuccesses is the number of consecutive successful calls.
ConsecutiveSuccesses int
// Errors is the total number of unsuccessful calls.
Errors int
// ConsecutiveErrors is the number of consecutive unsuccessful calls.
ConsecutiveErrors int
}
Counters holds the statistics of the performed calls. It is passed to Configuration.ShouldOpen and Configuration.ShouldClose and can be used to implement custom behaviour to open and close a circuit breaker.
CircuitBreaker resets the counters after each state change.
type Metrics ¶ added in v0.4.0
type Metrics struct {
// contains filtered or unexported fields
}
func NewMetrics ¶ added in v0.4.0
func NewMetrics(namespace, subsystem, cbName string, constLabels prometheus.Labels) *Metrics
NewMetrics returns Prometheus metrics to be used with a CircuitBreaker.
func (*Metrics) Collect ¶ added in v0.4.0
func (m *Metrics) Collect(ch chan<- prometheus.Metric)
Collect implements the prometheus.Collector interface.
func (*Metrics) Describe ¶ added in v0.4.0
func (m *Metrics) Describe(ch chan<- *prometheus.Desc)
Describe implements the prometheus.Collector interface.
type State ¶
type State int
State of the circuit breaker.
const ( // StateClosed is a closed circuit breaker: all requests are processed until the circuit breaker opens. StateClosed State = iota // StateOpen is an open circuit breaker: no requests are processed until the circuit breaker moves to half-open state StateOpen // StateHalfOpen is a half-open circuit breaker: errors will open the circuit breaker immediately. Sufficient successful calls close the circuit breaker. StateHalfOpen )
Source Files