gogolok / honeybadger-go

Send Go (golang) panics and errors to Honeybadger.

Honeybadger for Go

Go (golang) support for the ⚡ Honeybadger error notifier. Receive instant notification of panics and errors in your Go applications.

Getting Started

1. Install the library

Note: We recommend vendoring honeybadger-go in your application source until we have a stable (v1.0.0) release. See Versioning for more info.

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 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)
}

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.

Advanced Configuration

To set configuration options, use the honeybadger.Configuration method, like so:

honeybadger.Configure(honeybadger.Configuration{
  APIKey: "your 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
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:

if err != nil {
  honeybadger.Notify(err, honeybadger.Context{"user_id": 2})
}

---

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.

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).

---

Creating a new client

In the same way that the log library provides a predefined "standard" logger, honeybadger defines a standard client which may be accessed directly via honeybadger. A new client may also be created by calling honeybadger.New:

hb := honeybadger.New(honeybadger.Configuration{APIKey: "some other api key"})
hb.Notify("This error was reported by an alternate client.")

Versioning

We use Semantic Versioning to version releases of honeybadger-go. Because there is no official method to specify version dependencies in Go, we will do our best never to introduce a breaking change on the master branch of this repo after reaching version 1. Until we reach version 1 there is a small chance that we may introduce a breaking change (changing the signature of a function or method, for example), but we'll always tag a new minor release and broadcast that we made the change.

If you're concerned about versioning, there are two options:

Vendor your dependencies

If you're really concerned about changes to this library, then copy it into your source control management system so that you can perform upgrades on your own time.

Use gopkg.in

Rather than importing directly from GitHub, gopkg.in allows you to use their special URL format to transparently import a branch or tag from GitHub. Because we tag each release, using gopkg.in can enable you to depend explicitly on a certain version of this library. Importing from gopkg.in instead of directly from GitHub is as easy as:

import "gopkg.in/honeybadger-io/honeybadger-go.v0"

Check out the gopkg.in homepage for more information on how to request versions.

Changelog

See https://github.com/honeybadger-io/honeybadger-go/blob/master/CHANGELOG.md

Contributing

If you're adding a new feature, please submit an issue as a preliminary step; that way you can be (moderately) sure that your pull request will be accepted.

To contribute your code:

1. Fork it.
2. Create a topic branch git checkout -b my_branch
3. Commit your changes git commit -am "Boom"
4. Push to your branch git push origin my_branch
5. Send a pull request

License

This library is MIT licensed. See the LICENSE file in this repository for details.