diff --git a/content/commands/hotkeys-get.md b/content/commands/hotkeys-get.md new file mode 100644 index 0000000000..f2b39f34f5 --- /dev/null +++ b/content/commands/hotkeys-get.md @@ -0,0 +1,150 @@ +--- +acl_categories: +- '@admin' +- '@slow' +- '@dangerous' +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 returned. +container: HOTKEYS +description: Returns lists of top K hotkeys depending on metrics chosen in HOTKEYS START command. +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 lists of top K hotkeys depending on metrics chosen in HOTKEYS START command. +syntax_fmt: HOTKEYS GET +title: HOTKEYS GET +--- +Returns tracking results and metadata from the current or most recent hotkeys tracking session. + +This command returns comprehensive information about the hotkeys tracking session, including: + +- 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` + +## Example + +``` +HOTKEYS GET + 1) "tracking-active" + 2) (integer) 1 + 3) "sample-ratio" + 4) (integer) 1 + 5) "selected-slots" + 6) (empty array) + 7) "all-commands-all-slots-us" + 8) (integer) 220 + 9) "net-bytes-all-commands-all-slots" +10) (integer) 200 +11) "collection-start-time-unix-ms" +12) (integer) 1769420604522 +13) "collection-duration-ms" +14) (integer) 6408 +15) "total-cpu-time-user-ms" +16) (integer) 3 +17) "total-cpu-time-sys-ms" +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 + +| 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: + +**[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-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 +- `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-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. + +-tab-sep- + +One of the following: + +**[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-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 +- `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-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. + +{{< /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 new file mode 100644 index 0000000000..78e344ae06 --- /dev/null +++ b/content/commands/hotkeys-start.md @@ -0,0 +1,151 @@ +--- +acl_categories: +- '@admin' +- '@slow' +- '@dangerous' +arguments: +- 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 +- display_text: seconds + name: seconds + optional: true + token: DURATION + type: integer +- display_text: ratio + name: ratio + optional: true + token: SAMPLE + type: integer +- arguments: + - display_text: count + name: count + type: integer + - display_text: slot + 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 METRICS count [CPU] [NET] [COUNT k] [DURATION seconds] [SAMPLE ratio] [SLOTS count slot [slot ...]] +title: HOTKEYS START +--- +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 + +Specifies the value of K for the top-K hotkeys tracking. + +
+ +
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. Using `SLOTS` when not in cluster mode will result in an error. + +
+ +## 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]({{< 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. + +-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. + +{{< /multitabs >}} diff --git a/content/commands/hotkeys-stop.md b/content/commands/hotkeys-stop.md new file mode 100644 index 0000000000..b234a20f33 --- /dev/null +++ b/content/commands/hotkeys-stop.md @@ -0,0 +1,62 @@ +--- +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: 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 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. +- [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}): when tracking is not currently active. + +-tab-sep- + +One of the following: + +- [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 new file mode 100644 index 0000000000..e715ab50a4 --- /dev/null +++ b/content/commands/hotkeys.md @@ -0,0 +1,42 @@ +--- +acl_categories: +- '@slow' +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 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. + +## 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 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 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 new file mode 100644 index 0000000000..fe22872133 --- /dev/null +++ b/static/images/railroad/hotkeys-get.svg @@ -0,0 +1,47 @@ + + + + + + + +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 new file mode 100644 index 0000000000..523db27221 --- /dev/null +++ b/static/images/railroad/hotkeys-start.svg @@ -0,0 +1,80 @@ + + + + + + + + +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 new file mode 100644 index 0000000000..e0c6765be9 --- /dev/null +++ b/static/images/railroad/hotkeys-stop.svg @@ -0,0 +1,47 @@ + + + + + + + +HOTKEYS 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