Phoenix and Plug integration guide

Typical installation time: 5 minutes

Hi there! You’ve found Honeybadger’s guide to Phoenix error tracking and performance monitoring. Once installed, Honeybadger will automatically report errors and performance insights from your Phoenix application.

Installing the package

Add the Honeybadger package to deps/0 in your application’s mix.exs:

defp deps do
  [{:honeybadger, "~> 0.30"}]
end

Then run:

mix do deps.get, deps.compile

Finally, update your app’s config.exs file to include the Honeybadger configuration:

config :honeybadger,
  app: :my_app,
  api_key: "PROJECT_API_KEY",
  environment_name: config_env(),
  insights_enabled: true # Enable logging and performance insights

Tip

Set app to your OTP application name (the app value in your mix.exs). Honeybadger uses this to highlight your app’s code in backtraces, making it easier to distinguish your code from library and framework code.

Tip

You can also configure your API key using the HONEYBADGER_API_KEY environment variable:

export HONEYBADGER_API_KEY="PROJECT_API_KEY"

If you use this method, you can omit the api_key option from your configuration.

See the Configuration reference for additional info.

Testing your installation

Note

Honeybadger does not report errors in dev and test environments by default. To enable reporting in development environments, temporarily add exclude_envs: [] to your Honeybadger config.

To test your installation, fire up iex -S mix, then run:

Honeybadger.notify("Hello Elixir!")

If Honeybadger is configured correctly, you should see a new error report in your Honeybadger project dashboard.

You can also send a test error with the included Mix task. It sends the error even in excluded environments, so you do not need to change exclude_envs:

mix honeybadger.test

After you’ve tested your Honeybadger installation, you may want to configure one or more of the following integrations to automatically report errors.

Enabling automatic error reporting

The Honeybadger package can be used as a Plug alongside your Phoenix applications, as a logger backend, and/or as a standalone client for sprinkling in exception notifications where they are needed.

The Honeybadger Plug adds a Plug.ErrorHandler to your pipeline. Simply use the Honeybadger.Plug module inside of a Plug or Phoenix.Router and any crashes will be automatically reported to Honeybadger. It’s best to use Honeybadger.Plug after the Router plugs so that exceptions due to non-matching routes are not reported to Honeybadger.

Phoenix example

defmodule MyappWeb.Router do
  use MyappWeb, :router
  use Honeybadger.Plug

  pipeline :browser do
    [...]
  end
end

Plug example

defmodule MyPlugApp do
  use Plug.Router
  use Honeybadger.Plug

  [... the rest of your plug ...]
end

Configuring Elixir’s logger

When configured, Honeybadger will report errors for any SASL-compliant processes when they crash. Just set the use_logger option to true in your application’s config.exs and you’re good to go:

config :honeybadger,
  use_logger: true

Manually reporting errors

You can use the Honeybadger.notify/2 function to manually report rescued exceptions:

try do
  # Buggy code goes here
rescue
  exception ->
    Honeybadger.notify(exception, stacktrace: __STACKTRACE__)
end

You can also pass a string message to the notify function (the second argument is optional):

Honeybadger.notify("Sign in failed", metadata: %{
  user_id: current_user.id
})

See Reporting Errors for more information.

Reporting custom events

Use the Honeybadger.event/1 and Honeybadger.event/2 functions to send events to Honeybadger Insights for logging and performance monitoring:

Honeybadger.event(%{
  event_type: "user_created",
  user: user.id
})

# Honeybadger.event/2 is a shorthand that automatically adds the event_type
# property to the event:
Honeybadger.event("project_deleted", %{
  project: project.name
})

See Sending custom events for more details.

Sending logs from your infrastructure

Honeybadger isn’t just for errors and application data! You can use our syslog, Vector, or PaaS integrations to send additional data from your infrastructure to Honeybadger Insights, where you can query, visualize, and analyze all of your production data in one place.

Version requirements

See Supported Versions.