From c2d5ede8b04552b1591d6104586758588f7e5fcd Mon Sep 17 00:00:00 2001 From: "David W. Dougherty" Date: Mon, 12 Jan 2026 09:05:18 -0800 Subject: [PATCH 1/5] DEV: (cmds) add new hotkey detection commands --- content/commands/hotkeys-get.md | 150 +++++++++++++++++++++++ content/commands/hotkeys-start.md | 111 +++++++++++++++++ content/commands/hotkeys-stop.md | 55 +++++++++ content/commands/hotkeys.md | 39 ++++++ static/images/railroad/hotkeys-get.svg | 58 +++++++++ static/images/railroad/hotkeys-start.svg | 71 +++++++++++ static/images/railroad/hotkeys-stop.svg | 47 +++++++ static/images/railroad/hotkeys.svg | 47 +++++++ 8 files changed, 578 insertions(+) create mode 100644 content/commands/hotkeys-get.md create mode 100644 content/commands/hotkeys-start.md create mode 100644 content/commands/hotkeys-stop.md create mode 100644 content/commands/hotkeys.md create mode 100644 static/images/railroad/hotkeys-get.svg create mode 100644 static/images/railroad/hotkeys-start.svg create mode 100644 static/images/railroad/hotkeys-stop.svg create mode 100644 static/images/railroad/hotkeys.svg diff --git a/content/commands/hotkeys-get.md b/content/commands/hotkeys-get.md new file mode 100644 index 0000000000..88f5a6f949 --- /dev/null +++ b/content/commands/hotkeys-get.md @@ -0,0 +1,150 @@ +--- +arguments: +- name: mincpu + optional: true + token: MINCPU + type: integer +- name: minnet + optional: true + token: MINNET + type: integer +arity: -2 +categories: +- docs +- develop +- stack +- oss +- rs +- rc +- oss +- kubernetes +- clients +command_flags: +- ADMIN +- NOSCRIPT +complexity: O(K) where K is the number of hotkeys to return. +container: HOTKEYS +description: Returns two lists of top K hotkeys - one by cpu time and one by network + bytes. +function: hotkeysCommand +group: server +hidden: false +linkTitle: HOTKEYS GET +railroad_diagram: /images/railroad/hotkeys-get.svg +reply_schema: + oneOf: + - additionalProperties: false + description: Hotkeys report with collection metadata and two sorted lists + properties: + by-cpu-time: + description: Array of hotkeys with CPU time percentages + type: array + by-net-bytes: + description: Array of hotkeys with network throughput percentages + type: array + collection-duration: + type: integer + collection-start-time: + type: integer + type: object + - description: If no tracking is started + type: 'null' +since: 8.6.0 +summary: Returns two lists of top K hotkeys - one by cpu time and one by network bytes. +syntax_fmt: "HOTKEYS GET [MINCPU\_mincpu] [MINNET\_minnet]" +title: HOTKEYS GET +--- +Returns two lists of top K hotkeys - one by cpu time and one by network bytes. + +## Optional arguments + +
MINCPU + +Minimum CPU time percentage threshold. Only hotkeys with CPU time percentage greater than or equal to this value will be included in the `by-cpu-time` results. + +
+ +
MINNET + +Minimum network bytes percentage threshold. Only hotkeys with network bytes percentage greater than or equal to this value will be included in the `by-net-bytes` results. + +
+ +## Return information + +{{< multitabs id="return-info" + tab1="RESP2" + tab2="RESP3" >}} + +One of the following: +- [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) with the following items when tracking data is available: + - `collection-start-time`: Unix timestamp (integer) when tracking started. + - `collection-duration`: duration in seconds (integer) of the tracking period. + - `by-cpu-time`: array of key-percentage pairs (bulk strings) sorted by CPU time usage. + - `by-net-bytes`: array of key-percentage pairs (bulk strings) sorted by network bytes usage. + +- [Null bulk string reply]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) when no tracking has been started or no data is available. + +Example with tracking data: +``` +*8 +$21 +collection-start-time +:1768232225 +$19 +collection-duration +:0 +$11 +by-cpu-time +*2 +$6 +keys_1 +$6 +100.00 +$12 +by-net-bytes +*2 +$6 +keys_1 +$6 +100.00 +``` + +-tab-sep- + +One of the following: +- [Map reply]({{< relref "/develop/reference/protocol-spec#maps" >}}) with the following items when tracking data is available: + + - `collection-start-time`: Unix timestamp (integer) when tracking started. + - `collection-duration`: Duration in seconds (integer) of the tracking period. + - `by-cpu-time`: Array of key-percentage (bulk string) pairs sorted by CPU time usage + - `by-net-bytes`: Array of key-percentage (bulk string) pairs sorted by network bytes usage +- [Null reply]({{< relref "/develop/reference/protocol-spec#nulls" >}}) when no tracking has been started or no data is available. + +Example with tracking data: +``` +%4 +$21 +collection-start-time +:1768232225 +$19 +collection-duration +:0 +$11 +by-cpu-time +*2 +$6 +keys_1 +$6 +100.00 +$12 +by-net-bytes +*2 +$6 +keys_1 +$6 +100.00 +``` + +{{< /multitabs >}} + diff --git a/content/commands/hotkeys-start.md b/content/commands/hotkeys-start.md new file mode 100644 index 0000000000..ca81d9b8bf --- /dev/null +++ b/content/commands/hotkeys-start.md @@ -0,0 +1,111 @@ +--- +arguments: +- name: k + optional: true + token: COUNT + type: integer +- name: seconds + optional: true + token: DURATION + type: integer +- name: ratio + optional: true + token: SAMPLE + type: integer +- arguments: + - name: count + type: integer + - multiple: true + name: slot + type: integer + name: slots + optional: true + token: SLOTS + type: block +arity: -2 +categories: +- docs +- develop +- stack +- oss +- rs +- rc +- oss +- kubernetes +- clients +command_flags: +- ADMIN +- NOSCRIPT +complexity: O(1) +container: HOTKEYS +description: Starts hotkeys tracking. +function: hotkeysCommand +group: server +hidden: false +linkTitle: HOTKEYS START +railroad_diagram: /images/railroad/hotkeys-start.svg +reply_schema: + const: OK +since: 8.6.0 +summary: Starts hotkeys tracking. +syntax_fmt: "HOTKEYS START [COUNT\_k] [DURATION\_seconds] [SAMPLE\_ratio]\n [SLOTS\_\ + count slot [slot ...]]" +title: HOTKEYS START +--- +Starts hotkeys tracking. + +## Optional arguments + +
COUNT + +The maximum number of hotkeys to track and return. Specifies the value of K for the top-K hotkeys tracking. Must be between 10 and 64. Default behavior tracks a reasonable number of hotkeys. + +
+ +
DURATION + +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`. + +
+ +
SAMPLE + +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. + +
+ +
SLOTS + +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. + +
+ +## Return information + +{{< multitabs id="return-info" + tab1="RESP2" + tab2="RESP3" >}} + +One of the following: + +- [Simple string]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}) reply: `OK` when tracking is successfully started. +- [Error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}): when invalid parameters are provided. + +Example: +``` ++OK +``` + +-tab-sep- + +One of the following: + +- [Simple string]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}) reply: `OK` when tracking is successfully started. +- [Error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}): when invalid parameters are provided. + +Example: +``` ++OK +``` + +{{< /multitabs >}} diff --git a/content/commands/hotkeys-stop.md b/content/commands/hotkeys-stop.md new file mode 100644 index 0000000000..c09a6f627c --- /dev/null +++ b/content/commands/hotkeys-stop.md @@ -0,0 +1,55 @@ +--- +arity: 2 +categories: +- docs +- develop +- stack +- oss +- rs +- rc +- oss +- kubernetes +- clients +command_flags: +- ADMIN +- NOSCRIPT +complexity: O(1) +container: HOTKEYS +description: Stops hotkeys tracking. +function: hotkeysCommand +group: server +hidden: false +linkTitle: HOTKEYS STOP +railroad_diagram: /images/railroad/hotkeys-stop.svg +reply_schema: + const: OK +since: 8.6.0 +summary: Stops hotkeys tracking. +syntax_fmt: HOTKEYS STOP +title: HOTKEYS STOP +--- +Stops hotkeys tracking. + +## Return information + +{{< multitabs id="return-info" + tab1="RESP2" + tab2="RESP3" >}} + +[Simple string reply]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}): `OK` when tracking is successfully stopped. + +Example: +``` ++OK +``` + +-tab-sep- + +[Simple string reply]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}): `OK` when tracking is successfully stopped. + +Example: +``` ++OK +``` + +{{< /multitabs >}} diff --git a/content/commands/hotkeys.md b/content/commands/hotkeys.md new file mode 100644 index 0000000000..da9054af5a --- /dev/null +++ b/content/commands/hotkeys.md @@ -0,0 +1,39 @@ +--- +arity: -2 +categories: +- docs +- develop +- stack +- oss +- rs +- rc +- oss +- kubernetes +- clients +complexity: Depends on subcommand. +description: A container for hotkeys tracking commands. +group: server +hidden: false +linkTitle: HOTKEYS +railroad_diagram: /images/railroad/hotkeys.svg +since: 8.6.0 +summary: A container for hotkeys tracking commands. +syntax_fmt: HOTKEYS +title: HOTKEYS +--- + +This is a container command for hotkeys tracking commands that provides a method for identifying hotkeys inside a Redis server during a specifiedtracking time period. + +Hotkeys in this context are defined by two metrics: +* Percentage of CPU time spent on the key from the total time during the tracking period. +* Percentage of network bytes (input+output) used for the key from the total network bytes used by Redis during the tracking period. + +## Usage + +The general workflow is for the user to initiate a hotkeys tracking process which should run for some time. The keys' metrics are recorded inside a probabilistic structure and after that the user is able to fetch the top K of them. + +Available subcommands: + +- [`HOTKEYS START`]({{< relref "/commands/hotkeys-start" >}}) - Starts hotkeys tracking +- [`HOTKEYS STOP`]({{< relref "/commands/hotkeys-stop" >}}) - Stops hotkeys tracking +- [`HOTKEYS GET`]({{< relref "/commands/hotkeys-get" >}}) - Returns two lists of top K hotkeys diff --git a/static/images/railroad/hotkeys-get.svg b/static/images/railroad/hotkeys-get.svg new file mode 100644 index 0000000000..c80e117756 --- /dev/null +++ b/static/images/railroad/hotkeys-get.svg @@ -0,0 +1,58 @@ + + + + + + + + +GET + + + +MINCPU +mincpu + + + +MINNET +minnet \ No newline at end of file diff --git a/static/images/railroad/hotkeys-start.svg b/static/images/railroad/hotkeys-start.svg new file mode 100644 index 0000000000..f8fbca8eaf --- /dev/null +++ b/static/images/railroad/hotkeys-start.svg @@ -0,0 +1,71 @@ + + + + + + + + +START + + + +COUNT +k + + + +DURATION +seconds + + + +SAMPLE +ratio + + + +SLOTS +count + +slot + \ No newline at end of file diff --git a/static/images/railroad/hotkeys-stop.svg b/static/images/railroad/hotkeys-stop.svg new file mode 100644 index 0000000000..8895504997 --- /dev/null +++ b/static/images/railroad/hotkeys-stop.svg @@ -0,0 +1,47 @@ + + + + + + + +STOP \ No newline at end of file diff --git a/static/images/railroad/hotkeys.svg b/static/images/railroad/hotkeys.svg new file mode 100644 index 0000000000..b3a65c5b6e --- /dev/null +++ b/static/images/railroad/hotkeys.svg @@ -0,0 +1,47 @@ + + + + + + + +HOTKEYS \ No newline at end of file From 5e566759379ffc6a2a7c3b3c3c41ee80c478861e Mon Sep 17 00:00:00 2001 From: David Dougherty Date: Mon, 12 Jan 2026 13:59:19 -0800 Subject: [PATCH 2/5] Apply suggestions from code review Thank you, @mich-elle-luna! Co-authored-by: mich-elle-luna <153109578+mich-elle-luna@users.noreply.github.com> --- content/commands/hotkeys-get.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/commands/hotkeys-get.md b/content/commands/hotkeys-get.md index 88f5a6f949..aaaa6425c7 100644 --- a/content/commands/hotkeys-get.md +++ b/content/commands/hotkeys-get.md @@ -79,9 +79,9 @@ Minimum network bytes percentage threshold. Only hotkeys with network bytes perc One of the following: - [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) with the following items when tracking data is available: - `collection-start-time`: Unix timestamp (integer) when tracking started. - - `collection-duration`: duration in seconds (integer) of the tracking period. - - `by-cpu-time`: array of key-percentage pairs (bulk strings) sorted by CPU time usage. - - `by-net-bytes`: array of key-percentage pairs (bulk strings) sorted by network bytes usage. + - `collection-duration`: Duration in seconds (integer) of the tracking period. + - `by-cpu-time`: Array of key-percentage pairs (bulk strings) sorted by CPU time usage. + - `by-net-bytes`: Array of key-percentage pairs (bulk strings) sorted by network bytes usage. - [Null bulk string reply]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) when no tracking has been started or no data is available. @@ -117,8 +117,8 @@ One of the following: - `collection-start-time`: Unix timestamp (integer) when tracking started. - `collection-duration`: Duration in seconds (integer) of the tracking period. - - `by-cpu-time`: Array of key-percentage (bulk string) pairs sorted by CPU time usage - - `by-net-bytes`: Array of key-percentage (bulk string) pairs sorted by network bytes usage + - `by-cpu-time`: Array of key-percentage (bulk string) pairs sorted by CPU time usage. + - `by-net-bytes`: Array of key-percentage (bulk string) pairs sorted by network bytes usage. - [Null reply]({{< relref "/develop/reference/protocol-spec#nulls" >}}) when no tracking has been started or no data is available. Example with tracking data: From cad2b53d5da7c61bb9f59e26cc77a6923659dd81 Mon Sep 17 00:00:00 2001 From: "David W. Dougherty" Date: Tue, 20 Jan 2026 12:47:38 -0800 Subject: [PATCH 3/5] Major update after API change --- content/commands/hotkeys-get.md | 183 ++++++++++++----------- content/commands/hotkeys-reset.md | 61 ++++++++ content/commands/hotkeys-start.md | 82 +++++++--- content/commands/hotkeys-stop.md | 35 +++-- content/commands/hotkeys.md | 15 +- content/commands/info.md | 7 + static/images/railroad/hotkeys-get.svg | 17 +-- static/images/railroad/hotkeys-reset.svg | 47 ++++++ static/images/railroad/hotkeys-start.svg | 61 ++++---- static/images/railroad/hotkeys-stop.svg | 4 +- 10 files changed, 340 insertions(+), 172 deletions(-) create mode 100644 content/commands/hotkeys-reset.md create mode 100644 static/images/railroad/hotkeys-reset.svg diff --git a/content/commands/hotkeys-get.md b/content/commands/hotkeys-get.md index aaaa6425c7..732ad4acab 100644 --- a/content/commands/hotkeys-get.md +++ b/content/commands/hotkeys-get.md @@ -1,14 +1,9 @@ --- -arguments: -- name: mincpu - optional: true - token: MINCPU - type: integer -- name: minnet - optional: true - token: MINNET - type: integer -arity: -2 +acl_categories: +- '@admin' +- '@slow' +- '@dangerous' +arity: 2 categories: - docs - develop @@ -20,12 +15,11 @@ categories: - kubernetes - clients command_flags: -- ADMIN -- NOSCRIPT -complexity: O(K) where K is the number of hotkeys to return. +- admin +- noscript +complexity: O(K) where K is the number of hotkeys returned. container: HOTKEYS -description: Returns two lists of top K hotkeys - one by cpu time and one by network - bytes. +description: Returns lists of top K hotkeys depending on metrics chosen in HOTKEYS START command. function: hotkeysCommand group: server hidden: false @@ -50,25 +44,59 @@ reply_schema: - description: If no tracking is started type: 'null' since: 8.6.0 -summary: Returns two lists of top K hotkeys - one by cpu time and one by network bytes. -syntax_fmt: "HOTKEYS GET [MINCPU\_mincpu] [MINNET\_minnet]" +summary: Returns lists of top K hotkeys depending on metrics chosen in HOTKEYS START command. +syntax_fmt: HOTKEYS GET title: HOTKEYS GET --- -Returns two lists of top K hotkeys - one by cpu time and one by network bytes. +Returns tracking results and metadata from the current or most recent hotkeys tracking session. -## Optional arguments +This command returns comprehensive information about the hotkeys tracking session, including: -
MINCPU +- Tracking metadata (start time, duration, sample ratio, etc.) +- Performance statistics (CPU time, network bytes) +- Lists of top K hotkeys sorted by the metrics specified in `HOTKEYS START` -Minimum CPU time percentage threshold. Only hotkeys with CPU time percentage greater than or equal to this value will be included in the `by-cpu-time` results. +## Example -
- -
MINNET +``` +HOTKEYS GET + 1) "tracking-active" + 2) (integer) 0 + 3) "sample-ratio" + 4) (integer) 1 + 5) "selected-slots" + 6) (empty array) + 7) "all-commands-all-slots-ms" + 8) (integer) 0 + 9) "net-bytes-all-commands-all-slots" +10) (integer) 129 +11) "collection-start-time-unix-ms" +12) (integer) 1768927872057 +13) "collection-duration-ms" +14) (integer) 1 +15) "total-cpu-time-user-ms" +16) (integer) 0 +17) "total-cpu-time-sys-ms" +18) (integer) 0 +19) "total-net-bytes" +20) (integer) 129 +21) "by-cpu-time" +22) 1) "key1" + 2) (integer) 13 + 3) "key2" + 4) (integer) 2 +23) "by-net-bytes" +24) 1) "key1" + 2) (integer) 89 + 3) "key2" + 4) (integer) 40 +``` -Minimum network bytes percentage threshold. Only hotkeys with network bytes percentage greater than or equal to this value will be included in the `by-net-bytes` results. +## Redis Enterprise and Redis Cloud compatibility -
+| Redis
Enterprise | Redis
Cloud | Notes | +|:----------------------|:-----------------|:------| +| ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | ## Return information @@ -77,74 +105,51 @@ Minimum network bytes percentage threshold. Only hotkeys with network bytes perc tab2="RESP3" >}} One of the following: -- [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) with the following items when tracking data is available: - - `collection-start-time`: Unix timestamp (integer) when tracking started. - - `collection-duration`: Duration in seconds (integer) of the tracking period. - - `by-cpu-time`: Array of key-percentage pairs (bulk strings) sorted by CPU time usage. - - `by-net-bytes`: Array of key-percentage pairs (bulk strings) sorted by network bytes usage. -- [Null bulk string reply]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) when no tracking has been started or no data is available. - -Example with tracking data: -``` -*8 -$21 -collection-start-time -:1768232225 -$19 -collection-duration -:0 -$11 -by-cpu-time -*2 -$6 -keys_1 -$6 -100.00 -$12 -by-net-bytes -*2 -$6 -keys_1 -$6 -100.00 -``` +**[Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}})** when tracking data is available, containing pairs of field names and values: + +- `tracking-active` (integer): 1 if tracking is active, 0 if stopped +- `sample-ratio` (integer): The sampling ratio used during tracking +- `selected-slots` (array): Array of slot numbers being tracked (empty if all slots) +- `sampled-command-selected-slots-ms` (integer): Time in milliseconds for sampled commands on selected slots (conditional) +- `all-commands-selected-slots-ms` (integer): Time in milliseconds for all commands on selected slots (conditional) +- `all-commands-all-slots-ms` (integer): Time in milliseconds for all commands on all slots +- `net-bytes-sampled-commands-selected-slots` (integer): Network bytes for sampled commands on selected slots (conditional) +- `net-bytes-all-commands-selected-slots` (integer): Network bytes for all commands on selected slots (conditional) +- `net-bytes-all-commands-all-slots` (integer): Network bytes for all commands on all slots +- `collection-start-time-unix-ms` (integer): Unix timestamp in milliseconds when tracking started +- `collection-duration-ms` (integer): Duration of tracking in milliseconds +- `used-cpu-sys-ms` (integer): System CPU time used in milliseconds +- `used-cpu-user-ms` (integer): User CPU time used in milliseconds +- `total-net-bytes` (integer): Total network bytes processed +- `by-cpu-time` (array): Array of key-time pairs sorted by CPU time (if CPU tracking enabled) +- `by-net-bytes` (array): Array of key-bytes pairs sorted by network bytes (if NET tracking enabled) + +**[Null reply]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}})** when no tracking has been started or data has been reset. -tab-sep- One of the following: -- [Map reply]({{< relref "/develop/reference/protocol-spec#maps" >}}) with the following items when tracking data is available: - - `collection-start-time`: Unix timestamp (integer) when tracking started. - - `collection-duration`: Duration in seconds (integer) of the tracking period. - - `by-cpu-time`: Array of key-percentage (bulk string) pairs sorted by CPU time usage. - - `by-net-bytes`: Array of key-percentage (bulk string) pairs sorted by network bytes usage. -- [Null reply]({{< relref "/develop/reference/protocol-spec#nulls" >}}) when no tracking has been started or no data is available. - -Example with tracking data: -``` -%4 -$21 -collection-start-time -:1768232225 -$19 -collection-duration -:0 -$11 -by-cpu-time -*2 -$6 -keys_1 -$6 -100.00 -$12 -by-net-bytes -*2 -$6 -keys_1 -$6 -100.00 -``` +**[Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}})** when tracking data is available, containing pairs of field names and values: + +- `tracking-active` (integer): 1 if tracking is active, 0 if stopped +- `sample-ratio` (integer): The sampling ratio used during tracking +- `selected-slots` (array): Array of slot numbers being tracked (empty if all slots) +- `sampled-command-selected-slots-ms` (integer): Time in milliseconds for sampled commands on selected slots (conditional) +- `all-commands-selected-slots-ms` (integer): Time in milliseconds for all commands on selected slots (conditional) +- `all-commands-all-slots-ms` (integer): Time in milliseconds for all commands on all slots +- `net-bytes-sampled-commands-selected-slots` (integer): Network bytes for sampled commands on selected slots (conditional) +- `net-bytes-all-commands-selected-slots` (integer): Network bytes for all commands on selected slots (conditional) +- `net-bytes-all-commands-all-slots` (integer): Network bytes for all commands on all slots +- `collection-start-time-unix-ms` (integer): Unix timestamp in milliseconds when tracking started +- `collection-duration-ms` (integer): Duration of tracking in milliseconds +- `used-cpu-sys-ms` (integer): System CPU time used in milliseconds +- `used-cpu-user-ms` (integer): User CPU time used in milliseconds +- `total-net-bytes` (integer): Total network bytes processed +- `by-cpu-time` (array): Array of key-time pairs sorted by CPU time (if CPU tracking enabled) +- `by-net-bytes` (array): Array of key-bytes pairs sorted by network bytes (if NET tracking enabled) + +**[Null reply]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}})** when no tracking has been started or data has been reset. {{< /multitabs >}} - diff --git a/content/commands/hotkeys-reset.md b/content/commands/hotkeys-reset.md new file mode 100644 index 0000000000..57a8d8862b --- /dev/null +++ b/content/commands/hotkeys-reset.md @@ -0,0 +1,61 @@ +--- +acl_categories: +- '@admin' +- '@slow' +- '@dangerous' +arity: 2 +categories: +- docs +- develop +- stack +- oss +- rs +- rc +- oss +- kubernetes +- clients +command_flags: +- admin +- noscript +complexity: O(1) +container: HOTKEYS +description: Release the resources used for hotkey tracking. +function: hotkeysCommand +group: server +hidden: false +linkTitle: HOTKEYS RESET +railroad_diagram: /images/railroad/hotkeys-reset.svg +since: 8.6.0 +summary: Release the resources used for hotkey tracking. +syntax_fmt: HOTKEYS RESET +title: HOTKEYS RESET +--- +Release the resources used for hotkey tracking. + +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. + +## Redis Enterprise and Redis Cloud compatibility + +| Redis
Enterprise | Redis
Cloud | Notes | +|:----------------------|:-----------------|:------| +| ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | + +## Return information + +{{< multitabs id="return-info" + tab1="RESP2" + tab2="RESP3" >}} + +One of the following: + +- [Simple string reply]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}): `OK` when resources are successfully released. +- [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}): when tracking is currently active. + +-tab-sep- + +One of the following: + +- [Simple string reply]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}): `OK` when resources are successfully released. +- [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}): when tracking is currently active. + +{{< /multitabs >}} diff --git a/content/commands/hotkeys-start.md b/content/commands/hotkeys-start.md index ca81d9b8bf..a1f06c85f7 100644 --- a/content/commands/hotkeys-start.md +++ b/content/commands/hotkeys-start.md @@ -1,21 +1,47 @@ --- +acl_categories: +- '@admin' +- '@slow' +- '@dangerous' arguments: -- name: k +- arguments: + - display_text: count + name: count + type: integer + - display_text: cpu + name: cpu + optional: true + token: CPU + type: pure-token + - display_text: net + name: net + optional: true + token: NET + type: pure-token + name: metrics + token: METRICS + type: block +- display_text: k + name: k optional: true token: COUNT type: integer -- name: seconds +- display_text: seconds + name: seconds optional: true token: DURATION type: integer -- name: ratio +- display_text: ratio + name: ratio optional: true token: SAMPLE type: integer - arguments: - - name: count + - display_text: count + name: count type: integer - - multiple: true + - display_text: slot + multiple: true name: slot type: integer name: slots @@ -34,8 +60,8 @@ categories: - kubernetes - clients command_flags: -- ADMIN -- NOSCRIPT +- admin +- noscript complexity: O(1) container: HOTKEYS description: Starts hotkeys tracking. @@ -48,17 +74,35 @@ reply_schema: const: OK since: 8.6.0 summary: Starts hotkeys tracking. -syntax_fmt: "HOTKEYS START [COUNT\_k] [DURATION\_seconds] [SAMPLE\_ratio]\n [SLOTS\_\ - count slot [slot ...]]" +syntax_fmt: HOTKEYS START METRICS count [CPU] [NET] [COUNT k] [DURATION seconds] [SAMPLE ratio] [SLOTS count slot [slot ...]] title: HOTKEYS START --- -Starts hotkeys tracking. +Starts hotkeys tracking with specified metrics. + +This command initiates a hotkey tracking session. You must specify which metrics to track using the required `METRICS` parameter. +An error is returned if a tracking session is already in progress. + +The tracking session continues until manually stopped with [`HOTKEYS STOP`]({{< relref "/commands/hotkeys-stop" >}}) or automatically stopped after the specified duration. + +## Arguments + +
METRICS count [CPU] [NET] + +**Required.** Specifies which metrics to track and how many hotkeys to track. + +- `count` - The number of metrics to collect (required). +- `CPU` - Track hotkeys by CPU time percentage (optional). +- `NET` - Track hotkeys by network bytes percentage (optional). + +At least one of `CPU` or `NET` must be specified. + +
## Optional arguments
COUNT -The maximum number of hotkeys to track and return. Specifies the value of K for the top-K hotkeys tracking. Must be between 10 and 64. Default behavior tracks a reasonable number of hotkeys. +Specifies the value of K for the top-K hotkeys tracking.
@@ -80,6 +124,12 @@ Specifies which hash slots to track in a cluster environment. Takes a count foll +## Redis Enterprise and Redis Cloud compatibility + +| Redis
Enterprise | Redis
Cloud | Notes | +|:----------------------|:-----------------|:------| +| ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | + ## Return information {{< multitabs id="return-info" @@ -91,11 +141,6 @@ One of the following: - [Simple string]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}) reply: `OK` when tracking is successfully started. - [Error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}): when invalid parameters are provided. -Example: -``` -+OK -``` - -tab-sep- One of the following: @@ -103,9 +148,4 @@ One of the following: - [Simple string]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}) reply: `OK` when tracking is successfully started. - [Error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}): when invalid parameters are provided. -Example: -``` -+OK -``` - {{< /multitabs >}} diff --git a/content/commands/hotkeys-stop.md b/content/commands/hotkeys-stop.md index c09a6f627c..b234a20f33 100644 --- a/content/commands/hotkeys-stop.md +++ b/content/commands/hotkeys-stop.md @@ -1,4 +1,8 @@ --- +acl_categories: +- '@admin' +- '@slow' +- '@dangerous' arity: 2 categories: - docs @@ -11,8 +15,8 @@ categories: - kubernetes - clients command_flags: -- ADMIN -- NOSCRIPT +- admin +- noscript complexity: O(1) container: HOTKEYS description: Stops hotkeys tracking. @@ -28,28 +32,31 @@ summary: Stops hotkeys tracking. syntax_fmt: HOTKEYS STOP title: HOTKEYS STOP --- -Stops hotkeys tracking. +Stops hotkeys tracking but preserves the collected data. + +After stopping, the tracking data remains available through [`HOTKEYS GET`]({{< relref "/commands/hotkeys-get" >}}) until [`HOTKEYS RESET`]({{< relref "/commands/hotkeys-reset" >}}) is called or a new tracking session is started. + +## Redis Enterprise and Redis Cloud compatibility + +| Redis
Enterprise | Redis
Cloud | Notes | +|:----------------------|:-----------------|:------| +| ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | ## Return information {{< multitabs id="return-info" tab1="RESP2" tab2="RESP3" >}} +One of the following: -[Simple string reply]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}): `OK` when tracking is successfully stopped. - -Example: -``` -+OK -``` +- [Simple string reply]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}): `OK` when tracking is successfully stopped. +- [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}): when tracking is not currently active. -tab-sep- -[Simple string reply]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}): `OK` when tracking is successfully stopped. +One of the following: -Example: -``` -+OK -``` +- [Simple string reply]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}): `OK` when tracking is successfully stopped. +- [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}): when tracking is not currently active. {{< /multitabs >}} diff --git a/content/commands/hotkeys.md b/content/commands/hotkeys.md index da9054af5a..e715ab50a4 100644 --- a/content/commands/hotkeys.md +++ b/content/commands/hotkeys.md @@ -1,4 +1,6 @@ --- +acl_categories: +- '@slow' arity: -2 categories: - docs @@ -22,18 +24,19 @@ syntax_fmt: HOTKEYS title: HOTKEYS --- -This is a container command for hotkeys tracking commands that provides a method for identifying hotkeys inside a Redis server during a specifiedtracking time period. +This is a container command for hotkeys tracking commands that provides a method for identifying hotkeys inside a Redis server during a specified tracking time period. Hotkeys in this context are defined by two metrics: * Percentage of CPU time spent on the key from the total time during the tracking period. -* Percentage of network bytes (input+output) used for the key from the total network bytes used by Redis during the tracking period. +* Percentage of network bytes (input + output) used for the key from the total network bytes used by Redis during the tracking period. ## Usage -The general workflow is for the user to initiate a hotkeys tracking process which should run for some time. The keys' metrics are recorded inside a probabilistic structure and after that the user is able to fetch the top K of them. +The general workflow is for the user to initiate a hotkeys tracking process which should run for some time. The keys' metrics are recorded inside a probabilistic data structure, after which the user is able to fetch the top K metrics. Available subcommands: -- [`HOTKEYS START`]({{< relref "/commands/hotkeys-start" >}}) - Starts hotkeys tracking -- [`HOTKEYS STOP`]({{< relref "/commands/hotkeys-stop" >}}) - Stops hotkeys tracking -- [`HOTKEYS GET`]({{< relref "/commands/hotkeys-get" >}}) - Returns two lists of top K hotkeys +- [`HOTKEYS START`]({{< relref "/commands/hotkeys-start" >}}) - Starts hotkeys tracking with specified metrics. +- [`HOTKEYS STOP`]({{< relref "/commands/hotkeys-stop" >}}) - Stops hotkeys tracking but preserves data. +- [`HOTKEYS GET`]({{< relref "/commands/hotkeys-get" >}}) - Returns tracking results and metadata. +- [`HOTKEYS RESET`]({{< relref "/commands/hotkeys-reset" >}}) - Releases resources used for tracking. diff --git a/content/commands/info.md b/content/commands/info.md index 7e3d58ef9a..525c9e4820 100644 --- a/content/commands/info.md +++ b/content/commands/info.md @@ -61,6 +61,7 @@ The optional parameter can be used to select a specific section of information: * `keyspace`: Database-related statistics * `keysizes`: Statistics on the distribution of key sizes for each data type * `errorstats`: Redis error statistics +* `hotkeys`: Hotkeys tracking information It can also take the following values: @@ -495,6 +496,12 @@ For each error type, the following line is added: If the server detects that this section was flooded with an excessive number of errors, it will be disabled, show a single `ERRORSTATS_DISABLED` error, and print the errors to the server log. This can be reset by `CONFIG RESETSTAT`. +The **hotkeys** section provides information about hotkeys tracking. It consists of the following fields: + +* `tracking_active`: Boolean flag (0 or 1) indicating whether hotkeys tracking is currently active. +* `used_memory`: Memory overhead in bytes of the structures used for hotkeys tracking. +* `cpu_time`: Time in milliseconds spent updating the hotkey tracking structures. + The **sentinel** section is only available in Redis Sentinel instances. It consists of the following fields: * `sentinel_masters`: Number of Redis masters monitored by this Sentinel instance diff --git a/static/images/railroad/hotkeys-get.svg b/static/images/railroad/hotkeys-get.svg index c80e117756..fe22872133 100644 --- a/static/images/railroad/hotkeys-get.svg +++ b/static/images/railroad/hotkeys-get.svg @@ -1,4 +1,4 @@ - + - - -GET - - - -MINCPU -mincpu - - - -MINNET -minnet \ No newline at end of file + +HOTKEYS GET \ No newline at end of file diff --git a/static/images/railroad/hotkeys-reset.svg b/static/images/railroad/hotkeys-reset.svg new file mode 100644 index 0000000000..0807706a12 --- /dev/null +++ b/static/images/railroad/hotkeys-reset.svg @@ -0,0 +1,47 @@ + + + + + + + +HOTKEYS RESET \ No newline at end of file diff --git a/static/images/railroad/hotkeys-start.svg b/static/images/railroad/hotkeys-start.svg index f8fbca8eaf..523db27221 100644 --- a/static/images/railroad/hotkeys-start.svg +++ b/static/images/railroad/hotkeys-start.svg @@ -1,4 +1,4 @@ - + - -START - - - -COUNT -k - - - -DURATION -seconds - - - -SAMPLE -ratio - - - -SLOTS -count - -slot - \ No newline at end of file + +HOTKEYS START + +METRICS +count + + +CPU + + +NET + + + +COUNT +k + + + +DURATION +seconds + + + +SAMPLE +ratio + + + +SLOTS +count + +slot + \ No newline at end of file diff --git a/static/images/railroad/hotkeys-stop.svg b/static/images/railroad/hotkeys-stop.svg index 8895504997..e0c6765be9 100644 --- a/static/images/railroad/hotkeys-stop.svg +++ b/static/images/railroad/hotkeys-stop.svg @@ -1,4 +1,4 @@ - + -STOP \ No newline at end of file +HOTKEYS STOP \ No newline at end of file From b12eef1bd19436da8f6daad9c04aed4e6d84082b Mon Sep 17 00:00:00 2001 From: "David W. Dougherty" Date: Mon, 26 Jan 2026 07:12:34 -0800 Subject: [PATCH 4/5] Updates per #14742 --- content/commands/hotkeys-get.md | 51 ++++++++++++++----------------- content/commands/hotkeys-start.md | 2 +- 2 files changed, 24 insertions(+), 29 deletions(-) diff --git a/content/commands/hotkeys-get.md b/content/commands/hotkeys-get.md index 732ad4acab..f2b39f34f5 100644 --- a/content/commands/hotkeys-get.md +++ b/content/commands/hotkeys-get.md @@ -61,35 +61,30 @@ This command returns comprehensive information about the hotkeys tracking sessio ``` HOTKEYS GET 1) "tracking-active" - 2) (integer) 0 + 2) (integer) 1 3) "sample-ratio" 4) (integer) 1 5) "selected-slots" 6) (empty array) - 7) "all-commands-all-slots-ms" - 8) (integer) 0 + 7) "all-commands-all-slots-us" + 8) (integer) 220 9) "net-bytes-all-commands-all-slots" -10) (integer) 129 +10) (integer) 200 11) "collection-start-time-unix-ms" -12) (integer) 1768927872057 +12) (integer) 1769420604522 13) "collection-duration-ms" -14) (integer) 1 +14) (integer) 6408 15) "total-cpu-time-user-ms" -16) (integer) 0 +16) (integer) 3 17) "total-cpu-time-sys-ms" -18) (integer) 0 -19) "total-net-bytes" -20) (integer) 129 -21) "by-cpu-time" -22) 1) "key1" - 2) (integer) 13 - 3) "key2" - 4) (integer) 2 -23) "by-net-bytes" -24) 1) "key1" - 2) (integer) 89 - 3) "key2" - 4) (integer) 40 +18) (integer) 11 +19) "by-cpu-time-us" +20) 1) "x" + 2) (integer) 104 + 3) "y" + 4) (integer) 98 + 5) "z" + 6) (integer) 18 ``` ## Redis Enterprise and Redis Cloud compatibility @@ -111,9 +106,9 @@ One of the following: - `tracking-active` (integer): 1 if tracking is active, 0 if stopped - `sample-ratio` (integer): The sampling ratio used during tracking - `selected-slots` (array): Array of slot numbers being tracked (empty if all slots) -- `sampled-command-selected-slots-ms` (integer): Time in milliseconds for sampled commands on selected slots (conditional) -- `all-commands-selected-slots-ms` (integer): Time in milliseconds for all commands on selected slots (conditional) -- `all-commands-all-slots-ms` (integer): Time in milliseconds for all commands on all slots +- `sampled-command-selected-slots-us` (integer): Time in microseconds for sampled commands on selected slots (conditional) +- `all-commands-selected-slots-us` (integer): Time in microseconds for all commands on selected slots (conditional) +- `all-commands-all-slots-us` (integer): Time in microseconds for all commands on all slots - `net-bytes-sampled-commands-selected-slots` (integer): Network bytes for sampled commands on selected slots (conditional) - `net-bytes-all-commands-selected-slots` (integer): Network bytes for all commands on selected slots (conditional) - `net-bytes-all-commands-all-slots` (integer): Network bytes for all commands on all slots @@ -122,7 +117,7 @@ One of the following: - `used-cpu-sys-ms` (integer): System CPU time used in milliseconds - `used-cpu-user-ms` (integer): User CPU time used in milliseconds - `total-net-bytes` (integer): Total network bytes processed -- `by-cpu-time` (array): Array of key-time pairs sorted by CPU time (if CPU tracking enabled) +- `by-cpu-time-us` (array): Array of key-time pairs sorted by CPU time in microseconds (if CPU tracking enabled) - `by-net-bytes` (array): Array of key-bytes pairs sorted by network bytes (if NET tracking enabled) **[Null reply]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}})** when no tracking has been started or data has been reset. @@ -136,9 +131,9 @@ One of the following: - `tracking-active` (integer): 1 if tracking is active, 0 if stopped - `sample-ratio` (integer): The sampling ratio used during tracking - `selected-slots` (array): Array of slot numbers being tracked (empty if all slots) -- `sampled-command-selected-slots-ms` (integer): Time in milliseconds for sampled commands on selected slots (conditional) -- `all-commands-selected-slots-ms` (integer): Time in milliseconds for all commands on selected slots (conditional) -- `all-commands-all-slots-ms` (integer): Time in milliseconds for all commands on all slots +- `sampled-command-selected-slots-us` (integer): Time in microseconds for sampled commands on selected slots (conditional) +- `all-commands-selected-slots-us` (integer): Time in microseconds for all commands on selected slots (conditional) +- `all-commands-all-slots-us` (integer): Time in microseconds for all commands on all slots - `net-bytes-sampled-commands-selected-slots` (integer): Network bytes for sampled commands on selected slots (conditional) - `net-bytes-all-commands-selected-slots` (integer): Network bytes for all commands on selected slots (conditional) - `net-bytes-all-commands-all-slots` (integer): Network bytes for all commands on all slots @@ -147,7 +142,7 @@ One of the following: - `used-cpu-sys-ms` (integer): System CPU time used in milliseconds - `used-cpu-user-ms` (integer): User CPU time used in milliseconds - `total-net-bytes` (integer): Total network bytes processed -- `by-cpu-time` (array): Array of key-time pairs sorted by CPU time (if CPU tracking enabled) +- `by-cpu-time-us` (array): Array of key-time pairs sorted by CPU time in microseconds (if CPU tracking enabled) - `by-net-bytes` (array): Array of key-bytes pairs sorted by network bytes (if NET tracking enabled) **[Null reply]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}})** when no tracking has been started or data has been reset. diff --git a/content/commands/hotkeys-start.md b/content/commands/hotkeys-start.md index a1f06c85f7..9ce89dbf2f 100644 --- a/content/commands/hotkeys-start.md +++ b/content/commands/hotkeys-start.md @@ -120,7 +120,7 @@ Sampling ratio for probabilistic tracking. Each key is sampled with probability
SLOTS -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. +Specifies which hash slots to track in a cluster environment; ignored if not in a cluster. 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.
From 886489476d091699592043eaf96193c1814d83c3 Mon Sep 17 00:00:00 2001 From: "David W. Dougherty" Date: Mon, 26 Jan 2026 09:21:33 -0800 Subject: [PATCH 5/5] Apply review comments --- content/commands/hotkeys-start.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/commands/hotkeys-start.md b/content/commands/hotkeys-start.md index 9ce89dbf2f..78e344ae06 100644 --- a/content/commands/hotkeys-start.md +++ b/content/commands/hotkeys-start.md @@ -120,7 +120,7 @@ Sampling ratio for probabilistic tracking. Each key is sampled with probability
SLOTS -Specifies which hash slots to track in a cluster environment; ignored if not in a cluster. 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. +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.