Package com.google.gerrit.server

Interface ExceptionHook

All Known Implementing Classes:
ExceptionHookImpl
public interface ExceptionHook
Allows implementors to control how certain exceptions should be handled.

This interface is intended to be implemented for cluster setups with multiple primary nodes to control the behavior for handling exceptions that are thrown by a lower layer that handles the consensus and synchronization between different server nodes. E.g. if an operation fails because consensus for a Git update could not be achieved (e.g. due to slow responding server nodes) this interface can be used to retry the request instead of failing it immediately.

  • Method Details

    • shouldRetry

      default boolean shouldRetry(String actionType, String actionName, Throwable throwable)
      Whether an operation should be retried if it failed with the given throwable.

      Only affects operations that are executed with RetryHelper.

      Should return true only for exceptions that are caused by temporary issues where a retry of the operation has a chance to succeed.

      If false is returned the operation is still retried once to capture a trace, unless skipRetryWithTrace(String, String, Throwable) skips the auto-retry.

      If multiple exception hooks are registered, the operation is retried if any of them returns true from this method.

      Parameters:
      throwable - throwable that was thrown while executing the operation
      actionType - the type of the action for which the exception occurred
      actionName - the name of the action for which the exception occurred
      Returns:
      whether the operation should be retried

    • skipRetryWithTrace

      default boolean skipRetryWithTrace(String actionType, String actionName, Throwable throwable)
      Whether auto-retrying of an operation with tracing should be skipped for the given throwable.

      Only affects operations that are executed with RetryHelper.

      This method is only called for exceptions for which the operation should not be retried (shouldRetry(String, String, Throwable) returned false).

      By default this method returns false, so that by default traces for unexpected exceptions are captured, which allows to investigate them.

      Implementors may use this method to skip retry with tracing for exceptions that occur due to known causes that are permanent and where a trace is not needed for the investigation. For example, if an operation fails because persisted data is corrupt, it makes no sense to retry the operation with a trace, because the trace will not help with fixing the corrupt data.

      This method is only invoked if retry with tracing is enabled on the server ( retry.retryWithTraceOnFailure in gerrit.config is set to true).

      If multiple exception hooks are registered, retrying with tracing is skipped if any of them returns true from this method.

      Parameters:
      throwable - throwable that was thrown while executing the operation
      actionType - the type of the action for which the exception occurred
      actionName - the name of the action for which the exception occurred
      Returns:
      whether auto-retrying of an operation with tracing should be skipped for the given throwable

    • formatCause

      default Optional<String> formatCause(Throwable throwable)
      Formats the cause of an exception for use in metrics.

      This method allows implementors to group exceptions that have the same cause into one metric bucket.

      If multiple exception hooks return a value from this method, the value from the exception hook that is registered first is used.

      Parameters:
      throwable - the exception cause
      Returns:
      formatted cause or Optional.empty() if no formatting was done

    • getUserMessages

      default com.google.common.collect.ImmutableList<String> getUserMessages(Throwable throwable, String traceId)
      Returns messages that should be returned to the user.

      These messages are included into the HTTP response that is sent to the user.

      If multiple exception hooks return a value from this method, all the values are included into the HTTP response (in the order in which the exception hooks are registered).

      Parameters:
      throwable - throwable that was thrown while executing an operation
      traceId - ID of the trace if this request was traced, otherwise null
      Returns:
      error messages that should be returned to the user, Optional.empty() if no message should be returned to the user

    • getStatus

      default Optional<ExceptionHook.Status> getStatus(Throwable throwable)
      Returns the HTTP status that should be returned to the user.

      Implementors may use this method to change the status for certain exceptions (e.g. using this method it would be possible to return 503 Lock failure for LockFailureExceptions instead of 500 Internal server error).

      If no value is returned (Optional.empty()) it means that this exception hook doesn't want to change the default response code for the given exception which is 500 Internal Server Error, but is fine if other exception hook implementation do so.

      If multiple exception hooks return a value from this method, the value from exception hook that is registered first is used.

      getUserMessages(Throwable, String) allows to define which additional messages should be included into the body of the HTTP response.

      Parameters:
      throwable - throwable that was thrown while executing an operation
      Returns:
      HTTP status that should be returned to the user, Optional.empty() if the exception should result in 500 Internal Server Error