errors

cockroachdb/errors: Go errors with network portability

This library aims to be used as a drop-in replacement to github.com/pkg/errors and Go's standard errors package. It also provides network portability of error objects, in ways suitable for distributed systems with mixed-version software compatibility.

It also provides native and comprehensive support for PII-free details and an opt-in Sentry.io reporting mechanism that automatically formats error details and strips them of PII.

See also the design RFC.

Table of contents:

• Features
• How to use
• What comes out of an error?
• Available error leaves
• Available wrapper constructors
• Providing PII-free details
• Building your own error types
• Error composition (summary)
• API (not constructing error objects)

Features

"Forward compatibility" above refers to the ability of this library to recognize and properly handle network communication of error types it does not know about, for example when a more recent version of a software package sends a new error object to another system running an older version of the package.

How to use

• construct errors with errors.New(), etc as usual, but also see the other error leaf constructors below.
• wrap errors with errors.Wrap() as usual, but also see the other wrappers below.
• test error identity with errors.Is() as usual. Unique in this library: this works even if the error has traversed the network! Also, errors.IsAny() to recognize two or more reference errors.
• replace uses of os.IsPermission(), os.IsTimeout(), os.IsExist() and os.IsNotExist() by their analog in sub-package oserror so that they can peek through layers of wrapping.
• access error causes with errors.UnwrapOnce() / errors.UnwrapAll() (note: errors.Cause() and errors.Unwrap() also provided for compatibility with other error packages).
• encode/decode errors to protobuf with errors.EncodeError() / errors.DecodeError().
• extract PII-free safe details with errors.GetSafeDetails().
• extract human-facing hints and details with errors.GetAllHints()/errors.GetAllDetails() or errors.FlattenHints()/errors.FlattenDetails().
• produce detailed Sentry.io reports with errors.BuildSentryReport() / errors.ReportError().
• implement your own error leaf types and wrapper types:
  • implement the error and errors.Wrapper interfaces as usual.
  • register encode/decode functions: call errors.Register{Leaf,Wrapper}{Encoder,Decoder}() in a init() function in your package.
  • implement Format() that redirects to errors.FormatError().
  • see the section Building your own error types below.

What comes out of an error?

Available error leaves

An error leaf is an object that implements the error interface, but does not refer to another error via a Unwrap() or Cause() method.

• New(string) error, Newf(string, ...interface{}) error, Errorf(string, ...interface{}) error: leaf errors with message

  • when to use: common error cases.
  • what it does: also captures the stack trace at point of call and redacts the provided message for safe reporting.
  • how to access the detail: Error(), regular Go formatting. Details in Sentry report.
  • see also: Section Error composition below. errors.NewWithDepth() variants to customize at which call depth the stack trace is captured.

• AssertionFailedf(string, ...interface{}) error, NewAssertionFailureWithWrappedErrf(error, string, ...interface{}) error: signals an assertion failure / programming error.

  • when to use: when an invariant is violated; when an unreachable code path is reached.
  • what it does: also captures the stack trace at point of call, redacts the provided strings for safe reporting, prepares a hint to inform a human user.
  • how to access the detail: IsAssertionFailure()/HasAssertionFailure(), format with %+v, Safe details included in Sentry reports.
  • see also: Section Error composition below. errors.AssertionFailedWithDepthf() variant to customize at which call depth the stack trace is captured.

• Handled(error) error, Opaque(error) error, HandledWithMessage(error, string) error: captures an error cause but make it invisible to `Unwrap(