Raygun

Capture and send errors in your Elixir applications to Raygun for centralized bug reporting.

Install

Add the dependency to your mix.exs file.

def deps do  
  [{:raygun, "~> 0.3.1"}]
end

Add Raygun, httpoison and tzdata to the list of applications.

def application do
  [applications: [:logger, :raygun, :httpoison, :tzdata]
end

Configuration

Add the following entry to your config/config.exs file.

config :raygun,
    api_key: "<INSERT YOUR API KEY HERE>"

You can OPTIONALLY add other configuration options as well. They will be sent with every error.

tags: list of metadata strings
url: a reference URL
client_name: the name of the application as you want it to appear in Raygun
client_version: the version of the application as you want it to appear in Raygun

config :raygun,
    api_key: "<INSERT YOUR API KEY HERE>",
    tags: ["tag1", "tag2"],
    url: "http://docs.myapp.example.com",
    client_name: "MyApp",
    client_version: "2.3.4"

If you use a Plug, the version (client_version above) should be auto detected for you.

Usage

There are three different ways you can use Raygun. All three ways may be combined, but you might send the same message multiple times if you do that.

Via Plug in Phoenix

Add the plug to your router:

defmodule YourApp.Router do
  use Phoenix.Router
  use Raygun.Plug

  # ...
end

You can also provide a function that takes a Plug.Conn and returns a map with information about the logged in user.

defmodule YourApp.Router do
  use Phoenix.Router
  use Raygun.Plug, user: fn(conn) ->
    %{
      identifier: "<user id>",
      isAnonymous: false, # false if logged in, true if not logged in
      email: "email@example.com",
      fullName: "John Doe",
      firstName: "John",
      uuid: "<uuid>"
    }
  end

  # ...
end

Via the Logger

Any error logged with automatically be sent to Raygun.

Configure the Logger to use the Raygun backend. You can do this programmatically

  Logger.add_backend(Raygun.Logger)

or via configuration by adding Raygun as a backend in config/config.exs:

  config :logger,
    backends: [:console, Raygun.Logger]

Any messages logged at :error level will be automatically sent to Raygun.

If you would like messages to be associated with a system user then add the following configuration to config/config.exs:

  config :raygun,
      system_user: %{
                    identifier: "myuserid",
                    isAnonymous: true,
                    email: "myuserid@example.com",
                    fullName: "Jane Doe",
                    firstName: "Jane",
                    uuid: "b07eb66c-9055-4847-a173-881b77cdc83e"
              }

Any Elixir code

Start our Raygun application (if you did not configure it as an application in mix.exs)

Raygun.start

Send a string message to Raygun:

Raygun.report_message "Oh noes."

Report an exception programmatically. Be sure that System.stacktrace will be the correct stack trace!

try do
  :foo = :bar
rescue
  exception -> Raygun.report_exception(exception)
end

Or capture the stacktrace explicitly yourself and pass it to Raygun.

try do
  :foo = :bar
rescue
  exception ->
    stacktrace = System.stacktrace
    Raygun.report_stacktrace(stacktrace, exception)
end

Both forms allow some custom context to be passed as an optional final parameters as a Map. This will appear as 'userCustomData' under the custom tab in Raygun's web interface.

try do
  :foo = :bar
rescue
  exception ->
    Raygun.report_stacktrace(System.stacktrace, exception, %{env: Mix.env})
end

License

LICENSE

Cobenian / raygun

readme