org.apache.cassandra.db.guardrails

Class Threshold

java.lang.Object

org.apache.cassandra.db.guardrails.Guardrail

org.apache.cassandra.db.guardrails.Threshold

Direct Known Subclasses:

MaxThreshold, MinThreshold

public abstract class Threshold
extends Guardrail

A guardrail based on numeric threshold(s).

A Threshold guardrail defines (up to) 2 thresholds, one at which a warning is issued, and a lower one at which the operation is aborted with an exception. Only one of those thresholds can be activated if desired.

This guardrail only handles guarding positive values.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.function.ToLongFunction<ClientState>	failThreshold
protected org.apache.cassandra.db.guardrails.Threshold.ErrorMessageProvider	messageProvider
protected java.util.function.ToLongFunction<ClientState>	warnThreshold

Fields inherited from class org.apache.cassandra.db.guardrails.Guardrail

logger, name, REDACTED

Constructor Summary

Constructors

Constructor and Description
Threshold(java.lang.String name, java.util.function.ToLongFunction<ClientState> warnThreshold, java.util.function.ToLongFunction<ClientState> failThreshold, org.apache.cassandra.db.guardrails.Threshold.ErrorMessageProvider messageProvider) Creates a new threshold guardrail.

Method Summary

Modifier and Type	Method and Description
protected abstract boolean	compare(long value, long threshold)
boolean	enabled(ClientState state) Checks whether this guardrail is enabled or not.
protected java.lang.String	errMsg(boolean isWarning, java.lang.String what, long value, long thresholdValue)
boolean	failsOn(long value, ClientState state)
protected abstract long	failValue(ClientState state)
void	guard(long value, java.lang.String what, boolean containsUserData, ClientState state) Apply the guardrail to the provided value, warning or failing if appropriate.
boolean	triggersOn(long value, ClientState state) Checks whether the provided value would trigger a warning or failure if passed to guard(long, java.lang.String, boolean, org.apache.cassandra.service.ClientState).
boolean	warnsOn(long value, ClientState state)
protected abstract long	warnValue(ClientState state)

Methods inherited from class org.apache.cassandra.db.guardrails.Guardrail

enabled, fail, fail, warn, warn

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

warnThreshold

protected java.util.function.ToLongFunction<ClientState> warnThreshold

failThreshold

protected java.util.function.ToLongFunction<ClientState> failThreshold

messageProvider

protected final org.apache.cassandra.db.guardrails.Threshold.ErrorMessageProvider messageProvider

Constructor Detail

Threshold

public Threshold(java.lang.String name,
                 java.util.function.ToLongFunction<ClientState> warnThreshold,
                 java.util.function.ToLongFunction<ClientState> failThreshold,
                 org.apache.cassandra.db.guardrails.Threshold.ErrorMessageProvider messageProvider)

Creates a new threshold guardrail.

Parameters:

name - the identifying name of the guardrail

warnThreshold - a ClientState-based provider of the value above which a warning should be triggered.

failThreshold - a ClientState-based provider of the value above which the operation should be aborted.

messageProvider - a function to generate the warning or error message if the guardrail is triggered

Method Detail

compare

protected abstract boolean compare(long value,
                                   long threshold)

errMsg

protected java.lang.String errMsg(boolean isWarning,
                                  java.lang.String what,
                                  long value,
                                  long thresholdValue)

failValue

protected abstract long failValue(ClientState state)

warnValue

protected abstract long warnValue(ClientState state)

enabled

public boolean enabled(@Nullable
                       ClientState state)

Description copied from class: Guardrail

Checks whether this guardrail is enabled or not. This will be enabled if the database is initialized and the authenticated user (if specified) is not system nor superuser.

Overrides:

enabled in class Guardrail

Parameters:

state - the client state, used to skip the check if the query is internal or is done by a superuser. A null value means that the check should be done regardless of the query.

Returns:

true if this guardrail is enabled, false otherwise.

triggersOn

public boolean triggersOn(long value,
                          @Nullable
                          ClientState state)

Checks whether the provided value would trigger a warning or failure if passed to guard(long, java.lang.String, boolean, org.apache.cassandra.service.ClientState).

This method is optional (does not have to be called) but can be used in the case where the "what" argument to guard(long, java.lang.String, boolean, org.apache.cassandra.service.ClientState) is expensive to build to save doing so in the common case (of the guardrail not being triggered).

Parameters:

value - the value to test.

state - The client state, used to skip the check if the query is internal or is done by a superuser. A null value means that the check should be done regardless of the query.

Returns:

true if value is above the warning or failure thresholds of this guardrail, false otherwise.

warnsOn

public boolean warnsOn(long value,
                       @Nullable
                       ClientState state)

failsOn

public boolean failsOn(long value,
                       @Nullable
                       ClientState state)

guard

public void guard(long value,
                  java.lang.String what,
                  boolean containsUserData,
                  @Nullable
                  ClientState state)

Apply the guardrail to the provided value, warning or failing if appropriate.

Parameters:

value - The value to check.

what - A string describing what value is a value of. This is used in the error message if the guardrail is triggered. For instance, say the guardrail guards the size of column values, then this argument must describe which column of which row is triggering the guardrail for convenience.

containsUserData - whether the what contains user data that should be redacted on external systems.

state - The client state, used to skip the check if the query is internal or is done by a superuser. A null value means that the check should be done regardless of the query.