WARNING: This server provides a static reference view of the NetKernel documentation. Links to dynamic content do not work. For the best experience we recommend you install NetKernel and view the documentation in the live system .

Endpoint
Name:Circuit Breaker
Description:Implements the circuit breaker pattern to isolate failure of services
Id:mod.architecture.CircuitBreaker
Category:overlay

Circuit Breaker is an overlay. You must instantiate an instance of the overlay from its prototype, this will create a new instance within your application space.

Parameters

The mod.architecture.CircuitBreaker prototype has the following initialisation parameters:

NameRulesTypingDefaultDescription
configMandatoryIdentifier or XML(none)
configuration of the circuit breaker
spaceMandatorySpace(none)
A nested space definition which the overlay will delegate all requests in to.

Here is an auto-generated example of how to instantiate an instance of Circuit Breaker:

<overlay>
  <prototype>mod.architecture.CircuitBreaker</prototype>
  <config>configuration of the circuit breaker</config>
  <space>
    < !--wrapped space...-->
  </space>
</overlay>
Import Requirements

To use Circuit Breaker overlay you must import the module urn:com:ten60:netkernel:mod:architecture:

<import>
  <uri>urn:com:ten60:netkernel:mod:architecture</uri>
</import>

Description

The circuit breaker is a transparent overlay to protect an decouple a client from possible failure modes of a remote endpoint. Sometimes the failure of a single endpoint can cause a snowball effect leading to a chain of failures which can be hard to recover from. This can happen both upstream where, for example, an overloaded or slow to fail service might block dependent systems from failing or taking alternate action in a reasonable time. Downstream repeatedly calling a failing service might put unnecessary load on a database or other such system that might make recovery slower.

A circuit breaker detects failure of a service either as a timeout waiting for response or exception and then decide to trip. When a trip occurs the load is taken away from the underlying service and the breaker fails fast. Periodic re-testing of the service ensures that when it becomes functional again the breaker will be reset and requests will flow to it again.

Usage

The circuit breaker acts as a transparent overlay wrapping any endpoints within the enclosed space with the circuit breaker.

<space>
  <overlay>
    <prototype>mod.architecture.CircuitBreaker</prototype>
    <config>
      < !-- see config -->
    </config>
    <space>
      < !-- wrapped functionality -->
    </space>
  </overlay>
  <import>
    <uri>urn:com:ten60:netkernel:mod:architecture</uri>
  </import>
</space>

Configuration

<config>
  <timeoutPeriod>100</timeoutPeriod>
  <failCount>3</failCount>
  <retryPeriod>250</retryPeriod>
  <retryMultiplier>1.5</retryMultiplier>
  <retryMaxPeriod>5000</retryMaxPeriod>
  <failOnException>false</failOnException>
  <multipleBreakers>true</multipleBreakers>
  <statusResourceIdentifier>active:breakerState</statusResourceIdentifier>
  <statusRequest>
    <identifier>active:tripListener</identifier>
    <argument name="tripped">arg:tripped</argument>
    <argument name="endpoint">arg:endpoint</argument>
  </statusRequest>
</config>

Basic configuration

The timeoutPeriod tag determines how long the circuit breaker will wait for a response from a request. A value of 0 will mean the circuit breaker will not timeout waiting for a response. The default value is 0.

The failCount tag determines how many timeouts or exceptions must be thrown by requests passing through the circuit breaker before it trips. The default value is 1.

The retryPeriod tag determines how many milliseconds should elapse before retrying a single request to see if breaker should be reset. The default value is 1000.

The retryMultiplier tag specifies how the retry period increases after each successive failure causing exponential back-off. This must be a real number greater or equal to 1.0. The default value is 1.0, which mean the retry period remains constant.

The retryMaxPeriod tag places a limit on how much the retry period can increase. Once the retryMultiplier causes the the retry period to increase beyond this value it will be capped. By default the retryMaxPeriod is equal to retryPeriod.

The failOnException tag determines if exceptions count towards the tally of failures before the breaker trips. The value should be either true or false. The default value is true.

The multipleBreakers tag determines if the overlay embodies a single circuit breaker for all wrapped functionality or if multiple breakers should be created, one for each logical endpoint within the wrapped space. This is useful if the wrapped endpoints can fail independently. The value should be either true or false. The default value is false.

Status reporting

You can observe the status of the circuit breaker in the space explorer by looking at the details of the physical CircuitBreakerOverlay endpoint.

For programmatic access to the state you have two options. Firstly by specifying a statusResourceIdentifier the overlay can expose an additional endpoint which can be SOURCEd to obtain the circuit breaker state.

Secondly by specifying the statusRequest tag you can specify a declarative request that will be called by the circuit breaker when a breaker is tripped or reset. Both the tripped status and endpoint are available as argument to be passed to request as per the example above.