# Bugsnag Elixir [![Build Status](https://travis-ci.org/jarednorman/bugsnag-elixir.svg?branch=master)](https://travis-ci.org/jarednorman/bugsnag-elixir)
Capture exceptions and send them to the [Bugsnag](http://bugsnag.com) API!
## Installation
```elixir
# 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: "prod"
# Set `use_logger: true` to report all uncaught exceptions (using Erlang SASL)
config :bugsnag, use_logger: true
```
## 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_USE_LOGGER`
- `BUGSNAG_RELEASE_STAGE`
Or you can define from which env vars it should be loaded, eg:
```elixir
config :bugsnag, :api_key, {:system, "YOUR_ENV_VAR" [, optional_default]}
config :bugsnag, :release_stage, {:system, "YOUR_ENV_VAR" [, optional_default]}
config :bugsnag, :use_logger, {:system, "YOUR_ENV_VAR" [, optional_default]}
```
Ofcourse you can use regular values as in Installation guide.
### Manual reporting
```elixir
# 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:
```elixir
# ...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:
```elixir
# ...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"
- `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
- `metadata` - Arbitrary metadata (See [Bugsnag docs](https://docs.bugsnag.com/api/error-reporting/#json-payload) 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](http://www.erlang.org/doc/apps/sasl/error_logging.html)
compliant processes that crash will send an error report to the `Bugsnag.Logger`.
The logger will take care of sending the error to Bugsnag.