Interface LogMetrics

@ThreadSafe public interface LogMetrics
Metrics about the Raft log state on this node.

Provides visibility into how many entries the log contains, how many have been committed, and how much storage the log consumes. These metrics are essential for monitoring replication health and deciding when maintenance operations like snapshots are needed.

Node-Local Perspective

All values reflect this node's local log state. Followers may temporarily report fewer committed entries than the leader if replication is still in progress. To get a cluster-wide picture, collect metrics from all nodes and compare their committed entry counts and terms.

Log Lifecycle

Entries are first appended to the log, then committed once a majority of nodes have acknowledged them. Over time, snapshots compact the log by removing old entries, which reduces getTotalLogEntries() and getLogSizeInBytes() without affecting the commit index. A growing gap between total and committed entries on a follower indicates it is falling behind the leader.

Since:
2.0
Author:
José Bolina
See Also:

  • Method Details

    • getTotalLogEntries

      long getTotalLogEntries()
      The total number of entries currently in the log.

      This count reflects entries remaining after any snapshot truncation. A steadily growing value without periodic decreases suggests snapshots are not being triggered, which may lead to excessive disk usage. Compare against getCommittedLogEntries() to see how many entries are still pending a commit.

      Returns:
      the number of log entries, or -1 if metrics are disabled.

    • getCommittedLogEntries

      long getCommittedLogEntries()
      The number of entries committed on this node.

      An entry is committed once the leader confirms that a majority of nodes have appended it. On the leader, this value advances as soon as quorum is reached. On followers, it advances when the leader notifies them of the new commit index. A follower whose committed count is significantly lower than the leader's may be experiencing network delays or slow disk writes.

      Returns:
      the number of committed entries, or -1 if metrics are disabled.

    • getUncommittedLogEntries

      long getUncommittedLogEntries()
      The number of entries appended but not yet committed on this node.

      On the leader, uncommitted entries are waiting for majority acknowledgment. On followers, they are entries received from the leader but not yet confirmed as committed. A value that stays high or grows over time indicates the cluster is struggling to reach consensus, possibly due to unreachable members or network issues.

      Returns:
      the number of uncommitted entries, or -1 if metrics are disabled.

    • getLogSizeInBytes

      long getLogSizeInBytes()
      The physical storage size of the log, in bytes.

      Tracks how much disk space the log occupies. Use this metric alongside getSnapshotCount() to verify that snapshot compaction is keeping storage usage under control. A value that grows unbounded suggests the snapshot threshold may need adjustment.

      Returns:
      the log size in bytes, or -1 if metrics are disabled.

    • getCurrentTerm

      long getCurrentTerm()
      The current Raft term as observed by this node.

      The term increments with each new election. All nodes in a healthy cluster should converge to the same term. A node reporting a lower term than others may have been partitioned and is catching up. A rapidly increasing term across the cluster indicates frequent elections.

      Returns:
      the current term, or -1 if metrics are disabled.

    • getCommitIndex

      long getCommitIndex()
      The current commit index on this node.

      The commit index is the highest log index known to be committed. On a healthy cluster, all nodes should eventually converge to the same commit index. Compare this value across nodes to detect replication delays; a follower lagging behind the leader's commit index is still catching up.

      Returns:
      the commit index, or -1 if metrics are disabled.

    • getSnapshotCount

      int getSnapshotCount()
      The number of snapshots this node has performed.

      Snapshots compact the log by persisting the current state machine state and removing old entries. A zero value on a long-running node may explain high storage usage. Monitor this alongside getLogSizeInBytes() to verify that compaction is occurring as expected. A proper tuning is needed for taking snapshots, there is a trade-off between performance vs. disk usage. Taking a snapshot freezes all operations to the state machine until the snapshot finishes.

      Returns:
      the snapshot count, or -1 if metrics are disabled.

    • getSnapshotsReceived

      int getSnapshotsReceived()
      The number of snapshot-install messages received from the leader.

      When a follower falls too far behind, the leader sends its snapshot instead of individual log entries. A high value indicates this node has frequently been unable to keep up with normal replication, which is more expensive than regular log replication for both the leader and the follower.

      Returns:
      the number of snapshots received, or -1 if metrics are disabled.

    • getFailedSnapshotCreations

      int getFailedSnapshotCreations()
      The number of times snapshot creation failed on this node.

      A snapshot creation failure means the node attempted to take a snapshot but the operation did not complete successfully. The snapshot is retried automatically when the log size threshold is reached again. Persistent failures may indicate a problem in the state machine's snapshot implementation.

      Returns:
      the number of failed snapshot creations, or -1 if metrics are disabled.

    • getFailedSnapshotInstallations

      int getFailedSnapshotInstallations()
      The number of times snapshot installation failed on this node.

      A snapshot installation failure means the node received a snapshot from the leader but could not apply it. The leader will retry the transfer on the next replication cycle. Repeated failures suggest a mismatch between the leader's snapshot format and the follower's state machine, or persistent I/O errors on the follower.

      Returns:
      the number of failed snapshot installations, or -1 if metrics are disabled.

    • getFailedSnapshotTransfers

      int getFailedSnapshotTransfers()
      The number of chunked snapshot transfers that started but failed before completion.

      A chunked transfer fails when a view change interrupts the transfer (leader steps down, follower leaves) or when the leader takes a newer snapshot while a transfer is in progress. Occasional failures during membership changes are expected. A high value on a stable cluster may indicate network issues between the leader and this follower. Returns zero when synchronous snapshots are in use.

      Returns:
      the number of failed chunked transfers, or -1 if metrics are disabled.

    • getLastSnapshotTransferDuration

      Duration getLastSnapshotTransferDuration()
      The duration of the last completed chunked snapshot transfer on this node.

      Measures wall-clock time from the first chunk request to the final chunk received. Use this metric to evaluate whether the current chunk size and batch size configuration provides adequate transfer throughput. A transfer that takes significantly longer than expected may benefit from larger chunks or batches. Returns Duration.ZERO when no chunked transfer has completed or when synchronous snapshots are in use.

      Returns:
      the duration of the last chunked transfer, or Duration.ZERO if metrics are disabled or no transfer has completed.