Package com.linecorp.armeria.client.circuitbreaker


@NonNullByDefault package com.linecorp.armeria.client.circuitbreaker
Failure detection and fallback mechanism based on circuit breaker pattern.

Setup Client with Circuit Breaker

Example


 Iface helloClient =
     Clients.builder("tbinary+http://127.0.0.1:8080/hello")
            .decorator(CircuitBreakerClient.newDecorator(
                    CircuitBreaker.builder("hello").build()))
            .build(Iface.class);
 

A Unit of Failure Detection

You can specify a unit of failure detection from the following:
  • per remote service (as shown in the example above)
  • per method
  • per remote host
  • per remote host and method

Example


 // Setup with per-method failure detection
 AsyncIface helloClient =
     Clients.builder("tbinary+http://127.0.0.1:8080/hello")
            .decorator(CircuitBreakerClient.newPerMethodDecorator(
                    method -> CircuitBreaker.builder(method).build()))
            .build(AsyncIface.class);
 

Fallback

Once a failure is detected, A FailFastException is thrown from the client. You can write a fallback code by catching the exception.

Example


 try {
     helloClient.hello("line");
 } catch (TException e) {
     // error handling
 } catch (FailFastException e) {
    // fallback code
 }
 

Example in Async Client


 helloClient.hello("line", new AsyncMethodCallback() {
     public void onComplete(Object response) {
         // response handling
     }
     public void onError(Exception e) {
         if (e instanceof TException) {
             // error handling
         } else if (e instanceof FailFastException) {
             // fallback code
         }
     }
 });
 

Circuit States and Transitions

The circuit breaker provided by this package is implemented as a finite state machine consisting of the following states and transitions.

CLOSED

The initial state. All requests are sent to the remote service. If the failure rate exceeds the specified threshold, the state turns into OPEN.

OPEN

All requests fail immediately without calling the remote service. After the specified time, the state turns into HALF_OPEN.

HALF_OPEN

Only one trial request is sent at a time.
  • If it succeeds, the state turns into CLOSED.
  • If it fails, the state returns to OPEN.
  • If it doesn't complete within a certain time, another trial request will be sent again.

Circuit Breaker Configurations

The behavior of a circuit breaker can be modified via CircuitBreakerBuilder.

failureRateThreshold

The threshold of failure rate(= failure/total) to detect a remote service fault.

minimumRequestThreshold

The minimum number of requests within the time window necessary to detect a remote service fault.

circuitOpenWindow

The duration of OPEN state.

trialRequestInterval

The interval of trial request in HALF_OPEN state.

counterSlidingWindow

The time length of sliding window to accumulate the count of events.

counterUpdateInterval

The interval that a circuit breaker can see the latest count of events.

exceptionFilter

A filter that decides whether a circuit breaker should deal with a given error.