nodetool describering¶

Displays detailed token range information for a keyspace.

Synopsis¶

nodetool [connection_options] describering <keyspace>

Description¶

nodetool describering shows the token ranges for a keyspace, including the start and end tokens for each range and which nodes are responsible for each range. This provides more detail than ring by showing the actual replica endpoints for each token range.

Arguments¶

Argument	Description
`keyspace`	Required. The keyspace to describe

Output Format¶

Schema versions:
    abc123-def456-... [node1, node2, node3]

TokenRange(start_token:-9223372036854775808, end_token:-6148914691236517206, endpoints:[192.168.1.101, 192.168.1.102, 192.168.1.103], rpc_endpoints:[192.168.1.101, 192.168.1.102, 192.168.1.103], endpoint_details:[EndpointDetails(host:192.168.1.101, datacenter:dc1, rack:rack1), ...])
TokenRange(start_token:-6148914691236517206, end_token:-3074457345618258604, endpoints:[192.168.1.102, 192.168.1.103, 192.168.1.101], ...)
...

Output Fields¶

Field	Description
`start_token`	Beginning of the token range (exclusive)
`end_token`	End of the token range (inclusive)
`endpoints`	IP addresses of replica nodes
`rpc_endpoints`	Client-facing addresses
`endpoint_details`	Datacenter and rack for each endpoint

Examples¶

Describe Keyspace Token Ranges¶

nodetool describering my_keyspace

Parse with jq (if JSON output available)¶

nodetool describering my_keyspace | grep TokenRange

Count Token Ranges¶

nodetool describering my_keyspace | grep -c "TokenRange"

Use Cases¶

Find Replicas for Token Range¶

# Find which nodes own a specific token range
nodetool describering my_keyspace | grep "start_token:-614891"

Verify Replication Factor¶

# Count endpoints per range (should equal RF)
nodetool describering my_keyspace | head -1 | grep -o "192.168" | wc -l

Check Datacenter Distribution¶

# See datacenter placement for each range
nodetool describering my_keyspace | grep "datacenter:"

Understanding Token Ranges¶

Range Ownership¶

TokenRange(start_token:-9223372036854775808, end_token:-6148914691236517206, ...)

This means: - Data with tokens from -9223372036854775808 to -6148914691236517206 - Is stored on the listed endpoints

Wrap-Around Range¶

The token ring is circular. The last range wraps around:

TokenRange(start_token:6148914691236517204, end_token:-9223372036854775808, ...)

This range covers from the highest token back to the lowest (wrap-around).

Comparing with nodetool ring¶

Command	Shows	Best For
`nodetool ring`	All tokens for all nodes	Overall token distribution
`nodetool describering`	Token ranges with replicas	Finding replicas for ranges
`nodetool getendpoints`	Replicas for specific key	Finding replicas for a key

Multi-Datacenter Output¶

With NetworkTopologyStrategy:

TokenRange(
  start_token:-9223372036854775808,
  end_token:-6148914691236517206,
  endpoints:[
    192.168.1.101,  # DC1
    192.168.1.102,  # DC1
    192.168.1.103,  # DC1
    192.168.2.101,  # DC2
    192.168.2.102,  # DC2
    192.168.2.103   # DC2
  ],
  endpoint_details:[
    EndpointDetails(host:192.168.1.101, datacenter:dc1, rack:rack1),
    EndpointDetails(host:192.168.1.102, datacenter:dc1, rack:rack2),
    ...
  ]
)

Troubleshooting with Describering¶

Verify Rack Awareness¶

# Check that replicas are spread across racks
nodetool describering my_keyspace | grep -A10 "TokenRange" | head -20

Each range should have replicas in different racks.

Check for Missing Replicas¶

# Count endpoints per range
nodetool describering my_keyspace | grep "endpoints:" | head -5

If count doesn't match RF, investigate topology issues.

Verify Datacenter Coverage¶

# Ensure both DCs have replicas
nodetool describering my_keyspace | grep "datacenter:" | sort | uniq -c

Scripting Example¶

Extract All Endpoints for a Keyspace¶

#!/bin/bash
# List all unique endpoints for a keyspace

nodetool describering $1 | \
  grep -oP '(?<=endpoints:\[)[^\]]+' | \
  tr ',' '\n' | \
  sort -u

Validate Replication¶

#!/bin/bash
# Verify RF matches expected value

KS=$1
EXPECTED_RF=$2

ACTUAL_RF=$(nodetool describering $KS | \
  head -1 | \
  grep -oP '(?<=endpoints:\[)[^\]]+' | \
  tr ',' '\n' | wc -l)

if [ "$ACTUAL_RF" -eq "$EXPECTED_RF" ]; then
  echo "RF is correct: $ACTUAL_RF"
else
  echo "WARNING: Expected RF $EXPECTED_RF but found $ACTUAL_RF"
fi

Command	Relationship
ring	Simpler token distribution view
status	Node status overview
getendpoints	Find replicas for specific key
gossipinfo	Detailed node information