Cassandra Change Data Capture (CDC)

Change Data Capture (CDC) provides a mechanism for capturing row-level changes in Cassandra tables. When enabled, CDC creates hard links from commit log segments to a dedicated directory, allowing external systems to consume mutations as they occur.

CDC was introduced in Cassandra 3.8 and is designed for integration with streaming platforms, real-time analytics, and cross-system data synchronization.

---

Architecture Overview

CDC operates by leveraging the existing commit log infrastructure. Rather than modifying the write path, it creates hard links to commit log segments containing mutations for CDC-enabled tables.

How CDC Works

1. Write arrives: Mutation is written to commit log and memtable (normal write path)
2. Segment creation: When a new commit log segment is created, if cdc_enabled=true, a hard link is created in cdc_raw_directory
3. Index file creation: On segment fsync, a <segment_name>_cdc.idx file is created containing the byte offset of persisted data
4. Segment completion: When the segment is fully flushed, "COMPLETED" is appended to the index file
5. Consumer processing: External consumers read segments from cdc_raw_directory, respecting offset values for durability
6. Cleanup: Consumers must delete processed segments; Cassandra does not automatically clean up CDC files

---

Configuration

CDC is configured at two levels: node-wide settings in cassandra.yaml and per-table settings via CQL.

Node Configuration (cassandra.yaml)

# Enable CDC functionality node-wide
cdc_enabled: true

# Directory for CDC commit log hard links
# Should be on separate spindle from data directories
# Must be on same filesystem as commitlog_directory
cdc_raw_directory: /var/lib/cassandra/cdc_raw

# Maximum space for CDC logs before writes are rejected
# Default: min(4096 MiB, 1/8 of volume space)
# Cassandra 4.1+: cdc_total_space (with size unit, e.g., 4096MiB)
# Cassandra 4.0:  cdc_total_space_in_mb (integer MB)
cdc_total_space: 4096MiB

# How often to check CDC directory space usage
# Default: 250ms
# Cassandra 4.1+: cdc_free_space_check_interval (with duration, e.g., 250ms)
# Cassandra 4.0:  cdc_free_space_check_interval_ms (integer milliseconds)
cdc_free_space_check_interval: 250ms

CDC Configuration by Version:

Parameter	Cassandra 4.0	Cassandra 4.1+	Default
CDC space limit	cdc_total_space_in_mb (integer)	cdc_total_space (e.g., 4096MiB)	min(4096 MiB, 1/8 volume)
Space check interval	cdc_free_space_check_interval_ms (integer)	cdc_free_space_check_interval (e.g., 250ms)	250ms

Parameter	Default	Description
cdc_enabled	false	Enables CDC node-wide. When true, writes to CDC-enabled tables are rejected if cdc_raw_directory exceeds space limit
cdc_raw_directory	$CASSANDRA_HOME/data/cdc_raw	Destination for commit log hard links
cdc_total_space	min(4096MiB, 1/8 volume)	Space threshold before write rejection
cdc_free_space_check_interval	250ms	Frequency of space usage recalculation

Table Configuration (CQL)

Enable CDC on individual tables:

-- Enable CDC when creating table
CREATE TABLE events (
    event_id UUID,
    event_time TIMESTAMP,
    event_type TEXT,
    payload TEXT,
    PRIMARY KEY (event_id)
) WITH cdc = true;

-- Enable CDC on existing table
ALTER TABLE events WITH cdc = true;

-- Disable CDC
ALTER TABLE events WITH cdc = false;

---

CDC File Format

Commit Log Hard Links

Files in cdc_raw_directory are hard links to commit log segments. They share the same inode as the original commit log file, meaning:

• Hard links initially consume no additional disk space for the data itself
• Reading from CDC directory reads the same data as the commit log
• Modifications to the original segment are visible through the hard link

Disk Space Impact

