sidekiq-throttled 1.5.2 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07f60ab84ab53725f6189d8a142ccb7d5596ea408a5d52087e2665420c92a276
-  data.tar.gz: 489d3d9a5a72dc20af8295d6942d4abdc9a27dfffdf917b753a08af78184d59e
+  metadata.gz: dcec267e317bfaeabe891a21b776cbddc083cba27a163c82a5e5e0839390fb8d
+  data.tar.gz: '09706d9f91fdc770f01a5fb7835d8c35706c2852dfe798ec3e60dcd76bdeb8e9'
 SHA512:
-  metadata.gz: bac5ad071e0de8913f80f8c78cec87ee98c61da77a48c46000ba3680f0eeb684b2970c69d256b61cf5d1b680121f2762a0ae3c9220729ee25140ba6cbf3f9598
-  data.tar.gz: 92d08e2c0f76716816385b24df2c06092fa416ceb22714657967e2e312fe04357000db45fc18ee4f99d5eab57b6c267d93556a8064cb704478590b457ec48f2f
+  metadata.gz: 4c90a776bb731f2a140469a03092e8307997602d7723f73517ed804f0f3973cbfed9692baf8f0f98e47320e0b5c4316bbaa15ffc36c70637d68d553e9a537d25
+  data.tar.gz: e52c211802a6e740dcd8b1b77ef3d7cad8b39d6a5aa714b7f1619c9ec2391d893140a636562cb6bafdc326ce4bcbd42904bfe053e6410ceec215720d72100b4a

data/README.adoc

@@ -79,6 +79,30 @@ class MyWorker
 end
 ----
 
+=== Requeue Strategy
+The default requeue strategy `:enqueue` puts jobs immiediately back on the queue if they are being limited, with a potential `cooldown_period`. This is often an appropriate strategy but in some situations may cause the system to repeatedly dequeue and reenque the same job causing excessive redis CPU usage.
+
+An alternative requeue strategy `:schedule` is available that schedules the work for the future. This can be less appropriate for highly concurrent jobs, but may be a good way to reduce redis load when the number of jobs to be processed is modest.
+
+The alternative `:schedule` strategy may be configured globally with `config.default_requeue_options = { with: :schedule }`
+
+It may be configured on a per job basis with:
+
+```ruby
+  sidekiq_throttle(
+    # Allow 5 jobs to processed within 1 minute, using the 
+    threshold: { limit: 5, period: 1.minute, requeue: {with: :schedule} }
+  )
+```
+
+It is also possible to requeue jobs to another queue:
+
+```ruby
+  sidekiq_throttle(
+    # Allow 5 jobs to processed within 1 minute, using the 
+    threshold: { limit: 5, period: 1.minute, requeue: {to: :other_queue, with: :schedule} }
+  )
+```
 
 === Web UI
 
@@ -246,8 +270,8 @@ class MyJob
   sidekiq_throttle(
     # Allow maximum 10 concurrent jobs per project at a time and maximum 2 jobs per user
     concurrency: [
-      { limit: 10, key_suffix: -> (project_id, user_id) { project_id } },
-      { limit: 2, key_suffix: -> (project_id, user_id) { user_id } }
+      { limit: 10, key_suffix: -> (project_id, user_id) { "project_id:#{project_id}" } },
+      { limit: 2, key_suffix: -> (project_id, user_id) { "user_id:#{user_id}" } }
     ]
     # For :threshold it works the same
   )
@@ -309,16 +333,56 @@ lock TTL to fit your needs:
 sidekiq_throttle(concurrency: { limit: 20, ttl: 1.hour.to_i })
 ----
 
