An implementation of the circuit breaker pattern for Vert.x
A Vert.x web handler to expose the circuit breaker to the Hystrix dasbboard.
Circuit breaker configuration options.
Circuit breaker states.
Future* exception thrown by your code * uncompleted futures (timeout) Operations guarded by a circuit breaker are intended to be non-blocking and asynchronous in order to benefit from the Vert.x execution model. == Using the vert.x circuit breaker To use the Vert.x Circuit Breaker, add the following dependency to the _dependencies_ section of your build descriptor: * Maven (in your `pom.xml`): [source,xml,subs="+attributes"] ----
examples.Examples#example1(io.vertx.core.Vertx)---- The executed block receives a
Futureobject as parameter, to denote the success or failure of the operation as well as the result. For example in the following example, the result is the output of a REST endpoint invocation: [source,$lang] ----
examples.Examples#example2(io.vertx.core.Vertx)---- The result of the operation is provided using the: * returned
Futurewhen calling `execute` methods * provided
Futurewhen calling the `executeAndReport` methods Optionally, you can provide a fallback which is executed when the circuit is open: [source,$lang] ----
examples.Examples#example3(io.vertx.core.Vertx)---- The fallback is called whenever the circuit is open, or if the
CircuitBreakerOptions.isFallbackOnFailure()is enabled. When a fallback is set, the result is using the output of the fallback function. The fallback function takes as parameter a
Throwableobject and returns an object of the expected type. The fallback can also be set on the
CircuitBreakerobject directly: [source,$lang] ----
examples.Examples#example4(io.vertx.core.Vertx)---- You can also specify how often the circuit breaker should try your code before failing with
CircuitBreakerOptions.setMaxRetries(int). If you set this to something higher than 0 your code gets executed several times before finally failing in the last execution. If the code succeeded in one of the retries your handler gets notified and any retries left are skipped. Retries are only supported when the circuit is closed. == Callbacks You can also configures callbacks invoked when the circuit is opened or closed: [source,$lang] ----
examples.Examples#example5(io.vertx.core.Vertx)---- You can also be notified when the circuit breaker decides to attempt to reset (half-open state). You can register such a callback with
CircuitBreaker.halfOpenHandler(io.vertx.core.Handler). == Event bus notification Every time the circuit state changes, an event is published on the event bus. The address on which the events are sent is configurable with
CircuitBreakerOptions.setNotificationAddress(java.lang.String). If `null` is passed to this method, the notifications are disabled. By default, the used address is `vertx.circuit-breaker`. Each event contains a Json Object with: * `state` : the new circuit breaker state (`OPEN`, `CLOSED`, `HALF_OPEN`) * `name` : the name of the circuit breaker * `failures` : the number of failures * `node` : the identifier of the node (`local` if Vert.x is not running in cluster mode) == The half-open state When the circuit is “open,” calls to the circuit breaker fail immediately, without any attempt to execute the real operation. After a suitable amount of time (configured from
CircuitBreakerOptions.setResetTimeout(long), the circuit breaker decides that the operation has a chance of succeeding, so it goes into the
half-openstate. In this state, the next call to the circuit breaker is allowed to execute the dangerous operation. Should the call succeed, the circuit breaker resets and returns to the
closedstate, ready for more routine operation. If this trial call fails, however, the circuit breaker returns to the
openstate until another timeout elapses. == Pushing circuit breaker metrics to the Hystrix Dashboard Netflix Hystrix comes with a dashboard to present the current state of the circuit breakers. The Vert.x circuit breakers can publish their metrics in order to be consumed by this Hystrix Dashboard. The Hystrix dashboard requires a SSE stream sending the metrics. This stream is provided by the
HystrixMetricHandlerVert.x Web Handler: [source,$lang] ----
examples.Examples#example7(io.vertx.core.Vertx)---- In the Hystrix Dashboard, configure the stream url like: `http://localhost:8080/metrics`. The dashboard now consumes the metrics from the Vert.x circuit breakers. Notice that the metrics are collected by the Vert.x Web handler using the event bus notifications. If you don't use the default notification address, you need to pass it when creating the metrics handler. [language, java] ---- == Using Netflix Hystrix https://github.com/Netflix/Hystrix[Hystrix] provides an implementation of the circuit breaker pattern. You can use Hystrix with Vert.x instead of this circuit breaker or in combination of. This section describes the tricks to use Hystrix in a vert.x application. First you would need to add the Hystrix dependency to your classpath or build descriptor. Refer to the Hystrix page for details. Then, you need to isolate the "protected" call in a `Command`. Once you have your command, you can execute it: [source, $lang] \----
examples.hystrix.HystrixExamples#exampleHystrix1()\---- However, the command execution is blocking, so have to call the command execution either in an `executeBlocking` block or in a worker verticle: [source, $lang] \----
examples.hystrix.HystrixExamples#exampleHystrix2(io.vertx.core.Vertx)\---- If you use the async support of Hystrix, be careful that callbacks are not called in a vert.x thread and you have to keep a reference on the context before the execution (with
Vertx.getOrCreateContext(), and in the callback, switch back to the event loop using
Vertx.runOnContext(io.vertx.core.Handler). Without this, you are loosing the Vert.x concurrency model and have to manage the synchronization and ordering yourself: [source, $lang] \----
Copyright © 2017. All rights reserved.