# RNACOS_RAFT_SNAPSHOT_LOG_SIZE: Tuning Raft Snapshot Frequency in r-nacos

> Tune r-nacos Raft snapshot frequency with RNACOS_RAFT_SNAPSHOT_LOG_SIZE. Balance recovery speed and runtime performance by adjusting log entry processing before snapshots. Learn how to optimize your cluster.

- Repository: [Nacos Group/r-nacos](https://github.com/nacos-group/r-nacos)
- Tags: internals
- Published: 2026-03-07

---

**RNACOS_RAFT_SNAPSHOT_LOG_SIZE is an environment variable that controls how many Raft log entries r-nacos processes before triggering a state machine snapshot, directly balancing between recovery speed and runtime performance.**

In distributed consensus systems like those powering the `nacos-group/r-nacos` repository, **RNACOS_RAFT_SNAPSHOT_LOG_SIZE** determines the threshold for log compaction. This configuration parameter governs when the Raft engine compresses committed entries into binary snapshots, impacting both cluster recovery times and ongoing throughput.

## What is RNACOS_RAFT_SNAPSHOT_LOG_SIZE?

`RNACOS_RAFT_SNAPSHOT_LOG_SIZE` defines the number of committed log entries that must accumulate before the Raft subsystem initiates a **snapshot**—a compacted binary representation of the current state machine. When the node reaches this threshold, it creates the snapshot and discards the older log entries covered by that snapshot.

The application reads this value during startup in [`src/common/mod.rs`](https://github.com/nacos-group/r-nacos/blob/main/src/common/mod.rs)【https://github.com/nacos-group/r-nacos/blob/master/src/common/mod.rs#L185-L188】, where it populates the `AppSysConfig` struct with a default value of **10000** entries if the environment variable is not set.

## How Raft Snapshotting Works in r-nacos

The snapshot policy is applied during Raft initialization in [`src/starter.rs`](https://github.com/nacos-group/r-nacos/blob/main/src/starter.rs)【https://github.com/nacos-group/r-nacos/blob/master/src/starter.rs#L10-L13】:

```rust
let config = Config::build("rnacos raft".to_owned())
    .snapshot_policy(async_raft_ext::SnapshotPolicy::LogsSinceLast(
        sys_config.raft_snapshot_log_size,
    ))
    // …

```

When the Raft engine commits a new entry, it increments an internal counter. Once the number of entries since the last snapshot exceeds `raft_snapshot_log_size`, the leader triggers the snapshot creation process. This involves serializing the current state machine, writing it to disk, and subsequently truncating the Raft log to remove the now-redundant entries.

## Performance Implications of Snapshot Frequency

Tuning `RNACOS_RAFT_SNAPSHOT_LOG_SIZE` requires balancing **write throughput**, **recovery latency**, and **resource consumption**. The setting creates distinct trade-offs across the cluster.

### Low Values: Frequent Snapshots

Setting the value between **1,000** and **5,000** entries causes snapshots to occur frequently. This configuration minimizes the Raft log size, reducing memory consumption and disk usage for log entries. Network replication remains lightweight, and follower nodes or recovering leaders can synchronize quickly because they transfer fewer historical entries.

However, frequent snapshots impose significant CPU and I/O overhead. Each snapshot creation involves serializing the entire state machine, which can cause latency spikes during heavy write workloads. Network bandwidth also increases as snapshot files transfer between nodes.

### High Values: Infrequent Snapshots

Configuring values above **20,000** entries defers snapshot creation, allowing the system to maintain higher sustained write throughput. The Raft engine spends less time on compaction and serialization, dedicating more resources to processing client requests.

The trade-off manifests in increased log storage requirements and degraded recovery performance. Follower nodes must receive and replay thousands of log entries to synchronize, extending the time required for cluster membership changes or leader election. Memory pressure grows as the un-snapshoted log accumulates in RAM.

### Default Configuration (10,000 entries)

The default value of **10,000** entries represents a balanced compromise for typical production workloads. It constrains log growth to manageable levels while limiting snapshot frequency to approximately 1-2% of total processing time for standard configurations.

## Configuring RNACOS_RAFT_SNAPSHOT_LOG_SIZE

Operators can adjust this parameter through environment variables before node startup, as the configuration is read-only during runtime initialization.

### Single-Node Deployment

For standalone development or testing environments, export the variable before launching the binary:

```bash
export RNACOS_RAFT_SNAPSHOT_LOG_SIZE=5000
./target/release/r-nacos

```

This configuration triggers snapshots every 5,000 entries, suitable for testing snapshot behavior without extended runtime.

### Docker Compose Setup

In containerized deployments, specify the environment variable in the service definition:

```yaml
services:
  rnacos:
    image: nacos-group/r-nacos:latest
    environment:
      - RNACOS_RAFT_SNAPSHOT_LOG_SIZE=20000
    ports:
      - "8848:8848"
      - "9848:9848"
    volumes:
      - ./data:/app/data

```

This higher threshold reduces snapshot overhead in production container environments where write throughput takes priority over rapid node recovery.

### Runtime Verification

To confirm the active configuration, inspect the initialized `AppSysConfig` value during application startup logging. The effective value appears in the Raft configuration initialization at [`src/starter.rs`](https://github.com/nacos-group/r-nacos/blob/main/src/starter.rs), where the `snapshot_policy` parameter receives the parsed integer.

```rust
log::info!("Raft snapshot threshold: {}", sys_config.raft_snapshot_log_size);

```

This verification step ensures that environment variables propagate correctly through the configuration pipeline defined in [`src/common/mod.rs`](https://github.com/nacos-group/r-nacos/blob/main/src/common/mod.rs).

## Summary

- **RNACOS_RAFT_SNAPSHOT_LOG_SIZE** controls the number of Raft log entries (default **10,000**) that trigger a state machine snapshot in the `nacos-group/r-nacos` cluster.
- The value is parsed from environment variables in [`src/common/mod.rs`](https://github.com/nacos-group/r-nacos/blob/main/src/common/mod.rs) and applied as `LogsSinceLast` policy in [`src/starter.rs`](https://github.com/nacos-group/r-nacos/blob/main/src/starter.rs).
- **Low values** (1,000–5,000) reduce recovery time and log storage but increase CPU and I/O overhead from frequent snapshots.
- **High values** (20,000+) maximize write throughput by minimizing snapshot operations but extend follower synchronization time and increase memory usage.
- Configuration changes require node restart and take effect immediately upon initialization.

## Frequently Asked Questions

### What happens if I set RNACOS_RAFT_SNAPSHOT_LOG_SIZE too low?

Configuring the value below 1,000 entries causes the Raft engine to generate snapshots continuously, consuming excessive CPU cycles and disk I/O for serialization. While log replication remains minimal, the cluster may experience latency spikes during write-heavy operations as nodes pause to create and transfer compacted state files.

### How does this setting affect cluster recovery after a node failure?

The value directly determines how many log entries a recovering node must replay or receive from the leader. With a low threshold, the node installs a recent snapshot and catches up quickly using only a few subsequent entries. A high threshold forces the node to process thousands of historical log entries, extending the recovery window and delaying full cluster participation.

### Can I change RNACOS_RAFT_SNAPSHOT_LOG_SIZE without restarting the cluster?

No, this parameter is immutable during runtime. The `AppSysConfig` struct reads the environment variable once during initialization in [`src/common/mod.rs`](https://github.com/nacos-group/r-nacos/blob/main/src/common/mod.rs), and the Raft configuration applies it permanently at node startup in [`src/starter.rs`](https://github.com/nacos-group/r-nacos/blob/main/src/starter.rs). To modify the snapshot frequency, you must restart the node with the new environment variable value.

### What is the relationship between snapshot size and memory usage?

While the `RNACOS_RAFT_SNAPSHOT_LOG_SIZE` parameter controls the *frequency* of snapshots rather than their binary size, it indirectly affects memory consumption. Infrequent snapshots allow the Raft log to grow larger in memory before compaction, increasing the heap footprint during high-write scenarios. Frequent snapshots keep the log trimmed but require additional memory buffers during the serialization process.