+=== Scheduling based concurrency tuning
+
+The default concurrency throttling algorithm immediately requeues throttled
+jobs. This can lead to a lot of wasted work picking up the same set of still
+throttled jobs repeatedly. This churn also often starves lower priority
+jobs/queues. The `:schedule` requeue strategy delays checking the runability of
+throttled jobs until likely to be runnable. This future time is estimated based
+on the expected runtime of the job and current number of throttled jobs. This
+eliminates -- or greatly reduces -- the negative impacts to non-throttled job
+types and queues and reduces wasted work constantly rechecking the same still
+throttled jobs.
+
+**Config items**
+
+- `limit` — Maximum number of this job allowed to run simultaneously.
+- `avg_job_duration` — Expected runtime (in seconds) for this job type.  
+  Choose a value on the high end of what’s plausible; if you set this too low under heavy load, job scheduling will become sub-optimal.
+- `lost_job_threshold` — Duration (in seconds) representing how long a job “owns” its concurrency slot before being considered lost.
+- `ttl` — Deprecated alias for `lost_job_threshold`.
+- `max_delay` — The maximum number of seconds to delay a job when it is throttled.  
+  Prevents excessively long scheduling delays as the backlog grows.  
+  _Default: the smaller of 30 minutes or `10 × avg_job_duration`._
+
+[source,ruby]
+----
+sidekiq_throttle(
+  concurrency: {
+    # only run 10 of this job at a time 
+    limit: 10,
+    # these jobs finish in less than 30 seconds 
+    avg_job_duration: 30,
+    # if it doesn't release its lease in 2 minutes it's considered lost
+    lost_job_threshold: 120,
+    # maximum delay allowed when throttled
+    max_delay: 300
+  },
+  # requeue using Sidekiq's scheduler
+  requeue: { with: :schedule }
+)
+----
+
 
 == Supported Ruby Versions
 
 This library aims to support and is tested against the following Ruby versions:
 
-* Ruby 2.7.x
-* Ruby 3.0.x
-* Ruby 3.1.x
 * Ruby 3.2.x
 * Ruby 3.3.x
+* Ruby 3.4.x
+* Ruby 4.0.x
 
 If something doesn't work on one of these versions, it's a bug.
 
@@ -338,15 +402,13 @@ dropped.
 
 This library aims to support and work with following Sidekiq versions:
 
-* Sidekiq 7.0.x
-* Sidekiq 7.1.x
-* Sidekiq 7.2.x
+* Sidekiq 8.0.x
+* Sidekiq 8.1.x
 
-And the following Sidekiq Pro versions:
+And (might work with) the following Sidekiq Pro versions:
 
-* Sidekiq Pro 7.0.x
-* Sidekiq Pro 7.1.x
-* Sidekiq Pro 7.2.x
+* Sidekiq Pro 8.0.x
+* Sidekiq Pro 8.1.x
 
 == Development
 
@@ -361,6 +423,7 @@ If you're working on Sidekiq-Pro support make sure that you have Sidekiq-Pro
 license set either in the global config, or in `BUNDLE_GEMS\__CONTRIBSYS__COM`
 environment variable.
 
+
 == Contributing
 
 * Fork sidekiq-throttled on GitHub

data/lib/sidekiq/throttled/config.rb

@@ -51,7 +51,7 @@ module Sidekiq
 
       # @!attribute [w] default_requeue_options
       def default_requeue_options=(options)
-        requeue_with = options.delete(:with).intern || :enqueue
+        requeue_with = options.delete(:with)&.to_sym || :enqueue
 
         @default_requeue_options = options.merge({ with: requeue_with })
       end

data/lib/sidekiq/throttled/job.rb

@@ -88,8 +88,8 @@ module Sidekiq
         # @param [Hash] requeue What to do with jobs that are throttled
         # @see Registry.add
         # @return [void]
-        def sidekiq_throttle(**kwargs)
-          Registry.add(self, **kwargs)
+        def sidekiq_throttle(**)
+          Registry.add(self, **)
         end
 
         # Adds current worker to preconfigured throttling strategy. Allows

data/lib/sidekiq/throttled/registry.rb

@@ -17,10 +17,10 @@ module Sidekiq
         #
         # @param (see Strategy#initialize)
         # @return [Strategy]
