Implementation:LMCache LMCache Remote Backend Check

Knowledge Sources	LMCache
Domains	Health Monitoring, Storage Backend, Distributed Systems
Last Updated	2026-02-09 00:00 GMT

Overview

RemoteBackendHealthCheck is a health check implementation that verifies the reachability and responsiveness of a remote storage backend by performing periodic ping requests and tracking get-blocking failure counts.

Description

The RemoteBackendHealthCheck class extends the HealthCheck base class and provides a comprehensive health monitoring strategy for RemoteBackend instances. It monitors two failure indicators: consecutive get_blocking failures exceeding a configurable threshold, and ping timeouts to the remote connector. When a failure is detected, the check enters a recovery window defined by waiting_time_for_recovery, during which it performs a put-and-get verification test before resuming normal operation. The class supports two fallback policies: RECOMPUTE (skip all cache operations) and LOCAL_CPU (use local CPU with hot cache).

Usage

Use this class when deploying LMCache with remote storage backends (e.g., Redis, Mooncake) to detect connectivity failures and automatically degrade gracefully. It is instantiated via the create factory method, which scans a LMCacheManager for all RemoteBackend instances and creates a health check for each one.

Code Reference

Source Location

• Repository: LMCache
• File: lmcache/v1/health_monitor/checks/remote_backend_check.py
• Lines: 1-301

Signature

class RemoteBackendHealthCheck(HealthCheck):
    def __init__(self, backend: "RemoteBackend") -> None: ...

    @classmethod
    def create(cls, manager: "LMCacheManager") -> List[HealthCheck]: ...

    def name(self) -> str: ...

    @property
    def fallback_policy(self) -> FallbackPolicy: ...

    def get_bypass_backend_name(self) -> Optional[str]: ...

    def check(self) -> bool: ...

Import

from lmcache.v1.health_monitor.checks.remote_backend_check import RemoteBackendHealthCheck

I/O Contract

Inputs

Name	Type	Required	Description
backend	RemoteBackend	Yes	The remote storage backend instance to monitor for health
manager	LMCacheManager	Yes (for create)	The LMCacheManager instance used by the factory method to discover RemoteBackend instances

Outputs

Name	Type	Description
check()	bool	True if the remote backend is healthy (ping succeeds and get_blocking failures are below threshold), False otherwise
create()	List[HealthCheck]	List of RemoteBackendHealthCheck instances, one per RemoteBackend found in the storage manager
fallback_policy	FallbackPolicy	The configured fallback policy enum (RECOMPUTE or LOCAL_CPU) to apply when the backend is unhealthy
get_bypass_backend_name()	Optional[str]	The backend name to bypass when the health check fails

Usage Examples

# Creating health checks from a manager (factory method)
from lmcache.v1.health_monitor.checks.remote_backend_check import RemoteBackendHealthCheck

health_checks = RemoteBackendHealthCheck.create(manager)
for check in health_checks:
    is_healthy = check.check()
    if not is_healthy:
        print(f"{check.name()} is unhealthy, fallback: {check.fallback_policy}")
        bypass_name = check.get_bypass_backend_name()