Bugsnag Elixir

Capture exceptions and send them to the Bugsnag API!

Installation

# Add it to your deps in your projects mix.exs
defp deps do
  [{:bugsnag, "~> 1.5.0"}]
end

# Now, list the :bugsnag application as your application dependency:
def application do
  [applications: [:bugsnag]]
end

# Open up your config/config.exs (or appropriate project config)
config :bugsnag, api_key: "bbf085fc54ff99498ebd18ab49a832dd"

# Set the release stage in your environment configs (e.g. config/prod.exs)
config :bugsnag, release_stage: "production"

# Set the notify release stages to limit reporting the errors based on your environment
# Defaults to ["production"]
config :bugsnag, notify_release_stages: ["production"]

# Set app version, so "fixed" errors won't come back within the same version
config :bugsnag, app_version: Mix.Project.config[:version]

# Set `use_logger: true` to report all uncaught exceptions (using Erlang SASL)
config :bugsnag, use_logger: true

# Override the default bugsnag endpoint url
config :bugsnag, endpoint_url: "https://notify.bugsnag.com"

Usage

Configuration

You can use environment variables in order to set up all options. You can set default variable names, and don't touch config files, eg:

BUGSNAG_API_KEY
BUGSNAG_ENDPOINT_URL
BUGSNAG_USE_LOGGER
BUGSNAG_RELEASE_STAGE
BUGSNAG_NOTIFY_RELEASE_STAGES
BUGSNAG_HOSTNAME
BUGSNAG_APP_TYPE
BUGSNAG_APP_VERSION

Or you can define from which env vars it should be loaded, eg:

config :bugsnag, :api_key,        {:system, "YOUR_ENV_VAR" [, optional_default]}
config :bugsnag, :endpoint_url,   {:system, "YOUR_ENV_VAR" [, optional_default]}
config :bugsnag, :release_stage,  {:system, "YOUR_ENV_VAR" [, optional_default]}
config :bugsnag, :notify_release_stages,  {:system, "YOUR_ENV_VAR" [, optional_default]}
config :bugsnag, :use_logger,     {:system, "YOUR_ENV_VAR" [, optional_default]}
config :bugsnag, :hostname,       {:system, "YOUR_ENV_VAR" [, optional_default]}
config :bugsnag, :app_type,       {:system, "YOUR_ENV_VAR" [, optional_default]}
config :bugsnag, :app_version,    {:system, "YOUR_ENV_VAR" [, optional_default]}

Ofcourse you can use regular values as in Installation guide.

Manual reporting

# Report an exception.
try do
  :foo = :bar
rescue
  exception -> Bugsnag.report(exception)
end

In some cases you might want to send the report synchronously, to make sure that it got sent. You can do that with:

# ...an exception occured
  Bugsnag.sync_report(exception)

Options

These are optional fields to fill the bugsnag report with more information, depending on your specific usage scenario. They can be passed into the Bugsnag.report/2 function like so:

# ...an exception occured
  Bugsnag.report(exception, severity: "warn", user: %{name: "Jane Doe"})

api_key - Allows overriding any configured api key manually
stacktrace - Allows explicitly passing in a stacktrace used to generate the stacktrace object that is sent to bugsnag
severity - Sets the severity explicitly to "error", "warning" or "info"
release_stage - Explicitly sets an arbitrary release stage e.g. "development", "test" or "production"
notify_release_stages - States in which environments, bugnsnag will report errors e.g. "development", "test" or "production". Defaults to ["production"]
context - Allows passing in context information, like e.g. the name of the file the crash occured in
user - Allows passing in user information, needs to be a map with one or more of the following fields (which are then searchable):
- id - Any binary identifier for the user
- name - Full name of the user
- email - Full email of the user
os_version and hostname - Will be aggregated within Bugsnag's device field and can be used as a filter
app_type - The application type (defaults to elixir)
app_version - The version of your application in which the error occurred
metadata - Arbitrary metadata (See Bugsnag docs for more information)

Logger

Set the use_logger option to true in your application's config.exs. So long as :bugsnag is started, any SASL compliant processes that crash will send an error report to the Bugsnag.Logger. The logger will take care of sending the error to Bugsnag.