CLUSTER...-REPORTS(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

💖 CLUSTER COUNT-FAILURE-REPORTS — a valkey command manual, but make it bestie-core 💖

okay so this is a page from the Valkey Command Manual and we're talking about a lil cluster command that counts failure reports. it's giving detective energy fr fr 🕵️♀️

✨ NAME ✨

cluster-count-failure-reports — returns the number of active failure reports for a node. and bestie, note this: no new reports are created once the node is marked as failed. periodt.

🌸 SYNOPSIS 🌸

CLUSTER COUNT-FAILURE-REPORTS node-id

that's it. one command, one argument, no drama. 💅

🦋 DESCRIPTION 🦋

so this command returns the number of failure reports for the specified node. and what even are failure reports? okay so they're literally the way Valkey Cluster promotes a PFAIL state (aka "this node is not reachable") up to a FAIL state (aka "the majority of primaries in the cluster agreed, within a window of time, that this node is not reachable"). iconic escalation behaviour honestly.

a few more details, bestie, buckle up:

  • a node flags another node with PFAIL when that node has been not reachable for a time greater than the configured node timeout, which is a fundamental configuration parameter of a Valkey Cluster. like, it's the moment, ok?
  • nodes in PFAIL state get provided in gossip sections of heartbeat packets. gossip!! 💅
  • every time a node processes gossip packets from other nodes, it creates failure reports (and refreshes the TTL if needed), remembering that a given node said another given node is in PFAIL condition. however — once a node has been marked FAIL, additional failure reports are ignored. not me being ignored after getting marked failed 😭
  • each failure report has a time to live of two times the node timeout time. so it's on a lil timer, lowkey.
  • if at a given time a node has another node flagged with PFAIL, and at the same time collected the majority of other primary nodes' failure reports about this node (including itself if it is a primary), then it elevates the failure state of the node from PFAIL to FAIL, and broadcasts a message forcing all the nodes that can be reached to flag the node as FAIL. main character node making executive decisions, we love to see it 👑

so this command returns the number of failure reports for the current node which are currently not expired — meaning received within two times the node timeout time. and here's the important bit: the count does not include what the node we are asking this count believes about the node ID we pass as argument. the count only includes the failure reports the node received from other nodes. no self-reporting, no cap.

and ngl, this command is mainly useful for debugging, for when the failure detector of Valkey Cluster is not operating as we believe it should. it's giving "why are you acting like this" energy 🙈

💜 REPLY 💜

valkey-protocol(7) Integer reply: the number of active failure reports for the node. a whole number, that's the whole vibe. ✨

🎀 COMPLEXITY 🎀

O(N) where N is the number of failure reports

🌈 ACL CATEGORIES 🌈

@admin @dangerous @slow

bestie this one is dangerous and slow and admin-only, so like… know what you're doing, okay? 🫶

⭐ HISTORY ⭐

  • Available since: 3.0.0
  • Changed in 9.0.0: Ignore additional failure reports for a node which has been marked as failed.

👑 SEE ALSO 👑

the whole squad, fr fr:

asking(3valkey), cluster(3valkey), cluster-addslots(3valkey), cluster-addslotsrange(3valkey), cluster-bumpepoch(3valkey), cluster-cancelslotmigrations(3valkey), cluster-countkeysinslot(3valkey), cluster-delslots(3valkey), cluster-delslotsrange(3valkey), cluster-failover(3valkey), cluster-flushslots(3valkey), cluster-forget(3valkey), cluster-getkeysinslot(3valkey), cluster-getslotmigrations(3valkey), cluster-help(3valkey), cluster-info(3valkey), cluster-keyslot(3valkey), cluster-links(3valkey), cluster-meet(3valkey), cluster-migrateslots(3valkey), cluster-myid(3valkey), cluster-myshardid(3valkey), cluster-nodes(3valkey), cluster-replicas(3valkey), cluster-replicate(3valkey), cluster-reset(3valkey), cluster-saveconfig(3valkey), cluster-set-config-epoch(3valkey), cluster-setslot(3valkey), cluster-shards(3valkey), cluster-slot-stats(3valkey), cluster-slots(3valkey), cluster-syncslots(3valkey), readonly(3valkey), readwrite(3valkey)

and that's the tea, bestie 🍓 this page is from 9.0.0, dated 2025-10-21, and it lives in the CLUSTER...-REPORTS(3valkey) corner of the manual. go forth and count those failure reports, you absolute icon 💅✨

📦 where this page comes from