Telemetry integration for event metrics, logging and error reporting.

Job Events

Oban emits an event after a job executes: [:oban, :success] if the job succeeded or [:oban, :failure] if there was an error or the process crashed.

All job events share the same details about the job that was executed. In addition, failed jobs provide the error type, the error itself, and the stacktrace. The following chart shows which metadata you can expect for each event:

For :failure events the metadata includes details about what caused the failure. The :kind value is determined by how an error occurred. Here are the possible kinds:

• :error — from an {:error, error} return value. Some Erlang functions may also throw an :error tuple, which will be reported as :error.
• :exception — from a rescued exception
• :exit — from a caught process exit
• :throw — from a caught value, this doesn't necessarily mean that an error occurred and the error value is unpredictable

Circuit Events

All processes that interact with the database have circuit breakers to prevent errors from crashing the entire supervision tree. Processes emit a [:oban, :trip_circuit] event when a circuit is tripped and [:oban, :open_circuit] when the breaker is subsequently opened again.

Metadata

• :name — the registered name of the process that tripped a circuit, i.e. Oban.Notifier
• :message — a formatted error message describing what went wrong

Default Logger

A default log handler that emits structured JSON is provided, see attach_default_logger/0 for usage. Otherwise, if you would prefer more control over logging or would like to instrument events you can write your own handler.

Examples

A handler that only logs a few details about failed jobs:

defmodule MicroLogger do
  require Logger

  def handle_event([:oban, :failure], %{duration: duration}, meta, nil) do
    Logger.warn("[#{meta.queue}] #{meta.worker} failed in #{duration}")
  end
end

:telemetry.attach("oban-logger", [:oban, :failure], &MicroLogger.handle_event/4, nil)

Another great use of execution data is error reporting. Here is an example of integrating with Honeybadger, but only reporting jobs that have failed 3 times or more:

defmodule ErrorReporter do
  def handle_event([:oban, :failure], _timing, %{attempt: attempt} = meta, nil) do
    if attempt >= 3 do
      context = Map.take(meta, [:id, :args, :queue, :worker])

      Honeybadger.notify(meta.error, context, meta.stack)
    end
  end
end

:telemetry.attach("oban-errors", [:oban, :failure], &ErrorReporter.handle_event/4, nil)