Spring Boot Configuration

resilience4j:
  circuitbreaker:
    tags:                                       # added to every Micrometer meter of this module
      team: bookshelf
    circuitBreakerAspectOrder: 2147483643       # Ordered.LOWEST_PRECEDENCE - 4
    metrics:
      enabled: true
      legacy:
        enabled: false
    configs:
      default:
        registerHealthIndicator: false          # Boot only
        allowHealthIndicatorToFail: false       # Boot only
        eventConsumerBufferSize: 100            # Boot only
        slidingWindowType: COUNT_BASED
        slidingWindowSize: 100
        minimumNumberOfCalls: 100
        failureRateThreshold: 50
        slowCallRateThreshold: 100
        slowCallDurationThreshold: 60s
        waitDurationInOpenState: 60s
        permittedNumberOfCallsInHalfOpenState: 10
        maxWaitDurationInHalfOpenState: 0s
        transitionToStateAfterWaitDuration: OPEN
        automaticTransitionFromOpenToHalfOpenEnabled: false
        initialState: CLOSED
        writableStackTraceEnabled: true
        recordExceptions: []
        ignoreExceptions: []
    instances:
      reference-predicates:
        baseConfig: default
        recordFailurePredicate: com.example.bookshelf.PricingFailurePredicate
        recordResultPredicate: com.example.bookshelf.StalePriceIsAFailure
        ignoreExceptionPredicate: com.example.bookshelf.ClientErrorIsNotAFailure
        ignoreClassBindingExceptions: false
      reference-exponential:
        baseConfig: default
        waitDurationInOpenState: 20s
        enableExponentialBackoff: true
        exponentialBackoffMultiplier: 1.5
        exponentialMaxWaitDurationInOpenState: 10m
      reference-randomized:
        baseConfig: default
        waitDurationInOpenState: 20s
        enableRandomizedWait: true
        randomizedWaitFactor: 0.5
  retry:
    tags:
      team: bookshelf
    retryAspectOrder: 2147483642                # LOWEST_PRECEDENCE - 5
    metrics:
      enabled: true
      legacy:
        enabled: false
    configs:
      default:
        eventConsumerBufferSize: 100            # Boot only
        maxAttempts: 3
        waitDuration: 500ms
        failAfterMaxAttempts: false
        retryExceptions: []
        ignoreExceptions: []
    instances:
      reference-classes:
        baseConfig: default
        retryExceptionPredicate: com.example.bookshelf.TransientHttpFailure
        resultPredicate: com.example.bookshelf.StalePriceIsAFailure
        consumeResultBeforeRetryAttempt: com.example.bookshelf.LogRetriedResult
      reference-interval:
        baseConfig: default
        intervalBiFunction: com.example.bookshelf.RetryAfterIntervalFunction
      reference-backoff:
        baseConfig: default
        waitDuration: 500ms
        enableExponentialBackoff: true
        exponentialBackoffMultiplier: 1.5
        exponentialMaxWaitDuration: 30s
        enableRandomizedWait: true
        randomizedWaitFactor: 0.5
  ratelimiter:
    tags:
      team: bookshelf
    rateLimiterAspectOrder: 2147483644          # LOWEST_PRECEDENCE - 3
    metrics:
      enabled: true
      legacy:
        enabled: false
    configs:
      default:
        registerHealthIndicator: false          # Boot only
        allowHealthIndicatorToFail: false       # Boot only
        subscribeForEvents: false               # Boot only
        eventConsumerBufferSize: 100            # Boot only
        limitForPeriod: 50
        limitRefreshPeriod: 500ns
        timeoutDuration: 5s
        writableStackTraceEnabled: true
  bulkhead:
    tags:
      team: bookshelf
    bulkheadAspectOrder: 2147483646             # LOWEST_PRECEDENCE - 1
    metrics:
      enabled: true
      legacy:
        enabled: false
    configs:
      default:
        eventConsumerBufferSize: 100            # Boot only
        maxConcurrentCalls: 25
        maxWaitDuration: 0ms
        writableStackTraceEnabled: true
  thread-pool-bulkhead:
    tags:
      team: bookshelf
    metrics:
      enabled: true
      legacy:
        enabled: false
    configs:
      default:
        eventConsumerBufferSize: 100            # Boot only
        coreThreadPoolSize: 2                   # default: max(CPUs - 1, 1)
        maxThreadPoolSize: 4                    # default: number of CPUs
        queueCapacity: 100
        keepAliveDuration: 20ms
        writableStackTraceEnabled: true
        contextPropagators:
          - com.example.bookshelf.MdcContextPropagator
  timelimiter:
    tags:
      team: bookshelf
    timeLimiterAspectOrder: 2147483645          # LOWEST_PRECEDENCE - 2
    metrics:
      enabled: true
      legacy:
        enabled: false
    configs:
      default:
        eventConsumerBufferSize: 100            # Boot only
        timeoutDuration: 1s
        cancelRunningFuture: true
  micrometer:
    timer:
      tags:
        team: bookshelf
      timerAspectOrder: 2147483647              # Ordered.LOWEST_PRECEDENCE
      configs:
        default:
          eventConsumerBufferSize: 100          # Boot only
          metricNames: resilience4j.timer.calls
          onFailureTagResolver: com.example.bookshelf.CauseTag
  scheduled:
    executor:
      corePoolSize: 2
      contextPropagators:
        - com.example.bookshelf.MdcContextPropagator

