#Analyze large keys with valkey-cli

The Valkey Operator does not provide an integrated large-key inspection report. Use valkey-cli directly when a latency, memory, network, persistence, or slot migration investigation requires key-size evidence.

See the official Valkey CLI documentation for the option semantics supported by the CLI delivered with your server image.

#Operational impact

valkey-cli --bigkeys iterates the keyspace and runs type-specific size commands. Although iteration uses cursor-based scanning, the additional commands consume server CPU and network bandwidth. Large collection cardinality checks can also be expensive.

• Run during lower traffic and monitor latency, CPU, memory, and network usage.
• Use a dedicated least-privilege inspection account with only SCAN and the type and size commands required by the CLI. Validate the exact rule against the selected server line; a normal read-only application account may be too broad or may lack a required introspection command.
• Do not put passwords on the command line or in shell history.
• Stop the scan if service indicators degrade.
• Treat results as a point-in-time observation; the keyspace can change during the scan.

#Scan one endpoint

valkey-cli -h <host> -p 6379 --user <username> --askpass \
  --bigkeys -i 0.1

With --bigkeys, the -i 0.1 option sleeps for 0.1 seconds after each 100 scan cycles; it does not delay every cycle and does not make the command impact-free. Output can include key names, so treat it as sensitive and save only what the investigation requires.

With TLS:

valkey-cli --tls --cacert <ca-file> \
  --cert <client-certificate-file> --key <client-key-file> \
  -h <host> -p 6379 --user <username> --askpass \
  --bigkeys -i 0.1

#Cluster coverage

A scan issued to one Cluster node covers that node's local keyspace, not all primary nodes. List the observed primary Pods from the high-level status:

kubectl -n <namespace> get valkey <name> \
  -o jsonpath='{range .status.nodes[?(@.role=="master")]}{.podName}{"\t"}{.slots}{"\n"}{end}'

Run the approved scan once against each current primary endpoint. Topology can change during failover or rebalancing, so record CLUSTER NODES before and after the collection and avoid scanning while slots are moving.

#Interpret and act

The command reports the largest observed key for each data type and aggregate statistics. It does not determine a universal safe size. Evaluate the result against command complexity, access frequency, network payload, persistence cost, replication, and application latency objectives.

Prefer application-level remediation such as splitting oversized values or collections, bounding growth, applying expiration where semantically correct, and avoiding commands whose complexity is unsafe for the observed cardinality. Do not delete or rewrite a production key until ownership, recovery, and application behavior have been validated.