# `Gust.DAG.Run.ErrorReporter`
[🔗](https://github.com/marciok/gust/blob/v0.1.40/lib/gust/dag/run/error_reporter.ex#L1)

Defines the contract for reporting terminal DAG task errors.

## Sentry example

With the `:sentry` package installed and configured, an adapter can report
task errors through `Sentry.capture_exception/2`:

    defmodule MyApp.SentryErrorReporter do
      @behaviour Gust.DAG.Run.ErrorReporter

      @impl true
      def capture(exception, stacktrace, metadata) do
        Sentry.capture_exception(exception, stacktrace: stacktrace, tags: metadata) 
        :ok
      end
    end

    config :gust,
      error_tracking: [reporter: MyApp.SentryErrorReporter]

## Custom Reporter example

Implement `capture/3` in an adapter module and configure it under the
`:error_tracking` application environment:

    defmodule MyApp.ErrorReporter do
      @behaviour Gust.DAG.Run.ErrorReporter

      @impl true
      def capture(exception, stacktrace, metadata) do
        response =
          Req.post!("https://errors.example.com/events",
            json: %{
              message: Exception.message(exception),
              stacktrace: Exception.format_stacktrace(stacktrace),
              metadata: metadata
            }
          )

        {:ok, response.body["url"]}
      end
    end

    config :gust,
      error_tracking: [reporter: MyApp.ErrorReporter]

`capture/3` runs asynchronously in `Gust.DAG.Run.ErrorReporter.Worker`.
Exceptions, exits, and throws from an adapter are logged and contained so
they cannot interrupt DAG execution. When it returns an external reference,
the worker adds that reference to the task's persisted error map.

# `capture_result`

```elixir
@type capture_result() :: :ok | {:ok, external_reference()}
```

The result of delivering an error to the configured reporter.

# `config`

```elixir
@type config() :: [{:reporter, reporter()}]
```

Worker configuration containing an optional reporter implementation.

# `exception`

```elixir
@type exception() :: Exception.t()
```

An exception describing the failed task execution.

# `external_reference`

```elixir
@type external_reference() :: String.t()
```

An absolute HTTP(S) URL for the error in the external reporting service.

# `metadata`

```elixir
@type metadata() :: %{
  task_id: integer(),
  task_name: String.t(),
  run_id: integer(),
  dag_name: String.t()
}
```

Context identifying the task and DAG run that failed.

# `reporter`

```elixir
@type reporter() :: module()
```

A module implementing this behaviour.

# `stacktrace`

```elixir
@type stacktrace() :: Exception.stacktrace()
```

The original task exception stacktrace, or an empty list when unavailable.

# `capture`

```elixir
@callback capture(exception(), stacktrace(), metadata()) :: capture_result()
```

Delivers a task exception and its execution context to an error provider.

Implementations may return `:ok` or `{:ok, external_url}` when the
provider exposes an HTTP(S) page for the captured error. They may raise,
exit, or throw when delivery fails; the error reporter worker contains and
logs those failures.

---

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