Configuration options

Call bugsnag.Configure() passing it a bugsnag.Configuration object containing any of the following values or empty if configuring through environment variables.

Configuration set through environment variables will also be used when reporting panics.

The only required configuration is the BugSnag API key. We also recommend you set the ReleaseStage, AppType, and AppVersion if these make sense for your deployment workflow.

`APIKey`

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

API key can be loaded from the environment variable BUGSNAG_API_KEY or specified in code:

bugsnag.Configure(bugsnag.Configuration{
    APIKey: "YOUR_API_KEY_HERE",
})

Setting the environment variable BUGSNAG_API_KEY is required for panic handling.

`AppType`

If your app has multiple components with different configurations, it can be useful when filtering error reports to separate them by the type of app, like HTTP router, worker queues, and more.

App type can be loaded from the environment variable BUGSNAG_APP_TYPE or specified in code:

bugsnag.Configure(bugsnag.Configuration{
    AppType: "queue",
})

`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.

App version can be loaded from the environment variable BUGSNAG_APP_VERSION or specified in code:

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

`AutoCaptureSessions`

By default, BugSnag will automatically capture and report session information from your application. Use this flag to disable all automatic reporting.

AutoCaptureSessions can be disabled by setting environment variable BUGSNAG_AUTO_CAPTURE_SESSIONS to 0 or specified in code:

bugsnag.Configure(bugsnag.Configuration{
    AutoCaptureSessions: false,
})

If you want control over what is deemed a session, you can switch off automatic session tracking with the above configuration, and call bugsnag.StartSession(ctx) when appropriate for your application.

`Endpoints`

By default we will send error reports to notify.bugsnag.com and sessions to sessions.bugsnag.com.

If you are using BugSnag On-premise you’ll need to set these to your Event Server and Session Server endpoints. If the notify endpoint is set but the sessions endpoint is not, session tracking will be disabled automatically to avoid leaking session information outside of your server configuration, and a warning will be logged.

Endpoints can be loaded from the environment variables BUGSNAG_NOTIFY_ENDPOINT and BUGSNAG_SESSIONS_ENDPOINT respectively or specified in code:

bugsnag.Configure(bugsnag.Configuration{
    Endpoints: bugsnag.Endpoints{
        Notify:  "http://bugsnag.internal:49000/",
        Sessions: "http://bugsnag.internal:49001/",
    }
})

`Hostname`

The hostname is used to track where errors are coming from in the BugSnag dashboard. The default value is obtained from os.Hostname() so you won’t often need to change this.

Hostname can be loaded from the environment variable BUGSNAG_HOSTNAME or specified in code:

bugsnag.Configure(bugsnag.Configuration{
    Hostname: "go1",
})

`Logger`

By default, the notifier’s log messages will be logged using the global logger.

You can override this by setting the Logger configuration option in code:

bugsnag.Configure(bugsnag.Configuration{
    Logger: app.Logger,
}

`MainContext`

For improved shutdown handling, set the MainContext configuration option passing the main context of your application.

The context is used to control the lifecycle of the event sending goroutine. When the MainContext is marked as Done, an attempt is made to send the remaining events and the goroutine exits gracefully.

You can specify this configuration option in code:

bugsnag.Configure(bugsnag.Configuration{
    MainContext: ctx,
}

Adding metadata

To make custom metadata available to both handled errors and unhandled panics, add metadata through environment variables prefixed with BUGSNAG_METADATA_. The environment variable name after the prefix is expected to be the tab and key name, where the first underscore is the delimiter.

For example, the following variables:

BUGSNAG_METADATA_device_KubePod="carrot-delivery-service-beta1 reg3"
BUGSNAG_METADATA_device_deployment_area=region5_1
BUGSNAG_METADATA_device_fruit_type=apple

Would add the following metadata to the device tab in the event of a panic:

KubePod: carrot-delivery-service-beta1 reg3
deployment_area: region5_1
fruit_type: apple

`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.

NotifyReleaseStages can be loaded as a comma-delimited list from the environment variable BUGSNAG_NOTIFY_RELEASE_STAGES or specified in code:

bugsnag.Configure(bugsnag.Configuration{
    NotifyReleaseStages: []string{"production", "staging"},
})

