Honeybadger for Go
Typical installation time: ~5 minutes
Hi there! You've found Honeybadger's guide to Go exception and error tracking. Once installed, Honeybadger will automatically report errors from your Go application.
Getting Started
1. Install the library
To install, grab the package from GitHub:
go get github.com/honeybadger-io/honeybadger-go
Then add an import to your application code:
import "github.com/honeybadger-io/honeybadger-go"
2. Set your API key
Finally, configure your API key:
honeybadger.Configure(honeybadger.Configuration{APIKey: "Your project API key"})
You can also configure Honeybadger via environment variables. See Configuration for more information.
3. Enable automatic panic reporting
Panics during HTTP requests
To automatically report panics which happen during an HTTP request, wrap your
http.Handler function with honeybadger.Handler:
log.Fatal(http.ListenAndServe(":8080", honeybadger.Handler(handler)))
Request data such as cookies and params will automatically be reported with
errors which happen inside honeybadger.Handler. Make sure you recover from
panics after honeybadger's Handler has been executed to ensure all panics are
reported.
Unhandled Panics
To report all unhandled panics which happen in your application
the following can be added to main():
func main() {
defer honeybadger.Monitor()
// application code...
}
Manually Reporting Errors
To report an error manually, use honeybadger.Notify:
if err != nil {
honeybadger.Notify(err)
}
Configuration
To set configuration options, use the honeybadger.Configuration method, like so:
honeybadger.Configure(honeybadger.Configuration{
APIKey: "Your project API key",
Env: "staging"
})
The following options are available to you:
| Name | Type | Default | Example | Environment variable |
|---|---|---|---|---|
| APIKey | string |
"" |
"badger01" |
HONEYBADGER_API_KEY |
| Root | string |
The current working directory | "/path/to/project" |
HONEYBADGER_ROOT |
| Env | string |
"" |
"production" |
HONEYBADGER_ENV |
| Hostname | string |
The hostname of the current server. | "badger01" |
HONEYBADGER_HOSTNAME |
| Endpoint | string |
"https://api.honeybadger.io" |
"https://honeybadger.example.com/" |
HONEYBADGER_ENDPOINT |
| Sync | bool |
false | true |
HONEYBADGER_SYNC |
| Timeout | time.Duration |
3 seconds | 10 * time.Second |
HONEYBADGER_TIMEOUT (nanoseconds) |
| Logger | honeybadger.Logger |
Logs to stderr | CustomLogger{} |
n/a |
| Backend | honeybadger.Backend |
HTTP backend | CustomBackend{} |
n/a |
Public Interface
honeybadger.Notify(): Send an error to Honeybadger.
If you've handled a panic in your code, but would still like to report the error to Honeybadger, this is the method for you.
Examples:
if err != nil {
honeybadger.Notify(err)
}
You can also add local context using an optional second argument when calling
honeybadger.Notify:
honeybadger.Notify(err, honeybadger.Context{"user_id": 2})
Honeybadger uses the error's class name to group similar errors together. If
your error classes are often generic (such as errors.errorString), you can
improve grouping by overriding the default with something more unique:
honeybadger.Notify(err, honeybadger.ErrorClass{"CustomClassName"})
To override grouping entirely, you can send a custom fingerprint. All errors with the same fingerprint will be grouped together:
honeybadger.Notify(err, honeybadger.Fingerprint{"A unique string"})
To tag errors in Honeybadger:
honeybadger.Notify(err, honeybadger.Tags{"timeout", "http"})
honeybadger.SetContext(): Set metadata to be sent if an error occurs
This method lets you set context data that will be sent if an error should occur.
For example, it's often useful to record the current user's ID when an error occurs in a web app. To do that, just use SetContext to set the user id on each request. If an error occurs, the id will be reported with it.
Note: This method is currently shared across goroutines, and therefore may not be optimal for use in highly concurrent use cases, such as HTTP requests. See issue #35.
Examples:
honeybadger.SetContext(honeybadger.Context{
"user_id": 1,
})
defer honeybadger.Monitor(): Automatically report panics from your functions
To automatically report panics in your functions or methods, add
defer honeybadger.Monitor() to the beginning of the function or method you wish to monitor.
Examples:
func risky() {
defer honeybadger.Monitor()
// risky business logic...
}
Important: honeybadger.Monitor() will re-panic after it reports the error, so make sure that it is only called once before recovering from the panic (or allowing the process to crash).
honeybadger.BeforeNotify(): Add a callback to skip or modify error notification.
Sometimes you may want to modify the data sent to Honeybadger right before an
error notification is sent, or skip the notification entirely. To do so, add a
callback using honeybadger.BeforeNotify().
Examples:
honeybadger.BeforeNotify(
func(notice *honeybadger.Notice) error {
if notice.ErrorClass == "SkippedError" {
return fmt.Errorf("Skipping this notification")
}
// Return nil to send notification for all other classes.
return nil
}
)
To modify information:
honeybadger.BeforeNotify(
func(notice *honeybadger.Notice) error {
// Errors in Honeybadger will always have the class name "GenericError".
notice.ErrorClass = "GenericError"
return nil
}
)
honeybadger.NewNullBackend(): Disable data reporting.
NewNullBackend creates a backend which swallows all errors and does not send them to Honeybadger. This is useful for development and testing to disable sending unnecessary errors.
Examples:
honeybadger.Configure(honeybadger.Configuration{Backend: honeybadger.NewNullBackend()})
Sample Application
If you'd like to see the library in action before you integrate it with your apps, check out our sample application.
You can deploy the sample app to your Heroku account by clicking this button:
Don't forget to destroy the Heroku app after you're done so that you aren't charged for usage.
The code for the sample app is available on Github, in case you'd like to read through it, or run it locally.