the owner class of this sentry
name of the resource
target success ratio, 0 < targetSuccessRatio < 1
, defaults to 0.95D
the time between calculations of the current throughput, defaults to 1 second
the minimum number of invocations that must be observed per evaluationDelay
before invocations are throttled, defaults to 0
(>=0)
factor to apply to current throughput ratio, successIncreaseFactor > 1
, defaults to 1.2D
the minimum duration for a failed invocation to be counted as failed,
for backward compatibility this defaults to 0 milliseconds. A better default would be a small number,
e.g. 1 millisecond
.
Composes two instances of Sentry in a new Sentry, with this sentries context applied first.
Composes two instances of Sentry in a new Sentry, with this sentries context applied first.
a new sentry t such that t(x) == s(this(x))
Run the given code block in the context of this sentry, and return its value.
Run the given code block in the context of this sentry, and return its value.
Composes two instances of Sentry in a new Sentry, with this sentries context applied last.
Composes two instances of Sentry in a new Sentry, with this sentries context applied last.
a new sentry t such that t(x) == this(s(x))
the time between calculations of the current throughput, defaults to 1 second
The current fail ratio (0 <= ratio <= 1).
the minimum duration for a failed invocation to be counted as failed, for backward compatibility this defaults to 0 milliseconds.
the minimum duration for a failed invocation to be counted as failed,
for backward compatibility this defaults to 0 milliseconds. A better default would be a small number,
e.g. 1 millisecond
.
the minimum number of invocations that must be observed per evaluationDelay
before invocations are throttled, defaults to 0
(>=0)
Go back to the initial state.
Go back to the initial state.
name of the resource
name of the resource
a simple describing identifier that is unique per sentry chain, e.g. "rateLimit".
ResourceName
plus sentryType
uniquely name each sentry. The sentry registry
enforces this. The sentryType
is also used in JMX to uniquely name bean properties
for a resource.
null
for sentry wrappers, that must not be registered.
target success ratio, 0 < targetSuccessRatio < 1
, defaults to 0.95D
The current throughput ratio (0 <= ratio <= 1).
Reduce throughput to 0.
A sentry that adapts throughput with the success ratio of invoking the protected resource. Think of it as a gradual circuit breaker.
The goal of this sentry is to protect the caller from a resource that slows down, or starts to produce errors when overloaded. By reducing throughput until success ratio is at an expected level, the resource can recover and work at its optimal efficiency.
For resources that behave correct most of the time, the target success ratio can be set quite high, e.g.
0.95
. When exceptions are more 'normal', you may have to lower this parameter.The success ratio is calculated per
evaluationDelay
with a simple1 - (fail count / success count)
. When the success ratio is belowtargetSuccessRatio
, the throughput is reduced tocurrentSuccessRatio * currentThroughputRatio
. When the success ratio is again equal to or above the target ratio, throughput is increased bysuccessIncreaseFactor
(defaults to +20%) with a minimum of 0.0001D (1 in thousand calls may proceed). Note that regardless of thecurrentThroughputRatio
, at least 1 call per evaluation period is allowed to continue.This sentry only makes sense for high volume resources. To prevent throttling in low volume times, it is possible to set the minimum number of invocations that must be observed per
evaluationDelay
before throttling takes place. (see theminimumInvocationCountThreshold
parameter).It does not make sense to throttle on fast failing invocations. In those cases its better to get the exception from the underlying resource then to get a ReducedThroughputException. Parameter
failedInvocationDurationThreshold
sets the minimum duration of failed invocation in order for those invocations to be counted as failed. By setting this value to a non-zero value, fast failures do not reduce throughput. (Note that the default is0
for backward compatibility.)When there is a calamity, this sentry only reacts as fast as the given
evaluationDelay
(1 second by default). When the resource becomes fully available, it takes at most 39 evaluation before throughput is back at 100%. You can test this by evaluating the following code in a Scala REPL:A new instance can be obtained through the nl.grons.sentries.SentrySupport mixin.