Running basic platform health checks via REST API

Note

The check described on this page is deprecated. We recommend to run D1 or Conversion Service-specific checks instead.

You can run basic platform health check via /healthz endpoint. This check returns a response showing the status of the D1 or Conversion Service host, either in JSON, HTML or plain text.

Either in a local or distributed setup the status of an instance needs to be checked to decide if the instance is still alive or if it must be deactivated/replaced. The check API provides a standardized procedure to define and implement checks in order to obtain information about the status of a tribefire instance. Such checks may include:

• Availability of database connections
• Reachability of extensions
• Thread pools
• Status of deploys, especially accesses

The platform provides the /healthz endpoint which is responsible for the execution of checks. The full URL is https://[host]:[port]/tribefire-services/healthz. By default, this prints an HTML report:

If you render the output, you get a human-readable report:

You can change the output to either JSON or plain text by passing a HTTP Accept header, as explained below in the sample call.

Sample call using cURL

curl --request GET https://hostname:port/tribefire-services/healthz --header "Accept: application/json"

You might want to use --insecure when using HTTPS with self-signed certificates. Keep in mind that this option disables certificate validation.

HTTP Accept Header	Description
application/json	Prints out the report in JSON
text/html	Prints out the report in HTML
text/plain	Prints out the report in plain text

JSON response

In case the accept header is set to application/json, the endpoint answers with a JSON structured as check results per node.

Sample output:

{"_type": "flatmap", "value":[
 {"_type": "com.braintribe.model.service.api.InstanceId", "_id": "0",
   "applicationId": "master",
   "nodeId": "tf@NB-VIE01-CWI02#200128101854615f41f7f263064628ab"
  },[
   {"_type": "com.braintribe.model.check.service.CheckResult", "_id": "1",
    "entries": [
     {"_type": "com.braintribe.model.check.service.CheckResultEntry", "_id": "2",
      "checkStatus": "ok",
      "details": "Check infrastructure is ok",
      "name": "Base Check"
     },
     {"_type": "com.braintribe.model.check.service.CheckResultEntry", "_id": "3",
      "checkStatus": "ok",
      "details": "Active Threads: 0, Total Executions: 1, Average Execution Time: 182 ms, Pool Size: 0, Core Pool Size: 5",
      "name": "Thread Pool: Activation"
     },
   }
}

The maps's key value defines the type InstanceId which reflects the node (applicationId@nodeId) that was responsible for the check execution.
The map's value defines the list of CheckResults. A CheckResult returns a list of CheckResultEntry.

A CheckResultEntry is qualified by:

Value	Description
status	Set to one of the following values: ok, warn or fail
name	The name of the executed check e.g. "DB Connectivity Check"
message	The summarized check result message.
details	Contains check result details like an exception stacktrace or further information of the check result.

HTTP status codes

If you are using a monitoring system, you might be interested in the different HTTP status codes returned.

A 200 OK is returned when all checks have passed, while a 503 Service Unavailable is returned when at least one check has failed.
If check result entries contain at least one warn or fail, the returned HTTP status code is always 503 Service Unavailable. For example, if you have 4 checks:

• [ok, ok, ok, ok] the status is 200 OK
• [ok, ok, ok, warn] the status is 503 Service Unavailable

Custom HTTP status codes

You can define a custom status code for when a warn is thrown. You can do this by adding the warnStatusCode=123 parameter to the URL when calling the endpoint. Sample call:

https://hostname:port/tribefire-services/healthz?warnStatusCode=123

If the parameter is set, the defined status code is returned in case a CheckResult results in a warn. If this parameter is not defined, the default HTTP status code 503 is used.