1
2
3[](https://circleci.com/gh/goph/emperror)
4[](https://goreportcard.com/report/github.com/goph/emperror)
5[](https://golangci.com/r/github.com/goph/emperror)
6[](https://godoc.org/github.com/goph/emperror)
7
8**The Emperor takes care of all errors personally.**
9
10Go's philosophy encourages to gracefully handle errors whenever possible,
11but some times recovering from an error is not possible.
12
13In those cases handling the error means making the best effort to record every detail
14for later inspection, doing that as high in the application stack as possible.
15
16This project provides tools (building on the well-known [pkg/errors](https://github.com/pkg/errors) package)
17to make error handling easier.
18
19Read more about the topic here:
20
21- https://dave.cheney.net/2016/04/27/dont-just-check-errors-handle-them-gracefully
22- https://8thlight.com/blog/kyle-krull/2018/08/13/exploring-error-handling-patterns-in-go.html
23- https://banzaicloud.com/blog/error-handling-go/
24
25
26## Features
27
28- Various error handling strategies (eg. logging, third-party error services) using a simple interface
29- Error annotation with context (key-value pairs, HTTP request, etc)
30- Various helpers related to error handling (recovery from panics, etc)
31- Integrations with well-known error catchers and libraries:
32 - [Sentry](https://sentry.io) [SDK](https://godoc.org/github.com/getsentry/raven-go) (both hosted and on-premise)
33 - [Bugsnag](https://bugsnag.com) [SDK](https://godoc.org/github.com/bugsnag/bugsnag-go)
34 - [Airbrake](https://airbrake.com) [SDK](https://godoc.org/github.com/airbrake/gobrake) / [Errbit](https://errbit.com/)
35 - [Rollbar](https://rollbar.com) [SDK](https://godoc.org/github.com/rollbar/rollbar-go)
36
37
38## Usage
39
40### Log errors
41
42Logging is one of the most common target to record error events.
43
44The reference implementation for logging with Emperror can be found in package [logur](https://github.com/goph/logur).
45Logur is an opinionated logging toolkit supporting multiple logging libraries (like [logrus](https://github.com/sirupsen/logrus)).
46
47Emperror comes with a set of handlers backed by logging frameworks too:
48
49- **handler/logrushandler:** [logrus](https://github.com/sirupsen/logrus) handler implementation
50
51See [GoDoc](https://godoc.org/github.com/goph/emperror) for detailed usage examples.
52
53
54### Attach context to an error
55
56Following [go-kit's logger](https://github.com/go-kit/kit/tree/master/log) context pattern
57Emperror gives you tools to attach context (eg. key-value pairs) to an error:
58
59```go
60package main
61
62import (
63 "github.com/goph/emperror"
64 "github.com/pkg/errors"
65)
66
67func foo() error { return errors.New("error") }
68
69func bar() error {
70 err := foo()
71 if err != nil {
72 return emperror.With(err, "key", "value")
73 }
74
75 return nil
76}
77```
78
79Note that (just like with go-kit's logger) the context is *NOT* a set of key-value pairs per se,
80but most tools will convert the slice to key-value pairs.
81This is to provide flexibility in error handling implementations.
82
83
84## Development
85
86When all coding and testing is done, please run the test suite:
87
88``` bash
89$ make check
90```
91
92
93## License
94
95The MIT License (MIT). Please see [License File](LICENSE) for more information.
View as plain text