package com.example.bookshelf;

import java.util.function.Predicate;

public class ClientErrorIsNotAFailure implements Predicate<Throwable> {
    @Override
    public boolean test(Throwable t) { return t instanceof IllegalArgumentException; }
}

package com.example.bookshelf;

import io.github.resilience4j.common.circuitbreaker.configuration.CircuitBreakerConfigCustomizer;
import java.time.Clock;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
public class BookshelfResilienceConfig {

    @Bean
    @ConditionalOnMissingBean
    Clock clock() {
        return Clock.systemUTC();
    }

    @Bean
    CircuitBreakerConfigCustomizer pricingBreakerClock(Clock clock) {
        // the TIME_BASED window of "pricing" now reads the application's Clock bean,
        // which a test replaces with a fixed or manually advanced clock
        return CircuitBreakerConfigCustomizer.of("pricing", builder -> builder.clock(clock));
    }
}

package com.example.bookshelf;

import io.github.resilience4j.bulkhead.BulkheadConfig;
import io.github.resilience4j.circuitbreaker.CircuitBreakerConfig.SlidingWindowSynchronizationStrategy;
import io.github.resilience4j.common.bulkhead.configuration.BulkheadConfigCustomizer;
import io.github.resilience4j.common.bulkhead.configuration.ThreadPoolBulkheadConfigCustomizer;
import io.github.resilience4j.common.circuitbreaker.configuration.CircuitBreakerConfigCustomizer;
import io.github.resilience4j.common.ratelimiter.configuration.RateLimiterConfigCustomizer;
import io.github.resilience4j.common.retry.configuration.RetryConfigCustomizer;
import io.github.resilience4j.core.IntervalFunction;
import java.time.Duration;
import java.util.concurrent.ThreadPoolExecutor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/** Settings that exist on the builders but have no Spring Boot property in 2.4.0. */
@Configuration(proxyBeanMethods = false)
public class ProgrammaticOnlyCustomizers {

    @Bean
    CircuitBreakerConfigCustomizer recommendationsBreaker() {
        return CircuitBreakerConfigCustomizer.of("recommendations", builder -> builder
            .slidingWindowSynchronizationStrategy(SlidingWindowSynchronizationStrategy.LOCK_FREE)
            .ignoreExceptionsPrecedenceEnabled(true));
    }

    @Bean
    RetryConfigCustomizer isbnRetry() {
        return RetryConfigCustomizer.of("isbn", builder -> builder
            .intervalFunction(IntervalFunction.ofExponentialBackoff(Duration.ofMillis(100), 2.0)));
    }

