Bug: DOC - Improve tpstats documentation
Status: Open
Priority: Normal
Created: 29/Apr/20 15:11

h2. Background

The docs for {{nodetool tpstats}} gives the user a good overview of the correct command format, but lack an explanation of the message types.

As of Cassandra4.0 and CASSANDRA-15066 the Message types have expanded a lot so this becomes quite overwhelming (particularly for new users).

I'd propose we offer a simple explanation of these grouping them into logical groups (see CASSANDRA-15771 which I opened for the formatting output). 

The github code for the {{Verb.java}} class does give the user some idea of what these are but not everyone will go looking for that.
h2. Example

Code for ref

[https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/net/Verb.java]

I tried to sort some of the tpstats output into categories and made a first attempt at an explanation here:
{code:java}
Batches    BATCH_REMOVE_REQ         
Batches    BATCH_REMOVE_RSP         
Batches    BATCH_STORE_REQ          
Batches    BATCH_STORE_RSP    
- These are batches, I'd assume the store / removes are as we add and process them?
     
Counters   COUNTER_MUTATION_REQ     
Counters   COUNTER_MUTATION_RSP     
- Counter writes

Deprecated INTERNAL_RSP  
Deprecated REQUEST_RSP       
- Some of these are shown as deprecated in the code. Not sure what we should add here
     
Gossip     ECHO_REQ                 
Gossip     ECHO_RSP                 
Gossip     GOSSIP_DIGEST_ACK        
Gossip     GOSSIP_DIGEST_ACK2       
Gossip     GOSSIP_DIGEST_SYN        
Gossip     GOSSIP_SHUTDOWN          
Gossip     PING_REQ                 
Gossip     PING_RSP
- Gossip, probably we'd refer to a more detailed page on gossip from here
              
Hints      HINT_REQ                 
Hints      HINT_RSP
- Hints!  
              
LWTs       PAXOS_COMMIT_REQ         
LWTs       PAXOS_COMMIT_RSP         
LWTs       PAXOS_PREPARE_REQ        
LWTs       PAXOS_PREPARE_RSP        
LWTs       PAXOS_PROPOSE_REQ        
LWTs       PAXOS_PROPOSE_RSP
- Paxos phases request / response
    
Migration  SCHEMA_PULL_REQ          
Migration  SCHEMA_PULL_RSP          
Migration  SCHEMA_PUSH_REQ          
Migration  SCHEMA_PUSH_RSP          
Migration  SCHEMA_VERSION_REQ       
Migration  SCHEMA_VERSION_RSP      
- Schema migration messaging (i.e. adding new tables)

Misc       REPLICATION_DONE_REQ     
Misc       REPLICATION_DONE_RSP     
Misc       SNAPSHOT_MSG             
Misc       SNAPSHOT_REQ             
Misc       SNAPSHOT_RSP
- Unsure of these, could the snapshots be for simply nodetool snapshot requests like on truncates?     
        
Reads      RANGE_REQ                
Reads      RANGE_RSP                
Reads      READ_REPAIR_REQ          
Reads      READ_REPAIR_RSP          
Reads      READ_REQ                 
Reads      READ_RSP     
- All types of read messages     
       
Repair     CLEANUP_MSG              
Repair     FAILED_SESSION_MSG       
Repair     FAILURE_RSP              
Repair     FINALIZE_COMMIT_MSG      
Repair     FINALIZE_PROMISE_MSG     
Repair     FINALIZE_PROPOSE_MSG     
Repair     PREPARE_CONSISTENT_REQ   
Repair     PREPARE_CONSISTENT_RSP   
Repair     PREPARE_MSG              
Repair     REPAIR_RSP               
Repair     STATUS_REQ               
Repair     STATUS_RSP               
Repair     SYNC_REQ                 
Repair     SYNC_RSP                 
Repair     VALIDATION_REQ           
Repair     VALIDATION_RSP           
Repair     ASYMMETRIC_SYNC_REQ 
- Repairs, and phases, I think we'd need a bit more explanation here. Validation, Sync etc ok. But unsure on these other types
     
Writes     MUTATION_REQ             
Writes     MUTATION_RSP             
Writes     TRUNCATE_REQ             
Writes     TRUNCATE_RSP             
- All types of write messages{code}