Skip to main content
FullStackHero includes comprehensive health check endpoints using ASP.NET Core’s health check system. Health checks allow monitoring tools, orchestrators (like Kubernetes), and load balancers to determine if your application is running correctly.

​
Overview

The health check system provides:
  • Liveness Probe: Verify the application process is running
  • Readiness Probe: Verify the application can handle requests (database, cache, etc.)
  • Custom Health Checks: Add checks for dependencies (database, Redis, external APIs)
  • Detailed Diagnostics: View individual check results and durations
  • Anonymous Access: Health checks don’t require authentication

​
Health Check Endpoints

FullStackHero exposes two health check endpoints:

​
Liveness Endpoint

Endpoint: GET /health/live Returns a simple response indicating the process is alive. Does not check external dependencies. 
curl http://localhost:5000/health/live
Response: 
{
  "status": "Healthy",
  "results": []
}
The liveness endpoint always returns 200 OK if the process is running. Use this for Kubernetes liveness probes.

​
Readiness Endpoint

Endpoint: GET /health/ready Checks all registered health checks (database, cache, etc.) and returns detailed results. 
curl http://localhost:5000/health/ready
Response (Healthy): 
{
  "status": "Healthy",
  "results": [
    {
      "name": "database",
      "status": "Healthy",
      "description": "Database connection is healthy",
      "durationMs": 12.5,
      "details": {
        "connectionString": "Server=localhost;Database=fsh;..."
      }
    },
    {
      "name": "redis",
      "status": "Healthy",
      "description": "Redis connection is healthy",
      "durationMs": 3.2,
      "details": {}
    }
  ]
}
Response (Unhealthy) - Returns 503 Service Unavailable: 
{
  "status": "Unhealthy",
  "results": [
    {
      "name": "database",
      "status": "Unhealthy",
      "description": "Database connection failed",
      "durationMs": 5002.1,
      "details": {
        "error": "Timeout expired"
      }
    }
  ]
}

​
Health Check Implementation

The health check endpoints are defined in the Web building block:
HealthEndpoints.cs
public static IEndpointRouteBuilder MapHeroHealthEndpoints(
    this IEndpointRouteBuilder app)
{
    var group = app.MapGroup("/health")
                   .WithTags("Health")
                   .AllowAnonymous()
                   .DisableRateLimiting();

    // Liveness: only process up (no external deps)
    group.MapGet("/live",
            async Task<Ok<HealthResult>> (
                HealthCheckService hc, 
                CancellationToken cancellationToken) =>
            {
                var report = await hc.CheckHealthAsync(
                    _ => false, cancellationToken);
                var payload = new HealthResult(
                    Status: report.Status.ToString(),
                    Results: Array.Empty<HealthEntry>());

                return TypedResults.Ok(payload);
            })
            .WithName("Liveness")
            .WithSummary("Quick process liveness probe.")
            .WithDescription("Reports if the API process is alive. Does not check dependencies.")
            .Produces<HealthResult>(StatusCodes.Status200OK);

    // Readiness: includes DB (and any other registered checks)
    group.MapGet("/ready",
                async Task<Results<Ok<HealthResult>, StatusCodeHttpResult>> (
                    HealthCheckService hc, 
                    CancellationToken cancellationToken) =>
                {
                    var report = await hc.CheckHealthAsync(
                        cancellationToken: cancellationToken);
                    var results = report.Entries.Select(e =>
                        new HealthEntry(
                            Name: e.Key,
                            Status: e.Value.Status.ToString(),
                            Description: e.Value.Description,
                            DurationMs: e.Value.Duration.TotalMilliseconds,
                            Details: e.Value.Data.ToDictionary(
                                k => k.Key,
                                v => v.Value is null ? "null" : v.Value
                            )));

                    var payload = new HealthResult(
                        report.Status.ToString(), results);

                    return report.Status == HealthStatus.Healthy
                        ? TypedResults.Ok(payload)
                        : TypedResults.StatusCode(
                            StatusCodes.Status503ServiceUnavailable);
                })
                .WithName("Readiness")
                .WithSummary("Readiness probe with database check.")
                .WithDescription("Returns 200 if all dependencies are healthy, otherwise 503.")
                .Produces<HealthResult>(StatusCodes.Status200OK)
                .Produces(StatusCodes.Status503ServiceUnavailable);

    return app;
}

​
Key Features

Anonymous Access

Health checks use .AllowAnonymous() so they work without authentication.

No Rate Limiting

Health checks are exempt from rate limiting using .DisableRateLimiting().

Detailed Results

The readiness endpoint returns individual check results, durations, and diagnostic data.

Proper Status Codes

Returns 200 OK when healthy, 503 Service Unavailable when unhealthy.

​
Custom Health Checks

Add custom health checks for your dependencies:

​
Database Health Check

Automatically registered when using Entity Framework Core: 
services.AddDbContext<AppDbContext>(options => { ... })
    .AddHealthChecks()
    .AddDbContextCheck<AppDbContext>("database");

​
Redis Health Check

Check Redis connectivity: 
services.AddHealthChecks()
    .AddRedis(
        connectionString: "localhost:6379",
        name: "redis",
        failureStatus: HealthStatus.Degraded);

​
Custom Health Check Example