    @Bean
    RateLimiterConfigCustomizer searchLimiter() {
        return RateLimiterConfigCustomizer.of("search", builder -> builder
            .drainPermissionsOnResult(result -> result.isRight() && result.get() instanceof String s && s.isEmpty()));
    }

    @Bean
    BulkheadConfigCustomizer isbnBulkhead() {
        return BulkheadConfigCustomizer.of("isbn", builder -> builder.fairCallHandlingStrategyEnabled(false));
    }

    @Bean
    ThreadPoolBulkheadConfigCustomizer recommendationsPool() {
        return ThreadPoolBulkheadConfigCustomizer.of("recommendations", builder -> builder
            .rejectedExecutionHandler(new ThreadPoolExecutor.AbortPolicy()));
    }
}

resilience4j:
  retry:
    configs:
      default:
        maxAttempts: 3
        waitDuration: 200ms
---
spring:
  config:
    activate:
      on-profile: test
resilience4j:
  retry:
    configs:
      default:
        waitDuration: 1ms

package com.example.bookshelf;

import io.github.resilience4j.circuitbreaker.annotation.CircuitBreaker;
import io.github.resilience4j.ratelimiter.annotation.RateLimiter;
import org.springframework.stereotype.Component;

@Component
public class SpelNames {

    public record Tenant(String id, String tier) {}

    // placeholder, resolved from the Environment: the instance name lives in application.yml
    @CircuitBreaker(name = "${bookshelf.resilience.pricing-instance:pricing}")
    public String price(String isbn) {
        return "9.99";
    }

    // a method argument, by parameter name: one breaker per tenant tier, all created
    // from the "tier" configuration instead of from configs.default
    @CircuitBreaker(name = "#tenant.tier", configuration = "tier")
    public String catalogue(Tenant tenant) {
        return "catalogue";
    }

    // the method name: the limiter is called "search", like the instance in application.yml
    @RateLimiter(name = "#root.methodName")
    public String search(String query) {
        return "results";
    }

    // a bean method that receives the argument; the bean is called instanceNames
    @CircuitBreaker(name = "@instanceNames.forIsbn(#isbn)", configuration = "tier")
    public String metadata(String isbn) {
        return "metadata";
    }
}

<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-context</artifactId>
  <version>5.0.3</version>
</dependency>

# application.yml points at the file that the platform mounts or a config server serves
#   spring.config.import: optional:file:/etc/bookshelf/resilience.yml
#   management.endpoints.web.exposure.include: refresh,circuitbreakers

# after the file changed
curl -s -X POST http://localhost:8080/actuator/refresh
# ["resilience4j.circuitbreaker.instances.pricing.failureRateThreshold"]

curl -s http://localhost:8080/actuator/circuitbreakers
# {"circuitBreakers":{"pricing":{"failureRateThreshold":"20.0%","state":"CLOSED", ...}}}

package com.example.bookshelf;

import io.github.resilience4j.circuitbreaker.CircuitBreaker;
import io.github.resilience4j.circuitbreaker.CircuitBreakerRegistry;
import io.github.resilience4j.circuitbreaker.event.CircuitBreakerEvent;
import io.github.resilience4j.common.CompositeCustomizer;
import io.github.resilience4j.common.circuitbreaker.configuration.CircuitBreakerConfigCustomizer;
import io.github.resilience4j.consumer.EventConsumerRegistry;
import io.github.resilience4j.core.registry.RegistryEventConsumer;
import io.github.resilience4j.spring6.circuitbreaker.configure.CircuitBreakerConfiguration;
import io.github.resilience4j.spring6.circuitbreaker.configure.CircuitBreakerConfigurationProperties;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/** Spring Boot 3 starter 2.4.0 has no refresh-scoped registry: this is the same wiring the Boot 4 starter ships. */
@Configuration(proxyBeanMethods = false)
public class RefreshableCircuitBreakers {

