Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add CLUSTER SLOT-STATS document. #150

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Add CLUSTER SLOT-STATS document. #150

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
65d2006
Add CLUSTER SLOT-STATS document.
kyle-yh-kim Jun 25, 2024
c4f0775
Minor revision.
kyle-yh-kim Jun 26, 2024
3625f09
Minor revision.
kyle-yh-kim Jun 27, 2024
3c6a17e
Minor revision.
kyle-yh-kim Aug 2, 2024
3514037
Update commands/cluster-slot-stats.md
madolson Aug 7, 2024
cfcb41d
Minor revision.
kyle-yh-kim Oct 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 95 additions & 0 deletions commands/cluster-slot-stats.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
`CLUSTER SLOT-STATS` returns an array of slot usage statistics for slots assigned to the current shard.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just realize we kind of use metrics and statistics sort of interchangeably which now bothers me, but maybe it's fine.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. We could consolidate the wording into “stats / statistics” throughout the documentation, given that SLOT-STATS is the chosen name for the command.

Copy link
Contributor

@zuiderkwast zuiderkwast Oct 24, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The command name is the title of the page, so it doesn't need to be here.

Suggested change
`CLUSTER SLOT-STATS` returns an array of slot usage statistics for slots assigned to the current shard.
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 micro-seconds) 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.

## Supported filtering and ordering arguments
There exist two mutually exclusive arguments for controlling the output, namely;

### SLOTSRANGE
Returns slot statistics based on the slots range provided. The range is inclusive.
The `SLOTSRANGE` argument allows for request pagination.
The response is ordered in ascending slot number.
Comment on lines +10 to +16
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The syntax is also inserted automatically above this text, from the JSON file. We should document the options. If they're mutually exclusive, the syntax will display this as < SLOTRANGE xxxx | ORDERBY yyy > so I don't think we need to mention that.

Suggested change
## Supported filtering and ordering arguments
There exist two mutually exclusive arguments for controlling the output, namely;
### SLOTSRANGE
Returns slot statistics based on the slots range provided. The range is inclusive.
The `SLOTSRANGE` argument allows for request pagination.
The response is ordered in ascending slot number.
## Options
* `SLOTSRANGE`: Returns slot statistics based on the slots range provided.
The range is inclusive.
The `SLOTSRANGE` argument allows for request pagination.
The response is ordered in ascending slot number.


##### Response in RESP2
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Level 5 heading under a level 3 heading?

So many levels are not easy to distinguish. The fontsizes will not be different enough. Not to mention the man pages. I think we should not use more than 3 levels.

Let's add an ## Examples heading and move the examples as level 3 headings under that?

I would like to loosely follow the order within the page that's normal for man pages, as described under "Sections within a manual page" on the man-pages.7 man page: https://www.man7.org/linux/man-pages/man7/man-pages.7.html

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

### ORDERBY
The `ORDERBY` argument 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.

##### Response in RESP2
```
> CLUSTER SLOT-STATS ORDERBY KEY-COUNT LIMIT 2 DESC
Comment on lines +56 to +61
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Parameter documentation mixed with examples.

Let's put the parameter descriptions above under ## Options and all the examples below under ## Examples. See the page for the SET command for how options are documented.

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

##### Response in RESP3
```
> CLUSTER SLOT-STATS ORDERBY KEY-COUNT LIMIT 2 DESC
madolson marked this conversation as resolved.
Show resolved Hide resolved
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
```