Health check service
Overview
The Sitefinity CMS Health Check service, enables you to assess the core components of your Sitefinity CMS application. Once you enable the service, you can run background checks on whether the site is operational, responsive, and set up properly. The default checks are:
- System Bootstrap - Provides information on whether the Sitefinity CMS system is up and running.
- Startup - Provides information when Sitefinity startup is successfully completed.
You can also configure additional checks you run on demand to make sure other key aspects of the web application are properly functioning:
- Database access
- Load balancing nodes communication
- Internet connectivity
- Redis check
- Search service availability
Set up the Health check service
To set up Health check service on a Sitefinity CMS site you must first specify the name of the endpoint where you'd like to have the health check resolved. Follow these steps:
- Edit the
web.config
of the Sitefinity site, for which you want health checks to run.
- Add a new entry in the
appSettings
section with:
- key - sf:HealthCheckApiEndpoint
- value - specify on what endpoint you would like to access the health check service
For example:
<add key="sf:HealthCheckApiEndpoint" value="restapi/health"/>
- Save the edited file, and then restart the site.
Next you must enable and configure the health check service by following these steps:
- Select Administration » Settings, and then choose Advanced.
- Expand System and select Health check service.
- Select the Enable Health check service checkbox.
- Optionally, select the Enable logging of health check tasks checkbox.
Every time you demand the HTTP request URL, all information is stored in the healthcheck.log file, located in the ~/App_Data/Sitefinity/Logs folder, along with all responses, messages, and timestamps.
- Optionally, to configure the health check service to return a specific HTTP status code when the system is not healthy, set the app settings key
sf:HealthCheckUnhealthyStatusCode
to return the desired status code when the system is not healthy.
By default, the health check service returns a standard status code 200.
When you configure this setting, any failed heath check will return the status code that you have configured. The successfully passed health checks will return status code 200
.
For example, <add key="sf:HealthCheckUnhealthyStatusCode" value="500" />
.
- Optionally, enter an Аuthentication key. This makes the health check service endpoint accessible only if you pass an HTTP header to the request with key authKey and value - the specified authentication key value.
- Click Save Changes to record your entries.
Configure health checks
Once enabled, the health check service is available at the configured endpoint, for example https://www.yourwebsite.com/restapi/health. By default, the health check service will return a response with information about the status of the two default checks:
- SystemIsBootstrapped
Provides information on whether the Sitefinity CMS system is up and running.
- StartUpFinished
Provides information when Sitefinity startup is successfully completed.
For example, this is the default health check service response when both checks pass successfully:
NOTE: Health check results are cached for 10 seconds. If you run the check again within the 10 seconds, you get the same response.
Sitefinity CMS enables you to check other elements of the system in addition to Bootstrap and Startup operations. To include other checks in the health check service follow these steps:
- In your Sitefinity CMS administrative backend, navigate to Administration» Settings » Advanced.
- Expand System and select Health check service » Health checks
- Click on Create new
- Fill in the following information:
- Enable health check - select the checkbox to make sure the health check is included
- Health check name - type in a friendly name for the health check you want to add
- Critical - select this checkbox if you want this check to affect the end result when calling the health check service. By default, only the SystemIsBootstrapped and StartUpFinished health checks are critical. When a health check is not critial, it can fail, but the end result of calling the health check will still be successful, if the critical health checks have passed successfully.
- Groups - you can mark different health checks with the same group. THis approach is similar to classifying them. When calling the health check service, you can optionally pass a group name, and have only the checks that are marked with this group execute
- Type - configure the specific CLR type matching the health check you want to add. The health check types you can add out of the box are:
Health check |
Description |
Type |
System Bootstrap |
Default check.
Provides information only if the Sitefinity CMS system is up and running. |
Telerik.Sitefinity.Health.SystemIsBootstrapped |
Start Up |
Default check.
Provides information when Sitefinity CMS startup is successfully completed. |
Telerik.Sitefinity.Health.StartUpFinished |
Database access |
Provides information whether Sitefinity CMS database is accessible. |
Telerik.Sitefinity.Health.DatabaseCheck |
NLB communication |
Provides information whether communication between nodes is working |
Telerik.Sitefinity.Health.NlbCheck |
Internet connectivity |
Provides information if internet connectivity to a given URL (provided as a parameter when calling the health check service) |
Telerik.Sitefinity.Health.InternetConnectivityCheck |
Redis check |
Provides information if a load balanced environment with Redis is working |
Telerik.Sitefinity.Health.RedisCheck |
Search service check |
Provides information whether the search service (valid for external search services only) is working |
Telerik.Sitefinity.Search.Impl.HealthChecks.SearchServiceConnectivityCheck |
- Click Save changes
Configure parameters for health checks
Some health checks require that you configure a parameter as part of their setup process. For example, when you configure an Internet connectivity health check you also need to provide a URL address the health check to ping in order to verify successful internet connectivity.
IMPORTANT: You configure parameters only for the checks that require them. In addition, you only use the required parameter and key. The table below captures the available parameters for the different out of the box health checks:
Health check |
Type |
Required parameter |
Internet connectivity |
Telerik.Sitefinity.Health.InternetConnectivityCheck |
Key: url
Value:
Any existing URL, for example:
http://www.google.com |
Redis check |
Telerik.Sitefinity.Health.RedisCheck |
Key: requestTimeout
Value:
Any number, representing a time period in milliseconds.
Default value is 1000
NOTE: If you do not enter any value, the check considers the requestTimeout value to be the default one.
|
To configure parameters for health checks, follow these steps:
- Expand the node for your newly created health check.
- Click Parameters.
- Click the Create new button.
- Enter the key of the parameter, for example, url.
For details, refer to the table above.
- Enter the parameter value, for this example, http://www.google.com.
- Save your changes.
After you add health checks and their parameters, you must restart the site to enable the updated Health check service.
Run health checks
You run health checks by making an HTTP request to the health check endpoint. The response returns the status of all enabled health checks.To run a general health check, including all additional checks you configured, make an HTTP request to the health check service endpoint:
http://server:port/<path_value>
where:
- server:port is the host and port where the site you want check is running, for example, mysite.com
- <path_value> defines the path where the health check service is accessible. You can replace it with any value, for example: http://mysite.com/restapi/health
Use health check groups
You can group checks and associate them with a group name, acting as a tag to better filter the set of results you require. Thus, by running checks by a query parameter that interprets arguments in the query string, you define what checks to run.
You run group health checks by making an HTTP request with the following syntax:
server:port/<path_value>?type=groupname,groupname,…
Where ?type=groupname,groupname,… is the list of groups that you defined on individual health checks. When these parameters are omitted, all enabled checks will run.
For example, group the health checks for connectivity to Google under the group name Internet. Next, run the health check with the following HTTP request: mysite.com/restapi/health?type=Internet
Interpret Health Check results
After you enable the health check service, you can run a health check on the running site at any time.
To run a health check, simply make an HTTP request:
server:port/<path_value>?type=groupname,groupname,…
where:
- server:port is the host and port where the site you want check is running, for example, mysite.com
- <path_value> defines the path where the health check service is accessible. You can replace it with any value, for example, http://mysite.com/restapi/health
- ?type=groupname,groupname,… is the list of groups that you defined on individual health checks. When these parameters are omitted, all enabled checks will run.
The following example demonstrates how overall health check results are affected by the groups and configurations you set.
You configure the following:
Health check |
Group |
Critical |
Internet connectivity check Google |
internet |
Yes |
Redis check |
redis |
Yes |
You run the following HTTP request:
mysite.com/restapi/health?type=internet, redis
You get the following health check result:
In the example above, the overall result of the health check is false. The reasons are:
Redis check is critical. Therefore, since Redis check is unsuccessful, the overall result is false.
Network load balancing is not active, so the Redis test failed. By disabling the Redis check and restarting the site, that check is skipped and the overall health check result is true.