Current section
Files
Jump to
Current section
Files
README.md
# Collector
Reports your Elixir app's errors to [Collector](https://app.clt.chrom.ar),
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`:
```elixir
def deps do
[
{:collector, ">= 0.5.2"}
]
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`:
```elixir
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:
```sh
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:
```sh
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):
```elixir
# lib/my_app_web/endpoint.ex
plug Collector.Plug
```
And say who hit the error, by id:
```elixir
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:
```sh
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:
```sh
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:
```elixir
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):
```elixir
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
```elixir
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](LICENSE).