How to create Sitecore 9.3 custom health checks

Starting from version 9.3, Sitecore includes health check HTTP endpoints which you can use to check health of your Sitecore instance. In this post I will show how to add custom health checks.

I have already described built-in health checks in this post before: Sitecore 9.3 loves Docker . As a short recap, Sitecore 9.3 health checks are based on Microsoft.Extensions.Diagnostics.HealthChecks with some sauce on top:

  • Since Sitecore is not based on ASP.NET Core, it cannot use health checks middleware to expose liveness and readiness endpoints (/healthz/live and /healthz/ready). Instead, it is using a regular Web API controller for this: Sitecore.Diagnostics.HealthCheckController
  • Sitecore is exposing custom extension methods for Microsoft.Extensions.DependencyInjection.IServiceCollection to simplify dependency registration.

Monitoring health

I think it is obvious that you need to monitor health of your application if you want to minimize downtime and react on failures quickly. If you have mature DevOps culture in your organization, you will likely have some infrastructure/tooling for monitoring application health, logs and alerting your DevOps team if something is wrong. Datadog is one example of such tooling.

In case you have this infrastructure already in place, all you have to do is to point it to your Sitecore health check endpoints (/healthz/live and /healthz/ready) and set up alerts. In my case I use these endpoints for Kubernetes liveness and readiness probes .

Note: XConnect, Identity and Publishing Service also expose liveness and readiness HTTP endpoints (/healthz/live and /healthz/ready).

If you don’t have such a setup, have a look at the Advanced Sitecore Healthcheck module by Mihály Árvai (@mitya_1988): https://github.com/Mitya88/SitecoreHealthcheck . It includes nice SPEAK 3 dashboards, which would allow you to monitor health of your Sitecore instances (including XConnect) from a central location. Not to mention tons of pre-built health checks.

Note: This module is not based on top of Sitecore Health checks (and Microsoft.Extensions.Diagnostics.HealthChecks ) under the hood and does not expose any HTTP endpoints (as far as I know). It was built with a different purpose in mind: monitoring Sitecore health from within Sitecore UI.

Update (17.07.2020): it is now possible to expose the module’s health check result in Sitecore health HTTP endpoint . Good job Mihály!

Adding custom health checks

By default Sitecore health checks include SQL and SOLR, which is normally enough for most of the cases. However, when your application is more complex you might consider adding custom health checks.

For example, in my project I use readiness check to warmup some of the APIs and make sure they return 200OK. This becomes very useful during our Kubernetes deployment: in case one of the APIs is unhealthy, the readiness probe fails which will prevent pods from receiving the traffic. And if it is healthy – the instance would be warmed up before receiving any traffic, which results in smooth deployment experience.

Below are the steps needed to implement such a simple health check.

1. Implement custom health check

Implement a class inheriting from Microsoft.Extensions.Diagnostics.HealthChecks.IHealthCheck. This interface resides in Microsoft.Extensions.Diagnostics.HealthChecks.Abstractions Nuget package (version 2.2.0.0 for Sitecore 9.3).

2. Register a custom health check

In your DI registration import the Sitecore.HealthCheck.DependencyInjection namespace and use the AddHealthChecks extension method from Sitecore to register your health check class:

services.AddHealthChecks().AddCheck<ApiHealthCheck>(
	"API Smoke Test",
	HealthStatus.Unhealthy,
	new[] { "ready" });

Note: the last argument is an array of tags. You can tag your health checks with ready and/or live tags, which would enlist your custom healthcheck to be used in /healthz/ready and/or /healthz/live HTTP endpoints respectively.

Summary

All Sitecore roles, including Identity, XConnect and Publishing Service expose liveness and readiness HTTP endpoints which you can use to monitor health of your Sitecore deployment. If needed, you can implement custom health checks on top of the default ones.

That’s it, stay healthy out there!