Gin integration guide

Add BugSnag to your Gin applications.

This library supports Go 1.11 and above. To integrate with older versions of Go, check out our legacy integration.

Installation

Download the code via go get:

go get github.com/bugsnag/bugsnag-go-gin

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/v2"
import "github.com/bugsnag/bugsnag-go-gin"

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

    g.Use(bugsnaggin.AutoNotify(bugsnag.Configuration{
        // Your BugSnag project API key, required unless set as environment
        // variable $BUGSNAG_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"},
    }))
}

You can find your API key in Project Settings from your BugSnag dashboard.

Using context.Context to manage HTTP session data

We strongly recommend passing in context.Context to appropriate BugSnag calls. Passing the context.Context from *http.Request objects stored within the Gin Context, will automatically attach HTTP request data to your error reports, as well as session data that helps BugSnag track the stability of your application. For more information around how to use context.Context with BugSnag, see the context reference here.

Context can be retrieved from an HTTP request or created if outside a request (see session tracking for more details on sessions)

// Get context from an HTTP request
ctx = ginContext.Request.Context()
// or from manually starting a session outside a http request
ctx = bugsnag.StartSession(context.Background())

Reporting unhandled panics

Unhandled panics are reported using panic-monitor, which is a program launcher that automatically reports any panics which occur in your program.

After completing installation and basic configuration, set the BUGSNAG_API_KEY environment variable to the API key for your project and launch the monitor with your program and its arguments.

BUGSNAG_API_KEY="YOUR API KEY HERE" panic-monitor ./my-app --my-app-flag

Unhandled panics will be automatically reported and error data will begin to appear in your project’s dashboard.

#!/usr/bin/env bash

# Forward signals to the app process so it terminates if
# requested by the system
_forward_signal() {
    sig="$1"
    kill -$sig "$app_pid" 2>/dev/null
    wait $app_pid
}

_trap_signals() {
    for sig in "$@"; do
        trap "_forward_signal $sig" "$sig"
    done
}

# Wait to allow potential unhandled panic requests to complete
_at_exit() {
  sleep 3
}

_trap_signals INT TERM
trap _at_exit EXIT

./my-go-app &

# Wait until the app process terminates (ensuring signals
# can be captured)
app_pid=$!
wait $app_pid

go func(ctx context.Context) {
    defer bugsnag.AutoNotify(ctx)

    // ...
}(ctx)

go func(ctx context.Context) {
    defer bugsnag.Recover(ctx)

    // ...
}(ctx)

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

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.

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, ctx,
    bugsnag.MetaData{
        "Account": {
            "Name": Account.Name,
            "Paying": Account.Plan.Premium,
        },
    })

For more information, see the reporting handled errors reference.

See this reference to learn more about the ctx argument and the advantages of using it.

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, ctx,
    bugsnag.User{Id: "1234", Name: "Conrad", Email: "me@example.com"})

For more information, see the reporting handled errors reference.

See this reference to learn more about the ctx argument and the advantages of using it.

Session tracking

BugSnag tracks the number of “sessions” that happen within your application. This allows you to compare stability scores between releases and helps you to understand the quality of your releases.

Sessions are captured and reported by default. This behavior can be disabled using the AutoCaptureSessions configuration option.

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

• Catch and report errors in your client-side JavaScript with the Web browser JavaScript guide
• Monitor the performance of your web app in your users’ browsers with the Web performance guide
• View bugsnag-go, the library powering this integration, on GitHub
• Get support for your questions and feature requests