Puma Worker Killer

For non-containerized environments, you can enable worker killing based on RAM thresholds. Puma Worker Killer will periodically evaluate the memory usage of all Puma processes and their forks, killing workers that exceed the configured limit. Puma will automatically spawn fresh copies.

# config/puma.rb

before_fork do
  require 'puma_worker_killer'

  PumaWorkerKiller.start
end

Add puma_worker_killer to your Gemfile and run bundle install to install the gem.

gem 'puma_worker_killer'

Rolling restarts kill workers on a periodic basis to keep memory usage down. This is recommended for containerized platforms like Heroku where measuring RAM from inside the container is difficult.

Note: If you use enable_rolling_restart, do not also call PumaWorkerKiller.start.

# config/puma.rb

before_fork do
  require 'puma_worker_killer'

  # Default is every 6 hours
  PumaWorkerKiller.enable_rolling_restart 
end

You can configure the gem using a PumaWorkerKiller.config block or by calling methods directly on the module. Configuration must be done before calling PumaWorkerKiller.start or PumaWorkerKiller.enable_rolling_restart.

PumaWorkerKiller.config do |config|
  config.ram           = 1024 # mb
  config.frequency     = 5    # seconds
  config.percent_usage = 0.98
  config.rolling_restart_frequency = 12 * 3600 # 12 hours in seconds
  config.reaper_status_logs = true

  config.pre_term = -> (worker) { puts "Worker #{worker.inspect} being killed" }
  config.rolling_pre_term = -> (worker) { puts "Worker #{worker.inspect} being killed by rolling restart" }
end
PumaWorkerKiller.start

If you do not see PumaWorkerKiller debug output during boot, check the following:

1. Cluster Mode: Ensure Puma is running in cluster mode or hybrid mode. PWK only functions if you have multiple workers enabled. Look for * Process workers: X in the boot logs.
2. Frequency: If you have configured a frequency, try reducing it to a very low value to see if it triggers more often.
3. Daemon Mode: If running Puma as a daemon, ensure your configuration is placed in config/puma.rb inside a before_fork block rather than in a standard Rails initializer.

Use the PumaWorkerKiller.config method to set the configuration parameters for the worker killer. This is typically done in your config/puma.rb file. The configuration block yields the PumaWorkerKiller module itself, allowing you to set attributes like RAM limits, check frequency, and lifecycle hooks.

PumaWorkerKiller.config do |config|
  config.ram = 512
  config.frequency = 10
  config.percent_usage = 0.99
  config.pre_term = -> { puts 'Cleaning up...' }
end

To prevent all workers from restarting simultaneously (which can cause downtime), you can enable rolling restarts using PumaWorkerKiller.enable_rolling_restart. This uses the rolling_restart_frequency and rolling_restart_splay_seconds settings to randomize the restart timing across workers.

# Uses configured rolling_restart_frequency and rolling_restart_splay_seconds
PumaWorkerKiller.enable_rolling_restart

# Or provide custom frequency and splay duration
PumaWorkerKiller.enable_rolling_restart(3600, 60.0)

The reap method performs the actual memory check.

1. It checks if workers have already stopped to avoid redundant operations.
2. It calculates the total memory usage of the cluster.
3. If the total memory exceeds @max_ram:
   • It logs an 'Out of memory' message.
   • It identifies the largest_worker (the worker consuming the most memory).
   • It executes the pre_term callback (if provided) passing the largest_worker.
   • It sends a TERM signal to the largest_worker's PID.
4. If memory is within limits and @reaper_status_logs is enabled, it logs the current consumption.

Returns false if workers are already stopped, otherwise returns the result of the logic (implicitly nil or the result of the log/term operations).

# Typically called within a periodic timer or a Puma lifecycle hook
reaper.reap

To begin monitoring and killing workers that exceed memory limits, call PumaWorkerKiller.start. By default, it uses the configured frequency and a reaper instance created from your current configuration. You can optionally pass a custom frequency or a custom reaper instance to the start method.

# Uses default configuration
PumaWorkerKiller.start

# Or provide custom arguments
PumaWorkerKiller.start(5, my_custom_reaper)