🩺 Health Checks¶
CoreSystem.Cache is designed to integrate with the ASP.NET Core Health Checks infrastructure.
The health check can be used to expose the operational state of the cache layer, including the state of the primary provider when an external provider and fallback storage are configured.
❓ Why It Matters¶
In production environments, an external cache provider can become temporarily unavailable.
When fallback support is configured, the framework can switch the current cache operation to the fallback provider while keeping the application running.
A health check can expose this state so monitoring systems can distinguish between:
- A healthy cache infrastructure.
- A degraded cache infrastructure operating with the fallback provider.
🩺 Registering Health Checks¶
Register the ASP.NET Core Health Checks service in the application.
builder.Services.AddHealthChecks();
CoreSystem.Cache itself registers no health check. AddCoreCache() calls
AddCacheDiagnostics(), which registers OpenTelemetry metrics only, so
AddHealthChecks() on its own exposes an endpoint with no cache entry in it.
Health checks come from the provider packages. CoreSystem.Cache.Redis
contributes a check named redis_cache, tagged cache and primary, and it
appears as soon as AddCoreCacheRedis() is called.
🔌 Expose the Health Endpoint¶
Expose the ASP.NET Core health endpoint as usual.
app.MapHealthChecks("/health");
Example:
GET /health
💚 Health States¶
When a health-check implementation reports the cache provider state, the expected operational distinction is:
| Status | Description |
|---|---|
| 🟢 Healthy | The primary cache provider is available. |
| 🟡 Degraded | The primary provider is unavailable and the fallback provider is being used. |
The core package keeps track of the primary state itself, through the internal
IPrimaryHealthStateWriter, which FallbackBehavior calls when a primary
operation throws. The check that surfaces that state to /health is implemented
by the provider package, not by the core — see Redis Health Checks.
🔄 Fallback State¶
When the primary storage fails and a fallback provider exists, FallbackBehavior:
- Marks the primary storage as unavailable.
- Changes the current cache context to the fallback storage.
- Marks the operation with
CacheEntryOptions.Rehydrate. - Executes the operation using the fallback storage.
This state can be used by a health-check implementation to report a degraded cache condition.
🔁 Cache Rehydration¶
When fallback operations are marked with:
CacheEntryOptions.Rehydrate
the cache entry is prepared for rehydration by the recovery components.
Recovery is implemented by CoreSystem.Cache.Rehydration. Its
RehydrationService observes the health checks tagged primary and restores the
tracked entries once the primary reports healthy again after having been
observed unhealthy.
📈 Monitoring¶
The ASP.NET Core health endpoint can be consumed by monitoring and orchestration systems that support Health Checks.
The exact health-check response and provider-state reporting depend on the health-check implementation registered by the application or the corresponding external package.
🧭 Operational Recommendations¶
💚 Healthy¶
The primary cache provider is operating normally.
⚠️ Degraded¶
The primary provider is unavailable and cache operations are using the configured fallback provider.
Recommended actions:
- Verify the external cache provider availability.
- Review provider logs.
- Check network connectivity.
- Check provider authentication and configuration.
Once the primary provider becomes available again, the recovery components can rehydrate entries marked for recovery.
✅ Best Practices¶
- Expose a health endpoint for production applications.
- Monitor degraded states instead of only failures.
- Combine Health Checks with OpenTelemetry metrics.
- Use readiness probes when deploying to orchestration platforms.
- Configure alerts for prolonged degraded states.