Gust.DAG.Run.ErrorReporter behaviour (gust v0.1.40)

Copy Markdown View Source

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.

Summary

Types

capture_result()

The result of delivering an error to the configured reporter.

config()

Worker configuration containing an optional reporter implementation.

exception()

An exception describing the failed task execution.

external_reference()

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

metadata()

Context identifying the task and DAG run that failed.

reporter()

A module implementing this behaviour.

stacktrace()

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

Callbacks

capture(exception, stacktrace, metadata)

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

Types

capture_result()

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

The result of delivering an error to the configured reporter.

config()

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

Worker configuration containing an optional reporter implementation.

exception()

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

An exception describing the failed task execution.

external_reference()

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

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

metadata()

@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()

@type reporter() :: module()

A module implementing this behaviour.

stacktrace()

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

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

Callbacks

capture(exception, stacktrace, metadata)

@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.