Cassandra’s nodetool is your primary interface for understanding and managing your cluster, but its true power lies not in its basic commands, but in how they reveal the underlying health and distribution of your data.
Let’s see nodetool in action. Imagine you’ve got a small cluster, maybe two nodes, and you’re curious about its state. You’d start with nodetool status.
# On node 1
$ nodetool status
Datacenter: DC1
=====================
Status=Up/Down
|/ State=Normal/Leaving/Joining/Migrating
-- Address Load Tokens Owns (effective) Host ID Rack
UN 10.0.0.1 100.5 GiB 256 100.0% a1b2c3d4-e5f6-7890-1234-abcdef123456 RAC1
UN 10.0.0.2 101.2 GiB 256 100.0% b2c3d4e5-f6a7-8901-2345-bcdef1234567 RAC1
Datacenter: DC2
=====================
Status=Up/Down
|/ State=Normal/Leaving/Joining/Migrating
-- Address Load Tokens Owns (effective) Host ID Rack
UN 10.0.0.3 98.7 GiB 256 100.0% c3d4e5f6-a7b8-9012-3456-cdef12345678 RAC2
UN 10.0.0.4 99.1 GiB 256 100.0% d4e5f6a7-b8c9-0123-4567-def123456789 RAC2
This output tells you a lot: UN means "Up" and "Normal," which is good. You see the datacenter and rack layout, the IP address, how much data each node holds, and crucially, the Owns (effective) percentage. Here, each node owns 100% of its tokens, indicating a healthy distribution.
The problem nodetool solves is providing a window into Cassandra’s distributed state. It’s not just about running commands; it’s about interpreting their output to understand data placement, replication, and node health.
Let’s look at nodetool tpstats. This is your go-to for understanding what your nodes are doing.
# On node 1
$ nodetool tpstats
Pool Name Active Pending Completed Blocked All time blocked
MessagingService:Gossip 0 0 54321 0 0
MessagingService:Request 10 5 1234567 0 0
MemtableFlushWriter 0 0 8765 0 0
CompactionExecutor 2 1 98765 0 0
ReadStage 5 2 654321 0 0
This shows the thread pools and their activity. High Pending or Blocked counts on critical pools like MessagingService:Request or ReadStage can indicate performance bottlenecks. For instance, if MessagingService:Request is constantly blocked, it means your nodes are struggling to process incoming read/write requests, likely due to heavy load or slow disk I/O.
The mental model you build with nodetool is one of a distributed system where data is chopped up, replicated, and served by many nodes. nodetool lets you check if that distribution is working as expected. nodetool cfstats (or tablestats in newer versions) is your key to understanding the state of your tables.
# On node 1, for keyspace 'my_keyspace' and table 'my_table'
$ nodetool tablestats my_keyspace my_table
Table: my_keyspace.my_table
--------------------
Keyspace: my_keyspace
Table: my_table
...
Read Count: 1500000
Read Latency: 0.5 ms
Write Count: 1200000
Write Latency: 0.3 ms
SSTable Count: 12
SSTable Size (total): 500 MB
...
Local Read Repair: 10
Local Write Repair: 5
This gives you metrics for a specific table: read/write counts and latencies, the number and size of SSTables (Cassandra’s immutable data files). High latencies here directly correlate to slow queries. A growing SSTable Count without proportional data growth can signal a need for more aggressive compaction.
To truly manage Cassandra, you need to understand the interplay between these commands. A high Pending count in tpstats might be caused by slow disk I/O, which you’d then investigate with nodetool cfstats (looking for high SSTable counts and large SSTable sizes) or nodetool proxyhistograms (for request latencies).
The one thing most people don’t know is how nodetool’s repair command interacts with your replication strategy. When you run nodetool repair, it’s not just about "fixing" data; it’s an anti-entropy process that compares data replicas across nodes. If you have a NetworkTopologyStrategy with a replication factor of 3 in DC1, running nodetool repair on a single node will initiate a repair process for all replicas of the data that node owns across the other two nodes in DC1. This can be resource-intensive and is why incremental repair, often managed by tools like Cassandra Reaper, is preferred for larger clusters.
The next step in mastering nodetool is understanding how to use its commands in conjunction with system logs and metrics collection tools for comprehensive cluster diagnostics.