CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-io-quarkus--quarkus-smallrye-fault-tolerance

Build fault-tolerant network services

—

Pending
Overview
Eval results
Files

configuration.mddocs/

Configuration Options

Comprehensive configuration system for overriding fault tolerance strategy defaults through application properties. Configuration can be applied globally, per-class, or per-method, providing fine-grained control over fault tolerance behavior.

Capabilities

Global Configuration

System-wide configuration options that affect all fault tolerance operations.

// Global enable/disable
quarkus.fault-tolerance.enabled=true

// Metrics collection
quarkus.fault-tolerance.metrics.enabled=true

// MicroProfile specification compatibility
quarkus.fault-tolerance.mp-compatibility=false

Usage Example

# Disable fault tolerance globally except for fallback
quarkus.fault-tolerance.enabled=false

# Enable detailed metrics collection
quarkus.fault-tolerance.metrics.enabled=true

# Enable strict MicroProfile compatibility mode
quarkus.fault-tolerance.mp-compatibility=true

Strategy-Specific Configuration

Configuration properties for individual fault tolerance strategies with three levels of specificity.

Configuration Hierarchy

// Global strategy configuration (lowest priority)
quarkus.fault-tolerance.global.<strategy>.<property>=<value>

// Per-class configuration (medium priority)  
quarkus.fault-tolerance."<fully.qualified.ClassName>".<strategy>.<property>=<value>

// Per-method configuration (highest priority)
quarkus.fault-tolerance."<fully.qualified.ClassName>/<methodName>".<strategy>.<property>=<value>

Retry Configuration

Controls retry behavior including maximum attempts, delays, and exception handling.

// Maximum number of retry attempts
quarkus.fault-tolerance.global.retry.max-retries=3

// Delay between retry attempts (milliseconds)
quarkus.fault-tolerance.global.retry.delay=0

// Time unit for delay
quarkus.fault-tolerance.global.retry.delay-unit=MILLIS

// Maximum total retry duration (milliseconds)
quarkus.fault-tolerance.global.retry.max-duration=180000

// Time unit for max duration
quarkus.fault-tolerance.global.retry.max-duration-unit=MILLIS

// Random jitter for retry delays (milliseconds)
quarkus.fault-tolerance.global.retry.jitter=200

// Time unit for jitter
quarkus.fault-tolerance.global.retry.jitter-unit=MILLIS

// Exception types to retry on
quarkus.fault-tolerance.global.retry.retry-on=java.lang.Exception

// Exception types to abort on (higher priority)
quarkus.fault-tolerance.global.retry.abort-on=

Usage Example

# Global retry configuration
quarkus.fault-tolerance.global.retry.max-retries=5
quarkus.fault-tolerance.global.retry.delay=1000
quarkus.fault-tolerance.global.retry.delay-unit=MILLIS

# Per-class retry configuration
quarkus.fault-tolerance."com.example.WeatherService".retry.max-retries=3
quarkus.fault-tolerance."com.example.WeatherService".retry.delay=500

# Per-method retry configuration
quarkus.fault-tolerance."com.example.WeatherService/getCurrentWeather".retry.max-retries=2

Circuit Breaker Configuration

Controls circuit breaker behavior including failure thresholds, delays, and exception handling.

// Circuit breaker delay before transitioning from open to half-open (milliseconds)
quarkus.fault-tolerance.global.circuit-breaker.delay=5000

// Time unit for delay
quarkus.fault-tolerance.global.circuit-breaker.delay-unit=MILLIS

// Exception types considered failures
quarkus.fault-tolerance.global.circuit-breaker.fail-on=java.lang.Throwable

// Failure ratio threshold (0.0 to 1.0)
quarkus.fault-tolerance.global.circuit-breaker.failure-ratio=0.5

// Request volume threshold for failure evaluation
quarkus.fault-tolerance.global.circuit-breaker.request-volume-threshold=20

// Exception types not considered failures (higher priority)
quarkus.fault-tolerance.global.circuit-breaker.skip-on=

// Success threshold for transitioning from half-open to closed
quarkus.fault-tolerance.global.circuit-breaker.success-threshold=1

Usage Example

# Global circuit breaker settings
quarkus.fault-tolerance.global.circuit-breaker.failure-ratio=0.6
quarkus.fault-tolerance.global.circuit-breaker.request-volume-threshold=10
quarkus.fault-tolerance.global.circuit-breaker.delay=3000

# Service-specific circuit breaker
quarkus.fault-tolerance."com.example.PaymentService".circuit-breaker.failure-ratio=0.3
quarkus.fault-tolerance."com.example.PaymentService".circuit-breaker.success-threshold=2

