This document is work in progress!
The Carbon Health Check API can be used to check the health of a Carbon server. The sections below guide you through using this API.
Note: This API is only supported for WSO2 Carbon products that are running on Java 8 or a later version.
There are three health checkers available by default:
- Data sources health checker - This checker goes through the data sources that are configured in the
master-datasources.xmlfile and checks if the active connection count surpasses a healthy percentage limit (e.g., 80%) of the maximum allowed connections count. This checker also tests the connection from each data source to see whether the connection is successful.
- Server startup health checker - This checker uses the ServerAdmin service to check if the server status is RUNNING.
Super tenant user store health checker - This checker iterates through configured user stores of the super tenant domain and attempts to invoke the
isExistingUsermethod to check whether a failure occurs.
Deploying the API
This API is supported by default from WSO2 Identity Server 5.7.0 onwards. It is available by default for WSO2 IS versions 5.5.0 and 5.6.0 only as a WUM update. For more information on how to update using WUM, see Getting WSO2 Updates documentation.
If you are using a WSO2 product version that supports this feature by default (either in a fresh pack or via a WUM update), skip the instructions in this section and proceed to the configuring the API section.
This section guides you through deploying the Carbon Health Check components in a WSO2 Carbon product that does not support this feature by default.
- Download the org.wso2.carbon.healthcheck.server.feature-<version-number>.zip and extract it. This folder is reffered to as
<API_HOME>in this document.
- Copy the
org.wso2.carbon.healthcheck.api.core-<version-number>.jarfound in the
<API_HOME>/pluginsdirectory and paste it in the
- Copy the webapp
api#health-check#v1.0.warfound in the
<API_HOME>/features/org.wso2.carbon.healthcheck.server_1.0.0directory and paste it in the the
- (Optional step) Copy the
health-check.config.xmlconfiguration file found in the
org.wso2.carbon.healthcheck.server_1.0.0directory to your
Configuring the API
This feature is disabled by default. To enable the API, set the
<Enable> property in the
health-check-config.xml file to true.
If the feature has not been enabled successfully, a request to the API will only return a 200 OK response.
- A health checker can be enabled or disabled using the
- The execution order in which the health checkers are executes can be configured using the
The properties configured under each health checker will be available for each heath checker at runtime.
Invoking the API
This is an open API which should ideally be blocked at the load balancer level. To invoke it, start the WSO2 product and send a GET request to the health check API. A sample cURL command is shown below.
If the request is successful, you will recieve a 200 OK response (similar to the one shown below) with a list of health check results.
active.connection.countparameter reflects the number of connections that are active.
ConnectivityTimerefers to the the duration of the connection.
The following responses are possible error responses that you may receive.
The code block below shows a sample 503 Unavailable response with an array of errors.
|Data source connectivity error.|
|HC_00002||Number of connections in data source exceeds the healthy percentage.|
|HC_00003||Error while testing connectivity to the user store using the |
|HC_00004||Server status is not running.|
|HC_00005||Error listing user stores.|
Adding new health checkers
To add a new health checker, you can implement the HealthChecker API and register the health checker as an OSGI service.
To deploy it, copy the
.jar file to the
<PRODUCT_HOME>/repository/component/lib/ directory or the OSGI bundle and paste it in the