-        def add(name, **kwargs)
+        def add(name, **)
           name = name.to_s
 
-          @strategies[name] = Strategy.new(name, **kwargs)
+          @strategies[name] = Strategy.new(name, **)
         end
 
         # Adds alias for existing strategy.

data/lib/sidekiq/throttled/strategy/base.rb

@@ -14,7 +14,11 @@ module Sidekiq
           key = @base_key.dup
           return key unless @key_suffix
 
-          key << ":#{@key_suffix.call(*job_args)}"
+          key << ":#{key_suffix(job_args)}"
+        end
+
+        def key_suffix(job_args)
+          @key_suffix.respond_to?(:call) ? @key_suffix.call(*job_args) : @key_suffix
         rescue StandardError => e
           Sidekiq.logger.error "Failed to get key suffix: #{e}"
           raise e

data/lib/sidekiq/throttled/strategy/concurrency.lua

@@ -1,16 +1,61 @@
-local key = KEYS[1]
+local in_progress_jobs_key = KEYS[1]
+local backlog_info_key = KEYS[2]
 local jid = ARGV[1]
 local lmt = tonumber(ARGV[2])
-local ttl = tonumber(ARGV[3])
+local lost_job_threshold = tonumber(ARGV[3])
 local now = tonumber(ARGV[4])
 
-redis.call("ZREMRANGEBYSCORE", key, "-inf", "(" .. now)
+-- supporting functions
+local function over_limit()
+  return lmt <= redis.call("ZCARD", in_progress_jobs_key)
+end
+
+local function job_already_in_progress()
+  return redis.call("ZSCORE", in_progress_jobs_key, jid)
+end
+
+-- Estimates current backlog size. This function tends to underestimate 
+-- the actual backlog. This is intentional. Overestimates are bad as it
+-- can cause unnecessary delays in job processing. Underestimates are much
+-- safer as they only increase workload of sidekiq processors. 
+local function est_current_backlog_size()
+  local old_size = tonumber(redis.call("HGET", backlog_info_key, "size")) or 0
+  local old_timestamp = tonumber(redis.call("HGET", backlog_info_key, "timestamp")) or now
+  
+  local jobs_lost_since_old_timestamp = (now - old_timestamp) / lost_job_threshold * lmt
+
+  return math.max(old_size - jobs_lost_since_old_timestamp, 0) 
+end
+
+
+local function change_backlog_size(delta)
+  local curr_backlog_size = est_current_backlog_size()
+
+  redis.call("HSET", backlog_info_key, "size", curr_backlog_size + delta) 
+  redis.call("HSET", backlog_info_key, "timestamp", now)
+  redis.call("EXPIRE", backlog_info_key, math.ceil((lost_job_threshold * curr_backlog_size) + 1 / lmt))
+end
+
+local function register_job_in_progress()
+  redis.call("ZADD", in_progress_jobs_key, now + lost_job_threshold , jid)
+  redis.call("EXPIRE", in_progress_jobs_key, lost_job_threshold)
+end
+
+local function clear_stale_in_progress_jobs()
+  local cleared_count = redis.call("ZREMRANGEBYSCORE", in_progress_jobs_key, "-inf", "(" .. now)
+  change_backlog_size(-cleared_count)
+end
+
+-- END supporting functions
+
+clear_stale_in_progress_jobs()
 
-if lmt <= redis.call("ZCARD", key) and not redis.call("ZSCORE", key, jid) then
+if over_limit() and not job_already_in_progress() then
+  change_backlog_size(1)
   return 1
 end
 
-redis.call("ZADD", key, now + ttl, jid)
-redis.call("EXPIRE", key, ttl)
+register_job_in_progress()
+change_backlog_size(-1)
 
 return 0

data/lib/sidekiq/throttled/strategy/concurrency.rb

@@ -26,13 +26,26 @@ module Sidekiq
         # @param [#to_s] strategy_key
         # @param [#to_i, #call] limit Amount of allowed concurrent jobs
         #   per processors running for given key.
