Specs

start_link([option()]) :: Supervisor.on_start()

Starts an Oban supervision tree linked to the current process.

Options

These options are required; without them the supervisor won't start

• :name — used for supervisor registration, defaults to Oban
• :repo — specifies the Ecto repo used to insert and retrieve jobs

Primary Options

These options determine what the system does at a high level, i.e. which queues to run.

• :node — used to identify the node that the supervision tree is running in. If no value is provided it will use the node name in a distributed system, or the hostname in an isolated node. See "Node Name" below.

• :plugins — a list or modules or module/option tuples that are started as children of an Oban supervisor. Any supervisable module is a valid plugin, i.e. a GenServer or an Agent.

• :prefix — the query prefix, or schema, to use for inserting and executing jobs. An oban_jobs table must exist within the prefix. See the "Prefix Support" section in the module documentation for more details.

• :queues — a keyword list where the keys are queue names and the values are the concurrency setting or a keyword list of queue options. For example, setting queues to [default: 10, exports: 5] would start the queues default and exports with a combined concurrency level of 15. The concurrency setting specifies how many jobs each queue will run concurrently.

  Queues accept additional override options to customize their behavior, e.g. by setting paused or dispatch_cooldown for a specific queue. For testing purposes :queues may be set to false or nil, which effectively disables all job dispatching.

• :log — either false to disable logging or a standard log level (:error, :warn, :info, :debug). This determines whether queries are logged or not; overriding the repo's configured log level. Defaults to false, where no queries are logged.

Twiddly Options

Additional options used to tune system behaviour. These are primarily useful for testing or troubleshooting and don't usually need modification.

• :circuit_backoff — the number of milliseconds until queries are attempted after a database error. All processes communicating with the database are equipped with circuit breakers and will use this for the backoff. Defaults to 30_000ms.

• :dispatch_cooldown — the minimum number of milliseconds a producer will wait before fetching and running more jobs. A slight cooldown period prevents a producer from flooding with messages and thrashing the database. The cooldown period directly impacts a producer's throughput: jobs per second for a single queue is calculated by (1000 / cooldown) * limit. For example, with a 5ms cooldown and a queue limit of 25 a single queue can run 2,500 jobs/sec.

  The default is 5ms and the minimum is 1ms, which is likely faster than the database can return new jobs to run.

• :shutdown_grace_period - the amount of time a queue will wait for executing jobs to complete before hard shutdown, specified in milliseconds. The default is 15_000, or 15 seconds.

Example

To start an Oban supervisor within an application's supervision tree:

def start(_type, _args) do
  children = [MyApp.Repo, {Oban, queues: [default: 50]}]

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

Node Name

When the node value hasn't been configured it is generated based on the environment:

• In a distributed system the node name is used
• In a Heroku environment the system environment's DYNO value is used
• Otherwise, the system hostname is used