Philiprehberger.HealthCheckKit

Composable health checks for ASP.NET Core with built-in URL, TCP, DNS, certificate, disk, and memory checks.

Installation

dotnet add package Philiprehberger.HealthCheckKit

Usage

using Philiprehberger.HealthCheckKit;

builder.Services.AddHealthCheckKit(checks => checks
    .AddUrlCheck("https://api.example.com/health")
    .AddTcpCheck("db-server", 5432)
    .AddDnsCheck("api.example.com")
    .AddCertificateCheck("api.example.com")
    .AddDiskSpaceCheck(minimumFreeBytes: 500_000_000)
    .AddMemoryCheck(maximumBytes: 1_073_741_824));

app.MapHealthChecks("/health");

TCP Port Connectivity

using Philiprehberger.HealthCheckKit;

builder.Services.AddHealthCheckKit(checks => checks
    .AddTcpCheck("db-server", 5432)
    .AddTcpCheck("redis", 6379, timeout: TimeSpan.FromSeconds(2)));

DNS Resolution

using Philiprehberger.HealthCheckKit;

builder.Services.AddHealthCheckKit(checks => checks
    .AddDnsCheck("api.example.com")
    .AddDnsCheck("storage.example.com"));

SSL Certificate Expiration

using Philiprehberger.HealthCheckKit;

builder.Services.AddHealthCheckKit(checks => checks
    .AddCertificateCheck("api.example.com")
    .AddCertificateCheck("payments.example.com", warningDays: 14));

Composite Health Report

using Philiprehberger.HealthCheckKit;

var runner = new HealthCheckKitBuilder()
    .AddUrlCheck("https://api.example.com/health")
    .AddTcpCheck("db-server", 5432)
    .AddDnsCheck("api.example.com")
    .BuildRunner();

var report = await runner.RunAllAsync();

Console.WriteLine($"Status: {report.Status}, Total: {report.TotalElapsed.TotalMilliseconds}ms");

foreach (var entry in report.Entries)
{
    Console.WriteLine($"  {entry.Name}: {entry.Result.Status} ({entry.Duration.TotalMilliseconds}ms)");
}

Built-in Checks

using Philiprehberger.HealthCheckKit;

// URL check — Healthy on 2xx, Degraded on timeout, Unhealthy otherwise
builder.Services.AddHealthCheckKit(checks => checks
    .AddUrlCheck("https://downstream-service.example.com/ping"));

// Disk space check — Unhealthy when free space drops below threshold
builder.Services.AddHealthCheckKit(checks => checks
    .AddDiskSpaceCheck(minimumFreeBytes: 500_000_000));

// Memory check — Unhealthy when managed memory exceeds limit
builder.Services.AddHealthCheckKit(checks => checks
    .AddMemoryCheck(maximumBytes: 1_073_741_824));

Ping and Process Memory

using Philiprehberger.HealthCheckKit;

builder.Services.AddHealthCheckKit(checks => checks
    .AddPingCheck("api.example.com")
    .AddProcessMemoryCheck(maximumWorkingSetBytes: 2_147_483_648));

Tagging Checks

Each AddXxxCheck accepts a params string[] tags argument that is surfaced on the report entry:

using Philiprehberger.HealthCheckKit;

var runner = new HealthCheckKitBuilder()
    .AddTcpCheck("db", 5432, tags: new[] { "infra", "critical" })
    .AddUrlCheck("https://api.example.com/health", tags: new[] { "api" })
    .BuildRunner();

runner.PerCheckTimeout = TimeSpan.FromSeconds(10);
var report = await runner.RunAllAsync();

foreach (var entry in report.Entries)
{
    Console.WriteLine($"{entry.Name} [{string.Join(',', entry.Tags)}]: {entry.Result.Status}");
}

Custom Checks

using Microsoft.Extensions.Diagnostics.HealthChecks;
using Philiprehberger.HealthCheckKit;

