Deep Cassandra ops via nodetool + cqlsh: topology (status, ring, gossip, describering, failure detector), health (tpstats, netstats, proxy + table histograms, compaction stats + history, GC, clients, hot and large partitions, tombstones), schema introspection down to one table, effective runtime configuration, approval-gated data reads, runtime limits a running node accepts without a restart (stream and inter-datacenter throughput, compaction, hints, batchlog replay, snapshots, request timeouts, caches, stage concurrency, tracing), switches for compaction, hints, and backup, maintenance mutators (snapshot, flush, cleanup, verify, compact, scrub, garbage collect, upgrade + relocate SSTables, cache invalidation), repair workflows, node lifecycle (drain, decommission, assassinate, removenode, rebuild, bootstrap resume), default-denied native transport and gossip switches, and logging level control. JMX on 127.0.0.1:7199.
94 allowed by default
17 need approval by default
8 denied by default
Pack ID
cassandra
Vendor
emisar
OS
linux
Actions
119
Required binaries.
Install these on the host before relying on the pack — an action that calls a missing
one fails at run time.
nodetool
bash
Install
emisar pack install
fetches this pack, re-validates it, and verifies its content hash against the
--hash
below — the exact bytes this page was rendered against, so a tampered copy is
rejected — before copying it into the runner's packs dir. The command reloads a
running daemon itself; no manual restart.
nodetool actions connect to the local node's JMX port (127.0.0.1:7199 by default, set per call) and take no credentials. cqlsh actions read
CQLSH_HOST
and
CQLSH_PORT
on the runner host (defaulting to 127.0.0.1:9042) and authenticate, when the cluster requires it, from
~/.cassandra/cqlshrc
.
Environment
Set these on the runner host, then add each name to
execution.inherit_env
so the value reaches the action.
CQLSH_HOST
default 127.0.0.1
Host for the cqlsh actions (schema/keyspace/role introspection).
CQLSH_PORT
default 9042
Native CQL port for the cqlsh actions.
Host access
Run these commands yourself on the runner host. Emisar shows and copies setup
recipes; it never runs them.
Traverse Cassandra's service-owned data and commitlog directories.
id -nG emisar | tr ' ' '\n' | grep -Fx cassandra
sudo -u emisar test -r /var/lib/cassandra/data
sudo -u emisar test -x /var/lib/cassandra/data
sudo -u emisar test -r /var/lib/cassandra/commitlog
sudo -u emisar test -x /var/lib/cassandra/commitlog
Impact:
Every process running as emisar can traverse files exposed to the cassandra group, including raw database and commitlog storage outside this aggregate size action.
Notes
nodetool host/port come from each action's args (default 127.0.0.1:7199), not the environment; this pack passes no JMX username/password, so it works only against a node without JMX auth.
cqlsh credentials belong in
~/.cassandra/cqlshrc
(with a [authentication] username/password) on the runner host — read from disk, so it needs no
inherit_env
entry; the actions pass no -u/-p.
Lifecycle and maintenance mutators (repair, drain, decommission, assassinate, removenode, cleanup, compact) are cluster-affecting; run the read actions first.
The runtime limit actions change one node and take effect at once, but a restart returns it to cassandra.yaml — after any node restart, read the limits back and set them again.
Verify it works
Runs cassandra.nodetool_status, a low-risk
read that confirms the pack can reach its target. Run it on the host once the pack
is installed; pack install runs it for
you.
cassandra.analyze_disk_pressure
script
low
Low — read-only or trivially reversible
Analyze Cassandra disk pressure
Run a packaged shell script that inspects filesystem usage of the Cassandra data and commitlog directories. Read-only. Use as a first step when disk pressure is suspected. Output is human-readable; do not parse it.
cassandra.cqlsh_list_permissions
exec
low
Low — read-only or trivially reversible
cqlsh -e "LIST ALL PERMISSIONS"
List every permission granted to every role — who may read, write, or alter which keyspace and table. Needs CassandraAuthorizer and a login with permission to see other roles' grants.
cassandra.cqlsh_list_tables
exec
low
Low — read-only or trivially reversible
cqlsh -e "SELECT table_name FROM system_schema.tables"
List the tables in one keyspace by name — the cheap look-up before cassandra.cqlsh_describe_table, without the full DDL that cassandra.cqlsh_describe_keyspace dumps.
cassandra.cqlsh_repair_history
exec
low
Low — read-only or trivially reversible
cqlsh -e "SELECT * FROM system_distributed.repair_history"
List recent repair sessions the cluster recorded — keyspace, table, coordinator, start and finish time, and status. Shows what repaired and what failed, which cassandra.nodetool_repair's own output does not survive.
cassandra.cqlsh_running_queries
exec
high
High — service-affecting
cqlsh -e "SELECT * FROM system_views.queries"
List the queries this node is executing right now, with how long each has been queued and running — the first look when a node is busy and nobody knows what it is doing. The query text includes literal values, so this returns application data and is approval-gated.
cassandra.cqlsh_select_by_key
exec
high
High — service-affecting
cqlsh -e "SELECT * FROM <ks>.<table> WHERE <key> = <value>"
Read the rows of one partition by its key — the "does this row exist, and what does it hold" lookup. Returns stored application data, so it is approval-gated. Use cassandra.nodetool_getendpoints for which replicas own the key without reading it.
cassandra.cqlsh_select_rows
exec
high
High — service-affecting
cqlsh -e "SELECT * FROM <ks>.<table> LIMIT <n>"
Read a bounded sample of rows from one table. Returns stored application data, so it is approval-gated; use cassandra.cqlsh_select_by_key when you know the partition key, and cassandra.cqlsh_describe_table when you only need the shape.
cassandra.cqlsh_settings
exec
medium
Medium — changes state, easily reversible
cqlsh -e "SELECT name, value FROM system_views.settings"
Show the configuration this node is actually running, from the system_views.settings virtual table — cassandra.yaml as parsed at boot plus every runtime change made since. Pass a filter to narrow it to one area (compaction, stream, hinted_handoff); the unfiltered dump is over 500 rows.
cassandra.cqlsh_tombstones_per_read
exec
low
Low — read-only or trivially reversible
cqlsh -e "SELECT * FROM system_views.tombstones_per_read"
Show how many tombstones each table scans per read on this node (count, max, p50, p99) — the read that confirms a delete-heavy or TTL-heavy table is the reason queries are slow or failing.
cassandra.nodetool_assassinate
exec
critical
Critical — data loss or irreversible
nodetool assassinate <address>
Assassinate a dead node — forcibly remove it from gossip without streaming data. ONLY use when the node is permanently gone AND removenode failed. Risks: orphaned data, hint bleed, token misownership.
cassandra.nodetool_bootstrap_resume
exec
high
High — service-affecting
nodetool bootstrap resume
Resume a bootstrap that failed part way, streaming only the ranges this node is still missing — the recovery when a joining node lost a stream and stopped short of joining the ring. Fails on a node that already finished bootstrapping.
cassandra.nodetool_clientstats
exec
low
Low — read-only or trivially reversible
nodetool clientstats
List the clients connected to this node — count per user, driver, and protocol version. The read before cutting a node out of service, and the one that finds an old driver still talking to it.
cassandra.nodetool_compact
exec
high
High — service-affecting
nodetool compact <ks> [table]
Force major compaction. For STCS this merges everything into one big SSTable — almost always a mistake. Prefer per-token-range compaction or letting the strategy run.
cassandra.nodetool_compactionstats
exec
low
Low — read-only or trivially reversible
Cassandra compaction statistics
Run `nodetool compactionstats`. Pending compactions in the dozens-to-hundreds indicate the node is behind. Triggering repair on a node already behind on compactions usually makes things worse — wait for the queue to drain before recommending repair.
cassandra.nodetool_datapaths
exec
low
Low — read-only or trivially reversible
nodetool datapaths
List the directories each table stores data in — the read that shows which disk a table actually lives on before you judge a full filesystem or a JBOD imbalance.
cassandra.nodetool_disableautocompaction
exec
medium
Medium — changes state, easily reversible
nodetool disableautocompaction <keyspace> [table]
Stop automatic compaction for a keyspace or one table on this node — the usual move before a bulk load or a heavy backfill. Re-enable it with cassandra.nodetool_enableautocompaction as soon as the load is done.
cassandra.nodetool_disablebackup
exec
medium
Medium — changes state, easily reversible
nodetool disablebackup
Stop incremental backup on this node — Cassandra stops hard-linking each new SSTable into the backups directory. Use when those links are filling the disk and the backup tooling is not clearing them.
cassandra.nodetool_disablebinary
exec
critical
Critical — data loss or irreversible
nodetool disablebinary
Stop the native transport on this node — every CQL client is disconnected and no new client can connect to it. Gossip, streaming, and repair keep running, so the node stays a replica and keeps taking writes from its peers. Use to take one node out of client rotation without draining it.
cassandra.nodetool_disablegossip
exec
critical
Critical — data loss or irreversible
nodetool disablegossip
Stop gossip on this node. Every peer marks it Down and stops routing replica traffic to it, while it keeps serving whatever clients are still connected — the isolation move for a node that is poisoning cluster state, and the way to strand a node if used carelessly.
cassandra.nodetool_disablehandoff
exec
medium
Medium — changes state, easily reversible
nodetool disablehandoff
Stop this node storing hints for unreachable peers. Different from cassandra.nodetool_pausehandoff, which keeps storing them and only stops delivery. Use when hint disk use is the problem, not delivery load.
cassandra.nodetool_disablehintsfordc
exec
medium
Medium — changes state, easily reversible
nodetool disablehintsfordc <datacenter>
Stop this node storing hints for one datacenter — the move when a remote datacenter is down for maintenance, or is being retired, and its hints would otherwise pile up on every local node.
cassandra.nodetool_enableautocompaction
exec
medium
Medium — changes state, easily reversible
nodetool enableautocompaction <keyspace> [table]
Resume automatic compaction for a keyspace or one table on this node after a cassandra.nodetool_disableautocompaction. Confirm with cassandra.nodetool_statusautocompaction.
cassandra.nodetool_enablebackup
exec
medium
Medium — changes state, easily reversible
nodetool enablebackup
Start incremental backup on this node — every new SSTable is hard-linked into the table's backups directory for an external backup job to collect. Confirm with cassandra.nodetool_service_status.
cassandra.nodetool_enablebinary
exec
critical
Critical — data loss or irreversible
nodetool enablebinary
Start the native transport on this node so CQL clients can connect again — the recovery from cassandra.nodetool_disablebinary. Confirm with cassandra.nodetool_service_status.
cassandra.nodetool_enablegossip
exec
critical
Critical — data loss or irreversible
nodetool enablegossip
Start gossip on this node so the cluster sees it as Up again — the recovery from cassandra.nodetool_disablegossip. Confirm with cassandra.nodetool_service_status and cassandra.nodetool_status.
cassandra.nodetool_enablehintsfordc
exec
medium
Medium — changes state, easily reversible
nodetool enablehintsfordc <datacenter>
Resume storing hints for one datacenter after a cassandra.nodetool_disablehintsfordc — the step that goes with bringing a remote datacenter back into service.
cassandra.nodetool_garbagecollect
exec
high
High — service-affecting
nodetool garbagecollect <keyspace> [table]
Rewrite a table's SSTables to drop data already deleted or expired, without waiting for compaction to reach it — the way to reclaim space from a tombstone-heavy table on one node. Slower and heavier than letting compaction do the work.
cassandra.nodetool_gcstats
exec
low
Low — read-only or trivially reversible
nodetool gcstats
Show garbage-collection statistics since the last call — pause counts, max and total elapsed time, and memory reclaimed. Long pauses here explain client timeouts that the latency histograms alone do not.
cassandra.nodetool_getinterdcstreamthroughput
exec
low
Low — read-only or trivially reversible
nodetool getinterdcstreamthroughput
Show this node's cross-datacenter streaming cap — the rate it sends SSTable data to peers in other datacenters. Reports "unlimited" when throttling is off.
cassandra.nodetool_getseeds
exec
low
Low — read-only or trivially reversible
nodetool getseeds
List the seed nodes this node is currently using, excluding its own address — the running value, which drifts from cassandra.yaml after a cassandra.nodetool_reloadseeds or a seed-provider change.
cassandra.nodetool_getsstables
exec
low
Low — read-only or trivially reversible
nodetool getsstables <keyspace> <table> <key>
List the SSTable files that hold one partition key — how many files a read of that key must touch. Empty output means the key's data is still in the memtable or absent.
cassandra.nodetool_getstreamthroughput
exec
low
Low — read-only or trivially reversible
nodetool getstreamthroughput
Show this node's outbound streaming cap — the rate it sends SSTable data during bootstrap, rebuild, repair, and decommission. Reports "unlimited" when throttling is off.
cassandra.nodetool_invalidaterolescache
exec
medium
Medium — changes state, easily reversible
nodetool invalidaterolescache
Drop this node's cached roles so a role or membership change takes effect now instead of when the cache expires — the companion to cassandra.nodetool_invalidatepermissionscache after editing roles.
cassandra.nodetool_pausehandoff
exec
medium
Medium — changes state, easily reversible
nodetool pausehandoff
Pause hint delivery from this node. Hints keep accumulating; only the replay to peers stops — the move when a peer that just came back is being flooded. Resume with cassandra.nodetool_resumehandoff.
cassandra.nodetool_rebuild_index
exec
high
High — service-affecting
nodetool rebuild_index <keyspace> <table> <index>
Rebuild one secondary index on this node from its base table — the fix when an index returns stale or missing rows after a restore, a scrub, or index corruption.
cassandra.nodetool_refresh
exec
medium
Medium — changes state, easily reversible
nodetool refresh <keyspace> <table>
Load SSTable files that were placed into a table's data directory into the running node, with no restart — the last step of a file-level restore. Cassandra 5.0 prints a deprecation notice pointing at `nodetool import`, and still performs the load.
cassandra.nodetool_refreshsizeestimates
exec
medium
Medium — changes state, easily reversible
nodetool refreshsizeestimates
Recompute the system.size_estimates table this node publishes. Run it when cassandra.cqlsh_system_size_estimates looks stale — Spark and analytics connectors split work from those numbers.
cassandra.nodetool_reloadlocalschema
exec
medium
Medium — changes state, easily reversible
nodetool reloadlocalschema
Reload this node's schema from its own system tables — the first, cheap remedy when cassandra.nodetool_describecluster reports this node on a different schema version from the rest.
cassandra.nodetool_reloadseeds
exec
medium
Medium — changes state, easily reversible
nodetool reloadseeds
Re-read the seed list from the seed provider without restarting — the step after editing seeds in cassandra.yaml, typically while replacing seed nodes. Read the result back with cassandra.nodetool_getseeds.
cassandra.nodetool_reloadssl
exec
medium
Medium — changes state, easily reversible
nodetool reloadssl
Reload the keystore and truststore from disk so a renewed certificate takes effect without a restart — the step that finishes a certificate rotation on a live node.
cassandra.nodetool_relocatesstables
exec
high
High — service-affecting
nodetool relocatesstables <keyspace> <table>
Move a table's SSTables onto the disk that owns their token range — the fix after adding or replacing a data directory on a node that spreads data across several disks. A no-op on a node with one data directory.
cassandra.nodetool_repair
exec
high
High — service-affecting
Cassandra repair
Wrap `nodetool repair`. The most dangerous "normal" operation — repair reconciles data between replicas, can take hours, produces significant cluster-wide load, may interact poorly with TTL/tombstone-heavy tables, and can worsen latency on every replica it touches. Always inspect ring status, compactions, disk, and logs first. Prefer mode=preview — a dry run that estimates the repair without performing it (requires Cassandra 4.0+) — before a real repair. Refuse to proceed if the ring has DN/UJ/UL/UM nodes.
cassandra.nodetool_repair_admin_list
exec
low
Low — read-only or trivially reversible
nodetool repair_admin list
List the incremental repair sessions this node knows about. A session stuck in a non-finished state is what keeps SSTables pending repair and blocks later repairs; "no sessions" is the healthy answer.
cassandra.nodetool_replaybatchlog
exec
medium
Medium — changes state, easily reversible
nodetool replaybatchlog
Replay this node's batchlog now and wait for it to finish, instead of waiting for the periodic sweep — the step that clears batches left behind after a node came back from an outage.
cassandra.nodetool_scrub
exec
high
High — service-affecting
nodetool scrub <keyspace> [table]
Rebuild a table's SSTables on this node, validating each row as it goes — the repair for corrupt files reported in the log. Snapshots first by default, so the pre-scrub files remain until you clear that snapshot.
Check what this node currently has switched on — native transport (client traffic), gossip, incremental backup, and hinted handoff — in one call. The read to take before and after any of the enable/disable actions.
cassandra.nodetool_setbatchlogreplaythrottle
exec
medium
Medium — changes state, easily reversible
nodetool setbatchlogreplaythrottle <KiB/s>
Set the batchlog replay throttle in KiB/s. Lower it when replaying batches after an outage is adding load to an already busy node; 0 disables throttling. Read the current value with cassandra.nodetool_getbatchlogreplaythrottle.
Set the key, row, and counter cache capacities in MB. All three are set in one call, so pass the current value for any cache you are not changing; 0 disables a cache. cassandra.nodetool_info reports the capacities in use.
Set the min and max SSTable count that triggers size-tiered compaction for one table. Raising the minimum makes the table compact less often and keeps more SSTables; lowering it compacts sooner. Read the current pair with cassandra.nodetool_getcompactionthreshold.
cassandra.nodetool_setconcurrency
exec
medium
Medium — changes state, easily reversible
nodetool setconcurrency <stage> <max>
Set the maximum number of threads one request-processing stage may use. Lower a stage to stop it crowding out the rest of the node, raise it when a stage is the bottleneck. List the stages and their current sizes with cassandra.nodetool_getconcurrency.
cassandra.nodetool_setconcurrentcompactors
exec
medium
Medium — changes state, easily reversible
nodetool setconcurrentcompactors <count>
Set how many compactions this node runs at once. Raise it to work off a compaction backlog, lower it to give CPU and disk back to reads and writes. Read the current value with cassandra.nodetool_getconcurrentcompactors.
cassandra.nodetool_setconcurrentviewbuilders
exec
medium
Medium — changes state, easily reversible
nodetool setconcurrentviewbuilders <count>
Set how many materialized-view builds this node runs at once. Lower it when a view build is competing with live traffic, raise it to finish a build sooner. Read the current value with cassandra.nodetool_getconcurrentviewbuilders.
cassandra.nodetool_sethintedhandoffthrottlekb
exec
medium
Medium — changes state, easily reversible
nodetool sethintedhandoffthrottlekb <KiB/s>
Set the hinted-handoff delivery throttle in KiB/s, per delivery thread. Lower it when a peer coming back online is being flooded with replayed hints; raise it to clear a hint backlog faster.
cassandra.nodetool_setinterdcstreamthroughput
exec
medium
Medium — changes state, easily reversible
nodetool setinterdcstreamthroughput <value>
Set this node's cross-datacenter streaming cap — the rate it sends SSTable data to peers in other datacenters during rebuild, bootstrap, and repair. Protects a shared or metered inter-datacenter link while local streaming keeps its own cap from cassandra.nodetool_setstreamthroughput. 0 disables throttling.
cassandra.nodetool_setmaxhintwindow
exec
medium
Medium — changes state, easily reversible
nodetool setmaxhintwindow <ms>
Set how long this node keeps writing hints for an unreachable peer, in milliseconds. Raise it to carry a peer through a longer maintenance window without a repair afterwards; 0 stops hint storage entirely. Read the current window with cassandra.nodetool_getmaxhintwindow.
cassandra.nodetool_setsnapshotthrottle
exec
medium
Medium — changes state, easily reversible
nodetool setsnapshotthrottle <links/s>
Set how many hard links per second snapshot and clearsnapshot may create. Lower it when taking a snapshot of a large node stalls the filesystem; 0 disables throttling. Read the current value with cassandra.nodetool_getsnapshotthrottle.
cassandra.nodetool_setstreamthroughput
exec
medium
Medium — changes state, easily reversible
nodetool setstreamthroughput <value>
Set this node's outbound streaming cap — the rate it sends SSTable data during bootstrap, rebuild, repair, and decommission. Covers every stream the node sends; cross-datacenter streams are additionally capped by cassandra.nodetool_setinterdcstreamthroughput. 0 disables throttling.
cassandra.nodetool_settimeout
exec
medium
Medium — changes state, easily reversible
nodetool settimeout <type> <ms>
Set one of this node's request or internode timeouts, in milliseconds. Raise a timeout to ride out a slow period instead of failing queries, or lower it to fail fast. Read the current value with cassandra.nodetool_gettimeout.
cassandra.nodetool_settraceprobability
exec
medium
Medium — changes state, easily reversible
nodetool settraceprobability <probability>
Set the fraction of requests this node traces, between 0 and 1. Turn tracing on briefly to see where latency goes, then set it back to 0. Read the current value with cassandra.nodetool_gettraceprobability.
cassandra.nodetool_status
exec
low
Low — read-only or trivially reversible
Cassandra node ring status
Run `nodetool status`. Read-only — does not change Cassandra state. Use this before suggesting repair, cleanup, decommission, replacement, or topology changes. If any node is DN/UJ/UL/UM, do not recommend repair until the failure mode is understood.
cassandra.nodetool_statusautocompaction
exec
low
Low — read-only or trivially reversible
nodetool statusautocompaction [keyspace] [table]
Check whether automatic compaction is running — for the whole node, one keyspace, or one table. The read that catches a table left with autocompaction off after a bulk load.
cassandra.nodetool_tablestats
exec
low
Low — read-only or trivially reversible
Cassandra table stats
Run `nodetool tablestats`, optionally scoped to a single keyspace. Read-only. Output can be large for clusters with many tables. Use to identify tables with large sstable counts or large on-disk size — repairs on very large or tombstone-heavy tables are risky and worth surfacing before a repair recommendation.
Sample one table's traffic for a few seconds and print its busiest partitions by read and write frequency — the direct answer to "which key is hot" that cassandra.cqlsh_largest_partitions cannot give, since the biggest partition and the busiest one are rarely the same.
cassandra.nodetool_tpstats
exec
low
Low — read-only or trivially reversible
Cassandra thread pool stats
Run `nodetool tpstats` for active/pending/blocked counts per pool. High pending or blocked counts on MutationStage, CompactionExecutor, or ReadStage usually indicate ongoing pressure — investigate the cause before recommending operations that add load (repair, large reads, compaction tuning).
cassandra.nodetool_truncatehints
exec
high
High — service-affecting
nodetool truncatehints [endpoint]
Delete the hints this node is holding — all of them, or only those for one endpoint. The release valve when a hint backlog is filling the disk or targets a node that will never come back. The deleted writes are gone from this node's hint store, so the peers they were for need a repair.
cassandra.nodetool_upgradesstables
exec
high
High — service-affecting
nodetool upgradesstables <keyspace> [table]
Rewrite SSTables that are still in an older on-disk format into the current one — the step after a major-version upgrade, and what lets the old format's read path be retired.
cassandra.nodetool_viewbuildstatus
exec
low
Low — read-only or trivially reversible
nodetool viewbuildstatus <keyspace> <view>
Show whether a materialized view has finished building, per node. Exits non-zero while the build is still running, and names the nodes that are behind.
