Faulty

Error tracking for your application.

Installation

Add faulty to your mix.exs file, then mix deps.get it.

def deps do
  [
    {:faulty, "~> 0.2"}
  ]
end

or you can also use igniter to add/install Faulty.

mix igniter.install faulty`

Configuration

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

config :faulty,
    otp_app: :your_app,
    enabled: true,
    queue_size: 1000,
    scrub_pii: true,
    retry_interval: :timer.minutes(1),
    json_library: JSON,
    connect_options: [...]

The :otp_app option specifies your application, this allows FaultyTower to filter only your app's stack traces.

The :env option should be filled in with the name of the environment variable that contains the link to your FaultyTower instance, default is FAULTY_TOWER_URL.

The :enabled option if not given, will default to true. You probable want to turn this off for your test environment.

Errors are queued and sent one at a time, in the order they were reported, without blocking your application. If FaultyTower cannot be reached, or answers with a 408, 429 or 5xx status, the error stays at the head of the queue and is tried again after :retry_interval milliseconds, defaults to one minute. Any other response, such as a 422, means the error will never be accepted and it is dropped, so it can't hold up the errors queued behind it.

The :queue_size option limits how many errors wait to be sent, defaults to 1000. Once the queue is full new errors are dropped until there is room again, so an outage of FaultyTower can't make your application use more and more memory.

The :scrub_pii option, defaults to true, replaces the value of every sensitive key in the error context with "[FILTERED]" before it is sent. This covers request headers and params, Oban job args, LiveView event params and anything you add with Faulty.set_context/1. Keys such as password, token, secret, authorization, x-api-key and cookie are matched, ignoring case and separators, see Faulty.Scrubber for the full list. Only keys are checked, error messages are not touched. Set it to false to turn it off, your own Faulty.Filter runs afterwards either way.

The :json_library option is the module used to encode errors as JSON, defaults to the JSON module that is part of Elixir 1.18+. Any module that exports encode!/1 works, such as Jason. On Elixir 1.17 there is no JSON module, add {:jason, "~> 1.0"} to your dependencies and set json_library: Jason, mix faulty.install does this for you. Faulty checks the library when it starts. Values in the error context must be encodable by it.

Errors are sent with Erlang's built-in :httpc, so Faulty has no HTTP client dependency. The certificate of your FaultyTower is verified against your system's CA certificates.

The :connect_options tune the connection, these keys are supported:

• :transport_opts are :ssl options, merged over the secure defaults. For a FaultyTower with a self-signed certificate, for instance in development, use transport_opts: [verify: :verify_none], or trust your own CA with transport_opts: [cacertfile: "/path/to/ca.pem"].
• :timeout is the connect timeout in milliseconds, defaults to 30 seconds.
• :proxy is {:http, "proxy.example.com", 3128, []}, it is read when Faulty starts.

The :receive_timeout option limits how long a single request may take in milliseconds, defaults to 15 seconds.

Error tracking

Once configured Faulty is ready to start tracking your errors. It automatically starts with your application and tracks errors in your Phoenix controllers, LiveViews en Oban jobs. Checkout the Faulty.Integrations.Phoenix and Faulty.Integrations.Oban for more detailed information.

If your application uses Plug but not Phoenix, you will need to add the relevant integration in your Plug.Builder or Plug.Router module.

defmodule MyApp.Router do
  use Plug.Router
  use Faulty.Integrations.Plug

  # Your code here
end

This is also required if you want to track errors that happen in your Phoenix endpoint, before the Phoenix router starts handling the request. Keep in mind that this won't be needed in most cases as endpoint errors are infrequent.

defmodule MyApp.Endpoint do
  use Phoenix.Endpoint
  use Faulty.Integrations.Plug

  # Your code here
end

You can learn more about this in the Faulty.Integrations.Plug module documentation.

Error context

The default integrations include some additional context when tracking errors. You can take a look at the relevant integration modules to see what is being tracked out of the box.

In certain cases, you may want to include some additional information when tracking errors. For example it may be useful to track the user ID that was using the application when an error happened. Fortunately, Faulty allows you to enrich the default context with custom information.

The Faulty.set_context/1 function stores the given context in the current process so any errors that occur in that process (for example, a Phoenix request or an Oban job) will include this given context along with the default integration context.

There are some requirements on the type of data that can be included in the context, so we recommend taking a look at Faulty.set_context/1 documentation

Faulty.set_context(%{"user_id" =>  conn.assigns.current_user.id})

You may also want to sanitize or filter out some information from the context before saving it. To do that you can take a look at the Faulty.Filter behaviour.

Manual error tracking

If you want to report custom errors that fall outside the default integration scope, you may use Faulty.report/2. This allows you to report an exception yourself:

try do
  # your code
catch
  e ->
    Faulty.report(e, __STACKTRACE__)
end

You can also use Faulty.report/3 and set some custom context that will be included along with the reported error.

Ignoring errors

Faulty tracks every error by default. In certain cases some errors may be expected or just not interesting to track. Faulty provides functionality that allows you to ignore errors based on their attributes and context.

Take a look at the Faulty.Ignorer behaviour for more information about how to implement your own ignorer.

Faulty Tower

Faulty Tower is the accompanying website that hosts the error database.