Health Checks

A health check is an endpoint your infrastructure calls to ask your application how it is. It exists for machines, not people. Whatever it returns, something automatic happens: a load balancer stops sending traffic, an orchestrator restarts a container, a deployment stops rolling forward.

That is why the design matters more than it appears. A health check is not a diagnostic page. It is an input to an automated decision, and a check that answers the wrong question causes the automation to do the wrong thing.

There are two questions, and conflating them is the mistake this lesson exists to prevent.

Readiness is what stops traffic reaching a broken instance. Suppose one instance loses its database connection pool while the other three are fine. Its readiness check queries the database, fails, and the load balancer removes it from rotation. Users keep being served by the healthy three. When the pool recovers, the check passes and the instance quietly comes back.

Without a readiness check that touches the database, the load balancer sees a process responding to requests and keeps sending traffic to it. A quarter of requests fail, and from the outside the service looks intermittently broken with no obvious cause.

Liveness is for the case where the process is stuck: deadlocked, out of memory, unable to respond at all. Restarting it is the only available remedy, and that is exactly why it must not test anything outside the process.

// Requires Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore
// for AddDbContextCheck.
builder.Services.AddHealthChecks()

    // Liveness: no dependencies at all. If this code runs, the process lives.
    .AddCheck("self", () => HealthCheckResult.Healthy(), tags: ["live"])

    // Readiness: everything this instance needs to serve a request.
    .AddDbContextCheck<HrDbContext>("hr-database", tags: ["ready"])
    .AddCheck<PayrollApiHealthCheck>("payroll-api", tags: ["ready"]);

WebApplication app = builder.Build();

app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    // Runs no registered checks beyond the liveness one.
    Predicate = registration => registration.Tags.Contains("live"),
});

app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = registration => registration.Tags.Contains("ready"),
});

app.MapControllers();

• Tags are what let one registration list serve two endpoints. Each MapHealthChecks call filters by tag, so the liveness endpoint never touches a dependency.
• The liveness check returns healthy unconditionally. That looks pointless and is not: reaching the delegate means the process is running, the pipeline works and threads are available. If the process were deadlocked, the request would time out instead.
• AddDbContextCheck verifies that the context can connect. It is the cheapest meaningful readiness signal for an application whose main dependency is its database.
• A failing check maps to 503 by default and a healthy one to 200, which is what load balancers and orchestrators read. Note the middle case: a Degraded result also returns 200 unless you configure otherwise, so a degraded instance keeps receiving traffic. That is usually right, and it should be a decision rather than a surprise.
• Health endpoints describe your infrastructure. Restrict them to internal callers, or return no detail on the public one, so the shape of your dependencies is not published.

public sealed class PayrollApiHealthCheck(
    IHttpClientFactory httpClientFactory) : IHealthCheck
{
    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        try
        {
            HttpClient client = httpClientFactory.CreateClient("payroll");

            // Keep it short. A slow health check is itself a problem.
            using CancellationTokenSource timeout = new(TimeSpan.FromSeconds(2));
            using CancellationTokenSource linked =
                CancellationTokenSource.CreateLinkedTokenSource(cancellationToken, timeout.Token);

            using HttpResponseMessage response = await client.GetAsync("ping", linked.Token);

            return response.IsSuccessStatusCode
                ? HealthCheckResult.Healthy()
                : HealthCheckResult.Degraded("Payroll responded but not successfully.");
        }
        catch (Exception ex)
        {
            return HealthCheckResult.Unhealthy("Payroll is unreachable.", ex);
        }
    }
}

• IHealthCheck has one method. Return Healthy, Degraded or Unhealthy, and optionally a description and the exception.
• The timeout is deliberate. A health check that takes ten seconds will be interpreted as a failure by whatever called it, so bound every external call inside a check.
• Degraded is the honest answer when a dependency responds but not well. Remember that Degraded still returns 200 by default, so use Unhealthy when you want traffic to stop.
• The catch is broad on purpose. Anything at all going wrong here means the dependency cannot be relied on, and a health check that throws is less useful than one that reports.
• Be careful what goes in the description. It appears in the response, and naming hosts or connection details there publishes them.