Skip to content

Commit f9ddf58

Browse files
louyutinglouyuting
authored
Add doc.go for core/api, flow and circuitbreaker package (#235)
1 parent bd07b4b commit f9ddf58

File tree

4 files changed

+179
-1
lines changed

4 files changed

+179
-1
lines changed

‎api/api.go

-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
// Package api provides fundamental APIs of Sentinel.
21
package api
32

43
import (

‎api/doc.go

+50
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
// Package api provides the topmost fundamental APIs for users using sentinel-golang.
2+
// Users must initialize Sentinel before loading Sentinel rules. Sentinel support three ways to perform initialization:
3+
//
4+
// 1. api.InitDefault(), using default config to initialize.
5+
// 2. api.InitWithConfig(confEntity *config.Entity), using customized config Entity to initialize.
6+
// 3. api.InitWithConfigFile(configPath string), using yaml file to initialize.
7+
//
8+
// Here is the example code to use Sentinel:
9+
//
10+
// import sentinel "github.com/alibaba/sentinel-golang/api"
11+
//
12+
// err := sentinel.InitDefault()
13+
// if err != nil {
14+
// log.Fatal(err)
15+
// }
16+
//
17+
// //Load sentinel rules
18+
// _, err = flow.LoadRules([]*flow.Rule{
19+
// {
20+
// Resource: "some-test",
21+
// MetricType: flow.QPS,
22+
// Count: 10,
23+
// ControlBehavior: flow.Reject,
24+
// },
25+
// })
26+
// if err != nil {
27+
// log.Fatalf("Unexpected error: %+v", err)
28+
// return
29+
// }
30+
// ch := make(chan struct{})
31+
// for i := 0; i < 10; i++ {
32+
// go func() {
33+
// for {
34+
// e, b := sentinel.Entry("some-test", sentinel.WithTrafficType(base.Inbound))
35+
// if b != nil {
36+
// // Blocked. We could get the block reason from the BlockError.
37+
// time.Sleep(time.Duration(rand.Uint64()%10) * time.Millisecond)
38+
// } else {
39+
// // Passed, wrap the logic here.
40+
// fmt.Println(util.CurrentTimeMillis(), "passed")
41+
// time.Sleep(time.Duration(rand.Uint64()%10) * time.Millisecond)
42+
// // Be sure the entry is exited finally.
43+
// e.Exit()
44+
// }
45+
// }
46+
// }()
47+
// }
48+
// <-ch
49+
//
50+
package api

‎core/circuitbreaker/doc.go

+113
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
// Package circuitbreaker implements the circuit breaker.
2+
//
3+
// Sentinel circuit breaker module converts each Rule into a CircuitBreaker. Each CircuitBreaker has its own statistical structure.
4+
//
5+
// Sentinel circuit breaker module supports three strategies:
6+
//
7+
// 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.
8+
// In SlowRequestRatio strategy, user must set max response time.
9+
// 2. ErrorRatio: the ratio of error entry exceeds the threshold. The following entry to resource will be broken.
10+
// 3. ErrorCount: the number of error entry exceeds the threshold. The following entry to resource will be broken.
11+
//
12+
// Sentinel circuit breaker is implemented based on state machines. There are three state:
13+
//
14+
// 1. Closed: all entries could pass checking.
15+
// 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.
16+
// 3. Half-Open: the circuit breaker is in a temporary state of probing, only one entry is allowed to access resource, others are blocked.
17+
//
18+
// Sentinel circuit breaker provides the listener to listen on the state changes.
19+
//
20+
// type StateChangeListener interface {
21+
// OnTransformToClosed(prev State, rule Rule)
22+
//
23+
// OnTransformToOpen(prev State, rule Rule, snapshot interface{})
24+
//
25+
// OnTransformToHalfOpen(prev State, rule Rule)
26+
// }
27+
//
28+
// Here is the example code to use circuit breaker:
29+
//
30+
// type stateChangeTestListener struct {}
31+
//
32+
// func (s *stateChangeTestListener) OnTransformToClosed(prev circuitbreaker.State, rule circuitbreaker.Rule) {
33+
// fmt.Printf("rule.steategy: %+v, From %s to Closed, time: %d\n", rule.Strategy, prev.String(), util.CurrentTimeMillis())
34+
// }
35+
//
36+
// func (s *stateChangeTestListener) OnTransformToOpen(prev circuitbreaker.State, rule circuitbreaker.Rule, snapshot interface{}) {
37+
// fmt.Printf("rule.steategy: %+v, From %s to Open, snapshot: %.2f, time: %d\n", rule.Strategy, prev.String(), snapshot, util.CurrentTimeMillis())
38+
// }
39+
//
40+
// func (s *stateChangeTestListener) OnTransformToHalfOpen(prev circuitbreaker.State, rule circuitbreaker.Rule) {
41+
// fmt.Printf("rule.steategy: %+v, From %s to Half-Open, time: %d\n", rule.Strategy, prev.String(), util.CurrentTimeMillis())
42+
// }
43+
//
44+
// func main() {
45+
// err := sentinel.InitDefault()
46+
// if err != nil {
47+
// log.Fatal(err)
48+
// }
49+
// ch := make(chan struct{})
50+
// // Register a state change listener so that we could observer the state change of the internal circuit breaker.
51+
// circuitbreaker.RegisterStateChangeListeners(&stateChangeTestListener{})
52+
//
53+
// _, err = circuitbreaker.LoadRules([]*circuitbreaker.Rule{
54+
// // Statistic time span=10s, recoveryTimeout=3s, slowRtUpperBound=50ms, maxSlowRequestRatio=50%
55+
// {
56+
// Resource: "abc",
57+
// Strategy: circuitbreaker.SlowRequestRatio,
58+
// RetryTimeoutMs: 3000,
59+
// MinRequestAmount: 10,
60+
// StatIntervalMs: 10000,
61+
// MaxAllowedRtMs: 50,
62+
// Threshold: 0.5,
63+
// },
64+
// // Statistic time span=10s, recoveryTimeout=3s, maxErrorRatio=50%
65+
// {
66+
// Resource: "abc",
67+
// Strategy: circuitbreaker.ErrorRatio,
68+
// RetryTimeoutMs: 3000,
69+
// MinRequestAmount: 10,
70+
// StatIntervalMs: 10000,
71+
// Threshold: 0.5,
72+
// },
73+
// })
74+
// if err != nil {
75+
// log.Fatal(err)
76+
// }
77+
//
78+
// fmt.Println("Sentinel Go circuit breaking demo is running. You may see the pass/block metric in the metric log.")
79+
// go func() {
80+
// for {
81+
// e, b := sentinel.Entry("abc")
82+
// if b != nil {
83+
// //fmt.Println("g1blocked")
84+
// time.Sleep(time.Duration(rand.Uint64()%20) * time.Millisecond)
85+
// } else {
86+
// if rand.Uint64()%20 > 9 {
87+
// // Record current invocation as error.
88+
// sentinel.TraceError(e, errors.New("biz error"))
89+
// }
90+
// //fmt.Println("g1passed")
91+
// time.Sleep(time.Duration(rand.Uint64()%80+10) * time.Millisecond)
92+
// e.Exit()
93+
// }
94+
// }
95+
// }()
96+
//
97+
// go func() {
98+
// for {
99+
// e, b := sentinel.Entry("abc")
100+
// if b != nil {
101+
// //fmt.Println("g2blocked")
102+
// time.Sleep(time.Duration(rand.Uint64()%20) * time.Millisecond)
103+
// } else {
104+
// //fmt.Println("g2passed")
105+
// time.Sleep(time.Duration(rand.Uint64()%80) * time.Millisecond)
106+
// e.Exit()
107+
// }
108+
// }
109+
// }()
110+
// <-ch
111+
// }
112+
//
113+
package circuitbreaker

‎core/flow/doc.go

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
// Package flow implements the flow shaping control.
2+
//
3+
// flow module supports two statistic metric: QPS and Concurrency.
4+
//
5+
// The TrafficShapingController consists of two part: TrafficShapingCalculator and TrafficShapingChecker
6+
//
7+
// 1. TrafficShapingCalculator calculates the actual traffic shaping token threshold. Currently, Sentinel supports two token calculate strategy: Direct and WarmUp.
8+
// 2. TrafficShapingChecker performs checking logic according to current metrics and the traffic shaping strategy, then yield the token result. Currently, Sentinel supports two control behavior: Reject and Throttling.
9+
//
10+
// Besides, Sentinel supports customized TrafficShapingCalculator and TrafficShapingChecker. User could call function SetTrafficShapingGenerator to register customized TrafficShapingController and call function RemoveTrafficShapingGenerator to unregister TrafficShapingController.
11+
// There are a few notes users need to be aware of:
12+
//
13+
// 1. The function both SetTrafficShapingGenerator and RemoveTrafficShapingGenerator is not thread safe.
14+
// 2. Users can not override the Sentinel supported TrafficShapingController.
15+
//
16+
package flow

0 commit comments

Comments
 (0)