Add CLUSTER SLOT-STATS document (#150)

Docs for CLUSTER SLOT-STATS, with key-count, cpu-usec, network-bytes-in,
and network-bytes-out metrics.

- valkey-io/valkey#351
- valkey-io/valkey#712
- valkey-io/valkey#720

---------

Signed-off-by: Kyle Kim <[email protected]>
Signed-off-by: Madelyn Olson <[email protected]>
Signed-off-by: Viktor Söderqvist <[email protected]>
Co-authored-by: Madelyn Olson <[email protected]>
Co-authored-by: Viktor Söderqvist <[email protected]>

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
+```

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."
   ],

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."
   ],