# `Boop.Event`
[🔗](https://github.com/chrisgreg/boop_ex/blob/v1.0.0/lib/boop/event.ex#L1)

An event to send to Boop. Only `title` is required.

| Field | Notes |
| --- | --- |
| `title` | required, truncated to 200 characters |
| `body` | truncated to 4000 characters |
| `level` | `:info` (default), `:success`, `:warning`, `:error`, `:critical` |
| `source` | what produced it, e.g. `"cron"`; defaults to the configured `source` |
| `type` | a category within the source, e.g. `"deploy"` |
| `external_id` | your own id for the event |
| `fingerprint` | a stable grouping key |
| `occurred_at` | `DateTime`, `NaiveDateTime` (assumed UTC) or ISO 8601 string; defaults to now |
| `data` | a map of anything JSON-serialisable; sensitive keys are redacted before sending |

The keys `exception`, `stacktrace`, `tags`, `context` and `breadcrumbs` inside `data`
get a rich rendering in Boop. See `Boop.Event.exception/3` for a helper.

# `level`

```elixir
@type level() :: :info | :success | :warning | :error | :critical
```

# `t`

```elixir
@type t() :: %Boop.Event{
  body: String.t() | nil,
  data: map(),
  external_id: String.t() | nil,
  fingerprint: String.t() | nil,
  level: level(),
  occurred_at: DateTime.t() | nil,
  source: String.t() | nil,
  title: String.t() | nil,
  type: String.t() | nil
}
```

# `exception`

```elixir
@spec exception(Exception.t(), Exception.stacktrace(), keyword()) :: map()
```

Builds `data` for an error event from an exception and stacktrace, in the shape Boop renders richly.

    rescue e -> Boop.send(title: inspect(e.__struct__), level: :error,
                          data: Boop.Event.exception(e, __STACKTRACE__, tags: %{env: "prod"}))

# `levels`

```elixir
@spec levels() :: [level()]
```

The valid levels, in ascending severity.

# `new`

```elixir
@spec new(String.t() | keyword() | map() | t(), Boop.Config.t() | keyword()) ::
  {:ok, t()} | {:error, Boop.Error.t()}
```

Builds and validates an event from a title, keyword list, map, or `%Boop.Event{}`.

Strings that exceed their limits are truncated rather than rejected. Returns
`{:error, %Boop.Error{code: :invalid}}` when the title is missing or the level is unknown.

# `to_payload`

```elixir
@spec to_payload(t(), Boop.Config.t() | keyword()) :: map()
```

Converts an event to the JSON-ready map the server expects, redacting sensitive keys in
`data` and dropping `data` (with a note in `body`) if it is still over 256 KB.

---

*Consult [api-reference.md](api-reference.md) for complete listing*