Docs Platforms Go Gin Legacy
bugsnag.com Start Free Trial

Legacy Gin integration guide

Add BugSnag to your legacy Gin applications.

This integration supports Go 1.10 and earlier. For newer applications, see the updated integration guide.

Installation

Use bugsnag-go version 1.3.2 with Go 1.6 and earlier.

Use bugsnag-go version 1.9.0 with Go 1.10 and earlier.

The following is a few methods of installing the library with a pinned version.

Use BugSnag with Go 1.10 and below with dep

You can learn about using dep for dependency management here.

In your Gopkg.toml file add a dependency on the bugsnag-go library, specifying one of the versions from installation:

[[constraint]]
  name = "github.com/bugsnag/bugsnag-go"
  version = "1.3.2"

then run dep ensure to lock your version of bugsnag-go to a version that supports Go versions older than 1.11.

Use BugSnag with Go 1.10 and below with go get

If you wish to use the built in go get command for fetching dependencies, you’ll have to manually check out an older version of the notifier and downgrade the downloaded version:

go get github.com/bugsnag/bugsnag-go
cd $GOPATH/src/github.com/bugsnag/bugsnag-go
git checkout v1.3.2
go build

Note: If you do not have the $GOPATH environment variable configured, you should replace $GOPATH with $GOROOT.

Basic configuration

Add bugsnaggin.AutoNotify immediately after the gin.Recovery middleware or gin.Default initialization in main.go. This causes unhandled panics to notify BugSnag automatically and configures BugSnag for reporting handled errors.


import "github.com/bugsnag/bugsnag-go"
import "github.com/bugsnag/bugsnag-go/gin"

func main() {
    g := gin.Default()

    g.Use(bugsnaggin.AutoNotify(bugsnag.Configuration{
        // Your BugSnag project API key
        APIKey:          "YOUR API KEY HERE",
        // The import paths for the Go packages containing your source files
        ProjectPackages: []string{"main", "github.com/org/myapp"},
    }))
}

Reporting unhandled panics

After completing installation and basic configuration, unhandled panics will be automatically reported. Error data will begin to appear in your project’s dashboard. To ensure panics from goroutines are handled effectively, see reporting panics from goroutines.

This feature is enabled via the Configuration.PanicHandler, which forks and monitors the application as a sub-process, reporting any unhandled panics.

Reporting handled errors

Sometimes it is useful to manually notify BugSnag of a problem. To do this, call bugsnag.Notify()

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

When reporting handled errors, it’s often helpful to send us custom diagnostic data or to adjust the severity of particular errors. For more information, see the reporting handled errors reference.

Reporting panics from goroutines

Since goroutines are generally non-blocking, panics captured on a goroutine may crash the application before having the opportunity to be delivered to BugSnag unless intentionally handled.

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.

go func() {
    defer bugsnag.AutoNotify()

    // ...
}()

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

    // ...
}()

Sending diagnostic 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.

Custom metaData appears as tabs on error reports on your BugSnag dashboard. 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,
        },
    })

For more information, see the reporting handled errors reference.

Identifying users

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@example.com"})

For more information, see the reporting handled errors reference.

Session tracking

BugSnag can track the number of “sessions” that happen in your application. This enables BugSnag to provide and compare stability scores between releases to help you understand the quality of your releases.

Session tracking requires version 1.4 of bugsnag-go, and is not available for legacy Go applications.

Tracking releases

Configure your app version to see the release that each error was introduced in.

bugsnag.Configure(bugsnag.Configuration{
    AppVersion: "1.2.3",
})

Then set up a build tool integration to enable linking to code in your source control provider from the releases dashboard, timeline annotations, and stack traces.

Next steps