Tuning the ClientHandler/ReverseProxyHandler

The ClientHandler/ReverseProxyHandler communicates as a client to a downstream third-party service or protected application. The performance of the communication is determined by the following parameters:

  • The number of available connections to the downstream service or application.

  • Number of IG worker threads allocated to service inbound requests, and manage propagation to the downstream service or application.

  • The connection timeout, or maximum time to connect to a server-side socket, before timing out and abandoning the connection attempt.

  • The socket timeout, or the maximum time a request is expected to take before a response is received, after which the request is deemed to have failed.

ClientHandler/ReverseProxyHandler Tuning in Web Container Mode

Configure IG in conjunction with the Tomcat container, as follows:

  • For BIO Connector (Tomcat 3.x to 8.x), configure maxThreads in Tomcat to be close to the number of configured Tomcat connections.

    Because IG uses an asynchronous threading model, the numberOfWorkers in ClientHandler/ReverseProxyHandler can be much lower. The asynchronous threads are freed up immediately after the request is propagated, and can service another blocking Tomcat request thread.

    To take advantage of IG's asynchronous thread model, configure Tomcat to use a non-blocking, NIO or NIO2 connector, instead of a BIO connector.

  • For NIO connectors, align numberOfWorkers in IG with maxThreads in Tomcat.

    Because NIO connectors use an asynchronous threading model, the maxThreads in Tomcat can be much lower than for a BIO connector.

To identify the throughput plateau, test in a pre-production performance environment, with realistic use cases. Increment numberOfWorkers from its default value of one thread per JVM core, up to a large maximum value based on the number of concurrent connections.

ClientHandler/ReverseProxyHandler Tuning in Standalone Mode

Configure IG in conjunction with IG's first-class Vert.x configuration, and the vertx property of admin.json. For more information, see "AdminHttpApplication (admin.json)".

Vert.x Options for Tuning
ObjectVert.x OptionDescription

IG (first-class)


The number of Vert.x Verticle instances to deploy. Each instance operates on the same port on its own event-loop thread. This setting effectively determines the number of cores that IG operates across, and therefore, the number of available threads.

Default: The number of cores.



The number of available event-loop threads to be supplied to instances. Specify a value greater than that for gatewayUnits.

Default: 20



The maximum number of connections to queue before refusing requests.


TCP connection send buffer size. Set this property according to the available RAM and required number of concurrent connections.


TCP receive buffer size. Set this property according to the available RAM and required number of concurrent connections.

Vert.x Options for Troubleshooting Performance
ObjectVert.x OptionDescription


blockedThreadCheckInterval and blockedThreadCheckIntervalUnit

Interval at which Vert.x checks for blocked threads and logs a warning.

Default: One second.

maxEventLoopExecuteTime and maxEventLoopExecuteTimeUnit

Maximum time executing before Vert.x logs a warning.

Default: Two seconds.

warningExceptionTime and warningExceptionTimeUnit

Threshold at which warning logs are accompanied by a stack trace to identify causes.

Default: Five seconds.


Log network activity.

Read a different version of :