Monitoring API Gateway
As part of application monitoring, you can monitor the state, that is the cluster status and console access of API Gateway along with the resources.
How do I monitor the health of API Gateway?
Prerequisites:
You must have a valid
API Gateway user credential for using the Readiness Probe, Runtime Service Health Probe, and Administration Service Health Probe.
All the node level probes must be setup to target the local instance, typically, localhost.
Software AG recommends to set up a dedicated port for monitoring with an appropriate private thread pool.
Readiness Probe at Node-Level
To monitor the readiness of API Gateway, that is to check if the traffic-serving port of a particular API Gateway node is ready to accept requests, use the following REST endpoint:
GET /rest/apigateway/health
The following table shows the response code and the description.
Response | Description |
200 OK | Readiness check is successful. Readiness probe continues to reply OK if API Gateway remains in an operational state to serve the requests. |
500 Internal server error | Readiness check failed and denotes a problem. |
timeout or no response as the request did not reach the probe | Several factors can contribute to the delay when the Readiness Probe initiates, which may result in the timeout errors. To know the reasons for timeout errors, see
Causes for timeout errors for more information. |
Note:
As this is a Readiness Probe and only the response status code is essential, by design, JSON payload is not returned in the response for both success and failure scenarios.
Runtime Service Health Probe at Node-Level
To monitor the runtime service health of of API Gateway, that is to check the overall cluster health and to identify if the components of a particular API Gateway node are in an operational state, use the following REST endpoint:
GET /rest/apigateway/health/engine
The following table shows the response code and the description.
Response | Description |
200 OK | Runtime service health check is successful. |
500 Internal server error | Runtime service health check failed and denotes a problem. The response JSON indicates the problem. |
timeout or no response as the request did not reach the probe | Several factors can contribute to the delay when the Runtime Service Health Probe initiates, which may result in the timeout errors. To know the reasons for timeout errors, see
Causes for timeout errors for more information. |
The response JSON of each health check request displays a status field in the response.
The overall status of API Gateway node can be green ,yellow, or red.
Status | Description |
green | Indicates that the cluster within the node is in a healthy state. |
yellow | Indicates that API Gateway does not have adequate resources to run. |
red | Indicates the cluster failure in the node and an outage. |
The overall status of API Gateway node is assessed based on the API Data Store status, API Gateway resource status, and the Terracotta server status.
API Data Store status
Status | Description |
green | Indicates that API Data Store is in a healthy state. When the status of API Data Store signals green or yellow, the overall status of API Gateway is green. |
red | Indicates that API Data Store is not in a healthy state. When the status of API Data Store signals red, the overall status of API Gateway is red. |
yellow | Indicates a node failure in the cluster. However, the cluster is still functioning and operational. |
API Gateway resource status
Status | Description |
green | Indicates that API Gateway resource types like memory, disk space, and service threads are available to run. |
yellow | Indicates that API Gateway does not have adequate resources to run. When the API Gateway resource status is yellow, the overall status of API Gateway is yellow. |
Terracotta Server Array status
Status | Description |
green | Indicates that Terracotta server is in a healthy state. When the status of Terracotta server signals green, the overall status of API Gateway is green. |
red | Indicates that Terracotta server is not in a healthy state. When the status of Terracotta server signals red, the overall status of API Gateway is red. |
A sample HTTP response is as follows:
{
"status": "green",
"elasticsearch": {
"cluster_name": "SAG_EventDataStore",
"status": "yellow",
"number_of_nodes": "1",
"number_of_data_nodes": "1",
"timed_out": "false",
"active_shards": "95",
"initializing_shards": "0",
"unassigned_shards": "92",
"task_max_waiting_in_queue_millis": "0",
"port_9240": "ok",
"response_time_ms": "526"
},
"is": {
"status": "green",
"diskspace": {
"status": "up",
"free": "908510568448",
"inuse": "104799719424",
"threshold": "101331028787",
"total": "1013310287872"
},
"memory": {
"status": "up",
"freemem": "425073672",
"maxmem": "954728448",
"threshold": "92222259",
"totalmem": "922222592"
},
"servicethread": {
"status": "up",
"avail": "72",
"inuse": "3",
"max": "75",
"threshold": "7"
},
"response_time_ms": "258"
},
"terracotta": {
"status": "green",
"nodes": "1",
"healthy_nodes": "1",
"response_time_ms": "22"
}
}
The overall engine status is green since all components work as expected.
Administration Service Health Probe at Node-Level
To check the availability and health status of the API Gateway administration service (UI, Dashboards) on a particular API Gateway node, use the following rest endpoint:
GET /rest/apigateway/health/admin
The following table shows the response code and the description.
Response | Description |
200 OK | Administration service health check is successful. |
500 Internal server error | Denotes a problem. The response JSON indicates the problem. |
timeout or no response as the request did not reach the probe | Several factors can contribute to the delay when you initiate the Administration Service Health Probe, which may result in the timeout errors. To know the reasons for timeout errors, see
Causes for timeout errors for more information. |
The overall Administration Service Health Probe status can be green or red based on the API Gateway administration service's status and Kibana's status.
Kibana status
Status | Description |
green | Indicates that Kibana's port is accessible. When the status signals green, the overall status of Administration Service Health Probe is green. |
red | Indicates that either Kibana's port is inaccessible or Kibana's communication with API Data Store is not established. When the status signals red, the overall status of Administration Service Health Probe is red. |
API Gateway administration service status
Status | Description |
green | Indicates that API Gateway administration service is available. When the status signals green, the overall status of Administration Service Health Probe is green. |
red | Indicates that API Gateway administration service is not available. When the status signals red, the overall status of Administration Service Health Probe is red. |
A sample HTTP response is as follows:
{
"status": "green",
"ui": {
"status": "green",
"response_time_ms": "40"
},
"kibana": {
"status": {
"overall": {
"state": "green",
"nickname": "Looking good",
"icon": "success",
"uiColor": "secondary"
}
},
"response_time_ms": "36"
}
}
The overall status is green since API Gateway administration service and Kibana is in a healthy state.
How do I collect metrics?
To check the usage of the application and system parameters, use the following metrics endpoint: GET /metrics. When the endpoint is called, API Gateway gathers metrics and returns the data in the Prometheus format.
Note:
Prometheus is a non-
Software AG dashboarding tool that helps in trend analysis. For more information, see
https://prometheus.io/.
Prometheus metrics are exposed through the following endpoint.
[http|https]://host:port/metrics
The metrics endpoint by default is available on the following ports:
Default primary port (http). 5555
Default secure port (https). 5543
Default diagnostic port (debug port). 9999
A sample for the metrics endpoint is as follows:
http://server:5555/metrics
Authentication for the metrics endpoint
By default, the authentication is disabled when running
API Gateway as Docker container.
For on-premise installations, the following environment variable can be set to switch off the authentication for the metrics endpoint:
SAG_IS_METRICS_ENDPOINT_ACL=Anonymous
The endpoint also exposes the Integration Server Prometheus metrics. For more details on the Integration Server Prometheus metrics, see Developing Microservices with webMethods Microservices Runtime.
Exposing API Gateway Prometheus Metrics over a dedicated port
The metrics endpoint can be made available on a custom port. After creating the port, add the following service to the port's allow list:
wm.server.query:getPrometheusStats
Similarly, the metrics endpoint can be removed from the default ports (5555 or 5543 or 9999) by removing the service from the allow or deny lists.
