circuitbox 1.1.1 → 2.0.0.pre4
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +5 -5
- data/README.md +53 -187
- data/lib/circuitbox/circuit_breaker/logger_messages.rb +31 -0
- data/lib/circuitbox/circuit_breaker.rb +134 -154
- data/lib/circuitbox/configuration.rb +51 -0
- data/lib/circuitbox/errors/error.rb +3 -2
- data/lib/circuitbox/errors/open_circuit_error.rb +3 -1
- data/lib/circuitbox/errors/service_failure_error.rb +5 -1
- data/lib/circuitbox/excon_middleware.rb +23 -30
- data/lib/circuitbox/faraday_middleware.rb +43 -63
- data/lib/circuitbox/memory_store/container.rb +30 -0
- data/lib/circuitbox/memory_store/monotonic_time.rb +13 -0
- data/lib/circuitbox/memory_store.rb +85 -0
- data/lib/circuitbox/notifier/active_support.rb +19 -0
- data/lib/circuitbox/notifier/null.rb +13 -0
- data/lib/circuitbox/timer.rb +51 -0
- data/lib/circuitbox/version.rb +3 -1
- data/lib/circuitbox.rb +14 -54
- metadata +106 -117
- data/.gitignore +0 -20
- data/.ruby-version +0 -1
- data/.travis.yml +0 -9
- data/Gemfile +0 -6
- data/Rakefile +0 -30
- data/benchmark/circuit_store_benchmark.rb +0 -114
- data/circuitbox.gemspec +0 -48
- data/lib/circuitbox/notifier.rb +0 -34
- data/test/circuit_breaker_test.rb +0 -436
- data/test/circuitbox_test.rb +0 -45
- data/test/excon_middleware_test.rb +0 -131
- data/test/faraday_middleware_test.rb +0 -175
- data/test/integration/circuitbox_cross_process_open_test.rb +0 -56
- data/test/integration/faraday_middleware_test.rb +0 -78
- data/test/integration_helper.rb +0 -48
- data/test/notifier_test.rb +0 -21
- data/test/service_failure_error_test.rb +0 -23
- data/test/test_helper.rb +0 -15
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
|
-
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
2
|
+
SHA256:
|
3
|
+
metadata.gz: fb89d6ef46d73dfa35e7c43181112309aa524979ec1285688cc8cebf8d781bd4
|
4
|
+
data.tar.gz: 735c23115ea5127923c05b84d5b6cfe64193521bcd751639cc6ceab32c6b97ce
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: a29d10725e8a1a36eec12985681cd66b7c2b3303cb996bfe72226674230d7c8ef38b02bb5731665edd49c7922b2a9f0072434a2ab33da7f64713875415071420
|
7
|
+
data.tar.gz: 9a165096e2b0e5fe484c433284a3c0b6658f4b880552602cb57b22fcf3ea540302b3d3a0910b31b8f3e1938259ca6394faefd3bffffc6c40bf3104d8d02564ec
|
data/README.md
CHANGED
@@ -1,8 +1,8 @@
|
|
1
1
|
# Circuitbox
|
2
2
|
|
3
|
-
|
3
|
+
![Tests](https://github.com/yammer/circuitbox/workflows/Tests/badge.svg) [![Gem Version](https://badge.fury.io/rb/circuitbox.svg)](https://badge.fury.io/rb/circuitbox)
|
4
4
|
|
5
|
-
Circuitbox is a Ruby circuit breaker gem. It protects your application from failures of
|
5
|
+
Circuitbox is a Ruby circuit breaker gem. It protects your application from failures of its service dependencies. It wraps calls to external services and monitors for failures in one minute intervals. Once more than 10 requests have been made with a 50% failure rate, Circuitbox stops sending requests to that failing service for one minute. This helps your application gracefully degrade.
|
6
6
|
Resources about the circuit breaker pattern:
|
7
7
|
* [http://martinfowler.com/bliki/CircuitBreaker.html](http://martinfowler.com/bliki/CircuitBreaker.html)
|
8
8
|
* [https://github.com/Netflix/Hystrix/wiki/How-it-Works#CircuitBreaker](https://github.com/Netflix/Hystrix/wiki/How-it-Works#CircuitBreaker)
|
@@ -10,13 +10,13 @@ Resources about the circuit breaker pattern:
|
|
10
10
|
## Usage
|
11
11
|
|
12
12
|
```ruby
|
13
|
-
Circuitbox
|
13
|
+
Circuitbox.circuit(:your_service, exceptions: [Net::ReadTimeout]) do
|
14
14
|
Net::HTTP.get URI('http://example.com/api/messages')
|
15
15
|
end
|
16
16
|
```
|
17
17
|
|
18
18
|
Circuitbox will return nil for failed requests and open circuits.
|
19
|
-
If your HTTP client has
|
19
|
+
If your HTTP client has its own conditions for failure, you can pass an `exceptions` option.
|
20
20
|
|
21
21
|
```ruby
|
22
22
|
class ExampleServiceClient
|
@@ -25,53 +25,75 @@ class ExampleServiceClient
|
|
25
25
|
end
|
26
26
|
|
27
27
|
def http_get
|
28
|
-
circuit.run do
|
28
|
+
circuit.run(circuitbox_exceptions: false) do
|
29
29
|
Zephyr.new("http://example.com").get(200, 1000, "/api/messages")
|
30
30
|
end
|
31
31
|
end
|
32
32
|
end
|
33
33
|
```
|
34
34
|
|
35
|
-
Using the `run
|
35
|
+
Using the `run` method will throw an exception when the circuit is open or the underlying service fails.
|
36
36
|
|
37
37
|
```ruby
|
38
38
|
def http_get
|
39
|
-
circuit.run
|
39
|
+
circuit.run do
|
40
40
|
Zephyr.new("http://example.com").get(200, 1000, "/api/messages")
|
41
41
|
end
|
42
42
|
end
|
43
43
|
```
|
44
44
|
|
45
|
+
## Global Configuration
|
46
|
+
Circuitbox has defaults for circuit_store, notifier, and logger.
|
47
|
+
This can be configured through ```Circuitbox.configure```.
|
48
|
+
The circuit cache used by ```Circuitbox.circuit``` will be cleared after running ```Circuitbox.configure```.
|
49
|
+
This means when accessing the circuit through ```Circuitbox.circuit``` any custom configuration options should always be given.
|
50
|
+
|
51
|
+
Any circuit created manually through ```Circuitbox::CircuitBreaker``` before updating the configuration
|
52
|
+
will need to be recreated to pick up the new defaults.
|
53
|
+
|
54
|
+
```ruby
|
55
|
+
Circuitbox.configure do |config|
|
56
|
+
config.default_circuit_store = Circuitbox::MemoryStore.new
|
57
|
+
config.default_notifier = Circuitbox::Notifier::Null.new
|
58
|
+
config.default_logger = Rails.logger
|
59
|
+
end
|
60
|
+
```
|
61
|
+
|
45
62
|
|
46
|
-
## Configuration
|
63
|
+
## Per-Circuit Configuration
|
47
64
|
|
48
65
|
```ruby
|
49
66
|
class ExampleServiceClient
|
50
67
|
def circuit
|
51
68
|
Circuitbox.circuit(:your_service, {
|
69
|
+
# exceptions circuitbox tracks for counting failures (required)
|
52
70
|
exceptions: [YourCustomException],
|
53
71
|
|
54
72
|
# seconds the circuit stays open once it has passed the error threshold
|
55
73
|
sleep_window: 300,
|
56
|
-
|
74
|
+
|
57
75
|
# length of interval (in seconds) over which it calculates the error rate
|
58
76
|
time_window: 60,
|
59
77
|
|
60
|
-
# number of requests within `time_window` seconds before it calculates error rates
|
78
|
+
# number of requests within `time_window` seconds before it calculates error rates (checked on failures)
|
61
79
|
volume_threshold: 10,
|
62
80
|
|
63
81
|
# the store you want to use to save the circuit state so it can be
|
64
82
|
# tracked, this needs to be Moneta compatible, and support increment
|
65
|
-
|
83
|
+
# this overrides what is set in the global configuration
|
84
|
+
cache: Circuitbox::MemoryStore.new,
|
66
85
|
|
67
|
-
# exceeding this rate will open the circuit
|
86
|
+
# exceeding this rate will open the circuit (checked on failures)
|
68
87
|
error_threshold: 50,
|
69
88
|
|
70
|
-
# seconds before the circuit times out
|
71
|
-
timeout_seconds: 1
|
72
|
-
|
73
89
|
# Logger to use
|
74
|
-
|
90
|
+
# This overrides what is set in the global configuration
|
91
|
+
logger: Logger.new(STDOUT),
|
92
|
+
|
93
|
+
# Customized notifier
|
94
|
+
# overrides the default
|
95
|
+
# this overrides what is set in the global configuration
|
96
|
+
notifier: Notifier.new
|
75
97
|
})
|
76
98
|
end
|
77
99
|
end
|
@@ -81,29 +103,26 @@ You can also pass a Proc as an option value which will evaluate each time the ci
|
|
81
103
|
|
82
104
|
```ruby
|
83
105
|
Circuitbox.circuit(:yammer, {
|
84
|
-
sleep_window: Proc.new { Configuration.get(:sleep_window) }
|
106
|
+
sleep_window: Proc.new { Configuration.get(:sleep_window) },
|
107
|
+
exceptions: [Net::ReadTimeout]
|
85
108
|
})
|
86
109
|
```
|
87
110
|
|
88
111
|
## Circuit Store (:cache)
|
89
112
|
|
90
113
|
Holds all the relevant data to trip the circuit if a given number of requests
|
91
|
-
fail in a specified period of time.
|
92
|
-
[Moneta](https://github.com/minad/moneta)
|
93
|
-
|
94
|
-
|
95
|
-
|
96
|
-
-
|
114
|
+
fail in a specified period of time. Circuitbox also supports
|
115
|
+
[Moneta](https://github.com/minad/moneta). As moneta is not a dependency of circuitbox
|
116
|
+
it needs to be loaded prior to use. There are a lot of moneta stores to choose from but
|
117
|
+
some pre-requisits need to be satisfied first:
|
118
|
+
|
119
|
+
- Needs to support increment, this is true for most but not all available stores.
|
120
|
+
- Needs to support expiry.
|
121
|
+
- Needs to support concurrent access if you share them. For example sharing a
|
97
122
|
KyotoCabinet store across process fails because the store is single writer
|
98
123
|
multiple readers, and all circuits sharing the store need to be able to write.
|
99
124
|
|
100
125
|
|
101
|
-
## Monitoring & Statistics
|
102
|
-
|
103
|
-
You can also run `rake circuits:stats SERVICE={service_name}` to see successes, failures and opened circuits.
|
104
|
-
Add `PARTITION={partition_key}` to see the circuit for a particular partition.
|
105
|
-
The stats are aggregated into 1 minute intervals.
|
106
|
-
|
107
126
|
## Notifications
|
108
127
|
|
109
128
|
circuitbox use ActiveSupport Notifications.
|
@@ -123,7 +142,7 @@ ActiveSupport::Notifications.subscribe('circuit_close') do |name, start, finish,
|
|
123
142
|
circuit_name = payload[:circuit]
|
124
143
|
Rails.logger.info("Close circuit for: #{circuit_name}")
|
125
144
|
end
|
126
|
-
|
145
|
+
```
|
127
146
|
|
128
147
|
**generate metrics:**
|
129
148
|
|
@@ -142,9 +161,7 @@ end
|
|
142
161
|
|
143
162
|
`payload[:gauge]` can be:
|
144
163
|
|
145
|
-
- `
|
146
|
-
- `success_count`
|
147
|
-
- `error_rate`
|
164
|
+
- `runtime` # runtime will only be notified when circuit is closed and block is successfully executed.
|
148
165
|
|
149
166
|
**warnings:**
|
150
167
|
in case of misconfiguration, circuitbox will fire a circuitbox_warning
|
@@ -159,77 +176,6 @@ end
|
|
159
176
|
|
160
177
|
```
|
161
178
|
|
162
|
-
### Multi process Circuits
|
163
|
-
|
164
|
-
`circuit_store` is backed by [Moneta](https://github.com/minad/moneta) which
|
165
|
-
supports multiple backends. This can be configured by passing `cache:
|
166
|
-
Moneta.new(:PStore, file: "myfile.store")` to use for example the built in
|
167
|
-
PStore ruby library for persisted store, which can be shared cross process.
|
168
|
-
|
169
|
-
Depending on your requirements different stores can make sense, see the
|
170
|
-
benchmarks and [moneta
|
171
|
-
feature](https://github.com/minad/moneta#backend-feature-matrix) matrix for
|
172
|
-
details.
|
173
|
-
|
174
|
-
```
|
175
|
-
user system total real
|
176
|
-
memory: 1.440000 0.140000 1.580000 ( 1.579244)
|
177
|
-
lmdb: 4.330000 3.280000 7.610000 ( 13.086398)
|
178
|
-
pstore: 23.680000 4.350000 28.030000 ( 28.094312)
|
179
|
-
daybreak: 2.270000 0.450000 2.720000 ( 2.626748)
|
180
|
-
```
|
181
|
-
|
182
|
-
You can run the benchmarks yourself by running `rake benchmark`.
|
183
|
-
|
184
|
-
### Memory
|
185
|
-
|
186
|
-
An in memory store, which is local to the process. This is not threadsafe so it
|
187
|
-
is not useable with multithreaded webservers for example. It is always going to
|
188
|
-
be the fastest option if no multi-process or thread is required, like in
|
189
|
-
development on Webbrick.
|
190
|
-
|
191
|
-
This is the default.
|
192
|
-
|
193
|
-
```ruby
|
194
|
-
Circuitbox.circuit :identifier, cache: Moneta.new(:Memory)
|
195
|
-
```
|
196
|
-
|
197
|
-
### LMDB
|
198
|
-
|
199
|
-
An persisted directory backed store, which is thread and multi process safe.
|
200
|
-
depends on the `lmdb` gem. It is slower than Memory or Daybreak, but can be
|
201
|
-
used in multi thread and multi process environments like like Puma.
|
202
|
-
|
203
|
-
```ruby
|
204
|
-
require "lmdb"
|
205
|
-
Circuitbox.circuit :identifier, cache: Moneta.new(:LMDB, dir: "./", db: "mydb")
|
206
|
-
```
|
207
|
-
|
208
|
-
### PStore
|
209
|
-
|
210
|
-
An persisted file backed store, which comes with the ruby
|
211
|
-
[stdlib](http://ruby-doc.org/stdlib-2.3.0/libdoc/pstore/rdoc/PStore.html). It
|
212
|
-
has no external dependecies and works on every ruby implementation. Due to it
|
213
|
-
being file backed it is multi process safe, good for development using Unicorn.
|
214
|
-
|
215
|
-
```ruby
|
216
|
-
Circuitbox.circuit :identifier, cache: Moneta.new(:PStore, file: "db.pstore")
|
217
|
-
```
|
218
|
-
|
219
|
-
### Daybreak
|
220
|
-
|
221
|
-
Persisted, file backed key value store in pure ruby. It is process safe and
|
222
|
-
outperforms most other stores in circuitbox. This is recommended for production
|
223
|
-
use with Unicorn. It depends on the `daybreak` gem.
|
224
|
-
|
225
|
-
```ruby
|
226
|
-
require "daybreak"
|
227
|
-
Circuitbox.circuit :identifier, cache: Moneta.new(:Daybreak, file: "db.daybreak", expires: true)
|
228
|
-
```
|
229
|
-
|
230
|
-
It is important for the store to have
|
231
|
-
[expires](https://github.com/minad/moneta#backend-feature-matrix) support.
|
232
|
-
|
233
179
|
## Faraday
|
234
180
|
|
235
181
|
Circuitbox ships with [Faraday HTTP client](https://github.com/lostisland/faraday) middleware.
|
@@ -253,13 +199,6 @@ end
|
|
253
199
|
By default the Faraday middleware returns a `503` response when the circuit is
|
254
200
|
open, but this as many other things can be configured via middleware options
|
255
201
|
|
256
|
-
* `exceptions` pass a list of exceptions for the Circuitbreaker to catch,
|
257
|
-
defaults to Timeout and Request failures
|
258
|
-
|
259
|
-
```ruby
|
260
|
-
c.use Circuitbox::FaradayMiddleware, exceptions: [Faraday::Error::TimeoutError]
|
261
|
-
```
|
262
|
-
|
263
202
|
* `default_value` value to return for open circuits, defaults to 503 response
|
264
203
|
wrapping the original response given by the service and stored as
|
265
204
|
`original_response` property of the returned 503, this can be overwritten
|
@@ -268,9 +207,7 @@ c.use Circuitbox::FaradayMiddleware, exceptions: [Faraday::Error::TimeoutError]
|
|
268
207
|
* a `lambda` which is passed the `original_response` and `original_error`.
|
269
208
|
`original_response` will be populated if Faraday returns an error response,
|
270
209
|
`original_error` will be populated if an error was thrown before Faraday
|
271
|
-
returned a response.
|
272
|
-
only passed `original_response`. This use is deprecated and will be removed
|
273
|
-
in the next major version.)
|
210
|
+
returned a response.
|
274
211
|
|
275
212
|
```ruby
|
276
213
|
c.use Circuitbox::FaradayMiddleware, default_value: lambda { |response, error| ... }
|
@@ -282,15 +219,9 @@ c.use Circuitbox::FaradayMiddleware, default_value: lambda { |response, error| .
|
|
282
219
|
c.use Circuitbox::FaradayMiddleware, identifier: "service_name_circuit"
|
283
220
|
```
|
284
221
|
|
285
|
-
* `circuit_breaker_run_options` options passed to the circuit run method, see
|
286
|
-
the main circuitbreaker for those.
|
287
|
-
|
288
|
-
```ruby
|
289
|
-
conn.get("/api", circuit_breaker_run_options: {})
|
290
|
-
```
|
291
|
-
|
292
222
|
* `circuit_breaker_options` options to initialize the circuit with defaults to
|
293
|
-
`{
|
223
|
+
`{ exceptions: Circuitbox::FaradayMiddleware::DEFAULT_EXCEPTIONS }`.
|
224
|
+
Accepts same options as Circuitbox:CircuitBreaker#new
|
294
225
|
|
295
226
|
```ruby
|
296
227
|
c.use Circuitbox::FaradayMiddleware, circuit_breaker_options: {}
|
@@ -303,71 +234,6 @@ c.use Circuitbox::FaradayMiddleware, circuit_breaker_options: {}
|
|
303
234
|
c.use Circuitbox::FaradayMiddleware, open_circuit: lambda { |response| response.status >= 500 }
|
304
235
|
```
|
305
236
|
|
306
|
-
## CHANGELOG
|
307
|
-
### v1.1.0
|
308
|
-
- ruby 2.2 support [#58](https://github.com/yammer/circuitbox/pull/58)
|
309
|
-
- configurable logger [#58](https://github.com/yammer/circuitbox/pull/58)
|
310
|
-
|
311
|
-
### v1.0.3
|
312
|
-
- fix timeout issue for default configuration, as default `:Memory` adapter does
|
313
|
-
not natively support expires, we need to actually load it on demand.
|
314
|
-
- fix memoization of `circuit_breaker_options` not actually doing memoization in
|
315
|
-
`excon` and `faraday` middleware.
|
316
|
-
|
317
|
-
### v1.0.2
|
318
|
-
- Fix timeout issue [#51](https://github.com/yammer/circuitbox/issues/51)
|
319
|
-
[sebastian-juliu](https://github.com/sebastian-julius)
|
320
|
-
|
321
|
-
### v1.0.1
|
322
|
-
- Fix Rails integration, as version 1.0.0 removed the rails tasks integration, but missed
|
323
|
-
removing the related railtie.
|
324
|
-
|
325
|
-
### v1.0.0
|
326
|
-
- support for cross process circuitbreakers by swapping the circuitbreaker store for a
|
327
|
-
`Moneta` supported key value store.
|
328
|
-
- Change `FaradayMiddleware` default behaviour to not open on `4xx` errors but just on `5xx`
|
329
|
-
server errors and connection errors
|
330
|
-
- Remove stat store, which was largely unused
|
331
|
-
|
332
|
-
### v0.11.0
|
333
|
-
- fix URI require missing (https://github.com/yammer/circuitbox/pull/42 @gottfrois)
|
334
|
-
- configurable circuitbox store backend via Moneta supporting multi process circuits
|
335
|
-
|
336
|
-
### v0.10.4
|
337
|
-
- Issue #39, keep the original backtrace for the wrapped exception around when
|
338
|
-
re-raising a Circuitbox::Error
|
339
|
-
|
340
|
-
### v0.10.3
|
341
|
-
- Circuitbox::ServiceFailureError wraps the original exception that was raised.
|
342
|
-
The behaviour for to_s wasn't exposing this information and was returning the
|
343
|
-
name of class "Circuitbox::ServiceFailureError". Change the behaviour for to_s
|
344
|
-
to indicate this exception is a wrapper around the original exception.
|
345
|
-
[sherrry](https://github.com/sherrry)
|
346
|
-
|
347
|
-
### v0.10.2
|
348
|
-
- Faraday middleware passes two arguments to the `default_value` callback, not
|
349
|
-
just one. First argument is still the error response from Faraday if there is
|
350
|
-
one. Second argument is the exception that caused the call to fail if it
|
351
|
-
failed before Faraday returned a response. Old behaviour is preserved if you
|
352
|
-
pass a lambda that takes just one argument, but this is deprecated and will be
|
353
|
-
removed in the next version of Circuitbox.
|
354
|
-
[dwaller](https://github.com/dwaller)
|
355
|
-
|
356
|
-
### v0.10.1
|
357
|
-
- [Documentation fix](https://github.com/yammer/circuitbox/pull/29) [chiefcll](https://github.com/chiefcll)
|
358
|
-
- [Faraday middleware fix](https://github.com/yammer/circuitbox/pull/30) [chiefcll](https://github.com/chiefcll)
|
359
|
-
|
360
|
-
### v0.10
|
361
|
-
- configuration option for faraday middleware for what should be considered to open the circuit [enrico-scalavio](https://github.com/enrico-scalavino)
|
362
|
-
- fix for issue 16, support of in_parallel requests in faraday middlware which were opening the circuit.
|
363
|
-
- deprecate the __run_option__ `:storage_key`
|
364
|
-
|
365
|
-
### v0.9
|
366
|
-
- add `run!` method to raise exception on circuit open and service
|
367
|
-
|
368
|
-
### v0.8
|
369
|
-
- Everything prior to keeping the change log
|
370
|
-
|
371
237
|
## Installation
|
372
238
|
|
373
239
|
Add this line to your application's Gemfile:
|
@@ -0,0 +1,31 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
|
3
|
+
class Circuitbox
|
4
|
+
class CircuitBreaker
|
5
|
+
module LoggerMessages
|
6
|
+
def circuit_skipped_message
|
7
|
+
@circuit_skipped_message ||= "[CIRCUIT] #{service}: skipped"
|
8
|
+
end
|
9
|
+
|
10
|
+
def circuit_running_message
|
11
|
+
@circuit_running_message ||= "[CIRCUIT] #{service}: running"
|
12
|
+
end
|
13
|
+
|
14
|
+
def circuit_success_message
|
15
|
+
@circuit_success_message ||= "[CIRCUIT] #{service}: success"
|
16
|
+
end
|
17
|
+
|
18
|
+
def circuit_failure_message
|
19
|
+
@circuit_failure_message ||= "[CIRCUIT] #{service}: failure"
|
20
|
+
end
|
21
|
+
|
22
|
+
def circuit_opened_message
|
23
|
+
@circuit_opened_message ||= "[CIRCUIT] #{service}: opened"
|
24
|
+
end
|
25
|
+
|
26
|
+
def circuit_closed_message
|
27
|
+
@circuit_closed_message ||= "[CIRCUIT] #{service}: closed"
|
28
|
+
end
|
29
|
+
end
|
30
|
+
end
|
31
|
+
end
|