honeybadger

README

honeybadger-go

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

Try it out

To deploy a sample Go application which uses this library to report errors to Honeybadger.io:

Don't forget to destroy the Heroku app after you're done so that you aren't charged for usage.

You can also download the sample application and run it locally.

Installation

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"

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.

Automatically reporting panics during a server request

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.

Automatically reporting other panics

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. To report all unhandled panics which happen in your application the following can be added to main():

func main() {
  defer honeybadger.Monitor()
  // application code...
}

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

Manually reporting errors

To report an error manually, use honeybadger.Notify:

if err != nil {
  honeybadger.Notify(err)
}

Sending extra data to Honeybadger

To send extra context data to Honeybadger, use honeybadger.SetContext:

honeybadger.SetContext(honeybadger.Context{
  "badgers": true,
  "user_id": 1,
})

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

Local context keys override the keys set using honeybadger.SetContext.

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

Configuration

The following options are available through honeybadger.Configuration:

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

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/releases

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.

Documentation

Index

• Constants
• Variables
• func Configure(c Configuration)
• func Flush()
• func Handler(h http.Handler) http.Handler
• func Monitor()
• func Notify(err interface{}, extra ...interface{}) (string, error)
• func SetContext(c Context)
• type Backend
• type CGIData
• type Client
  • func New(c Configuration) *Client
  • func (client *Client) Configure(config Configuration)
  • func (client *Client) Flush()
  • func (client *Client) Handler(h http.Handler) http.Handler
  • func (client *Client) Monitor()
  • func (client *Client) Notify(err interface{}, extra ...interface{}) (string, error)
  • func (client *Client) SetContext(context Context)
• type Configuration
• type Context
  • func (context Context) Update(other Context)
• type Error
  • func (e Error) Error() string
• type Feature
• type Frame
• type Logger
• type Notice
• type Params
• type Payload

Constants

const VERSION = "0.0.1"

VERSION defines the version of the honeybadger package.

Variables

var (
	// client is a pre-defined "global" client.
	DefaultClient = New(Configuration{})

	// Config is a pointer to the global client's Config.
	Config = DefaultClient.Config

	// Notices is the feature for sending error reports.
	Notices = Feature{"notices"}
)

var (
	ErrRateExceeded    = errors.New("Rate exceeded: slow down!")
	ErrPaymentRequired = errors.New("Payment required: expired trial or credit card?")
	ErrUnauthorized    = errors.New("Unauthorized: bad API key?")
)

Errors returned by the backend when unable to successfully handle payload.

Functions

func Configure

func Configure(c Configuration)

Configure updates configuration of the global client.

func Flush

func Flush()

Flush blocks until all data (normally sent in the background) has been sent to the Honeybadger service.

func Handler

func Handler(h http.Handler) http.Handler

Handler returns an http.Handler function which automatically reports panics to Honeybadger and then re-panics.

func Monitor

func Monitor()

Monitor is used to automatically notify Honeybadger service of panics which happen inside the current function. In order to monitor for panics, defer a call to Monitor. For example:

func main {
	defer honeybadger.Monitor()
	// Do risky stuff...
}

The Monitor function re-panics after the notification has been sent, so it's still up to the user to recover from panics if desired.

func Notify

func Notify(err interface{}, extra ...interface{}) (string, error)

Notify reports the error err to the Honeybadger service.

The first argument err may be an error, a string, or any other type in which case its formatted value will be used.

It returns a string UUID which can be used to reference the error from the Honeybadger service, and an error as a second argument.

func SetContext

func SetContext(c Context)

SetContext merges c Context into the Context of the global client.

Types

type Backend

type Backend interface {
	Notify(feature Feature, payload Payload) error
}

The Backend interface is implemented by the server type by default, but a custom implementation may be configured by the user.

type CGIData

type CGIData hash

CGIData stores variables from the server/request environment indexed by key. Header keys should be converted to upercase, all non-alphanumeric characters replaced with underscores, and prefixed with HTTP_. For example, the header "Content-Type" would become "HTTP_CONTENT_TYPE".

type Client

type Client struct {
	Config *Configuration
	// contains filtered or unexported fields
}

Client is the manager for interacting with the Honeybadger service. It holds the configuration and implements the public API.

func New

func New(c Configuration) *Client

New returns a new instance of Client.

func (*Client) Configure

func (client *Client) Configure(config Configuration)

Configure updates the client configuration with the supplied config.

func (*Client) Flush

func (client *Client) Flush()

Flush blocks until the worker has processed its queue.

func (*Client) Handler

func (client *Client) Handler(h http.Handler) http.Handler

Handler returns an http.Handler function which automatically reports panics to Honeybadger and then re-panics.

func (*Client) Monitor

func (client *Client) Monitor()

Monitor automatically reports panics which occur in the function it's called from. Must be deferred.

func (*Client) Notify

func (client *Client) Notify(err interface{}, extra ...interface{}) (string, error)

Notify reports the error err to the Honeybadger service.

func (*Client) SetContext

func (client *Client) SetContext(context Context)

SetContext updates the client context with supplied context.

type Configuration

type Configuration struct {
	APIKey   string
	Root     string
	Env      string
	Hostname string
	Endpoint string
	Timeout  time.Duration
	Logger   Logger
	Backend  Backend
}

Configuration manages the configuration for the client.

type Context

type Context hash

Context is used to send extra data to Honeybadger.

func (Context) Update

func (context Context) Update(other Context)

Update applies the values in other Context to context.

type Error

type Error struct {
	Message string
	Class   string
	Stack   []*Frame
	// contains filtered or unexported fields
}

Error provides more structured information about a Go error.

func (Error) Error

func (e Error) Error() string

type Feature

type Feature struct {
	Endpoint string
}

Feature references a resource provided by the API service. Its Endpoint maps to the collection endpoint of the /v1 API.

type Frame

type Frame struct {
	Number string `json:"number"`
	File   string `json:"file"`
	Method string `json:"method"`
}

Frame represent a stack frame inside of a Honeybadger backtrace.

type Logger

type Logger interface {
	Printf(format string, v ...interface{})
}

The Logger interface is implemented by the standard log package and requires a limited subset of the interface implemented by log.Logger.

type Notice

type Notice struct {
	APIKey       string
	Error        Error
	Token        string
	ErrorMessage string
	ErrorClass   string
	Hostname     string
	Env          string
	Backtrace    []*Frame
	ProjectRoot  string
	Context      Context
	Params       Params
	CGIData      CGIData
	URL          string
}

Notice is a representation of the error which is sent to Honeybadger, and implements the Payload interface.

type Params

type Params url.Values

Params stores the form or url values from an HTTP request.

type Payload

type Payload interface {
	// contains filtered or unexported methods
}

The Payload interface is implemented by any type which can be handled by the Backend interface.