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.

See also

CoroutineScope.raftNode

Inheritors

ProposeAccepted

ProposeCommitted

ElectionStarted

ElectionTimedOut

Types

ElectionStarted

data class ElectionStarted(val term: Long) : RaftMetric

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

ElectionTimedOut

data class ElectionTimedOut(val term: Long) : RaftMetric

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

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.

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.