Well-documented, maintainable, idiomatic, opinionated, and unofficial rewrite of the Bugsnag Go notifier. See this document for an overview of the differences between this package and the official notifier.
In addition to the notifier library in github.com/kinbiko/bugsnag
, there's a bugsnag
command-line application in github.com/kinbiko/bugsnag/cmd/bugsnag
that can easily report builds and releases to Bugsnag for an even better debugging experience.
Make sure you're importing this package, and not the official notifier:
import "github.com/kinbiko/bugsnag"
Then set up your *bugsnag.Notifier
, the type that exposes the main API of this package, based on a bugsnag.Configuration
.
notifier, err := bugsnag.New(bugsnag.Configuration{
APIKey: "<<YOUR API KEY HERE>>",
AppVersion: "1.3.5", // Some semver
ReleaseStage: "production",
})
if err != nil {
panic(err) // TODO: Handle error in an appropriate manner
}
defer notifier.Close() // Close once you know there are no further calls to notifier.Notify or notifier.StartSession.
In order to get the most accurate filepaths in stacktraces (generated in the case of panics and bugsnag.Error
s), make sure to build (or run) your application with the -trimpath
flag set:
go build -trimpath ./cmd/myapp
Applications built without -trimpath
have stacktraces that appear with absolute paths of the machine where go build
was executed.
The Notifier is now ready for use.
Call notifier.Notify()
to notify Bugsnag about an error in your application.
if err != nil {
notifier.Notify(ctx, err)
}
See the With*
methods in the docs to learn how to attach additional information to your error reports:
In Go, errors don't include a stacktrace, so it can be difficult to track where an error originates, if the location that it is being reported is different to where it is first created.
Similarly, any context.Context
data may get lost if reporting at a location higher up the stack than where the error occurred.
To prevent this loss of information, this package exposes an notifier.Wrap
method that can wrap an existing error with its stacktrace along with the context data at this location.
You can then safely call notifier.Notify()
at a single location if you so wish.
if err != nil {
return notifier.Wrap(ctx, err, "unable to foo the bar")
}
You can safely re-wrap this error again should you so wish.
IMPORTANT: In order to get the most out of this package, it is recommended to wrap your errors as far down the stack as possible.
If you would like to mark your error as unhandled, e.g. in the case of a panic, you should set these flags explicitly on the error returned from Wrap.
if r := recover(); r != nil {
// You can use notifier.Wrap as well, but this requires a type cast.
err := bugsnag.Wrap(ctx, fmt.Errorf("unhandled panic when calling FooBar: %v", r))
err.Unhandled = true
err.Panic = true
notifier.Notify(ctx, err)
}
For each session, usually synonymous with 'request' (HTTP/gRPC/AMQP/PubSub/etc.), you should call ctx = notifier.StartSession(ctx)
, usually performed in a middleware function.
Any unhandled errors that are reported along with this ctx
will count negatively towards your stability score.
Check out the examples/
directory for more advanced blueprints:
o11y
structural pattern.In particular, the examples highlight the additional the features that are different from, or not found, in the official notifier.
bugsnag
command-line application usageInstall the binary with:
$ go install github.com/kinbiko/bugsnag/cmd/bugsnag@latest
Report a new release to Bugsnag with
$ bugsnag release \
--api-key=$SOME_API_KEY \
--app-version=5.1.2 \
--release-stage=staging \
--repository=https://github.com/kinbiko/bugsnag \
--revision=64414f621b33680419b1cb3e5c622b510207ae1e \
--builder=kinbiko \
--metadata="KEY1=VALUE1,KEY2=VALUE2"
release info published for version 5.1.2
If you have environment variables BUGSNAG_API_KEY
and BUGSNAG_APP_VERSION
(or APP_VERSION
) set, then you can skip the first two (required) flags.
See bugsnag release --help
for more info and additional configuration parameters.