How to change the process name of your Ruby script as shown by `top` and `ps`

Whenever you run a program on linux or OSX, it runs inside of a process. And every process has a name. The name is what you see when you run a command like ps or top, or htop.

htop shows the process names in the rightmost column.

Default Process Names Can Suck

By default a process's name is derived from the executable file name containing the program you're running. This works out nicely for most executables. After all, it makes sense that when you run "less", its process name should be "less."

But the default process names are less helpful when you have a Ruby script that you're running from the command line. In the example below, I'm running a ruby script that sleeps for five seconds. If I simultaneously run "ps" in another terminal window, I see that the process name for my sleeper is "ruby sleep_5_seconds.rb". If I were to add command line arguments, those would show up in the process name as well. This would make it difficult to refer to the process by name.

The full ruby command is listed as the process name

How to Change the Process Name

Fortunately you can change the name of the current process easily with Ruby. Here's our updated script. It now sets its process name to "sleeper."

# `Process.setproctitle()` is in Ruby >= 2.1
# For earlier versions of Ruby, you can use
#   $PROGRAM_NAME = "sleeper"
# or 
#   $0 = "sleeper"

Process.setproctitle("sleeper")
sleep 5

Now, when we run the program and use ps to display its title, we get "sleeper"

Changing the process title in Ruby changes the output of ps and top

But even better, we can now easily refer to the process by name. Suppose I get tired of waiting for my sleeper to sleep. I can kill it using the command killall sleeper   .

You can use the killall command to terminate processes by name

Displaying Server Status via Process Name

One interesting use of our new ability to change process titles is to display status information for long running processes. If you've ever run Unicorn, this should look familiar:

\-+= 27185 deply unicorn master -c simple_unicorn_config.rb -l0.0.0.0:8080
   |--- 27210 deply unicorn worker[0] -c simple_unicorn_config.rb -l0.0.0.0:8080
   |--- 27211 deply unicorn worker[1] -c simple_unicorn_config.rb -l0.0.0.0:8080
   |--- 27212 deply unicorn worker[2] -c simple_unicorn_config.rb -l0.0.0.0:8080
   |--- 27213 deply unicorn worker[3] -c simple_unicorn_config.rb -l0.0.0.0:8080

It's an instance of Unicorn with four child processes. Just as with our sleep_5_seconds.rb example, the process names just show the commands used to launch the processes.

It might be useful for the status lines to display if the worker is busy or idle. Something like this:

\-+= 27185 deply unicorn master -c simple_unicorn_config.rb -l0.0.0.0:8080
   |--- 27210 deply unicorn worker[0] -c simple_unicorn_config.rb -l0.0.0.0:8080 BUSY
   |--- 27211 deply unicorn worker[1] -c simple_unicorn_config.rb -l0.0.0.0:8080
   |--- 27212 deply unicorn worker[2] -c simple_unicorn_config.rb -l0.0.0.0:8080
   |--- 27213 deply unicorn worker[3] -c simple_unicorn_config.rb -l0.0.0.0:8080 BUSY

You could actually do this pretty easily with a Rack middleware. Here's an example of what that might look like:

class UpdateProcessTitle
  def initialize(app)
    @app = app
  end

  def call(env)
    title = $0
    $0 = $0 + " BUSY"
    status, headers, body = @app.call(env)
    $0 = title
    [status, headers, body]
  end
end

I have no idea of the performance implications of setting the process title on every web page request. So take this all with a grain of salt. But still, it's a pretty cool idea.

If you'd like to see a more advanced implementation of this idea - one that's actually been used in production - check out Thomas Varaneckas' great blog post on Overriding Unicorn Worker Process Names.