Elixir
The collector package reports your Elixir or Phoenix application's errors. This page describes version 0.5.4.
Installation
Add the dependency to mix.exs:
def deps do
[
{:collector, ">= 0.5.4"}
]
end
Give the deployed application the project's DSN (it's on its Setup) in the COLLECTOR_DSN environment variable. Or, to take it from somewhere else, in config/runtime.exs:
config :collector, dsn: System.get_env("MY_COLLECTOR_DSN")
That's it. From now on, crashes are reported on their own: controllers, LiveViews, GenServers, Tasks, any process. Oban job failures too, when the application uses Oban (not the jobs that return {:cancel, _} or {:discard, _}). Exceptions that Plug turns into a 4xx, like Ecto.NoResultsError, aren't bugs in your code and aren't reported. A crash that comes through the log carries that line as its message, and its plain metadata and domain as tags.
It also sends a signal when it starts and every hour, so Collector knows the application is up even when nothing breaks, with its release, its environment and the SDK's version.
Without a DSN nothing is sent, so dev and test stay quiet: don't export COLLECTOR_DSN there.
Checking it works
MIX_ENV=prod mix collector.test
It prints the event's id when Collector accepted it, or what went wrong (no DSN, a refused key, Collector unreachable), and exits with 1 then. In a release, where mix tasks aren't available:
bin/my_app rpc 'IO.inspect(Collector.test_event())'
The request and the user
Add the plug to your endpoint to see the request each error happened in. Credentials, such as cookies, are never sent:
# lib/my_app_web/endpoint.ex
plug Collector.Plug
And say who hit the error, by their id, never their email:
Collector.set_user(current_user.id)
Do it in the plug where you read the session and in your LiveViews' on_mount, since each LiveView is its own process.
Source lines in a release
Collector shows the lines around each frame of your code. Releases don't ship source files, so package them right before building the release:
MIX_ENV=prod mix collector.package_source
MIX_ENV=prod mix release
In a Dockerfile, that's one line before mix release.
Your dependencies' frames show as deps/<package>/…, with no code around them: only your application's sources are packaged.
Logs, requests and sign-ins
To let Collector catch attacks (sign-in abuse, scanning, unusual volume), the application can also send what it logs, every request it serves and its sign-ins. That needs a server key, a secret separate from the DSN. Set it next to the DSN:
COLLECTOR_SERVER_KEY=clts_…
With it, without any other change, Collector gets:
- log lines at
:infoand above, with their metadata's plain values (a conn, a struct or a map is left out, since it can carry cookies). Phoenix's own "GET /x" and "Sent 200" lines are left out too: each request is already a record; - one record per request a Phoenix endpoint serves, the ones that raise or match no route included (in a Plug app without Phoenix, add
plug Collector.Plug); - sign-ins, once you report them:
Collector.sign_in(:failed, email, conn: conn, method: :password)
Collector.sign_in(:succeeded, email, conn: conn, method: :password, user: user.id)
In an application made with mix phx.gen.auth, call Collector.PhxGenAuth.sign_in(conn, user_params, user_or_nil) in both branches of UserSessionController.create; its docs show where.
Behind a load balancer, list its networks so the client's address is read from X-Forwarded-For (which is believed only from them). Catching attacks depends on it:
config :collector,
logs: [
trusted_proxies: ["10.0.0.0/8"],
skip_paths: ["/health"], # exact, or a prefix as "/up/*"
level: :info, # the lowest level sent
lines: true, # false: no log lines
requests: true, # false: no requests
sign_ins: true # false: no sign-ins
]
An error raised while serving a request carries its id (the one from Plug.RequestId), the same as its records, so the issue links to them.
logs: false switches it all off. Path segments for route params named like token, password or secret are sent as their name, so a sign-in link isn't stored. Collector keeps what's sent for a year, as sent: what the application logs is its responsibility. Records go in batches every second, in the background; when a release stops, what's left is sent, waiting up to 5 seconds.
Reporting by hand
try do
charge!(order)
rescue
e ->
Collector.capture_exception(e, stacktrace: __STACKTRACE__)
{:error, :payment_failed}
end
Collector.capture_message("Payment gateway slow", level: :warning)
Options
| Option | Default | |
|---|---|---|
:dsn | COLLECTOR_DSN | https://clt_…@app.clt.chrom.ar: where Collector runs plus the project's key. Nothing is sent without it. |
:key, :endpoint | COLLECTOR_KEY, https://app.clt.chrom.ar | The DSN's two halves, set apart. A DSN wins over both. |
:environment | The Mix env the app was built in | prod, staging, … |
:release | RELEASE_VSN | Version or git sha. |
:in_app | Your app's own applications | Which applications count as "your code". It decides how errors group. |
:server_key | COLLECTOR_SERVER_KEY | The secret key logs are sent with. Setting it turns logs on. |
:logs | see above | Tunes logs, or false to switch them off. |
:repos | none | Ecto repo telemetry prefixes, e.g. [[:my_app, :repo]], to record queries in what happened before the error, with their duration and how long they waited for a connection. |
How it behaves
Events are sent in the background, one at a time, from a bounded queue (the oldest is dropped past 1000), so a slow or unreachable Collector never slows your application down. Failed sends are retried with the same id, so nothing is counted twice; when Collector asks to slow down, it does. Signals share that queue, at most one waiting at a time, and have their own limit: being slowed down on signals never slows errors.