Health Check

[Source]

The Health Check is a special peer port method for reporting on the health of an individual rippled server. This method is intended for use in automated monitoring to recognize outages and prompt automated or manual interventions such as restarting the server.

This method checks several metrics to see if they are in ranges generally considered healthy. If all metrics are in normal ranges, this method reports that the server is healthy. If any metric is outside normal ranges, this method reports that the server is unhealthy and reports the metric(s) that are unhealthy. Since some metrics may rapidly fluctuate into and out of unhealthy ranges, you should not raise alerts unless the health check fails multiple times in a row.

Note: Since the health check is a peer port method, it is not available when testing the server in stand-alone mode.

Request Format

To request the Health Check information, make the following HTTP request:

• Protocol: https
• HTTP Method: GET
• Host: (any rippled server, by hostname or IP address)
• Port: (the port number where the rippled server uses the Peer Protocol, typically 51235)
• Path: /health
• Security: Most rippled servers use a self-signed certificate to respond to the request. By default, most tools (including web browsers) flag or block such responses for being untrusted. You must ignore the certificate checking (for example, if using cURL, add the --insecure flag) to display a response from those servers.

Example Response

HTTP/1.1 200 OK
Server: rippled-1.6.0-b8
Content-Type: application/json
Connection: close
Transfer-Encoding: chunked

{
  "info": {}
}

HTTP/1.1 503 Service Unavailable
Server: rippled-1.6.0
Content-Type: application/json
Connection: close
Transfer-Encoding: chunked

{
  "info": {
    "server_state": "connected",
    "validated_ledger": -1
  }
}

HTTP/1.1 500 Internal Server Error
Server: rippled-1.6.0
Content-Type: application/json
Connection: close
Transfer-Encoding: chunked

{
  "info": {
    "peers": 0,
    "server_state": "disconnected",
    "validated_ledger":-1
  }
}

Response Format

The response's HTTP status code indicates the health of the server:

The response body is a JSON object with a single info object at the top level. The info object contains values for each metric that is in a warning or critical range. The response omits metrics that are in a healthy range, so a fully healthy server has an empty object.

The info object may contain the following fields:

See Also

For guidance interpreting the results of the health check, see Health Check Interventions.