---
agentTools:
  projectIndex: https://resilience4j.readme.io/v1.7.0/llms.txt
---

# Getting Started

Getting started with resilience4j-micronaut

[block:api-header]
{
  "title": "Setup"
}
[/block]

Add the Micronaut Starter of Resilience4j to your compile dependency.

include the maven bom for micronaut dependencies `io.micronaut:micronaut-bom:2.0.0.M3`.

[block:code]
{
  "codes": [
    {
      "code": "repositories {\n    mavenCentral()\n    jCenter()\n}\n\ndependencyManagement {\n    imports {\n        mavenBom 'io.micronaut:micronaut-bom:2.0.0.M3'\n    }\n}\n\ndependencies {\n  annotationProcessor \"io.micronaut:micronaut-inject-java\"\n  annotationProcessor \"io.micronaut:micronaut-validation\"\n  compile \"io.github.resilience4j:resilience4j-micronaut:${resilience4jVersion}\"\n}",
      "language": "groovy"
    }
  ]
}
[/block]

[block:api-header]
{
  "title": "Demo"
}
[/block]

Setup and usage in Micronaut is demonstrated into a [demo](https://github.com/resilience4j/resilience4j-micronaut-demo).

[block:api-header]
{
  "title": "Configuration"
}
[/block]

You can configure your CircuitBreaker, Retry, RateLimiter, Bulkhead, Thread pool bulkhead and TimeLimiter instances in Micronaut’s `application.yml` config file.
For example

[block:code]
{
  "codes": [
    {
      "code": "resilience4j:\n  circuitbreaker:\n    enabled: true\n    instances:\n      backendA:\n        baseConfig: default\n      backendB:\n        registerHealthIndicator: true\n        slidingWindowSize: 10\n        minimumNumberOfCalls: 10\n        permittedNumberOfCallsInHalfOpenState: 3\n        waitDurationInOpenState: PT5s\n        failureRateThreshold: 50\n        eventConsumerBufferSize: 10\n        recordFailurePredicate: resilience4j.micronaut.demo.exception.RecordFailurePredicate\n    configs:\n      default:\n        registerHealthIndicator: true\n        slidingWindowSize: 10\n        minimumNumberOfCalls: 5\n        permittedNumberOfCallsInHalfOpenState: 3\n        automaticTransitionFromOpenToHalfOpenEnabled: true\n        waitDurationInOpenState: PT5s\n        failureRateThreshold: 50\n        eventConsumerBufferSize: 10\n        recordExceptions:\n          - io.micronaut.http.exceptions.HttpStatusException\n          - java.util.concurrent.TimeoutException\n          - java.io.IOException\n        ignoreExceptions:\n          - resilience4j.micronaut.demo.exception.BusinessException\n      shared:\n        slidingWindowSize: 100\n        permittedNumberOfCallsInHalfOpenState: 30\n        waitDurationInOpenState: PT1s\n        failureRateThreshold: 50\n        eventConsumerBufferSize: 10\n        ignoreExceptions:\n          - resilience4j.micronaut.demo.exception.BusinessException\n  retry:\n    enabled: true\n    configs:\n      default:\n        maxAttempts: 3\n        waitDuration: 100\n        retryExceptions:\n          - io.micronaut.http.exceptions.HttpStatusException\n          - java.util.concurrent.TimeoutException\n          - java.io.IOException\n        ignoreExceptions:\n          - resilience4j.micronaut.demo.exception.BusinessException\n    instances:\n      backendA:\n        baseConfig: default\n      backendB:\n        baseConfig: default\n  bulkhead:\n    enabled: true\n    configs:\n      default:\n        maxConcurrentCalls: 100\n    instances:\n      backendA:\n        maxConcurrentCalls: 10\n      backendB:\n        maxWaitDuration: PT0.01S\n        maxConcurrentCalls: 20\n  thread-pool-bulkhead:\n    enabled: true\n    configs:\n      default:\n        maxThreadPoolSize: 4\n        coreThreadPoolSize: 2\n        queueCapacity: 2\n    instances:\n      backendA:\n        baseConfig: default\n      backendB:\n        maxThreadPoolSize: 1\n        coreThreadPoolSize: 1\n        queueCapacity: 1\n  ratelimiter:\n    enabled: true\n    configs:\n      default:\n        registerHealthIndicator: false\n        limitForPeriod: 10\n        limitRefreshPeriod: 1s\n        timeoutDuration: 0\n        eventConsumerBufferSize: 100\n    instances:\n      backendA:\n        baseConfig: default\n      backendB:\n        limitForPeriod: 6\n        limitRefreshPeriod: PT0.5S\n        timeoutDuration: 3s\n  timelimiter:\n    enabled: true\n    configs:\n      default:\n        cancelRunningFuture: false\n        timeoutDuration: PT2s\n    instances:\n      backendA:\n        baseConfig: default\n      backendB:\n        baseConfig: default\n        ",
      "language": "yaml"
    }
  ]
}
[/block]

You can also override the default configuration, define shared configurations and overwrite them in Micronaut’s `application.yml` config file.
For example:

[block:code]
{
  "codes": [
    {
      "code": "resilience4j: \n  circuitbreaker: \n    enabled: true\n  configs: \n    default: \n      eventConsumerBufferSize: 10\n      failureRateThreshold: 60\n      permittedNumberOfCallsInHalfOpenState: 10\n      registerHealthIndicator: true\n      slidingWindowSize: 100\n      waitDurationInOpenState: 10000\n    someShared: \n      permittedNumberOfCallsInHalfOpenState: 10\n      slidingWindowSize: 50\n  instances: \n    backendA: \n      baseConfig: default\n      waitDurationInOpenState: 5000\n    backendB: \n     baseConfig: someShared",
      "language": "yaml"
    }
  ]
}
[/block]

You can also override the configuration of a specific CircuitBreaker, Bulkhead, Retry, RateLimiter or TimeLimiter instances by using Customizer for specific instance names. The following shows an example of how to override a configured CircuitBreaker **backendA** in the above in the YAML file:

[block:code]
{
  "codes": [
    {
      "code": "@Bean\n@CircuitBreakerQualifier\npublic CircuitBreakerConfigCustomizer testCustomizer() {\n    return CircuitBreakerConfigCustomizer\n        .of(\"backendA\", builder -> builder.slidingWindowSize(100));\n}",
      "language": "java"
    }
  ]
}
[/block]

Resilience4j has its own customizer types which can be used as shown above. The beans have to be marked with the correct Qualifier:

[block:parameters]
{
  "data": {
    "h-0": "Resilienc4j Type",
    "h-1": "Instance Customizer class",
    "0-0": "Circuit breaker",
    "1-0": "Retry",
    "2-0": "Rate limiter",
    "3-0": "Bulkhead",
    "4-0": "ThreadPoolBulkhead",
    "5-0": "Time Limiter",
    "3-1": "BulkheadConfigCustomizer",
    "0-1": "CircuitBreakerConfigCustomizer",
    "2-1": "RateLimiterConfigCustomizer",
    "1-1": "RetryConfigCustomizer",
    "5-1": "TimeLimiterConfigCustomizer",
    "4-1": "ThreadPoolBulkheadConfigCustomizer",
    "h-2": "Qualifier",
    "0-2": "@CircuitBreakerQualifier",
    "1-2": "@RetryQualifier",
    "2-2": "@RateLimiterQualifier",
    "3-2": "@BulkheadQualifier",
    "4-2": "@ThreadPoolBulkheadQualifier",
    "5-2": "@TimeLimiterQualifier"
  },
  "cols": 3,
  "rows": 6
}
[/block]

[block:api-header]
{
  "title": "Configuration through Interceptor"
}
[/block]

beans can be intercepted before they are injected. so additional customization can be issued through intercepting the Resilience4j properties.

[block:code]
{
  "codes": [
    {
      "code": "package io.micronaut.ignite.docs.config;\n\n@Singleton\npublic class BulkheadConfiguration implements BeanCreatedEventListener<BulkheadProperties> {\n    @Override\n    public IgniteConfiguration onCreated(BeanCreatedEvent<BulkheadConfigurationProperties> event) {\n        CircuitBreakerProperties configuration = event.getBean();\n        return configuration;\n    }\n}",
      "language": "text"
    }
  ]
}
[/block]

[block:parameters]
{
  "data": {
    "h-0": "Resilience4j Type",
    "h-1": "Instance Customizer class",
    "0-1": "RateLimiterProperties",
    "0-0": "BulkheadConfigurationProperties",
    "1-0": "CircuitBreakerConfigurationProperties",
    "2-0": "RateLimiterProperties",
    "3-0": "RetryProperties",
    "4-0": "TimeLimiterProperties",
    "5-0": "ThreadPoolBulkheadProperties"
  },
  "cols": 1,
  "rows": 6
}
[/block]

[block:api-header]
{
  "title": "Annotations"
}
[/block]

The Micronaut starter provides annotations and AOP Aspects which are auto-configured.
RateLimiter, Retry, CircuitBreaker and Bulkhead annotations support synchronous return types and asynchronous types like CompletableFuture and reactive types like Spring Reactor's Flux and Mono (if you imported appropriate package like `resilience4j-reactor`).

Bulkhead annotation has a type attribute to define which bulkhead implementation will be used. By default it is semaphore but you can switch to thread pool  by setting the type attribute in the annotation:

[block:code]
{
  "codes": [
    {
      "code": "@Bulkhead(name = BACKEND_A, type = Bulkhead.Type.THREADPOOL)\npublic CompletableFuture<String> futureFailure() {\n\tCompletableFuture<String> future = new CompletableFuture<>();\n\tfuture.completeExceptionally(new IOException(\"BAM!\"));\n\treturn future;\n}\n",
      "language": "java"
    }
  ]
}
[/block]

An example of all resilience4j supported spring aspects

[block:code]
{
  "codes": [
    {
      "code": "\n@Override\n@Bulkhead(name = BACKEND_A, type = Bulkhead.Type.THREADPOOL)\n@TimeLimiter(name = BACKEND_A)\n@CircuitBreaker(name = BACKEND_A, fallbackMethod = \"futureFallback\")\npublic CompletableFuture<String> futureTimeout() {\n\tTry.run(() -> Thread.sleep(5000));\n\treturn CompletableFuture.completedFuture(\"Hello World from backend A\");\n}\n\n\n @Executable\n public String fallback() {\n \treturn \"Recovered HttpServerErrorException\";\n }\n\n@Executable\npublic CompletableFuture<String> futureFallback() {\n\treturn CompletableFuture.completedFuture(\"Recovered specific TimeoutException\");\n}",
      "language": "java"
    }
  ]
}
[/block]

It's important to remember that a fallback method should be placed in the same class and must be marked with @Executable.

The fallback method has to have the same matching argument signature and the same matching return type.

[block:api-header]
{
  "title": "Aspect order"
}
[/block]

The Resilience4j Aspects order is following: `Retry ( CircuitBreaker ( RateLimiter ( TimeLimiter ( Bulkhead ( Function ) ) ) ) )`

There is currently no way to change the order of the executing aspects.