Timeout Configuration

Controls method execution timeout limits.

// Timeout value (milliseconds)
quarkus.fault-tolerance.global.timeout.value=1000

// Time unit for timeout
quarkus.fault-tolerance.global.timeout.unit=MILLIS

Usage Example

# Global timeout settings
quarkus.fault-tolerance.global.timeout.value=5000
quarkus.fault-tolerance.global.timeout.unit=MILLIS

# Method-specific timeout
quarkus.fault-tolerance."com.example.SlowService/processLargeFile".timeout.value=30000

Fallback Configuration

Controls fallback method and handler configuration.

// Exception types that trigger fallback
quarkus.fault-tolerance.global.fallback.apply-on=java.lang.Throwable

// Exception types that skip fallback (higher priority)
quarkus.fault-tolerance.global.fallback.skip-on=

// Fallback handler class
quarkus.fault-tolerance.global.fallback.value=com.example.CustomFallbackHandler

// Fallback method name (build-time only)
quarkus.fault-tolerance.global.fallback.fallback-method=alternativeMethod

Usage Example

# Global fallback configuration
quarkus.fault-tolerance.global.fallback.apply-on=java.io.IOException,java.net.SocketTimeoutException

# Class-specific fallback handler
quarkus.fault-tolerance."com.example.ExternalService".fallback.value=com.example.ExternalServiceFallback

Bulkhead Configuration

Controls concurrent execution limits and queuing behavior.

// Maximum concurrent executions
quarkus.fault-tolerance.global.bulkhead.value=10

// Waiting task queue size for asynchronous operations
quarkus.fault-tolerance.global.bulkhead.waiting-task-queue=10

Usage Example

# Global bulkhead settings
quarkus.fault-tolerance.global.bulkhead.value=5
quarkus.fault-tolerance.global.bulkhead.waiting-task-queue=15

# Service-specific bulkhead
quarkus.fault-tolerance."com.example.DatabaseService".bulkhead.value=3

Rate Limit Configuration

Controls rate limiting behavior including windows and spacing.

// Maximum invocations per time window
quarkus.fault-tolerance.global.rate-limit.value=100

// Time window length (milliseconds)
quarkus.fault-tolerance.global.rate-limit.window=1000

// Time unit for window
quarkus.fault-tolerance.global.rate-limit.window-unit=MILLIS

// Minimum spacing between invocations (milliseconds)
quarkus.fault-tolerance.global.rate-limit.min-spacing=0

// Time unit for min spacing
quarkus.fault-tolerance.global.rate-limit.min-spacing-unit=MILLIS

// Rate limit window type
quarkus.fault-tolerance.global.rate-limit.type=FIXED

Usage Example

# Global rate limiting
quarkus.fault-tolerance.global.rate-limit.value=50
quarkus.fault-tolerance.global.rate-limit.window=60000
quarkus.fault-tolerance.global.rate-limit.window-unit=MILLIS
quarkus.fault-tolerance.global.rate-limit.type=ROLLING

# API endpoint rate limiting
quarkus.fault-tolerance."com.example.ApiController/publicEndpoint".rate-limit.value=10
quarkus.fault-tolerance."com.example.ApiController/publicEndpoint".rate-limit.window=60000

Backoff Strategy Configuration

Controls retry delay strategies including exponential and Fibonacci backoff.

Exponential Backoff Configuration

// Multiplicative factor for exponential growth
quarkus.fault-tolerance.global.exponential-backoff.factor=2

// Maximum delay between retries (milliseconds)
quarkus.fault-tolerance.global.exponential-backoff.max-delay=60000

// Time unit for max delay
quarkus.fault-tolerance.global.exponential-backoff.max-delay-unit=MILLIS

Fibonacci Backoff Configuration

// Maximum delay between retries (milliseconds)
quarkus.fault-tolerance.global.fibonacci-backoff.max-delay=60000

// Time unit for max delay
quarkus.fault-tolerance.global.fibonacci-backoff.max-delay-unit=MILLIS

Custom Backoff Configuration

// Custom backoff strategy class
quarkus.fault-tolerance.global.custom-backoff.value=com.example.CustomBackoffStrategy

Usage Example

# Exponential backoff configuration
quarkus.fault-tolerance.global.exponential-backoff.factor=3
quarkus.fault-tolerance.global.exponential-backoff.max-delay=30000

# Custom backoff for specific service
quarkus.fault-tolerance."com.example.RetryService".custom-backoff.value=com.example.CustomExponentialBackoff

Conditional Retry Configuration

