Skip to content

Commit 8597ee7

Browse files
dwdoughertymich-elle-luna
dwdougherty
and
mich-elle-luna
authored
DEV: (cmds) add new hotkey detection commands (#2624)
* DEV: (cmds) add new hotkey detection commands * Apply suggestions from code review Thank you, @mich-elle-luna! Co-authored-by: mich-elle-luna <153109578+mich-elle-luna@users.noreply.github.com> * Major update after API change * Updates per #14742 * Apply review comments --------- Co-authored-by: mich-elle-luna <153109578+mich-elle-luna@users.noreply.github.com>
1 parent 7b98665 commit 8597ee7

11 files changed

Lines changed: 741 additions & 0 deletions

File tree

‎content/commands/hotkeys-get.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
acl_categories:
3+
- '@admin'
4+
- '@slow'
5+
- '@dangerous'
6+
arity: 2
7+
categories:
8+
- docs
9+
- develop
10+
- stack
11+
- oss
12+
- rs
13+
- rc
14+
- oss
15+
- kubernetes
16+
- clients
17+
command_flags:
18+
- admin
19+
- noscript
20+
complexity: O(K) where K is the number of hotkeys returned.
21+
container: HOTKEYS
22+
description: Returns lists of top K hotkeys depending on metrics chosen in HOTKEYS START command.
23+
function: hotkeysCommand
24+
group: server
25+
hidden: false
26+
linkTitle: HOTKEYS GET
27+
railroad_diagram: /images/railroad/hotkeys-get.svg
28+
reply_schema:
29+
oneOf:
30+
- additionalProperties: false
31+
description: Hotkeys report with collection metadata and two sorted lists
32+
properties:
33+
by-cpu-time:
34+
description: Array of hotkeys with CPU time percentages
35+
type: array
36+
by-net-bytes:
37+
description: Array of hotkeys with network throughput percentages
38+
type: array
39+
collection-duration:
40+
type: integer
41+
collection-start-time:
42+
type: integer
43+
type: object
44+
- description: If no tracking is started
45+
type: 'null'
46+
since: 8.6.0
47+
summary: Returns lists of top K hotkeys depending on metrics chosen in HOTKEYS START command.
48+
syntax_fmt: HOTKEYS GET
49+
title: HOTKEYS GET
50+
---
51+
Returns tracking results and metadata from the current or most recent hotkeys tracking session.
52+
53+
This command returns comprehensive information about the hotkeys tracking session, including:
54+
55+
- Tracking metadata (start time, duration, sample ratio, etc.)
56+
- Performance statistics (CPU time, network bytes)
57+
- Lists of top K hotkeys sorted by the metrics specified in `HOTKEYS START`
58+
59+
## Example
60+
61+
```
62+
HOTKEYS GET
63+
1) "tracking-active"
64+
2) (integer) 1
65+
3) "sample-ratio"
66+
4) (integer) 1
67+
5) "selected-slots"
68+
6) (empty array)
69+
7) "all-commands-all-slots-us"
70+
8) (integer) 220
71+
9) "net-bytes-all-commands-all-slots"
72+
10) (integer) 200
73+
11) "collection-start-time-unix-ms"
74+
12) (integer) 1769420604522
75+
13) "collection-duration-ms"
76+
14) (integer) 6408
77+
15) "total-cpu-time-user-ms"
78+
16) (integer) 3
79+
17) "total-cpu-time-sys-ms"
80+
18) (integer) 11
81+
19) "by-cpu-time-us"
82+
20) 1) "x"
83+
2) (integer) 104
84+
3) "y"
85+
4) (integer) 98
86+
5) "z"
87+
6) (integer) 18
88+
```
89+
90+
## Redis Enterprise and Redis Cloud compatibility
91+
92+
| Redis<br />Enterprise | Redis<br />Cloud | <span style="min-width: 9em; display: table-cell">Notes</span> |
93+
|:----------------------|:-----------------|:------|
94+
| <span title="Not supported">&#x274c; Standard</span><br /><span title="Not supported"><nobr>&#x274c; Active-Active</nobr></span> | <span title="Not supported">&#x274c; Standard</span><br /><span title="Not supported"><nobr>&#x274c; Active-Active</nobr></span> | |
95+
96+
## Return information
97+
98+
{{< multitabs id="return-info"
99+
tab1="RESP2"
100+
tab2="RESP3" >}}
101+
102+
One of the following:
103+
104+
**[Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}})** when tracking data is available, containing pairs of field names and values:
105+
106+
- `tracking-active` (integer): 1 if tracking is active, 0 if stopped
107+
- `sample-ratio` (integer): The sampling ratio used during tracking
108+
- `selected-slots` (array): Array of slot numbers being tracked (empty if all slots)
109+
- `sampled-command-selected-slots-us` (integer): Time in microseconds for sampled commands on selected slots (conditional)
110+
- `all-commands-selected-slots-us` (integer): Time in microseconds for all commands on selected slots (conditional)
111+
- `all-commands-all-slots-us` (integer): Time in microseconds for all commands on all slots
112+
- `net-bytes-sampled-commands-selected-slots` (integer): Network bytes for sampled commands on selected slots (conditional)
113+
- `net-bytes-all-commands-selected-slots` (integer): Network bytes for all commands on selected slots (conditional)
114+
- `net-bytes-all-commands-all-slots` (integer): Network bytes for all commands on all slots
115+
- `collection-start-time-unix-ms` (integer): Unix timestamp in milliseconds when tracking started
116+
- `collection-duration-ms` (integer): Duration of tracking in milliseconds
117+
- `used-cpu-sys-ms` (integer): System CPU time used in milliseconds
118+
- `used-cpu-user-ms` (integer): User CPU time used in milliseconds
119+
- `total-net-bytes` (integer): Total network bytes processed
120+
- `by-cpu-time-us` (array): Array of key-time pairs sorted by CPU time in microseconds (if CPU tracking enabled)
121+
- `by-net-bytes` (array): Array of key-bytes pairs sorted by network bytes (if NET tracking enabled)
122+
123+
**[Null reply]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}})** when no tracking has been started or data has been reset.
124+
125+
-tab-sep-
126+
127+
One of the following:
128+
129+
**[Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}})** when tracking data is available, containing pairs of field names and values:
130+
131+
- `tracking-active` (integer): 1 if tracking is active, 0 if stopped
132+
- `sample-ratio` (integer): The sampling ratio used during tracking
133+
- `selected-slots` (array): Array of slot numbers being tracked (empty if all slots)
134+
- `sampled-command-selected-slots-us` (integer): Time in microseconds for sampled commands on selected slots (conditional)
135+
- `all-commands-selected-slots-us` (integer): Time in microseconds for all commands on selected slots (conditional)
136+
- `all-commands-all-slots-us` (integer): Time in microseconds for all commands on all slots
137+
- `net-bytes-sampled-commands-selected-slots` (integer): Network bytes for sampled commands on selected slots (conditional)
138+
- `net-bytes-all-commands-selected-slots` (integer): Network bytes for all commands on selected slots (conditional)
139+
- `net-bytes-all-commands-all-slots` (integer): Network bytes for all commands on all slots
140+
- `collection-start-time-unix-ms` (integer): Unix timestamp in milliseconds when tracking started
141+
- `collection-duration-ms` (integer): Duration of tracking in milliseconds
142+
- `used-cpu-sys-ms` (integer): System CPU time used in milliseconds
143+
- `used-cpu-user-ms` (integer): User CPU time used in milliseconds
144+
- `total-net-bytes` (integer): Total network bytes processed
145+
- `by-cpu-time-us` (array): Array of key-time pairs sorted by CPU time in microseconds (if CPU tracking enabled)
146+
- `by-net-bytes` (array): Array of key-bytes pairs sorted by network bytes (if NET tracking enabled)
147+
148+
**[Null reply]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}})** when no tracking has been started or data has been reset.
149+
150+
{{< /multitabs >}}

