Report failed Oban jobs to Bugsink
When an Oban job fails, Bugsink can show you the exception, the worker frame which raised it, and the job data needed to investigate the failure.
This guide adds the Elixir SDK’s built-in Oban integration to an existing application. You’ll enable automatic error capture and run one deliberately failing job to confirm that it reaches Bugsink.
To follow along, create a Bugsink project and copy its DSN. The quickstart guide shows where to find it. You need Oban 2.17.6 or newer; this guide was tested with Oban 2.24.2.
Install the SDK
Add the open-source Sentry Elixir SDK and its Finch HTTP client to your Mix dependencies. Bugsink accepts the Sentry event protocol, so the SDK can send job failures directly to your Bugsink project:
defp deps do [ # Your existing dependencies... {:finch, "~> 0.21"}, {:sentry, "~> 14.0"} ] enddefp deps do [ # Your existing dependencies... {:finch, "~> 0.21"}, {:sentry, "~> 14.0"} ] end
Start Sentry with your application and fetch the new dependencies:
def application do [ # Keep your existing application module and applications... extra_applications: [:logger, :sentry] ] end :::bash mix deps.getdef application do [ # Keep your existing application module and applications... extra_applications: [:logger, :sentry] ] end :::bash mix deps.get
Configure failed-job reporting
Set your Bugsink DSN and enable error capture under the SDK’s Oban integration.
capture_errors subscribes to Oban’s job exception telemetry, so your workers
do not need a Bugsink call or a rescue block:
config :sentry, dsn: System.get_env("SENTRY_DSN"), environment_name: "production", integrations: [oban: [capture_errors: true]]config :sentry, dsn: System.get_env("SENTRY_DSN"), environment_name: "production", integrations: [oban: [capture_errors: true]]
Set SENTRY_DSN to the DSN shown by your Bugsink project when you run your
application:
export SENTRY_DSN=https://key@bugsink.example/1export SENTRY_DSN=https://key@bugsink.example/1
Send a test error
Temporarily raise an exception in a worker you can enqueue. This inventory job raises its domain exception when the requested product does not exist:
defmodule InventoryOban.ProductNotFound do defexception [:message] end defmodule InventoryOban.InventoryReservationJob do use Oban.Worker, queue: :inventory, max_attempts: 1 alias InventoryOban.ProductNotFound @inventory %{"coffee" => 12, "tea" => 8} @impl Oban.Worker def perform(%Oban.Job{args: %{"order_id" => order_id, "sku" => sku}}) do unless Map.has_key?(@inventory, sku) do raise ProductNotFound, "Product #{sku} for #{order_id} is not in inventory" end :ok end enddefmodule InventoryOban.ProductNotFound do defexception [:message] end defmodule InventoryOban.InventoryReservationJob do use Oban.Worker, queue: :inventory, max_attempts: 1 alias InventoryOban.ProductNotFound @inventory %{"coffee" => 12, "tea" => 8} @impl Oban.Worker def perform(%Oban.Job{args: %{"order_id" => order_id, "sku" => sku}}) do unless Map.has_key?(@inventory, sku) do raise ProductNotFound, "Product #{sku} for #{order_id} is not in inventory" end :ok end end
Run your application and enqueue that worker through the same code path you normally use. For a one-off check, start an IEx session with your application and insert the job directly:
iex -S mix :::elixir %{"order_id" => "order-2401", "sku" => "oban-missing"} |> InventoryOban.InventoryReservationJob.new() |> Oban.insert!()iex -S mix :::elixir %{"order_id" => "order-2401", "sku" => "oban-missing"} |> InventoryOban.InventoryReservationJob.new() |> Oban.insert!()
See the failed job in Bugsink
Open your Bugsink project. The new InventoryOban.ProductNotFound issue points
to the worker’s perform/1 function. The event also contains the worker,
queue, attempt, and original order_id and sku arguments.
InventoryOban.ProductNotFound
That’s it: exceptions raised by Oban workers will now be reported to Bugsink. Remove the deliberate failure; the integration remains active for future job errors.
Tune failed-job reporting
The default setup reports each failed attempt. Applications with retries may want to report only the final attempt or promote their own job tags so issues are easier to filter.
Report only the final attempt
should_report_error_callback decides whether one failure should become an
event. This callback suppresses intermediate retries and reports the job only
after its last configured attempt fails:
config :sentry, integrations: [ oban: [ capture_errors: true, should_report_error_callback: fn _worker, job -> job.attempt >= job.max_attempts end ] ]config :sentry, integrations: [ oban: [ capture_errors: true, should_report_error_callback: fn _worker, job -> job.attempt >= job.max_attempts end ] ]
The SDK also reports workers which return {:error, reason}. Returning
{:discard, reason} or {:cancel, reason} is an intentional Oban outcome and
is not reported automatically.
Turn Oban job tags into event tags
oban_tags_to_sentry_tags maps your Oban job tags to searchable event tags.
The SDK already adds oban_worker, oban_queue, and oban_state; this example
also makes every application-defined job tag available for filtering:
config :sentry, integrations: [ oban: [ capture_errors: true, oban_tags_to_sentry_tags: fn job -> Map.new(job.tags, fn tag -> {"oban_tag.#{tag}", true} end) end ] ]config :sentry, integrations: [ oban: [ capture_errors: true, oban_tags_to_sentry_tags: fn job -> Map.new(job.tags, fn tag -> {"oban_tag.#{tag}", true} end) end ] ]
This guide covers failed-job error events. Oban’s separate cron check-ins are not stored as issues by Bugsink.
For handled exceptions, Logger messages, tags, context, breadcrumbs, releases, and shutdown behavior outside Oban, continue with the plain Elixir guide.