`OnBeforeNotify`

Add callbacks to modify or discard error events before they are sent to BugSnag. To cancel an event, return an error from the callback.

Custom structures passed to Notify are available in the RawData of the event within the callback. The RawData itself is not delivered as a part of the event, but can be accessed to add information when available.

bugsnag.OnBeforeNotify(
    func(event *bugsnag.Event, config *bugsnag.Configuration) error {
        for _, datum := range event.RawData {
            if user, ok := datum.(*MyUserInfo); ok {
                event.User = &User{Id: user.Id}
            }
        }
    })

OnBeforeNotify callbacks have no effect on unhandled panics. Use metadata variables to add custom metadata to panic events.

If you are not using panic-monitor, all OnBeforeNotify callbacks must be registered prior to calling Configure() or will have no effect on events created from unrecovered panics. Panic handling in bugsnag-go forks the process when Configure() is first called, so any callbacks added after that point will not be present in the monitoring process. See the Reporting unhandled panics guide for more information.

Detailed example with custom metadata and conditional cancellation

For example, lets say our system processes jobs:

type Job struct{
    Retry     bool
    UserId    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 job as a tab in the BugSnag dashboard
                event.MetaData.AddStruct("Job", job)

                // set the user correctly
                event.User = &User{Id: job.UserId, Email: job.UserEmail}
            }
        }

        // continue notifying as normal
        return nil
    })

See Customizing error reports for more examples and a list of available Event properties.

`PanicHandler`

If you are not using panic-monitor, 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 process forking and disable reporting unhandled panics, set PanicHandler to func() {} the first time you call bugsnag.Configure or set environment variable BUGSNAG_DISABLE_PANIC_HANDLER to 1.

bugsnag.Configure(bugsnag.Configuration{
    PanicHandler: func() {},
})

If you are using panic-monitor, this configuration option has no effect.

`ParamsFilters`

Set filters to remove sensitive data before it is attached to events reported to BugSnag.

Any key in the MetaData, HTTP request headers, or HTTP URL query parameters that include any string in the filters will be redacted. The default filters are:

[]string{"password", "secret", "authorization", "cookie", "access_token"}

which prevent fields like password, password_confirmation and secret_answer from being sent.

ParamsFilters can be loaded as a comma-delimited list from the environment variable BUGSNAG_PARAMS_FILTERS or specified in code:

bugsnag.Configure(bugsnag.Configuration{
    ParamsFilters: []string{"password", "secret"},
}

`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.

For matching subpackages within a package you may use the ** notation. For example, github.com/domain/package/** will match all subpackages under package/.

ProjectPackages can be loaded as a comma-delimited list from the environment variable BUGSNAG_PROJECT_PACKAGES or specified in code:

bugsnag.Configure(bugsnag.Configuration{
    ProjectPackages: []string{"main", "github.com/domain/myapp/*"},
}

`ReleaseStage`

The ReleaseStage tracks where your app is deployed. You should set this to production, staging, development or similar as appropriate.

Release stage can be loaded from the environment variable BUGSNAG_RELEASE_STAGE or specified in code:

bugsnag.Configure(bugsnag.Configuration{
    ReleaseStage: "development",
})

`SourceRoot`

The directory where source packages are built and the assumed prefix of package directories. When set, the prefix is trimmed from callstack frame file names before ProjectPackages are stripped, for better readability and error grouping on the BugSnag dashboard. The default value is $GOPATH/src or $GOROOT/src if $GOPATH is unset. At runtime, $GOROOT is the root used during the Go build. See the Go runtime package documentation for more information

SourceRoot can be loaded from the environment variable BUGSNAG_SOURCE_ROOT or specified in code.

`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 ;).

Synchronous can be enabled by setting environment variable BUGSNAG_SYNCHRONOUS to 1 or specified in code:

bugsnag.Configure(bugsnag.Configuration{
    Synchronous: true
})

Or just for one error:

bugsnag.Notify(err, bugsnag.Configuration{Synchronous: true})

This setting has no effect on panic handling, as it is unhandled panics are always sent synchronously to ensure the event is delivered prior to the process terminating.

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