gh-giuseppe-trisciuoglio-developer-kit-developer-kit/skills/spring-boot-resilience4j/references/configuration-reference.md

Resilience4j Configuration Reference

Circuit Breaker Configuration

Complete Properties List

resilience4j:
  circuitbreaker:
    configs:
      default:
        registerHealthIndicator: true                              # Default: false
        slidingWindowType: COUNT_BASED                            # COUNT_BASED or TIME_BASED
        slidingWindowSize: 100                                    # Default: 100 (calls or seconds)
        minimumNumberOfCalls: 10                                  # Default: 100
        failureRateThreshold: 50                                  # Default: 50 (percentage)
        slowCallRateThreshold: 100                                # Default: 100 (percentage)
        slowCallDurationThreshold: 60s                            # Default: 60000ms
        waitDurationInOpenState: 60s                              # Default: 60000ms
        automaticTransitionFromOpenToHalfOpenEnabled: false       # Default: false
        permittedNumberOfCallsInHalfOpenState: 10                 # Default: 10
        maxWaitDurationInHalfOpenState: 0s                        # Default: 0 (unlimited)
        recordExceptions:
          - java.io.IOException
          - java.util.concurrent.TimeoutException
        ignoreExceptions:
          - java.lang.IllegalArgumentException
        eventConsumerBufferSize: 100                              # Default: 100
    instances:
      myService:
        baseConfig: default
        failureRateThreshold: 60

Circuit Breaker States

1. CLOSED: Normal operation, calls pass through
2. OPEN: Circuit is open, calls immediately fail with CallNotPermittedException
3. HALF_OPEN: Testing if service recovered, allows limited test calls
4. DISABLED: Circuit breaker disabled, all calls pass through
5. FORCED_OPEN: Manually forced to open state for emergency situations

Sliding Window Types

COUNT_BASED (Default)

• Aggregates outcome of last N calls
• Better for services with consistent traffic
• slidingWindowSize = number of calls to track

TIME_BASED

• Aggregates outcome of calls in last N seconds
• Better for services with variable traffic
• slidingWindowSize = time in seconds

Retry Configuration

Complete Properties List

resilience4j:
  retry:
    configs:
      default:
        maxAttempts: 3                                            # Default: 3
        waitDuration: 500ms                                       # Default: 500ms
        enableExponentialBackoff: false                           # Default: false
        exponentialBackoffMultiplier: 2                           # Default: 2
        exponentialMaxWaitDuration: 10s                           # Default: no limit
        enableRandomizedWait: false                               # Default: false
        randomizedWaitFactor: 0.5                                 # Default: 0.5
        retryExceptions:
          - java.io.IOException
          - org.springframework.web.client.ResourceAccessException
        ignoreExceptions:
          - java.lang.IllegalArgumentException
        failAfterMaxAttempts: false                               # Default: false
        eventConsumerBufferSize: 100                              # Default: 100
    instances:
      myService:
        baseConfig: default
        maxAttempts: 5

Exponential Backoff Example

waitDuration: 500ms
enableExponentialBackoff: true
exponentialBackoffMultiplier: 2.0
exponentialMaxWaitDuration: 10s

Attempt waits:

• Attempt 1: 500ms
• Attempt 2: 1000ms (500 × 2)
• Attempt 3: 2000ms (1000 × 2)
• Attempt 4: 4000ms (2000 × 2)
• Attempt 5: 8000ms (4000 × 2)
• Maximum: 10000ms

Rate Limiter Configuration

Complete Properties List

resilience4j:
  ratelimiter:
    configs:
      default:
        limitForPeriod: 50                                        # Default: 50
        limitRefreshPeriod: 500ns                                 # Default: 500ns
        timeoutDuration: 5s                                       # Default: 5s
        registerHealthIndicator: true                             # Default: false
        allowHealthIndicatorToFail: true                          # Default: false
    instances:
      myService:
        baseConfig: default
        limitForPeriod: 10
        limitRefreshPeriod: 1s

Common Rate Limit Patterns

10 requests per second

limitForPeriod: 10
limitRefreshPeriod: 1s
timeoutDuration: 0s           # Fail immediately if no permits

100 requests per minute

limitForPeriod: 100
limitRefreshPeriod: 1m
timeoutDuration: 500ms        # Wait up to 500ms for permit

5 requests per second with queuing

limitForPeriod: 5
limitRefreshPeriod: 1s
timeoutDuration: 2s           # Wait up to 2s for permit

Bulkhead Configuration

Semaphore Bulkhead

resilience4j:
  bulkhead:
    configs:
      default:
        maxConcurrentCalls: 25                                    # Default: 25
        maxWaitDuration: 0ms                                      # Default: 0
        eventConsumerBufferSize: 100                              # Default: 100
    instances:
      myService:
        baseConfig: default
        maxConcurrentCalls: 10
        maxWaitDuration: 100ms

Thread Pool Bulkhead

