The Raygun Elixir client adds Raygun-based error handling to your Elixir code. It catches all occuring errors, extracts as much information as possible and sends the error to Raygun where it is viewable in the Crash Reporting dashboard.

Installation

Step 1 - Add the Raygun dependency to mix.exs

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

You can run mix help deps to learn about dependencies.

Step 2 - Initialize the Elixir client

In your project's config/config.exs file, add the API Key -

import Config

config :raygun,
    api_key: "paste_your_api_key_here"

Step 3 - Install the dependencies

Run the mix deps.get command to install the dependencies.

Step 4 - Test your Raygun integration

Add a call to Raygun.report_message in your application.ex to raise a test exception.

Then run mix run --no-halt to run the app.

You can deploy Raygun into your production environment for the best and accurate results.

Additional configuraiton

You can add other optional 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: "paste_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 client_version should be auto detected for you.

Sending errors manually

Currently, the client supports 3 routes on how to use Raygun -

• With Plug in Phoenix
• Through the Logger
• With default Elixir code

It is recommended to not use all 3 if you'd like to not see multiple messages of the same error.

With Plug in Phoenix

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

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"
    }

Default Elixir implementation

Start the 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."

This will 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

You can also 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