net.modulolotus.truegrit.circuit-breaker — net.modulolotus/truegrit 2.1.30

Implements circuit breakers, which keep track of fn failures and temporarily disable a fn when it fails too often.

See https://resilience4j.readme.io/docs/circuitbreaker

*default-config* clj

Set this to override the R4j defaults with your own

add-listeners clj

(add-listeners cb
               {:keys [on-event on-success on-error on-state-transition on-reset
                       on-ignored-error on-call-not-permitted
                       on-failure-rate-exceeded on-slow-call-rate-exceeded]})

Add event handlers for CircuitBreaker lifecycle events. Note that a call that succeeds on the first try will generate no events.

Config map options

• :on-event - a handler that runs for all events
• :on-success - a handler that runs after every successful call - receives a CircuitBreakerOnSuccessEvent
• :on-error - a handler that runs after every failed call - receives a CircuitBreakerOnErrorEvent
• :on-state-transition - a handler that runs after a state changed (OPEN, CLOSED, HALF_OPEN) - receives a CircuitBreakerOnStateTransitionEvent - breakers start in CLOSED
• :on-reset - a handler that runs after a manual reset - receives a CircuitBreakerOnResetEvent
• :on-ignored-error - a handler that runs after an error was ignored - receives a CircuitBreakerOnIgnoredErrorEvent
• :on-call-not-permitted - a handler that runs after a call was attempted, but the breaker forbid it - receives a CircuitBreakerOnCallNotPermittedEvent - NB: this can trigger on health checks, see call-allowed? for more
• :on-failure-rate-exceeded - a handler that runs after the failure rate is exceeded - receives a CircuitBreakerOnFailureRateExceededEvent
• :on-slow-call-rate-exceeded - a handler that runs after the slow call rate is exceeded - receives a CircuitBreakerOnSlowCallRateExceededEvent - NB: this can trigger on health checks, see call-allowed? for more

call-allowed? clj

(call-allowed? cb)

Is the circuit breaker healthy enough to allow a call?

Does not rely on the CB state (OPEN, CLOSED, etc), because state alone is insufficient to determine if a call is permitted.

E.g., HALF-OPEN has an internal counter of test calls, so it may or may not allow the next one. And, when :automatic-transition-from-open-to-half-open-enabled? is false (the default), the breaker will remain in the OPEN state past the waiting period until a call is made or permission is checked/requested, which can be misleading.

NB: r4j does not currently distinguish between checking and acquiring permissions. Therefore, calling this when it's not currently allowed will trigger a call-not-permitted event, even if you're not invoking the wrapped fn.

circuit-breaker clj

(circuit-breaker cb-name config)

Creates a CircuitBreaker with the given name and config.

circuit-breaker-config clj

(circuit-breaker-config config)

Creates a Resilience4j CircuitBreakerConfig.

Config map options

• :failure-rate-threshold - Percentage from 1 to 100 - if more than this percentage of calls have failed, go to OPEN - defaults to 50%
• :slow-call-rate-threshold - Percentage from 1 to 100 - if more than this percentage of calls are too slow, go to OPEN - defaults to 100%
• :slow-call-duration-threshold - How slow is too slow, even if the call succeeds? All calls exceeding this duration are treated as failures - defaults to 60000 ms - accepts number of ms or java.time.Duration
• :permitted-number-of-calls-in-half-open-state - # of calls to track when HALF-OPEN - defaults to 10
• :minimum-number-of-calls - # of calls to keep track of - will not go to OPEN unless at least this many calls have been made - defaults to 100
• :sliding-window-type - How the CB considers statistics. Either :count or :time. When count-based, examines the last n number of calls; when time-based, examines all calls from the last n seconds. (Time-based mimics Hystrix's behavior.) - defaults to :count
• :sliding-window-size - The meaning depends on :sliding-window-type. When count-based, it's the number of calls to record; when time-based, it's the number of seconds. - defaults to 100
• :max-wait-duration-in-half-open-state - How long to wait in HALF_OPEN before automatically switching to OPEN - 0 means wait until all calls have been completed - defaults to 0 ms - accepts number of ms or java.time.Duration
• :wait-duration-in-open-state - How long to wait in OPEN before allowing a call again - defaults to 60000 ms - accepts number of ms or java.time.Duration

Less common config map options

• :automatic-transition-from-open-to-half-open-enabled? - Should it automatically transition to HALF-OPEN after the wait duration, or only after a call or check is made? - NB: when false, an OPEN state may actually allow calls if the wait duration has passed and nobody has tried yet, so don't rely on state, use call-allowed? - defaults to false
• :record-exceptions - A coll of Throwables to record failure for - defaults to empty, which means all exceptions are recorded - :ignore-exceptions takes precedence over this
• :ignore-exceptions - A coll of Throwables to ignore - e.g., [IrrelevantException IgnoreThisException] - are not counted as either successes or failures - defaults to empty
• :record-exception - A 1-arg fn that tests a Throwable and returns true if it should be recorded as a failure, false if not - :ignore-exception predicate takes precedence
• :ignore-exception - A 1-arg fn that tests a Throwable and returns true if it should be ignored, false if not

metrics clj

(metrics cb)

Returns a map of metrics for the given circuit breaker.

Failure rate and slow call rate are percentages, unless insufficient calls have been made (i.e., below :minimum-number-of-calls), in which case it's -1.

Slow calls refer to calls that take a long time, but do not actually fail.

Metric key list:

• :failure-rate
• :number-of-buffered-calls - total number of calls in the metrics, "buffered" doesn't mean anything
• :number-of-failed-calls
• :number-of-not-permitted-calls - number of calls blocked by OPEN status - always 0 in CLOSED or HALF_OPEN status
• :number-of-slow-calls
• :number-of-slow-failed-calls
• :number-of-slow-successful-calls
• :number-of-successful-calls
• :slow-call-rate

Also see io.github.resilience4j.circuitbreaker.CircuitBreaker.Metrics

retrieve clj

(retrieve f)

Retrieves a circuit breaker from a wrapped fn

state-name clj

(state-name cb)

Returns a keyword of the current state of the CircuitBreaker.

One of: :closed, :open, :half-open, :forced-open, or :disabled

NB: Do not rely on the state to determine if a call can be made. Use call-allowed? instead.

wrap clj

(wrap f cb)

Wraps a function in a CircuitBreaker.

Attaches the circuit breaker as metadata on the wrapped fn at :truegrit/circuit-breaker