{{ result.summaryTitle }}
{{ result.primaryDisplay }}
{{ result.secondaryText }}
{{ badge.label }}
Shown in table, chart, and JSON exports so this capacity check stays traceable.
Choose the closest queue policy; the math remains local and deterministic.
Use the busiest recent interval when assessing production saturation.
threads
For fixed pools this usually equals the maximum; for elastic pools it can be lower.
threads
Use the configured maxPoolSize, worker cap, or autoscaler ceiling.
threads
Queue growth while active threads are high is the clearest saturation warning.
tasks
Set 0 for direct handoff; for unbounded queues, enter the operational alert threshold.
tasks
Use a peak-window rate instead of a full-day average when traffic is bursty.
tasks/s
Use measured wall time per task while it owns a pool thread.
ms
Production pools often need headroom below 100% to avoid queue amplification.
%
Leave 0 for measured average; raise it for retries, spikes, or batch fan-out.
%
Use 0 when this metric is unavailable; the review table will mark it as not measured.
ms
Used only for the wait-latency review row and JSON export.
ms
Use 0 to skip CPU advisory; high thread-to-core ratios can still be normal for I/O-heavy pools.
cores
Used for the saturation review recommendation; it does not hide rejected work.
Longer windows help show slow queue growth; shorter windows emphasize imminent overflow.
min
MetricValueDetailCopy
{{ row.metric }}{{ row.value }}{{ row.detail }}
CheckStateRecommendationCopy
{{ row.check }}{{ row.state }}{{ row.recommendation }}
ScenarioArrivalTask timeThreads at targetMax-thread useQueue trendOperator noteCopy
{{ row.scenario }}{{ row.arrival }}{{ row.taskTime }}{{ row.threadsAtTarget }}{{ row.maxThreadUse }}{{ row.queueTrend }}{{ row.note }}
Tags: Devops, Devtools
Export to PDF Fullscreen
Customize
Advanced
:

Thread pool saturation happens when a worker pool no longer has enough execution capacity, queue space, or latency headroom for the work being submitted. A pool can look acceptable while most workers are busy, then become unstable as soon as queued tasks rise faster than workers can finish them. The result often appears as tail latency, request timeouts, caller backpressure, task rejection, or silent dropped work, depending on the runtime and rejection policy.

Capacity pressure comes from more than the number of active threads. Arrival rate, average task time, current pool size, maximum thread cap, queue depth, queue limit, burst reserve, and observed queue wait all change the conclusion. A pool with 70 active threads out of 100 can still be at risk if tasks arrive faster than the current service ceiling and the queue will hit its alert boundary in seconds.

Thread pool saturation model with arrivals, active threads, waiting queue, maximum cap, and pressure inputs.

Thread-pool planning is also sensitive to task shape. CPU-bound work, blocking I/O, database waits, remote API calls, retry loops, and synchronized sections can hold a worker for very different lengths of time. Average task time should represent wall-clock time while the task owns a pool thread, not only CPU time inside application code.

The calculation is a planning estimate, not a live profiler. It assumes a steady arrival rate, one priority class, one average task duration, no task abandonment, and a fixed capacity policy during the modeled interval. Use it to decide whether a pool needs more evidence, smaller tasks, a queue limit change, or a safer scaling plan before changing production settings.

Technical Details:

Thread pool demand can be estimated from arrival rate and service time. If tasks arrive at 600 per second and each task holds a thread for 100 ms, the work requires about 60 concurrent threads before any reserve is added. That Little-style relationship is useful because it converts traffic and task duration into the thread count needed to avoid steady queue growth.

The service ceiling is the number of usable worker threads divided by average task time. A 96-thread pool with 140 ms average task time can complete about 685.7 tasks per second at the current size. If modeled arrivals exceed that ceiling, the queue grows. If the maximum thread cap has a higher ceiling, the pool may still recover after expansion, but the queue can still create latency or rejection risk before the larger capacity takes effect.

Queue policy changes how pressure should be read. A Java bounded-queue model treats finite maximum threads and finite queue capacity as the saturation boundary. A fixed-size worker pool normally sets current and maximum threads to the same value. A direct-handoff model has no waiting queue, so overload turns into immediate handoff or rejection pressure. An unbounded-queue model uses the queue capacity field as an operational alert threshold because the queue itself may not stop growth.

Formula Core:

The core calculation compares modeled demand with current capacity, maximum capacity, queue headroom, and the selected utilization target.

Amodeled = Abase×(1+burst reserve percent100) S = average task ms1000 Dthreads = Amodeled×S Ccurrent = current pool sizeS Cmax = maximum threadsS queue growth at current size = Amodeled-Ccurrent threads at target = ⌈Dthreadstarget utilization⌉
Quantity Meaning Practical reading
Active thread utilization Active threads divided by current pool size. High values mean little immediate execution headroom even before queue growth is checked.
Queue pressure Queued tasks divided by the finite queue limit or alert threshold. Direct handoff has no queue; any waiting work is treated as full queue pressure.
Modeled demand concurrency Modeled arrival rate multiplied by average task time in seconds. This is the Little-style thread demand before utilization reserve is applied.
Current service ceiling Current pool size divided by average task time. If arrivals are higher, the current pool size grows the queue.
Max service ceiling Maximum threads divided by average task time. If demand exceeds this ceiling, scaling the pool alone cannot keep up.
Target utilization budget Demand concurrency divided by maximum threads at the selected target utilization. Values at or above 100% mean the target headroom cannot be met under the current max-thread cap.
P95 queue wait pressure Observed P95 queue wait divided by the queue wait target. Queue wait can expose user-visible saturation even when thread counts look below hard limits.

Status Rules:

Status Rule How to read it
saturated Active utilization is at least 100%, queue pressure is at least 100%, max-thread demand is at least 100%, or the current queue reaches its alert boundary within 60 seconds while growing. Expect rejected work, blocked submitters, fast queue growth, or visible latency unless demand or task time falls.
near saturation Active utilization is at least 90%, queue pressure is at least 80%, target budget use is at least 100%, wait pressure is at least 100%, or the queue is growing but not inside the saturated horizon. The pool still has some modeled room, but the next burst, slow dependency, or retry wave can remove it quickly.
healthy headroom None of the saturated or near-saturation rules are true. The entered values fit the current model, but production metrics should still agree before reducing capacity.

Rejection policy does not change the arithmetic. It changes the operational consequence after finite thread and queue capacity are exhausted. Abort or reject exposes failure quickly. Caller-runs behavior slows submitters and can create backpressure. Discard behavior can hide overload by dropping work. Blocking submitters can protect the queue while risking request-thread starvation upstream.

Input checks stop impossible models. Active threads cannot exceed current pool size, maximum threads must be greater than or equal to current pool size, average task time and wait target must be positive, and target utilization must be between 1% and 99%. Queue capacity can be zero for direct handoff, and P95 queue wait can be zero when the metric is not available.

Everyday Use & Decision Guide:

Start with one executor, worker group, or queue at a time. Enter a pool label that matches dashboards or incident notes, then choose the runtime model that best matches how tasks wait. Use Java bounded queue for a finite work queue and max-pool cap, Fixed-size worker pool when current and maximum thread counts are effectively the same, Direct handoff / no queue when submissions must meet an idle worker, and Unbounded queue with alert threshold when the queue needs an operator-defined warning line.

Use the busiest recent interval for Arrival rate, not a full-day average. Pair it with Average task time measured as wall time while a task owns a thread. If the workload blocks on databases, storage, HTTP calls, locks, or sleeps, include that waiting time because the worker cannot run another task during it.

  • Use Burst reserve for retries, deploy fan-out, batch spikes, reconnect storms, or traffic bursts above the measured rate.
  • Use Target utilization as the planned steady upper bound; values below 100% leave room for tail latency and measurement error.
  • Use P95 queue wait when metrics or tracing show time spent waiting before a task starts.
  • Use Queue wait target as the wait threshold that would trigger operator concern.
  • Use CPU cores only as an advisory for thread-to-core ratio; high ratios can be reasonable for blocking I/O and poor for CPU-bound work.
  • Use Chart window to show whether the queue fills quickly or drains across the interval that matters for an incident or load test.

The first read should be the summary pressure percentage and badges, then the Pool Saturation rows. A high Threads at target value points to a max-thread gap or a task-time problem. A growing Queue trend at current size means the current pool cannot keep up with the modeled arrival rate. The Saturation Review tab turns those signals into capacity cautions, including wait percentile, rejection policy, and CPU advisory rows.

Do not treat a green result as permission to raise or lower thread counts by habit. Compare the result with executor metrics, rejected-task counts, oldest queue age, downstream latency, CPU run time, lock contention, and load-test behavior. If the model and production signals disagree, fix the input window or task-time measurement before acting on the recommendation.

Step-by-Step Guide:

Build the model from measured pool state first, then add reserves and policy details after the plain calculation makes sense.

  1. Enter Pool label so tables and JSON identify the executor, worker group, or queue being reviewed.
  2. Choose Runtime model. For a fixed pool, set Current pool size and Maximum threads to the same value unless the runtime can actually grow.
  3. Enter Active threads, Current pool size, Maximum threads, Queued tasks, and Queue capacity. The summary should update as soon as the values are valid.
  4. Enter Arrival rate in tasks per second and Average task time in milliseconds. These two fields drive modeled demand concurrency and service ceilings.
  5. Open Advanced and set Target utilization, Burst reserve, P95 queue wait, Queue wait target, CPU cores, Rejection policy, and Chart window when those details are available.
  6. If the red input alert appears, fix the named field before reading the result. For example, active threads cannot exceed current pool size, and maximum threads must be greater than or equal to current pool size.
  7. Read Pool Saturation for normalized metrics, then Saturation Review for warnings and recommendations.
  8. Use Capacity Scenarios, Pool Boundary Map, and Queue Fill Curve to compare burst reserve, slower task time, current-size behavior, and max-thread behavior before copying JSON into a review note.

Interpreting Results:

The pressure percentage is the maximum of active thread utilization, queue pressure, target utilization budget use, and P95 wait pressure when wait data is entered. That makes the headline intentionally conservative. A pool with moderate active usage can still show high pressure when modeled demand exceeds the selected target budget or when queue wait is already above target.

Signal Read it as Check next
Active thread utilization Current execution occupancy. If it is near or at 100%, inspect task time, blocking calls, and CPU run time before relying on queue capacity.
Queue pressure How much of the finite queue or alert threshold is already consumed. At 80% or higher, confirm rejection policy and alert timing before adding more producers.
Target utilization budget Whether demand fits under the max-thread cap after the target utilization reserve. At 100% or higher, reduce task time, lower arrivals, increase max threads, or relax the target only after testing.
Queue trend at current size The net growth or drain rate using current pool size. A positive rate means the current pool grows the queue while conditions stay the same.
Queue trend at max size The net growth or drain rate if the pool reaches maximum threads. A positive rate at max size means thread growth cannot solve the offered load.
P95 queue wait High-percentile waiting time before execution starts. If it exceeds the wait target, treat it as user-visible saturation even when counts look tolerable.

A large thread count does not prove the pool has enough capacity. If task time rises, demand concurrency rises with it. A service that uses 80 threads at 100 ms per task may need about twice as many threads at 200 ms per task for the same arrival rate and target utilization.

A low queue depth does not prove the pool is safe either. Direct handoff can fail without a visible backlog, and bounded queues can stay small while callers block or tasks are rejected. Match the result with runtime metrics for accepted tasks, rejected tasks, queue wait, submit latency, and downstream health.

Worked Examples:

Bounded queue under burst pressure

The default-style run uses api-worker, Java bounded queue, 76 active threads, a current pool size of 96, 128 maximum threads, 420 queued tasks, a 1,000 task queue capacity, 620 tasks/s arrival rate, 140 ms average task time, 80% target utilization, 20% burst reserve, and 180 ms P95 queue wait against a 250 ms target. Modeled arrival load becomes 744 tasks/s and demand concurrency becomes 104.2 threads. Current service ceiling is about 685.7 tasks/s, so Queue trend at current size grows by about 58.3 tasks/s and reaches the alert boundary in about 10 seconds. The summary reads as saturated even though active thread utilization is only 79.2%.

Direct handoff with no queue cushion

A direct-handoff pool has 40 active threads, 40 current threads, 40 maximum threads, no queue, 900 tasks/s arrivals, and 35 ms average task time. Demand concurrency is 31.5 threads, so raw max-thread use is 78.8%, but active utilization is already 100% and the target utilization budget at 70% needs 46 threads. The result is saturated because no queued buffer exists and the selected target headroom cannot be met.

Maximum threads still cannot drain demand

A slow dependency raises average task time to 160 ms while arrivals reach 900 tasks/s plus a 10% burst reserve. With 96 active threads, 96 current threads, 128 maximum threads, 980 queued tasks, and a 1,000 task queue capacity, modeled demand is 158.4 threads. Demand versus max threads becomes critical because max-thread demand is 123.8%, and Queue trend at max size still grows by about 190 tasks/s. Increasing only the current pool size cannot solve that load.

Input check catches an impossible pool state

If Active threads is set to 120 while Current pool size is 96, the alert shows Active threads cannot exceed current pool size. The result tables switch to input issues instead of capacity rows. Fix the pool size or active count from executor metrics before using Pool Saturation, charts, or JSON.

FAQ:

Should I use average traffic or peak traffic?

Use the sustained peak interval that the pool must survive. Daily averages can hide bursty submissions, retry waves, or batch fan-out, and Burst reserve is available when the chosen interval still needs extra headroom.

Why can the result be saturated when active threads are below 100%?

Active threads show current occupancy only. The result can still be saturated when queue pressure is at its boundary, modeled demand exceeds the max-thread cap, or the queue is growing fast enough to hit the alert boundary within 60 seconds.

What value should I use for average task time?

Use measured wall time from task start to task finish while the task owns a pool thread. Include blocking database calls, remote waits, sleeps, lock waits, and retry work because they prevent that worker from executing another task.

How should I model an unbounded queue?

Choose Unbounded queue with alert threshold and enter the queue depth that should trigger operator concern in Queue capacity. The result treats that value as an alert boundary rather than a hard runtime limit.

Why does rejection policy matter if the math stays the same?

The same capacity shortfall has different consequences. Abort / reject exposes failed submissions, Caller runs / backpressure slows submitters, Discard can hide lost work, and Block submitter can move saturation upstream.

Where does the calculation run?

The calculation runs in the browser from the values entered on the page. Treat pool labels, copied tables, downloaded charts, and JSON as operational records when they include private system names or incident details.

Glossary:

Active threads
Workers currently executing tasks inside the pool.
Queue pressure
Queued tasks compared with the finite queue capacity or alert threshold.
Demand concurrency
The thread demand estimated from modeled arrival rate multiplied by average task time.
Service ceiling
The task completion rate implied by a thread count and average task time.
Target utilization
The planned maximum steady worker occupancy after keeping headroom for bursts and latency.
Rejection policy
The runtime behavior after finite thread and queue capacity can no longer accept work.

References: