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"}
  ]
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.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]]

Set SENTRY_DSN to the DSN shown by your Bugsink project when you run your application:

export 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
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!()

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.

Bugsink preview

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
    ]
  ]

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
    ]
  ]

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.