Add some further clarifications to the gauge descriptions #61
Conversation
| * puma.running - The number of worker threads currently running. In quiet times, idle threads may be shutdown, but they'll start back up again when traffic arrives | ||
| * puma.backlog - The number of requests that have made it to a worker but are yet to be processed. This will normally be zero, as requests queue on the tcp/unix socket in front of the master puma process, not in the worker thread pool | ||
| * puma.pool_capacity - The number of idle and unused worker threads. When this is low/zero, puma is running at full capacity and might need scaling up | ||
| * puma.running - The number of worker threads currently running. In quiet times, idle threads may be shutdown if min threads is less than max threads, but they'll start back up again when traffic arrives |
There was a problem hiding this comment.
There was a problem hiding this comment.
Hmm. This extra wording is confusing me a little.
Is this saying that if the current config has set min threads to be lower than max threads, then idle threads will eventually terminate until the running threads equals min threads?
There was a problem hiding this comment.
That's right. Thread auto-scaling only takes place when min != max, and the pool will be scaled down to at least min threads when idle. When min == max, the thread count is constant.
| * puma.backlog - The number of requests that have made it to a worker but are yet to be processed. This will normally be zero, as requests queue on the tcp/unix socket in front of the master puma process, not in the worker thread pool | ||
| * puma.pool_capacity - The number of idle and unused worker threads. When this is low/zero, puma is running at full capacity and might need scaling up | ||
| * puma.running - The number of worker threads currently running. In quiet times, idle threads may be shutdown if min threads is less than max threads, but they'll start back up again when traffic arrives | ||
| * puma.backlog - The number of requests that have made it to a worker but are yet to be processed. This will normally be zero if queue_requests is disabled, as requests will only queue on the tcp/unix socket in front of the master puma process, but not in the worker thread pool |
There was a problem hiding this comment.
There was a problem hiding this comment.
interesting. queue_requests is enabled by default though, so does that mean This will normally be zero is typically not true?
It's been a while since I worked with these stats closely, but my recollection is that this value was nearly always 0 in my apps that used cluster mode 🤔
There was a problem hiding this comment.
so does that mean This will normally be zero is typically not true?
Ah yep that wording doesn't make sense anymore.
but my recollection is that this value was nearly always 0 in my apps that used cluster mode 🤔
When queue_requests is enabled, each worker has a reactor thread that is responsible for queuing and read-buffering requests. However, and this was surprising to me as well, when there's a new connection, worker threads try to eagerly read the request off the socket first, and only hand it over to the reactor if it's not ready. I'm trying to change that behavior, but that might explain why your backlog is close to 0, it could just be that your requests are always processed before they can get queued.
| * puma.pool_capacity - The number of idle and unused worker threads. When this is low/zero, puma is running at full capacity and might need scaling up | ||
| * puma.running - The number of worker threads currently running. In quiet times, idle threads may be shutdown if min threads is less than max threads, but they'll start back up again when traffic arrives | ||
| * puma.backlog - The number of requests that have made it to a worker but are yet to be processed. This will normally be zero if queue_requests is disabled, as requests will only queue on the tcp/unix socket in front of the master puma process, but not in the worker thread pool | ||
| * puma.pool_capacity - The number of idle and unspawned worker threads. When this is low/zero, puma is running at full capacity and might need scaling up |
| * puma.max_threads - The maximum number of worker threads that might run at one time | ||
| * puma.percent_busy - The percentage of busy threads calculated as pool capacity relative to max threads | ||
| * puma.percent_busy - The percentage of busy threads, calculated as the complement of the ratio of pool capacity to max threads |
There was a problem hiding this comment.
This seems correct, but .... I worry it's not very clear. (neither was whats on main now). I wonder if it's possible to fit a concise example? Maybe not 🤔
There was a problem hiding this comment.
Hmm I agree, I'll try to think of a more concise way to put it. Also an fyi that you could hook into this new stat once it has been included in a release.
I’ve linked some references below (from puma 5 since it's the min supported version). If the reasoning or accuracy of these changes is still uncertain, please feel free to let me know, and I’d be glad to explain.