PollyHealthChecks 1.0.6

PollyHealthChecks

<img src="icon.png" width="100" align="right" />

ASP.NET Core health checks for Polly v8 circuit breakers — expose circuit-breaker state as /health endpoint responses so Kubernetes probes, load balancers, and monitoring dashboards can automatically react to your resilience state.

var stateProvider = new CircuitBreakerStateProvider();

services.AddResiliencePipeline("payments-api", builder =>
    builder.AddCircuitBreaker(new CircuitBreakerStrategyOptions
    {
        StateProvider = stateProvider,
        FailureRatio = 0.5,
        MinimumThroughput = 5,
        BreakDuration = TimeSpan.FromSeconds(30),
    }));

services.AddHealthChecks()
    .AddPollyCircuitBreaker("payments-api", stateProvider);  // ← one line

When the circuit opens, /health returns Unhealthy — Kubernetes stops routing traffic, zero manual intervention required.

Why PollyHealthChecks?

"How do I expose my circuit breaker state in the ASP.NET Core health endpoint?" is one of the most-asked Polly questions. Without this package you must write your own IHealthCheck, wire up CircuitBreakerStateProvider, and map the four circuit states manually. PollyHealthChecks does all of that in a single method call.

Installation

dotnet add package PollyHealthChecks

Targets net6.0, net8.0, and net9.0.

Dependencies: Polly.Core 8.*, Microsoft.Extensions.Diagnostics.HealthChecks 8.*

Quick start

1. Attach a CircuitBreakerStateProvider to your pipeline

using Polly.CircuitBreaker;
using PollyHealthChecks;

var stateProvider = new CircuitBreakerStateProvider();

services.AddResiliencePipeline("downstream-api", builder =>
    builder.AddCircuitBreaker(new CircuitBreakerStrategyOptions
    {
        StateProvider  = stateProvider,
        FailureRatio   = 0.5,
        SamplingDuration  = TimeSpan.FromSeconds(10),
        MinimumThroughput = 5,
        BreakDuration  = TimeSpan.FromSeconds(30),
    }));

2. Register the health check

services.AddHealthChecks()
    .AddPollyCircuitBreaker("downstream-api", stateProvider);

3. Map the health endpoint

app.MapHealthChecks("/health");

State mapping

Kubernetes liveness & readiness probes

Use tags to split circuit breaker health into separate liveness and readiness probes:

services.AddHealthChecks()
    .AddPollyCircuitBreaker("payments-api",   paymentsStateProvider,  tags: ["ready"])
    .AddPollyCircuitBreaker("inventory-api",  inventoryStateProvider, tags: ["ready"])
    .AddPollyCircuitBreaker("auth-api",       authStateProvider,      tags: ["live", "ready"]);

// Liveness — just the critical auth circuit
app.MapHealthChecks("/health/live",  new HealthCheckOptions
{
    Predicate = r => r.Tags.Contains("live"),
});

// Readiness — all dependency circuits
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = r => r.Tags.Contains("ready"),
});

Kubernetes deployment:

livenessProbe:
  httpGet:
    path: /health/live
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health/ready
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 5

Multiple circuit breakers

Monitor every downstream dependency independently:

services.AddHealthChecks()
    .AddPollyCircuitBreaker("payments-api",   paymentsStateProvider)
    .AddPollyCircuitBreaker("inventory-api",  inventoryStateProvider, failureStatus: HealthStatus.Degraded)
    .AddPollyCircuitBreaker("auth-api",       authStateProvider,      tags: ["ready", "live"])
    .AddPollyCircuitBreaker("email-service",  emailStateProvider,     failureStatus: HealthStatus.Degraded);

Custom failure status

Demote a non-critical circuit to Degraded so a single open circuit doesn't fail the entire readiness check:

services.AddHealthChecks()
    // Critical — Unhealthy when open (default)
    .AddPollyCircuitBreaker("payments-api", paymentsStateProvider)
    // Non-critical — Degraded when open (app still serves traffic)
    .AddPollyCircuitBreaker("analytics-api", analyticsStateProvider,
        failureStatus: HealthStatus.Degraded);

HealthChecks UI integration

Works out-of-the-box with AspNetCore.HealthChecks.UI:

services.AddHealthChecksUI(opts =>
    opts.AddHealthCheckEndpoint("App", "/health"))
    .AddInMemoryStorage();

services.AddHealthChecks()
    .AddPollyCircuitBreaker("payments-api", paymentsStateProvider)
    .AddPollyCircuitBreaker("inventory-api", inventoryStateProvider);

app.MapHealthChecks("/health", new HealthCheckOptions
{
    ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse,
});
app.MapHealthChecksUI();

Full ASP.NET Core example

var builder = WebApplication.CreateBuilder(args);

var paymentsStateProvider  = new CircuitBreakerStateProvider();
var inventoryStateProvider = new CircuitBreakerStateProvider();

builder.Services.AddResiliencePipeline("payments-api", b =>
    b.AddCircuitBreaker(new CircuitBreakerStrategyOptions
    {
        StateProvider     = paymentsStateProvider,
        FailureRatio      = 0.5,
        MinimumThroughput = 5,
        BreakDuration     = TimeSpan.FromSeconds(30),
    }));

builder.Services.AddResiliencePipeline("inventory-api", b =>
    b.AddCircuitBreaker(new CircuitBreakerStrategyOptions
    {
        StateProvider     = inventoryStateProvider,
        FailureRatio      = 0.5,
        MinimumThroughput = 5,
        BreakDuration     = TimeSpan.FromSeconds(30),
    }));

builder.Services.AddHealthChecks()
    .AddPollyCircuitBreaker("payments-api",   paymentsStateProvider,  tags: ["ready", "live"])
    .AddPollyCircuitBreaker("inventory-api",  inventoryStateProvider, tags: ["ready"]);

var app = builder.Build();
app.MapHealthChecks("/health/live",  new HealthCheckOptions { Predicate = r => r.Tags.Contains("live") });
app.MapHealthChecks("/health/ready", new HealthCheckOptions { Predicate = r => r.Tags.Contains("ready") });
app.Run();

Related packages

Package	Downloads	Description
PollyEFCore		Polly v8 resilience for EF Core queries and SaveChanges
PollyMediatR		Polly v8 pipelines for MediatR request handlers
PollyBackoff		Jitter, linear & custom backoff for Polly v8 retry
PollyChaos		Fault & latency injection (Simmy for Polly v8)
PollyCaching		Cache-aside resilience strategy for Polly v8
PollyBulkhead		Bulkhead / concurrency limiter for Polly v8
PollyOpenTelemetry		OpenTelemetry metrics & tracing for Polly v8

Support

If PollyHealthChecks is useful in your Kubernetes or monitoring setup, consider supporting the project:

💼 Need .NET / cloud-native help? Visit solidqualitysolutions.com for consulting and architecture services.

License

MIT