Vert.x Circuit Breaker
Vert.x Circuit Breaker is an implementation of the Circuit Breaker pattern for Vert.x.
It keeps track of the number of failures and open the circuit when a threshold is reached. Optionally, a fallback is executed.
Supported failures are:
-
failures reported by your code in a
Future
-
exception thrown by your code
-
uncompleted futures (timeout)
Operations guarded by a circuit breaker are intended to by non-blocking and asynchronous in order to benefits 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
):
<dependency>
<groupId>io.vertx</groupId>
<artifactId>vertx-circuit-breaker</artifactId>
<version>3.3.0.CR2</version>
</dependency>
-
Gradle (in your
build.gradle
file):
compile 'io.vertx:vertx-circuit-breaker:3.3.0.CR2'
Using the circuit breaker
To use the circuit breaker you need to:
-
Create a circuit breaker, with the configuration you want (timeout, number of failure before opening the circuit)
-
Execute some code using the breaker
Here is an example:
CircuitBreaker breaker = CircuitBreaker.create("my-circuit-breaker", vertx,
new CircuitBreakerOptions()
.setMaxFailures(5) // number of failure before opening the circuit
.setTimeout(2000) // consider a failure if the operation does not succeed in time
.setFallbackOnFailure(true) // do we call the fallback on failure
.setResetTimeout(10000) // time spent in open state before attempting to re-try
);
breaker.execute(future -> {
// some code executing with the breaker
// the code reports failures or success on the given future.
// if this future is marked as failed, the breaker increased the
// number of failures
}).setHandler(ar -> {
// Get the operation result.
});
The executed block receives a Future
object 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:
CircuitBreaker breaker = CircuitBreaker.create("my-circuit-breaker", vertx,
new CircuitBreakerOptions().setMaxFailures(5).setTimeout(2000)
);
breaker.<String>execute(future -> {
vertx.createHttpClient().getNow(8080, "localhost", "/", response -> {
if (response.statusCode() != 200) {
future.fail("HTTP error");
} else {
response
.exceptionHandler(future::fail)
.bodyHandler(buffer -> {
future.complete(buffer.toString());
});
}
});
}).setHandler(ar -> {
// Do something with the result
});
The result of the operation is provided using the:
Optionally, you can provide a fallback executed when the circuit is open:
CircuitBreaker breaker = CircuitBreaker.create("my-circuit-breaker", vertx,
new CircuitBreakerOptions().setMaxFailures(5).setTimeout(2000)
);
breaker.executeWithFallback(
future -> {
vertx.createHttpClient().getNow(8080, "localhost", "/", response -> {
if (response.statusCode() != 200) {
future.fail("HTTP error");
} else {
response
.exceptionHandler(future::fail)
.bodyHandler(buffer -> {
future.complete(buffer.toString());
});
}
});
}, v -> {
// Executed when the circuit is opened
return "Hello";
})
.setHandler(ar -> {
// Do something with the result
});
The fallback is called whenever the circuit is open, or if the
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
Throwable
object and returned an object of the expected type.
The fallback can also be set on the CircuitBreaker
object directly:
CircuitBreaker breaker = CircuitBreaker.create("my-circuit-breaker", vertx,
new CircuitBreakerOptions().setMaxFailures(5).setTimeout(2000)
).fallback(v -> {
// Executed when the circuit is opened.
return "hello";
});
breaker.execute(
future -> {
vertx.createHttpClient().getNow(8080, "localhost", "/", response -> {
if (response.statusCode() != 200) {
future.fail("HTTP error");
} else {
response
.exceptionHandler(future::fail)
.bodyHandler(buffer -> {
future.complete(buffer.toString());
});
}
});
});
Callbacks
You can also configures callbacks invoked when the circuit is opened or closed:
CircuitBreaker breaker = CircuitBreaker.create("my-circuit-breaker", vertx,
new CircuitBreakerOptions().setMaxFailures(5).setTimeout(2000)
).openHandler(v -> {
System.out.println("Circuit opened");
}).closeHandler(v -> {
System.out.println("Circuit closed");
});
breaker.execute(
future -> {
vertx.createHttpClient().getNow(8080, "localhost", "/", response -> {
if (response.statusCode() != 200) {
future.fail("HTTP error");
} else {
// Do something with the response
future.complete();
}
});
});
You can also be notified when the circuit breaker decide to attempt to reset (half-open state). You can register
such as callback with halfOpenHandler
.
Event bus notification
Every time the circuit state changes, an event is published on the event bus. The address on which the event are
sent is configurable with
setNotificationAddress
. 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
is 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
setResetTimeout
, the circuit breaker decides that the
operation has a chance of succeeding, so it goes into the half-open
state. 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 closed
state, ready for more routine operation. If this trial call fails, however, the circuit
breaker returns to the open
state until another timeout elapses.
Using 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 to details. Them, you need to isolate the "protected" call in a Command
. Once you have your command, you
can execute it:
HystrixCommand<String> someCommand = getSomeCommandInstance();
String result = someCommand.execute();
However, the command execution is blocking, so have to call the command execution either in an executeBlocking
block or in a worker verticle:
HystrixCommand<String> someCommand = getSomeCommandInstance();
vertx.<String>executeBlocking(
future -> future.complete(someCommand.execute()),
ar -> {
// back on the event loop
String result = ar.result();
}
);
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 getOrCreateContext
,
and in the callback, switch back to the event loop using
runOnContext
. Without this, you are loosing the Vert.x
concurrency model and have to manage the synchronization and ordering yourself:
vertx.runOnContext(v -> {
Context context = vertx.getOrCreateContext();
HystrixCommand<String> command = getSomeCommandInstance();
command.observe().subscribe(result -> {
context.runOnContext(v2 -> {
// Back on context (event loop or worker)
String r = result;
});
});
});