33 |
34 |
35 | class CircuitBreaker
36 |
37 |
38 |
39 |
40 |
41 |
42 |
43 |
44 |
45 |
Overview
46 |
47 |
Simple Implementation of the circuit breaker pattern in Crystal.
48 |
49 |
Given a certain error threshold, timeframe and timeout window, a breaker can be used to monitor criticial command executions. Circuit breakers are usually used to prevent unnecessary requests if a server ressource et al becomes unavailable. This protects the server from additional load and allows it to recover and relieves the client from requests that are doomed to fail.
50 |
51 |
Wrap API calls inside a breaker, if the error rate in a given time frame surpasses a certain threshold, all subsequent calls will fail for a given duration.
52 |
53 |
54 |
55 |
56 |
57 |
58 |
59 |
60 |
61 |
62 |
63 |
64 |
65 |
66 |
Defined in:
67 |
68 |
69 |
circuit_breaker.cr
70 |
71 |
72 |
73 |
74 |
75 |
76 |
77 |
78 |
Class Method Summary
79 |
89 |
90 |
91 |
92 |
Instance Method Summary
93 |
94 |
95 | -
96 | #run(&block)
97 |
98 |
get's passed a block to watch for errors every error thrown inside your block counts towards the error rate once the threshold is surpassed, it starts throwing CircuitOpenExceptions you can catch these rrors and implement some fallback behaviour
101 |
102 |
103 |
104 |
105 |
106 |
107 |
108 |
109 |
110 |
111 |
112 |
113 |
114 |
115 |
116 |
117 |
118 |
119 |
120 |
121 |
122 |
123 |
124 |
125 |
126 |
127 |
Class Method Detail
128 |
129 |
130 |
131 |
132 | def self.
new(threshold error_threshold, timewindow timeframe, reenable_after duration, handled_errors =
[] of Exception, ignored_errors =
[] of Exception)
133 |
134 |
#
135 |
136 |
137 |
creates a CircuitBreaker instance with a specified error threshold, timeframe, breaker duration and optionally a number of ignored or handled errors
138 |
139 |
breaker = CircuitBreaker.new(
140 | threshold: 5, # % of errors before you want to trip the circuit
141 | timewindow: 60, # in s: anything older will be ignored in error_rate
142 | reenable_after: 300 # after x seconds, the breaker will allow executions again
143 | )
144 |
145 |
146 |
151 |
152 |
153 |
154 |
155 |
156 |
Instance Method Detail
157 |
158 |
159 |
160 |
161 | def
run(&block)
162 |
163 |
#
164 |
165 |
166 |
get's passed a block to watch for errors
167 | every error thrown inside your block counts towards the error rate
168 | once the threshold is surpassed, it starts throwing CircuitOpenExceptions
169 | you can catch these rrors and implement some fallback behaviour
170 |
171 |
begin
172 | breaker.run do
173 | my_rest_call()
174 | end
175 | rescue exc : CircuitOpenException
176 | log "happens to the best of us..."
177 | 42
178 | end
179 |
180 |
181 |
186 |
187 |
188 |
189 |
190 |
191 |
192 |
33 |
circuit_breaker 
34 |
35 |
Simple Implementation of the circuit breaker pattern in Crystal.
36 |
37 |
Given a certain error threshold, timeframe and timeout window, a breaker can be used to monitor criticial command executions. Circuit breakers are usually used to prevent unnecessary requests if a server ressource et al becomes unavailable. This protects the server from additional load and allows it to recover and relieves the client from requests that are doomed to fail.
38 |
39 |
Wrap API calls inside a breaker, if the error rate in a given time frame surpasses a certain threshold, all subsequent calls will fail for a given duration.
40 |
41 |
Installation
42 |
43 |
Add to your shard.yml
44 |
45 |
dependencies:
46 | circuit_breaker:
47 | github: tpei/circuit_breaker
48 | branch: master
49 |
50 |
and then install the library into your project with
51 |
52 |
$ crystal deps
53 |
54 |
Usage
55 |
56 |
Create a new breaker:
57 |
58 |
require "circuit_breaker"
59 |
60 | breaker = CircuitBreaker.new(
61 | threshold: 5, # % of errors before you want to trip the circuit
62 | timewindow: 60, # in s: anything older will be ignored in error_rate
63 | reenable_after: 300 # after x seconds, the breaker will allow executions again
64 | )
65 |
66 |
Then wrap whatever you like:
67 |
68 |
breaker.run do
69 | my_rest_call()
70 | end
71 |
72 |
The Breaker will open and throw an CircuitOpenException for all subsequent calls, once the threshold is reached. You can of course catch these exceptions and do whatever you want :D
73 |
74 |
begin
75 | breaker.run do
76 | my_rest_call()
77 | end
78 | rescue exc : CircuitOpenException
79 | log "happens to the best of us..."
80 | 42
81 | end
82 |
83 |
After the given reenable time, the circuit will transition to "half open". This will completely reset the circuit if the next execution succeeds, but reopen the circuit and reset the timer if the next execution fails.
84 |
85 |
If you are feeling really funky, you can also hand in exception classes to monitor. You might want to catch RandomRestError, but not ArgumentError, so do this:
86 |
87 |
breaker = CircuitBreaker.new(
88 | threshold: 5,
89 | timewindow: 60,
90 | reenable_after: 300,
91 | handled_errors: [RandomRestError.new]
92 | )
93 |
94 | breaker.run
95 | raise ArgumentError.new("won't count towards the error rate")
96 | end
97 |
98 |
Of course you can also add custom errors to ignore and count all others:
99 |
100 |
breaker = CircuitBreaker.new(
101 | threshold: 5,
102 | timewindow: 60,
103 | reenable_after: 300,
104 | ignored_errors: [ArgumentError.new]
105 | )
106 |
107 | breaker.run
108 | raise ArgumentError.new("won't count towards the error rate")
109 | end
110 |
111 |
Unfortunately this both won't match against exception subclasses just yet, so at the moment you have to specify the exact class to monitor and can't just use RestException to match every subclass like RestTimeoutException < RestException...
112 |
113 |
Thanks
114 |
115 |
Special thanks goes to Pedro Belo on whose ruby circuit breaker implementation (CB2) this is loosely based.
116 |