Product Configurations Guidelines

API Gateway Configurations

You must have the Manage user administration functional privilege assigned to configure the watt parameters in webMethods API Gateway UI. You can configure the watt parameters in the Watt keys section under webMethods API Gateway UI > Administration > General > Extended settings > Show and hide keys by providing the recommended values. For more information about the extended settings, see Configuring Extended Settings.

Following is the list of WATT properties that you can alter by changing the default value with the recommended value that IBM suggests for an optimal performance of webMethods API Gateway:

watt.server.threadPool

Specifies the maximum number of threads that the server maintains in the thread pool that it uses to run services. If this maximum number is reached, the server waits until services complete and return threads to the pool before running more services.

Recommended value: 600

watt.server.threadPoolMin

Specifies the minimum number of threads that the server maintains in the thread pool that it uses to run services. When the server starts, the thread pool initially contains this minimum number of threads. The server adds threads to the pool as needed until it reaches the maximum allowed, which is specified by the watt.server.threadPool setting.

Recommended value: 200

watt.server.control.serverThreadThreshold

Specifies the threshold at which webMethods API Gateway starts to warn of insufficient available threads. When the percentage of available server threads goes below the value of this property, webMethods API Gateway generates a journal log message indicating the current available thread percentage stating "Available Thread Warning Threshold Exceeded." When you receive this message in the journal log, you can adjust the thread usage to make server threads available.

Recommended value: 20%

watt.server.clientTimeout

Specifies the amount of time in minutes after which an idle user session times out.

Recommended value: 75

watt.server.serverlogFilesToKeep

Specifies the number of server log files that webMethods API Gateway keeps on the file system, including the current server log file. When webMethods API Gateway reaches the limit for the number of server log files, webMethods API Gateway deletes the oldest archived server log file each time webMethods API Gateway rotates the server log. If you set watt.server.log.filesToKeep to 1, webMethods API Gateway keeps the current server.log file and no previous server.log files. When webMethods API Gateway rotates the server.log, webMethods API Gateway does not create an archive file for the previous server log. If you set watt.server.log.filesToKeep to 0, or any value less than 1, webMethods API Gateway keeps an unlimited number of server log files.

Recommended value: 100

Important: If you change the setting of this parameter, you must restart webMethods API Gateway for the changes to take effect.

watt.server.serverlogRotateSize

Specifies the file size at which webMethods API Gateway rolls over the server.log file. Set this property to N[KB|MB|GB], where N is any valid integer. The minimum size at which webMethods API Gateway rotates the server.log file is 33KB. If you use KB as the unit of measure, you must set N to a value greater than or equal to 33. If you do not specify a unit of measure, webMethods API Gateway treats the supplied N value as bytes. In this case, N must be greater than or equal to 32768 to take effect. Do not include any spaces between the integer and the unit of measure.

Recommended value: 10 MB

watt.server.audit.logFilesToKeep

Specifies the number of audit log files, including the current log file for the audit logger, that webMethods API Gateway keeps on the file system for an audit logger that writes to a file. When webMethods API Gateway reaches the limit for the number of log files for the audit logger, each time webMethods API Gateway rotates the audit log, webMethods API Gateway deletes the oldest archived audit log file. If you set watt.server.audit.log.filesToKeep to 1, webMethods API Gateway keeps the current audit log file and no previous audit log files for each file-system based audit logger. That is, when webMethods API Gateway rotates the audit log for a logger, webMethods API Gateway does not create an archive file for the previous audit log. If you set watt.server.audit.logFilesToKeep to 0, or any value less than 1, webMethods API Gateway keeps an unlimited number of audit log files.

Recommended value: 100

The watt.server.audit.logFilesToKeep parameter affects only the audit loggers configured to write to a file. The parameter does not affect audit loggers configured to write to a database nor does it affect the FailedAuditLog.

If you reduce the number of logs that webMethods API Gateway keeps for file-based audit logs and then restart webMethods API Gateway, the existing audit logs will not be pruned until webMethods API Gateway writes to the audit log. For example, if the error logger writes to a file and you reduce the number of log files to keep from 10 to 6, webMethods API Gateway does not delete the 4 oldest error audit log files immediately after start up. webMethods API Gateway deletes the 4 oldest error audit logs after the error logger writes to the error audit log.

Important: If you change the setting of this parameter, you must restart webMethods API Gateway for the changes to take effect.

watt.server.audit.logRotateSize

Specifies the file size at which webMethods API Gateway rolls over the audit log for a logger that writes to a file. Set this property to N[KB|MB|GB], where N is any valid integer. The minimum size at which webMethods API Gateway rotates an audit log is 33KB. If you use KB as the unit of measure, you must set N to a value greater than or equal to 33. If you do not specify a unit of measure, webMethods API Gateway treats the supplied N value as bytes. In this case, N must be greater than or equal to 32768 to take effect. Do not include any spaces between the integer and the unit of measure.

