Reporter.Bugsnag

This reporter sends tracing information for failing requests to Bugsnag, a platform for monitoring applications. Learn more about Bugsnag on their website:

https://www.bugsnag.com/

Documentation

report :: Handler -> Text -> TracingSpan -> IO ()

This function takes the root span of a completed request and reports it to Bugsnag, if there has been a failure. A request that completed succesfully is not reported.

If we squint a bit, the rough shape of data that Bugsnag expects of us is:

event {attributes} [breadcrumbs]

Meaning: we can use various attributes to describe an event and in addition pass a list of "breadcrumbs", other events that took place before the one the report we're making is about.

The root span we pass in is a tree structure. It can have child spans, which in turn can have child spans, etc. Each span is marked with whether it succeeded or failed. If one of the children of a span failed, the span itself failed too.

To turn this tree structure into the data that Bugsnag expects we're going to take the following approach. First we're going to find the 'root cause span'. This is the most recently started span that failed. The data in this span and it's parents is going to make up the main event to Bugsnag. All other spans that completed before the root cause span started we'll turn into breadcrumbs. For some span tree it might look like this:

^ failed span, a = 1 -> event { a = 1, t succeeded span i failed span, b = 2 -> b = 2, m failed span, c = 3 -> c = 3 } e succeeded span -> [ breadcrumb1 ^ succeeded span -> , breadcrumb2 ]

A span that happened _after_ the root cause event completed we're not reporting.

Example usage:

settings <- Bugsnag.decode
handler <- Bugsnag.handler settings
Bugsnag.report handler "request-id" span

data Handler

Contextual information this reporter needs to do its work. You can create one using handler.

handler :: Settings -> IO Handler

Create a Handler for a specified set of Settings. Do this once when your application starts and reuse the Handler you get.

data Settings

Configuration settings for this reporter. A value of this type can be read from the environment using the decoder function.

decoder :: Decoder Settings

Read Settings from environment variables. Default variables will be used in case no environment variable is set for an option.

apiKey :: Settings -> Secret ApiKey

The Bugsnag API key to use. This determines which Bugsnag project your errors will end up in.

environment variable

BUGSNAG_API_KEY

default value

*****

appName :: Settings -> Namespace

The name of this application. This will be attached to all bugsnag reports.

environment variable

LOG_ROOT_NAMESPACE

default value

your-application-name-here

appEnvironment :: Settings -> Environment

The environment this application is running in. This will be attached to all bugsnage reports.

environment variable

ENVIRONMENT

default value

development