builder.Services.AddHealthCheckKit(checks => checks
    .AddCustomCheck("database", async cancellationToken =>
    {
        var isHealthy = await CheckDatabaseConnectionAsync(cancellationToken);
        return isHealthy
            ? HealthCheckResult.Healthy("Database is reachable.")
            : HealthCheckResult.Unhealthy("Database is unreachable.");
    }));

API

HealthCheckKitBuilder

Method	Description
AddUrlCheck(string url, TimeSpan? timeout = null, params string[] tags)	Adds an HTTP GET check for the given URL
AddTcpCheck(string host, int port, TimeSpan? timeout = null, params string[] tags)	Adds a TCP port connectivity check
AddDnsCheck(string hostname, params string[] tags)	Adds a DNS resolution check
AddCertificateCheck(string host, int warningDays = 30, params string[] tags)	Adds an SSL certificate expiration check
AddDiskSpaceCheck(long minimumFreeBytes, string? drivePath = null, params string[] tags)	Adds a disk free space check
AddMemoryCheck(long maximumBytes, params string[] tags)	Adds a managed memory usage check
AddProcessMemoryCheck(long maximumWorkingSetBytes, params string[] tags)	Adds a process working-set memory check
AddPingCheck(string host, TimeSpan? timeout = null, params string[] tags)	Adds an ICMP ping reachability check
AddCustomCheck(string name, Func<CancellationToken, Task<HealthCheckResult>> check, params string[] tags)	Adds a custom delegate-based check
BuildRunner()	Creates a HealthCheckRunner for standalone execution

HealthCheckRunner

Method / Property	Description
RunAllAsync(CancellationToken cancellationToken = default)	Runs all checks and returns a composite HealthReport
PerCheckTimeout	Per-check timeout (default 30s); a hung check is reported as Unhealthy

HealthReport

Property	Type	Description
Status	HealthReportStatus	Overall status: Healthy, Degraded, or Unhealthy
Entries	IReadOnlyList<HealthCheckEntry>	Individual check results
TotalElapsed	TimeSpan	Total time to run all checks

HealthCheckEntry

Property	Type	Description
Name	string	Name of the health check
Result	HealthCheckResult	The check result with status and description
Duration	TimeSpan	How long the check took to execute
Tags	IReadOnlyList<string>	Tags associated with the check

ServiceCollectionExtensions

Method	Description
AddHealthCheckKit(this IServiceCollection services, Action<HealthCheckKitBuilder> configure)	Registers all configured health checks with the DI container

TcpHealthCheck

Member	Description
TcpHealthCheck(string host, int port, TimeSpan? timeout = null)	Creates a TCP connectivity check with optional timeout (default 5s)
CheckHealthAsync(context, cancellationToken)	Returns Healthy if connection succeeds, Unhealthy otherwise

DnsHealthCheck

Member	Description
DnsHealthCheck(string hostname)	Creates a DNS resolution check for the given hostname
CheckHealthAsync(context, cancellationToken)	Returns Healthy if resolution returns addresses, Unhealthy otherwise

CertificateHealthCheck

Member	Description
CertificateHealthCheck(string host, int warningDays = 30)	Creates an SSL certificate expiration check
CheckHealthAsync(context, cancellationToken)	Returns Healthy, Degraded (expiring soon), or Unhealthy (expired/failed)

UrlHealthCheck

Member	Description
UrlHealthCheck(string url, TimeSpan? timeout = null)	Creates a URL health check with optional timeout (default 5s)
CheckHealthAsync(context, cancellationToken)	Returns Healthy (2xx), Degraded (timeout), or Unhealthy

DiskSpaceHealthCheck

Member	Description
DiskSpaceHealthCheck(long minimumFreeBytes, string drivePath = "/")	Creates a disk space check for the given drive
CheckHealthAsync(context, cancellationToken)	Returns Healthy if free space meets minimum, Unhealthy otherwise

MemoryHealthCheck

Member	Description
MemoryHealthCheck(long maximumBytes)	Creates a memory check with the given byte limit
CheckHealthAsync(context, cancellationToken)	Returns Healthy if within limit, Unhealthy otherwise

Development

dotnet build src/Philiprehberger.HealthCheckKit.csproj --configuration Release

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT