sidekiq-throttled

When a job is throttled, it must be requeued. You can choose between two strategies:

1. :enqueue (Default): Puts jobs immediately back on the queue. This can cause high Redis CPU usage if many jobs are constantly being dequeued and re-enqueued.
2. :schedule: Schedules the work for the future. This reduces Redis load by delaying the check until the job is likely to be runnable.

Global Configuration

You can set a default strategy globally:

Sidekiq::Throttled.configure do |config|
  config.default_requeue_options = { with: :schedule }
end

Per-job Configuration

You can specify the strategy and even a target queue for a specific job:

# Using :schedule strategy
sidekiq_throttle(
  threshold: { limit: 5, period: 1.minute, requeue: { with: :schedule } }
)

# Using :schedule strategy and moving to a different queue
sidekiq_throttle(
  threshold: { limit: 5, period: 1.minute, requeue: { to: :other_queue, with: :schedule } }
)

You can apply different throttle limits based on job arguments using the :key_suffix option. This allows for per-user or per-resource throttling.

Per-argument key suffix

Pass a proc to :key_suffix that receives the job arguments and returns a unique identifier for the throttle bucket.

sidekiq_throttle(
  concurrency: { limit: 10, key_suffix: -> (user_id) { user_id } }
)

Dynamic limits and periods

You can also pass procs to limit and period to change the throttling constraints dynamically based on job arguments.

sidekiq_throttle(
  concurrency: {
    limit:      ->(user_id) { User.vip?(user_id) ? 1_000 : 10 },
    key_suffix: ->(user_id) { User.vip?(user_id) ? "vip" : "std" }
  }
)

Multiple throttling keys

You can pass an array of hashes to concurrency or threshold to apply multiple independent throttling rules to a single worker.

sidekiq_throttle(
  concurrency: [
    { limit: 10, key_suffix: -> (project_id, user_id) { "project_id:#{project_id}" } },
    { limit: 2, key_suffix: -> (project_id, user_id) { "user_id:#{user_id}" } }
  ]
)

IMPORTANT: If you use dynamic limit or period values, you must also specify a :key_suffix that returns different values for different groups (e.g., 'vip' vs 'std'), otherwise they will all share the same throttle bucket.

If you want multiple different worker classes to share the same throttling pool (e.g., to respect a single global API rate limit), use sidekiq_throttle_as.

First, register a named strategy using Sidekiq::Throttled::Registry.add. Then, in your worker classes, call sidekiq_throttle_as with that name. This ensures that the sum of all jobs using that strategy does not exceed the defined limits.

Example: If a strategy allows 10 concurrent jobs and you have two workers using it, the total number of concurrent jobs across both workers will not exceed 10.

# 1. Create a shared strategy in the registry
Sidekiq::Throttled::Registry.add(:google_api, {
  :threshold => { :limit => 123, :period => 1.hour },
  :concurrency => { :limit => 10 }
})

# 2. Assign workers to that shared strategy
class FetchProfileJob
  include Sidekiq::Job
  include Sidekiq::Throttled::Job
  sidekiq_throttle_as :google_api
end

class FetchCommentsJob
  include Sidekiq::Job
  include Sidekiq::Throttled::Job
  sidekiq_throttle_as :google_api
end

A Strategy in sidekiq-throttled is a meta-strategy that can combine Concurrency (limiting simultaneous jobs) and Threshold (limiting jobs within a time window) constraints.

When a job is identified as throttled?, the requeue_throttled method is invoked. The behavior depends on the :with option:

1. :enqueue: Uses re_enqueue_throttled. For standard Sidekiq, this performs an LPUSH to the target queue. If using Sidekiq::Pro::SuperFetch, it uses the UnitOfWork to requeue the job to the head of the target queue.
2. :schedule: Uses reschedule_throttled. This treats the job as a new unit of work by calling Sidekiq::Client.enqueue_to_in. It calculates a retry_in interval by taking the maximum of the intervals suggested by the active concurrency and threshold strategies, then adding a random jitter (up to 20% of the interval if the interval is > 10 seconds).