‎content/commands/hotkeys-reset.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
acl_categories:
3+
- '@admin'
4+
- '@slow'
5+
- '@dangerous'
6+
arity: 2
7+
categories:
8+
- docs
9+
- develop
10+
- stack
11+
- oss
12+
- rs
13+
- rc
14+
- oss
15+
- kubernetes
16+
- clients
17+
command_flags:
18+
- admin
19+
- noscript
20+
complexity: O(1)
21+
container: HOTKEYS
22+
description: Release the resources used for hotkey tracking.
23+
function: hotkeysCommand
24+
group: server
25+
hidden: false
26+
linkTitle: HOTKEYS RESET
27+
railroad_diagram: /images/railroad/hotkeys-reset.svg
28+
since: 8.6.0
29+
summary: Release the resources used for hotkey tracking.
30+
syntax_fmt: HOTKEYS RESET
31+
title: HOTKEYS RESET
32+
---
33+
Release the resources used for hotkey tracking.
34+
35+
This command can only be executed when hotkey tracking is stopped. It will return an error if tracking is currently active. Use [`HOTKEYS STOP`]({{< relref "/commands/hotkeys-stop" >}}) first to stop tracking, then use `HOTKEYS RESET` to free the allocated resources.
36+
37+
## Redis Enterprise and Redis Cloud compatibility
38+
39+
| Redis<br />Enterprise | Redis<br />Cloud | <span style="min-width: 9em; display: table-cell">Notes</span> |
40+
|:----------------------|:-----------------|:------|
41+
| <span title="Not supported">&#x274c; Standard</span><br /><span title="Not supported"><nobr>&#x274c; Active-Active</nobr></span> | <span title="Not supported">&#x274c; Standard</span><br /><span title="Not supported"><nobr>&#x274c; Active-Active</nobr></span> | |
42+
43+
## Return information
44+
45+
{{< multitabs id="return-info"
46+
tab1="RESP2"
47+
tab2="RESP3" >}}
48+
49+
One of the following:
50+
51+
- [Simple string reply]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}): `OK` when resources are successfully released.
52+
- [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}): when tracking is currently active.
53+
54+
-tab-sep-
55+
56+
One of the following:
57+
58+
- [Simple string reply]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}): `OK` when resources are successfully released.
59+
- [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}): when tracking is currently active.
60+
61+
{{< /multitabs >}}

