Which connection states must be counted when sizing Tomcat maxConnections for production traffic?

Answer to the core question

For a Tomcat 8.5+ NIO or NIO2 connector, maxConnections counts every socket that the connector has accepted. That includes sockets that are actively processing a request and sockets that are idle but kept alive by the HTTP keep‑alive mechanism. In other words, the peak number of concurrent active requests plus the peak number of idle keep‑alive connections must both fit within the maxConnections ceiling.

Confirmed facts from Tomcat’s implementation

• Both NIO and NIO2 connectors treat idle keep‑alive sockets as part of the maxConnections count. They remain counted until the keep‑alive timeout expires or the client closes the socket.
• The APR/native connector follows the same counting logic, but its default maxConnections value changed to 8192 in Tomcat 10.x (previous releases defaulted to Integer.MAX_VALUE).
• Adjusting connectionTimeout only changes how long an idle socket is kept; it does not reduce the number of sockets that are counted against maxConnections.
• Exceeding the operating‑system file‑descriptor limit (ulimit -n) will prevent new sockets from being accepted regardless of maxConnections.

Practical sizing workflow

1. Measure the peak:
   • Deploy the connector with its current configuration.
   • During a representative traffic burst, query the JMX bean org.apache.coyote:type=Connector,port=… for currentConnections and currentThreadsBusy to capture the peak number of sockets and busy threads.
   • Cross‑check with OS tools (e.g., lsof -iTCP -sTCP:LISTEN -P -n | grep java) to verify that the reported currentConnections matches the actual open TCP sockets for the Tomcat process.
2. Separate active vs idle:
   • The currentThreadsBusy value gives the number of sockets actively handling requests.
   • Subtract this from currentConnections to infer the count of idle keep‑alive sockets at that moment.
   • Repeat during different traffic patterns to find the true peak of each.
3. Set maxConnections:
   • Take the maximum of the summed peaks: peakActive + peakIdleKeepAlive.
   • Round up to the next power of two or add a safety margin (e.g., +10–15%) to guard against sudden spikes.
   • Ensure the value does not exceed the OS file‑descriptor limit; if it does, raise the limit with ulimit -n or sysctl.
4. Validate after change:
   • Re‑run the traffic burst and confirm that currentConnections never approaches the new maxConnections value.
   • Monitor for 503 Service Unavailable responses, which indicate that the limit was hit.

What to check next

To fine‑tune the recommendation, it would help to know:

• What is your typical peak concurrent request count?
• What keep‑alive timeout is configured (connectionTimeout and keepAliveTimeout)?
• Are there any proxies or load balancers that might terminate idle connections earlier?

With those details, you can refine the margin and confirm that the chosen maxConnections will accommodate both active and idle traffic in production.