Schedule icon
Webhook icon
Assert icon
Query icon
Get icon
Script icon
Set icon
If icon
Pause icon
Loop icon
Log icon
SlackIncomingWebhook icon

Cassandra Speculative Retry Storm Mitigation and Safe Alignment Guard

Audit Cassandra table speculative retry policies, pause for operator approval, mitigate read retry storms with safe CQL alterations, and verify in Kestra.

Categories
DataInfrastructure

In Apache Cassandra, speculative retry is designed to eliminate high tail read latencies by allowing the coordinator node to issue a speculative read request to a second replica if the primary replica fails to respond within a defined threshold. However, when database tables are configured with aggressive speculative retry policies, most notably speculative_retry = 'ALWAYS' or excessively low millisecond thresholds (e.g., 5ms or 10ms), the coordinator duplicates read I/O across cluster nodes on every single query.

Under peak production query workloads, aggressive speculative retries double or triple coordinator read traffic, rapidly saturating JVM ReadStage thread pool queues and exhausting operating system page cache. When a temporary network blip or garbage collection pause occurs, duplicate speculative requests overwhelm struggling nodes, creating a self-reinforcing "retry storm" that triggers widespread ReadTimeoutException errors and brings down live customer microservices.

This blueprint provides an automated Day-2 operations guard that inspects system_schema.tables for aggressive speculative retry policies across user keyspaces, tracks policy drift across executions in Kestra KV, gates DDL changes behind a human approval Pause, issues safe CQL ALTER TABLE statements (aligning policies to 99p or NONE), verifies post-remediation schema conformity, and publishes detailed Slack audit telemetry.

How it works

  1. Pre-flight Assertion: Validates operational inputs (io.kestra.plugin.core.execution.Assert), confirming valid hostnames, CQL port bounds (1-65535), and non-empty remediation policies.
  2. Schema Metadata Collection: scan_tables_speculative_retry (io.kestra.plugin.cassandra.standard.Query) queries system_schema.tables over the native CQL binary protocol to extract keyspace names, table names, and current speculative_retry policies.
  3. Historical State Retrieval: get_previous_audit_state (io.kestra.plugin.core.kv.Get) retrieves prior execution audit records from the Kestra KV store to identify chronic policy violations across runs.
  4. Triage and Policy Analysis: A Python inspection script (inspect_speculative_retry_policies) excludes built-in system keyspaces (system, system_schema, system_auth), filters by target keyspaces, and flags tables where speculative_retry is set to ALWAYS or a fixed-latency threshold below max_fixed_ms_ceiling. It formats the proposed ALTER TABLE <keyspace>.<table> WITH speculative_retry = '<remediation_policy>' DDL statements.
  5. Cross-Run State Persistence: save_audit_state (io.kestra.plugin.core.kv.Set) updates Kestra KV with consecutive violation counters and policy snapshots for every evaluated table.
  6. Human Approval Gate: When unsafe tables are detected and dry_run is disabled, the workflow halts at pause_for_remediation_approval (io.kestra.plugin.core.flow.Pause), presenting operators with flagged table names, current aggressive policies, and proposed safe settings.
  7. Write-Path Schema Alteration: Upon operator approval, apply_remediation_loop (io.kestra.plugin.core.flow.Loop) iterates through each flagged table and executes the safe ALTER TABLE CQL statement via io.kestra.plugin.cassandra.standard.Query.
  8. Post-Remediation Verification: verify_speculative_retry_remediation re-queries system_schema.tables, and verify_remediation_results asserts that all target tables have been updated to the safe policy, confirming zero remaining retry storm risks.
  9. Audit & Escalation Alerting: Structured Slack alerts (notify_slack_audit) report cluster health status, flagged table counts, and remediation modes, while flow-level errors capture cluster connectivity failures.

What you get

  • Continuous protection against Cassandra read thread pool exhaustion and cascading retry storms.
  • Automated detection of tables configured with ALWAYS or dangerous sub-20ms speculative retry floors.
  • Safe human-in-the-loop approval gate before executing DDL schema modifications on production clusters.
  • Automated CQL ALTER TABLE remediation aligning tables to recommended 99th-percentile (99p) thresholds.
  • Post-remediation schema re-query asserting complete elimination of aggressive policies.
  • Historical state persistence in Kestra KV store for compliance tracking and drift auditing.

Who it's for

  • Database Reliability Engineers (DBREs) and SREs managing multi-node Apache Cassandra or ScyllaDB clusters.
  • Platform Engineers maintaining distributed backend microservices subject to read latency spikes.
  • Data Infrastructure Teams seeking automated schema governance and performance guardrails.

Why orchestrate this with Kestra

Cassandra's command-line tools like cqlsh require manual query execution and lack automated scheduling, cross-run state tracking, or centralized audit logs. Custom cron scripts running cqlsh create single points of failure without built-in pause-and-resume approval mechanics or credential encryption.

Orchestrating this guard with Kestra delivers a declarative workflow with native CQL driver support, approval gates (Pause), cross-execution KV state tracking, secret masking, and real-time Slack escalation.

Prerequisites

  • An accessible Apache Cassandra cluster (version 3.11, 4.x, or 5.x) reachable from the Kestra worker.
  • CQL administrative credentials with permissions to query system_schema.tables and alter table schemas.
  • A Slack Incoming Webhook URL for incident alerting.

Secrets

  • SLACK_WEBHOOK_URL: Slack Incoming Webhook endpoint used for compliance notifications and error alerts.
  • CASSANDRA_GUARD_WEBHOOK_KEY: Secret authentication key protecting the on-demand webhook trigger.
  • CASSANDRA_PASSWORD: Password for Cassandra native authentication (if enabled on the cluster).

Quick start

  1. Configure SLACK_WEBHOOK_URL and CASSANDRA_GUARD_WEBHOOK_KEY in your Kestra namespace secrets.
  2. Import this blueprint and set cassandra_host, cassandra_port, and target_keyspaces to match your cluster.
  3. Run a manual execution with dry_run: true to review current table configurations without altering schemas.
  4. Enable the periodic_speculative_retry_guard schedule trigger to audit cluster tables every 4 hours.
  5. When ready for automated alignment, set dry_run: false to allow operator-approved CQL table alterations.

How to extend

  • Tombstone Threshold Alignment: Chain an additional inspection step to audit tombstone_threshold and unchecked_tombstone_compaction settings on flagged tables.
  • PagerDuty Incident Escalation: Integrate io.kestra.plugin.pagerduty.notifications.PagerDutyAlert to page on-call DBREs when multiple tables exhibit chronic retry storm risks.
  • Nodetool Metric Sampling: Add a io.kestra.plugin.scripts.shell.Commands task to sample live JMX org.apache.cassandra.metrics:type=ThreadPools,path=request,scope=ReadStage metrics before and after DDL execution.

Links

See How

New to Kestra?

Use blueprints to kickstart your first workflows.