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/2] 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/2] 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: