rogerr

README

rogerr

Zero-dependency error handling support package for Go.

Usage

When creating errors, do not include goroutine-specific or request-specific information as part of the error message itself. Error messages with these specific bits of information often break filtering/grouping algorithms, e.g. as used by error reporting tools like Sentry/Rollbar/etc. (If you use Bugsnag, I recommend kinbiko/bugsnag for an even better experience than this package).

Instead this information should be treated as structured data, akin to structured logging solutions like Logrus and Zap. In Go, it's conventional to attach this kind of request specific 'diagnostic' metadata to a context.Context type, and that's what this package enables too.

At a high level:

1. Attach metadata to your context with rogerr.WithMetadata or rogerr.WithMetadatum.
2. When you come across an error, use err = rogerr.Wrap(ctx, err, msg) to attach the metadata accumulated so far to the wrapped error.
3. Return the error as you would normally, and at the time of logging/reporting, extract the metadata with md := rogerr.Metadata(err).
4. Record the structured metadata alongside the error message.

Documentation

Overview

Package rogerr is a zero-dependency error handling support package.

When creating errors, **do not include goroutine-specific or request-specific information as part of the error message itself**. Error messages with these specific bits of information often break filtering/grouping algorithms, e.g. as used by error reporting tools like Sentry/Rollbar/etc. (If you use Bugsnag, I recommend kinbiko/bugsnag(https://github.com/kinbiko/bugsnag) for an **even better** experience than this package).

Instead this information should be treated as structured data, akin to structured logging solutions like Logrus and Zap. In Go, it's conventional to attach this kind of request specific 'diagnostic' metadata to a `context.Context` type, and that's what this package enables too.

At a high level:

1. Attach metadata to your context with `rogerr.WithMetadata` or `rogerr.WithMetadatum`. 1. When you come across an error, use `err = rogerr.Wrap(ctx, err, msg)` to attach the metadata accumulated so far to the wrapped error. 1. Return the error as you would normally, and at the time of logging/reporting, extract the metadata with `md := rogerr.Metadata(err)`. 1. Record the _structured_ metadata alongside the error message.

Index

• func Metadata(err error) map[string]interface{}
• func WithMetadata(ctx context.Context, data map[string]interface{}) context.Context
• func WithMetadatum(ctx context.Context, key string, value interface{}) context.Context
• type Error
  • func Wrap(ctx context.Context, err error, msgAndFmtArgs ...interface{}) *Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error

Functions

func Metadata

func Metadata(err error) map[string]interface{}

Metadata pulls out all the metadata known by this package as a map[key]value from the given error.

func WithMetadata

func WithMetadata(ctx context.Context, data map[string]interface{}) context.Context

WithMetadata attaches the given keys and values to the rogerr metadata associated with this context. Returns a new context with the metadata attached, or nil if the given ctx was nil.

func WithMetadatum

func WithMetadatum(ctx context.Context, key string, value interface{}) context.Context

WithMetadatum attaches the given key and value to the rogerr metadata associated with this context. Returns a new context with the metadatum attached, or nil if the given ctx was nil.

Types

type Error

type Error struct {
	Unhandled bool
	Panic     bool
	// contains filtered or unexported fields
}

Error allows you to specify certain properties of an error. Setting Panic to true indicates that the application was not able to gracefully handle an error or panic that occurred in the system.

func Wrap

func Wrap(ctx context.Context, err error, msgAndFmtArgs ...interface{}) *Error

Wrap attaches ctx data and wraps the given error with message. ctx, err, and msgAndFmtArgs are all optional, but at least one must be given for this function to return a non-nil error. Any attached diagnostic data from this ctx will be preserved should you pass the returned error further up the stack.

func (*Error) Error

func (e *Error) Error() string

Error returns the message of the error, along with any wrapped error messages.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap is the conventional method for getting the underlying error of an error.