ErrorTracker Documentation

ErrorTracker is an Elixir-native, built-in error tracking solution designed to run as part of your application. It captures application errors, stores them in your database, and provides a web dashboard for inspecting and resolving them.

Key characteristics:

• Data Control: Since it runs within your application, you maintain full control over where and how error data is stored.
• Notification Strategy: ErrorTracker focuses strictly on tracking. It does not include built-in integrations for issue trackers or notifications; instead, it provides a Telemetry integration that allows you to attach your own handlers for sending notifications or opening tickets.

If you want to keep tracking error occurrences in the database and Web UI but avoid receiving notifications, you can mute them.

• Muted errors are still stored and visible in the Web UI.
• Telemetry events for muted errors include a muted: true flag.

You can mute and unmute errors manually via the Web UI or programmatically using:

• ErrorTracker.mute/1
• ErrorTracker.unmute/1

If certain errors are expected or uninteresting, you can prevent them from being stored in the database by implementing the ErrorTracker.Ignorer behaviour. When an error is ignored, its occurrences are not tracked at all.

defmodule MyApp.ErrorIgnores do
  @behaviour ErrorTracker.Ignorer

  @impl ErrorTracker.Ignorer
  def ignore?(%{kind: "Elixir.UnreliableThirdParty.Error", reason: ":timeout"} = _error, _context) do
    true
  end
end

If you have igniter available, you can automate the entire installation process (dependencies, configuration, and migrations) with a single command.

If Igniter is already available

Run:

mix igniter.install error_tracker

If Igniter is not yet available

Add error_tracker and igniter to your mix.exs dependencies, fetch them, and then run the ErrorTracker installer:

1. Update mix.exs:

{:error_tracker, "~> 0.9"},
{:igniter, "~> 0.5", only: [:dev]}

2. Run mix deps.get
3. Run mix error_tracker.install

To install ErrorTracker manually, follow these steps:

1. Add dependency: Add {:error_tracker, "~> 0.9"} to your mix.exs file.
2. Fetch dependencies: Run mix deps.get.
3. Configure: Add the required configuration to config/config.exs (see Configure ErrorTracker for details).
4. Setup Database: Create and run a migration to add ErrorTracker tables (see Setting up the database for details).

# mix.exs
defp deps do
  [
    {:error_tracker, "~> 0.9"}
  ]
end

The project includes a dev.exs script based on Phoenix Playground to facilitate starting a development environment.

iex dev.exs

ErrorTracker automatically tracks errors in Phoenix controllers, LiveViews, and Oban jobs.

If you are using Plug (without Phoenix) or want to track errors occurring in the Phoenix Endpoint before the router starts, you must manually add the ErrorTracker.Integrations.Plug integration.

For Plug Routers:

defmodule MyApp.Router do
  use Plug.Router
  use ErrorTracker.Integrations.Plug
end

For Phoenix Endpoints:

defmodule MyApp.Endpoint do
  use Phoenix.Endpoint
  use ErrorTracker.Integrations.Plug
end

If you are setting up the ErrorTracker project for the first time, you must generate the local configuration files from the provided examples and then fetch the project dependencies.

# Generate configuration files
cp config/dev.example.exs config/dev.exs
cp config/test.example.exs config/test.exs

# Download dependencies
mix deps.get

ErrorTracker requires specific tables in your database. Generate a new migration and use ErrorTracker.Migration to implement the up and down functions.

1. Generate migration:

mix ecto.gen.migration add_error_tracker

2. Implement the migration:

defmodule MyApp.Repo.Migrations.AddErrorTracker do
  use Ecto.Migration

  def up, do: ErrorTracker.Migration.up(version: 5)

  # We specify `version: 1` in `down`, to ensure we remove all migrations.
  def down, do: ErrorTracker.Migration.down(version: 1)
end

3. Run the migration:

mix ecto.migrate

mix ecto.gen.migration add_error_tracker
# ... edit file ...
mix ecto.migrate

The ErrorTracker Web UI relies on compiled JS and CSS. To build these assets, use the assets.install and assets.build tasks. If you modify CSS (which is managed by Tailwind), you should run the asset watcher in a separate terminal to automatically regenerate styles.

# Perform a clean build of JS and CSS
mix do assets.install, assets.build

# Run the watcher for CSS/Tailwind changes in a separate terminal
mix assets.watch

The ErrorTracker.Error module defines the data structure for a captured error or exception. It is designed to group similar errors using a fingerprint to prevent duplicates.

Fingerprinting Mechanism

A fingerprint is generated using a SHA256 hash of the following parameters:

• kind
• source_line (formatted as file:line or (nofile))
• source_function (formatted as Module.function/arity or -)

Note that the reason is not included in the fingerprint calculation. This allows errors with the same source and kind to be grouped together even if the specific error message (reason) varies slightly due to runtime conditions.

Error Statuses

Errors can be in one of two states:

• :unresolved (default)
• :resolved

The ErrorTracker.Integrations.Phoenix integration only catches errors that occur after a request has hit your Router.

Important Limitations:

• It will not report exceptions raised by plugs defined on your Endpoint.
• To capture errors occurring at the Endpoint level, you must also set up the ErrorTracker.Integrations.Plug integration.