search

valkey-io / valkey-doc

Content for website and man pages
Other
23 stars 37 forks source link

Add CLUSTER SLOT-STATS document. #150

Closed kyle-yh-kim closed 1 week ago

kyle-yh-kim commented 5 months ago

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

zuiderkwast commented 1 month ago

@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 commented 1 month ago

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

kyle-yh-kim commented 1 week ago

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 commented 1 week ago

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 commented 1 week ago

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 commented 1 week ago

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 commented 1 week ago

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

kyle-yh-kim commented 1 week ago

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

zuiderkwast commented 1 week ago

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 commented 1 week ago

And Thank you for completing this!