Honeybadger for Elixir

Source CodeHex PackageUpgrading to v0.11? See the release notes

Getting Started

ElixirSips

Watch our screencast by Josh Adams of ElixirSips!

Configuration

You can set configuration options in config.exs. It looks like this:

config :honeybadger,
  api_key: "sup3rs3cr3tk3y",
  environment_name: :prod

If you’d rather read, eg., environment_name from the OS environment, you can do like this:

config :honeybadger,
  environment_name: {:system, "HONEYBADGER_ENV"},
  revision: {:system, "HEROKU_SLUG_COMMIT"}

NOTE: This works only for the string options, and environment_name.

Here are all of the options you can pass in the keyword list:

Name Description Default
app Name of your app’s OTP Application as an atom Mix.Project.config[:app]
api_key Your application’s Honeybadger API key System.get_env("HONEYBADGER_API_KEY"))
environment_name (required) The name of the environment your app is running in. nil
exclude_envs Environments that you want to disable Honeybadger notifications [:dev, :test]
hostname Hostname of the system your application is running on :inet.gethostname
origin URL for the Honeybadger API "https://api.honeybadger.io"
project_root Directory root for where your application is running System.cwd/0
revision The project’s git revision nil
filter Module implementing Honeybadger.Filter to filter data before sending to Honeybadger.io Honeybadger.Filter.Default
filter_keys A list of keywords (atoms) to filter. Only valid if filter is Honeybadger.Filter.Default [:password, :credit_card]
filter_args If true, will remove function arguments in backtraces true
filter_disable_url If true, will remove the request url false
filter_disable_session If true, will remove the request session false
filter_disable_params If true, will remove the request params false
fingerprint_adapter Implementation of FingerprintAdapter behaviour  
notice_filter Module implementing Honeybadger.NoticeFilter. If nil, no filtering is done. Honeybadger.NoticeFilter.Default
use_logger Enable the Honeybadger Logger for handling errors outside of web requests true
ignored_domains Add domains to ignore Error events in Honeybadger.Logger. [:cowboy]
breadcrumbs_enabled Enable breadcrumb event tracking false
ecto_repos Modules with implemented Ecto.Repo behaviour for tracking SQL breadcrumb events []

Breadcrumbs allow you to record events along a processes execution path. If an error is thrown, the set of breadcrumb events will be sent along with the notice. These breadcrumbs can contain useful hints while debugging.

Breadcrumbs are stored in the logger context, referenced by the calling process. If you are sending messages between processes, breadcrumbs will not transfer automatically. Since a typical system might have many processes, it is advised that you be conservative when storing breadcrumbs as each breadcrumb consumes memory.

Automatic Breadcrumbs

We leverage the telemetry library to automatically create breadcrumbs from specific events.

Phoenix

If you are using phoenix (>= v1.4.7) we add a breadcrumb from the router start event.

Ecto

We can create breadcrumbs from Ecto SQL calls if you are using ecto_sql (>= v3.1.0). You also must specify in the config which ecto adapters you want to be instrumented:

config :honeybadger,
  ecto_repos: [MyApp.Repo]

Public Interface

Honeybadger.notify: Send an exception to Honeybadger.

Use the Honeybadger.notify/2 function to send exception information to the collector API. The first parameter is the exception and the second parameter is the context/metadata/fingerprint. There is also a Honeybadger.notify/1 which doesn’t require the second parameter.

Examples:

try do
  File.read! "this_file_really_should_exist_dang_it.txt"
rescue
  exception ->
    context = %{user_id: 5, account_name: "Foo"}
    Honeybadger.notify(exception, metadata: context, stacktrace: __STACKTRACE__)
end

Honeybadger.context/1: Set metadata to be sent if an error occurs

Honeybadger.context/1 is provided for adding extra data to the notification that gets sent to Honeybadger. You can make use of this in places such as a Plug in your Phoenix Router or Controller to ensure useful debugging data is sent along.

Examples:

def MyPhoenixApp.Controller
  use MyPhoenixApp.Web, :controller

  plug :set_honeybadger_context

  def set_honeybadger_context(conn, _opts) do
    user = get_user(conn)
    Honeybadger.context(user_id: user.id, account: user.account.name)
    conn
  end
end

Honeybadger.context/1 stores the context data in the process dictionary, so it will be sent with errors/notifications on the same process. The following Honeybadger.notify/1 call will not see the context data set in the previous line.

Honeybadger.context(user_id: 5)
Task.start(fn ->
  # this notify does not see the context set earlier
  # as this runs in a different elixir/erlang process.
  Honeybadger.notify(%RuntimeError{message: "critical error"})
end)

Honeybadger.add_breadcrumb/2: Store breadcrumb within process

Appends a breadcrumb to the notice. Use this when you want to add some custom data to your breadcrumb trace in effort to help debugging. If a notice is reported to Honeybadger, all breadcrumbs within the execution path will be appended to the notice. You will be able to view the breadcrumb trace in the Honeybadger interface to see what events led up to the notice.

Examples:

Honeybadger.add_breadcrumb("Email sent", metadata: %{
  user: user.id,
  message: message
})

Sample Application

If you’d like to see the module in action before you integrate it with your apps, check out our sample Phoenix application.

You can deploy the sample app to your Heroku account by clicking this button:

Deploy

Don’t forget to destroy the Heroku app after you’re done so that you aren’t charged for usage.

The code for the sample app is available on Github, in case you’d like to read through it, or run it locally.