Current section

Files

Jump to
collector README.md
Raw

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.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`:

```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).