solid_queue_autoscaler 1.0.19 → 1.0.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a4488b919923025829a72e3c9a23220a528f76499adfe1575b3f7484adca8ec
-  data.tar.gz: 19b2bf974f03231b8f060ebaaa12ff0ce214ee3bb89620a1b90981fee3e0410e
+  metadata.gz: 4d595bb4e0a25ed4dee60b1356275872000b56845d574a2df7251a3c49f51a2c
+  data.tar.gz: 3fa34bfdbd30991096ceba918548660b955ab882ca050bae2e03be94f19c0967
 SHA512:
-  metadata.gz: 4dac7f9c83dab082137824c6a730fb6bb68e042758f155aac8480067810904bc234b9f152c7ee023264b6fcb4eb09c2fbfebc43b668520b0fdb446cc66eb1dad
-  data.tar.gz: 56c9cc4d51523f1752fc36e70f8c3cc4cb83177c4e7c345c8972116d27b0e12812aedbe2839f8bcb958f4ea50dd20432f3a686d2e9217e2fbf2588bf0cbfe872
+  metadata.gz: 52e7e13ad3261de3ca958e5e5468b9fde784c1573a4e3865022331c07e21ce74d047646cb68f7d9376df1b3863ffded3a2dcd649655047ca240db074050f65c0
+  data.tar.gz: ce1ad6a0ab0eb9205cf73db618d0363afeedc449c9527b0187f634aa320ec0735e4c216990f0dc3aae760f47936ab48abd5ab278aafd845b4e3d0ecd48f9a923

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.21] - 2025-02-02
+
+### Added
+- **Scale-from-zero documentation** - Updated README and docs/configuration.md with:
+  - New "Faster Scale-from-Zero" section explaining the v1.0.20 optimizations
+  - Configuration reference for `scale_from_zero_queue_depth` and `scale_from_zero_latency_seconds`
+  - Example configuration showing how to customize scale-from-zero behavior
+  - Explanation of cooldown bypass and grace period for other workers
+
+## [1.0.20] - 2025-02-02
+
+### Added
+- **Scale-from-zero optimization** - New configuration options for faster cold starts when `min_workers = 0`:
+  - `scale_from_zero_queue_depth` (default: 1) - Scale up immediately when at 0 workers if queue has at least this many jobs
+  - `scale_from_zero_latency_seconds` (default: 1.0) - Job must be at least this old before scaling up (gives other workers a chance to pick it up first)
+  - When at 0 workers, uses these lower thresholds instead of the normal `scale_up_queue_depth` and `scale_up_latency_seconds`
+  - Cooldowns are bypassed when scaling from 0 workers for fast cold start
+  - Comprehensive tests in `scale_to_zero_workflow_spec.rb`
+
 ## [1.0.19] - 2025-02-02
 
 ### Added

data/README.md

@@ -80,6 +80,41 @@ end
 
 Total cold-start time is typically **30-90 seconds** depending on your configuration and dyno startup time.
 
