Oban v0.5.0 Oban.Telemetry View Source
Telemetry integration for event metrics, logging and error reporting.
Oban currently emits an event when a job has exeucted: [: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:
event | metadata |
---|---|
:success | :id, :args, :queue, :worker, :attempt, :max_attempt |
:failure | :id, :args, :queue, :worker, :attempt, :max_attempt, :kind, :error, :stack |
For :failure
events the metadata will include 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
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.warning("[#{meta.queue}] #{meta.worker} failed in #{duration}")
end
end
:telemetry.attach("oban-logger", [:oban, :failure], &ObanLogger.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}, 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)
Link to this section Summary
Functions
Attaches a default structured JSON Telemetry handler for logging.
Link to this section Functions
attach_default_logger()
View Source
(since 0.4.0)
attach_default_logger() :: :ok | {:error, :already_exists}
attach_default_logger() :: :ok | {:error, :already_exists}
Attaches a default structured JSON Telemetry handler for logging.
This function attaches a handler that outputs logs with the following fields:
source
— always "oban"event
— either:success
or:failure
dependening on whether the job succeeded or erroredargs
— a map of the job's raw argumentsworker
— the job's worker modulequeue
— the job's queueduration
— the job's runtime duration in microseconds
Examples
:ok = Oban.Telemetry.attach_default_logger()