# Dragonboat SnapshotEntries vs CompactionOverhead: Configuration and Behavior Differences

> Understand SnapshotEntries and CompactionOverhead differences in Dragonboat. Learn how to configure snapshot frequency and optimize log compaction for lagging followers.

- Repository: [lni/dragonboat](https://github.com/lni/dragonboat)
- Tags: deep-dive
- Published: 2026-03-06

---

**SnapshotEntries determines the frequency of automatic snapshots by counting applied Raft entries, while CompactionOverhead specifies how many recent log entries to preserve after compaction to support lagging followers.**

In the `lni/dragonboat` Raft library, managing the trade-off between snapshot frequency and log retention is essential for cluster performance. The **SnapshotEntries** and **CompactionOverhead** configuration fields in [`config/config.go`](https://github.com/lni/dragonboat/blob/main/config/config.go) control distinct phases of log management—triggering snapshots versus preserving log history. Understanding how these settings interact helps prevent excessive snapshotting while ensuring nodes can recover without full state transfers.

## What SnapshotEntries Configures

**SnapshotEntries** controls when automatic snapshots are triggered. Defined in [`config/config.go`](https://github.com/lni/dragonboat/blob/main/config/config.go) (lines 99-101), this field specifies the number of Raft log entries that must be applied to the state machine before Dragonboat automatically initiates a snapshot.

When `Config.SnapshotEntries` is set to a value greater than `0`, the Raft node periodically checks the applied entry count. Once the threshold is reached, the system triggers a snapshot automatically. Setting this value to `0` (the default) disables automatic snapshotting, requiring manual intervention via `NodeHost.RequestSnapshot` or `NodeHost.SyncRequestSnapshot`.

Typical use cases include reducing snapshot frequency for workloads with high volumes of small proposals, or ensuring regular snapshots occur in write-heavy environments to prevent unbounded log growth.

## What CompactionOverhead Configures

**CompactionOverhead** determines how much of the Raft log is preserved after a snapshot triggers log compaction. Defined in [`config/config.go`](https://github.com/lni/dragonboat/blob/main/config/config.go) (lines 120-124), this setting specifies the number of most recent log entries to retain after compaction, ensuring lagging followers can catch up using log entries rather than requiring a full snapshot transfer.

When compaction runs—either automatically following a snapshot or manually via `RequestSnapshot`—Dragonboat calculates the cutoff point as `lastSnapshotIndex - CompactionOverhead`. Entries older than this index are physically removed, while the specified overhead count is preserved.

The default value of `0` removes all entries up to the snapshot index, which minimizes disk usage but forces lagging nodes to receive full snapshots. Setting a non-zero overhead creates a "log tail" that facilitates faster recovery for followers that are slightly behind, and supports debugging or replay of recent history.

## Key Differences and Interaction

While both settings relate to snapshot management, they control distinct phases with different override capabilities.

**SnapshotEntries** governs the trigger condition for automatic snapshots. It is a static configuration that cannot be overridden per request. Once set, the node monitors applied entry counts and initiates snapshots automatically when the threshold is reached.

**CompactionOverhead** governs the retention policy applied after snapshot completion. While it has a default node-wide value in `Config`, it can be overridden for individual snapshot requests using `SnapshotOption.OverrideCompactionOverhead` and `SnapshotOption.CompactionOverhead` (defined in [`nodehost.go`](https://github.com/lni/dragonboat/blob/main/nodehost.go), lines 98-104).

The interaction between these settings follows a sequential process: first, `SnapshotEntries` triggers the snapshot creation; second, after the snapshot persists, the compaction process applies the effective overhead (either from config or the override) to determine which log entries to preserve.

## Configuration Examples

### Automatic Snapshots with Log Retention

Configure automatic snapshots every 10,000 entries while preserving the last 500 entries for follower catch-up:

```go
cfg := config.Config{
    // Trigger snapshot after 10,000 applied entries
    SnapshotEntries: 10000,
    // Preserve 500 recent entries after compaction
    CompactionOverhead: 500,
}

```

With this configuration, Dragonboat automatically snapshots after approximately 10,000 proposals and then compacts the log, leaving the last 500 entries on disk.

### Overriding Compaction Overhead for a Single Snapshot

Temporarily increase log retention for a specific manual snapshot without changing the node configuration:

```go
opt := nodehost.SnapshotOption{
    OverrideCompactionOverhead: true,
    CompactionOverhead:         1000,
}
err := nh.RequestSnapshot(shardID, replicaID, opt)

```

This request preserves the latest 1,000 entries regardless of the `Config.CompactionOverhead` setting, which remains unchanged for subsequent automatic snapshots.

### Disabling Automatic Snapshots

For complete manual control over when snapshots occur:

```go
cfg := config.Config{
    SnapshotEntries: 0, // Disable automatic snapshotting
}

```

With this configuration, the log grows until you explicitly call `RequestSnapshot` or `SyncRequestSnapshot`.

## Summary

- **SnapshotEntries** controls the frequency of automatic snapshots by counting applied Raft log entries. Set it to `0` to disable automatic snapshots and trigger them manually via `RequestSnapshot`.

- **CompactionOverhead** determines how many recent log entries are preserved after snapshot compaction. It ensures lagging followers can catch up without full state transfers and can be overridden per-request using `SnapshotOption`.

- These settings operate sequentially: `SnapshotEntries` triggers snapshot creation, then compaction applies the effective overhead (from `Config` or override) to retain a tail of recent entries.

- **Source locations**: `Config.SnapshotEntries` and `Config.CompactionOverhead` are defined in [`config/config.go`](https://github.com/lni/dragonboat/blob/main/config/config.go), while per-request override capabilities reside in `SnapshotOption` within [`nodehost.go`](https://github.com/lni/dragonboat/blob/main/nodehost.go).

## Frequently Asked Questions

### What happens if I set SnapshotEntries to 0?

When `SnapshotEntries` is set to `0` (the default), automatic snapshotting is completely disabled. The Raft log will grow indefinitely until you manually trigger a snapshot using `NodeHost.RequestSnapshot` or `NodeHost.SyncRequestSnapshot`. This configuration is useful when you need precise control over when snapshots occur, such as during maintenance windows or after specific business logic milestones.

### Can I change CompactionOverhead without restarting the node?

No, the node-wide `Config.CompactionOverhead` cannot be changed dynamically without restarting the node. However, you can temporarily override the compaction behavior for a single snapshot request by setting `SnapshotOption.OverrideCompactionOverhead` to `true` and specifying a custom `SnapshotOption.CompactionOverhead` value. This override affects only that specific snapshot operation and does not modify the permanent node configuration.

### How do these settings affect cluster recovery time?

**SnapshotEntries** indirectly affects recovery time by controlling snapshot freshness. Lower values create snapshots more frequently, reducing the number of log entries a crashed node must replay, but increasing I/O overhead. **CompactionOverhead** directly impacts recovery by determining whether lagging followers can catch up via incremental log entries or must receive a full snapshot. A higher overhead preserves more recent entries, enabling faster catch-up for slightly behind nodes, but increases disk usage for the log.

### Should SnapshotEntries and CompactionOverhead values be related?

While the settings operate independently, practical deployments often consider their interaction. If `SnapshotEntries` is set to 10,000 and `CompactionOverhead` is set to 500, the system snapshots every 10,000 entries but keeps the last 500 of those in the log. Ensure `CompactionOverhead` is significantly smaller than `SnapshotEntries` to avoid negating the disk space benefits of snapshotting. There is no enforced relationship in the code, but maintaining a ratio where overhead is 5-10% of the snapshot frequency is a common operational guideline.