README ¶
Bugsnag Notifier for Golang
The Bugsnag Notifier for Golang gives you instant notification of panics, or unexpected errors, in your golang app. Any unhandled panics will trigger a notification to be sent to your Bugsnag project.
Bugsnag captures errors in real-time from your web, mobile and desktop applications, helping you to understand and resolve them as fast as possible. Create a free account to start capturing exceptions from your applications.
How to Install
-
Download the code
go get github.com/bugsnag/bugsnag-go
Using with net/http apps
For a golang app based on net/http, integrating Bugsnag takes two steps. You should also use these instructions if you're using the gorilla toolkit, or the pat muxer.
-
Configure bugsnag at the start of your
main()
function:import "github.com/bugsnag/bugsnag-go" func main() { bugsnag.Configure(bugsnag.Configuration{ APIKey: "YOUR_API_KEY_HERE", ReleaseStage: "production", // more configuration options }) // rest of your program. }
-
Wrap your server in a bugsnag.Handler
// a. If you're using the builtin http mux, you can just pass // bugsnag.Handler(nil) to http.ListenAndServer http.ListenAndServe(":8080", bugsnag.Handler(nil)) // b. If you're creating a server manually yourself, you can set // its handlers the same way srv := http.Server{ Handler: bugsnag.Handler(nil) } // c. If you're not using the builtin http mux, wrap your own handler // (though make sure that it doesn't already catch panics) http.ListenAndServe(":8080", bugsnag.Handler(handler))
Using with Revel apps
There are two steps to get panic handling in revel apps.
-
Add the
bugsnagrevel.Filter
immediately after therevel.PanicFilter
inapp/init.go
:import "github.com/bugsnag/bugsnag-go/revel" revel.Filters = []revel.Filter{ revel.PanicFilter, bugsnagrevel.Filter, // ... }
-
Set bugsnag.apikey in the top section of
conf/app.conf
.module.static=github.com/revel/revel/modules/static bugsnag.apikey=YOUR_API_KEY_HERE [dev]
Using with Google App Engine
-
Configure bugsnag at the start of your
init()
function:import "github.com/bugsnag/bugsnag-go" func init() { bugsnag.Configure(bugsnag.Configuration{ APIKey: "YOUR_API_KEY_HERE", }) // ... }
-
Wrap every http.Handler or http.HandlerFunc with Bugsnag:
// a. If you're using HandlerFuncs http.HandleFunc("/", bugsnag.HandlerFunc( func (w http.ResponseWriter, r *http.Request) { // ... })) // b. If you're using Handlers http.Handle("/", bugsnag.Handler(myHttpHandler))
-
In order to use Bugsnag, you must provide the current
appengine.Context
, or current*http.Request
as rawData. The easiest way to do this is to create a new notifier.c := appengine.NewContext(r) notifier := bugsnag.New(c) if err != nil { notifier.Notify(err) } go func () { defer notifier.Recover() // ... }()
Notifying Bugsnag manually
Bugsnag will automatically handle any panics that crash your program and notify
you of them. If you've integrated with revel
or net/http
, then you'll also
be notified of any panics() that happen while processing a request.
Sometimes however it's useful to manually notify Bugsnag of a problem. To do this,
call bugsnag.Notify()
if err != nil {
bugsnag.Notify(err)
}
Manual panic handling
To avoid a panic in a goroutine from crashing your entire app, you can use
bugsnag.Recover()
to stop a panic from unwinding the stack any further. When Recover()
is hit,
it will send any current panic to Bugsnag and then stop panicking. This is
most useful at the start of a goroutine:
go func() {
defer bugsnag.Recover()
// ...
}()
Alternatively you can use
bugsnag.AutoNotify()
to notify bugsnag of a panic while letting the program continue to panic. This
is useful if you're using a Framework that already has some handling of panics
and you are retrofitting bugsnag support.
defer bugsnag.AutoNotify()
Sending Custom Data
Most functions in the Bugsnag API, including bugsnag.Notify()
,
bugsnag.Recover()
, bugsnag.AutoNotify()
, and bugsnag.Handler()
let you
attach data to the notifications that they send. To do this you pass in rawData,
which can be any of the supported types listed here. To add support for more
types of rawData see OnBeforeNotify.
Custom MetaData
Custom metaData appears as tabs on Bugsnag.com. You can set it by passing
a bugsnag.MetaData
object as rawData.
bugsnag.Notify(err,
bugsnag.MetaData{
"Account": {
"Name": Account.Name,
"Paying": Account.Plan.Premium,
},
})
Request data
Bugsnag can extract interesting data from
*http.Request
objects, and
*revel.Controller
objects. These are automatically passed in when handling panics, and you can
pass them yourself.
func (w http.ResponseWriter, r *http.Request) {
bugsnag.Notify(err, r)
}
User data
User data is searchable, and the Id
powers the count of users affected. You
can set which user an error affects by passing a
bugsnag.User
object as
rawData.
bugsnag.Notify(err,
bugsnag.User{Id: "1234", Name: "Conrad", Email: "me@cirw.in"})
Context
The context shows up prominently in the list view so that you can get an idea
of where a problem occurred. You can set it by passing a
bugsnag.Context
object as rawData.
bugsnag.Notify(err, bugsnag.Context{"backgroundJob"})
Severity
Bugsnag supports three severities, SeverityError
, SeverityWarning
, and SeverityInfo
.
You can set the severity of an error by passing one of these objects as rawData.
bugsnag.Notify(err, bugsnag.SeverityInfo)
Configuration
You must call bugsnag.Configure()
at the start of your program to use Bugsnag, you pass it
a bugsnag.Configuration
object
containing any of the following values.
APIKey
The Bugsnag API key can be found on your Bugsnag dashboard under "Settings".
bugsnag.Configure(bugsnag.Configuration{
APIKey: "YOUR_API_KEY_HERE",
})
Endpoint
The Bugsnag endpoint defaults to https://notify.bugsnag.com/
. If you're using Bugsnag enterprise,
you should set this to the endpoint of your local instance.
bugsnag.Configure(bugsnag.Configuration{
Endpoint: "http://bugsnag.internal:49000/",
})
ReleaseStage
The ReleaseStage tracks where your app is deployed. You should set this to production
, staging
,
development
or similar as appropriate.
bugsnag.Configure(bugsnag.Configuration{
ReleaseStage: "development",
})
NotifyReleaseStages
The list of ReleaseStages to notify in. By default Bugsnag will notify you in all release stages, but you can use this to silence development errors.
bugsnag.Configure(bugsnag.Configuration{
NotifyReleaseStages: []string{"production", "staging"},
})
AppVersion
If you use a versioning scheme for deploys of your app, Bugsnag can use the AppVersion
to only
re-open errors if they occur in later version of the app.
bugsnag.Configure(bugsnag.Configuration{
AppVersion: "1.2.3",
})
Hostname
The hostname is used to track where exceptions are coming from in the Bugsnag dashboard. The
default value is obtained from os.Hostname()
so you won't often need to change this.
bugsnag.Configure(bugsnag.Configuration{
Hostname: "go1",
})
ProjectPackages
In order to determine where a crash happens Bugsnag needs to know which packages you consider to
be part of your app (as opposed to a library). By default this is set to []string{"main*"}
. Strings
are matched to package names using filepath.Match
.
bugsnag.Configure(bugsnag.Configuration{
ProjectPackages: []string{"main", "github.com/domain/myapp/*"},
}
ParamsFilters
Sometimes sensitive data is accidentally included in Bugsnag MetaData. You can remove it by
setting ParamsFilters
. Any key in the MetaData
that includes any string in the filters
will be redacted. The default is []string{"password", "secret"}
, which prevents fields like
password
, password_confirmation
and secret_answer
from being sent.
bugsnag.Configure(bugsnag.Configuration{
ParamsFilters: []string{"password", "secret"},
}
Logger
The Logger to write to in case of an error inside Bugsnag. This defaults to the global logger.
bugsnag.Configure(bugsnag.Configuration{
Logger: app.Logger,
}
PanicHandler
The first time Bugsnag is configured, it wraps the running program in a panic
handler using panicwrap. This
forks a sub-process which monitors unhandled panics. To prevent this, set
PanicHandler
to func() {}
the first time you call
bugsnag.Configure
. This will prevent bugsnag from being able to notify you about
unhandled panics.
bugsnag.Configure(bugsnag.Configuration{
PanicHandler: func() {},
})
Synchronous
Bugsnag usually starts a new goroutine before sending notifications. This means
that notifications can be lost if you do a bugsnag.Notify and then immediately
os.Exit. To avoid this problem, set Bugsnag to Synchronous (or just panic()
instead ;).
bugsnag.Configure(bugsnag.Configuration{
Synchronous: true
})
Or just for one error:
bugsnag.Notify(err, bugsnag.Configuration{Synchronous: true})
Transport
The transport configures how Bugsnag makes http requests. By default we use
http.DefaultTransport
which handles
HTTP proxies automatically using the $HTTP_PROXY
environment variable.
bugsnag.Configure(bugsnag.Configuration{
Transport: http.DefaultTransport,
})
Custom data with OnBeforeNotify
While it's nice that you can pass MetaData
directly into bugsnag.Notify
,
bugsnag.AutoNotify
, and bugsnag.Recover
, this can be a bit cumbersome and
inefficient — you're constructing the meta-data whether or not it will actually
be used. A better idea is to pass raw data in to these functions, and add an
OnBeforeNotify
filter that converts them into MetaData
.
For example, lets say our system processes jobs:
type Job struct{
Retry bool
UserId string
UserEmail string
Name string
Params map[string]string
}
You can pass a job directly into Bugsnag.notify:
bugsnag.Notify(err, job)
And then add a filter to extract information from that job and attach it to the Bugsnag event:
bugsnag.OnBeforeNotify(
func(event *bugsnag.Event, config *bugsnag.Configuration) error {
// Search all the RawData for any *Job pointers that we're passed in
// to bugsnag.Notify() and friends.
for _, datum := range event.RawData {
if job, ok := datum.(*Job); ok {
// don't notify bugsnag about errors in retries
if job.Retry {
return fmt.Errorf("not notifying about retried jobs")
}
// add the job as a tab on Bugsnag.com
event.MetaData.AddStruct("Job", job)
// set the user correctly
event.User = &User{Id: job.UserId, Email: job.UserEmail}
}
}
// continue notifying as normal
return nil
})
Advanced Usage
If you want to have multiple different configurations around in one program,
you can use bugsnag.New()
to create multiple independent instances of
Bugsnag. You can use these without calling bugsnag.Configure()
, but bear in
mind that until you call bugsnag.Configure()
unhandled panics will not be
sent to bugsnag.
notifier := bugsnag.New(bugsnag.Configuration{
APIKey: "YOUR_OTHER_API_KEY",
})
In fact any place that lets you pass in rawData
also allows you to pass in
configuration. For example to send http errors to one bugsnag project, you
could do:
bugsnag.Handler(nil, bugsnag.Configuration{APIKey: "YOUR_OTHER_API_KEY"})
GroupingHash
If you need to override Bugsnag's grouping algorithm, you can set the
GroupingHash
in an OnBeforeNotify
:
bugsnag.OnBeforeNotify(
func (event *bugsnag.Event, config *bugsnag.Configuration) error {
event.GroupingHash = calculateGroupingHash(event)
return nil
})
Documentation ¶
Overview ¶
Package bugsnag captures errors in real-time and reports them to Bugsnag (http://bugsnag.com).
Using bugsnag-go is a three-step process.
1. As early as possible in your program configure the notifier with your APIKey. This sets up handling of panics that would otherwise crash your app.
func init() { bugsnag.Configure(bugsnag.Configuration{ APIKey: "YOUR_API_KEY_HERE", }) }
2. Add bugsnag to places that already catch panics. For example you should add it to the HTTP server when you call ListenAndServer:
http.ListenAndServe(":8080", bugsnag.Handler(nil))
If that's not possible, for example because you're using Google App Engine, you can also wrap each HTTP handler manually:
http.HandleFunc("/" bugsnag.HandlerFunc(func (w http.ResponseWriter, r *http.Request) { ... })
3. To notify Bugsnag of an error that is not a panic, pass it to bugsnag.Notify. This will also log the error message using the configured Logger.
if err != nil { bugsnag.Notify(err) }
For detailed integration instructions see https://bugsnag.com/docs/notifiers/go.
Configuration ¶
The only required configuration is the Bugsnag API key which can be obtained by clicking "Settings" on the top of https://bugsnag.com/ after signing up. We also recommend you set the ReleaseStage and AppVersion if these make sense for your deployment workflow.
RawData ¶
If you need to attach extra data to Bugsnag notifications you can do that using the rawData mechanism. Most of the functions that send errors to Bugsnag allow you to pass in any number of interface{} values as rawData. The rawData can consist of the Severity, Context, User or MetaData types listed below, and there is also builtin support for *http.Requests.
bugsnag.Notify(err, bugsnag.SeverityError)
If you want to add custom tabs to your bugsnag dashboard you can pass any value in as rawData, and then process it into the event's metadata using a bugsnag.OnBeforeNotify() hook.
bugsnag.Notify(err, account) bugsnag.OnBeforeNotify(func (e *bugsnag.Event, c *bugsnag.Configuration) { for datum := range e.RawData { if account, ok := datum.(Account); ok { e.MetaData.Add("account", "name", account.Name) e.MetaData.Add("account", "url", account.URL) } } })
If necessary you can pass Configuration in as rawData, or modify the Configuration object passed into OnBeforeNotify hooks. Configuration passed in this way only affects the current notification.
Index ¶
- Constants
- Variables
- func AutoNotify(rawData ...interface{})
- func Configure(config Configuration)
- func Handler(h http.Handler, rawData ...interface{}) http.Handler
- func HandlerFunc(h http.HandlerFunc, rawData ...interface{}) http.HandlerFunc
- func Notify(err error, rawData ...interface{}) error
- func OnBeforeNotify(callback func(event *Event, config *Configuration) error)
- func Recover(rawData ...interface{})
- type Configuration
- type Context
- type Event
- type MetaData
- type Notifier
- type User
Examples ¶
Constants ¶
const VERSION = "1.0.2"
The current version of bugsnag-go.
Variables ¶
var ( SeverityError = severity{"error"} SeverityWarning = severity{"warning"} SeverityInfo = severity{"info"} )
Sets the severity of the error on Bugsnag. These values can be passed to Notify, Recover or AutoNotify as rawData.
Functions ¶
func AutoNotify ¶
func AutoNotify(rawData ...interface{})
AutoNotify logs a panic on a goroutine and then repanics. It should only be used in places that have existing panic handlers further up the stack. See bugsnag.Recover(). The rawData is used to send extra information along with any panics that are handled this way. Usage: defer bugsnag.AutoNotify()
Example ¶
Output:
func Configure ¶
func Configure(config Configuration)
Configure Bugsnag. The only required setting is the APIKey, which can be obtained by clicking on "Settings" in your Bugsnag dashboard. This function is also responsible for installing the global panic handler, so it should be called as early as possible in your initialization process.
Example ¶
Output:
func Handler ¶
Handler creates an http Handler that notifies Bugsnag any panics that happen. It then repanics so that the default http Server panic handler can handle the panic too. The rawData is used to send extra information along with any panics that are handled this way.
Example ¶
Output:
Example (CustomHandlers) ¶
Output:
Example (CustomServer) ¶
Output:
func HandlerFunc ¶
func HandlerFunc(h http.HandlerFunc, rawData ...interface{}) http.HandlerFunc
HandlerFunc creates an http HandlerFunc that notifies Bugsnag about any panics that happen. It then repanics so that the default http Server panic handler can handle the panic too. The rawData is used to send extra information along with any panics that are handled this way. If you have already wrapped your http server using bugsnag.Handler() you don't also need to wrap each HandlerFunc.
func Notify ¶
Notify sends an error to Bugsnag along with the current stack trace. The rawData is used to send extra information along with the error. For example you can pass the current http.Request to Bugsnag to see information about it in the dashboard, or set the severity of the notification.
Example ¶
Output:
func OnBeforeNotify ¶
func OnBeforeNotify(callback func(event *Event, config *Configuration) error)
OnBeforeNotify adds a callback to be run before a notification is sent to Bugsnag. It can be used to modify the event or its MetaData. Changes made to the configuration are local to notifying about this event. To prevent the event from being sent to Bugsnag return an error, this error will be returned from bugsnag.Notify() and the event will not be sent.
Example ¶
Output:
Types ¶
type Configuration ¶
type Configuration struct { // Your Bugsnag API key, e.g. "c9d60ae4c7e70c4b6c4ebd3e8056d2b8". You can // find this by clicking Settings on https://bugsnag.com/. APIKey string // The Endpoint to notify about crashes. This defaults to // "https://notify.bugsnag.com/", if you're using Bugsnag Enterprise then // set it to your internal Bugsnag endpoint. Endpoint string // The current release stage. This defaults to "production" and is used to // filter errors in the Bugsnag dashboard. ReleaseStage string // The currently running version of the app. This is used to filter errors // in the Bugsnag dasboard. If you set this then Bugsnag will only re-open // resolved errors if they happen in different app versions. AppVersion string // The hostname of the current server. This defaults to the return value of // os.Hostname() and is graphed in the Bugsnag dashboard. Hostname string // The Release stages to notify in. If you set this then bugsnag-go will // only send notifications to Bugsnag if the ReleaseStage is listed here. NotifyReleaseStages []string // packages that are part of your app. Bugsnag uses this to determine how // to group errors and how to display them on your dashboard. You should // include any packages that are part of your app, and exclude libraries // and helpers. You can list wildcards here, and they'll be expanded using // filepath.Glob. The default value is []string{"main*"} ProjectPackages []string // Any meta-data that matches these filters will be marked as [REDACTED] // before sending a Notification to Bugsnag. It defaults to // []string{"password", "secret"} so that request parameters like password, // password_confirmation and auth_secret will not be sent to Bugsnag. ParamsFilters []string // The PanicHandler is used by Bugsnag to catch unhandled panics in your // application. The default panicHandler uses mitchellh's panicwrap library, // and you can disable this feature by passing an empty: func() {} PanicHandler func() // The logger that Bugsnag should log to. Uses the same defaults as go's // builtin logging package. bugsnag-go logs whenever it notifies Bugsnag // of an error, and when any error occurs inside the library itself. Logger *log.Logger // The http Transport to use, defaults to the default http Transport. This // can be configured if you are in an environment like Google App Engine // that has stringent conditions on making http requests. Transport http.RoundTripper // Whether bugsnag should notify synchronously. This defaults to false which // causes bugsnag-go to spawn a new goroutine for each notification. Synchronous bool }
Configuration sets up and customizes communication with the Bugsnag API.
var Config Configuration
The configuration for the default bugsnag notifier.
type Context ¶
type Context struct {
String string
}
Context is the context of the error in Bugsnag. This can be passed to Notify, Recover or AutoNotify as rawData.
type Event ¶
type Event struct { // The original error that caused this event, not sent to Bugsnag. Error *errors.Error // The rawData affecting this error, not sent to Bugsnag. RawData []interface{} // The error class to be sent to Bugsnag. This defaults to the type name of the Error, for // example *error.String ErrorClass string // The error message to be sent to Bugsnag. This defaults to the return value of Error.Error() Message string // The stacktrrace of the error to be sent to Bugsnag. Stacktrace []stackFrame // The context to be sent to Bugsnag. This should be set to the part of the app that was running, // e.g. for http requests, set it to the path. Context string // The severity of the error. Can be SeverityError, SeverityWarning or SeverityInfo. Severity severity // The grouping hash is used to override Bugsnag's grouping. Set this if you'd like all errors with // the same grouping hash to group together in the dashboard. GroupingHash string // User data to send to Bugsnag. This is searchable on the dashboard. User *User // Other MetaData to send to Bugsnag. Appears as a set of tabbed tables in the dashboard. MetaData MetaData }
Event represents a payload of data that gets sent to Bugsnag. This is passed to each OnBeforeNotify hook.
type MetaData ¶
MetaData is added to the Bugsnag dashboard in tabs. Each tab is a map of strings -> values. You can pass MetaData to Notify, Recover and AutoNotify as rawData.
Example ¶
Output:
func (MetaData) Add ¶
Add creates a tab of Bugsnag meta-data. If the tab doesn't yet exist it will be created. If the key already exists, it will be overwritten.
type Notifier ¶
type Notifier struct { Config *Configuration RawData []interface{} }
Notifier sends errors to Bugsnag.
func New ¶
func New(rawData ...interface{}) *Notifier
New creates a new notifier. You can pass an instance of bugsnag.Configuration in rawData to change the configuration. Other values of rawData will be passed to Notify.
func (*Notifier) AutoNotify ¶
func (notifier *Notifier) AutoNotify(rawData ...interface{})
AutoNotify notifies Bugsnag of any panics, then repanics. It sends along any rawData that gets passed in. Usage: defer AutoNotify()
type User ¶
type User struct { Id string `json:"id,omitempty"` Name string `json:"name,omitempty"` Email string `json:"email,omitempty"` }
User represents the searchable user-data on Bugsnag. The Id is also used to determine the number of users affected by a bug. This can be passed to Notify, Recover or AutoNotify as rawData.