Documentation
¶
Overview ¶
Package retry provides exponential backoff retry logic for transient failures
This implements a robust retry mechanism for handling transient AWS API failures with intelligent backoff and jitter. Key features:
- Exponential backoff with configurable base delay and maximum attempts - Jitter to prevent thundering herd problems - Context-aware operations with timeout support - Retry predicate for selective retries based on error type - Metrics tracking for success rate and attempt distribution
Example usage:
retryer := retry.NewExponentialBackoff(3, time.Second)
err := retryer.Do(ctx, func() error {
return awsOperation()
})
Index ¶
- type ExponentialBackoff
- func (r *ExponentialBackoff) Do(ctx context.Context, operation func() error) error
- func (r *ExponentialBackoff) DoNamed(ctx context.Context, operationName string, operation func() error) error
- func (r *ExponentialBackoff) GetMetrics() Metrics
- func (r *ExponentialBackoff) ResetMetrics()
- func (r *ExponentialBackoff) WithJitter(ratio float64) *ExponentialBackoff
- func (r *ExponentialBackoff) WithMaxDelay(maxDelay time.Duration) *ExponentialBackoff
- func (r *ExponentialBackoff) WithRetryPredicate(predicate func(error) bool) *ExponentialBackoff
- type Metrics
- type RetryableError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ExponentialBackoff ¶
type ExponentialBackoff struct {
// contains filtered or unexported fields
}
ExponentialBackoff implements retry logic with exponential backoff and jitter
func NewExponentialBackoff ¶
func NewExponentialBackoff(maxAttempts int, baseDelay time.Duration) *ExponentialBackoff
NewExponentialBackoff creates a new exponential backoff retryer
Parameters:
- maxAttempts: Maximum number of attempts (including initial try)
- baseDelay: Initial delay before first retry
The backoff formula is: delay = baseDelay * (2 ^ (attempt - 1)) + jitter Maximum delay is capped at 30 seconds by default.
func (*ExponentialBackoff) Do ¶
func (r *ExponentialBackoff) Do(ctx context.Context, operation func() error) error
Do executes an operation with retry logic
The operation function is called up to maxAttempts times. If it returns an error that passes the retry predicate, it will be retried with exponential backoff. Context cancellation is checked before each attempt.
Returns:
- nil if operation succeeds
- RetryableError if all attempts fail
- context error if context is canceled/timed out
func (*ExponentialBackoff) DoNamed ¶
func (r *ExponentialBackoff) DoNamed(ctx context.Context, operationName string, operation func() error) error
DoNamed is like Do but accepts an operation name for better error messages
func (*ExponentialBackoff) GetMetrics ¶
func (r *ExponentialBackoff) GetMetrics() Metrics
GetMetrics returns retry metrics
func (*ExponentialBackoff) ResetMetrics ¶
func (r *ExponentialBackoff) ResetMetrics()
ResetMetrics resets all metrics counters
func (*ExponentialBackoff) WithJitter ¶
func (r *ExponentialBackoff) WithJitter(ratio float64) *ExponentialBackoff
WithJitter sets the jitter ratio (0.0-1.0)
Jitter adds randomness to retry delays to prevent thundering herd problems when many clients retry simultaneously. A ratio of 0.2 adds up to 20% random variation.
func (*ExponentialBackoff) WithMaxDelay ¶
func (r *ExponentialBackoff) WithMaxDelay(maxDelay time.Duration) *ExponentialBackoff
WithMaxDelay sets the maximum delay between retries
func (*ExponentialBackoff) WithRetryPredicate ¶
func (r *ExponentialBackoff) WithRetryPredicate(predicate func(error) bool) *ExponentialBackoff
WithRetryPredicate sets a custom retry predicate function
The predicate receives an error and returns true if the error is retryable. By default, transient AWS errors are retried.
type Metrics ¶
type Metrics struct {
TotalOperations int64 // Total operations attempted
SuccessfulOps int64 // Operations that succeeded
FailedOps int64 // Operations that failed after all retries
SuccessRate float64 // Success rate (0.0-1.0)
TotalRetries int64 // Total number of retries across all operations
AvgRetries float64 // Average retries per operation
AttemptHistogram map[int]int64 // Attempts -> count distribution
}
Metrics contains retry performance metrics
type RetryableError ¶
type RetryableError struct {
Operation string
Attempt int
MaxAttempts int
LastError error
TotalDelay time.Duration
}
RetryableError wraps an error with retry information
func (*RetryableError) Error ¶
func (e *RetryableError) Error() string
func (*RetryableError) Unwrap ¶
func (e *RetryableError) Unwrap() error
Source Files