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
• func Wrap(ctx context.Context, err error, msgAndFmtArgs ...interface{}) error

Examples

• Wrap

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.

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.

Example

package main

import (
	"context"
	"fmt"

	"github.com/kinbiko/rogerr"
)

func main() {
	someFuncWithAProblem := func(ctx context.Context) error {
		return fmt.Errorf("some low level err")
	}

	someFuncThatWrapsWithRogerr := func(ctx context.Context) error {
		// Attach some projectID to the context as structured metadata
		ctx = rogerr.WithMetadatum(ctx, "projectID", 123)

		err := someFuncWithAProblem(ctx)
		if err != nil {
			return rogerr.Wrap(ctx, err, "wrap args")
		}
		return nil
	}

	someFuncThatWrapsARogerrError := func(ctx context.Context) error {
		err := someFuncThatWrapsWithRogerr(ctx)
		if err != nil {
			return fmt.Errorf("wrap with fmt: %w", err)
		}
		return nil
	}

	err := someFuncThatWrapsARogerrError(context.Background())
	md := rogerr.Metadata(err)
	fmt.Println(err.Error())     // error message should be cleanly wrapped
	fmt.Println(md["projectID"]) // structured metadata should be available
}

Output:

wrap with fmt: wrap args: some low level err
123