Oban.Web.Telemetry (Oban Web v2.10.4)

Oban Web uses Telemetry to provide instrumentation and to power logging of dashboard activity.

Action Events

An action event is emitted whenever a user performs a write operation with the dashboard, e.g. pausing a queue, cancelling a job, etc.

The dashboard emits the following events:

[:oban_web, :action, :start]
[:oban_web, :action, :stop]
[:oban_web, :action, :exception]

Action events include the action name, Oban config, the user that performed the action (if available), and relevant metadata. In addition, failed actions provide the error type, the error itself, and the stacktrace.

The following chart shows the base metadata for each event:

event	measures	metadata
`:start`	`:system_time`	`:action, :config, :user`
`:stop`	`:duration`	`:action, :config, :user`
`:exception`	`:duration`	`:action, :config, :user, :kind, :error, :stacktrace`

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

This chart breaks down the possible actions and their specific metadata:

action	metadata
`:mount`
`:pause_queue`	`:queue`
`:resume_queue`	`:queue`
`:pause_all_queues`
`:resume_all_queues`
`:scale_queue`	`:queue`, `:limit`
`:cancel_jobs`	`:job_ids`
`:delete_jobs`	`:job_ids`
`:retry_jobs`	`:job_ids`

Action Logging

The Oban.Web.Telemetry module ships with a default handler that logs structured JSON for :stop and :exception events. To attach the logger, call attach_default_logger/1 as your application starts:

def start(_type, _args) do
  children = [
    MyApp.Repo,
    MyApp.Endpoint,
    {Oban, oban_opts()}
  ]

  Oban.Telemetry.attach_default_logger(:info)
  Oban.Web.Telemetry.attach_default_logger(:info)

  Supervisor.start_link(children, [strategy: :one_for_one, name: MyApp.Supervisor])
end

Summary

Functions

attach_default_logger(opts \\ [encode: true, level: :info])

Attaches a structured telemetry handler for logging.

Functions

attach_default_logger(opts \\ [encode: true, level: :info])

Attaches a structured telemetry handler for logging.

Options

:level — The log level to use for logging output, defaults to :info
:encode — Whether to encode log output as JSON, defaults to true

Events

Here is an example of the JSON output for an action:stop event:

{
  "action":"cancel_jobs",
  "duration":2544,
  "event":"action:stop",
  "job_ids":[290950],
  "oban_name":"Oban",
  "source":"oban_web",
  "user":1818
}

Event metadata is passed through directly along with these constant fields:

action — The reported action, e.g. cancel_jobs
duration — Action duration, recorded in native units and logged as microseconds
source — Always "oban_web", which is useful for log filtering
user — If the dashboard was mounted with an Oban.Web.Resolver that implements resolve_user/1 this is the user's id, otherwise null
oban_name — The instance that the dashboard is linked to, typically this is "Oban" unless an application is using multiple Oban instances.

Examples

Attach the logger at the :debug log level:

Oban.Web.Telemetry.attach_default_logger(level: :debug)

Disable JSON encoding output:

Oban.Web.Telemetry.attach_default_logger(encode: false)