collector

# 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.1.0"}
  ]
end
```

Give it your project's key (from its setup page in Collector), in
`config/runtime.exs`:

```elixir
config :collector, key: System.get_env("COLLECTOR_KEY")
```

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.

Without a key nothing is sent, so dev and test stay quiet.

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

## 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 | |
|---|---|---|
| `:key` | none | The project's key. Nothing is sent without it |
| `:endpoint` | `https://app.clt.chrom.ar` | Where Collector runs |
| `: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" |
| `: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.

The protocol is documented in Collector's `docs/protocol.md`, if you'd
like to report from another language.

## License

MIT. See [LICENSE](LICENSE).