While hard links share data with the original commit log segment, they prevent segment reuse. Cassandra cannot recycle commit log segments that have CDC hard links until consumers delete the hard links. This effectively increases disk utilization over time if consumers fall behind—space is held until both the original segment is flushed and the CDC hard link is deleted.

cdc_raw_directory/
├── CommitLog-7-1702987654321.log      # Hard link to commit log segment
├── CommitLog-7-1702987654321_cdc.idx  # Index file with offset
├── CommitLog-7-1702987654322.log
├── CommitLog-7-1702987654322_cdc.idx
└── ...

Index Files (_cdc.idx)

Each commit log segment in the CDC directory has a corresponding index file:

# While segment is being written
1234567

# After segment is complete
1234567
COMPLETED

State	Index File Content	Consumer Action
In progress	Integer offset only	Read up to offset bytes only
Complete	Offset + "COMPLETED"	Safe to read entire segment and delete

Durability Guarantee

Consumers must only parse data up to the offset specified in the index file. Data beyond that offset may not be durable and could be lost on crash recovery.

---

Backpressure and Write Rejection

When cdc_raw_directory exceeds the configured space limit, Cassandra applies backpressure by rejecting writes to CDC-enabled tables.

Monitoring CDC Space

Cassandra does not expose dedicated JMX metrics for CDC space usage. The CDC size tracking is internal to CommitLogSegmentManagerCDC. Monitor CDC space through filesystem monitoring:

# Check cdc_raw directory size
du -sh /var/lib/cassandra/cdc_raw/

