Utilities for web service resilience. Java 1.7+.

For questions and support please contact [email protected]

• Dependency
• Circuit Breaker
  • Operation
  • Configuration
    • Parameters

<dependency>
    <groupId>com.mercadolibre.resilience</groupId>
    <artifactId>resilience-core</artifactId>
    <version>0.0.5</version>
</dependency>

You can find it in our repo

<repository>
	<id>java-circuit-breaker-mvn-repo</id>
	<url>https://raw.github.com/mercadolibre/java-circuit-breaker/mvn-repo/</url>
	<snapshots>
	    <enabled>true</enabled>
	    <updatePolicy>always</updatePolicy>
	</snapshots>
</repository>

A circuit breaker is intended to be placed between an app and an external service, to be opened automatically upon service malfunction and later close again, based on predefined operational metrics.

This is useful to return quickly a response (partial or failure) in case of known external services shortage, and to prevent unnecessary overload to these services which probably difficult their recovery procedure.

An instance of CircuitBreaker begins its operation in closed state, and for each request that goes through it, counts a success or failure, based on user defined parameters.

It groups these metrics in fixed time width buckets. Upon rolling of a bucket, it recalculates a service score as a weighted moving average, which is compared against a user predefined minimum acceptable score.

If the calculated score is less than the user defined one, circuit is open for a fixed amount of time and every request will get a RejectedExecutionException.

When the open window is elapsed, the circuit breaker closes again in try mode, in which it'll check for a definite amount of time whether the backend service is normal again. In this case, it'll resume normal operation, otherwise it'll open and restart this procedure.

Therefore, a typical breaker cycle shall look as this:

We provide a factory class CircuitBreakers to make breaker creation easier. You can choose between two strategies for score calculation: fixed and exponential.

Using a fixed strategy means you must provide and array of bucket weights, from newer to older.

An exponential strategy weights samples with a decreasing exponential function. You must provide a number between 0 and 1, for the exponential base.

There are many parameters concerning the circuit breaker itself, independent of score strategy, which are detailed as follows

• interval: amount of time in ms the breaker should remain open after triggered.
• tryWindow: amount of time in ms the breaker should check backend service after interval is elapsed. It should allow al least a full evaluation window (buckets*bucketWidthMs).
• buckets: Amount of buckets to be considered for a score evaluation window
• bucketWidthMs: With of each bucket in ms.
• minScore: Minimum acceptable score to remain closed. Should be a number between 0 and 1.
• staleInterval: Amount expressed as bucket count after which a bucket is to be considered staled and not taken into account for score calculation. A staleInterval of 10 and a bucketWidthMs of 2 means that every bucket older than 20ms before actual time will be discarded.
• minMeasures: Minimal amount of measures for a bucket to be considered eligible for score evaluation.