Product Configurations Guidelines

API Gateway Configurations

You must have the API Gateway's manage user administration functional privilege assigned to configure the watt parameters in API Gateway UI. You can configure the watt parameters in the Watt keys section under 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 Software AG suggests for an optimal performance of 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 API Gateway starts to warn of insufficient available threads. When the percentage of available server threads goes below the value of this property, 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 API Gateway keeps on the file system, including the current server log file. When API Gateway reaches the limit for the number of server log files, API Gateway deletes the oldest archived server log file each time API Gateway rotates the server log. If you set watt.server.log.filesToKeep to 1, API Gateway keeps the current server.log file and no previous server.log files. When API Gateway rotates the server.log, 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, 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 API Gateway for the changes to take effect.

watt.server.serverlogRotateSize

Specifies the file size at which 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 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, 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 API Gateway keeps on the file system for an audit logger that writes to a file. When API Gateway reaches the limit for the number of log files for the audit logger, each time API Gateway rotates the audit log, API Gateway deletes the oldest archived audit log file. If you set watt.server.audit.log.filesToKeep to 1, API Gateway keeps the current audit log file and no previous audit log files for each file-system based audit logger. That is, when API Gateway rotates the audit log for a logger, 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, 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 API Gateway keeps for file-based audit logs and then restart API Gateway, the existing audit logs will not be pruned until 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, API Gateway does not delete the 4 oldest error audit log files immediately after start up. 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 API Gateway for the changes to take effect.

watt.server.audit.logRotateSize

Specifies the file size at which 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 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, 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 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 API Gateway does not retain client keep aliveconnections for a target endpoint. 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 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, 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 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, 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 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, API Gateway disregards the empty trusted authorities list and sends its chain anyway. When set to false, before sending out its certificate chain, API Gateway requires the presentation of trusted authorities list that proves itself trusted.

Recommended value: true

watt.server.url.alias.partialMatching

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

Recommended value: true

When partial matching is enabled, 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 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, 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, API Gateway closes the socket. If a new socket is needed in the pool, API Gateway creates one.

Recommended value: 10000000 uses

Note: Even if the number of connection usages is less than the watt.net.clientKeepaliveUsageLimit parameter, 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 API Gateway for the changes to take effect.

watt.server.rg.internalsocket.timeout

Specifies the length of time, in milliseconds, that 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, 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 API Gateway must ignore the X-Forwarded-For request header while processing the rules in API Gateway server. If this property is set to true, then 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 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

Software AG recommends the following configurations for the Extended settings.

portClusteringEnabled

By default, API Gateway provides synchronization of the port configuration across API Gateway cluster nodes. If you do not want the ports to be synchronized across API Gateway cluster nodes, set the portClusteringEnabled parameter available under Username > Administration >General > Extended settings in API Gateway 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 API Gateway, this property is only for the analytics indices and core data changes are refreshed every 1 second by default.

For changing the refresh interval, go to API Gateway UI -> Administration -> Extended settings -> eventRefreshInterval and change it.

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 API Gateway, Elasticsearch, API 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 API Gateway, Elasticsearch, API 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.

Terracotta Configurations

See Terracotta Server Array Configuration and set the configurations accordingly.

API Data Store (Elasticsearch) Configurations

This section explains the API Data Store configurations. As part of API Data Store configurations, this section covers the connection properties:

Connection properties

This section explains the configurations that are required to make API Gateway connect to desired Elasticsearch cluster located at SAGInstallDirectory\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 SAGInstallDirectory\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 Elastic Search, 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

telemetry.enabled

Disables the telemetry data being sent to elastic server.

Recommended value: false

For more details about Kibana configurations, see Connecting to an External Kibana.