    @Bean
    @RefreshScope
    CircuitBreakerRegistry circuitBreakerRegistry(
            CircuitBreakerConfigurationProperties properties,
            EventConsumerRegistry<CircuitBreakerEvent> eventConsumerRegistry,
            RegistryEventConsumer<CircuitBreaker> registryEventConsumer,
            @Qualifier("compositeCircuitBreakerCustomizer")
            CompositeCustomizer<CircuitBreakerConfigCustomizer> customizers) {
        return new CircuitBreakerConfiguration(properties)
                .circuitBreakerRegistry(eventConsumerRegistry, registryEventConsumer, customizers);
    }
}

spring:
  application:
    name: bookshelf-service

resilience4j:
  circuitbreaker:
    tags:
      application: ${spring.application.name}
    configs:
      default:                                  # what an unlisted breaker gets
        slidingWindowType: COUNT_BASED
        slidingWindowSize: 20
        minimumNumberOfCalls: 10
        failureRateThreshold: 50
        waitDurationInOpenState: 30s
        permittedNumberOfCallsInHalfOpenState: 3
        automaticTransitionFromOpenToHalfOpenEnabled: true
        registerHealthIndicator: true
        eventConsumerBufferSize: 50
        recordExceptions:
          - org.springframework.web.client.ResourceAccessException
          - org.springframework.web.client.HttpServerErrorException
          - java.util.concurrent.TimeoutException
        ignoreExceptions:
          - org.springframework.web.client.HttpClientErrorException
    instances:
      pricing:                                  # critical, high traffic: time-based window
        baseConfig: default
        slidingWindowType: TIME_BASED
        slidingWindowSize: 10
        minimumNumberOfCalls: 20
        slowCallDurationThreshold: 800ms
        slowCallRateThreshold: 70
        waitDurationInOpenState: 20s
        enableExponentialBackoff: true
        exponentialBackoffMultiplier: 2
        exponentialMaxWaitDurationInOpenState: 2m
        permittedNumberOfCallsInHalfOpenState: 5
        maxWaitDurationInHalfOpenState: 10s
        allowHealthIndicatorToFail: false
      isbn:                                     # third-party API: jitter the probes
        baseConfig: default
        waitDurationInOpenState: 10s
        enableRandomizedWait: true
        randomizedWaitFactor: 0.25
        registerHealthIndicator: false
      recommendations:                          # optional feature: open early, tolerate slowness
        baseConfig: default
        failureRateThreshold: 30
        slowCallDurationThreshold: 1s
      reviews:
        baseConfig: default

  retry:
    configs:
      default:
        maxAttempts: 3
        waitDuration: 200ms
        enableExponentialBackoff: true
        exponentialBackoffMultiplier: 2
        enableRandomizedWait: true
        randomizedWaitFactor: 0.5
        ignoreExceptions:
          - io.github.resilience4j.circuitbreaker.CallNotPermittedException
    instances:
      pricing:
        baseConfig: default
        maxAttempts: 2
        retryExceptions:
          - org.springframework.web.client.ResourceAccessException
      isbn:
        baseConfig: default
        maxAttempts: 4
        exponentialMaxWaitDuration: 5s
        retryExceptionPredicate: com.example.bookshelf.TransientHttpFailure
        eventConsumerBufferSize: 200

  ratelimiter:
    configs:
      default:
        limitForPeriod: 10
        limitRefreshPeriod: 1s
        timeoutDuration: 0
    instances:
      isbn:                                     # client side: stay under the third-party quota
        baseConfig: default
        limitForPeriod: 5
        timeoutDuration: 500ms
        subscribeForEvents: true
        registerHealthIndicator: true
      search:                                   # server side: protect our own endpoint
        baseConfig: default
        limitForPeriod: 3
        limitRefreshPeriod: 2s
        subscribeForEvents: true

  bulkhead:
    configs:
      default:
        maxConcurrentCalls: 10
        maxWaitDuration: 0
    instances:
      isbn:
        baseConfig: default
        maxConcurrentCalls: 2
        maxWaitDuration: 100ms
        writableStackTraceEnabled: false

  thread-pool-bulkhead:
    configs:
      default:
        coreThreadPoolSize: 2
        maxThreadPoolSize: 4
        queueCapacity: 2
        keepAliveDuration: 20ms
        contextPropagators:
          - com.example.bookshelf.MdcContextPropagator
    instances:
      recommendations:
        baseConfig: default

  timelimiter:
    configs:
      default:
        timeoutDuration: 2s
        cancelRunningFuture: true
    instances:
      pricing:
        baseConfig: default
        timeoutDuration: 800ms
      recommendations:
        baseConfig: default
        timeoutDuration: 1s
      reviews:
        baseConfig: default
        timeoutDuration: 300ms
        cancelRunningFuture: false

management:
  endpoints:
    web:
      exposure:
        include: health,circuitbreakers,circuitbreakerevents,retries,ratelimiters,bulkheads,timelimiters,metrics,prometheus
  endpoint:
    circuitbreakers:
      access: read-only                         # no CLOSE / FORCE_OPEN / DISABLE over HTTP
    health:
      show-details: when-authorized
  health:
    circuitbreakers:
      enabled: true
    ratelimiters:
      enabled: true

# Test profile: small windows, tiny waits and no jitter, so a test can open a breaker with four calls
resilience4j:
  circuitbreaker:
    configs:
      default:
        slidingWindowSize: 4
        minimumNumberOfCalls: 4
        waitDurationInOpenState: 100ms
        permittedNumberOfCallsInHalfOpenState: 1
    instances:
      pricing:
        slidingWindowType: COUNT_BASED
        slidingWindowSize: 4
        minimumNumberOfCalls: 4
        enableExponentialBackoff: false
        waitDurationInOpenState: 100ms
      isbn:                                     # the instance sets its own wait, so the default above would not reach it
        waitDurationInOpenState: 100ms
        enableRandomizedWait: false
  retry:
    configs:
      default:
        waitDuration: 1ms
        enableExponentialBackoff: false
        enableRandomizedWait: false
  ratelimiter:
    instances:
      isbn:
        limitForPeriod: 2
  timelimiter:
    configs:
      default:
        timeoutDuration: 500ms

# Local profile: breakers that never trip while you debug, everything else as in production
resilience4j:
  circuitbreaker:
    configs:
      default:
        failureRateThreshold: 100
        minimumNumberOfCalls: 1000
  retry:
    configs:
      default:
        maxAttempts: 1

package com.example.bookshelf;

import static org.assertj.core.api.Assertions.assertThat;

import io.github.resilience4j.circuitbreaker.CircuitBreakerRegistry;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.SpringBootConfiguration;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Import;
import org.springframework.test.context.ActiveProfiles;

@SpringBootTest(classes = PricingBreakerClockTest.TestApp.class, webEnvironment = SpringBootTest.WebEnvironment.NONE)
@ActiveProfiles("test")
class PricingBreakerClockTest {

    @SpringBootConfiguration
    @EnableAutoConfiguration
    @Import(BookshelfResilienceConfig.class)
    static class TestApp {
    }

    @TestConfiguration
    static class FixedClock {
        @Bean
        Clock clock() {
            return Clock.fixed(Instant.parse("2026-10-04T12:00:00Z"), ZoneOffset.UTC);
        }
    }

    @Autowired
    CircuitBreakerRegistry registry;

    @Autowired
    Clock clock;

    @Test
    void pricingBreakerReadsTheApplicationClock() {
        assertThat(registry.circuitBreaker("pricing").getCircuitBreakerConfig().getClock()).isSameAs(clock);
        assertThat(registry.circuitBreaker("pricing").getCircuitBreakerConfig().getSlidingWindowSize()).isEqualTo(4);
    }
}