Package 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 Details

    • warnThreshold

      protected ToLongFunction<ClientState> warnThreshold

    • failThreshold

      protected ToLongFunction<ClientState> failThreshold

    • messageProvider

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

  • Constructor Details

    • Threshold

      public Threshold(String name, @Nullable String reason, ToLongFunction<ClientState> warnThreshold, ToLongFunction<ClientState> failThreshold, org.apache.cassandra.db.guardrails.Threshold.ErrorMessageProvider messageProvider)
      Creates a new threshold guardrail.
      Parameters:
      name - the identifying name of the guardrail
      reason - the optional description of the reason for guarding the operation
      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 Details

    • compare

      protected abstract boolean compare(long value, long threshold)

    • errMsg

      protected String errMsg(boolean isWarning, 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, 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.