# CLUSTER SLOT-STATS

> Report the key count and resource usage of each hash slot served by the receiving node's shard.

URL: https://docs.hotkv.com/commands/cluster-slot-stats/

```
CLUSTER SLOT-STATS SLOTSRANGE start-slot end-slot
CLUSTER SLOT-STATS ORDERBY metric [LIMIT limit] [ASC | DESC]
```

- Group: Cluster
- Complexity: O(N) where N is the number of slots reported
- HotKV Cloud: not available
- On-Premise: no license needed

`CLUSTER SLOT-STATS` shows per-slot figures for the slots of the receiving
node's shard (on a replica, its primary's slots). Use it to find hot slots:
the ones with the most keys, CPU time or traffic, and to decide which slots
to move when you rebalance.

`SLOTSRANGE` reports the shard's slots in the inclusive range, in slot
order. `ORDERBY` reports all of the shard's slots sorted by one metric,
largest first by default (ties by slot number), and `LIMIT` keeps only the
first ones.

## Metrics

| Metric | Meaning | Reported |
| --- | --- | --- |
| `key-count` | Keys in the slot, in every database. An expired key counts until it is deleted. | Always |
| `cpu-usec` | Microseconds spent running commands on the slot's keys (a transaction or script counts with its `EXEC`, `EVAL` or `FCALL`) | While `cluster-slot-stats-enabled` includes `cpu` |
| `network-bytes-in` | Bytes of the commands sent for the slot | While it includes `net` |
| `network-bytes-out` | Bytes of the replies, plus the writes sent on to replicas | While it includes `net` |
| `memory-bytes` | An estimate of the memory the slot's keys use | While it includes `mem` (which can only be turned on at startup) |

`cluster-slot-stats-enabled` takes `yes` (all three), `no`, or one or more
of `cpu`, `net` and `mem`. A command that names no key counts for no slot. A
slot's CPU and network figures start again from 0 when the slot changes
owner on this node, and for every slot on `CONFIG RESETSTAT` and
[CLUSTER RESET](https://docs.hotkv.com/commands/cluster-reset/index.md).

## Options

| Option | Effect |
| --- | --- |
| `SLOTSRANGE start-slot end-slot` | The shard's slots from `start-slot` to `end-slot`. |
| `ORDERBY metric` | Sort by a metric that is currently reported. |
| `LIMIT limit` | Return at most `limit` slots, from 1 to 16384 (default: all). |
| `ASC` / `DESC` | Smallest first, or largest first (the default). |

## Return value

An array with one entry per slot. Each entry is a two-element array: the
slot number (integer), and a map of metric names to integers (a flat array
of pairs in RESP2). The metrics that are reported appear in this order:
`key-count`, `memory-bytes`, `cpu-usec`, `network-bytes-in`,
`network-bytes-out`.

| Case | Error |
| --- | --- |
| Slot not from 0 to 16383 | `ERR Invalid or out of range slot` |
| Range starts after it ends | `ERR Start slot number <start> is greater than end slot number <end>` |
| Unknown metric, or one not reported now | `ERR Unrecognized sort metric for ORDERBY.` |
| `LIMIT` outside 1 to 16384 | `ERR Limit has to lie in between 1 and 16384 (maximum number of slots).` |
| `LIMIT`, or `ASC`/`DESC`, given twice | `ERR Multiple filters of the same type are disallowed.` |
| Any other option after `ORDERBY` | `ERR syntax error` |
| Any other form | `ERR unknown subcommand or wrong number of arguments for 'SLOT-STATS'. Try CLUSTER HELP.` |
| Cluster mode is off | `ERR This instance has cluster support disabled` |

## Examples

```
127.0.0.1:6379> CONFIG SET cluster-slot-stats-enabled "cpu net"
OK
127.0.0.1:6379> CLUSTER SLOT-STATS SLOTSRANGE 0 1
1) 1) (integer) 0
   2) 1) "key-count"
      2) (integer) 18
      3) "cpu-usec"
      4) (integer) 412
      5) "network-bytes-in"
      6) (integer) 1290
      7) "network-bytes-out"
      8) (integer) 340
2) 1) (integer) 1
   2) 1) "key-count"
      2) (integer) 11
      3) "cpu-usec"
      4) (integer) 97
      5) "network-bytes-in"
      6) (integer) 430
      7) "network-bytes-out"
      8) (integer) 102
127.0.0.1:6379> CLUSTER SLOT-STATS ORDERBY key-count LIMIT 1
1) 1) (integer) 1649
   2) 1) "key-count"
      2) (integer) 2741
      3) "cpu-usec"
      4) (integer) 18044
      5) "network-bytes-in"
      6) (integer) 90211
      7) "network-bytes-out"
      8) (integer) 30876
127.0.0.1:6379> CLUSTER SLOT-STATS ORDERBY memory-bytes
(error) ERR Unrecognized sort metric for ORDERBY.
```

## Compatibility

Same forms, metric names and error strings as Valkey 8 and Redis 8.2, with
Redis 8.6's `memory-bytes` metric. Redis 7 does not have this subcommand.
HotKV estimates `memory-bytes`, while Redis counts it exactly.

## See also

[CLUSTER COUNTKEYSINSLOT](https://docs.hotkv.com/commands/cluster-countkeysinslot/index.md),
[CLUSTER SETSLOT](https://docs.hotkv.com/commands/cluster-setslot/index.md),
[CLUSTER SHARDS](https://docs.hotkv.com/commands/cluster-shards/index.md)

In a cluster: [Scaling a cluster](https://docs.hotkv.com/clustering/scaling/index.md#balance-by-load)