Skip to main content

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 :info and 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​

OptionDefault
:dsnCOLLECTOR_DSNhttps://clt_…@app.clt.chrom.ar: where Collector runs plus the project's key. Nothing is sent without it.
:key, :endpointCOLLECTOR_KEY, https://app.clt.chrom.arThe DSN's two halves, set apart. A DSN wins over both.
:environmentThe Mix env the app was built inprod, staging, …
:releaseRELEASE_VSNVersion or git sha.
:in_appYour app's own applicationsWhich applications count as "your code". It decides how errors group.
:server_keyCOLLECTOR_SERVER_KEYThe secret key logs are sent with. Setting it turns logs on.
:logssee aboveTunes logs, or false to switch them off.
:reposnoneEcto 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.