Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add some further clarifications to the gauge descriptions #61

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+5 −5
Open

Add some further clarifications to the gauge descriptions #61

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,14 @@ that puma can provide:

Gauges:

* puma.workers - The number of distinct process running. In single mode this will be 1, in cluster mode the number of worker processes
* puma.workers - The number of distinct processes running. In single mode this will be 1, in cluster mode the number of worker processes
* puma.old_workers - The number of worker processes that are about to be shut down as part of a phased restart. Will normally be 0
* puma.booted_workers - The number of worker processes that are in a booted state
* 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
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://github.com/puma/puma/blob/13e18e8078c800adfc52af687acc1d8de5f3988d/lib/puma/thread_pool.rb#L264

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 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
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://github.com/puma/puma/blob/13e18e8078c800adfc52af687acc1d8de5f3988d/lib/puma/dsl.rb#L699-L715

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 🤔

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 unspawned worker threads. When this is low/zero, puma is running at full capacity and might need scaling up
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

makes sense 👍

* 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
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 🤔

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this new stat just got released in the latest puma

* puma.requests_count - Total number of requests served by this puma since it started

Counters:
Expand Down