circuitbreaker

Documentation

Overview

Package circuitbreaker implements the circuit breaker.

Sentinel circuit breaker module converts each Rule into a CircuitBreaker. Each CircuitBreaker has its own statistical structure.

Sentinel circuit breaker module supports three strategies:

1. SlowRequestRatio: the ratio of slow response time entry(entry's response time is great than max slow response time) exceeds the threshold. The following entry to resource will be broken. In SlowRequestRatio strategy, user must set max response time.
2. ErrorRatio: the ratio of error entry exceeds the threshold. The following entry to resource will be broken.
3. ErrorCount: the number of error entry exceeds the threshold. The following entry to resource will be broken.

Sentinel circuit breaker is implemented based on state machines. There are three state:

1. Closed: all entries could pass checking.
2. Open: the circuit breaker is broken, all entries are blocked. After retry timeout, circuit breaker switches state to Half-Open and allows one entry to probe whether the resource returns to its expected state.
3. Half-Open: the circuit breaker is in a temporary state of probing, only one entry is allowed to access resource, others are blocked.

Sentinel circuit breaker provides the listener to listen on the state changes.

type StateChangeListener interface {
	OnTransformToClosed(prev State, rule Rule)

	OnTransformToOpen(prev State, rule Rule, snapshot interface{})

	OnTransformToHalfOpen(prev State, rule Rule)
}

Here is the example code to use circuit breaker:

 type stateChangeTestListener struct {}

 func (s *stateChangeTestListener) OnTransformToClosed(prev circuitbreaker.State, rule circuitbreaker.Rule) {
 	fmt.Printf("rule.steategy: %+v, From %s to Closed, time: %d\n", rule.Strategy, prev.String(), util.CurrentTimeMillis())
 }

 func (s *stateChangeTestListener) OnTransformToOpen(prev circuitbreaker.State, rule circuitbreaker.Rule, snapshot interface{}) {
 	fmt.Printf("rule.steategy: %+v, From %s to Open, snapshot: %.2f, time: %d\n", rule.Strategy, prev.String(), snapshot, util.CurrentTimeMillis())
 }

 func (s *stateChangeTestListener) OnTransformToHalfOpen(prev circuitbreaker.State, rule circuitbreaker.Rule) {
 	fmt.Printf("rule.steategy: %+v, From %s to Half-Open, time: %d\n", rule.Strategy, prev.String(), util.CurrentTimeMillis())
 }

 func main() {
 	err := sentinel.InitDefault()
 	if err != nil {
 		log.Fatal(err)
 	}
 	ch := make(chan struct{})
 	// Register a state change listener so that we could observer the state change of the internal circuit breaker.
 	circuitbreaker.RegisterStateChangeListeners(&stateChangeTestListener{})

 	_, err = circuitbreaker.LoadRules([]*circuitbreaker.Rule{
 	// Statistic time span=10s, recoveryTimeout=3s, slowRtUpperBound=50ms, maxSlowRequestRatio=50%
 		{
 			Resource:         "abc",
 			Strategy:         circuitbreaker.SlowRequestRatio,
 			RetryTimeoutMs:   3000,
 			MinRequestAmount: 10,
 			StatIntervalMs:   10000,
 			MaxAllowedRtMs:   50,
 			Threshold:        0.5,
 		},
 		// Statistic time span=10s, recoveryTimeout=3s, maxErrorRatio=50%
 		{
 			Resource:         "abc",
 			Strategy:         circuitbreaker.ErrorRatio,
 			RetryTimeoutMs:   3000,
 			MinRequestAmount: 10,
 			StatIntervalMs:   10000,
 			Threshold:        0.5,
 		},
 	})
 	if err != nil {
 		log.Fatal(err)
 	}

 	fmt.Println("Sentinel Go circuit breaking demo is running. You may see the pass/block metric in the metric log.")
 	go func() {
 		for {
 			e, b := sentinel.Entry("abc")
 			if b != nil {
 				//fmt.Println("g1blocked")
 				time.Sleep(time.Duration(rand.Uint64()%20) * time.Millisecond)
 			} else {
 				if rand.Uint64()%20 > 9 {
 					// Record current invocation as error.
 					sentinel.TraceError(e, errors.New("biz error"))
 				}
 				//fmt.Println("g1passed")
 				time.Sleep(time.Duration(rand.Uint64()%80+10) * time.Millisecond)
 				e.Exit()
 			}
 		}
		}()

 	go func() {
 		for {
 			e, b := sentinel.Entry("abc")
 			if b != nil {
 				//fmt.Println("g2blocked")
 				time.Sleep(time.Duration(rand.Uint64()%20) * time.Millisecond)
 			} else {
 				//fmt.Println("g2passed")
 				time.Sleep(time.Duration(rand.Uint64()%80) * time.Millisecond)
 				e.Exit()
 			}
 		}
 	}()
 	<-ch
 }

Index

• func ClearRules() error
• func ClearStateChangeListeners()
• func IsValid(r *Rule) error
• func LoadRules(rules []*Rule) (bool, error)
• func RegisterStateChangeListeners(listeners ...StateChangeListener)
• func RemoveCircuitBreakerGenerator(s Strategy) error
• func SetCircuitBreakerGenerator(s Strategy, generator CircuitBreakerGenFunc) error
• type CircuitBreaker
• type CircuitBreakerGenFunc
• type MetricStatSlot
  • func (c *MetricStatSlot) OnCompleted(ctx *base.EntryContext)
  • func (c *MetricStatSlot) OnEntryBlocked(_ *base.EntryContext, _ *base.BlockError)
  • func (c *MetricStatSlot) OnEntryPassed(_ *base.EntryContext)
• type Rule
  • func GetResRules(resource string) []*Rule
  • func (r *Rule) ResourceName() string
  • func (r *Rule) String() string
• type Slot
  • func (b *Slot) Check(ctx *base.EntryContext) *base.TokenResult
• type State
  • func (s *State) String() string
• type StateChangeListener
• type Strategy
  • func (s Strategy) String() string

Functions

func ClearRules

func ClearRules() error

ClearRules clear all the previous rules.

func ClearStateChangeListeners

func ClearStateChangeListeners()

ClearStateChangeListeners will clear the all StateChangeListener Note: this function is not thread-safe.

func IsValid

func IsValid(r *Rule) error

func LoadRules

func LoadRules(rules []*Rule) (bool, error)

LoadRules replaces old rules with the given circuit breaking rules.

return value:

bool: was designed to indicate whether the internal map has been changed error: was designed to indicate whether occurs the error.

func RegisterStateChangeListeners

func RegisterStateChangeListeners(listeners ...StateChangeListener)

Note: this function is not thread-safe.

func RemoveCircuitBreakerGenerator

func RemoveCircuitBreakerGenerator(s Strategy) error

func SetCircuitBreakerGenerator

func SetCircuitBreakerGenerator(s Strategy, generator CircuitBreakerGenFunc) error

SetCircuitBreakerGenerator sets the circuit breaker generator for the given strategy. Note that modifying the generator of default strategies is not allowed.

Types

type CircuitBreaker

type CircuitBreaker interface {
	// BoundRule returns the associated circuit breaking rule.
	BoundRule() *Rule
	// BoundStat returns the associated statistic data structure.
	BoundStat() interface{}
	// TryPass acquires permission of an invocation only if it is available at the time of invocation.
	TryPass(ctx *base.EntryContext) bool
	// CurrentState returns current state of the circuit breaker.
	CurrentState() State
	// OnRequestComplete record a completed request with the given response time as well as error (if present),
	// and handle state transformation of the circuit breaker.
	// OnRequestComplete is called only when a passed invocation finished.
	OnRequestComplete(rtt uint64, err error)
}

CircuitBreaker is the basic interface of circuit breaker

type CircuitBreakerGenFunc

type CircuitBreakerGenFunc func(r *Rule, reuseStat interface{}) (CircuitBreaker, error)

type MetricStatSlot

type MetricStatSlot struct {
}

MetricStatSlot records metrics for circuit breaker on invocation completed. MetricStatSlot must be filled into slot chain if circuit breaker is alive.

func (*MetricStatSlot) OnCompleted

func (c *MetricStatSlot) OnCompleted(ctx *base.EntryContext)

func (*MetricStatSlot) OnEntryBlocked

func (c *MetricStatSlot) OnEntryBlocked(_ *base.EntryContext, _ *base.BlockError)

func (*MetricStatSlot) OnEntryPassed

func (c *MetricStatSlot) OnEntryPassed(_ *base.EntryContext)

type Rule

type Rule struct {
	// unique id
	Id string `json:"id,omitempty"`
	// resource name
	Resource string   `json:"resource"`
	Strategy Strategy `json:"strategy"`
	// RetryTimeoutMs represents recovery timeout (in milliseconds) before the circuit breaker opens.
	// During the open period, no requests are permitted until the timeout has elapsed.
	// After that, the circuit breaker will transform to half-open state for trying a few "trial" requests.
	RetryTimeoutMs uint32 `json:"retryTimeoutMs"`
	// MinRequestAmount represents the minimum number of requests (in an active statistic time span)
	// that can trigger circuit breaking.
	MinRequestAmount uint64 `json:"minRequestAmount"`
	// StatIntervalMs represents statistic time interval of the internal circuit breaker (in ms).
	StatIntervalMs uint32 `json:"statIntervalMs"`
	// MaxAllowedRtMs indicates that any invocation whose response time exceeds this value (in ms)
	// will be recorded as a slow request.
	// MaxAllowedRtMs only takes effect for SlowRequestRatio strategy
	MaxAllowedRtMs uint64 `json:"maxAllowedRtMs"`
	// Threshold represents the threshold of circuit breaker.
	// for SlowRequestRatio, it represents the max slow request ratio
	// for ErrorRatio, it represents the max error request ratio
	// for ErrorCount, it represents the max error request count
	Threshold float64 `json:"threshold"`
}

Rule encompasses the fields of circuit breaking rule.

func GetResRules

func GetResRules(resource string) []*Rule

func (*Rule) ResourceName

func (r *Rule) ResourceName() string

func (*Rule) String

func (r *Rule) String() string

type Slot

type Slot struct {
}

func (*Slot) Check

func (b *Slot) Check(ctx *base.EntryContext) *base.TokenResult

type State

type State int32

 Circuit Breaker State Machine:

                                switch to open based on rule
				+-----------------------------------------------------------------------+
				|                                                                       |
				|                                                                       v
		+----------------+                   +----------------+      Probe      +----------------+
		|                |                   |                |<----------------|                |
		|                |   Probe succeed   |                |                 |                |
		|     Closed     |<------------------|    HalfOpen    |                 |      Open      |
		|                |                   |                |   Probe failed  |                |
		|                |                   |                +---------------->|                |
		+----------------+                   +----------------+                 +----------------+

const (
	Closed State = iota
	HalfOpen
	Open
)

func (*State) String

func (s *State) String() string

type StateChangeListener

type StateChangeListener interface {
	// OnTransformToClosed is triggered when circuit breaker state transformed to Closed.
	// Argument rule is copy from circuit breaker's rule, any changes of rule don't take effect for circuit breaker
	// Copying rule has a performance penalty and avoids invalid listeners as much as possible
	OnTransformToClosed(prev State, rule Rule)

	// OnTransformToOpen is triggered when circuit breaker state transformed to Open.
	// The "snapshot" indicates the triggered value when the transformation occurs.
	// Argument rule is copy from circuit breaker's rule, any changes of rule don't take effect for circuit breaker
	// Copying rule has a performance penalty and avoids invalid listeners as much as possible
	OnTransformToOpen(prev State, rule Rule, snapshot interface{})

	// OnTransformToHalfOpen is triggered when circuit breaker state transformed to HalfOpen.
	// Argument rule is copy from circuit breaker's rule, any changes of rule don't take effect for circuit breaker
	// Copying rule has a performance penalty and avoids invalid listeners as much as possible
	OnTransformToHalfOpen(prev State, rule Rule)
}

StateChangeListener listens on the circuit breaker state change event

type Strategy

type Strategy int8

Strategy represents the strategy of circuit breaker. Each strategy is associated with one rule type.

const (
	// SlowRequestRatio strategy changes the circuit breaker state based on slow request ratio
	SlowRequestRatio Strategy = iota
	// ErrorRatio strategy changes the circuit breaker state based on error request ratio
	ErrorRatio
	// ErrorCount strategy changes the circuit breaker state based on error amount
	ErrorCount
)

func (Strategy) String

func (s Strategy) String() string