Add CLUSTER SLOT-STATS document.

[kyle-yh-kim]

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

• Introduce CLUSTER SLOT-STATS command (#20). valkey#351
• Add cpu-usec metric support under CLUSTER SLOT-STATS command (#20). valkey#712
• Add network-bytes-in and network-bytes-out metric support under CLUSTER SLOT-STATS command (#20) valkey#720

[madolson]

Sorry for the delay, finally really looked through everything and left a few comments about clarity.

[zuiderkwast]

@kyle-yh-kim Will you update this PR? It would be good to have docs for the feature. 8.0 is already released.

[kyle-yh-kim]

Thanks for the reminder. All comments have been addressed, now awaiting for approval.

[zuiderkwast]

Thanks! I have some comments about the structure of the page.

When we generate the man pages, stuff like Reply, ACL categories and History are inserted above Examples. (It looks for certain headings.)

Example man page HSET screenshot

[kyle-yh-kim]

Thanks for your suggestions, I agree with following the existing man page standards.

Attached below is the new man page for cluster-slot-stats.3valkey, let me know what you think.

CLUSTER-SLOT-STATS(3valkey)               Valkey Command Manual              CLUSTER-SLOT-STATS(3valkey)

NAME
       cluster-slot-stats - Return an array of slot usage statistics for slots assigned to the current
       node.

SYNOPSIS
       CLUSTER SLOT-STATS SLOTSRANGE start-slot end-slot
       CLUSTER SLOT-STATS ORDERBY metric [LIMIT limit] [ASC | DESC]

DESCRIPTION
       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.

       The following statistics are supported:

       • KEY-COUNT – Number of keys residing in a given slot.

       • CPU-USEC micro-seconds – Amount of cpu time (in micro-seconds) spent on a given slot.

       • NETWORK-BYTES-IN bytes – Amount of network ingress (in bytes) received for given slot.

       • NETWORK-BYTES-OUT bytes – 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.  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.

COMPLEXITY
       O(N) where N is the total number of slots based on arguments.  O(N*log(N)) with ORDERBY
       subcommand.

ACL CATEGORIES
       @slow

HISTORY
       • Available since: 8.0.0

EXAMPLES
   Response in RESP2
              > 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

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

              > 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

SEE ALSO
       asking(3valkey), cluster(3valkey), cluster-addslots(3valkey), cluster-addslotsrange(3valkey),
       cluster-bumpepoch(3valkey), cluster-count-failure-reports(3valkey),
       cluster-countkeysinslot(3valkey), cluster-delslots(3valkey), cluster-delslotsrange(3valkey),
       cluster-failover(3valkey), cluster-flushslots(3valkey), cluster-forget(3valkey),
       cluster-getkeysinslot(3valkey), cluster-help(3valkey), cluster-info(3valkey),
       cluster-keyslot(3valkey), cluster-links(3valkey), cluster-meet(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), readonly(3valkey), readwrite(3valkey).

Valkey Documentation                           2024-11-16                    CLUSTER-SLOT-STATS(3valkey)

[zuiderkwast]

I remember we have two files that describe the reply types of each command:

resp2_replies.json
resp3_replies.json

They are easily forgotten because the website still doesn't display this information. It's used in the man page version though.

[kyle-yh-kim]

New man page has been attached below;

CLUSTER-SLOT-STATS(3valkey)                      Valkey Command Manual                      CLUSTER-SLOT-STATS(3valkey)

NAME
       cluster-slot-stats - Return an array of slot usage statistics for slots assigned to the current node.

SYNOPSIS
       CLUSTER SLOT-STATS SLOTSRANGE start-slot end-slot
       CLUSTER SLOT-STATS ORDERBY metric [LIMIT limit] [ASC | DESC]

DESCRIPTION
       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.

REPLY
   RESP2
       valkey-protocol(7) Array reply: nested list of slot usage statistics.

COMPLEXITY
       O(N) where N is the total number of slots based on arguments.  O(N*log(N)) with ORDERBY subcommand.

ACL CATEGORIES
       @slow

HISTORY
       • Available since: 8.0.0

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

SEE ALSO
       asking(3valkey), cluster(3valkey), cluster-addslots(3valkey), cluster-addslotsrange(3valkey),
       cluster-bumpepoch(3valkey), cluster-count-failure-reports(3valkey), cluster-countkeysinslot(3valkey),
       cluster-delslots(3valkey), cluster-delslotsrange(3valkey), cluster-failover(3valkey),
       cluster-flushslots(3valkey), cluster-forget(3valkey), cluster-getkeysinslot(3valkey), cluster-help(3valkey),
       cluster-info(3valkey), cluster-keyslot(3valkey), cluster-links(3valkey), cluster-meet(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), readonly(3valkey), readwrite(3valkey).

Valkey Documentation                                   2024-11-18                           CLUSTER-SLOT-STATS(3valkey)

[zuiderkwast]

Good, but add it to resp3 replies too, please. Usually all commands are in both files. (If the content is identical, the man page will detect that and not include it twice.)

[kyle-yh-kim]

Apologies, I've now added CLUSTER SLOT-STATS entries under both resp2_replies.json and resp3_replies.json.

[zuiderkwast]

Great! I'm happy now.

[kyle-yh-kim]

Nice, thanks a lot for your feedback and review :)
When will it take effect on our documentation page?

[zuiderkwast]

Ask the other Kyle. :)

I wish we could make it automatic when we merge a doc PR. That's how it used to work in Redis, but Kyle doesn't want that. I think he wants to test every change manually before deploying.

[zuiderkwast]

And Thank you for completing this!