Controls predicate-based retry logic for advanced retry scenarios.

// Exception predicate class for conditional retry
quarkus.fault-tolerance.global.retry-when.exception=com.example.ExceptionPredicate

// Result predicate class for conditional retry
quarkus.fault-tolerance.global.retry-when.result=com.example.ResultPredicate

Usage Example

# Conditional retry based on exception type
quarkus.fault-tolerance."com.example.ApiClient".retry-when.exception=com.example.RetryableExceptionPredicate

# Conditional retry based on return value
quarkus.fault-tolerance."com.example.DataService".retry-when.result=com.example.InvalidResultPredicate

Before Retry Configuration

Controls pre-retry execution behavior.

// Before retry handler class
quarkus.fault-tolerance.global.before-retry.value=com.example.BeforeRetryHandler

// Before retry method name (build-time only)
quarkus.fault-tolerance.global.before-retry.method-name=handleBeforeRetry

Usage Example

# Global before retry handler
quarkus.fault-tolerance.global.before-retry.value=com.example.LoggingBeforeRetryHandler

# Method-specific before retry
quarkus.fault-tolerance."com.example.ExternalService/callApi".before-retry.method-name=logRetryAttempt

Apply Guard Configuration

Controls programmatic guard application.

// Guard identifier for ApplyGuard annotation
quarkus.fault-tolerance.global.apply-guard.value=my-custom-guard

Usage Example

# Custom guard configuration
quarkus.fault-tolerance."com.example.ProtectedService".apply-guard.value=database-guard

Types

Configuration Interfaces

// Runtime configuration interface
@ConfigMapping(prefix = "quarkus.fault-tolerance")
interface SmallRyeFaultToleranceConfig {
    Optional<Boolean> enabled();
    Optional<Boolean> metricsEnabled();
    Optional<Boolean> mpCompatibility();
    Map<String, StrategiesConfig> strategies();
}

// Build-time configuration interface
@ConfigMapping(prefix = "quarkus.fault-tolerance")
interface SmallRyeFaultToleranceBuildTimeConfig {
    Map<String, StrategiesConfig> strategies();
}

Strategy Configuration Types

// Strategy configuration container
interface StrategiesConfig {
    Optional<RetryConfig> retry();
    Optional<CircuitBreakerConfig> circuitBreaker();
    Optional<TimeoutConfig> timeout();
    Optional<FallbackConfig> fallback();
    Optional<BulkheadConfig> bulkhead();
    Optional<RateLimitConfig> rateLimit();
    Optional<ExponentialBackoffConfig> exponentialBackoff();
    Optional<FibonacciBackoffConfig> fibonacciBackoff();
    Optional<CustomBackoffConfig> customBackoff();
    Optional<RetryWhenConfig> retryWhen();
    Optional<BeforeRetryConfig> beforeRetry();
    Optional<ApplyGuardConfig> applyGuard();
    Optional<AsynchronousConfig> asynchronous();
    Optional<AsynchronousNonBlockingConfig> asynchronousNonBlocking();
}

Individual Strategy Configuration Interfaces

// Retry configuration
interface RetryConfig {
    Optional<Boolean> enabled();
    OptionalInt maxRetries();
    OptionalLong delay();
    Optional<ChronoUnit> delayUnit();
    OptionalLong maxDuration();
    Optional<ChronoUnit> maxDurationUnit();
    OptionalLong jitter();
    Optional<ChronoUnit> jitterUnit();
    Optional<Class<? extends Throwable>[]> retryOn();
    Optional<Class<? extends Throwable>[]> abortOn();
}

// Circuit breaker configuration
interface CircuitBreakerConfig {
    Optional<Boolean> enabled();
    OptionalLong delay();
    Optional<ChronoUnit> delayUnit();
    Optional<Class<? extends Throwable>[]> failOn();
    OptionalDouble failureRatio();
    OptionalInt requestVolumeThreshold();
    Optional<Class<? extends Throwable>[]> skipOn();
    OptionalInt successThreshold();
}

// Timeout configuration
interface TimeoutConfig {
    Optional<Boolean> enabled();
    OptionalLong value();
    Optional<ChronoUnit> unit();
}

// Additional configuration interfaces for other strategies...

Install with Tessl CLI

npx tessl i tessl/maven-io-quarkus--quarkus-smallrye-fault-tolerance

docs

asynchronous-strategies.md

bulkhead-strategies.md

circuit-breaker-strategies.md

configuration.md

fallback-strategies.md

index.md

programmatic-api.md

rate-limiting-strategies.md

retry-strategies.md

timeout-strategies.md

tile.json