Add workers :auto (#3827)

nateberkopec · web-flow · commit 5d7d1ddb266d · 2026-01-20T11:53:03.000+09:00
* Add workers :auto * Docs: clarify workers :auto hook gotcha [ci skip] * Apply @MSP-Greg suggestion, but don't break tests
diff --git a/README.md b/README.md
@@ -115,9 +115,18 @@ Or with the `WEB_CONCURRENCY` environment variable:
 $ WEB_CONCURRENCY=3 puma -t 8:32
 ```
 
+When using a config file, most applications can simply set `workers :auto` (requires the `concurrent-ruby` gem) to match the number of worker processes to the available processors:
+
+```ruby
+# config/puma.rb
+workers :auto
+```
+
+See [`workers :auto` gotchas](lib/puma/dsl.rb).
+
 Note that threads are still used in cluster mode, and the `-t` thread flag setting is per worker, so `-w 2 -t 16:16` will spawn 32 threads in total, with 16 in each worker process.
 
-If the `WEB_CONCURRENCY` environment variable is set to `"auto"` and the `concurrent-ruby` gem is available in your application, Puma will set the worker process count to the result of [available processors](https://msp-greg.github.io/concurrent-ruby/Concurrent.html#available_processor_count-class_method).
+If `workers` is set to `:auto`, or the `WEB_CONCURRENCY` environment variable is set to `"auto"`, and the `concurrent-ruby` gem is available in your application, Puma will set the worker process count to the result of [available processors](https://msp-greg.github.io/concurrent-ruby/Concurrent.html#available_processor_count-class_method).
 
 For an in-depth discussion of the tradeoffs of thread and process count settings, [see our docs](docs/deployment.md).
 
diff --git a/docs/deployment.md b/docs/deployment.md
@@ -35,10 +35,14 @@ For the purposes of Puma provisioning, "CPU cores" means:
 
 Set your config with the following process:
 
-* Use cluster mode and set the number of workers to the same number of CPU cores on the machine (minimum 2, otherwise use single mode!)
+* Use cluster mode and set `workers :auto` (requires the `concurrent-ruby` gem) to match the number of CPU cores on the machine (minimum 2, otherwise use single mode!). If you can't add the gem, set the worker count manually to the available CPU cores.
 * Set the number of threads to desired concurrent requests/number of workers.
   Puma defaults to 5, and that's a decent number.
 
+For most deployments, adding `concurrent-ruby` and using `workers :auto` is the right starting point.
+
+See [`workers :auto` gotchas](../lib/puma/dsl.rb).
+
 ## Worker utilization
 
 **How do you know if you've got enough (or too many workers)?**
@@ -72,7 +76,7 @@ Should you run 2 pods with 50 workers each? 25 pods, each with 4 workers? 100 po
 * **Increasing thread counts will increase throughput, but also latency and memory use** Unless you have a very I/O-heavy application (50%+ time spent waiting on IO), use the default thread count (5 for MRI). Using higher numbers of threads with low I/O wait (<50% of wall clock time) will lead to additional request latency and additional memory usage.
 * **Increasing worker counts decreases memory per worker on average**. More processes per pod reduces memory usage per process, because of copy-on-write memory and because the cost of the single master process is "amortized" over more child processes.
 * **Low worker counts (<4) have exceptionally poor throughput**. Don't run less than 4 processes per pod if you can. Low numbers of processes per pod will lead to high request queueing (see discussion above), which means you will have to run more pods and resources.
-* **CPU-core-to-worker ratios should be around 1**. If running Puma with `threads > 1`, allocate 1 CPU core (see definition above!) per worker. If single threaded, allocate ~0.75 cpus per worker. Most web applications spend about 25% of their time in I/O - but when you're running multi-threaded, your Puma process will have higher CPU usage and should be able to fully saturate a CPU core.
+* **CPU-core-to-worker ratios should be around 1**. If running Puma with `threads > 1`, allocate 1 CPU core (see definition above!) per worker. If single threaded, allocate ~0.75 cpus per worker. Most web applications spend about 25% of their time in I/O - but when you're running multi-threaded, your Puma process will have higher CPU usage and should be able to fully saturate a CPU core. Using `workers :auto` will size workers to this guidance on most platforms.
 * **Don't set memory limits unless necessary**. Most Puma processes will use about ~512MB-1GB per worker, and about 1GB for the master process. However, you probably shouldn't bother with setting memory limits lower than around 2GB per process, because most places you are deploying will have 2GB of RAM per CPU. A sensible memory limit for a Puma configuration of 4 child workers might be something like 8 GB (1 GB for the master, 7GB for the 4 children).
 
 **Measuring utilization and queue time**
diff --git a/lib/puma/configuration.rb b/lib/puma/configuration.rb
@@ -238,18 +238,14 @@ def puma_options_from_env(env = ENV)
       min = env['PUMA_MIN_THREADS'] || env['MIN_THREADS']
       max = env['PUMA_MAX_THREADS'] || env['MAX_THREADS']
       persistent_timeout = env['PUMA_PERSISTENT_TIMEOUT']
-      workers = if env['WEB_CONCURRENCY'] == 'auto'
-        require_processor_counter
-        ::Concurrent.available_processor_count
-      else
-        env['WEB_CONCURRENCY']&.strip
-      end
+      workers_env = env['WEB_CONCURRENCY']
+      workers = workers_env && workers_env.strip != "" ? parse_workers(workers_env.strip) : nil
 
       {
         min_threads: min && min != "" && Integer(min),
         max_threads: max && max != "" && Integer(max),
         persistent_timeout: persistent_timeout && persistent_timeout != "" && Integer(persistent_timeout),
-        workers: workers && workers != "" && Integer(workers),
+        workers: workers,
         environment: env['APP_ENV'] || env['RACK_ENV'] || env['RAILS_ENV'],
       }
     end
@@ -380,12 +376,23 @@ def require_processor_counter
       require 'concurrent/utility/processor_counter'
     rescue LoadError
       warn <<~MESSAGE
-        WEB_CONCURRENCY=auto requires the "concurrent-ruby" gem to be installed.
+        WEB_CONCURRENCY=auto or workers(:auto) requires the "concurrent-ruby" gem to be installed.
         Please add "concurrent-ruby" to your Gemfile.
       MESSAGE
       raise
     end
 
+    def parse_workers(value)
+      if value == :auto || value == 'auto'
+        require_processor_counter
+        Integer(::Concurrent.available_processor_count)
+      else
+        Integer(value)
+      end
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "workers must be an Integer or :auto"
+    end
+
     # Load and use the normal Rack builder if we can, otherwise
     # fallback to our minimal version.
     def rack_builder
diff --git a/lib/puma/dsl.rb b/lib/puma/dsl.rb
@@ -669,21 +669,27 @@ def state_permission(permission)
       @options[:state_permission] = permission
     end
 
-    # How many worker processes to run.  Typically this is set to
-    # the number of available cores.
+    # How many worker processes to run. Typically this is set to the number of
+    # available cores.
     #
     # The default is the value of the environment variable +WEB_CONCURRENCY+ if
-    # set, otherwise 0.
+    # set, otherwise 0. Passing +:auto+ will set the value to
+    # +Concurrent.available_processor_count+ (requires the concurrent-ruby gem).
+    # On some platforms (e.g. under CPU quotas) this may be fractional, and Puma
+    # will round down. If it rounds down to 0, Puma will run in single mode and
+    # cluster-only hooks like +before_worker_boot+ will not execute.
+    # If you rely on cluster-only hooks, set an explicit worker count.
     #
-    # @note Cluster mode only.
+    # A value of 0 or nil means run in single mode.
     #
     # @example
     #   workers 2
+    #   workers :auto
     #
     # @see Puma::Cluster
     #
     def workers(count)
-      @options[:workers] = count.to_i
+      @options[:workers] = count.nil? ? 0 : @config.send(:parse_workers, count)
     end
 
     # Disable warning message when running in cluster mode with a single worker.
diff --git a/test/test_config.rb b/test/test_config.rb
@@ -830,6 +830,43 @@ def test_config_loads_correct_max_threads
     assert_equal default_max_threads, conf.options.default_options[:max_threads]
   end
 
+  def test_config_workers_auto_from_dsl_and_env
+    require 'concurrent/utility/processor_counter'
+
+    Concurrent.stub(:available_processor_count, 5) do
+      conf = Puma::Configuration.new
+      conf.configure { |c| c.workers :auto }
+      conf.clamp
+      assert_equal 5, conf.options[:workers]
+    end
+
+    Concurrent.stub(:available_processor_count, 1.7) do
+      conf = Puma::Configuration.new({}, {}, { "WEB_CONCURRENCY" => "auto" })
+      conf.clamp
+      assert_equal 1, conf.options.default_options[:workers]
+    end
+  end
+
+  def test_config_workers_auto_requires_concurrent_ruby
+    conf = Puma::Configuration.new
+
+    def conf.require(path)
+      raise LoadError, "Mocking system where concurrent-ruby is not available" if path == 'concurrent/utility/processor_counter'
+      super(path)
+    end
+
+    _, err = capture_io do
+      assert_raises(LoadError) { conf.configure { |c| c.workers :auto } }
+    end
+    assert_includes err, 'Please add "concurrent-ruby" to your Gemfile'
+  end
+
+  def test_config_workers_rejects_unknown_symbol
+    conf = Puma::Configuration.new
+    error = assert_raises(ArgumentError) { conf.configure { |c| c.workers :boom } }
+    assert_includes error.message, 'Integer or :auto'
+  end
+
   def test_config_loads_workers_from_env
     env = { "WEB_CONCURRENCY" => "9" }
     conf = Puma::Configuration.new({}, {}, env)
