Collector
Reports your Elixir app's errors to Collector, which groups them into issues, emails you when one is new or comes back, and shows you what broke and why.
Installation
Add the dependency to mix.exs:
def deps do
[
{:collector, ">= 0.5.3"}
]
end
Give it your project's DSN (from its setup page in Collector) in the
COLLECTOR_DSN environment variable of the deployed app. 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
Oban is around (not the jobs that return {:cancel, _} or
{:discard, _}). Exceptions that Plug turns into a 4xx, like
Ecto.NoResultsError, aren't bugs and aren't reported.
It also sends a heartbeat when the app starts and every hour after, so Collector knows the app is up even when nothing breaks, and shows its release, environment and SDK version.
Without a DSN nothing is sent, so dev and test stay quiet: don't export
COLLECTOR_DSN there.
Checking the setup
Send a test event and see Collector's answer:
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())'
Request details and users
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 id:
Collector.set_user(current_user.id)
Source lines in releases
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.
Logs, requests and sign-ins
To let Collector catch attacks (login abuse, scanning, unusual volume), the app can also send what it logs, every request it serves and its sign-ins. That needs a server key, a secret made in the project's settings in Collector (not the DSN's key, which is public). 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 app 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):
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
]
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 app 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. See Collector.Logs for the details.
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" |
: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 as breadcrumbs |
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 app down. Failed sends are retried with the same id, so nothing is counted twice; when Collector asks to slow down, it does. Heartbeats share that queue, at most one waiting at a time. They have their own rate limit, so being slowed down on heartbeats never pauses errors, and they never log anything.
The protocol is documented in Collector's docs/protocol.md, if you'd
like to report from another language.
License
MIT. See LICENSE.