Recommended value: 10MB

The watt.server.audit.logRotateSize parameter affects only the audit loggers configured to write to a file. The parameter does not affect audit loggers configured to write to a database.

Important: If you change the setting of this parameter, you must restart webMethods API Gateway for the changes to take effect.

watt.net.maxClientKeepaliveConns

Sets the default number of client keep alive connections to retain for a given target endpoint.

The default is 0, which indicates that webMethods API Gateway does not retain client keep aliveconnections for a target endpoint. webMethods API Gateway creates a new socket for each request.

Recommended value: 500

This benefits in situations where the frequency and number of concurrent requests to a given target endpoint are high. In situations where this is not the case, idle sockets will become stale and inoperable, resulting in unexpected exceptions such as the following:

[ISC.0077.9998E] Exception --> org.apache.axis2.AxisFault: Broken pipe

watt.server.revInvoke.proxyMapUserCerts

Specifies whether an webMethods API Gateway server is to perform client authentication itself in addition to passing authentication information to the Internal Server for processing.

Recommended value: true

If it is set to true, webMethods API Gateway rejects all anonymous requests (no certificate and no username or password supplied), even if the request is for an unprotected service on the Internal Server.

watt.security.ssl.cacheClientSessions

Controls whether webMethods API Gateway reuses previous SSL session information (for example, client certificates) for connections to the same client.

Recommended value: true

When this property is set to true, webMethods API Gateway caches and reuses SSL session information. For example, set this property to true when there are repeated HTTPS requests from the same client.

watt.security.ssl.client.ignoreEmptyAuthoritiesList

Specifies whether an webMethods API Gateway acting as a client sends its certificate chain after a remote SSL server returns an empty list of trusted authorities. When set to true, webMethods API Gateway disregards the empty trusted authorities list and sends its chain anyway. When set to false, before sending out its certificate chain, webMethods API Gateway requires the presentation of trusted authorities list that proves itself trusted.

Recommended value: true

watt.server.url.alias.partialMatching

Specifies whether webMethods API Gateway enables partial matching on URL aliases. If you set this server configuration parameter to true and define a URL alias in webMethods API Gateway Administrator, webMethods API Gateway enables partial matching on URL aliases.

Recommended value: true

When partial matching is enabled, webMethods API Gateway considers an alias a match if the entire alias matches all or part of the request URL, starting with the first character of the request URL path.

Important: If you change the setting of this parameter, you must restart webMethods API Gateway for the changes to take effect.

watt.net.clientKeepaliveUsageLimit

Specifies the maximum number of usages for a socket in a client connection pool. Before returning a socket to the pool, webMethods API Gateway compares the number of times the socket has been used to send a request to the watt.net.clientKeepaliveUsageLimit value. If the socket usage count is greater than the watt.net.clientKeepaliveUsageLimit value, then Integration Server does not return the socket to the pool. Instead, webMethods API Gateway closes the socket. If a new socket is needed in the pool, webMethods API Gateway creates one.

Recommended value: 10000000 uses

Note: Even if the number of connection usages is less than the watt.net.clientKeepaliveUsageLimit parameter, webMethods API Gateway closes the connection if the connection has exceeded the age limit set by the watt.net.clientKeepaliveAgingLimit server configuration parameter.

The watt.net.clientKeepaliveUsageLimit parameter applies only if watt.net.maxClientKeepaliveConns is set to a value greater than 0.

Important: If you change the setting of this parameter, you must restart webMethods API Gateway for the changes to take effect.

watt.server.rg.internalsocket.timeout

Specifies the length of time, in milliseconds, that webMethods API Gateway server allows a client request to wait for a connection to the Internal Server before terminating the request with an HTTP 500 Internal Server Error. If a connection to the Internal Server becomes available within the specified timeout period, Enterprise Gateway Server forwards the request to the Internal Server. If a connection does not become available before the timeout elapses, webMethods API Gateway returns a HTTP 500-Internal Server Error to the requesting client and writes the following message to the error log: Enterprise Gateway port {port_number} is unable to forward the request to Internal Server because there are no Internal Server connections available. This is applicable for paired deployment with reverse invoke setup.

Recommended value: 300 ms

watt.server.enterprisegateway.ignoreXForwardedForHeader

Specifies whether webMethods API Gateway must ignore the X-Forwarded-For request header while processing the rules in webMethods API Gateway server. If this property is set to true, then webMethods API Gateway ignores the X-Forwarded-For request header and considers the proxy server's IP address as the host IP address. If the property is set to false, then webMethods API Gateway obtains the actual host IP address from the X-Forwarded-For request header. This is applicable for paired deployment with reverse invoke setup.

