# When to Enable Quiesce Mode in Dragonboat: A Complete Guide

> Enable Dragonboat Quiesce mode for bursty or idle Raft shards to cut network traffic and CPU use after inactivity while ensuring safety. Learn when and why.

- Repository: [lni/dragonboat](https://github.com/lni/dragonboat)
- Tags: how-to-guide
- Published: 2026-03-06

---

**Enable Quiesce mode in Dragonboat when running Raft shards with bursty or idle workloads to automatically suppress heartbeat traffic after 10×ElectionRTT ticks of inactivity, reducing network bandwidth and CPU usage while maintaining safety.**

Quiesce mode is an **experimental optimization** available in the Dragonboat Raft library that addresses the inefficiency of constant heartbeat traffic in idle clusters. By setting the `Quiesce` flag in the node configuration, you allow Raft shards to enter a dormant state during periods of inactivity, automatically resuming full heartbeat operations when new requests arrive.

## What is Quiesce Mode in Dragonboat?

Quiesce mode is a state machine optimization implemented in [`quiesce.go`](https://github.com/lni/dragonboat/blob/main/quiesce.go) that allows a Raft node to **temporarily cease sending heartbeat messages** when it detects prolonged inactivity. According to the source code in the `lni/dragonboat` repository, this mode is controlled by the `Config.Quiesce` boolean flag defined in [`config/config.go`](https://github.com/lni/dragonboat/blob/main/config/config.go) (lines 90-96).

When active, the node monitors Raft-level activity—including proposals, configuration changes, and read-index requests. If no activity occurs for a duration exceeding **10×ElectionRTT** ticks (calculated in [`quiesce.go`](https://github.com/lni/dragonboat/blob/main/quiesce.go) lines 81-83), the node transitions into quiesce state.

## When Should You Enable Quiesce Mode?

You should consider enabling Quiesce mode in the following deployment scenarios:

- **Bursty Workloads**: Applications with sporadic write activity where shards remain idle for extended periods between bursts of proposals.
- **Read-Heavy Clusters**: Deployments with long-lived read-only nodes that must stay synchronized but rarely participate in write operations.
- **Resource-Constrained Environments**: Edge deployments or IoT scenarios where network bandwidth and CPU cycles are limited and constant heartbeat traffic represents significant overhead.
- **Multi-Tenant Systems**: Shared infrastructure where idle tenant shards should consume minimal resources.

**Important**: As an experimental feature, Quiesce mode should be thoroughly tested in staging environments before production deployment.

## How Quiesce Mode Works (Technical Deep Dive)

### Entry Conditions and Threshold Calculation

The decision to enter quiesce state occurs in `quiesceState.tick()` (defined in [`quiesce.go`](https://github.com/lni/dragonboat/blob/main/quiesce.go) lines 49-53). The system tracks idle time using the `idleSince` timestamp and compares it against a threshold calculated as:

```go
// From quiesce.go lines 81-83
threshold := qs.electionRTT * 10

```

When `currentTick - idleSince > threshold`, the node invokes `enterQuiesce()`.

### The Quiesce State Machine

The state transition logic resides in [`quiesce.go`](https://github.com/lni/dragonboat/blob/main/quiesce.go) (lines 10-15). When `enterQuiesce()` executes:

1. It sets `quiescedSince` to the current tick
2. Raises the `newQuiesceStateFlag` to signal state change
3. Logs the transition via the node's logger

The node then broadcasts its new state to peers through `node.sendEnterQuiesceMessages()` (implemented in [`node.go`](https://github.com/lni/dragonboat/blob/main/node.go) lines 93-100), sending a `pb.Quiesce` protocol buffer message defined in [`raftpb/types.go`](https://github.com/lni/dragonboat/blob/main/raftpb/types.go).

### Heartbeat Suppression Mechanism

Once in quiesce state, heartbeat suppression occurs in the message handling loop. In [`node.go`](https://github.com/lni/dragonboat/blob/main/node.go) (lines 1385-1388), incoming `pb.Quiesce` messages trigger `qs.tryEnterQuiesce()`, which prevents the node from sending further heartbeats while `qs.quiesced()` returns true.

This effectively creates a **quiet period** where the shard generates no heartbeat traffic, significantly reducing network utilization for idle replicas.

### Exit Conditions and Wake-Up Behavior

The system exits quiesce state immediately upon detecting Raft activity. The `qs.record(msg.Type)` function (in [`quiesce.go`](https://github.com/lni/dragonboat/blob/main/quiesce.go) lines 61-78) monitors incoming message types. When it receives any non-heartbeat message—such as a proposal, read-index request, or configuration change—it:

1. Resets `idleSince` to the current tick
2. If the node was quiesced, invokes `exitQuiesce()`
3. Resumes normal heartbeat transmission

To prevent rapid oscillation between states, the `justExitedQuiesce()` guard (lines 92-97) implements a grace period using the same 10×ElectionRTT threshold before the node can re-enter quiesce state.

## Configuring Quiesce Mode in Your Application

To enable Quiesce mode, set the `Quiesce` field to `true` in your node configuration:

```go
cfg := dragonboat.Config{
    // ... other required fields ...
    Quiesce:      true,  // Enable experimental quiesce optimization
    HeartbeatRTT: 1,
    ElectionRTT:  10,    // Quiesce threshold = 10 * 10 = 100 ticks
}

nhc := dragonboat.NodeHostConfig{/* ... */}
nodeHost, _ := dragonboat.NewNodeHost(nhc)

// Start your state machine with quiesce enabled
nodeHost.StartReplica(cfg, sm)

```

The `Quiesce` field is documented in [`config/config.go`](https://github.com/lni/dragonboat/blob/main/config/config.go) (lines 90-96). Note that this is an experimental feature and should be validated in your specific workload before production deployment.

## Monitoring Quiesce Transitions

Dragonboat logs state transitions to help operators verify that Quiesce mode is functioning correctly. When a node enters or exits quiesce state, it generates log entries via the `enterQuiesce()` and `record()` functions in [`quiesce.go`](https://github.com/lni/dragonboat/blob/main/quiesce.go):

```go
// Example log output
2023-03-12T12:00:01.234Z INFO  shard[1] replica[2] entered quiesce
2023-03-12T12:05:13.567Z INFO  shard[1] replica[2] exited from quiesce, msg type Proposal, current tick 12345

```

These log lines originate from [`quiesce.go`](https://github.com/lni/dragonboat/blob/main/quiesce.go) (lines 14-15 and 76-78) and provide visibility into:
- When a shard becomes idle and enters quiesce
- What message type triggered the exit (proposal, read-index, etc.)
- The current tick count for debugging timing issues

## Summary

- **Quiesce mode** is an experimental optimization in Dragonboat (enabled via `Config.Quiesce` in [`config/config.go`](https://github.com/lni/dragonboat/blob/main/config/config.go)) that suppresses heartbeat traffic for idle Raft shards.
- **Enable it** when running bursty workloads, read-heavy clusters, or resource-constrained environments where constant heartbeats waste bandwidth and CPU.
- **Entry threshold** is automatically calculated as **10×ElectionRTT** ticks of inactivity, monitored by `quiesceState.tick()` in [`quiesce.go`](https://github.com/lni/dragonboat/blob/main/quiesce.go).
- **Effect** is immediate suppression of heartbeat messages via `node.sendEnterQuiesceMessages()` and `node.handleMessage`, reducing network utilization until real activity resumes.
- **Safety** is maintained because any non-heartbeat Raft message (proposal, read-index, config change) immediately triggers `exitQuiesce()` and restores normal operation.

## Frequently Asked Questions

### Is Quiesce mode safe for production use?

Quiesce mode is currently marked as **experimental** in the Dragonboat source code. While the implementation includes safety mechanisms such as immediate exit on any Raft activity and grace periods to prevent oscillation, you should thoroughly test it in staging environments that mirror your production workload patterns before enabling it in production systems.

### How does Quiesce mode differ from standard Raft heartbeats?

Standard Raft requires nodes to send periodic heartbeat messages to maintain leadership and detect failures, regardless of activity levels. **Quiesce mode** allows nodes to **automatically suppress these heartbeats** after detecting 10×ElectionRTT ticks of inactivity, as implemented in [`quiesce.go`](https://github.com/lni/dragonboat/blob/main/quiesce.go). The shard remains functional and will instantly resume heartbeats when new requests arrive, unlike standard Raft which never suppresses heartbeat traffic.

### Can I enable or disable Quiesce mode at runtime?

Dragonboat does not expose a public API for dynamically toggling Quiesce mode after node initialization. The feature is controlled by the `Quiesce` boolean field in the `Config` struct ([`config/config.go`](https://github.com/lni/dragonboat/blob/main/config/config.go)), which is read during node startup. Advanced users could potentially modify the internal `qs.enabled` field in the `quiesceState` struct at runtime, but this is not supported and requires source code modification.

### What happens if a node crashes while in Quiesce mode?

If a node crashes while quiesced, the remaining cluster members will detect the failure through their standard failure detection mechanisms. Since quiesced nodes still respond to non-heartbeat messages (and exit quiesce immediately upon receiving them), a crashed node simply appears as unresponsive. The cluster will proceed with leader election according to standard Raft protocols. The quiesce state is not persisted to disk; when the node restarts, it begins in active mode and can re-enter quiesce only after the idle threshold is met again.