• Stars
    star
    1,869
  • Rank 23,815 (Top 0.5 %)
  • Language
    Go
  • License
    Apache License 2.0
  • Created almost 5 years ago
  • Updated 6 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Go error library with error portability over the network

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.

Build Status Go Reference

Table of contents:

Features

Feature Go's <1.13 errors github.com/pkg/errors Go 1.13 errors/xerrors cockroachdb/errors
error constructors (New, Errorf etc) ✔ ✔ ✔ ✔
error causes (Cause / Unwrap) ✔ ✔ ✔
cause barriers (Opaque / Handled) ✔ ✔
errors.As(), errors.Is() ✔ ✔
automatic error wrap when format ends with : %w ✔ ✔
standard wrappers with efficient stack trace capture ✔ ✔
transparent protobuf encode/decode with forward compatibility ✔
errors.Is() recognizes errors across the network ✔
comprehensive support for PII-free reportable strings ✔
support for both Cause() and Unwrap() go#31778 ✔
standard error reports to Sentry.io ✔
wrappers to denote assertion failures ✔
wrappers with issue tracker references ✔
wrappers for user-facing hints and details ✔
wrappers to attach secondary causes ✔
wrappers to attach logtags details from context.Context ✔
errors.FormatError(), Formatter, Printer (under construction) ✔
errors.SafeFormatError(), SafeFormatter ✔
wrapper-aware IsPermission(), IsTimeout(), IsExist(), IsNotExist() ✔

"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?

Error detail Error() and format %s/%q/%v format %+v GetSafeDetails() Sentry report via ReportError()
main message, eg New() visible visible yes (CHANGED IN v1.6) full (CHANGED IN v1.6)
wrap prefix, eg WithMessage() visible (as prefix) visible yes (CHANGED IN v1.6) full (CHANGED IN v1.6)
stack trace, eg WithStack() not visible simplified yes full
hint , eg WithHint() not visible visible no type only
detail, eg WithDetail() not visible visible no type only
assertion failure annotation, eg WithAssertionFailure() not visible visible no type only
issue links, eg WithIssueLink(), UnimplementedError() not visible visible yes full
safe details, eg WithSafeDetails() not visible not visible yes full
telemetry keys, eg. WithTelemetryKey() not visible visible yes full
secondary errors, eg. WithSecondaryError(), CombineErrors() not visible visible redacted, recursively redacted, recursively
barrier origins, eg. Handled() not visible visible redacted, recursively redacted, recursively
error domain, eg. WithDomain() not visible visible yes full
context tags, eg. WithContextTags() not visible visible keys visible, values redacted keys visible, values redacted

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() / Is().

    • when to use: when a new error occurs while handling an error, and the original error must be "hidden".
    • what it does: captures the cause in a hidden field. The error message is preserved unless the ...WithMessage() variant is used.
    • how to access the detail: format with %+v, redacted details reported in Sentry reports.
  • UnimplementedError(IssueLink, string) error: captures a message string and a URL reference to an external resource to denote a feature that was not yet implemented.

    • when to use: to inform (human) users that some feature is not implemented yet and refer them to some external resource.
    • what it does: captures the message, URL and detail in a wrapper. The URL and detail are considered safe for reporting.
    • how to access the detail: errors.GetAllHints(), errors.FlattenHints(), format with %+v, URL and detail included in Sentry report (not the message).
    • see also: errors.WithIssueLink() below for errors that are not specifically about unimplemented features.

Available wrapper constructors

An error wrapper is an object that implements the error interface, and also refers to another error via an Unwrap() (preferred) and/or Cause() method.

All wrapper constructors can be applied safely to a nil error: they behave as no-ops in this case:

// The following:
// if err := foo(); err != nil {
//    return errors.Wrap(err, "foo")
// }
// return nil
//
// is not needed. Instead, you can use this:
return errors.Wrap(foo(), "foo")
  • Wrap(error, string) error, Wrapf(error, string, ...interface{}) error:

    • when to use: on error return paths.
    • what it does: combines WithMessage(), WithStack(), WithSafeDetails().
    • how to access the details: Error(), regular Go formatting. Details in Sentry report.
    • see also: Section Error composition below. WrapWithDepth() variants to customize at which depth the stack trace is captured.
  • WithSecondaryError(error, error) error: annotate an error with a secondary error.

    • when to use: when an additional error occurs in the code that is handling a primary error. Consider using errors.CombineErrors() instead (see below).
    • what it does: it captures the secondary error but hides it from errors.Is().
    • how to access the detail: format with %+v, redacted recursively in Sentry reports.
    • see also: errors.CombineErrors()
  • CombineErrors(error, error) error: combines two errors into one.

    • when to use: when two operations occur concurrently and either can return an error, and only one final error must be returned.
    • what it does: returns either of its arguments if the other is nil, otherwise calls WithSecondaryError().
    • how to access the detail: see WithSecondaryError() above.
  • Mark(error, error) error: gives the identity of one error to another error.

    • when to use: when a caller expects to recognize a sentinel error with errors.Is() but the callee provides a diversity of error messages.
    • what it does: it overrides the "error mark" used internally by errors.Is().
    • how to access the detail: format with %+v, Sentry reports.
  • WithStack(error) error: annotate with stack trace

    • when to use: usually not needed, use errors.Wrap()/errors.Wrapf() instead.

      Special cases:

      • when returning a sentinel, for example:

        var myErr = errors.New("foo")
        
        func myFunc() error {
          if ... {
             return errors.WithStack(myErr)
          }
        }
      • on error return paths, when not trivial but also not warranting a wrap. For example:

        err := foo()
        if err != nil {
          doSomething()
          if !somecond {
             return errors.WithStack(err)
          }
        }
    • what it does: captures (efficiently) a stack trace.

    • how to access the details: format with %+v, errors.GetSafeDetails(), Sentry reports. The stack trace is considered safe for reporting.

    • see also: WithStackDepth() to customize the call depth at which the stack trace is captured.

  • WithSafeDetails(error, string, ...interface{}) error: safe details for reporting.

    • when to use: probably never. Use errors.Wrap()/errors.Wrapf() instead.
    • what it does: saves some strings for safe reporting.
    • how to access the detail: format with %+v, errors.GetSafeDetails(), Sentry report.
  • WithMessage(error, string) error, WithMessagef(error, string, ...interface{}) error: message prefix.

    • when to use: probably never. Use errors.Wrap()/errors.Wrapf() instead.
    • what it does: adds a message prefix.
    • how to access the detail: Error(), regular Go formatting, Sentry Report.
  • WithDetail(error, string) error, WithDetailf(error, string, ...interface{}) error, user-facing detail with contextual information.

    • when to use: need to embark a message string to output when the error is presented to a developer.
    • what it does: captures detail strings.
    • how to access the detail: errors.GetAllDetails(), errors.FlattenDetails() (all details are preserved), format with %+v. Not included in Sentry reports.
  • WithHint(error, string) error, WithHintf(error, string, ...interface{}) error: user-facing detail with suggestion for action to take.

    • when to use: need to embark a message string to output when the error is presented to an end user.
    • what it does: captures hint strings.
    • how to access the detail: errors.GetAllHints(), errors.FlattenHints() (hints are de-duplicated), format with %+v. Not included in Sentry reports.
  • WithIssueLink(error, IssueLink) error: annotate an error with an URL and arbitrary string.

    • when to use: to refer (human) users to some external resources.
    • what it does: captures the URL and detail in a wrapper. Both are considered safe for reporting.
    • how to access the detail: errors.GetAllHints(), errors.FlattenHints(), errors.GetSafeDetails(), format with %+v, Sentry report.
    • see also: errors.UnimplementedError() to construct leaves (see previous section).
  • WithTelemetry(error, string) error: annotate an error with a key suitable for telemetry.

    • when to use: to gather strings during error handling, for capture in the telemetry sub-system of a server package.
    • what it does: captures the string. The telemetry key is considered safe for reporting.
    • how to access the detail: errors.GetTelemetryKeys(), errors.GetSafeDetails(), format with %+v, Sentry report.
  • WithDomain(error, Domain) error, HandledInDomain(error, Domain) error, HandledInDomainWithMessage(error, Domain, string) error (experimental): annotate an error with an origin package.

    • when to use: at package boundaries.
    • what it does: captures the identity of the error domain. Can be asserted with errors.EnsureNotInDomain(), errors.NotInDomain().
    • how to access the detail: format with %+v, Sentry report.
  • WithAssertionFailure(error) error: annotate an error as being an assertion failure.

    • when to use: probably never. Use errors.AssertionFailedf() and variants.
    • what it does: wraps the error with a special type. Triggers an auto-generated hint.
    • how to access the detail: IsAssertionFailure()/HasAssertionFailure(), errors.GetAllHints(), errors.FlattenHints(), format with %+v, Sentry report.
  • WithContextTags(error, context.Context) error: annotate an error with the k/v pairs attached to a context.Context instance with the logtags package.

    • when to use: when capturing/producing an error and a context.Context is available.
    • what it does: it captures the logtags.Buffer object in the wrapper.
    • how to access the detail: errors.GetContextTags(), format with %+v, Sentry reports.

