Status/Health API

1. Overview

Contains status and health related API info.

Health
Status
Prometheus

In CleanSpeak 3.x and earlier, /status requires no authentication. In 4.x, /api/status, /prometheus/metrics, and /status require at least 1 of the following:

Logged in user (via browser)
API key
Request from localhost with cleanspeak-app.local-metrics.enabled set to true in the configuration file

2. Health

Health API Available Since Version 4.0.0

Health is a lighter weight version of the status API, suitable for Kubernetes liveliness/readiness checks, that just checks the ability of CleanSpeak to query the database and respond.

2.1. Request

URI

GET /api/health

No authentication is required to access the health endpoint.

2.2. Response

The response body will always be empty. The Response Codes noted below are what should be checked.

Table 1. Response Codes
Code	Description
200	The CleanSpeak server is functioning properly
500	The CleanSpeak server is not functioning properly. This could indicate that the database connectivity failed or one or more services within CleanSpeak failed. Consult the CleanSpeak Troubleshooting to learn more about the failure or contact CleanSpeak support for assistance.

3. Status

This API provides status information about CleanSpeak with the help of the Dropwizard Metrics project. The status information is broken down into metrics and health checks. Metrics provide timing information, counts, meters, histograms, etc. The health checks provide information about services in CleanSpeak and whether or not they are working properly.

3.1. Request

URI

GET /status

URI (4.x)

GET /api/status

In 3.x, both the WebService and Management Interface endpoints were /status. The WebService endpoint includes an actual filter check in the status.

In 4.x, since there is just a single application, /status is a lighter status check and /api/status runs a check with the filter like the WebService application did.

3.2. Response

The JSON response from the Status API is complex and subject to change. The specific contents of the JSON body are not documented here. If you choose to use this API for monitoring purposes you should primarily use the response code to indicate server health. If you receive a 200 you may consider CleanSpeak in a healthy state. The response body is intended for use by CleanSpeak support.

Table 2. Response Codes
Code	Description
200	The CleanSpeak server is functioning properly
500	The CleanSpeak server is not functioning properly. This could indicate that the database connectivity failed or one or more services within CleanSpeak failed. Consult the CleanSpeak Troubleshooting to learn more about the failure or contact CleanSpeak support for assistance.

4. Prometheus

This API provides metrics similar to the Status Endpoint but responds in a format designed for Prometheus.

If you need help setting up prometheus, see our tutorial.

4.1. Request

In CleanSpeak 3.x, this endpoint exists on both the Webservice and Management Interface

URI

GET /prometheus/metrics

4.2. Response

The Prometheus encoded response.

Table 3. Response Codes
Code	Description
200	The request succeeded and the response is a valid Prometheus body
500	Something went wrong and it will be logged. The body will be empty.