⚠ Project moved

The project has been moved to a new organization: https://github.com/emperror

It also received a vanity import URL: emperror.dev/emperror

This package will stay here to provide backward compatibility, but it won't receive any updates. Please follow the new repositories.

The Emperor takes care of all errors personally.

Go's philosophy encourages to gracefully handle errors whenever possible, but some times recovering from an error is not possible.

In those cases handling the error means making the best effort to record every detail for later inspection, doing that as high in the application stack as possible.

This project provides tools (building on the well-known pkg/errors package) to make error handling easier.

Read more about the topic here:

• https://dave.cheney.net/2016/04/27/dont-just-check-errors-handle-them-gracefully
• https://8thlight.com/blog/kyle-krull/2018/08/13/exploring-error-handling-patterns-in-go.html
• https://banzaicloud.com/blog/error-handling-go/

Features

• Various error handling strategies (eg. logging, third-party error services) using a simple interface
• Error annotation with context (key-value pairs, HTTP request, etc)
• Various helpers related to error handling (recovery from panics, etc)
• Integrations with well-known error catchers and libraries:
  • Sentry SDK (both hosted and on-premise)
  • Bugsnag SDK
  • Airbrake SDK / Errbit
  • Rollbar SDK

Usage

Log errors

Logging is one of the most common target to record error events.

The reference implementation for logging with Emperror can be found in package logur. Logur is an opinionated logging toolkit supporting multiple logging libraries (like logrus).

Emperror comes with a set of handlers backed by logging frameworks too:

• handler/logrushandler: logrus handler implementation

See GoDoc for detailed usage examples.

Attach context to an error

Following go-kit's logger context pattern Emperror gives you tools to attach context (eg. key-value pairs) to an error:

package main

import (
	"github.com/goph/emperror"
	"github.com/pkg/errors"
)

func foo() error { return errors.New("error") }

func bar() error {
	err := foo()
	if err != nil {
	    return emperror.With(err, "key", "value")
	}
	
	return nil
}

Note that (just like with go-kit's logger) the context is NOT a set of key-value pairs per se, but most tools will convert the slice to key-value pairs. This is to provide flexibility in error handling implementations.

Development

When all coding and testing is done, please run the test suite:

$ make check

License

The MIT License (MIT). Please see License File for more information.