# Count pending CDC segments
ls -1 /var/lib/cassandra/cdc_raw/*.log 2>/dev/null | wc -l

# Check for completed segments (ready for processing)
grep -l "COMPLETED" /var/lib/cassandra/cdc_raw/*_cdc.idx 2>/dev/null | wc -l

Monitoring Approach	Description
Filesystem monitoring	Track cdc_raw_directory size with node_exporter or similar
Segment count	Count .log files in CDC directory
Completion rate	Track ratio of segments with "COMPLETED" in .idx files
Log monitoring	Watch for "CDC is full" rejection messages

Alerting Recommendations

Condition	Action
cdc_raw size > 50% of cdc_total_space_in_mb	Warning: Consumer may be falling behind
cdc_raw size > 75% of cdc_total_space_in_mb	Critical: Consumer is falling behind
cdc_raw size > 90% of cdc_total_space_in_mb	Emergency: Write rejection imminent
"CDC is full" in logs	Writes to CDC-enabled tables are being rejected

---

Consumption Patterns

Consumer Responsibilities

CDC consumers must:

1. Poll for new segments: Watch cdc_raw_directory for new files
2. Read index files: Parse _cdc.idx to determine safe read offset
3. Parse commit log format: Decode mutations from binary commit log format
4. Handle duplicates: Same mutation may appear in multiple segments (replicas)
5. Delete processed files: Remove segments after successful processing

Consumer Required

Do not enable CDC without an active consumption process. Without consumers deleting processed files, cdc_raw_directory fills up and writes to CDC-enabled tables are rejected.

Integration Options

Tool	Description	Deduplication	Use Case
Debezium	Open-source CDC platform	No - consumers must deduplicate	Kafka integration, schema evolution
DataStax CDC for Pulsar	Official connector	Yes - MD5 digest cache	Apache Pulsar streaming
Custom consumer	Direct commit log parsing	Must implement	Specialized requirements

Debezium Integration

Debezium provides a Cassandra connector that consumes CDC data and produces change events to Kafka:

Key Debezium characteristics:

• Runs agent on each Cassandra node
• Monitors cdc_raw_directory for new segments
• Produces Kafka messages with row change data
• Does not deduplicate: Due to replication factor, the same mutation appears on multiple nodes; downstream consumers must handle deduplication
• Default behavior waits for completion: By default, Debezium waits for the _cdc.idx file to be marked "COMPLETED" before processing, adding latency

Real-Time Processing Trade-off

The default Debezium behavior (waiting for segment completion) adds latency but guarantees durability. Organizations requiring near real-time CDC (sub-second latency) have modified Debezium to process commit logs continuously as data arrives, before the completion marker. This trades durability guarantees for lower latency—on crash, some events may be reprocessed or lost.

---

Operational Considerations

Filesystem Requirements

Requirement	Reason
Same filesystem for commitlog and cdc_raw	Hard links cannot span filesystems
Separate spindle for cdc_raw (recommended)	Reduces I/O contention with commit log
Sufficient space	Consumers must keep up to avoid write rejection

Performance Impact

CDC has minimal performance impact on normal operations:

Operation	Impact
Write latency	Negligible (hard link creation is metadata-only)
Commit log fsync	Slight increase (index file creation)
Disk space	Hard links share inodes but prevent segment reuse until consumers delete files
CPU	None on Cassandra side; consumers bear parsing cost

Version Compatibility

Cassandra Version	CDC Support
< 3.8	Not available
3.8 - 3.11	Basic CDC
4.0+	Enhanced CDC with improved metrics
5.0+	CDC improvements for large partitions

Mixed-Version Clusters

Do not enable CDC on mixed-version clusters. Upgrade all nodes to the same version before enabling CDC.

---

Use Cases

Event Streaming

Capture mutations as events for downstream processing:

CREATE TABLE orders (
    order_id UUID,
    customer_id UUID,
    order_time TIMESTAMP,
    status TEXT,
    total DECIMAL,
    PRIMARY KEY (order_id)
) WITH cdc = true;

Each insert or update produces a change event containing the full row state.

Cache Invalidation

Invalidate caches when source data changes:

Cross-Datacenter Sync

Replicate changes to external systems:

Source	Target	Method
Cassandra	Elasticsearch	CDC → Kafka → ES Connector
Cassandra	Data Lake	CDC → Kafka → S3 Sink
Cassandra	Analytics DB	CDC → Kafka → JDBC Sink

Audit Logging

Capture all changes for compliance:

CREATE TABLE user_profiles (
    user_id UUID PRIMARY KEY,
    email TEXT,
    phone TEXT,
    preferences MAP<TEXT, TEXT>
) WITH cdc = true;

CDC events provide a complete audit trail of all profile changes.

---

Deduplication Strategies

Due to Cassandra's replication, the same mutation is captured on multiple nodes. For RF=3, each write produces up to 3 CDC events. Consumers must deduplicate.

Strategy	Description	Trade-off
MD5 digest cache	Hash mutation content, cache seen digests	Memory-bound; loses state on restart
Kafka exactly-once	Use Kafka transactions with idempotent producers	Adds latency; requires Kafka configuration
Downstream dedup	Deduplicate in stream processor (Flink, Spark)	Adds processing layer; more infrastructure
Database constraint	Use upserts/idempotent writes to target	Target must support; may miss deletes
Single-node consumption	Consume from one node only	Loses CDC if that node fails

For high-scale environments (tens of thousands of events per second), dedicated deduplication infrastructure is typically required. Solutions like Apache Flink or custom stateful processors provide the scale and state retention needed for reliable deduplication.

---

Limitations

Limitation	Description
No built-in parser	Consumers must parse binary commit log format
No automatic cleanup	Consumers must delete processed files
Space-based backpressure	Write rejection when CDC directory fills
Replica duplication	Same mutation captured on all replicas; consumers must deduplicate
No filtering	All mutations to CDC-enabled tables are captured
Schema changes	Consumers must handle schema evolution
Latency vs durability	Real-time processing requires trading off durability guarantees

---

Related Documentation

• Write Path - Commit log and memtable operations
• Commit Log Configuration - cassandra.yaml settings
• Monitoring - Metrics and alerting
• Outbox Pattern - Alternative pattern for event publishing