Exception handling

In most applications some errors will get raised that aren’t related to possible bugs in your code, they just happen when your app gets into contact with the real world. Bots might drop by and try to automatically post forms, outdated links might direct visitors to content that doesn’t exist anymore and so on. To avoid these errors from being raised as problems in AppSignal it’s possible to add exception handling to your code or even let AppSignal completely ignore certain errors.

Ignore errors

The AppSignal configuration makes it possible to ignore errors. By providing a list of specific errors AppSignal will not send alerts when these errors are raised.

Appsignal.set_error/3

If you want to rescue exceptions in your application to prevent crashes, but still want to track the occurrence you can use Appsignal.set_error/2 to add the exception to the current AppSignal transaction:

try do
  raise "Exception!"
rescue
  exception -> Appsignal.set_error(exception, __STACKTRACE__)
end

Erlang

The AppSignal integration tries its best to convert errors raised from Erlang to Elixir exceptions. For example, a :badarg raised from Erlang is automatically converted to an ArgumentError. However, sometimes the best it can do is wrapping the error originating from Erlang in an ErlangError. Since these don’t give much insight into the underlying issue, we recommend adding information from within your application by catching the error, creating an Elixir exception yourself and adding that to the current span using the set_error/2 function.

NOTE: Appsignal.set_error/2 was added in AppSignal for Elixir 2.1.0. If you’re on a lower version, use Appsignal.set_error/3 instead.

On versions before 2.1.0, use catch and Appsignal.send_error/3:

try do
  raise "Exception!"
catch
  kind, reason ->
    Appsignal.set_error(kind, reason, __STACKTRACE__)
end

The exception will be tracked by AppSignal like any other error, and it allows you to provide custom error handling and fallbacks. If you do not have an error object when calling send_error, but still want to report the scenario as an error, it’s also possible to initialize a custom error struct.

defmodule MyCustomError do
  defexception message: "default message" # Customize if you call it without a custom message
end

case Worker.do_something() do
  :ok -> IO.puts "yay!"
  {:error, message} ->
    Appsignal.set_error(:error, %MyCustomError{ message: message }, [])
end

Note: This function only works when there is an AppSignal transaction active. Otherwise the error will be ignored. Please see Appsignal.send_error/3 for sending errors without an AppSignal transaction.

Appsignal.send_error/3

AppSignal provides a mechanism to track errors that occur in code that’s not in a web or background job context, such as Mix tasks. This is useful for instrumentation that doesn’t automatically create AppSignal transactions to profile. You can use the Appsignal.send_error/3 function to directly send an exception to AppSignal from any place in your code without starting an AppSignal transaction first.

try do
  raise "Exception!"
catch
  kind, reason ->
    Appsignal.send_error(kind, reason, __STACKTRACE__)
end

If you do not have an error object when calling send_error, but still want to report the scenario as an error, it’s also possible to initialize a custom error struct.

defmodule MyCustomError do
  defexception message: "default message" # Customize if you call it without a custom message
end

case Worker.do_something() do
  :ok -> IO.puts "yay!"
  {:error, message} ->
    Appsignal.send_error(:error, %MyCustomError{ message: message }, [])
end

Additional metadata

To add metadata to the sent error, pass a function as the fourth argument to Appsignal.send_errror/4:

try do
  raise "Exception!"
catch
  kind, reason ->
    Appsignal.send_error(kind, reason, __STACKTRACE__, fn span ->
      Appsignal.Span.set_attribute(span, "key", "value")
    end)
end

NOTE: Appsignal.send_error/4 was added in AppSignal for Elixir 2.1.0.

Function arguments in backtraces

Some lines in an Elixir backtrace include the arguments a function was called with, and those arguments can contain personal data or secrets. AppSignal for Elixir replaces argument values with placeholders before it reports an error. It keeps atoms and the shape of maps, tuples, and keyword lists, so you can still tell which function clause was called. You can’t turn this off. For example, this code raises a KeyError:

article_attributes = %{title: "Getting started with Phoenix LiveView", header: "liveview-header.png"}
Map.fetch!(article_attributes, :author)

The backtrace Elixir prints includes the map’s values:

:erlang.map_get(:author, %{header: "liveview-header.png", title: "Getting started with Phoenix LiveView"})

AppSignal reports the same backtrace line with placeholders:

:erlang.map_get(:author, %{header: "...", title: "..."})

Only backtrace lines are cleaned. AppSignal for Elixir reports the error message as the exception formats it, so the message of the KeyError above still contains the map’s values.

Common values are reported like this:

Value in your code	Value in AppSignal
`:author`, `true`, `nil`	Unchanged
`"jane@example.com"`	`"..."`
`42`, `1.5`	`integer()`, `float()`
`%{id: 42, name: "Jane"}`	`%{id: integer(), name: "..."}`
`%{"email" => "jane@example.com"}`	`%{"..." => "..."}`
`%MyApp.User{name: "Jane"}`	`%MyApp.User{...}`
`{:ok, "token"}`	`{:ok, "..."}`
`[timeout: 5000, mode: "fast"]`	`[timeout: integer(), mode: "..."]`
`[1, 2, 3]`	`[...]`

Other values, such as PIDs and anonymous functions, are also replaced with placeholders, like #PID<...>. Maps, tuples, and keyword lists with more than four items, and maps and tuples nested more than two levels deep, are collapsed to %{...}, {...}, and [...].

SDKs & telemetry

Language SDKs

Telemetry tools

Ignore errors

Appsignal.set_error/3

Erlang

Appsignal.send_error/3

Additional metadata

Function arguments in backtraces

​Ignore errors

​Appsignal.set_error/3

​Erlang

​Appsignal.send_error/3

​Additional metadata

​Function arguments in backtraces

Ignore errors

Appsignal.set_error/3

Erlang

Appsignal.send_error/3

Additional metadata

Function arguments in backtraces