Skip to content
Resilience4j is a fault tolerance library designed for Java8 and functional programming
Java Groovy Kotlin
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Deleted examples folder Jul 22, 2019
gradle/wrapper Added fallbackMethod mechanism to resilience4j-ratpack May 17, 2019
resilience4j-all Removed deprecated methods and classes. (#512) Jun 28, 2019
resilience4j-annotations Added fixed threadpool bulkhead to spring (#474) May 30, 2019
resilience4j-bom introduce resilience4j bom Oct 18, 2018
resilience4j-bulkhead Remove javax.xml.ws.WebServiceException (#638) Sep 19, 2019
resilience4j-cache Remove javax.xml.ws.WebServiceException (#638) Sep 19, 2019
resilience4j-circuitbreaker Remove javax.xml.ws.WebServiceException (#638) Sep 19, 2019
resilience4j-circularbuffer Added Jdk 11 support (#424) Apr 15, 2019
resilience4j-consumer Remove javax.xml.ws.WebServiceException (#638) Sep 19, 2019
resilience4j-core Remove javax.xml.ws.WebServiceException (#638) Sep 19, 2019
resilience4j-documentation Remove javax.xml.ws.WebServiceException (#638) Sep 19, 2019
resilience4j-feign Tests speedup (#617) Sep 15, 2019
resilience4j-framework-common Issue #618: Expose config property to disable writable stack traces (#… Sep 17, 2019
resilience4j-kotlin Fixed sonar findings (#637) Sep 18, 2019
resilience4j-metrics Remove javax.xml.ws.WebServiceException (#638) Sep 19, 2019
resilience4j-micrometer Depending on the number of cpus, the default core threadpool size can… Sep 16, 2019
resilience4j-prometheus Fixed sonar findings (#637) Sep 18, 2019
resilience4j-ratelimiter Remove javax.xml.ws.WebServiceException (#638) Sep 19, 2019
resilience4j-ratpack Fixed sonar findings (#637) Sep 18, 2019
resilience4j-reactor Remove javax.xml.ws.WebServiceException (#638) Sep 19, 2019
resilience4j-retrofit Tests speedup (#617) Sep 15, 2019
resilience4j-retry Remove javax.xml.ws.WebServiceException (#638) Sep 19, 2019
resilience4j-rxjava2 Remove javax.xml.ws.WebServiceException (#638) Sep 19, 2019
resilience4j-spring-boot-common Fixed sonar findings Sep 18, 2019
resilience4j-spring-boot Tests speedup (#617) Sep 15, 2019
resilience4j-spring-boot2 Tests speedup (#617) Sep 15, 2019
resilience4j-spring-cloud-common Removed unused imports. Sep 18, 2019
resilience4j-spring-cloud Removed unused imports. Sep 18, 2019
resilience4j-spring-cloud2 Fixed bug in prometheus metrics publisher and increased code coverage ( Sep 15, 2019
resilience4j-spring Tests speedup (#617) Sep 15, 2019
resilience4j-test Remove javax.xml.ws.WebServiceException (#638) Sep 19, 2019
resilience4j-timelimiter Fixed sonar findings (#637) Sep 18, 2019
resilience4j-vertx Fixed sonar findings (#637) Sep 18, 2019
.gitignore Issue #268 and #291: Allow sharing of CircuitBreaker configurations a… Apr 24, 2019
.travis.yml Duration standardization in properties and duration support in spring… Jun 13, 2019
LICENSE.txt Initial commit Jun 3, 2015
README.adoc add overview and patterns to readme (#641) Sep 21, 2019
RELEASENOTES.adoc Updated release notes. Sep 13, 2019
azure-pipelines.yml Switch off unstable building agents Sep 14, 2019
build.gradle Updated version to 1.0.0-SNAPSHOT Sep 16, 2019
gradle.properties Modularization (#59) Mar 23, 2017
gradlew Refactored resilience4j-reactor and resilience4j-rxJava2 May 16, 2019
gradlew.bat Refactored resilience4j-reactor and resilience4j-rxJava2 May 16, 2019
grafana_dashboard.json Issue Fix #470. Update Prometheus query to evaluate as regex instead … May 25, 2019
libraries.gradle Issue #546: Added resilience4j-spring-cloud modules (#550) Sep 2, 2019
publishing.gradle Prepare release v0.14.0 Apr 5, 2019
settings.gradle Issue #546: Added resilience4j-spring-cloud modules (#550) Sep 2, 2019

README.adoc

Fault tolerance library designed for functional programming

Build Status Build Status Quality Gate Coverage download Apache License 2

Introduction

Resilience4j is a lightweight fault tolerance library inspired by Netflix Hystrix, but designed for Java 8 and functional programming. Lightweight, because the library only uses Vavr, which does not have any other external library dependencies. Netflix Hystrix, in contrast, has a compile dependency to Archaius which has many more external library dependencies such as Guava and Apache Commons Configuration.

Resilience4j provides higher-order functions (decorators) to enhance any functional interface, lambda expression or method reference with a Circuit Breaker, Rate Limiter, Retry or Bulkhead. You can stack more than one decorator on any functional interface, lambda expression or method reference. The advantage is that you have the choice to select the decorators you need and nothing else.

Supplier<String> supplier = () -> backendService.doSomething(param1, param2);

Supplier<String> decoratedSupplier = Decorators.ofSupplier(supplier)
  .withRetry(Retry.ofDefaults("name"))
  .withCircuitBreaker(CircuitBreaker.ofDefaults("name"))
  .withBulkhead(Bulkhead.ofDefaults("name"));

String result = Try.ofSupplier(decoratedSupplier)
  .recover(throwable -> "Hello from Recovery").get();

// When you don't want to decorate your lambda expression,
// but just execute it and protect the call by a CircuitBreaker.
String result = circuitBreaker.executeSupplier(supplier);

With Resilience4j you don’t have to go all-in, you can pick what you need.

Documentation

Setup and usage is described in our User Guide.

Overview

Resilience4j provides several core modules and add-on modules:

Core modules

  • resilience4j-circuitbreaker: Circuit breaking

  • resilience4j-ratelimiter: Rate limiting

  • resilience4j-bulkhead: Bulkheading

  • resilience4j-retry: Automatic retrying (sync and async)

Add-on modules

  • resilience4j-cache: Result caching

  • resilience4j-timelimiter: Timeout handling

  • resilience4j-retrofit: Retrofit adapter

  • resilience4j-feign: Feign adapter

  • resilience4j-consumer: Circular Buffer Event consumer

  • resilience4j-kotlin: Kotlin coroutines support

Frameworks modules

  • resilience4j-spring-boot: Spring Boot Starter

  • resilience4j-spring-boot2: Spring Boot 2 Starter

  • resilience4j-ratpack: Ratpack Starter

  • resilience4j-vertx: Vertx Future decorator

Reactive modules

  • resilience4j-rxjava2: Custom RxJava2 operators

  • resilience4j-reactor: Custom Spring Reactor operators

Metrics modules

  • resilience4j-micrometer: Micrometer Metrics exporter

  • resilience4j-metrics: Dropwizard Metrics exporter

  • resilience4j-prometheus: Prometheus Metrics exporter

Resilience patterns

Name Links Premise Slogan How does it mitigate?

Retry

overview, documentation

Many faults are transient and may self-correct after a short delay.

"Maybe it’s just a blip"

Allows configuring automatic retries.

Circuit Breaker

overview, documentation

When a system is seriously struggling, failing fast is better than making users/callers wait.
Protecting a faulting system from overload can help it recover.

"Stop doing it if it hurts",
"Give that system a break"

Breaks the circuit (blocks executions) for a period, when faults exceed some pre-configured threshold.

Time Limiter

Beyond a certain wait, a success result is unlikely.

"Don’t wait forever"

Guarantees the caller won’t have to wait beyond the timeout.

Bulkhead

overview, documentation

When a process faults, multiple failing calls backing up can easily swamp resource (eg. threads/CPU) in a host.
A faulting downstream system can also cause `backed-up' failing calls upstream.
Both risk a faulting process bringing down a wider system.

"One fault shouldn’t sink the whole ship"

Constrains the governed actions to a fixed-size resource pool, isolating their potential to affect others.

Cache

Some proportion of requests may be similar.

"You’ve asked that one before"

Provides a response from cache if known.
Stores responses automatically in cache, when first retrieved.

Fallback

overview

Things will still fail - plan what you will do when that happens.

"Degrade gracefully"

Defines an alternative value to be returned (or action to be executed) on failure.

Above table was based on Polly: resilience policies.

Spring Boot demo

Setup and usage in Spring Boot 2 is demonstrated here.

Usage examples

CircuitBreaker, Retry and Fallback

The following example shows how to decorate a lambda expression (Supplier) with a CircuitBreaker and how to retry the call at most 3 times when an exception occurs.
You can configure the wait interval between retries and also configure a custom backoff algorithm.
The example uses Vavr’s Try Monad to recover from an exception and invoke another lambda expression as a fallback, when even all retries have failed.

// Simulates a Backend Service
public interface BackendService {
    String doSomething();
}

// Create a CircuitBreaker (use default configuration)
CircuitBreaker circuitBreaker = CircuitBreaker.ofDefaults("backendName");
// Create a Retry with at most 3 retries and a fixed time interval between retries of 500ms
Retry retry = Retry.ofDefaults("backendName");

// Decorate your call to BackendService.doSomething() with a CircuitBreaker
Supplier<String> decoratedSupplier = CircuitBreaker
    .decorateSupplier(circuitBreaker, backendService::doSomething);

// Decorate your call with automatic retry
decoratedSupplier = Retry
    .decorateSupplier(retry, decoratedSupplier);

// Execute the decorated supplier and recover from any exception
String result = Try.ofSupplier(decoratedSupplier)
    .recover(throwable -> "Hello from Recovery").get();

// When you don't want to decorate your lambda expression,
// but just execute it and protect the call by a CircuitBreaker.
String result = circuitBreaker.executeSupplier(backendService::doSomething);

CircuitBreaker and RxJava2

The following example shows how to decorate an Observable by using the custom RxJava operator.

CircuitBreaker circuitBreaker = CircuitBreaker.ofDefaults("testName");
Observable.fromCallable(backendService::doSomething)
    .compose(CircuitBreakerOperator.of(circuitBreaker))
Note
Resilience4j also provides RxJava operators for RateLimiter, Bulkhead and Retry. Find out more in our User Guide

CircuitBreaker and Reactor

The following example shows how to decorate a Mono by using the custom Reactor operator.

CircuitBreaker circuitBreaker = CircuitBreaker.ofDefaults("testName");
Mono.fromCallable(backendService::doSomething)
    .compose(CircuitBreakerOperator.of(circuitBreaker))
Note
Resilience4j also provides Reactor operators for RateLimiter, Bulkhead and Retry. Find out more in our User Guide

RateLimiter

The following example shows how to restrict the calling rate of some method to be not higher than 1 req/sec.

// Create a custom RateLimiter configuration
RateLimiterConfig config = RateLimiterConfig.custom()
    .timeoutDuration(Duration.ofMillis(100))
    .limitRefreshPeriod(Duration.ofSeconds(1))
    .limitForPeriod(1)
    .build();
// Create a RateLimiter
RateLimiter rateLimiter = RateLimiter.of("backendName", config);

// Decorate your call to BackendService.doSomething()
Supplier<String> restrictedSupplier = RateLimiter
    .decorateSupplier(rateLimiter, backendService::doSomething);

// First call is successful
Try<String> firstTry = Try.ofSupplier(restrictedSupplier);
assertThat(firstTry.isSuccess()).isTrue();

// Second call fails, because the call was not permitted
Try<String> secondTry = Try.of(restrictedSupplier);
assertThat(secondTry.isFailure()).isTrue();
assertThat(secondTry.getCause()).isInstanceOf(RequestNotPermitted.class);

Bulkhead

The following example shows how to decorate a lambda expression with a Bulkhead. A Bulkhead can be used to limit the amount of parallel executions. This bulkhead abstraction should work well across a variety of threading and io models. It is based on a semaphore, and unlike Hystrix, does not provide "shadow" thread pool option.

// Create a custom Bulkhead configuration
BulkheadConfig config = BulkheadConfig.custom()
    .maxConcurrentCalls(150)
    .maxWaitTime(100)
    .build();

Bulkhead bulkhead = Bulkhead.of("backendName", config);

Supplier<String> supplier = Bulkhead
    .decorateSupplier(bulkhead, backendService::doSomething);

ThreadPoolBulkhead

The following example shows how to use a lambda expression with a ThreadPoolBulkhead which uses a bounded queue and a fixed thread pool.

// Create a custom ThreadPoolBulkhead configuration
ThreadPoolBulkheadConfig config = ThreadPoolBulkheadConfig.custom()
    .maxThreadPoolSize(10)
    .coreThreadPoolSize(2)
    .queueCapacity(20)
    .build();

ThreadPoolBulkhead bulkhead = ThreadPoolBulkhead.of("backendName", config);

// Decorate or execute immediately a lambda expression with a ThreadPoolBulkhead.
Supplier<CompletionStage<String>> supplier = ThreadPoolBulkhead
    .decorateSupplier(bulkhead, backendService::doSomething);

CompletionStage<String> execution = bulkhead
    .executeSupplier(backendService::doSomething);

Consume emitted events

CircuitBreaker, RateLimiter, Cache and Retry components emit a stream of events which can be consumed.

CircuitBreaker example below:

A CircuitBreakerEvent can be a state transition, a circuit breaker reset, a successful call, a recorded error or an ignored error. All events contains additional information like event creation time and processing duration of the call. If you want to consume events, you have to register an event consumer.

circuitBreaker.getEventPublisher()
    .onSuccess(event -> logger.info(...))
    .onError(event -> logger.info(...))
    .onIgnoredError(event -> logger.info(...))
    .onReset(event -> logger.info(...))
    .onStateTransition(event -> logger.info(...));
// Or if you want to register a consumer listening to all events, you can do:
circuitBreaker.getEventPublisher()
    .onEvent(event -> logger.info(...));

You can use RxJava or Spring Reactor Adapters to convert the EventPublisher into a Reactive Stream. The advantage of a Reactive Stream is that you can use RxJava’s observeOn operator to specify a different Scheduler that the CircuitBreaker will use to send notifications to its observers/consumers.

RxJava2Adapter.toFlowable(circuitBreaker.getEventPublisher())
    .filter(event -> event.getEventType() == Type.ERROR)
    .cast(CircuitBreakerOnErrorEvent.class)
    .subscribe(event -> logger.info(...))
Note
You can also consume events from RateLimiter, Bulkhead, Cache and Retry. Find out more in our User Guide

Companies who use Resilience4j

  • Deutsche Telekom (In an application with over 400 million request per day)

  • AOL (In an application with low latency requirements)

  • Netpulse (In system with 40+ integrations)

  • wescale.de (In a B2B integration platform)

  • Topia (In an HR application built with microservices architecture)

  • Auto Trader Group plc (UK’s largest digital automotive marketplace)

  • PlayStation Network (Platform backend)

License

Copyright 2019 Robert Winkler, Bohdan Storozhuk, Mahmoud Romeh and Dan Maas

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

You can’t perform that action at this time.