Providing PII-free details

The library support PII-free strings essentially as follows:

  • by default, many strings included in an error object are considered to be PII-unsafe, and are stripped out when building a Sentry report.
  • some fields in the library are assumed to be PII-safe by default.
  • you can opt additional strings in to Sentry reports.

The following strings from this library are considered to be PII-free, and thus included in Sentry reports automatically:

  • the type of error objects,
  • stack traces (containing only file paths, line numbers, function names - arguments are not included),
  • issue tracker links (including URL and detail field),
  • telemetry keys,
  • error domains,
  • context tag keys,
  • the format string argument of Newf, AssertionFailedf, etc (the constructors ending with ...f()),
  • the type of the additional arguments passed to the ...f() constructors,
  • the value of specific argument types passed to the ...f() constructors, when known to be PII-safe. For details of which arguments are considered PII-free, see the redact package.

It is possible to opt additional in to Sentry reporting, using either of the following methods:

  • implement the errors.SafeDetailer interface, providing the SafeDetails() []string method on your error type.

  • enclose additional arguments passed to the ...f() constructors with errors.Safe(). For example: err := errors.Newf("my code: %d", errors.Safe(123)) — in this example, the value 123 will be included when a Sentry report is constructed.

    • it also makes it available via errors.GetSafeDetails()/GetAllSafeDetails().
    • the value 123 is also part of the main error message returned by Error().
  • attach additional arbitrary strings with errors.WithSafeDetails(error, string, ...interface{}) error and also use errors.Safe(). For example: err = errors.WithSafeDetails(err, "additional data: %s", errors.Safe("hello")).

    • in this example, the string "hello" will be included in Sentry reports.
    • however, it is not part of the main error message returned by Error().

For more details on how Sentry reports are built, see the report sub-package.

Building your own error types

You can create an error type as usual in Go: implement the error interface, and, if your type is also a wrapper, the errors.Wrapper interface (an Unwrap() method). You may also want to implement the Cause() method for backward compatibility with github.com/pkg/errors, if your project also uses that.

If your error type is a wrapper, you should implement a Format() method that redirects to errors.FormatError(), otherwise %+v will not work. Additionally, if your type has a payload not otherwise visible via Error(), you may want to implement errors.SafeFormatter. See making %+v work with your type below for details.

Finally, you may want your new error type to be portable across the network.

If your error type is a leaf, and already implements proto.Message (from gogoproto), you are all set and the errors library will use that automatically. If you do not or cannot implement proto.Message, or your error type is a wrapper, read on.

At a minimum, you will need a decoder function: while cockroachdb/errors already does a bunch of encoding/decoding work on new types automatically, the one thing it really cannot do on its own is instantiate a Go object using your new type.

