You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This guide is an introduction to the ErrorTracker, an Elixir based built-in error tracking solution. The ErrorTracker provides a basic and free error-tracking solution integrated in your own application. It is designed to be easy to install and easy to use so you can integrate it in your existing project with minimal changes. The only requirement is a relational database in which errors will be tracked.
4
+
5
+
In this guide we will learn how to install the ErrorTracker in an Elixir project so you can start reporting errors as soon as possible. We will also cover more advanced topics such as how to report custom errors and how to add extra context to reported errors.
6
+
7
+
**This guide requires you to have setup Ecto with PostgreSQL beforehand.**
8
+
9
+
## Installing the ErrorTracking as a dependency
10
+
11
+
The first step add the ErrorTracker to your application is to declare the package as a dependency in your `mix.exs` file:
12
+
13
+
```elixir
14
+
# mix.exs
15
+
defpdepsdo
16
+
[
17
+
{:error_tracker, "~> 1.0"}
18
+
]
19
+
end
20
+
```
21
+
22
+
Once the ErrorTracker is declared as a dependency of your application, you can install it with the following command:
23
+
24
+
```bash
25
+
mix deps.get
26
+
```
27
+
28
+
## Configuring the ErrorTracker
29
+
30
+
The ErrorTracker needs a few configuration options to work. This configuration should be added in your `config/config.exs` file:
31
+
32
+
```elixir
33
+
config :error_tracker,
34
+
repo:MyApp.Repo,
35
+
otp_app::my_app
36
+
```
37
+
38
+
The `:repo` option specifies the repository that will be used by the ErrorTracker. You can use your regular application repository, or a different one if you prefer to keep errors in a different database.
39
+
40
+
The `:otp_app` option specifies your application name. When an error happens the ErrorTracker will use this information to understand which parts of the stacktrace belong to your application and which parts belong to third party dependencies. This allows you to filter in-app vs third-party frames when viewing errors.
41
+
42
+
## Setting up the database
43
+
44
+
Since the ErrorTracker stores errors in the database you must create a database migration to add the required tables:
45
+
46
+
```
47
+
mix ecto.gen.migration add_error_tracker
48
+
```
49
+
50
+
Open the generated migration and call the `up` and `down` functions on `ErrorTracker.Migration`:
51
+
52
+
```elixir
53
+
defmoduleMyApp.Repo.Migrations.AddErrorTrackerdo
54
+
useEcto.Migration
55
+
56
+
defup, do:ErrorTracker.Migration.up()
57
+
defdown, do:ErrorTracker.Migration.down()
58
+
end
59
+
```
60
+
61
+
You can run the migration and perform the database changes with the following command:
62
+
63
+
```bash
64
+
mix ecto.migrate
65
+
```
66
+
67
+
For more information about how to handle migrations take a look at the `ErrorTracker.Migration` module docs.
68
+
69
+
## Automatic error tracking
70
+
71
+
At this point, the ErrorTracker is ready to track errors. It will automatically start when your application boots and track errors that happen in your Phoenix controllers, Phoenix LiveViews and Oban jobs. The `ErrorTracker.Integrations.Phoenix` and `ErrorTracker.Integrations.Oban` provide detailed information about how this works.
72
+
73
+
If your application uses Plug but not Phoenix, you will need to add the relevant integration in your `Plug.Builder` or `Plug.Router` module.
74
+
75
+
```elixir
76
+
defmoduleMyApp.Routerdo
77
+
usePlug.Router
78
+
useErrorTracker.Integrations.Plug
79
+
80
+
# Your code here
81
+
end
82
+
```
83
+
84
+
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 very infrequent.
85
+
86
+
```elixir
87
+
defmoduleMyApp.Endpointdo
88
+
usePhoenix.Endpoint
89
+
useErrorTracker.Integrations.Plug
90
+
91
+
# Your code here
92
+
end
93
+
```
94
+
95
+
You can learn more about this in the `ErrorTracker.Integrations.Plug` module documentation.
96
+
97
+
## Error context
98
+
99
+
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.
100
+
101
+
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, the ErrorTracker allows you to enrich the default context with custom information.
102
+
103
+
The `ErrorTracker.set_context/1` function stores the given context in the current process so any errors that happen in that process (for example a Phoenix request or an Oban job) will include this given context along with the default integration context.
If you want to report custom errors that fall outside the default integrations scope you may use `ErrorTracker.report/2`. This allows you to report an exception by yourself:
112
+
113
+
```elixir
114
+
trydo
115
+
# your code
116
+
catch
117
+
e ->
118
+
ErrorTracker.report(e, __STACKTRACE__)
119
+
end
120
+
```
121
+
122
+
You can also use `ErrorTracker.report/3` and set some custom context that will be included along with the reported error.
123
+
124
+
## Web UI
125
+
126
+
The ErrorTracker also provides a dashboard built with Phoenix LiveView that can be used to see and manage the recorded errors.
127
+
128
+
This is completely optional and you can find more information about it in the `ErrorTracker.Web` module documentation.
0 commit comments