circuit

package
v0.0.0-...-7429660 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 29, 2023 License: Apache-2.0 Imports: 17 Imported by: 0

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.

This file implement some rate limiter.

Index

Constants

View Source 
const (
	QPSReject      = "reject"
	QPSLeakyBucket = "leaky_bucket"
	QPSSlowStart   = "slow_start"
)

Variables

View Source 
var (
	ErrBreakerTimeout = NewBreakerError("breaker: timeout")

	ErrMaxConcurrent = NewBreakerError("breaker: exceeds max concurrent request number")
	ErrRateLimit     = NewBreakerError("breaker: exceeds request rate limit")
	ErrSystemLoad    = NewBreakerError("breaker: exceeds system load")
	ErrAverageRT     = NewBreakerError("breaker: exceeds average rt")
	ErrConsecutive   = NewBreakerError("breaker: exceeds consecutive fail times")
	ErrPercent       = NewBreakerError("breaker: exceeds error percent")
	ErrOpen          = NewBreakerError("breaker: initiative open")
)

Error codes returned by Call

View Source 
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 AddBreaker 

func AddBreaker(name string, cb *Breaker)

func SetLogger 

func SetLogger(l *log.Logger)

func SettingAverageRT 

func SettingAverageRT(name string, open bool, rt time.Duration)

func SettingConsecutiveError 

func SettingConsecutiveError(name string, open bool, threshold int64)

func SettingErrorPercent 

func SettingErrorPercent(name string, open bool, threshold int64, minSamples int64)

func SettingMaxConcurrent 

func SettingMaxConcurrent(name string, open bool, threshold int64)

SettingMaxConcurrent set the max concurrent limiter's configure.

func SettingQPSLimitLeakyBucket 

func SettingQPSLimitLeakyBucket(name string, open bool, leaky int64)

func SettingQPSLimitReject 

func SettingQPSLimitReject(name string, open bool, reject int64)

func SettingSystemLoads 

func SettingSystemLoads(name string, open bool, threshold float64)

SettingSystemLoads set the system load limiter's configure. All SettingXX function can change configure concurrently at runtime. Parameter name is the resource name you what to setting. Parameter open control whether use system load limiter. Parameter threshold is the system load1 value.

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

	// ShouldTrip is a TripFunc that determines whether a Fail() call should trip the breaker.
	ShouldTripFail    []CheckerFunc
	ShouldTripSuccess []CheckerFunc

	// TODO
	Checkers []CheckerFunc

	// Clock is used for controlling time in tests.
	Clock clock.Clock

	// TODO
	Sys System
	// 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 GetBreaker(name string) *Breaker

func NewBreakerWithOptions 

func NewBreakerWithOptions(options *Options) *Breaker

NewBreakerWithOptions creates a base breaker with a specified backoff, clock and TripFunc

func (*Breaker) AddListener 

func (cb *Breaker) AddListener(listener chan ListenerEvent)

AddListener adds a channel of ListenerEvents on behalf of a listener. The listener channel must be buffered.

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 

func (cb *Breaker) Call(circuit func() error) error

func (*Breaker) CallContext 

func (cb *Breaker) CallContext(ctx context.Context, circuit func() error) 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 

func (cb *Breaker) ConsecFailures() int64

ConsecFailures returns the number of consecutive failures that have occured.

func (*Breaker) ErrorRate 

func (cb *Breaker) ErrorRate() float64

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) Failures 

func (cb *Breaker) Failures() int64

Failures returns the number of failures for this circuit breaker.

func (*Breaker) GetStats 

func (cb *Breaker) GetStats() Stats

func (*Breaker) Ready 

func (cb *Breaker) Ready() bool

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) RemoveListener 

func (cb *Breaker) RemoveListener(listener chan ListenerEvent) bool

RemoveListener removes a channel previously added via AddListener. Once removed, the channel will no longer receive ListenerEvents. Returns true if the listener was found and removed.

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) Subscribe 

func (cb *Breaker) Subscribe() <-chan BreakerEvent

Subscribe returns a channel of BreakerEvents. Whenever the breaker changes state, the state will be sent over the channel. See BreakerEvent for the types of events.

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().

func (*Breaker) SuccessWithUpdate 

func (cb *Breaker) SuccessWithUpdate(r metricResult)

func (*Breaker) Successes 

func (cb *Breaker) Successes() int64

Successes returns the number of successes for this circuit breaker.

func (*Breaker) Trip 

func (cb *Breaker) Trip(err error)

Trip will trip the circuit breaker. After Trip() is called, Tripped() will return true.

func (*Breaker) Tripped 

func (cb *Breaker) Tripped() bool

Tripped returns true if the circuit breaker is tripped, false if it is reset.

