README

ObanDoctor

Static analysis and runtime monitoring for Oban. Catches misconfigurations at CI time and provides runtime queue metrics for capacity planning. Based on lessons learnt over many years of happily using Oban.

Installation

Add oban_doctor to your list of dependencies in mix.exs:

def deps do
  [
    {:oban_doctor, "~> 0.2"}
  ]
end

For static analysis only (checks without runtime plugins):

{:oban_doctor, "~> 0.2", only: [:dev, :test], runtime: false}

Usage

Run all checks:

mix oban_doctor

Or run specific check types:

mix oban_doctor.check_workers  # Worker checks only
mix oban_doctor.check_config   # Config checks only

Options:

--format=json - Output as JSON (for CI integration)
--strict - Treat warnings as errors (exit code 1)
--verbose - Show detailed output

Checks

Worker Checks

Check	Description
MissingQueue	Detects workers using queues not defined in Oban configuration
StateGroupUsage	Detects workers using the dangerous `:all` state group
UniquenessMissingStates	Detects unique configs missing recommended states like `:retryable`
UniqueWithoutKeys	Detects unique constraints on `:args` without explicit `keys`
NoMaxAttempts	Detects workers using the default `max_attempts` of 20

Config Checks

Check	Description
InsertTriggerEnabled	Detects Oban instances without `insert_trigger: false` (performance overhead)
MissingPruner	Detects Oban instances without a pruner plugin (jobs accumulate indefinitely)
NoReindexer	Detects Oban instances without the Reindexer plugin (index bloat)

Runtime Plugins

ObanDoctor provides runtime plugins for monitoring queue health and capacity. See the Plugins Guide for usage details.

Plugin	Description
QueueMetrics	Live queue metrics including utilization percentages
TableHealth	Table size, bloat, and vacuum monitoring with alerts

Configuration

Create a .oban_doctor.exs file in your project root to customize behavior:

mix oban_doctor.gen.config

Example:

[
  checks: [
    # Disable a check entirely
    unique_without_keys: [enabled: false],

    # Override severity
    no_max_attempts: [severity: :info],

    # Exclude specific workers from a worker check
    missing_queue: [
      excluded_workers: [MyApp.Workers.LegacyWorker]
    ],

    # Exclude specific Oban instances from a config check
    missing_pruner: [
      excluded_instances: [MyApp.SecondaryOban]
    ]
  ],

  # Exclude workers from ALL worker checks
  excluded_workers: [MyApp.Workers.DeprecatedWorker],

  # Exclude files from ALL checks
  excluded_files: ["test/support/"]
]

See the Configuration Guide for full documentation.

CI Integration

Add to your CI pipeline:

mix oban_doctor --strict

For JSON output (useful for custom reporting):

mix oban_doctor --format=json

Exit codes:

0 - No errors (warnings are allowed unless --strict)
1 - Errors found (or warnings with --strict)

License

Apache 2.0

Next Page → Configuration