123456789_123456789_123456789_123456789_123456789_

Control/Status Server

Puma has a built-in status and control app that can be used to query and control Puma.

$ puma --control-url tcp://127.0:9293 --control-token foo

Puma will start the control server on localhost port 9293. All requests to the control server will need to include a control token (in this case, token=foo) as a query parameter. This allows for simple authentication. Check out App::Status orstatus.rb to see what the status app has available.

You can also interact with the control server via pumactl. This command will restart Puma:

$ pumactl --control-url 'tcp://127.0.0.1:9293' --control-token foo restart

To see a list of pumactl options, use pumactl --help.

Accessing stats

Stats can be accessed in two ways:

control server

$ pumactl stats or GET /stats

Puma.stats

Puma.stats produces a JSON string. Puma.stats_hash produces a ruby hash.

in single mode

Invoke Puma.stats anywhere in runtime, e.g. in a rails initializer:

# config/initializers/puma_stats.rb

Thread.new do
  loop do
    sleep 30
    puts Puma.stats
  end
end

in cluster mode

Invoke Puma.stats from the master process

# config/puma.rb

before_fork do
  Thread.new do
    loop do
      puts Puma.stats
      sleep 30
    end
  end
end

Explanation of stats

Puma.stats returns different information and a different structure depending on if Puma is in single vs. cluster mode. There is one top-level attribute that is common to both modes:

single mode and individual workers in cluster mode

When Puma runs in single mode, these stats are available at the top level. When Puma runs in cluster mode, these stats are available within the worker_status array in a hash labeled last_status, in an array of hashes where one hash represents each worker.

cluster mode

worker status

Examples

Here are two example stats hashes produced by Puma.stats:

single

{
  "started_at": "2021-01-14T07:12:35Z",
  "backlog": 0,
  "running": 5,
  "pool_capacity": 5,
  "max_threads": 5,
  "requests_count": 3
}

cluster

{
  "started_at": "2021-01-14T07:09:17Z",
  "workers": 2,
  "phase": 0,
  "booted_workers": 2,
  "old_workers": 0,
  "worker_status": [
    {
      "started_at": "2021-01-14T07:09:24Z",
      "pid": 64136,
      "index": 0,
      "phase": 0,
      "booted": true,
      "last_checkin": "2021-01-14T07:11:09Z",
      "last_status": {
        "backlog": 0,
        "running": 5,
        "pool_capacity": 5,
        "max_threads": 5,
        "requests_count": 2
      }
    },
    {
      "started_at": "2021-01-14T07:09:24Z",
      "pid": 64137,
      "index": 1,
      "phase": 0,
      "booted": true,
      "last_checkin": "2021-01-14T07:11:09Z",
      "last_status": {
        "backlog": 0,
        "running": 5,
        "pool_capacity": 5,
        "max_threads": 5,
        "requests_count": 1
      }
    }
  ]
}

Monitoring

*puma-status — Monitor CPU/Mem/Load of running puma instances from the CLI