resilience4j:
  thread-pool-bulkhead:
    configs:
      default:
        maxThreadPoolSize: 4                                      # Default: Runtime.availableProcessors()
        coreThreadPoolSize: 2                                     # Default: Runtime.availableProcessors() - 1
        queueCapacity: 100                                        # Default: 100
        keepAliveDuration: 20ms                                   # Default: 20ms
        writableStackTraceEnabled: true                           # Default: true
    instances:
      myService:
        baseConfig: default
        maxThreadPoolSize: 8
        coreThreadPoolSize: 4
        queueCapacity: 200

Time Limiter Configuration

Complete Properties List

resilience4j:
  timelimiter:
    configs:
      default:
        timeoutDuration: 1s                                       # Default: 1s
        cancelRunningFuture: true                                 # Default: true
    instances:
      myService:
        baseConfig: default
        timeoutDuration: 3s

Annotation Reference

@CircuitBreaker

@CircuitBreaker(
    name = "serviceName",                    // Required: Instance name from config
    fallbackMethod = "fallbackMethodName"    // Optional: Fallback method name
)

// Fallback method signature
public String fallback(Long id, Exception ex) { }

@Retry

@Retry(
    name = "serviceName",                    // Required: Instance name from config
    fallbackMethod = "fallbackMethodName"    // Optional: Fallback method name
)

@RateLimiter

@RateLimiter(
    name = "serviceName",
    fallbackMethod = "fallbackMethodName"
)

@Bulkhead

@Bulkhead(
    name = "serviceName",
    fallbackMethod = "fallbackMethodName",
    type = Bulkhead.Type.SEMAPHORE              // SEMAPHORE or THREADPOOL
)

@TimeLimiter

@TimeLimiter(
    name = "serviceName",
    fallbackMethod = "fallbackMethodName"
)
// Works only with CompletableFuture<T> or reactive types (Mono<T>, Flux<T>)

Annotation Execution Order

When combining annotations on a method, execution order from outermost to innermost:

1. @Retry
2. @CircuitBreaker
3. @RateLimiter
4. @TimeLimiter
5. @Bulkhead
6. Actual method call

Exception Reference

Pattern	Exception	HTTP Status	Meaning
Circuit Breaker	CallNotPermittedException	503	Circuit is OPEN or FORCED_OPEN
Rate Limiter	RequestNotPermitted	429	No permits available
Bulkhead	BulkheadFullException	503	Bulkhead at capacity
Time Limiter	TimeoutException	408	Operation exceeded timeout

Programmatic Configuration

Circuit Breaker

CircuitBreakerConfig config = CircuitBreakerConfig.custom()
    .failureRateThreshold(50)
    .waitDurationInOpenState(Duration.ofSeconds(10))
    .slowCallDurationThreshold(Duration.ofSeconds(2))
    .permittedNumberOfCallsInHalfOpenState(3)
    .minimumNumberOfCalls(10)
    .slidingWindowType(CircuitBreakerConfig.SlidingWindowType.COUNT_BASED)
    .slidingWindowSize(100)
    .recordExceptions(IOException.class, TimeoutException.class)
    .ignoreExceptions(IllegalArgumentException.class)
    .build();

CircuitBreakerRegistry registry = CircuitBreakerRegistry.of(config);
CircuitBreaker circuitBreaker = registry.circuitBreaker("myService");

Retry

RetryConfig config = RetryConfig.custom()
    .maxAttempts(3)
    .waitDuration(Duration.ofMillis(500))
    .intervalFunction(IntervalFunction.ofExponentialBackoff(
        Duration.ofMillis(500),
        2.0
    ))
    .retryExceptions(IOException.class, TimeoutException.class)
    .ignoreExceptions(IllegalArgumentException.class)
    .build();

RetryRegistry registry = RetryRegistry.of(config);
Retry retry = registry.retry("myService");

Actuator Endpoints

Access monitoring endpoints when management endpoints are enabled:

Endpoint	Description
GET /actuator/circuitbreakers	List all circuit breakers and states
GET /actuator/circuitbreakerevents	List circuit breaker events
GET /actuator/retryevents	List retry events
GET /actuator/ratelimiters	List rate limiters
GET /actuator/bulkheads	List bulkhead status
GET /actuator/timelimiters	List time limiters
GET /actuator/metrics	Custom resilience metrics

Micrometer Metrics

Resilience4j exposes the following metrics:

Circuit Breaker Metrics

• resilience4j.circuitbreaker.calls{name, kind}
• resilience4j.circuitbreaker.state{name, state}
• resilience4j.circuitbreaker.failure.rate{name}
• resilience4j.circuitbreaker.slow.call.rate{name}

Retry Metrics

• resilience4j.retry.calls{name, kind}

Rate Limiter Metrics

• resilience4j.ratelimiter.available.permissions{name}
• resilience4j.ratelimiter.waiting_threads{name}

Bulkhead Metrics

• resilience4j.bulkhead.available.concurrent.calls{name}
• resilience4j.bulkhead.max.allowed.concurrent.calls{name}

Version Compatibility

Resilience4j	Spring Boot	Java	Spring Framework
2.2.x	3.x	17+	6.x
2.1.x	3.x	17+	6.x
2.0.x	2.7.x	8+	5.3.x
1.7.x	2.x	8+	5.x

References

• Resilience4j Official Documentation
• Spring Boot Integration Guide
• Micrometer Metrics Guide