# `ScoutApm.Error`

Public API for capturing errors in Scout APM.

Errors can be captured manually using `capture/1` or `capture/2`, or
automatically via Phoenix telemetry handlers.

## Manual Error Capture

    try do
      some_risky_operation()
    rescue
      e ->
        ScoutApm.Error.capture(e, stacktrace: __STACKTRACE__)
        reraise e, __STACKTRACE__
    end

## With Additional Context

    try do
      process_user_request(user)
    rescue
      e ->
        ScoutApm.Error.capture(e,
          stacktrace: __STACKTRACE__,
          context: %{user_id: user.id},
          request_path: "/api/users",
          request_params: %{action: "update"}
        )
        reraise e, __STACKTRACE__
    end

## Configuration

Error capture can be configured in your config:

    config :scout_apm,
      errors_enabled: true,
      errors_ignored_exceptions: [Phoenix.Router.NoRouteError],
      errors_filter_parameters: ["credit_card", "cvv"]

## Options

All capture functions accept these options:

  * `:stacktrace` - The exception stacktrace. For best results, pass `__STACKTRACE__`
    from within a rescue block.
  * `:context` - A map of additional context to include with the error.
  * `:request_path` - The request path (e.g., "/api/users").
  * `:request_params` - A map of request parameters.
  * `:session` - A map of session data.
  * `:custom_controller` - Override the controller name.
  * `:custom_params` - A map of custom parameters.

# `capture_opts`

```elixir
@type capture_opts() :: [
  stacktrace: Exception.stacktrace(),
  context: map(),
  request_path: String.t(),
  request_params: map(),
  session: map(),
  custom_controller: String.t(),
  custom_params: map()
]
```

# `capture`

```elixir
@spec capture(Exception.t(), capture_opts()) :: :ok
```

Captures an exception and sends it to Scout APM.

The stacktrace will be captured automatically if not provided, but for
best results, pass `__STACKTRACE__` from within a rescue block.

Returns `:ok` on success.

## Examples

    try do
      do_something_risky()
    rescue
      e ->
        ScoutApm.Error.capture(e, stacktrace: __STACKTRACE__)
        reraise e, __STACKTRACE__
    end

    # With additional context
    ScoutApm.Error.capture(exception,
      stacktrace: __STACKTRACE__,
      context: %{user_id: 123},
      request_path: conn.request_path
    )

# `capture_from_telemetry`

```elixir
@spec capture_from_telemetry(
  kind :: :error | :throw | :exit,
  reason :: term(),
  stacktrace :: Exception.stacktrace(),
  capture_opts()
) :: :ok
```

Captures an error from kind/reason/stacktrace tuple (as received in
telemetry exception events).

This is primarily used internally by telemetry handlers but can be called
directly when handling exceptions in catch blocks.

## Examples

    try do
      do_something()
    catch
      kind, reason ->
        ScoutApm.Error.capture_from_telemetry(kind, reason, __STACKTRACE__)
        :erlang.raise(kind, reason, __STACKTRACE__)
    end

# `enabled?`

```elixir
@spec enabled?() :: boolean()
```

Returns whether error capture is currently enabled.

---

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