tremlab / bugsnag-elm / BugsnagElm

Send error reports to bugsnag.

General example

import BugsnagElm exposing (Bugsnag)
import Task exposing (Task)

-- initialize bugsnag. You will probably need to pull values from the env or flags
bugsnag : Bugsnag
bugsnug =
    BugsnagElm.start
        { apiKey = "abcdef1234...."
        , appVersion = "xyz0101010......"
        , releaseStage = "test"
        , enabledReleaseStages = ["production", "staging", "test"]
        , user =
            Just
                { id = flags.currentUserId
                , username = flags.username
                , email = flags.email
                }
        }

-- send error reports within your app's update function
update msg model =
    .... ->
        -- log some debug info
        ( model
        , bugsnag.info
            "Hitting the slothNinja API."
            "Page.Customer.Login.Main"
            Dict.empty
            |> Task.attempt (\() -> NoOp) -- convert the Task into a Cmd
        )

    .... ->
        -- log an error
        ( model
        , [ ( "Payload", toString payload ) ]
            |> Dict.fromList
            |> bugsnag.error
                "Unexpected payload from the slothNinja API."
                "Page.Customer.Login.Main"
            |> Task.attempt (\() -> NoOp) -- convert the Task into a Cmd
        )

Basic Usage

start : BugsnagConfig -> Bugsnag

Return a Bugsnag record configured with the given BugsnagConfig details.

bugsnag = BugsnagElm.start
    { apiKey = "abcdef1234...."
    , appVersion = "xyz0101010......"
    , releaseStage = "test"
    , enabledReleaseStages = ["production", "staging", "test"]
    , user =
        Just
            { id = "42"
            , username = "Grace Hopper"
            , email = "support@bugsnag.com"
            }
    }


type alias Bugsnag =
{ error : String -> String -> Dict String Json.Encode.Value -> Task Http.Error ()
, warning : String -> String -> Dict String Json.Encode.Value -> Task Http.Error ()
, info : String -> String -> Dict String Json.Encode.Value -> Task Http.Error () 
}

Functions preapplied with apiKey, code version, user info and releaseStage, separated by Severity.

Create one using start, and then throughout your app you can call bugsnag.error to send the error report.

When calling any of the functions herein, it will return Task.succeed () if the message was successfully sent to Bugsnag. Otherwise it fails with the Http.Error responsible. I recommend you ignore the error in your code; although it is possible for the bugsnag api to go down, it is exceedingly rare, and not something worth disrupting your user's experience for.

    bugsnag.error "problem accessing the database." "Page.Checkout" Dict.empty
        |> Task.attempt (\() -> NoOp) -- convert the Task into a Cmd


type alias BugsnagConfig =
{ apiKey : String
, appVersion : String
, releaseStage : String
, enabledReleaseStages : List String
, user : Maybe User 
}

Basic data needed to define the local client for a BugsnagElm instance. Applies to all error reports that may occur in the app, with error-specific data added later in notify


type alias User =
{ id : String
, username : String
, email : String 
}

A record of datapoints bugsnag's api can accept for user data. To display additional custom user data alongside these standard fields on the Bugsnag website, the custom data should be included in the 'metadata' object in a user object. learn more


type Severity
    = Error
    | Warning
    | Info

Severity levels - bugsnag only accepts these three.

Customized Usage

notify : BugsnagConfig -> Severity -> String -> String -> Dict String Json.Encode.Value -> Task Http.Error ()

Send a message to bugsnag. start provides a nice wrapper around this.

Arguments:

If the message was successfully sent to Bugsnag, it returns Task.succeed () Otherwise it fails with the Http.Error responsible. I recommend you ignore this error in your code; although it is possible for the bugsnag api to go down, it is exceedingly rare, and not something worth disrupting your user's experience for.

notify bugsnagConfig Error "cannot connect to database" "Page.Login" Dict.empty