Cassandra nodetool Commands
nodetool is the command-line administration tool for Cassandra. It lets you inspect cluster health, trigger repairs, monitor performance, manage nodes, and control compaction — all from the terminal without touching your application code. Learning nodetool is essential for anyone who operates a Cassandra cluster.
Basic Usage
nodetool [options] command [args] # Connect to a remote node: nodetool -h 10.0.0.2 status # Connect with authentication: nodetool -u cassandra -pw cassandra status
Cluster Health Commands
nodetool status
The most commonly used command. Shows every node in the cluster with its address, status (Up/Down), state (Normal/Leaving/Joining), load, and token ownership percentage.
nodetool status Datacenter: us-east =================== Status=Up/Down |/ State=Normal/Leaving/Joining/Moving -- Address Load Tokens Owns Host ID Rack UN 10.0.0.1 1.02 GiB 256 25.1% a1b2c3d4... rack1 UN 10.0.0.2 998.4 MiB 256 24.9% b2c3d4e5... rack2 UN 10.0.0.3 1.01 GiB 256 25.0% c3d4e5f6... rack1 UN 10.0.0.4 1.00 GiB 256 25.0% d4e5f6a7... rack2
nodetool info
Shows detailed information about the local node including uptime, heap usage, data directory load, and gossip state.
nodetool info ID : a1b2c3d4-e5f6-... Gossip active : true Native Transport active: true Load : 1.02 GiB Generation No : 1710000000 Uptime (seconds) : 86423 Heap Memory (MB) : 1024.00 / 4096.00 Data Center : us-east Rack : rack1
nodetool ring
Displays every token range in the cluster with the owning node's address, status, and load.
nodetool ring Address Rack Status State Token 10.0.0.1 rack1 Up Normal -9213093298666736028 10.0.0.2 rack2 Up Normal -9208148236388885498 ...
Repair Commands
nodetool repair
Repair synchronizes data across replicas to fix inconsistencies. Run it regularly (at least weekly) to keep replicas in sync and prevent deleted data from reappearing.
# Full repair on all keyspaces: nodetool repair # Repair a specific keyspace: nodetool repair ecommerce # Repair a specific table: nodetool repair ecommerce orders_by_customer # Incremental repair (only unrepairedSSTables): nodetool repair --incremental ecommerce # Parallel repair across all nodes simultaneously: nodetool repair --parallel ecommerce
nodetool repair_admin
Lists and manages ongoing repair jobs (Cassandra 4.0+).
nodetool repair_admin list nodetool repair_admin cancel --cancel-all
Compaction Commands
nodetool compact
Forces immediate compaction on a keyspace or table.
nodetool compact ecommerce orders_by_customer
nodetool compactionstats
Shows active compaction tasks and their progress.
nodetool compactionstats pending tasks: 3 - ecommerce.orders_by_customer: 2 tasks, 45% complete - ecommerce.products: 1 task, 10% complete
nodetool compactionhistory
nodetool compactionhistory
nodetool disableautocompaction / enableautocompaction
# Pause compaction (e.g., during a bulk load): nodetool disableautocompaction ecommerce # Re-enable: nodetool enableautocompaction ecommerce
Performance Monitoring Commands
nodetool tpstats
Shows thread pool statistics — active threads, pending tasks, and dropped messages per stage. A growing pending or dropped count signals a stressed cluster.
nodetool tpstats Pool Name Active Pending Completed Dropped ReadStage 0 0 1234567 0 MutationStage 2 0 5678901 0 CompactionExecutor 1 3 123456 0
nodetool tablehistograms
Shows read/write latency histograms for a specific table — useful for diagnosing slow queries.
nodetool tablehistograms ecommerce orders_by_customer
nodetool cfstats (or tablestats)
Shows statistics for all tables in a keyspace, including read/write counts, average latency, and SSTable count.
nodetool tablestats ecommerce Keyspace : ecommerce Table: orders_by_customer SSTable count: 5 Space used (live): 512 MB Read count: 1000000 Read latency: 0.45 ms per operation Write count: 2000000 Write latency: 0.12 ms per operation
nodetool netstats
Shows network streaming progress — useful during node bootstrap, repair, or decommission.
nodetool netstats Mode: JOINING Not sending any streams. Receiving 45 files, 2.1 GiB total. Already received 1.0 GiB.
Maintenance Commands
nodetool flush
Forces all MemTables to flush to SSTables on disk. Run before a planned node restart to minimize replay time from the commit log.
nodetool flush nodetool flush ecommerce # flush one keyspace only
nodetool cleanup
Removes data from a node that no longer belongs to it after a node addition. Run after adding nodes.
nodetool cleanup nodetool cleanup ecommerce
nodetool scrub
Validates SSTables and removes any corrupted rows. Run when you suspect data corruption.
nodetool scrub ecommerce orders_by_customer
nodetool rebuild
Streams all data for the local node from a source data center. Run on a new node joining an existing data center.
nodetool rebuild -- us_east
nodetool snapshot
# Take a snapshot of all keyspaces: nodetool snapshot # Snapshot a specific keyspace with a tag: nodetool snapshot -t backup_2024_06_15 ecommerce # List snapshots: nodetool listsnapshots # Delete a snapshot: nodetool clearsnapshot -t backup_2024_06_15
Summary nodetool Reference
Command Purpose ────────────────────────────────────────────────────────────── status Cluster node overview info Local node details ring Token ring layout repair Sync replicas compact Force compaction compactionstats View active compaction tpstats Thread pool health tablestats Per-table statistics netstats Streaming progress flush Flush MemTables to disk cleanup Remove non-owned data snapshot Take a backup snapshot decommission Remove a live node removenode Remove a dead node rebuild Stream data from another DC
Summary
nodetool is the primary operations tool for Cassandra cluster management. Use nodetool status as your daily health check. Run nodetool repair regularly to keep replicas in sync. Use nodetool tpstats and nodetool tablestats to spot performance problems before they affect your application. Combine nodetool commands with Cassandra's system log to diagnose and resolve issues quickly.