-        # @param [#to_i] ttl Concurrency lock TTL in seconds.
+        # @param [#to_i] avg_job_duration Average number of seconds needed
+        #   to complete a job of this type. Default: 300 or 1/3 of lost_job_threshold
+        # @param [#to_i] lost_job_threshold Seconds to wait before considering
+        #   a job lost or dead. Default: 900 or 3 * avg_job_duration
         # @param [Proc] key_suffix Dynamic key suffix generator.
-        def initialize(strategy_key, limit:, ttl: 900, key_suffix: nil)
-          @base_key   = "#{strategy_key}:concurrency.v2"
-          @limit      = limit
-          @ttl        = ttl.to_i
+        # @param [#to_i] max_delay Maximum number of seconds to delay a job when it
+        #   throttled. This prevents jobs from being schedule very far in the future
+        #   when the backlog is large. Default: the smaller of 30 minutes or 10 * avg_job_duration
+        # @deprecated @param [#to_i] ttl Obsolete alias for `lost_job_threshold`.
+        #   Default: 900 or 3 * avg_job_duration
+        def initialize(strategy_key, limit:, avg_job_duration: nil, ttl: nil, # rubocop:disable Metrics/ParameterLists
+                       lost_job_threshold: ttl, key_suffix: nil, max_delay: nil)
+          @base_key = "#{strategy_key}:concurrency.v2"
+          @limit = limit
+          @avg_job_duration, @lost_job_threshold = interp_duration_args(avg_job_duration, lost_job_threshold)
           @key_suffix = key_suffix
+          @max_delay = max_delay || [(10 * @avg_job_duration), 1_800].min
+
+          raise(ArgumentError, "lost_job_threshold must be greater than avg_job_duration") if
+            @lost_job_threshold <= @avg_job_duration
         end
 
         # @return [Boolean] Whenever strategy has dynamic config
@@ -46,8 +59,8 @@ module Sidekiq
           return false unless job_limit
           return true if job_limit <= 0
 
-          keys = [key(job_args)]
-          argv = [jid.to_s, job_limit, @ttl, Time.now.to_f]
+          keys = [key(job_args), backlog_info_key(job_args)]
+          argv = [jid.to_s, job_limit, @lost_job_threshold, Time.now.to_f]
 
           Sidekiq.redis { |redis| 1 == SCRIPT.call(redis, keys: keys, argv: argv) }
         end
@@ -57,9 +70,8 @@ module Sidekiq
           job_limit = limit(job_args)
           return 0.0 if !job_limit || count(*job_args) < job_limit
 
-          oldest_jid_with_score = Sidekiq.redis { |redis| redis.zrange(key(job_args), 0, 0, withscores: true) }.first
-          expiry_time = oldest_jid_with_score.last.to_f
-          expiry_time - Time.now.to_f
+          (estimated_backlog_size(job_args) * @avg_job_duration / limit(job_args))
+            .then { |delay_sec| @max_delay * (1 - Math.exp(-delay_sec / @max_delay)) } # limit to max_delay
         end
 
         # @return [Integer] Current count of jobs
@@ -76,7 +88,40 @@ module Sidekiq
         # Remove jid from the pool of jobs in progress
         # @return [void]
         def finalize!(jid, *job_args)
