0
# Configuration Options
1
2
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.
3
4
## Capabilities
5
6
### Global Configuration
7
8
System-wide configuration options that affect all fault tolerance operations.
9
10
```java { .api }
11
// Global enable/disable
12
quarkus.fault-tolerance.enabled=true
13
14
// Metrics collection
15
quarkus.fault-tolerance.metrics.enabled=true
16
17
// MicroProfile specification compatibility
18
quarkus.fault-tolerance.mp-compatibility=false
19
```
20
21
#### Usage Example
22
23
```properties
24
# Disable fault tolerance globally except for fallback
25
quarkus.fault-tolerance.enabled=false
26
27
# Enable detailed metrics collection
28
quarkus.fault-tolerance.metrics.enabled=true
29
30
# Enable strict MicroProfile compatibility mode
31
quarkus.fault-tolerance.mp-compatibility=true
32
```
33
34
### Strategy-Specific Configuration
35
36
Configuration properties for individual fault tolerance strategies with three levels of specificity.
37
38
#### Configuration Hierarchy
39
40
```java { .api }
41
// Global strategy configuration (lowest priority)
42
quarkus.fault-tolerance.global.<strategy>.<property>=<value>
43
44
// Per-class configuration (medium priority)
45
quarkus.fault-tolerance."<fully.qualified.ClassName>".<strategy>.<property>=<value>
46
47
// Per-method configuration (highest priority)
48
quarkus.fault-tolerance."<fully.qualified.ClassName>/<methodName>".<strategy>.<property>=<value>
49
```
50
51
### Retry Configuration
52
53
Controls retry behavior including maximum attempts, delays, and exception handling.
54
55
```java { .api }
56
// Maximum number of retry attempts
57
quarkus.fault-tolerance.global.retry.max-retries=3
58
59
// Delay between retry attempts (milliseconds)
60
quarkus.fault-tolerance.global.retry.delay=0
61
62
// Time unit for delay
63
quarkus.fault-tolerance.global.retry.delay-unit=MILLIS
64
65
// Maximum total retry duration (milliseconds)
66
quarkus.fault-tolerance.global.retry.max-duration=180000
67
68
// Time unit for max duration
69
quarkus.fault-tolerance.global.retry.max-duration-unit=MILLIS
70
71
// Random jitter for retry delays (milliseconds)
72
quarkus.fault-tolerance.global.retry.jitter=200
73
74
// Time unit for jitter
75
quarkus.fault-tolerance.global.retry.jitter-unit=MILLIS
76
77
// Exception types to retry on
78
quarkus.fault-tolerance.global.retry.retry-on=java.lang.Exception
79
80
// Exception types to abort on (higher priority)
81
quarkus.fault-tolerance.global.retry.abort-on=
82
```
83
84
#### Usage Example
85
86
```properties
87
# Global retry configuration
88
quarkus.fault-tolerance.global.retry.max-retries=5
89
quarkus.fault-tolerance.global.retry.delay=1000
90
quarkus.fault-tolerance.global.retry.delay-unit=MILLIS
91
92
# Per-class retry configuration
93
quarkus.fault-tolerance."com.example.WeatherService".retry.max-retries=3
94
quarkus.fault-tolerance."com.example.WeatherService".retry.delay=500
95
96
# Per-method retry configuration
97
quarkus.fault-tolerance."com.example.WeatherService/getCurrentWeather".retry.max-retries=2
98
```
99
100
### Circuit Breaker Configuration
101
102
Controls circuit breaker behavior including failure thresholds, delays, and exception handling.
103
104
```java { .api }
105
// Circuit breaker delay before transitioning from open to half-open (milliseconds)
106
quarkus.fault-tolerance.global.circuit-breaker.delay=5000
107
108
// Time unit for delay
109
quarkus.fault-tolerance.global.circuit-breaker.delay-unit=MILLIS
110
111
// Exception types considered failures
112
quarkus.fault-tolerance.global.circuit-breaker.fail-on=java.lang.Throwable
113
114
// Failure ratio threshold (0.0 to 1.0)
115
quarkus.fault-tolerance.global.circuit-breaker.failure-ratio=0.5
116
117
// Request volume threshold for failure evaluation
118
quarkus.fault-tolerance.global.circuit-breaker.request-volume-threshold=20
119
120
// Exception types not considered failures (higher priority)
121
quarkus.fault-tolerance.global.circuit-breaker.skip-on=
122
123
// Success threshold for transitioning from half-open to closed
124
quarkus.fault-tolerance.global.circuit-breaker.success-threshold=1
125
```
126
127
#### Usage Example
128
129
```properties
130
# Global circuit breaker settings
131
quarkus.fault-tolerance.global.circuit-breaker.failure-ratio=0.6
132
quarkus.fault-tolerance.global.circuit-breaker.request-volume-threshold=10
133
quarkus.fault-tolerance.global.circuit-breaker.delay=3000
134
135
# Service-specific circuit breaker
136
quarkus.fault-tolerance."com.example.PaymentService".circuit-breaker.failure-ratio=0.3
137
quarkus.fault-tolerance."com.example.PaymentService".circuit-breaker.success-threshold=2
138
```
139
140
### Timeout Configuration
141
142
Controls method execution timeout limits.
143
144
```java { .api }
145
// Timeout value (milliseconds)
146
quarkus.fault-tolerance.global.timeout.value=1000
147
148
// Time unit for timeout
149
quarkus.fault-tolerance.global.timeout.unit=MILLIS
150
```
151
152
#### Usage Example
153
154
```properties
155
# Global timeout settings
156
quarkus.fault-tolerance.global.timeout.value=5000
157
quarkus.fault-tolerance.global.timeout.unit=MILLIS
158
159
# Method-specific timeout
160
quarkus.fault-tolerance."com.example.SlowService/processLargeFile".timeout.value=30000
161
```
162
163
### Fallback Configuration
164
165
Controls fallback method and handler configuration.
166
167
```java { .api }
168
// Exception types that trigger fallback
169
quarkus.fault-tolerance.global.fallback.apply-on=java.lang.Throwable
170
171
// Exception types that skip fallback (higher priority)
172
quarkus.fault-tolerance.global.fallback.skip-on=
173
174
// Fallback handler class
175
quarkus.fault-tolerance.global.fallback.value=com.example.CustomFallbackHandler
176
177
// Fallback method name (build-time only)
178
quarkus.fault-tolerance.global.fallback.fallback-method=alternativeMethod
179
```
180
181
#### Usage Example
182
183
```properties
184
# Global fallback configuration
185
quarkus.fault-tolerance.global.fallback.apply-on=java.io.IOException,java.net.SocketTimeoutException
186
187
# Class-specific fallback handler
188
quarkus.fault-tolerance."com.example.ExternalService".fallback.value=com.example.ExternalServiceFallback
189
```
190
191
### Bulkhead Configuration
192
193
Controls concurrent execution limits and queuing behavior.
194
195
```java { .api }
196
// Maximum concurrent executions
197
quarkus.fault-tolerance.global.bulkhead.value=10
198
199
// Waiting task queue size for asynchronous operations
200
quarkus.fault-tolerance.global.bulkhead.waiting-task-queue=10
201
```
202
203
#### Usage Example
204
205
```properties
206
# Global bulkhead settings
207
quarkus.fault-tolerance.global.bulkhead.value=5
208
quarkus.fault-tolerance.global.bulkhead.waiting-task-queue=15
209
210
# Service-specific bulkhead
211
quarkus.fault-tolerance."com.example.DatabaseService".bulkhead.value=3
212
```
213
214
### Rate Limit Configuration
215
216
Controls rate limiting behavior including windows and spacing.
217
218
```java { .api }
219
// Maximum invocations per time window
220
quarkus.fault-tolerance.global.rate-limit.value=100
221
222
// Time window length (milliseconds)
223
quarkus.fault-tolerance.global.rate-limit.window=1000
224
225
// Time unit for window
226
quarkus.fault-tolerance.global.rate-limit.window-unit=MILLIS
227
228
// Minimum spacing between invocations (milliseconds)
229
quarkus.fault-tolerance.global.rate-limit.min-spacing=0
230
231
// Time unit for min spacing
232
quarkus.fault-tolerance.global.rate-limit.min-spacing-unit=MILLIS
233
234
// Rate limit window type
235
quarkus.fault-tolerance.global.rate-limit.type=FIXED
236
```
237
238
#### Usage Example
239
240
```properties
241
# Global rate limiting
242
quarkus.fault-tolerance.global.rate-limit.value=50
243
quarkus.fault-tolerance.global.rate-limit.window=60000
244
quarkus.fault-tolerance.global.rate-limit.window-unit=MILLIS
245
quarkus.fault-tolerance.global.rate-limit.type=ROLLING
246
247
# API endpoint rate limiting
248
quarkus.fault-tolerance."com.example.ApiController/publicEndpoint".rate-limit.value=10
249
quarkus.fault-tolerance."com.example.ApiController/publicEndpoint".rate-limit.window=60000
250
```
251
252
### Backoff Strategy Configuration
253
254
Controls retry delay strategies including exponential and Fibonacci backoff.
255
256
#### Exponential Backoff Configuration
257
258
```java { .api }
259
// Multiplicative factor for exponential growth
260
quarkus.fault-tolerance.global.exponential-backoff.factor=2
261
262
// Maximum delay between retries (milliseconds)
263
quarkus.fault-tolerance.global.exponential-backoff.max-delay=60000
264
265
// Time unit for max delay
266
quarkus.fault-tolerance.global.exponential-backoff.max-delay-unit=MILLIS
267
```
268
269
#### Fibonacci Backoff Configuration
270
271
```java { .api }
272
// Maximum delay between retries (milliseconds)
273
quarkus.fault-tolerance.global.fibonacci-backoff.max-delay=60000
274
275
// Time unit for max delay
276
quarkus.fault-tolerance.global.fibonacci-backoff.max-delay-unit=MILLIS
277
```
278
279
#### Custom Backoff Configuration
280
281
```java { .api }
282
// Custom backoff strategy class
283
quarkus.fault-tolerance.global.custom-backoff.value=com.example.CustomBackoffStrategy
284
```
285
286
#### Usage Example
287
288
```properties
289
# Exponential backoff configuration
290
quarkus.fault-tolerance.global.exponential-backoff.factor=3
291
quarkus.fault-tolerance.global.exponential-backoff.max-delay=30000
292
293
# Custom backoff for specific service
294
quarkus.fault-tolerance."com.example.RetryService".custom-backoff.value=com.example.CustomExponentialBackoff
295
```
296
297
### Conditional Retry Configuration
298
299
Controls predicate-based retry logic for advanced retry scenarios.
300
301
```java { .api }
302
// Exception predicate class for conditional retry
303
quarkus.fault-tolerance.global.retry-when.exception=com.example.ExceptionPredicate
304
305
// Result predicate class for conditional retry
306
quarkus.fault-tolerance.global.retry-when.result=com.example.ResultPredicate
307
```
308
309
#### Usage Example
310
311
```properties
312
# Conditional retry based on exception type
313
quarkus.fault-tolerance."com.example.ApiClient".retry-when.exception=com.example.RetryableExceptionPredicate
314
315
# Conditional retry based on return value
316
quarkus.fault-tolerance."com.example.DataService".retry-when.result=com.example.InvalidResultPredicate
317
```
318
319
### Before Retry Configuration
320
321
Controls pre-retry execution behavior.
322
323
```java { .api }
324
// Before retry handler class
325
quarkus.fault-tolerance.global.before-retry.value=com.example.BeforeRetryHandler
326
327
// Before retry method name (build-time only)
328
quarkus.fault-tolerance.global.before-retry.method-name=handleBeforeRetry
329
```
330
331
#### Usage Example
332
333
```properties
334
# Global before retry handler
335
quarkus.fault-tolerance.global.before-retry.value=com.example.LoggingBeforeRetryHandler
336
337
# Method-specific before retry
338
quarkus.fault-tolerance."com.example.ExternalService/callApi".before-retry.method-name=logRetryAttempt
339
```
340
341
### Apply Guard Configuration
342
343
Controls programmatic guard application.
344
345
```java { .api }
346
// Guard identifier for ApplyGuard annotation
347
quarkus.fault-tolerance.global.apply-guard.value=my-custom-guard
348
```
349
350
#### Usage Example
351
352
```properties
353
# Custom guard configuration
354
quarkus.fault-tolerance."com.example.ProtectedService".apply-guard.value=database-guard
355
```
356
357
## Types
358
359
### Configuration Interfaces
360
361
```java { .api }
362
// Runtime configuration interface
363
@ConfigMapping(prefix = "quarkus.fault-tolerance")
364
interface SmallRyeFaultToleranceConfig {
365
Optional<Boolean> enabled();
366
Optional<Boolean> metricsEnabled();
367
Optional<Boolean> mpCompatibility();
368
Map<String, StrategiesConfig> strategies();
369
}
370
371
// Build-time configuration interface
372
@ConfigMapping(prefix = "quarkus.fault-tolerance")
373
interface SmallRyeFaultToleranceBuildTimeConfig {
374
Map<String, StrategiesConfig> strategies();
375
}
376
```
377
378
### Strategy Configuration Types
379
380
```java { .api }
381
// Strategy configuration container
382
interface StrategiesConfig {
383
Optional<RetryConfig> retry();
384
Optional<CircuitBreakerConfig> circuitBreaker();
385
Optional<TimeoutConfig> timeout();
386
Optional<FallbackConfig> fallback();
387
Optional<BulkheadConfig> bulkhead();
388
Optional<RateLimitConfig> rateLimit();
389
Optional<ExponentialBackoffConfig> exponentialBackoff();
390
Optional<FibonacciBackoffConfig> fibonacciBackoff();
391
Optional<CustomBackoffConfig> customBackoff();
392
Optional<RetryWhenConfig> retryWhen();
393
Optional<BeforeRetryConfig> beforeRetry();
394
Optional<ApplyGuardConfig> applyGuard();
395
Optional<AsynchronousConfig> asynchronous();
396
Optional<AsynchronousNonBlockingConfig> asynchronousNonBlocking();
397
}
398
```
399
400
### Individual Strategy Configuration Interfaces
401
402
```java { .api }
403
// Retry configuration
404
interface RetryConfig {
405
Optional<Boolean> enabled();
406
OptionalInt maxRetries();
407
OptionalLong delay();
408
Optional<ChronoUnit> delayUnit();
409
OptionalLong maxDuration();
410
Optional<ChronoUnit> maxDurationUnit();
411
OptionalLong jitter();
412
Optional<ChronoUnit> jitterUnit();
413
Optional<Class<? extends Throwable>[]> retryOn();
414
Optional<Class<? extends Throwable>[]> abortOn();
415
}
416
417
// Circuit breaker configuration
418
interface CircuitBreakerConfig {
419
Optional<Boolean> enabled();
420
OptionalLong delay();
421
Optional<ChronoUnit> delayUnit();
422
Optional<Class<? extends Throwable>[]> failOn();
423
OptionalDouble failureRatio();
424
OptionalInt requestVolumeThreshold();
425
Optional<Class<? extends Throwable>[]> skipOn();
426
OptionalInt successThreshold();
427
}
428
429
// Timeout configuration
430
interface TimeoutConfig {
431
Optional<Boolean> enabled();
432
OptionalLong value();
433
Optional<ChronoUnit> unit();
434
}
435
436
// Additional configuration interfaces for other strategies...
437
```