diff --git a/commands/cluster-slot-stats.md b/commands/cluster-slot-stats.md new file mode 100644 index 00000000..ea773a97 --- /dev/null +++ b/commands/cluster-slot-stats.md @@ -0,0 +1,96 @@ +Returns an array of slot usage statistics for slots assigned to the current shard. +The command is suitable for Valkey Cluster users aiming to assess general slot usage trends, identify hot / cold slots, migrate slots for a balanced cluster workload, and / or re-write application logic to better utilize slots. + +The following statistics are supported: + +* `key-count` -- Number of keys residing in a given slot. +* `cpu-usec` -- Amount of CPU time (in microseconds) spent on a given slot. +* `network-bytes-in` -- Amount of network ingress (in bytes) received for given slot. +* `network-bytes-out` -- Amount of network egress (in bytes) sent out for given slot. + +## Options + +* `ORDERBY` -- Returns an ordered slot statistics based on the specified statistic and sub-arguments to identify hot / cold slots across the cluster. Either `ASC` or `DESC` modifiers can be used. In the event of a tie in the stats, ascending slot number is used as a tie breaker. +* `SLOTSRANGE` -- Returns slot statistics based on the slots range provided for pagination. The range is inclusive. The response is ordered in ascending slot number. + +## Examples + +### Response in RESP2 + +For `ORDERBY`: +``` +> CLUSTER SLOT-STATS ORDERBY KEY-COUNT LIMIT 2 DESC +1) 1) (integer) 12426 + 2) 1) "key-count" + 2) (integer) 45 + 3) "cpu-usec" + 4) (integer) 0 + 5) "network-bytes-in" + 6) (integer) 0 + 7) "network-bytes-out" + 8) (integer) 0 +2) 1) (integer) 13902 + 2) 1) "key-count" + 2) (integer) 20 + 3) "cpu-usec" + 4) (integer) 0 + 5) "network-bytes-in" + 6) (integer) 0 + 7) "network-bytes-out" + 8) (integer) 0 +``` + +For `SLOTSRANGE`: +``` +> CLUSTER SLOT-STATS SLOTSRANGE 0 1 +1) 1) (integer) 0 + 2) 1) "key-count" + 2) (integer) 0 + 3) "cpu-usec" + 4) (integer) 0 + 5) "network-bytes-in" + 6) (integer) 0 + 7) "network-bytes-out" + 8) (integer) 0 +2) 1) (integer) 1 + 2) 1) "key-count" + 2) (integer) 0 + 3) "cpu-usec" + 4) (integer) 0 + 5) "network-bytes-in" + 6) (integer) 0 + 7) "network-bytes-out" + 8) (integer) 0 +``` + +### Response in RESP3 + +For `ORDERBY`: +``` +> CLUSTER SLOT-STATS ORDERBY KEY-COUNT LIMIT 2 DESC +1) 1) (integer) 12426 + 2) 1# "key-count" => (integer) 45 + 2# "cpu-usec" => (integer) 0 + 3# "network-bytes-in" => (integer) 0 + 4# "network-bytes-out" => (integer) 0 +2) 1) (integer) 13902 + 2) 1# "key-count" => (integer) 20 + 2# "cpu-usec" => (integer) 0 + 3# "network-bytes-in" => (integer) 0 + 4# "network-bytes-out" => (integer) 0 +``` + +For `SLOTSRANGE`: +``` +> CLUSTER SLOT-STATS SLOTSRANGE 0 1 +1) 1) (integer) 0 + 2) 1# "key-count" => (integer) 0 + 2# "cpu-usec" => (integer) 0 + 3# "network-bytes-in" => (integer) 0 + 4# "network-bytes-out" => (integer) 0 +2) 1) (integer) 1 + 2) 1# "key-count" => (integer) 0 + 2# "cpu-usec" => (integer) 0 + 3# "network-bytes-in" => (integer) 0 + 4# "network-bytes-out" => (integer) 0 +``` diff --git a/resp2_replies.json b/resp2_replies.json index d57e8877..f93f0ac4 100644 --- a/resp2_replies.json +++ b/resp2_replies.json @@ -291,6 +291,9 @@ "CLUSTER SLOTS": [ "[Array reply](../topics/protocol.md#arrays): nested list of slot ranges with networking information." ], + "CLUSTER SLOT-STATS": [ + "[Array reply](../topics/protocol.md#arrays): nested list of slot usage statistics." + ], "COMMAND": [ "[Array reply](../topics/protocol.md#arrays): a nested list of command details. The order of the commands in the array is random." ], diff --git a/resp3_replies.json b/resp3_replies.json index dfcd1145..fc62d1c3 100644 --- a/resp3_replies.json +++ b/resp3_replies.json @@ -291,6 +291,9 @@ "CLUSTER SLOTS": [ "[Array reply](../topics/protocol.md#arrays): nested list of slot ranges with networking information." ], + "CLUSTER SLOT-STATS": [ + "[Array reply](../topics/protocol.md#arrays): nested list of slot usage statistics." + ], "COMMAND": [ "[Array reply](../topics/protocol.md#arrays): a nested list of command details. The order of the commands in the array is random." ],