Performance Tuning

There are numerous settings which can be used to help optimise the performance of the IBM Application Gateway (IAG) in an environment.


The IAG employs various caches which can be used to improve the performance of the system.

SSL Session Cache

A cache of SSL connections is maintained by the IAG to help reduce the number of SSL sessions which are negotiated and established. The 'ssl-max-entries' advanced configuration entry is used to define the maximum number of entries which are stored in this cache (default: 1048576). For example:

    - stanza: ssl
      entry: ssl-max-entries
      operation: set
      value: [ 1048576 ]

An increase to the SSL cache sizes can cause the IAG memory usage to exceed system limits. The SSL session cache uses about 250 bytes of process memory per entry.

Session Cache

A cache of authenticated user sessions is maintained by the IAG to help reduce the number of authentication requests required by a user. The Session YAML reference contains information on how to adjust the size of the session cache.

An increase to the session cache size can cause the IAG memory usage to exceed system limits. The session cache uses about 7 KB of process memory per entry.

Document Cache

The IAG can cache static web content received from resource servers to increase the performance and response time of requests. By default this caching is disabled, but can be selectively enabled for particular resources. Further information on how to enable and manage the document cache can be found in the Caching Responses page.

Worker threads

The worker_threads YAML configuration entry specifies the number of worker threads that the IAG allocates for handling incoming requests. In most cases, it is not necessary to adjust this configuration entry.

When all worker threads become busy processing requests, thread starvation occurs for new requests and leads to request timeouts, failures, and poor performance. In such cases, increasing the number of worker thread may help to to address the problem.

The following situations may result in a high worker thread usage:

  • A slow back-end Web server can block a worker thread until that server responds. If all of the default worker threads become blocked, thread starvation occurs and the IAG is not able to process any further requests;
  • Slow network connections between browsers and the IAG can result in many worker threads waiting on the completion of send or receive operations;

Detecting worker thread starvation

One way to detect worker threads starvation is to check the IAG container console log. When the soft or hard thread worker limit is reached, a message is generated. The soft and hard worker thread limits for a resource server are controlled by the 'hard-limit' and 'soft-limit' YAML configuration entries. The unit of measure for these limits is percentage of total threads. A configuration value of 100 indicates that a message is generated when all worker threads are in use. When the number of active worker threads reaches the hard limit, and the hard limit is not the maximum value of 100, in addition to generating a message, a '503: Service Unavailable' error is returned to the client. Refer to the Worker Threads YAML reference for further information.

Another way to monitor and evaluate a worker thread starvation situation is to use the IAG active worker thread statistics - 'pdweb.threads'. The Enabling Statistics Gathering page contains information on how to enable statistics gathering. If the number of active and total threads is equal or near equal, increase the number of worker threads, and restart the IAG container.

Other indications that worker thread starvation is occurring includes:

  • Clients receiving timeout errors;
  • Response times are high, yet the CPU utilization of the IAG is low;
  • TCP/IP packet traces indicate that the number of active requests that the reverse proxy is processing is equal to the number of worker threads.

Determining the number of worker threads to use

Processing concurrent requests at peak loads requires a sufficient number of worker threads to handle the expected number of requests. Each worker thread consumes about 450 KB of virtual storage and two TCP/IP sockets. To prevent thrashing, process memory usage should be limited to the available physical memory. The configured number of worker threads must be a balance between available resources, and anticipated request rates for the system.

Persistent Connections

The IAG supports persistent connections between the gateway and a resource server. By enabling this feature the IAG caches a pool of open connections to each resource server for future use.

A new HTTP request results in the IAG retrieving an open connection from the pool, if available. After the request is processed, the open connection is returned to the pool unless either of the following circumstances occur:

  • The configured limit on the pool size is reached;
  • The HTTP response from the resource server includes the 'connection: close' header.

Benefits of persistent connections

The benefits of enabling persistent connections include:

  • Faster response time for requests;
  • Less CPU usage for both the IAG and the junctioned application server.

Therefore, persistent connections can significantly improve IAG performance.



If the resource server is configured to use short connection timeouts, the usefulness of the IAG persistent connection pool is limited.

Security implications of persistent connections

When persistent connections are enabled a single connection can potentially be used by multiple users. This setup might not be appropriate for applications that tie a user identity to an open connection.

If SSL is enabled between the IAG and the resource server, then using persistent connections means that the SSL handshake and establishment is not performed for each request. Multiple requests might reuse a single SSL connection from the IAG to the resource server.

Tuning persistent connections

You can tune the persistent connections between the IAG and a resource server for optimized processing.

The IAG does not impose any upper limit for the size of the persistent connection pool cache. You can set the size of the cache to any number you want. However, there is no point to setting it higher than the number of available worker threads, as that is the maximum number of concurrent connections that the IAG opens to a resource server. Each resource server will maintain its own connection pool.

In order to tune the persistent connection settings:

  1. Calculate the number of cached connections (max_cache_size) for each resource server that requires persistent connections. The value should be the expected number of concurrent requests to each defined server for that resource server. The worker_threads parameter is a reasonable upper limit for each resource server.
  2. Calculate the connection timeout value (connection_timeout) so that it is less than the maximum connection lifetime supported by the resource server. This will ensure that the IAG does not attempt to use connections which have already been closed by the resource server.
  - path: "/app"
    connection_type: "tcp"
      - host: ""
        port: 80
    transparent_path: false
      max_cache_size: 100
      connection_timeout: 5



If the backend connection timeout is less than the IAG persistent connection timeout, then the IAG attempts to use a connection that the backend may have already closed. Such actions can cause requests to fail at the network level. The result of this is additional overhead for the request as the IAG opens a new connection and tries the request again.