CLUSTER SLOT-STATS

CLUSTER SLOT-STATS shows per-slot figures for the slots of the receiving node’s shard (on a replica, its primary’s slots). Use it to find hot slots: the ones with the most keys, CPU time or traffic, and to decide which slots to move when you rebalance.

SLOTSRANGE reports the shard’s slots in the inclusive range, in slot order. ORDERBY reports all of the shard’s slots sorted by one metric, largest first by default (ties by slot number), and LIMIT keeps only the first ones.

Metrics

Metric	Meaning	Reported
key-count	Keys in the slot, in every database. An expired key counts until it is deleted.	Always
cpu-usec	Microseconds spent running commands on the slot’s keys (a transaction or script counts with its EXEC, EVAL or FCALL)	While cluster-slot-stats-enabled includes cpu
network-bytes-in	Bytes of the commands sent for the slot	While it includes net
network-bytes-out	Bytes of the replies, plus the writes sent on to replicas	While it includes net
memory-bytes	An estimate of the memory the slot’s keys use	While it includes mem (which can only be turned on at startup)

cluster-slot-stats-enabled takes yes (all three), no, or one or more of cpu, net and mem. A command that names no key counts for no slot. A slot’s CPU and network figures start again from 0 when the slot changes owner on this node, and for every slot on CONFIG RESETSTAT and CLUSTER RESET.

Options

Option	Effect
SLOTSRANGE start-slot end-slot	The shard’s slots from start-slot to end-slot.
ORDERBY metric	Sort by a metric that is currently reported.
LIMIT limit	Return at most limit slots, from 1 to 16384 (default: all).
ASC / DESC	Smallest first, or largest first (the default).

Return value

An array with one entry per slot. Each entry is a two-element array: the slot number (integer), and a map of metric names to integers (a flat array of pairs in RESP2). The metrics that are reported appear in this order: key-count, memory-bytes, cpu-usec, network-bytes-in, network-bytes-out.

Case	Error
Slot not from 0 to 16383	ERR Invalid or out of range slot
Range starts after it ends	ERR Start slot number <start> is greater than end slot number <end>
Unknown metric, or one not reported now	ERR Unrecognized sort metric for ORDERBY.
LIMIT outside 1 to 16384	ERR Limit has to lie in between 1 and 16384 (maximum number of slots).
LIMIT, or ASC/DESC, given twice	ERR Multiple filters of the same type are disallowed.
Any other option after ORDERBY	ERR syntax error
Any other form	ERR unknown subcommand or wrong number of arguments for 'SLOT-STATS'. Try CLUSTER HELP.
Cluster mode is off	ERR This instance has cluster support disabled

Examples

127.0.0.1:6379> CONFIG SET cluster-slot-stats-enabled "cpu net"
OK
127.0.0.1:6379> CLUSTER SLOT-STATS SLOTSRANGE 0 1
1) 1) (integer) 0
   2) 1) "key-count"
      2) (integer) 18
      3) "cpu-usec"
      4) (integer) 412
      5) "network-bytes-in"
      6) (integer) 1290
      7) "network-bytes-out"
      8) (integer) 340
2) 1) (integer) 1
   2) 1) "key-count"
      2) (integer) 11
      3) "cpu-usec"
      4) (integer) 97
      5) "network-bytes-in"
      6) (integer) 430
      7) "network-bytes-out"
      8) (integer) 102
127.0.0.1:6379> CLUSTER SLOT-STATS ORDERBY key-count LIMIT 1
1) 1) (integer) 1649
   2) 1) "key-count"
      2) (integer) 2741
      3) "cpu-usec"
      4) (integer) 18044
      5) "network-bytes-in"
      6) (integer) 90211
      7) "network-bytes-out"
      8) (integer) 30876
127.0.0.1:6379> CLUSTER SLOT-STATS ORDERBY memory-bytes
(error) ERR Unrecognized sort metric for ORDERBY.

Compatibility

Same forms, metric names and error strings as Valkey 8 and Redis 8.2, with Redis 8.6’s memory-bytes metric. Redis 7 does not have this subcommand. HotKV estimates memory-bytes, while Redis counts it exactly.

See also

CLUSTER COUNTKEYSINSLOT, CLUSTER SETSLOT, CLUSTER SHARDS

In a cluster: Scaling a cluster