kuilt-raft/us.tractat.kuilt.raft/RaftMetric

RaftMetric

sealed interface RaftMetric

A structured metric event emitted by a RaftNode at key state-machine transitions.

Delivered via the onMetric callback on CoroutineScope.raftNode. The hook is invoked on the engine's coroutine — the consumer must not block inside the callback.

Use-cases:

Route to a metrics back-end (Prometheus, StatsD, OpenTelemetry) without parsing logs.
Assert sequencing in tests (e.g. verify Accepted → Committed → Applied for a propose).
Surface where wall-time went in a slow propose: election vs replication vs commit-apply.

Threading contract. The callback is always invoked on the Raft engine's internal coroutine. It must return promptly — blocking inside the hook will stall the engine and delay replication for the entire cluster.

Inheritors

ElectionSuppressedTermCeiling

SnapshotRejectedSizeCeiling

WedgeSuspected

Types

ElectionStarted

data class ElectionStarted(val term: Long) : RaftMetric

This node started an election for term (election timeout fired).

ElectionSuppressedTermCeiling

data class ElectionSuppressedTermCeiling(val term: Long, val ceiling: Long) : RaftMetric

No election was started, because this node's term has reached the engine's term plausibility ceiling and the term + 1 an election must propose would sit above it (#1886).

ElectionTimedOut

data class ElectionTimedOut(val term: Long) : RaftMetric

An election timed out without this node winning leadership for term.

ElectionWon

data class ElectionWon(val term: Long, val elapsed: Duration) : RaftMetric

This node won the election and became leader for term.

ProposeAccepted

data class ProposeAccepted(val logIndex: Long, val term: Long) : RaftMetric

A RaftNode.propose call was accepted by the leader and appended to its log at logIndex.

ProposeApplied

data class ProposeApplied(val logIndex: Long, val elapsed: Duration) : RaftMetric

The committed entry at logIndex was emitted to RaftNode.committed (applied).

ProposeCommitted

data class ProposeCommitted(val logIndex: Long, val elapsed: Duration) : RaftMetric

The proposed entry at logIndex has been replicated to a quorum and committed.

SnapshotRejectedSizeCeiling

data class SnapshotRejectedSizeCeiling(val attemptedTotal: Long, val ceiling: Int) : RaftMetric

An inbound snapshot chunk would have pushed this follower's reassembly to attemptedTotal bytes, above the configured RaftConfig.snapshotTotalCeiling of ceiling, so the whole in-flight reassembly was discarded and offset 0 re-advertised to the sender (#1881, #1926).

WedgeSuspected

data class WedgeSuspected(val sender: NodeId, val senderTerm: Long, val ourTerm: Long, val ourVoters: Set<NodeId>, val gate: RaftMetric.WedgeSuspected.Gate) : RaftMetric

This node has been refusing leader→peer frames for a sustained run while its own commit index stood still — the local signature of a node that has argued itself out of the conversation (#1898, and the honest-jump case of #1897).

RaftMetric

See also

Inheritors

Types