+### Faster Scale-from-Zero (v1.0.20+)
+
+As of **v1.0.20**, the autoscaler includes optimizations for faster cold starts when scaling from zero:
+
+1. **Lower thresholds at zero**: When workers are at 0 (with `min_workers = 0`), the autoscaler uses separate, more aggressive thresholds:
+   - `scale_from_zero_queue_depth` (default: 1) - Scale up when there's at least 1 job
+   - `scale_from_zero_latency_seconds` (default: 1.0) - Job must be at least 1 second old
+
+2. **Cooldown bypass**: Cooldowns are skipped when scaling from 0 workers, ensuring the fastest possible response.
+
+3. **Grace period for other workers**: The `scale_from_zero_latency_seconds` setting (default: 1 second) ensures that if you have multiple worker types, other workers have a brief chance to pick up the job before a new dyno is spun up.
+
+**Example configuration:**
+
+```ruby
+SolidQueueAutoscaler.configure(:batch_worker) do |config|
+  config.adapter = :heroku
+  config.heroku_api_key = ENV['HEROKU_API_KEY']
+  config.heroku_app_name = ENV['HEROKU_APP_NAME']
+  config.process_type = 'batch_worker'
+
+  # Enable scale-to-zero
+  config.min_workers = 0
+  config.max_workers = 5
+
+  # Normal scaling thresholds (used when workers > 0)
+  config.scale_up_queue_depth = 100
+  config.scale_up_latency_seconds = 300
+
+  # Scale-from-zero thresholds (used when workers == 0)
+  config.scale_from_zero_queue_depth = 1        # Scale up with just 1 job
+  config.scale_from_zero_latency_seconds = 2.0  # Wait 2 seconds for other workers
+end
+```
+
 **Where to run the autoscaler**: The autoscaler job **must run on a process that's always running** (like your web dyno), NOT on the workers being scaled. If the autoscaler runs on workers and those workers scale to zero, there's nothing to scale them back up!
 
 ```yaml
@@ -326,6 +361,17 @@ Scaling down triggers when **ALL** thresholds are met:
 | `scale_down_cooldown_seconds` | Integer | `nil` | Override for scale-down cooldown |
 | `persist_cooldowns` | Boolean | `true` | Save cooldowns to database |
 
+### Scale-from-Zero Optimization
+
+These settings control the faster cold-start behavior when `min_workers = 0` and workers are currently at 0:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `scale_from_zero_queue_depth` | Integer | `1` | Jobs in queue to trigger scale-up when at 0 workers |
+| `scale_from_zero_latency_seconds` | Float | `1.0` | Job must be at least this old (gives other workers a chance) |
+
+**Note:** When scaling from 0 workers, cooldowns are automatically bypassed for the fastest possible response.
+
 ### AutoscaleJob Settings
 
 | Option | Type | Default | Description |

data/lib/solid_queue_autoscaler/configuration.rb

@@ -69,6 +69,9 @@ module SolidQueueAutoscaler
     # AutoscaleJob settings
     attr_accessor :job_queue, :job_priority
 
+    # Scale-from-zero settings (for faster cold start when min_workers=0)
+    attr_accessor :scale_from_zero_queue_depth, :scale_from_zero_latency_seconds
+
     def initialize
       # Configuration name (auto-set when using named configurations)
       @name = :default
@@ -141,6 +144,11 @@ module SolidQueueAutoscaler
       # AutoscaleJob settings
       @job_queue = :autoscaler # Queue name for the autoscaler job
       @job_priority = nil # Job priority (lower = higher priority, nil = default)
+
+      # Scale-from-zero settings (for faster cold start when min_workers=0)
+      # When at 0 workers, use these lower thresholds instead of normal scale_up thresholds
+      @scale_from_zero_queue_depth = 1 # Scale up if at least 1 job in queue
+      @scale_from_zero_latency_seconds = 1.0 # Job must be at least 1 second old (gives other workers a chance)
     end
 
     # Returns the lock key, auto-generating based on name if not explicitly set
@@ -196,6 +204,10 @@ module SolidQueueAutoscaler
         errors << "scaling_strategy must be one of: #{VALID_SCALING_STRATEGIES.join(', ')}"
       end
 
+      # Validate scale-from-zero settings
+      errors << 'scale_from_zero_queue_depth must be > 0' if scale_from_zero_queue_depth <= 0
+      errors << 'scale_from_zero_latency_seconds must be >= 0' if scale_from_zero_latency_seconds.negative?
+
       raise ConfigurationError, errors.join(', ') if errors.any?
 
       true

data/lib/solid_queue_autoscaler/decision_engine.rb

@@ -41,12 +41,30 @@ module SolidQueueAutoscaler
     def should_scale_up?(metrics, current_workers)
       return false if current_workers >= @config.max_workers
 
+      # Special case: scale-from-zero uses lower thresholds for faster cold start
+      # This allows immediate scaling when at 0 workers with any work in queue
+      if current_workers.zero? && @config.min_workers.zero?
+        return should_scale_from_zero?(metrics)
+      end
+
       queue_depth_high = metrics.queue_depth >= @config.scale_up_queue_depth
       latency_high = metrics.oldest_job_age_seconds >= @config.scale_up_latency_seconds
 
       queue_depth_high || latency_high
     end
 
+    # Scale-from-zero check: uses lower thresholds for faster cold start
+    # Requires:
+    # 1. Queue depth >= scale_from_zero_queue_depth (default: 1)
+    # 2. Oldest job age >= scale_from_zero_latency_seconds (default: 1s)
+    #    This gives other workers/queues a chance to pick up the job first
+    def should_scale_from_zero?(metrics)
+      has_work = metrics.queue_depth >= @config.scale_from_zero_queue_depth
+      job_old_enough = metrics.oldest_job_age_seconds >= @config.scale_from_zero_latency_seconds
+
+      has_work && job_old_enough
+    end
+
     def should_scale_down?(metrics, current_workers)
       return false if current_workers <= @config.min_workers
 
@@ -161,12 +179,22 @@ module SolidQueueAutoscaler
     def build_scale_up_reason(metrics, current_workers = nil, target = nil)
       reasons = []
 
-      if metrics.queue_depth >= @config.scale_up_queue_depth
-        reasons << "queue_depth=#{metrics.queue_depth} >= #{@config.scale_up_queue_depth}"
-      end
+      # Check if this is a scale-from-zero scenario
+      is_scale_from_zero = current_workers&.zero? && @config.min_workers.zero? &&
+                           metrics.queue_depth >= @config.scale_from_zero_queue_depth &&
+                           metrics.oldest_job_age_seconds >= @config.scale_from_zero_latency_seconds
 
-      if metrics.oldest_job_age_seconds >= @config.scale_up_latency_seconds
-        reasons << "latency=#{metrics.oldest_job_age_seconds.round}s >= #{@config.scale_up_latency_seconds}s"
+      if is_scale_from_zero
+        reasons << "scale_from_zero: queue_depth=#{metrics.queue_depth} >= #{@config.scale_from_zero_queue_depth}"
+        reasons << "job_age=#{metrics.oldest_job_age_seconds.round(1)}s >= #{@config.scale_from_zero_latency_seconds}s"
+      else
+        if metrics.queue_depth >= @config.scale_up_queue_depth
+          reasons << "queue_depth=#{metrics.queue_depth} >= #{@config.scale_up_queue_depth}"
+        end
+
+        if metrics.oldest_job_age_seconds >= @config.scale_up_latency_seconds
+          reasons << "latency=#{metrics.oldest_job_age_seconds.round}s >= #{@config.scale_up_latency_seconds}s"
+        end
       end
 
       base_reason = reasons.join(', ')

data/lib/solid_queue_autoscaler/scaler.rb

@@ -185,6 +185,12 @@ module SolidQueueAutoscaler
     end
 
     def cooldown_active?(decision)
+      # Bypass cooldowns when scaling from zero - we want fast cold start
+      # This is safe because there are no workers to destabilize
+      if decision.scale_up? && decision.from.zero? && @config.min_workers.zero?
+        return false
+      end
+
       if @config.persist_cooldowns && cooldown_tracker.table_exists?
         # Use database-persisted cooldowns (survives process restarts)
         if decision.scale_up?

data/lib/solid_queue_autoscaler/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SolidQueueAutoscaler
-  VERSION = '1.0.19'
+  VERSION = '1.0.21'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid_queue_autoscaler
 version: !ruby/object:Gem::Version
-  version: 1.0.19
+  version: 1.0.21
 platform: ruby
 authors:
 - reillyse