Health check service

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

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:

1. Edit the web.config of the Sitefinity site, for which you want health checks to run.
2. 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"/>  
3. Save the edited file, and then restart the site.

Next you must enable and configure the health check service by following these steps:

1. Select Administration » Settings, and then choose Advanced.
2. Expand System and select Health check service.
3. Select the Enable Health check service checkbox.
4. 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.
5. 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" />.
   
6. 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.
   
7. Click Save Changes to record your entries.

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.

1. In your Sitefinity CMS administrative backend, navigate to Administration» Settings » Advanced.
2. Expand System and select Health check service » Health checks
3. Click on Create new
4. Fill in the following information:
   1. Enable health check - select the checkbox to make sure the health check is included 
   2. Health check name - type in a friendly name for the health check you want to add
   3. 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.
   4. 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
   5. 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

5. 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:

To configure parameters for health checks, follow these steps:

1. Expand the node for your newly created health check.
2. Click Parameters.
3. Click the Create new button.
4. Enter the key of the parameter, for example, url.
   For details, refer to the table above.
5. Enter the parameter value, for this example, http://www.google.com.
6. Save your changes.

After you add health checks and their parameters, you must restart the site to enable the updated Health check service.

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 

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

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:

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.