Interface LatencyMetrics

public interface LatencyMetrics
Latency distribution for a specific operation category.

Provides statistical summaries (average, percentiles, and maximum) over all recorded latency samples for a given operation type. Each method in PerformanceMetrics returns a LatencyMetrics instance scoped to that category (e.g., total request latency, consensus latency, election latency, or redirect latency).

Values and Units

All latency values are reported in nanoseconds. Percentile values (p95, p99) represent the latency at or below which that percentage of all recorded operations completed. For example, a p99 of 5,000,000 ns means 99% of operations completed within 5 ms.

Interpreting the Distribution

The average alone can be misleading; a few slow operations can skew it significantly. Prefer percentile-based metrics for SLA monitoring: p95 captures the typical worst case, while p99 reveals tail latency outliers. A large gap between p95 and p99 suggests occasional spikes worth investigating. Use getPercentile(double) for custom thresholds beyond the predefined ones.

Since:
2.0
Author:
José Bolina
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    static LatencyMetrics
    disabled()
     
    double
    getAvgLatency()
    The arithmetic mean of all recorded latency samples, in nanoseconds.
    double
    getMaxLatency()
    The highest latency recorded across all samples, in nanoseconds.
    double
    getP95Latency()
    The 95th percentile latency, in nanoseconds.
    double
    getP99Latency()
    The 99th percentile latency, in nanoseconds.
    double
    getPercentile(double p)
    The latency at a custom percentile, in nanoseconds.
    long
    getTotalMeasurements()
    The total number of latency samples recorded.

  • Method Details

    • disabled

      static LatencyMetrics disabled()

    • getAvgLatency

      double getAvgLatency()
      The arithmetic mean of all recorded latency samples, in nanoseconds.

      Useful as a general health indicator, but can be skewed by outliers. Compare against percentile values for a more accurate picture of typical performance.

      Returns:
      the average latency in nanoseconds, or -1 if metrics are disabled.

    • getP99Latency

      double getP99Latency()
      The 99th percentile latency, in nanoseconds.

      99% of all recorded operations completed at or below this latency. This metric captures tail latency and is the most sensitive to performance regressions or transient issues like garbage collection pauses or network retransmissions.

      Returns:
      the p99 latency in nanoseconds, or -1 if metrics are disabled.

    • getP95Latency

      double getP95Latency()
      The 95th percentile latency, in nanoseconds.

      95% of all recorded operations completed at or below this latency. This is a common choice for SLA targets as it filters out rare outliers while still reflecting the experience of most requests.

      Returns:
      the p95 latency in nanoseconds, or -1 if metrics are disabled.

    • getMaxLatency

      double getMaxLatency()
      The highest latency recorded across all samples, in nanoseconds.

      Represents the absolute worst-case latency observed. Useful for capacity planning and for identifying the upper bound of operation duration under the current workload.

      Returns:
      the maximum latency in nanoseconds, or -1 if metrics are disabled.

    • getPercentile

      double getPercentile(double p)
      The latency at a custom percentile, in nanoseconds.

      Use this when the predefined p95 and p99 do not match your SLA thresholds. For example, getPercentile(99.9) returns the latency below which 99.9% of operations completed.

      Parameters:
      p - the percentile to query, between 0 and 100.
      Returns:
      the latency at the given percentile in nanoseconds, or -1 if metrics are disabled.

    • getTotalMeasurements

      long getTotalMeasurements()
      The total number of latency samples recorded.

      Use this to assess whether the statistical summaries are meaningful; a small sample count means percentile values may not yet be representative. This value also serves as an operation counter for the category this instance tracks.

      Returns:
      the number of recorded measurements, or -1 if metrics are disabled.