Compactor

Source: server/etcdserver/api/v3compactor/.

Purpose

Without compaction, MVCC history grows forever. The compactor proposes regular Compaction Raft entries that drop revisions older than a threshold, so the keyspace stays a manageable size. Two strategies ship in-tree:

• Periodic — keep the last --auto-compaction-retention of time.
• Revision — keep only the last N revisions.

A third option is "no auto-compaction", in which case the operator runs etcdctl compaction manually.

Directory layout

server/etcdserver/api/v3compactor/
├── compactor.go           # Compactor interface, factory
├── periodic.go, periodic_test.go
├── revision.go, revision_test.go
└── doc.go

Key abstractions

Symbol	File	Description
Compactor interface	server/etcdserver/api/v3compactor/compactor.go	Run, Stop, Pause, Resume
Periodic	server/etcdserver/api/v3compactor/periodic.go	Time-based compactor; sleeps until retention has elapsed, takes a sample of currentRev, proposes Compaction(rev)
Revision	server/etcdserver/api/v3compactor/revision.go	Revision-window compactor; on each tick proposes Compaction(currentRev - retention)

How it works

graph LR
    cfg[--auto-compaction-mode<br>--auto-compaction-retention] --> factory[New]
    factory --> compactor[Compactor]
    compactor -->|sample current revision| mvcc[mvcc.Store]
    compactor -->|propose Compaction| raft[Raft]
    raft -->|commit| apply[apply pipeline]
    apply --> mvccCompact[mvcc.Store.Compact]
    mvccCompact -->|delete revs <= rev| boltdb[(bbolt)]

Revision compaction is "best effort": the compactor pauses when it detects the cluster is overloaded (Pause/Resume paths in compactor.go).

Configuration knobs

Flag	Default	Effect
--auto-compaction-mode	periodic	periodic or revision
--auto-compaction-retention	0 (disabled)	Duration (e.g. 1h) for periodic, integer for revision

server/embed/config.go defines the constants DefaultAutoCompactionMode and DefaultAutoCompactionRetention.

Integration points

• mvcc — Compactor calls mvcc.Store.Rev() to sample, and the apply pipeline calls mvcc.Store.Compact to perform the deletion.
• gRPC — etcdctl compaction issues an out-of-band KV.Compact. Both paths converge in apply.
• Hash storage — after compaction, the next periodic hash check (server/etcdserver/corrupt.go) updates accordingly.

Entry points for modification

• New compaction strategy → add a file matching periodic.go's shape, register in compactor.go::New.
• Tuning periodic resolution → constants in periodic.go (revInterval, checkCompactionInterval).
• Pausing under pressure → compactor.go already has hooks; new triggers (e.g. high backend size) wire in there.