Keyspaces Diagnostics

Amazon Keyspaces (for Apache Cassandra) Diagnostics

When to use

Any Amazon Keyspaces investigation where the console alone is insufficient — table creation failures, schema issues, CQL compatibility, read/write throttling, hot partitions, connectivity problems, TLS/SigV4 authentication, capacity planning, TTL behavior, PITR backup/restore, or Cassandra migration.

Investigation workflow

Step 1 — Collect and triage

aws keyspaces list-keyspaces
aws keyspaces get-keyspace --keyspace-name <keyspace>
aws keyspaces list-tables --keyspace-name <keyspace>
aws keyspaces get-table --keyspace-name <keyspace> --table-name <table>
aws cloudwatch get-metric-statistics --namespace AWS/Cassandra --metric-name PerConnectionRequestRateExceeded --dimensions Name=TableName,Value=<table> --start-time <start> --end-time <end> --period 300 --statistics Sum

Step 2 — Domain deep dive

aws cloudwatch get-metric-statistics --namespace AWS/Cassandra --metric-name ReadThrottleEvents --dimensions Name=TableName,Value=<table> --start-time <start> --end-time <end> --period 300 --statistics Sum
aws cloudwatch get-metric-statistics --namespace AWS/Cassandra --metric-name WriteThrottleEvents --dimensions Name=TableName,Value=<table> --start-time <start> --end-time <end> --period 300 --statistics Sum
aws cloudwatch get-metric-statistics --namespace AWS/Cassandra --metric-name SuccessfulRequestLatency --dimensions Name=TableName,Value=<table> Name=Operation,Value=SELECT --start-time <start> --end-time <end> --period 300 --statistics Average
aws application-autoscaling describe-scalable-targets --service-namespace cassandra --resource-ids keyspace/<keyspace>/table/<table>
aws keyspaces get-table --keyspace-name <keyspace> --table-name <table> --query '{CapacityMode:CapacitySpecification,TTL:Ttl,PITR:PointInTimeRecovery}'

Step 3 — Detailed investigation

aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=cassandra.amazonaws.com --max-results 20
aws cloudwatch get-metric-statistics --namespace AWS/Cassandra --metric-name SystemErrors --dimensions Name=TableName,Value=<table> --start-time <start> --end-time <end> --period 300 --statistics Sum
aws cloudwatch get-metric-statistics --namespace AWS/Cassandra --metric-name ConsumedReadCapacityUnits --dimensions Name=TableName,Value=<table> --start-time <start> --end-time <end> --period 300 --statistics Sum
aws cloudwatch get-metric-statistics --namespace AWS/Cassandra --metric-name ConsumedWriteCapacityUnits --dimensions Name=TableName,Value=<table> --start-time <start> --end-time <end> --period 300 --statistics Sum

Read references/keyspaces-guardrails.md before concluding on any Keyspaces issue.

Tool quick reference

Gotchas: Amazon Keyspaces

• Keyspaces is NOT Apache Cassandra. It is a serverless, CQL-compatible service with a different underlying engine. Many Cassandra-native features are unavailable. Do not assume Cassandra documentation applies directly.
• No ALLOW FILTERING by default. Queries must use partition key. Full table scans via ALLOW FILTERING are not supported in the same way as open-source Cassandra. Queries must be designed around partition keys.
• No lightweight transactions (LWT) in some versions. Conditional writes (IF NOT EXISTS, IF conditions) have limited support. Check current documentation for LWT availability in your region.
• Partition key design is critical — same principles as DynamoDB. Hot partitions cause throttling. Distribute writes evenly across partition keys. Single hot partition can throttle the entire table.
• TLS is required for all connections. Keyspaces does not accept unencrypted connections. Port 9142 with TLS. The Starfield digital certificate must be trusted by the client.
• SigV4 or service-specific credentials for authentication. IAM-based SigV4 authentication is recommended. Service-specific credentials (username/password) are an alternative generated via IAM console. No native Cassandra authentication.
• No UDFs, UDAs, or materialized views. User-defined functions, user-defined aggregates, and materialized views are not supported. Use application-side logic or secondary indexes instead.
• TTL maximum is 630,720,000 seconds (20 years). TTL values exceeding this are rejected. TTL is set per-row, not per-table. Expired data is deleted asynchronously and may be visible briefly after expiration.
• PITR provides continuous backup. Point-in-time recovery is always-on continuous backup with 35-day retention. Restores create a new table. No manual snapshots like Cassandra nodetool.
• No multi-region tables natively. Use application-level replication patterns. Keyspaces does not support Cassandra-style multi-datacenter replication. Each table exists in a single region.

Anti-hallucination rules

1. Always cite specific table names, keyspace names, or API responses as evidence.
2. Keyspaces is NOT Cassandra. Never suggest Cassandra-specific tools (nodetool, cassandra-stress) or features (materialized views, UDFs).
3. TLS is mandatory. Never suggest connecting without TLS or on port 9042.
4. Partition key design drives performance. Never ignore partition key analysis for throttling issues.
5. CQL compatibility is partial. Never assume all CQL features work. Verify against Keyspaces documentation.
6. Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.

22 runbooks