resilience.breaker — resilience-for-clojure 0.2.3

*breaker-name* clj

Contextual value represents circuit breaker name

*creation-time* clj

Contextual value represents event create time

circuit-breaker clj

(circuit-breaker name)

(circuit-breaker name config)

Create a circuit breaker with a name and a default or custom circuit breaker configuration.

The name argument is only used to register this newly created circuit breaker to a CircuitBreakerRegistry. If you don't want to bind this circuit breaker with a CircuitBreakerRegistry, the name argument is ignored.

Please refer to circuit-breaker-config for allowed key value pairs within the circuit breaker configurations map.

If you want to register this circuit breaker to a CircuitBreakerRegistry, you need to put :registry key with a CircuitBreakerRegistry in the config argument. If you do not provide any other configurations, the newly created circuit breaker will inherit circuit breaker configurations from this provided CircuitBreakerRegistry Example: (circuit-breaker my-breaker {:registry my-registry})

If you want to register this circuit breaker to a CircuitBreakerRegistry and you want to use new circuit breaker configurations to overwrite the configurations inherited from the registered CircuitBreakerRegistry, you need not only provide the :registry key with the CircuitBreakerRegistry in config argument but also provide other circuit breaker configurations you'd like to overwrite. Example: (circuit-breaker my-breaker {:registry my-registry :failure-rate-threshold 50.0 :ring-buffer-size-in-closed-state 30 :ring-buffer-size-in-half-open-state 20})

If you only want to create a circuit breaker and not register it to any CircuitBreakerRegistry, you just need to provide circuit breaker configurations in config argument. The name argument is ignored.

circuit-breaker-config clj

(circuit-breaker-config opts)

Create a CircuitBreakerConfig.

Allowed options are:

• :failure-rate-threshold Configures the failure rate threshold in percentage above which the circuit breaker should trip open and start short-circuiting calls. Must be a float/double. Default value is 50%.

• :wait-millis-in-open-state Configures the wait duration which specifies how long the circuit breaker should stay open, before it switches to half open. Default value is 60 seconds.

• :ring-buffer-size-in-half-open-state Configures the size of the ring buffer when the circuit breaker is half open. The circuit breaker stores the success/failure status of the latest calls in a ring buffer. For example, if :ring-buffer-size-in-half-open-state is 10, then at least 10 calls must be evaluated, before the failure rate can be calculated. If only 9 calls have been evaluated the CircuitBreaker will not trip back to closed or open even if all 9 calls have failed. The size must be greater than 0. Default size is 10.

• :ring-buffer-size-in-closed-state Configures the size of the ring buffer when the circuit breaker is closed. The circuit breaker stores the success/failure status of the latest calls in a ring buffer. For example, if :ring-buffer-size-in-closed-state is 100, then at least 100 calls must be evaluated, before the failure rate can be calculated. If only 99 calls have been evaluated the circuit breaker will not trip open even if all 99 calls have failed. The default size is 100.

• :record-failure Configures a function which take a throwable as argument and evaluates if an exception should be recorded as a failure and thus increase the failure rate. The predicate function must return true if the exception should count as a failure, otherwise it must return false.

• :record-exceptions Configures a list of error classes that are recorded as a failure and thus increase the failure rate. Any exception matching or inheriting from one of the list should count as a failure, unless ignored via :ignore-exceptions. Ignoring an exception has priority over recording an exception. Example: {:record-exceptions [Throwable] :ignore-exceptions [RuntimeException]} would capture all Errors and checked Exceptions, and ignore unchecked exceptions. For a more sophisticated exception management use the :record-failure option.

• :ignore-exceptions Configures a list of error classes that are ignored as a failure and thus do not increase the failure rate. Any exception matching or inheriting from one of the list will not count as a failure, even if marked via :record-exceptions. Ignoring an exception has priority over recording an exception. Example: {:ignore-exceptions [Throwable] :record-exceptions [Exception]} would capture nothing. Example: {:ignore-exceptions [Exception] :record-exceptions [Throwable]} would capture Errors. For a more sophisticated exception management use the :record-failure option.

• :automatic-transfer-from-open-to-half-open? Enables automatic transition from :OPEN to :HALF_OPEN state once the :wait-millis-in-open-state has passed.

config clj

(config breaker)

Returns the configurations of this CircuitBreaker

defbreaker clj macro

(defbreaker name)

(defbreaker name config)

Define a circuit breaker under name with a default or custom circuit breaker configuration.

Please refer to circuit-breaker-config for allowed key value pairs within the circuit breaker configuration.

If you want to register this circuit breaker to a CircuitBreakerRegistry, you need to put :registry key with a CircuitBreakerRegistry in the config argument. If you do not provide any other configurations, the newly created circuit breaker will inherit circuit breaker configurations from this provided CircuitBreakerRegistry Example: (defbreaker my-breaker {:registry my-registry})

If you want to register this circuit breaker to a CircuitBreakerRegistry and you want to use new circuit breaker configurations to overwrite the configurations inherited from the registered CircuitBreakerRegistry, you need not only provide the :registry key with the CircuitBreakerRegistry in config argument but also provide other circuit breaker configurations you'd like to overwrite. Example: (defbreaker my-breaker {:registry my-registry :failure-rate-threshold 50.0 :ring-buffer-size-in-closed-state 30 :ring-buffer-size-in-half-open-state 20})

If you only want to create a circuit breaker and not register it to any CircuitBreakerRegistry, you just need to provide circuit breaker configuration in config argument without :registry keyword.

defregistry clj macro

(defregistry name)

(defregistry name config)

Define a CircuitBreakerRegistry under name with a default or custom circuit breaker configuration.

Please refer to circuit-breaker-config for allowed key value pairs within the circuit breaker configuration map.

get-all-breakers clj

(get-all-breakers registry)

Get all circuit breakers registered to a CircuitBreakerRegistry

metrics clj

(metrics breaker)

Get the Metrics of this CircuitBreaker

name clj

(name breaker)

Get the name of this CircuitBreaker

on-error clj

(on-error breaker duration-in-nanos throwable)

Records a failed call. This method must be invoked when a call failed.

on-success clj

(on-success breaker duration-in-nanos)

Records a successful call.

registry-with-config clj

(registry-with-config config)

Create a CircuitBreakerRegistry with a circuit breaker configurations map.

Please refer to circuit-breaker-config for allowed key value pairs within the circuit breaker configuration map.

reset! clj

(reset! breaker)

Get the circuit breaker to its original closed state, losing statistics. Should only be used, when you want to want to fully reset the circuit breaker without creating a new one.

set-on-all-event-consumer! clj

(set-on-all-event-consumer! breaker consumer-fn-map)

set-on-call-not-permitted-consumer! clj

(set-on-call-not-permitted-consumer! breaker consumer-fn)

set-on-error-event-consumer! clj

(set-on-error-event-consumer! breaker consumer-fn)

set-on-ignored-error-event! clj

(set-on-ignored-error-event! breaker consumer-fn)

set-on-reset-event-consumer! clj

(set-on-reset-event-consumer! breaker consumer-fn)

set-on-state-transition-event-consumer! clj

(set-on-state-transition-event-consumer! breaker consumer-fn)

set-on-success-event-consumer! clj

(set-on-success-event-consumer! breaker consumer-fn)

state clj

(state breaker)

Get the state of the circuit breaker in keyword format. Currently, state can be one of :DISABLED, :CLOSED, :OPEN, :FORCED_OPEN, :HALF_OPEN

transition-to-closed-state! clj

(transition-to-closed-state! breaker)

Transitions the circuit breaker state machine to CLOSED state.

Should only be used, when you want to force a state transition. State transition are normally done internally.

transition-to-disabled-state! clj

(transition-to-disabled-state! breaker)

Transitions the circut breaker state machine to a DISABLED state, stopping state transition, metrics and event publishing.

Should only be used, when you want to disable the circuit breaker allowing all calls to pass. To recover from this state you must force a new state transition

transition-to-forced-open-state! clj

(transition-to-forced-open-state! breaker)

Transitions the state machine to a FORCED_OPEN state, stopping state transition, metrics and event publishing.

Should only be used, when you want to disable the circuit breaker allowing no call to pass. To recover from this state you must force a new state transition.

transition-to-half-open! clj

(transition-to-half-open! breaker)

Transitions the circuit breaker state machine to HALF_OPEN state.

Should only be used, when you want to force a state transition. State transition are normally done internally.

transition-to-open-state! clj

(transition-to-open-state! breaker)

Transitions the circuit breaker state machine to OPEN state.

Should only be used, when you want to force a state transition. State transition are normally done internally.