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.4"}
  ]
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:

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.