type BreakerError 

type BreakerError interface {
	Error() string
	Breaker() bool
}

func NewBreakerError 

func NewBreakerError(m string) BreakerError

type BreakerEvent 

type BreakerEvent int

BreakerEvent indicates the type of event received over an event channel 

const (
	// BreakerTripped is sent when a breaker trips
	BreakerTripped BreakerEvent = iota

	// BreakerReset is sent when a breaker resets
	BreakerReset BreakerEvent = iota

	// BreakerFail is sent when Fail() is called
	BreakerFail BreakerEvent = iota

	// BreakerReady is sent when the breaker enters the half open state and is ready to retry
	BreakerReady BreakerEvent = iota
)

type CheckerFunc 

type CheckerFunc func(*Breaker) error

CheckerFunc is a function called by a Breaker's and check whether exceeds the breaker resource. It will receive the Breaker as an argument and returns an error. By default, a Breaker has no CheckerFunc.

func AverageRTTripFunc 

func AverageRTTripFunc(name string) CheckerFunc

AverageRTTripFunc returns a TripFunc with that trips whenever the success response time excced the threshold.

func ConsecutiveTripFunc 

func ConsecutiveTripFunc(name string) CheckerFunc

ConsecutiveTripFunc returns a TripFunc that trips whenever the consecutive failure count meets the threshold.

func ErrorPercentTripFunc 

func ErrorPercentTripFunc(name string) CheckerFunc

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.

func MaxConcurrentCheckerFunc 

func MaxConcurrentCheckerFunc(name string) CheckerFunc

MaxConcurrentCheckerFunc return a CheckerFunc that return error whenever the concurrent request number exceed the threshold.

func QPSCheckerFunc 

func QPSCheckerFunc(name string) CheckerFunc

QPSCheckerFunc return a CheckerFunc that return error whenever request rate exceeds the QPS limter currently used.

func QPSLeakyBucketCheckerFunc 

func QPSLeakyBucketCheckerFunc(name string) CheckerFunc

QPSLeakyBucketCheckerFunc return a CheckerFunc that will block the function whenever the request QPS exceeds the limit using leaky bucket. QPSLeakyBucketCheckerFunc must be checked after the MaxConcurrentCheckerFunc.

func QPSRejectCheckerFunc 

func QPSRejectCheckerFunc(name string) CheckerFunc

QPSRejectCheckerFunc return a CheckerFunc that return error whenever the request number per second exceed the threshold.

func QPSSlowStartCheckerFunc 

func QPSSlowStartCheckerFunc(name string) CheckerFunc

QPSSlowStartCheckerFunc return a CheckerFunc that return error whenever the rate of incoming request exceeds the QPSSlowStartCheckerFunc's growing rate.

func SystemLoadCheckerFunc 

func SystemLoadCheckerFunc(name string) CheckerFunc

SystemLoadCheckerFunc return a CheckerFunc that return error whenever the system load1 exceeds the threshold.

type ListenerEvent 

type ListenerEvent struct {
	CB    *Breaker
	Event BreakerEvent
}

ListenerEvent includes a reference to the circuit breaker and the event.

type Options 

type Options struct {
	BackOff       backoff.BackOff
	Clock         clock.Clock
	WindowTime    time.Duration
	WindowBuckets int
	Name          string
	Sys           System
}

Options holds breaker configuration options.

type Panel 

type Panel struct {
	StatsPrefixf string
	// contains filtered or unexported fields
}

Panel tracks a group of circuit breakers by name.

func NewPanel 

func NewPanel() *Panel

NewPanel creates a new Panel

func (*Panel) Add 

func (p *Panel) Add(name string, cb *Breaker)

Add sets the name as a reference to the given circuit breaker.

func (*Panel) Get 

func (p *Panel) Get(name string) *Breaker

Get retrieves a circuit breaker by name. If no circuit breaker exists, it returns the NoOp one and sets ok to false.

func (*Panel) Subscribe 

func (p *Panel) Subscribe() <-chan PanelEvent

Subscribe returns a channel of PanelEvents. Whenever a breaker changes state, the PanelEvent will be sent over the channel. See BreakerEvent for the types of events.

type PanelEvent 

type PanelEvent struct {
	Name  string
	Event BreakerEvent
}

PanelEvent wraps a BreakerEvent and provides the string name of the breaker

type Stats 

type Stats struct {
	Concurrent       int
	SystemLoad       float64
	AverageRT        time.Duration
	ErrorPercent     int
	ErrorSamples     int
	ErrorConsecutive int
}

type System 

type System interface {
	Load1() (float64, error)
}

type TripFunc 

type TripFunc func(*Breaker) bool

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.