Recommended value: false

API Gateway Extended Settings

The following configurations are recommended for the Extended settings. You can configure the extended settings under webMethods API Gateway UI > Administration > General > Extended settings > Show and hide keys by providing the recommended values. For more information about the extended settings, see Configuring Extended Settings.

portClusteringEnabled

By default, webMethods API Gateway provides synchronization of the port configuration across webMethods API Gateway cluster nodes. If you do not want the ports to be synchronized across webMethods API Gateway cluster nodes, set the portClusteringEnabled parameter to false.

Recommended value: false

For more details about Ports Configuration, see Ports Configuration.

eventsRefreshInterval

Specifies the frequency at which Elasticsearch should refresh its own indices. In Elasticsearch, an operation that updates the data, which is visible in search is called a refresh. Any document that is modified or inserted appears in search operations only after the index is refreshed. Specifying a lesser value to this parameter overloads Elasticsearch with frequent indexing when there is a large volume of data. Henceforth, it is recommended to specify a higher value to this parameter.

Note: In webMethods API Gateway, this property is only for the analytics indices and core data changes are refreshed every 1 second by default.

Recommended value: 10s

events.collectionPool.maxThreads

Specifies the maximum number of threads to be used for the event data collection pool.

Recommended value: 40

events.collectionPool.minThreads

Specifies the minimum number of threads to be used for the event data collection pool.

Recommended value: 2

events.collectionQueue.size

Specifies the size of the collection queue to be used during event data collection. When events like transaction, error events, and performance metrics are generated during API invocations, they are put in the collection queue for further processing. Each thread in the collection pool is assigned a task of collecting these events and processing them for sending to the desired destinations such as webMethods API Gateway, Elasticsearch, webMethods Developer Portal, and so on.

If the queue capacity is reached, then any additional event data would be lost. To avoid the loss of data, it is recommended to increase this size when there is an increase in incoming traffic. You should choose the value based on the payload size of the transactions as queue size and payload size determine the memory occupied by the queue.

events.reportingPool.maxThreads

Specifies the maximum number of threads to be used for the event data reporting pool.

Recommended value: 24

events.reportingPool.minThreads

Specifies the minimum number of threads to be used for the event data reporting pool.

Recommended value: 4

events.reportingQueue.size

Specifies the size of the reporting queue to be used during event data reporting. When events like transaction, error events, and performance metrics are generated during API invocations, they are put in the collection queue for further processing. Each thread in the collection pool is assigned a task of collecting these events, processing them and put in the reporting queue for sending to the desired destinations such as webMethods API Gateway, Elasticsearch, webMethods Developer Portal, and so on.

If the reporting queue capacity is reached, then any additional event data would be lost. To avoid the loss of data, it is recommended to increase this size when there is an increase in incoming traffic. You should choose the value based on the payload size of the transactions as queue size and payload size determine the memory occupied by the queue.

Elasticsearch Configurations

This section explains the Elasticsearch configurations. As part of external Elasticsearch configurations, this section covers the connection properties:

Connection properties

This section explains the configurations that are required to make webMethods API Gateway connect to desired Elasticsearch cluster located at InstallDir\IntegrationServer\instances\instance_name\Packages\WmAPIGateway\config\resources\elasticsearch\config.properties. You must change the configurations of the following properties and tune it as per the following guidelines. You can modify the configurations according to your business requirements.

pg.gateway.elasticsearch.hosts = Elasticsearch Service endpoint, that is localhost:9240
pg.gateway.elasticsearch.http.connectionTimeout = 10000
pg.gateway.elasticsearch.http.socketTimeout = 30000
pg.gateway.elasticsearch.sniff.enable = false
pg.gateway.elasticsearch.http.maxRetryTimeout = 100000

Kibana Configurations

This section explains the configuration changes for Kibana in kibana.yml file located at InstallDir\profiles\IS_instance_name\apigateway\dashboard\configor Kibana_InstallDirectory\config. You must change the configurations of the following properties and tune it as per the following guidelines. You can modify the configurations according to your business requirements.

elasticsearch.requestTimeout property

This property specifies Kibana’s wait time to receive a response from Elasticsearch, in seconds, for retries after which it times out.

Recommended value: 90 seconds

elasticsearch.hosts

Specifies the URLs of the Elasticsearch instance to use for all your queries.

[http://hostname:port]

For example,

elasticsearch.hosts: ["http://localhost:9240"]

telemetry.enabled

Disables the telemetry data being sent to Elasticsearch server.

Recommended value: false