Here is the simplest decode function for a new leaf error type and a new wrapper type:

// note: we use the gogoproto `proto` sub-package.
func yourDecode(_ string, _ []string, _ proto.Message) error {
   return &yourType{}
}

func init() {
   errors.RegisterLeafEncoder((*yourType)(nil), yourDecodeFunc)
}

func yourDecodeWrapper(cause error, _ string, _ []string, _ proto.Message) error {
   // Note: the library already takes care of encoding/decoding the cause.
   return &yourWrapperType{cause: cause}
}

func init() {
   errors.RegisterWrapperDecoder((*yourWrapperType)(nil), yourDecodeWrapper)
}

In the case where your type does not have any other field (empty struct for leafs, just a cause for wrappers), this is all you have to do.

(See the type withAssertionFailure in assert/assert.go for an example of this simple case.)

If your type does have additional fields, you may still not need a custom encoder. This is because the library automatically encodes/decodes the main error message and any safe strings that your error types makes available via the errors.SafeDetailer interface (the SafeDetails() method).

Say, for example, you have the following leaf type:

type myLeaf struct {
   code int
}

func (m *myLeaf) Error() string { return fmt.Sprintf("my error: %d" + m.code }

In that case, the library will automatically encode the result of calling Error(). This string will then be passed back to your decoder function as the first argument. This makes it possible to decode the code field exactly:

func myLeafDecoder(msg string, _ []string, _ proto.Message) error {
	codeS := strings.TrimPrefix(msg, "my error: ")
	code, _ := strconv.Atoi(codeS)
	// Note: error handling for strconv is omitted here to simplify
	// the explanation. If your decoder function should fail, simply
	// return a `nil` error object (not another unrelated error!).
	return &myLeaf{code: code}
}

Likewise, if your fields are PII-free, they are safe to expose via the errors.SafeDetailer interface. Those strings also get encoded automatically, and get passed to the decoder function as the second argument.

For example, say you have the following leaf type:

type myLeaf struct {
   // both fields are PII-free.
   code int
   tag string
}

func (m *myLeaf) Error() string { ... }

Then you can expose the fields as safe details as follows:

func (m *myLeaf) SafeDetails() []string {
  return []string{fmt.Sprintf("%d", m.code), m.tag}
}

(If the data is PII-free, then it is good to do this in any case: it enables any network system that receives an error of your type, but does not know about it, to still produce useful Sentry reports.)

Once you have this, the decode function receives the strings and you can use them to re-construct the error:

func myLeafDecoder(_ string, details []string, _ proto.Message) error {
    // Note: you may want to test the length of the details slice
	// is correct.
    code, _ := strconv.Atoi(details[0])
    tag := details[1]
	return &myLeaf{code: code, tag: tag}
}

(For an example, see the withTelemetry type in telemetry/with_telemetry.go.)

The only case where you need a custom encoder is when your error type contains some fields that are not reflected in the error message (so you can't extract them back from there), and are not PII-free and thus cannot be reported as "safe details".

To take inspiration from examples, see the following types in the library that need a custom encoder:

Making %+v work with your type

In short:

  • When in doubt, you should always implement the fmt.Formatter interface (Format(fmt.State, rune)) on your custom error types, exactly as follows:

    func (e *yourType) Format(s *fmt.State, verb rune) { errors.FormatError(e, s, verb) }

    (If you do not provide this redirection for your own custom wrapper type, this will disable the recursive application of the %+v flag to the causes chained from your wrapper.)

  • You may optionally implement the errors.SafeFormatter interface: SafeFormatError(p errors.Printer) (next error). This is optional, but should be done when some details are not included by Error() and should be emitted upon %+v.

The example withHTTPCode wrapper included in the source tree achieves this as follows:

// Format() implements fmt.Formatter, is required until Go knows about FormatError.
func (w *withHTTPCode) Format(s fmt.State, verb rune) { errors.FormatError(w, s, verb) }

// FormatError() formats the error.
func (w *withHTTPCode) SafeFormatError(p errors.Printer) (next error) {
	// Note: no need to print out the cause here!
	// FormatError() knows how to do this automatically.
	if p.Detail() {
		p.Printf("http code: %d", errors.Safe(w.code))
	}
	return w.cause
}

Technical details follow:

  • The errors library follows the Go 2 proposal.

  • At some point in the future, Go's standard fmt library will learn how to recognize error wrappers, and how to use the errors.Formatter interface automatically. Until then, you must ensure that you also implement a Format() method (from fmt.Formatter) that redirects to errors.FormatError.

    Note: you may implement fmt.Formatter (Format() method) in this way without implementing errors.Formatter (a FormatError() method). In that case, errors.FormatError will use a separate code path that does "the right thing", even for wrappers.

  • The library provides an implementation of errors.FormatError(), modeled after the same function in Go 2. This is responsible for printing out error details, and knows how to present a chain of causes in a semi-structured format upon formatting with %+v.

Ensuring errors.Is works when errors/packages are renamed

If a Go package containing a custom error type is renamed, or the error type itself is renamed, and errors of this type are transported over the network, then another system with a different code layout (e.g. running a different version of the software) may not be able to recognize the error any more via errors.Is.

To ensure that network portability continues to work across multiple software versions, in the case error types get renamed or Go packages get moved / renamed / etc, the server code must call errors.RegisterTypeMigration() from e.g. an init() function.

Example use:

 previousPath := "github.com/old/path/to/error/package"
 previousTypeName := "oldpackage.oldErrorName"
 newErrorInstance := &newTypeName{...}
 errors.RegisterTypeMigration(previousPath, previousTypeName, newErrorInstance)

Error composition (summary)

Constructor Composes
New NewWithDepth (see below)
Errorf = Newf
Newf NewWithDepthf (see below)
WithMessage custom wrapper with message prefix and knowledge of safe strings
Wrap WrapWithDepth (see below)
Wrapf WrapWithDepthf (see below)
AssertionFailed AssertionFailedWithDepthf (see below)
NewWithDepth custom leaf with knowledge of safe strings + WithStackDepth (see below)
NewWithDepthf custom leaf with knowledge of safe strings + WithSafeDetails + WithStackDepth
WithMessagef custom wrapper with message prefix and knowledge of safe strings
WrapWithDepth WithMessage + WithStackDepth
WrapWithDepthf WithMessagef + WithStackDepth
AssertionFailedWithDepthf NewWithDepthf + WithAssertionFailure
NewAssertionErrorWithWrappedErrf HandledWithMessagef (barrier) + WrapWithDepthf + WithAssertionFailure
Join JoinWithDepth (see below)
JoinWithDepth multi-cause wrapper + WithStackDepth

API (not constructing error objects)

The following is a summary of the non-constructor API functions, grouped by category. Detailed documentation can be found at: https://pkg.go.dev/github.com/cockroachdb/errors

// Access causes.
func UnwrapAll(err error) error
func UnwrapOnce(err error) error
func Cause(err error) error // compatibility
func Unwrap(err error) error // compatibility
type Wrapper interface { ... } // compatibility

// Error formatting.
type Formatter interface { ... } // compatibility, not recommended
type SafeFormatter interface { ... }
type Printer interface { ... }
func FormatError(err error, s fmt.State, verb rune)
func Formattable(err error) fmt.Formatter

// Identify errors.
func Is(err, reference error) bool
func IsAny(err error, references ...error) bool
func If(err error, pred func(err error) (interface{}, bool)) (interface{}, bool)
func As(err error, target interface{}) bool

// Encode/decode errors.
type EncodedError // this is protobuf-encodable
func EncodeError(ctx context.Context, err error) EncodedError
func DecodeError(ctx context.Context, enc EncodedError) error

// Register encode/decode functions for custom/new error types.
func RegisterLeafDecoder(typeName TypeKey, decoder LeafDecoder)
func RegisterLeafEncoder(typeName TypeKey, encoder LeafEncoder)
func RegisterWrapperDecoder(typeName TypeKey, decoder WrapperDecoder)
func RegisterWrapperEncoder(typeName TypeKey, encoder WrapperEncoder)
func RegisterWrapperEncoderWithMessageOverride (typeName TypeKey, encoder WrapperEncoderWithMessageOverride)
func RegisterMultiCauseEncoder(theType TypeKey, encoder MultiCauseEncoder)
func RegisterMultiCauseDecoder(theType TypeKey, decoder MultiCauseDecoder)
type LeafEncoder = func(ctx context.Context, err error) (msg string, safeDetails []string, payload proto.Message)
type LeafDecoder = func(ctx context.Context, msg string, safeDetails []string, payload proto.Message) error
type WrapperEncoder = func(ctx context.Context, err error) (msgPrefix string, safeDetails []string, payload proto.Message)
type WrapperEncoderWithMessageOverride = func(ctx context.Context, err error) (msgPrefix string, safeDetails []string, payload proto.Message, overrideError bool)
type WrapperDecoder = func(ctx context.Context, cause error, msgPrefix string, safeDetails []string, payload proto.Message) error
type MultiCauseEncoder = func(ctx context.Context, err error) (msg string, safeDetails []string, payload proto.Message)
type MultiCauseDecoder = func(ctx context.Context, causes []error, msgPrefix string, safeDetails []string, payload proto.Message) error

// Registering package renames for custom error types.
func RegisterTypeMigration(previousPkgPath, previousTypeName string, newType error)

// Sentry reports.
func BuildSentryReport(err error) (*sentry.Event, map[string]interface{})
func ReportError(err error) (string)

// Stack trace captures.
func GetOneLineSource(err error) (file string, line int, fn string, ok bool)
type ReportableStackTrace = sentry.StackTrace
func GetReportableStackTrace(err error) *ReportableStackTrace

// Safe (PII-free) details.
type SafeDetailPayload struct { ... }
func GetAllSafeDetails(err error) []SafeDetailPayload
func GetSafeDetails(err error) (payload SafeDetailPayload)

// Obsolete APIs.
type SafeMessager interface { ... }
func Redact(r interface{}) string

// Aliases redact.Safe.
func Safe(v interface{}) SafeMessager

// Assertion failures.
func HasAssertionFailure(err error) bool
func IsAssertionFailure(err error) bool

// User-facing details and hints.
func GetAllDetails(err error) []string
func FlattenDetails(err error) string
func GetAllHints(err error) []string
func FlattenHints(err error) string

// Issue links / URL wrappers.
func HasIssueLink(err error) bool
func IsIssueLink(err error) bool
func GetAllIssueLinks(err error) (issues []IssueLink)

// Unimplemented errors.
func HasUnimplementedError(err error) bool
func IsUnimplementedError(err error) bool

// Telemetry keys.
func GetTelemetryKeys(err error) []string

// Domain errors.
type Domain
const NoDomain Domain
func GetDomain(err error) Domain
func NamedDomain(domainName string) Domain
func PackageDomain() Domain
func PackageDomainAtDepth(depth int) Domain
func EnsureNotInDomain(err error, constructor DomainOverrideFn, forbiddenDomains ...Domain) error
func NotInDomain(err error, doms ...Domain) bool

// Context tags.
func GetContextTags(err error) []*logtags.Buffer

More Repositories

1

cockroach

CockroachDB - the open source, cloud-native distributed SQL database.
Go
29,054
star
2

pebble

RocksDB/LevelDB inspired key-value database in Go
Go
4,442
star
3

copyist

Mocking your SQL database in Go tests has never been easier.
Go
833
star
4

apd

Arbitrary-precision decimals for Go
Go
540
star
5

cockroach-operator

k8s operator for CRDB
Go
264
star
6

docs

CockroachDB user documentation
HTML
177
star
7

django-cockroachdb

CockroachDB Backend for Django
Python
155
star
8

sqlalchemy-cockroachdb

SQLAlchemy adapter for CockroachDB
Python
133
star
9

activerecord-cockroachdb-adapter

CockroachDB adapter for ActiveRecord.
Ruby
100
star
10

rpc-bench

Benchmarking various RPC implementations
Go
87
star
11

examples-orms

Sample uses of CockroachDB with popular ORMs
Go
82
star
12

helm-charts

Helm charts for cockroachdb
Go
81
star
13

examples-go

Sample uses of cockroachDB.
Go
75
star
14

terraform-provider-cockroach

Terraform provider for CockroachDB Cloud
Go
53
star
15

cdc-sink

cdc-sink is a toolkit for ingesting logical replication feeds into a CockroachDB cluster
Go
52
star
16

sequelize-cockroachdb

Use Sequelize and CockroachDB together
JavaScript
52
star
17

cockroachdb-todo-apps

CockroachDB To-Do Apps
Python
51
star
18

c-rocksdb

🚫 DEPRECATED
C++
46
star
19

datadriven

Data-Driven Testing for Go
Go
38
star
20

logtags

key/value annotations for Go contexts
Go
35
star
21

cockroach-gen

CockroachDB with pre-generated Go code
Go
33
star
22

movr

A fictional ride sharing company.
Python
32
star
23

loadgen

CockroachDB load generators
Go
30
star
24

k8s

Images and utilities to run cockroach on kubernetes
Go
26
star
25

redact

Utilities to redact Go strings for confidentiality
Go
25
star
26

c-snappy

C++
21
star
27

ui

Published assets for Cockroach Labs user interfaces
TypeScript
19
star
28

cockroachdb-parser

Apache licensed CockroachDB parser and dependencies.
Go
19
star
29

roachprod

Internal CockroachDB production testing tool
Go
15
star
30

cockroachdb-typescript

A modern cloud-native web app using TypeScript, React, Prisma, Netlify serverless functions, and CockroachDB
TypeScript
14
star
31

crlfmt

Formatter for CockroachDB's additions to the Go style guide.
Go
14
star
32

homebrew-tap

`brew install cockroachdb/tap/cockroach`
Ruby
14
star
33

c-protobuf

🚫 DEPRECATED: go-gettable version of google/protobuf
C++
13
star
34

watermill-crdb

CockroachDB Pub/Sub for the Watermill project.
Go
13
star
35

cockroachdb-cloudformation

Quickly setup dev/test CockroachDB clusters using AWS CloudFormation and Kubernetes
Shell
12
star
36

molt

Migrate Off Legacy Things - open-source tooling to assist migrations to CockroachDB.
Go
12
star
37

vendored

CockroachDB's vendored Go dependencies
Go
11
star
38

c-jemalloc

🚫 DEPRECATED
C
11
star
39

yacc

Fork of go yacc tool with increased hardcoded constants to handle larger grammars.
Go
11
star
40

examples-python

Sample uses of CockroachDB
Python
10
star
41

c-lz4

C
10
star
42

build-cache

Cache the installed output of go builds
Go
9
star
43

definitive_guide_sample_code

Sample code for The Definitive Guide to CockroachDB
JavaScript
8
star
44

quickstart-code-samples

Java
8
star
45

pcf-crdb-service-broker

Pivotal Cloud Foundry service broker for CockroachDB.
Go
8
star
46

dcos-cockroachdb-service

Framework for running CockroachDB on Mesosphere DC/OS
Python
8
star
47

backport

automatically backport pull requests
Go
7
star
48

cockroach-proto

Protocol Buffer
7
star
49

python-heroku-cockroachdb

A modern cloud-native web app using Python, Flask, Heroku, and CockroachDB
Python
7
star
50

walkabout

Walkabout generates visitor-pattern accessors for your existing go structs.
Go
6
star
51

sample-apps

6
star
52

nextjs-react-vercel-crdb-app

A CockroachDB sample app for coordinating social events using Next.js with react-bootstrap deployed on vercel
JavaScript
6
star
53

rksql

Fork of scaledata/rksql
Go
5
star
54

ddshop

TodoMVC app for distributed database workshop
JavaScript
5
star
55

postgres-test

Dockerfile
5
star
56

benchviz

A tool used for visualizing results from benchmark tests over time.
Go
5
star
57

stress

A fork of Golang's stress function.
Go
5
star
58

cockroach-cloud-sdk-go

Go client SDK for CockroachDB Cloud
Mustache
5
star
59

example-app-rust-postgres

Rust
4
star
60

protoc-gen-gogoroach

protoc (protobuf compiler) plugin for CockroachDB protobuf files
Go
4
star
61

generated-diagrams

HTML
4
star
62

roachspeed

codespeed instance
Python
4
star
63

hibernate-savepoint-fix

Java
4
star
64

scripts

Utility and helper scripts for CockroachDB contributors -
Vim Script
4
star
65

go-lab

Scripts and test programs to reveal what happens under the hood in Go.
Go
4
star
66

yarn-vendored

CockroachDB's vendored JavaScript dependencies
3
star
67

cockroachdb.github.io

Supporting static content for CockroachDB
JavaScript
3
star
68

cgo_static_boom

cgo static binary boom
Go
3
star
69

docs-docker

Docker image for the docs build
3
star
70

libedit

CockroachDB fork of the libedit terminal line-editing library
3
star
71

gostdlib

Vendor-friendly Go standard library packages
Go
3
star
72

dev

A utility for performing common CockroachDB development tasks
3
star
73

example-app-python-psycopg3

Simple CRUD application in Python using the psycopg3 driver.
Python
3
star
74

scp-interview

Shell
3
star
75

efcore.pg.cockroach

C#
3
star
76

university-event-driven-architecture-for-java-developers-app-exercises

Exercise code for Cockroach University - Event Driven Architecture for Java Developers
Java
3
star
77

bincheck

Verify CockroachDB binaries
Shell
3
star
78

eddie

Big Eddie, the golang contract enforcer
Go
3
star
79

roachperf-og

🚫 Deprecated CockroachDB performance tool — use roachprod instead!
Go
3
star
80

university-getting-started-with-sql-app-exercises

Exercise code for the Cockroach University - Getting Started with SQL for Application Developers course
Shell
3
star
81

jsonb-spec

Acceptance tests/spec for CockroachDB JSONB support, complement to scoping RFC
JavaScript
3
star
82

social-events-app

JavaScript
3
star
83

ttycolor

Conditionally expose ANSI color codes for use on a terminal
Go
2
star
84

admin-ui-components

Shared frontend components between the CRDB Admin UI and other apps
TypeScript
2
star
85

rails-crdb-app

A CockroachDB leaderboard sample application using Rails deployed on Heroku
Ruby
2
star
86

fullstack-node-cockroachdb-app

Fullstack sample application in Node.js using Sequelize
JavaScript
2
star
87

university-multi-region-course-app-exercises

exercise code for the cockroach university multi-region course
Java
2
star
88

go-plus

API library for CRL's custom Go extensions
Go
2
star
89

tokenbucket

Token bucket implementation in Go
Go
2
star
90

homebrew-go

🚫 DEPRECATED 🚫 — use `brew install go` instead
Ruby
2
star
91

build-utils

🚫 DEPRECATED: Build utilities for CockroachDB
Go
2
star
92

psycopg2-cockroachdb

Testing psycopg2 against cockroachdb
Shell
2
star
93

katacoda

In-browser, interactive tutorials on CockroachDB
Shell
2
star
94

cockroachdb-hibernate

Package to improve compatibility between CockroachDB and Hibernate
2
star
95

pulumi-poc

Demo of simple control plane built on top of Pulumi.
Go
2
star
96

avrogen

Avro generator for import testing
Go
1
star
97

redcarpet-extender

Extends the Redcarpet Markdown parser to handle CockroachDB documentation
1
star
98

s3checker

Check s3 support for bulk operations
Go
1
star
99

university-getting-started-with-node-postgres-app-exercises

JavaScript
1
star
100

university-multi-region-latency-exercises

Optimizing latency in multi-region database course exercise code
Shell
1
star