-          Sidekiq.redis { |conn| conn.zrem(key(job_args), jid.to_s) }
+          Sidekiq.redis do |conn|
+            conn.zrem(key(job_args), jid.to_s)
+          end
+        end
+
+        private
+
+        def backlog_info_key(job_args)
+          "#{key(job_args)}.backlog_info"
+        end
+
+        def estimated_backlog_size(job_args)
+          old_size_str, old_timestamp_str =
+            Sidekiq.redis { |conn| conn.hmget(backlog_info_key(job_args), "size", "timestamp") }
+          old_size = (old_size_str || 0).to_f
+          old_timestamp = (old_timestamp_str || Time.now).to_f
+
+          (old_size - jobs_lost_since(old_timestamp, job_args)).clamp(0, Float::INFINITY)
+        end
+
+        def jobs_lost_since(timestamp, job_args)
+          (Time.now.to_f - timestamp) / @lost_job_threshold * limit(job_args)
+        end
+
+        def interp_duration_args(avg_job_duration, lost_job_threshold)
+          if avg_job_duration && lost_job_threshold
+            [avg_job_duration.to_i, lost_job_threshold.to_i]
+          elsif avg_job_duration && lost_job_threshold.nil?
+            [avg_job_duration.to_i, avg_job_duration.to_i * 3]
+          elsif avg_job_duration.nil? && lost_job_threshold
+            [lost_job_threshold.to_i / 3, lost_job_threshold.to_i]
+          else
+            [300, 900]
+          end
         end
       end
     end

data/lib/sidekiq/throttled/version.rb

@@ -3,6 +3,6 @@
 module Sidekiq
   module Throttled
     # Gem version
-    VERSION = "1.5.2"
+    VERSION = "2.1.0"
   end
 end

data/lib/sidekiq/throttled/web/stats.rb

@@ -62,12 +62,13 @@ module Sidekiq
 
         # @return [String]
         def humanize_integer(int)
-          digits = int.to_s.chars
-          str    = digits.shift(digits.count % 3).join
-
-          str << " " << digits.shift(3).join while digits.count.positive?
-
-          str.strip
+          int.to_s.chars
+            .reverse
+            .each_slice(3)
+            .map(&:reverse)
+            .reverse
+            .map(&:join)
+            .join(",")
         end
       end
     end

data/lib/sidekiq/throttled/web.rb

@@ -1,43 +1,39 @@
 # frozen_string_literal: true
 
-# stdlib
 require "pathname"
 
-# 3rd party
 require "sidekiq"
 require "sidekiq/web"
 
-# internal
 require_relative "./registry"
 require_relative "./web/stats"
 
 module Sidekiq
   module Throttled
-    # Provides Sidekiq tab to monitor and reset throttled stats.
     module Web
-      VIEWS         = Pathname.new(__dir__).join("web")
-      THROTTLED_TPL = VIEWS.join("throttled.html.erb").read.freeze
+      ROOT  = Pathname.new(__dir__).join("../../../web").expand_path.realpath.freeze
+      VIEWS = ROOT.join("views").freeze
 
-      class << self
-        # @api private
-        def registered(app)
-          register_throttled_tab app
+      def self.registered(app)
+        app.get("/throttled") do
+          erb :index, views: VIEWS
         end
 
-        private
-
-        def register_throttled_tab(app)
-          app.get("/throttled") { erb THROTTLED_TPL.dup }
-
-          app.post("/throttled/:id/reset") do
-            Registry.get(params[:id], &:reset!)
-            redirect "#{root_path}throttled"
-          end
+        app.post("/throttled/:id/reset") do
+          Registry.get(route_params(:id), &:reset!)
+          redirect "#{root_path}throttled"
         end
       end
     end
   end
 end
 
-Sidekiq::Web.register Sidekiq::Throttled::Web
-Sidekiq::Web.tabs["Throttled"] = "throttled"
+Sidekiq::Web.configure do |config|
+  config.register_extension(
+    Sidekiq::Throttled::Web,
+    name:     "throttled",
+    tab:      %w[Throttled],
+    index:    %w[throttled],
+    root_dir: Sidekiq::Throttled::Web::ROOT.to_s
+  )
+end

data/web/views/index.erb

