Circuit Breaker

code

docs

tests

The Circuit Breaker library provides a way to guard your application against faulty external systems (e.g. mail servers being down, web services being down). It is used by many Zest™ Extensions and Libraries.

There’s a couple of differences between this implementation and others seen on the net, but we’ve also heavily borrowed from others. The first difference is that we’ve not focused on performance at all. For some reason other implementations make a point about doing "atomic changes" with various tricks, to ensure good performance. Since this is used to guard access to external systems, where latencies range in milliseconds and up, that seems completely useless, so we’ve just put "synchronized" on all methods, which should be safe. "It works" is better than "it’s fast" for these types of things.

Second, other implementations have had really crude logic for what types of exceptions cause the circuit to break. The most crude is "all", more advanced ones allow exceptions that be excepted to be registered, but in real cases this is not enough. Case in point is JDBC exceptions where you want to fail on "connect exception" but not necessarily "invalid SQL syntax". So instead we’ve leveraged Specification from Core Functional API where you get to provide your own specification that can use any logic to determine whether a particular exception is ok or not.

Third, there’s a big focus on manageability through JMX. A circuitbreaker can be easily exposed in JMX as an MBean, where you can track service levels and see exception messages, and trip/enable circuit breakers.

Fourth, if an external system is unavailable due to a circuitbreaker tripping it should be possible to expose this to other Zest™ services. There is a standard implementation of the Availability interface that delegates to a circuit breaker and the Enabled configuration flag, which is what we’d suspect will be used in most cases where external systems are invoked.

Table 26. Artifact

Group ID	Artifact ID	Version
org.qi4j.library	org.qi4j.library.circuitbreaker	2.1

Direct usage

The CircuitBreaker can be used directly, even without using anything else from the Zest™ SDK.

Here is a code snippet that demonstrate how to create a CircuitBreaker and how it behave:

// Create a CircuitBreaker with a threshold of 3, a 250ms timeout, allowing IllegalArgumentExceptions
CircuitBreaker cb = new CircuitBreaker( 3, 250, CircuitBreakers.in( IllegalArgumentException.class ) );

  [...snip...]

// Service levels goes down but does not cause a trip
cb.throwable( new IOException() );

  [...snip...]

// Service level goes down and causes a trip
cb.throwable( new IOException() );
cb.throwable( new IOException() );

  [...snip...]

// Turn on the CB again
cb.turnOn();

  [...snip...]

// Service levels goes down and causes a trip
cb.throwable( new IOException() );
cb.throwable( new IOException() );
cb.throwable( new IOException() );

  [...snip...]

// Wait until timeout

  [...snip...]

// CircuitBreaker is back on

Service Circuit Breaker

As a facility you can make your Services extends AbstractBreakOnThrowable, set them a CircuitBreaker as MetaInfo during assembly and annotate methods with @BreaksCircuitOnThrowable. Doing this will :

add a circuit breaker accessor to the Service (CircuitBreaker getCircuitBreaker()) ;
allow exposition of the circuit breaker in JMX ;
update the circuit breaker on annotated methods invocation success and thrown exceptions using the BreakCircuitConcern.

Here is how to declare such a Service:

public void assemble( ModuleAssembly module )
        throws AssemblyException
{
    module.services( TestService.class ).setMetaInfo( new CircuitBreaker() );
}
  [...snip...]

public interface TestService
        extends AbstractBreakOnThrowable, ServiceComposite
{

    @BreaksCircuitOnThrowable
    int successfulMethod();

    @BreaksCircuitOnThrowable
    void throwingMethod();

      [...snip...]

}

Remember to annotate methods which when they throw throwables should cause circuit breakers to trip and go back on invocation success with the @BreaksCircuitOnThrowable annotation.

Exposing Service Circuit Breakers in JMX

To expose their circuit breaker in JMX, your Services using one must implement the ServiceCircuitBreaker interface. Note that if you already extends AbstractBreakOnThrowable you don’t need to do anything else as it already extends ServiceCircuitBreaker.

Here is how it goes:

public void assemble( ModuleAssembly module )
        throws AssemblyException
{
  [...snip...]

    // JMX Library
    module.importedServices( MBeanServer.class ).
        importedBy( MBeanServerImporter.class );
    // CircuitBreakers in JMX
    module.services( CircuitBreakerManagement.class ).
        instantiateOnStartup();
}

Interactive sample

A gradle task runSample is defined in this library as a shortcut to run a simple interactive example. You’ll need a MBean client to connect to the sample, VisualVM with its MBean plugin does the job. See Build System if you need some guidance.