‎content/commands/hotkeys-start.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
acl_categories:
3+
- '@admin'
4+
- '@slow'
5+
- '@dangerous'
6+
arguments:
7+
- arguments:
8+
- display_text: count
9+
name: count
10+
type: integer
11+
- display_text: cpu
12+
name: cpu
13+
optional: true
14+
token: CPU
15+
type: pure-token
16+
- display_text: net
17+
name: net
18+
optional: true
19+
token: NET
20+
type: pure-token
21+
name: metrics
22+
token: METRICS
23+
type: block
24+
- display_text: k
25+
name: k
26+
optional: true
27+
token: COUNT
28+
type: integer
29+
- display_text: seconds
30+
name: seconds
31+
optional: true
32+
token: DURATION
33+
type: integer
34+
- display_text: ratio
35+
name: ratio
36+
optional: true
37+
token: SAMPLE
38+
type: integer
39+
- arguments:
40+
- display_text: count
41+
name: count
42+
type: integer
43+
- display_text: slot
44+
multiple: true
45+
name: slot
46+
type: integer
47+
name: slots
48+
optional: true
49+
token: SLOTS
50+
type: block
51+
arity: -2
52+
categories:
53+
- docs
54+
- develop
55+
- stack
56+
- oss
57+
- rs
58+
- rc
59+
- oss
60+
- kubernetes
61+
- clients
62+
command_flags:
63+
- admin
64+
- noscript
65+
complexity: O(1)
66+
container: HOTKEYS
67+
description: Starts hotkeys tracking.
68+
function: hotkeysCommand
69+
group: server
70+
hidden: false
71+
linkTitle: HOTKEYS START
72+
railroad_diagram: /images/railroad/hotkeys-start.svg
73+
reply_schema:
74+
const: OK
75+
since: 8.6.0
76+
summary: Starts hotkeys tracking.
77+
syntax_fmt: HOTKEYS START METRICS count [CPU] [NET] [COUNT k] [DURATION seconds] [SAMPLE ratio] [SLOTS count slot [slot ...]]
78+
title: HOTKEYS START
79+
---
80+
Starts hotkeys tracking with specified metrics.
81+
82+
This command initiates a hotkey tracking session. You must specify which metrics to track using the required `METRICS` parameter.
83+
An error is returned if a tracking session is already in progress.
84+
85+
The tracking session continues until manually stopped with [`HOTKEYS STOP`]({{< relref "/commands/hotkeys-stop" >}}) or automatically stopped after the specified duration.
86+
87+
## Arguments
88+
89+
<details open><summary><code>METRICS count [CPU] [NET]</code></summary>
90+
91+
**Required.** Specifies which metrics to track and how many hotkeys to track.
92+
93+
- `count` - The number of metrics to collect (required).
94+
- `CPU` - Track hotkeys by CPU time percentage (optional).
95+
- `NET` - Track hotkeys by network bytes percentage (optional).
96+
97+
At least one of `CPU` or `NET` must be specified.
98+
99+
</details>
100+
101+
## Optional arguments
102+
103+
<details open><summary><code>COUNT</code></summary>
104+
105+
Specifies the value of K for the top-K hotkeys tracking.
106+
107+
</details>
108+
109+
<details open><summary><code>DURATION</code></summary>
110+
111+
The duration in seconds for how long the hotkeys tracking should run. After this time period, tracking will automatically stop. If not specified, tracking continues until manually stopped with `HOTKEYS STOP`.
112+
113+
</details>
114+
115+
<details open><summary><code>SAMPLE</code></summary>
116+
117+
Sampling ratio for probabilistic tracking. Each key is sampled with probability `1/ratio`. Higher values reduce performance impact but may miss some hotkeys. Lower values provide more accurate results but with higher performance cost.
118+
119+
</details>
120+
121+
<details open><summary><code>SLOTS</code></summary>
122+
123+
Specifies which hash slots to track in a cluster environment. Takes a count followed by that many slot numbers. Only keys that hash to the specified slots will be tracked. Useful for tracking hotkeys on specific shards in a Redis cluster. Using `SLOTS` when not in cluster mode will result in an error.
124+
125+
</details>
126+
127+
## Redis Enterprise and Redis Cloud compatibility
128+
129+
| Redis<br />Enterprise | Redis<br />Cloud | <span style="min-width: 9em; display: table-cell">Notes</span> |
130+
|:----------------------|:-----------------|:------|
131+
| <span title="Not supported">&#x274c; Standard</span><br /><span title="Not supported"><nobr>&#x274c; Active-Active</nobr></span> | <span title="Not supported">&#x274c; Standard</span><br /><span title="Not supported"><nobr>&#x274c; Active-Active</nobr></span> | |
132+
133+
## Return information
134+
135+
{{< multitabs id="return-info"
136+
tab1="RESP2"
137+
tab2="RESP3" >}}
138+
139+
One of the following:
140+
141+
- [Simple string]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}) reply: `OK` when tracking is successfully started.
142+
- [Error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}): when invalid parameters are provided.
143+
144+
-tab-sep-
145+
146+
One of the following:
147+
148+
- [Simple string]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}) reply: `OK` when tracking is successfully started.
149+
- [Error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}): when invalid parameters are provided.
150+
151+
{{< /multitabs >}}

0 commit comments

Comments
 (0)