Interface JGroupsRaftMetrics

All Known Implementing Classes:
JGroupsRaftMetrics.DisabledJGroupsRaftMetrics
public interface JGroupsRaftMetrics
Monitoring interface for a Raft node.

Provides access to cluster membership, leader election information, log replication status, and operation latency measurements. Each metric category is exposed through a dedicated sub-interface: ElectionMetrics, LogMetrics, and PerformanceMetrics.

Node-Local Metrics

All metrics are local to the node they are retrieved from. Different nodes may report different values for the same metric depending on their role and when they received cluster-wide messages. For example, a follower's election timestamp reflects when it learned about the new leader, not when the election completed on the coordinator. To get a complete picture of the cluster, collect metrics from all nodes.

Enabling Metrics

Metrics collection is disabled by default. Enable it by setting the jgroups.raft.metrics.enabled runtime property: 

JGroupsRaft.builder(stateMachine, Api.class)
    .withRuntimeProperties(RuntimeProperties.from(Map.of("jgroups.raft.metrics.enabled", "true")))
    .build();

When disabled, all methods return safe default values: -1 for numeric metrics, empty strings for identifiers, and Instant.EPOCH or Duration.ZERO for time values. A disabled instance can be obtained via disabled().

Thread Safety

Implementations are thread-safe. Metrics can be read concurrently from any thread without external synchronization.

Since:
2.0
Author:
José Bolina
See Also:

  • Field Details

  • Method Details

    • getTotalNodes

      int getTotalNodes()
      The total number of nodes configured in the cluster, excluding learners.

      This value reflects the static Raft membership. The member in the list include only the voting members of the algorithm. This list reflects the currently configured members, and as such, it only changes through membership operation submitted through JGroupsRaftAdministration. The getActiveNodes() returns a live view of the cluster members.

      Returns:
      the configured cluster size, or -1 if metrics are disabled.

    • getActiveNodes

      int getActiveNodes()
      The number of nodes currently reachable in the cluster view.

      Compare this value against getTotalNodes() to detect membership degradation. When active nodes drop below the majority threshold (totalNodes / 2 + 1), the cluster becomes unavailable until enough members rejoin. Monitoring this metric is essential for alerting on availability risks before the cluster loses quorum.

      Returns:
      the number of active nodes (including learners), or -1 if metrics are disabled.

    • leaderMetrics

      ElectionMetrics leaderMetrics()
      Metrics about the current leader and election timing.

      Use these metrics to identify the current leader, determine when the last election occurred, and detect leadership instability. Frequent leader changes may indicate network issues or misconfigured failure detectors, and each election causes a brief period where operations are unavailable.

      Returns:
      the leader election metrics; never null.
      See Also:

    • replicationMetrics

      LogMetrics replicationMetrics()
      Metrics about the Raft log, including entry counts and replication progress.

      Use these metrics to monitor replication health. A growing gap between total and replicated entries indicates that followers are falling behind.

      Returns:
      the log replication metrics; never null.
      See Also:

    • performanceMetrics

      PerformanceMetrics performanceMetrics()
      Latency measurements for the main operations: request processing, consensus, leader election, and request forwarding.

      Use these metrics to identify performance bottlenecks and validate SLAs. Comparing the different latency categories helps pinpoint whether delays originate from consensus, request queuing, or network forwarding. See PerformanceMetrics for details on each category.

      Returns:
      the performance metrics; never null.
      See Also:

    • reset

      void reset()
      Resets all collected metrics to their initial state.

      Clears latency histograms, counters, and any accumulated statistics across all metric categories (election, log, performance). Membership metrics (getTotalNodes(), getActiveNodes()) are not affected since they reflect live cluster state rather than accumulated measurements.

      This is useful for establishing a clean baseline after configuration changes, deployments, or when investigating a specific time window. Has no effect when metrics are disabled.

    • disabled

      static JGroupsRaftMetrics disabled()