Add CLUSTER SLOT-STATS document.

- Valkey PR link; valkey-io/valkey#351.

Signed-off-by: Kyle Kim <[email protected]>

commands.json

@@ -3095,6 +3095,87 @@
             "nondeterministic_output"
         ]
     },
+    "CLUSTER SLOT-STATS": {
+        "summary": "Returns an array of slot usage statistics for slots assigned to the current shard.",
+        "since": "8.0.0",
+        "group": "cluster",
+        "complexity": "O(N) where N is the total number of slots based on arguments. O(N log N) with ORDERBY subcommand.",
+        "history": [
+            [
+                "8.0.0",
+                "Initial release with key-count metric support."
+            ]
+        ],
+        "acl_categories": [
+            "@slow"
+        ],
+        "arity": -4,
+        "command_flags": [
+            "stale",
+            "loading"
+        ],
+        "hints": [
+            "nondeterministic_output",
+            "request_policy:all_shards"
+        ],
+        "arguments": [
+            {
+                "name": "filter",
+                "type": "oneof",
+                "arguments": [
+                    {
+                        "token": "SLOTSRANGE",
+                        "name": "slotsrange",
+                        "type": "block",
+                        "arguments": [
+                            {
+                                "name": "start-slot",
+                                "type": "integer"
+                            },
+                            {
+                                "name": "end-slot",
+                                "type": "integer"
+                            }
+                        ]
+                    },
+                    {
+                        "token": "ORDERBY",
+                        "name": "orderby",
+                        "type": "block",
+                        "arguments": [
+                            {
+                                "name": "metric",
+                                "type": "string"
+                            },
+                            {
+                                "token": "LIMIT",
+                                "name": "limit",
+                                "type": "integer",
+                                "optional": true
+                            },
+                            {
+                                "name": "order",
+                                "type": "oneof",
+                                "optional": true,
+                                "arguments": [
+                                    {
+                                        "name": "asc",
+                                        "type": "pure-token",
+                                        "token": "ASC"
+                                    },
+                                    {
+                                        "name": "desc",
+                                        "type": "pure-token",
+                                        "token": "DESC"
+                                    }
+                                ]
+                            }
+                        ]
+                    }
+                ]
+            }
+        ]
+    },
     "COMMAND": {
         "summary": "Returns detailed information about all commands.",
         "since": "2.8.13",

commands/cluster-slot-stats.md

@@ -0,0 +1,42 @@
+`CLUSTER SLOT-STATS` 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.
+
+As of now, the following metrics are supported:
+* key-count
+
+## Supported arguments
+There exist two mutually exclusive arguments, namely;
+
+### SLOTSRANGE
+Returns slot statistics based on the slots range provided.
+The `SLOTSRANGE` argument allows for request pagination.
+
+```
+> CLUSTER SLOT-STATS SLOTSRANGE 0 2
+> 1) (integer) 0
+> 2) 1) "key-count"
+>    2) (integer) 0
+> 3) (integer) 1
+> 4) 1) "key-count"
+>    2) (integer) 0
+> 5) (integer) 2
+> 6) 1) "key-count"
+>    2) (integer) 0
+```
+
+### ORDERBY
+Orders slot statistics based on the provided metric. Right now, only `key-count` is available.
+The `ORDERBY` argument allows for the user to identify hot / cold slots across the cluster.
+
+```
+> CLUSTER SLOT-STATS ORDERBY KEY-COUNT LIMIT 3 DESC
+> 1) (integer) 12426
+> 2) 1) "key-count"
+>    2) (integer) 45
+> 3) (integer) 13902
+> 4) 1) "key-count"
+>    2) (integer) 20
+> 5) (integer) 2704
+> 6) 1) "key-count"
+>    2) (integer) 11
+```