The health check is a PING, and PING says healthy for a full noeviction server and a read-only replica

[AlexeyShalaev]

Measured on 0.1.4 against three redis:7-alpine containers: a healthy primary, a primary started with --maxmemory 1mb --maxmemory-policy noeviction and then filled, and a replica of the healthy one. Each was asked check_async_redis_health and then a write-then-read of one namespaced key with a TTL:

primary                          PING health=True   write+read probe: ok (2.2 ms)
maxmemory 1mb, noeviction, full  PING health=True   write+read probe: OutOfMemoryError: command not allowed when used memory > 'maxmemory'.
replica of the primary           PING health=True   write+read probe: ReadOnlyError: You can't write against a read only replica.
paused primary                   PING health=False  decided in 0.50 s

The check is a PING, and PING answers PONG from a server that cannot take a write: one that is out of memory under noeviction (every cache and idempotency SET fails from now on), and a replica that a failover or a DNS mistake pointed the client at (every write fails, every read is stale). Both are the states in which a service that uses Redis for anything but reads is down, and both report healthy, so readiness stays green and the pods keep taking traffic they cannot serve. Rule 10 says the check "never says maybe"; here it says yes when the answer is no.

What I think it needs: an opt-in deeper probe on both health functions, something like check_async_redis_health(client, *, probe="ping" | "write") with "ping" staying the default so nothing changes for existing callers. The write probe does SET <key_prefix>:health:<uuid> 1 EX <n> followed by GET and DEL (or just the SET with EX and let it expire), and returns False on ReadOnlyError, OutOfMemoryError and any other ResponseError the way it already returns False on connection trouble, still never raising, still inside the socket timeout. The key needs the settings' key_prefix, which the function does not receive today, so either the prefix becomes an argument or the probe key is passed in. On a cluster the write lands on one slot, which is a partial answer; the docs should say so and leave cluster slot coverage (CLUSTER INFO cluster_state:ok) as a separate follow-up rather than fold it in here. Rule 10, the health rows in the API table and the health section of the guide follow.

Lab: health_lab.py in https://github.com/bedrock-python/bedrock-python.github.io/tree/docs/production-python-series/docs/blog/lab/2026-09-07-redis-health-checks.

[AlexeyShalaev]

Reproduced on 0.1.5 with your lab as it is: PING health=True on the full noeviction primary and on the replica, False only for the paused one. The check is a PING, which is a liveness answer being read as a readiness one.

What I am going to do: one keyword-only argument on both health functions, write_key.

await check_async_redis_health(client)                                              # PING, as today
await check_async_redis_health(client, write_key=f"{settings.key_prefix}:health")   # PING, then a write
check_redis_health(client, write_key=f"{settings.key_prefix}:health")               # the sync twin

With write_key given the check still pings first, and then runs SET <write_key> 1 EX 60. It keeps the ping because on a cluster that is one answer per node, and opting into the write should not cost you the all-nodes coverage. True only when both answer; False on ReadOnlyError, OutOfMemoryError or any other RedisError, through the same branch that already turns connection trouble into False plus a warning in the log. It still never raises. Each command has its own socket_timeout, so the worst case is two of them, and a paused server is still decided by the ping alone. No GET and no DEL: OK from SET is the proof that the server takes writes, and EX lets the key expire on its own rather than adding one more command that can fail.

Why not probe="ping" | "write": the write needs a key either way, and this library applies key_prefix to nothing (rule 7, it is a value you carry), so a mode string plus a key is two arguments where the key alone carries the decision. A key present is the opt-in, and there is no probe="write" without a key to reject. Why not a callable probe=: general enough to take the cluster-state check you mention later, but that one is not a write, and I would rather add it on its own terms when there is a design for it than open a hook now.

Boundaries: the Dishka provider's startup check stays a PING. RedisSettingsProtocol has no key_prefix, so threading a key through the provider is a separate decision, not something to bolt on here. On a cluster the write lands on one slot; the docs will say so. Rule 10, the two API rows and the health sections of the guide follow, and a container test for each of the two servers in both flavours.

[AlexeyShalaev]

Shipped in #32, as planned: one keyword-only write_key on both health functions.

await check_async_redis_health(client)                       # PING, exactly as before
await check_async_redis_health(client, write_key="shop:health")
check_redis_health(client, write_key="shop:health")          # the sync twin

Given a key the check still pings first, then runs SET <write_key> 1 EX 60 — WRITE_PROBE_TTL_S, now exported from redis_client_kit.utils. True only when both answer; ReadOnlyError, OutOfMemoryError and anything else the write raises come back as False plus a warning, through the branch that already handled connection trouble, so it still never raises. No GET and no DEL: OK from SET is the proof the server takes writes, and EX lets the key expire on its own.

Your lab's servers, each asked both ways, on the branch:

--- a healthy primary ---
  primary                                    PING health=True   (  2.5 ms)   write_key health=True   (  0.5 ms)

--- a primary at maxmemory with noeviction ---
  maxmemory 1mb, noeviction, full            PING health=True   (  0.2 ms)   write_key health=False  (  0.4 ms)

--- a read-only replica ---
  replica of the primary                     PING health=True   (  6.5 ms)   write_key health=False  (  1.4 ms)

--- the primary, paused ---
  paused primary                             PING health=False  (501.7 ms)   write_key health=False  (503.0 ms)

The PING health column is unchanged from master — no write_key, no write, no second round trip, so nothing moves for a caller who never had this problem. The paused primary is still decided by the ping alone, inside the same socket_timeout.

On your side: pass the key, and build it yourself. key_prefix is still applied to nothing (rule 7), so write_key=f"{settings.key_prefix}:health" is the line. One key, reused every probe, is the intended shape — no UUID, since the point is whether the server accepts a write and the TTL keeps it from outliving the deploy. On a cluster the ping still covers every node and the write reaches the one node owning that key's slot; CLUSTER INFO cluster_state:ok stays the separate follow-up you suggested, and I would rather design it on its own terms than fold it in here.

Integration tests cover both servers in both flavours — a container started with --maxmemory 1mb --maxmemory-policy noeviction and filled until it refuses a write, and one started as redis-server --replicaof primary 6379 synced against a live primary — each asserting the ping still says True and the probe says False. The Dishka provider's startup check stays a PING; it has no key and no settings member to build one from, so that is a separate decision.

Docs: rule 10, the two API rows and the redis_client_kit.utils row, a "common mistakes" block and the errors note on the agents page, the health sections of the quick start and the cluster guide, and the README example.