Skip to content

giuseppe-trisciuoglio/developer-kit / plugins/developer-kit-java/skills/spring-boot-resilience4j

spring-boot-resilience4j

Verified

Provides fault tolerance patterns for Spring Boot 3.x using Resilience4j. Use when implementing circuit breakers, handling service failures, adding retry logic with exponential backoff, configuring rate limiters, or protecting services from cascading failures. Generates circuit breaker, retry, rate limiter, bulkhead, time limiter, and fallback implementations. Validates resilience configurations through Actuator endpoints.

FileKindSize
SKILL.mdskill md13.8 KB
references/configuration-reference.mdmarkdown10.8 KB
references/examples.mdmarkdown13.5 KB
references/testing-patterns.mdmarkdown12.9 KB

references/configuration-reference.md

View on GitHub
# Resilience4j Configuration Reference

## Circuit Breaker Configuration

### Complete Properties List

```yaml
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

```yaml
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

```yaml
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

```yaml
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**
```yaml
limitForPeriod: 10
limitRefreshPeriod: 1s
timeoutDuration: 0s           # Fail immediately if no permits
```

**100 requests per minute**
```yaml
limitForPeriod: 100
limitRefreshPeriod: 1m
timeoutDuration: 500ms        # Wait up to 500ms for permit
```

**5 requests per second with queuing**
```yaml
limitForPeriod: 5
limitRefreshPeriod: 1s
timeoutDuration: 2s           # Wait up to 2s for permit
```

## Bulkhead Configuration

### Semaphore Bulkhead

```yaml
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

```yaml
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

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

## Annotation Reference

### `@`CircuitBreaker

```java
@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

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

### `@`RateLimiter

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

### `@`Bulkhead

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

### `@`TimeLimiter

```java
@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

```java
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

```java
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](https://resilience4j.readme.io/)
- [Spring Boot Integration Guide](https://resilience4j.readme.io/docs/getting-started-3)
- [Micrometer Metrics Guide](https://resilience4j.readme.io/docs/micrometer)
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall