Throttle Jama REST/SOAP API Requests - 8.0 and above

By Steve posted 04-29-2016 15:04

Jama provides an option to help system admins protect their Jama servers. The system
can stop aggressive integrations from overwhelming the CPU and degrading overall system performance by throttling the threads available and queuing API requests.

This option is configurable to fit the CPU cores available and requires a restart to enable. The
setting for threads will not reserve CPU cores for API requests, just that the requests will not be able to exceed the configured value, sparing CPU for other activities.

API calls are not throttled by default and configuring this feature will likely
require existing integrations to be updated.


The parameters
can be configured by updating the default values available within the admin
console used to manage Jama installs and upgrades. Customers using throttling for SOAP in 2015.x will need to make updates.

Note: If an invalid value is
specified for any of these settings (ex: -1), throttling will instead revert to
the default value. This will be indicated in the contour.log

While technically throttling is enabled by
default and can not be disabled, the default settings are set so high that in
effect there is no throttling happening.

Sets amount of API requests the server will process at once. A value of 0 will stop the application from accepting requests.
Recommended Value: No more than half of the available cores.
Failure Message: No requests allowed
REST Failure Status: 429
SOAP Failure Status: 500

Sets amount of API requests that can be queued up when the concurrentLimit is reached. Once full, new requests will be rejected until space is available in the queue.
Recommended Value: 50
Failure Message: Too many requests were waiting
REST Failure Status: 429
SOAP Failure Status: 500

The length of time (in milliseconds) that a request can be in the queue before it is considered stale.
Recommended Value: 30000 (30 seconds)
Failure Message: Request timed out while waiting
REST Failure Status: 429
SOAP Failure Status: 500

Sample SOAP Fault Response
Once any of the thresholds have been met the system will respond with a SOAP fault.

<soap:Envelope xmlns:soap="”>;
<faultstring>Request timed out while waiting</faultstring>

Throttling messages will be logged to the contour.log file. Circumstances that lead to a request
being rejected due to throttling (such as too many requests in the queue) will
result in an error message similar to the following:

2016-01-18 18:35:58,583 ERROR http-apr-8080-exec-4
jamatenant_qa5256 [com.jamasoftware.contour.soap.v3.ContourSoapServiceAdvice] –
Error executing SOAP method "com.jamasoftware.contour.soap.v3.ContourSoapServiceImpl.getItemsFromFilter",
Message: "Too many requests were waiting", Re-throw.

2016-01-18 18:35:58,587 WARN http-apr-8080-exec-4
jamatenant_qa5256 [org.apache.cxf.phase.PhaseInterceptorChain] – Application
has thrown exception, unwinding now org.apache.cxf.interceptor.Fault: Too many requests
were waiting  

You can optionally enable DEBUG logging on the following packages:

  • com.jamasoftware.contour.soap

The debug logging will let you know what the concurrent count and wait count are at
as each request goes in and out of the system.