circuitbreaker
The library's main abstraction, representing protection of an effectful program.
The library's main abstraction, representing protection of an effectful
program. The API is relatively simple, consisting of one primary function, protect,
which takes the program to protect and returns that an enhanced version of that program
having the ability to fail fast without invoking the underlying service if conditions
warrant, ensuring failure of the service it represents does not result in a cascade
of failure. The CircuitBreaker has two secondary
functions: 1.) currentStatistics, which provides the current statistics.Statistics
for use by monitoring and dashboarding applications and; 2.) lastActivity which provides
the java.time.Instant timestamp indicating the instant the CircuitBreaker was last active.
The CircuitBreaker is not generally directly instantiated; rather, a CircuitBreaker is requested
from the CircuitBreakerRegistry via the CircuitBreakerRegistry#forFailure function which
provides a variant that trips/opens given a configured percentage of protected program failures within a
configured time period or via the CircuitBreakerRegistry#forFlowControl function which provides a
variant that, in addition to the failure protected just described, also throttles requests when the
average rate of requests over a configured time period is greater than the observed
average rate of processing for the protected program.
- the type of effectful program.
Provides syntax enrichment on the effectful program F[A] so that
one can write, for example, prg.protect(circuitBreaker) rather than
circuitBreaker.protect(prg).
Provides syntax enrichment on the effectful program F[A] so that
one can write, for example, prg.protect(circuitBreaker) rather than
circuitBreaker.protect(prg). This can lead to less awkward code
under certain circumstances.
The circuit breaker registry maintains the non-persistent collection of CircuitBreakers created for a given virtual machine.
The circuit breaker registry maintains the non-persistent collection of CircuitBreakers created
for a given virtual machine. It provides the means to create and retrieve circuit breakers and to
subscribe to fs2.Streams of statistics.Statistics and CircuitBreaker#CircuitBreakerEvent
state change events. A CircuitBreakerRegistry instance is not directly instantiated but rather
created via the smart constructor in the companion object. The effectful program types protected
by the CircuitBreakers created and maintained with this registry are fixed by an F where an
instance of Effect[F] is provided in implicit scope.
The configuration which controls the failure-based CircuitBreakers (that is, those circuit breakers which are created via the CircuitBreakerRegistry#forFailure function).
The configuration which controls the failure-based CircuitBreakers (that is, those circuit breakers which are created via the CircuitBreakerRegistry#forFailure function).
- the time-based window to be used to constrain the number of program execution
success/failure indicators to store in order to determine the percentage of failures over this
time period. An example would be SampleWindow(2.minutes) which means maintain the last two minutes
of program execution success/failure indicators for a program protected by a given CircuitBreaker.
- the Percentage of items within the sample window which indicate program
failure. For instance, if the percentage were Percentage(40.0) and there were 50 sample items in the
2 minute window, with 25 indicating program failure, then since 50% is greater than 40%, the circuit breaker
would open.
- the testing configuration is used when the circuit breaker is open in order to determine how often a program should be executed rather than failed fast and then how many consecutively successful test executions need to occur in order to close the circuit breaker and allow normal operation of the protected program.
- The CircuitBreaker can be enabled or disabled with this parameter.
The configuration which controls the flow control-based CircuitBreakers (that is, those circuit breakers which are created via the CircuitBreakerRegistry#forFlowControl function).
The configuration which controls the flow control-based CircuitBreakers (that is, those circuit breakers which are created via the CircuitBreakerRegistry#forFlowControl function).
- the configuration for the failure component of the flow control CircuitBreaker. In addition to providing flow control, it also provides the same failure functionality as its failure-only variant.
- the time-based window to be used to constrain the number of inbound program execution requests per second and program executions processed per second. The flow control circuit breaker maintains two separate collections (the inbound rate and the processing/completed rate) and both use this sample window configuration to constrain the sizes of these collections.
- the Percentage that the mean inbound rate is allowed to exceed the mean processing rate before this circuit breaker starts throttling inbound requests to lower it to an acceptable rate. Put another way, the acceptable rate is the processing rate + (processing rate * percentage / 100).
- this is the percent that the calculated acceptable rate must be observed to have changed (either lower or higher) before a state change event is triggered. If it is 0, all state changes result in an event. This configuration item is meant to alleviate a flood of events when the request traffic pattern is very choppy (lots of spikes and valleys in a short time period).
- this is the minimum observed inbound rate at which flow control throttling will kick in.
- this is the hard limit of the inbound requests per second above which requests will be throttled by the circuit breaker (failed fast without execution) for the remainder of the current second. It will be monitored and acted upon continuously.
- The flow control portion of the CircuitBreaker can be enabled or disabled with this parameter.
Represents a percentage value, used throughout the library.
The configuration used for the CircuitBreakerRegistry - it defines how often the registry should examine the CircuitBreakers under its control to remove instances which have been inactive longer than the configured cut-off time.
The configuration used for the CircuitBreakerRegistry - it defines how often the
registry should examine the CircuitBreakers under its control to remove instances
which have been inactive longer than the configured cut-off time. If the checkInterval
property of the RegistrySettings#GarbageCollection configuration item is set to a
0 value (e.g., 0.milliseconds), this feature will then be disabled.
Represents a window of time, defined by the duration property and
used to constrain the number of time-stamped sample items retained in order
to calculate statistics for deriving CircuitBreaker state changes.
Represents a window of time, defined by the duration property and
used to constrain the number of time-stamped sample items retained in order
to calculate statistics for deriving CircuitBreaker state changes. A
hard limit of the number of samples is defined by the maximumEntries
property.
The companion object for a CircuitBreaker instance.
The companion object for a CircuitBreaker instance. The smart constructors for creation of failure and flow control
CircuitBreaker instances live here, as do common data types used by CircuitBreaker instances.
The companion object to the CircuitBreakerRegistry - contains a smart constructor for registry creation,
optionally registering a garbage collector to reap CircuitBreakers managed by the registry when they
have not been accessed for a configured period of time.
The companion object to the CircuitBreakerRegistry - contains a smart constructor for registry creation,
optionally registering a garbage collector to reap CircuitBreakers managed by the registry when they
have not been accessed for a configured period of time. The companion also defines private data types used
internally by the registry.
The circuitbreaker library provides protection against cascading failure and system overload via the CircuitBreaker and its primary function CircuitBreaker#protect. A CircuitBreakerRegistry maintains the collection of active circuit breakers and is the interface through which circuit breakers are created, retrieved, and removed and by which clients can subscribe for state change and statistics events related to the circuit breakers.