Implement IHealthCheck for custom checks:
TenantMigrationsHealthCheck.cs
public class TenantMigrationsHealthCheck : IHealthCheck
{
    private readonly IServiceProvider _serviceProvider;

    public TenantMigrationsHealthCheck(IServiceProvider serviceProvider)
    {
        _serviceProvider = serviceProvider;
    }

    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken ct = default)
    {
        try
        {
            // Check if all tenant databases have migrations applied
            using var scope = _serviceProvider.CreateScope();
            var tenantStore = scope.ServiceProvider
                .GetRequiredService<ITenantStore>();
            
            var tenants = await tenantStore.GetAllAsync();
            var unhealthyTenants = new List<string>();

            foreach (var tenant in tenants)
            {
                var dbContext = GetTenantDbContext(tenant.Id);
                var pendingMigrations = await dbContext.Database
                    .GetPendingMigrationsAsync(ct);
                
                if (pendingMigrations.Any())
                {
                    unhealthyTenants.Add(tenant.Identifier);
                }
            }

            if (unhealthyTenants.Any())
            {
                return HealthCheckResult.Degraded(
                    $"Tenants with pending migrations: {string.Join(", ", unhealthyTenants)}");
            }

            return HealthCheckResult.Healthy(
                "All tenant databases are up to date");
        }
        catch (Exception ex)
        {
            return HealthCheckResult.Unhealthy(
                "Failed to check tenant migrations", ex);
        }
    }
}
Register the custom health check: 
services.AddHealthChecks()
    .AddCheck<TenantMigrationsHealthCheck>(
        "tenant-migrations",
        HealthStatus.Degraded);

​
Health Status Levels

ASP.NET Core provides three health status levels:
​
Healthy
HealthStatus
The component is functioning correctly. Returns 200 OK.
​
Degraded
HealthStatus
The component is functioning but not optimally (e.g., high latency, non-critical failures). Returns 200 OK.
​
Unhealthy
HealthStatus
The component is not functioning. Returns 503 Service Unavailable.

​
Kubernetes Integration

Configure Kubernetes probes to use the health check endpoints:
deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: fsh-api
spec:
  template:
    spec:
      containers:
      - name: api
        image: fsh-api:latest
        ports:
        - containerPort: 8080
        livenessProbe:
          httpGet:
            path: /health/live
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 10
          timeoutSeconds: 5
          failureThreshold: 3
        readinessProbe:
          httpGet:
            path: /health/ready
            port: 8080
          initialDelaySeconds: 15
          periodSeconds: 10
          timeoutSeconds: 5
          failureThreshold: 3

​
Probe Configuration

1

Liveness Probe

Kubernetes restarts the pod if the liveness probe fails. Use /health/live to detect if the process is alive.
2

Readiness Probe

Kubernetes removes the pod from the load balancer if the readiness probe fails. Use /health/ready to check dependencies.
3

Startup Probe

(Optional) Use a startup probe for slow-starting applications to prevent premature liveness probe failures.

​
Monitoring and Alerting

Integrate health checks with monitoring tools:

​
Prometheus

Expose health check metrics: 
services.AddHealthChecks()
    .AddCheck<DatabaseHealthCheck>("database")
    .ForwardToPrometheus();

​
Grafana

Create dashboards to visualize health check results: 
# Health check status (1 = healthy, 0 = unhealthy)
health_check_status{name="database"}

# Health check duration
health_check_duration_seconds{name="database"}

​
DataDog

Use synthetic monitoring to periodically check health endpoints: 
curl -X GET https://api.example.com/health/ready

​
Best Practices

Liveness checks should only verify the process is running. Don’t check external dependencies.
Readiness checks should verify all critical dependencies (database, cache, external APIs).
Configure health check timeouts to avoid false negatives. A slow check is better than a failed check.
Include useful diagnostic information in health check responses (e.g., error messages, latencies).
Set up alerts when health checks fail to detect issues early.

​
Testing Health Checks

Write tests to verify health checks work correctly: 
[Fact]
public async Task HealthCheck_Ready_ReturnsHealthy()
{
    // Arrange
    var client = _factory.CreateClient();

    // Act
    var response = await client.GetAsync("/health/ready");

    // Assert
    response.EnsureSuccessStatusCode();
    var content = await response.Content.ReadFromJsonAsync<HealthResult>();
    Assert.Equal("Healthy", content?.Status);
}

[Fact]
public async Task HealthCheck_DatabaseDown_ReturnsUnhealthy()
{
    // Arrange
    var client = _factory
        .WithWebHostBuilder(builder =>
        {
            builder.ConfigureTestServices(services =>
            {
                // Replace DB with failing connection
                services.RemoveAll<DbContextOptions<AppDbContext>>();
                services.AddDbContext<AppDbContext>(options =>
                    options.UseNpgsql("Server=invalid;Database=test;"));
            });
        })
        .CreateClient();

    // Act
    var response = await client.GetAsync("/health/ready");

    // Assert
    Assert.Equal(HttpStatusCode.ServiceUnavailable, response.StatusCode);
}

Observability

Monitor application health with OpenTelemetry

Background Jobs

Add health checks for background job processors

Multi-Tenancy

Check tenant database health

Rate Limiting

Health checks are exempt from rate limiting

Build docs developers (and LLMs) love

Get started for freeTalk to us