@@ -0,0 +1,41 @@
+<section>
+  <header>
+    <h1>Throttled</h1>
+  </header>
+
+  <div class="table_container">
+    <table class="throttled">
+      <thead>
+        <tr>
+          <th>Name</th>
+          <th>Concurrency</th>
+          <th>Threshold</th>
+          <th>Actions</th>
+        </tr>
+      </thead>
+      <tbody>
+        <% Sidekiq::Throttled::Registry.each_with_static_keys do |name, strategy| %>
+          <tr>
+            <td style="vertical-align:middle;"><%= name %></td>
+            <td style="vertical-align:middle;text-align:center;">
+              <% strategy.concurrency.each do |concurrency| %>
+                <%= Sidekiq::Throttled::Web::Stats.new(concurrency).to_html %>
+              <% end %>
+            </td>
+            <td style="vertical-align:middle;text-align:center;">
+              <% strategy.threshold.each do |threshold| %>
+                <%= Sidekiq::Throttled::Web::Stats.new(threshold).to_html %>
+              <% end %>
+            </td>
+            <td style="vertical-align:middle;text-align:center;">
+              <form action="<%= root_path %>throttled/<%= CGI.escape name %>/reset" method="post">
+                <%= csrf_tag %>
+                <button class="btn btn-danger" type="submit">Reset</button>
+              </form>
+            </td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  </div>
+</section>

data/web/views/index.html.erb

@@ -0,0 +1 @@
+index.erb

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: sidekiq-throttled
 version: !ruby/object:Gem::Version
-  version: 1.5.2
+  version: 2.1.0
 platform: ruby
 authors:
 - Alexey Zapparov
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-01-12 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -44,15 +43,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.5'
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.5'
-description:
+        version: '8.0'
 email:
 - alexey@zapparov.com
 executables: []
@@ -83,18 +81,18 @@ files:
 - lib/sidekiq/throttled/version.rb
 - lib/sidekiq/throttled/web.rb
 - lib/sidekiq/throttled/web/stats.rb
-- lib/sidekiq/throttled/web/throttled.html.erb
 - lib/sidekiq/throttled/worker.rb
+- web/views/index.erb
+- web/views/index.html.erb
 homepage: https://github.com/ixti/sidekiq-throttled
 licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/ixti/sidekiq-throttled
-  source_code_uri: https://github.com/ixti/sidekiq-throttled/tree/v1.5.2
+  source_code_uri: https://github.com/ixti/sidekiq-throttled/tree/v2.1.0
   bug_tracker_uri: https://github.com/ixti/sidekiq-throttled/issues
-  changelog_uri: https://github.com/ixti/sidekiq-throttled/blob/v1.5.2/CHANGES.md
+  changelog_uri: https://github.com/ixti/sidekiq-throttled/blob/v2.1.0/CHANGES.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -102,15 +100,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Concurrency and rate-limit throttling for Sidekiq
 test_files: []

data/lib/sidekiq/throttled/web/throttled.html.erb

@@ -1,35 +0,0 @@
-<h3>Throttled</h3>
-
-<div class="table_container">
-  <table class="table table-hover table-bordered table-striped table-white">
-    <thead>
-      <tr>
-        <th>Name</th>
-        <th style="text-align:center;">Concurrency</th>
-        <th style="text-align:center;">Threshold</th>
-        <th style="text-align:center;">Actions</th>
-      </tr>
-    </thead>
-    <% Sidekiq::Throttled::Registry.each_with_static_keys do |name, strategy| %>
-      <tr>
-        <td style="vertical-align:middle;"><%= name %></td>
-        <td style="vertical-align:middle;text-align:center;">
-          <% strategy.concurrency.each do |concurrency| %>
-            <%= Sidekiq::Throttled::Web::Stats.new(concurrency).to_html %>
-          <% end %>
-        </td>
-        <td style="vertical-align:middle;text-align:center;">
-          <% strategy.threshold.each do |threshold| %>
-            <%= Sidekiq::Throttled::Web::Stats.new(threshold).to_html %>
-          <% end %>
-        </td>
-        <td style="vertical-align:middle;text-align:center;">
-          <form action="<%= root_path %>throttled/<%= CGI.escape name %>/reset" method="post">
-            <%= csrf_tag %>
-            <button class="btn btn-danger" type="submit">Reset</button>
-          </form>
-        </td>
-      </tr>
-    <% end %>
-  </table>
-</div>