Class RaftTracer

java.lang.Object
com.loomcache.server.tracing.RaftTracer
public class RaftTracer extends Object
Distributed tracing instrumentation for Raft consensus operations.

Traced Operations

- AppendEntries: leader replicating log entries to followers - RequestVote: node requesting votes during election - Leader Election: timing and outcome of elections - Log Replication: progress of log replication to followers - Snapshot Installation: transfer of snapshots to lagging followers - Log Compaction: state machine snapshot and log truncation

Attributes

- raft.term: current election term - raft.index: log entry index - raft.leader: current leader ID - raft.commit_index: highest committed log index - raft.last_applied: last applied log index - raft.peers: number of peers in cluster - raft.follower: target follower ID (for replication spans) - raft.match_index: last log index replicated on follower - raft.next_index: next log index to send to follower
Since:
1.0

  • Constructor Details

    • RaftTracer

      public RaftTracer(String nodeId, RaftNodeApi raftNode)
      Create a new RaftTracer for the given Raft node.
      Parameters:
      nodeId - the node ID (must not be null)
      raftNode - the Raft node to instrument (must not be null)
      Throws:
      NullPointerException - if nodeId or raftNode is null

  • Method Details

    • startElectionAttempt

      public TracingContext.Span startElectionAttempt()
      Start tracing an election timeout event. Indicates that this node did not receive a heartbeat and is starting an election.
      Returns:
      a span for the election attempt

    • recordElectionWon

      public void recordElectionWon(TracingContext.Span span, int votesReceived, int totalPeers)
      Record that the election was won.
      Parameters:
      span - the election span (must not be null)
      votesReceived - number of votes received
      totalPeers - total number of peers
      Throws:
      NullPointerException - if span is null

    • recordElectionLost

      public void recordElectionLost(TracingContext.Span span, String newLeader)
      Record that the election was lost (another node became leader).
      Parameters:
      span - the election span (must not be null)
      newLeader - the ID of the new leader (must not be null)
      Throws:
      NullPointerException - if span or newLeader is null

    • recordLeaderChange

      public TracingContext.Span recordLeaderChange(@Nullable String oldLeader, String newLeader)
      Record a leader change.
      Parameters:
      oldLeader - the previous leader ID (may be null)
      newLeader - the new leader ID (must not be null)
      Returns:
      a span for the leader change event
      Throws:
      NullPointerException - if newLeader is null

    • startReplication

      public TracingContext.Span startReplication(String followerId)
      Start tracing a replication attempt to a specific follower.
      Parameters:
      followerId - the target follower ID (must not be null)
      Returns:
      a span for the replication attempt
      Throws:
      NullPointerException - if followerId is null

    • recordReplicationSuccess

      public void recordReplicationSuccess(TracingContext.Span span, long matchIndex, long nextIndex)
      Record successful replication to a follower.
      Parameters:
      span - the replication span (must not be null)
      matchIndex - the log index now replicated on the follower
      nextIndex - the next index to replicate
      Throws:
      NullPointerException - if span is null

    • recordReplicationFailure

      public void recordReplicationFailure(TracingContext.Span span, String reason, int attempt)
      Record failed replication to a follower.
      Parameters:
      span - the replication span (must not be null)
      reason - the reason for failure (e.g., "timeout", "network_error") (must not be null)
      attempt - the attempt number
      Throws:
      NullPointerException - if span or reason is null

    • startAppendEntriesRpc

      public TracingContext.Span startAppendEntriesRpc(boolean isRequest)
      Start tracing an AppendEntries RPC (either outgoing from leader or incoming to follower).
      Parameters:
      isRequest - true if this is an outgoing request, false if receiving
      Returns:
      a span for the RPC

    • recordAppendEntriesDetails

      public void recordAppendEntriesDetails(TracingContext.Span span, long prevLogIndex, long prevLogTerm, int entriesCount, long leaderCommit)
      Record AppendEntries RPC details.
      Parameters:
      span - the RPC span (must not be null)
      prevLogIndex - the previous log index used for matching
      prevLogTerm - the previous log term
      entriesCount - the number of entries being replicated
      leaderCommit - the leader's commit index
      Throws:
      NullPointerException - if span is null

    • startRequestVoteRpc

      public TracingContext.Span startRequestVoteRpc(long candidateTerm, String candidateId, long lastLogIndex, long lastLogTerm)
      Start tracing a RequestVote RPC.
      Parameters:
      candidateTerm - the candidate's term
      candidateId - the candidate's ID
      lastLogIndex - the candidate's last log index
      lastLogTerm - the candidate's last log term
      Returns:
      a span for the RPC

    • recordVoteGranted

      public void recordVoteGranted(TracingContext.Span span)
      Record vote granted.
      Parameters:
      span - the RequestVote span

    • recordVoteDenied

      public void recordVoteDenied(TracingContext.Span span, String reason)
      Record vote denied.
      Parameters:
      span - the RequestVote span
      reason - the reason for denial

    • startSnapshotInstall

      public TracingContext.Span startSnapshotInstall(String followerId)
      Start tracing a snapshot installation RPC.
      Parameters:
      followerId - the target follower ID
      Returns:
      a span for the snapshot installation

    • recordSnapshotChunk

      public void recordSnapshotChunk(TracingContext.Span span, int chunkIndex, int totalChunks, boolean done)
      Record snapshot installation progress.
      Parameters:
      span - the snapshot installation span
      chunkIndex - the chunk index being transferred
      totalChunks - the total number of chunks
      done - whether the installation is complete

    • startSnapshotSave

      public TracingContext.Span startSnapshotSave()
      Start tracing a snapshot save operation.
      Returns:
      a span for the snapshot save

    • recordSnapshotSaved

      public void recordSnapshotSaved(TracingContext.Span span, long snapshotSize, long durationMs)
      Record snapshot save completion.
      Parameters:
      span - the snapshot save span
      snapshotSize - the size of the snapshot in bytes
      durationMs - the time taken to save

    • startLogCompaction

      public TracingContext.Span startLogCompaction()
      Start tracing a log compaction operation.
      Returns:
      a span for the compaction

    • recordLogCompacted

      public void recordLogCompacted(TracingContext.Span span, long logSizeAfter, long entriesRemoved)
      Record log compaction completion.
      Parameters:
      span - the compaction span
      logSizeAfter - the log size after compaction
      entriesRemoved - the number of entries removed

    • recordCommitIndexAdvanced

      public TracingContext.Span recordCommitIndexAdvanced(long oldCommitIndex, long newCommitIndex)
      Record commit index advancement.
      Parameters:
      oldCommitIndex - the previous commit index
      newCommitIndex - the new commit index
      Returns:
      a span for the commit advancement

    • getActiveReplicationSpans

      public Map<String, TracingContext.Span> getActiveReplicationSpans()
      Get all active replication spans.
      Returns:
      an unmodifiable map of follower IDs to active spans

    • closeAllReplicationSpans

      public void closeAllReplicationSpans()
      Close all active replication spans. Called during shutdown or when transitioning to follower state.