Package org.voltdb.client

Class ClientStats

java.lang.Object
org.voltdb.client.ClientStats
public class ClientStats extends Object

Essentially a set of counters for a specific context with helper methods. The context has a time window and can apply to all connections and procedures, or a single of connections and/or procedure.

The helper methods such as getTxnThroughput() or kPercentileLatency(double) perform common operations on the counters.

This object is immutable outside of the package scope and does not directly reference any internal data structures.

See also ClientStatsContext.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    HUNDRED_MS_BUCKET_COUNT
    The number of buckets tracking latency with 100ms granularity.
    static final int
    ONE_MS_BUCKET_COUNT
    The number of buckets tracking latency with 1ms granularity.
    static final int
    TEN_MS_BUCKET_COUNT
    The number of buckets tracking latency with 10ms granularity.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected Object
    clone()
     
    static org.HdrHistogram_voltpatches.Histogram
    constructHistogram()
     
    double
    getAverageInternalLatency()
    Get the server-side average latency in milliseconds for the time period covered by this stats instance.
    double
    getAverageLatency()
    Get the average latency in milliseconds for the time period covered by this stats instance.
    long
    getBytesRead()
    Return the number of bytes read from the network during the time period covered by this stats instance.
    long
    getBytesWritten()
    Return the number of bytes written over the network during the time period covered by this stats instance.
    long
    getConnectionId()
    Get the id of the individual socket connection this statistics instance applies to.
    long
    getDuration()
    Get the number of milliseconds this stats instance covers.
    long
    getEndTimestamp()
    Get the Date-compatible timestamp that describes the end of the range of time this stats instance covers.
    String
    getHostname()
    The hostname or IP (as string) of the connection this stats instance covers.
    long
    getInvocationAborts()
    Get the number of transactions aborted by the VoltDB server(s) during the time period covered by this stats instance.
    long
    getInvocationErrors()
    Get the number of transactions failed by the VoltDB server(s) during the time period covered by this stats instance.
    long
    getInvocationsCompleted()
    Get the number of transactions acknowledged by the VoltDB server(s) during the time period covered by this stats instance.
    long
    getInvocationTimeouts()
    Get the number of transactions timed out before being sent to or responded by VoltDB server(s) during the time period covered by this stats instance.
    long
    getIOReadThroughput()
    Return an average throughput of bytes read per second from the network for the duration covered by this stats instance.
    long
    getIOWriteThroughput()
    Return an average throughput of bytes sent per second over the network for the duration covered by this stats instance.
    long[]
    getLatencyBucketsBy100ms()
    Get the raw buckets used for latency tracking in 1ms increments.
    long[]
    getLatencyBucketsBy10ms()
    Get the raw buckets used for latency tracking in 10ms increments.
    long[]
    getLatencyBucketsBy1ms()
    Get the raw buckets used for latency tracking in 1ms increments.
    int
    getPort()
    The port number of the connection this stats instance covers.
    String
    getProcedureName()
    Get the name of the procedure this statistics instance applies to.
    long
    getStartTimestamp()
    Get the Date-compatible timestamp that describes the start of the range of time this stats instance covers.
    long
    getTxnThroughput()
    Return an average throughput of transactions acknowledged per second for the duration covered by this stats instance.
    int
    kPercentileLatency(double percentile)
    Using the latency bucketing statistics gathered by the client, estimate the k-percentile latency value for the time period covered by this stats instance.
    double
    kPercentileLatencyAsDouble(double percentile)
    Using the latency bucketing statistics gathered by the client, estimate the k-percentile latency value for the time period covered by this stats instance.
    String
    latencyHistoReport()
    Generate a human-readable report of latencies in the form of a histogram.
    String
    toString()
     

    Methods inherited from class java.lang.Object

    equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • ONE_MS_BUCKET_COUNT

      public static final int ONE_MS_BUCKET_COUNT
      The number of buckets tracking latency with 1ms granularity.
      See Also:

    • TEN_MS_BUCKET_COUNT

      public static final int TEN_MS_BUCKET_COUNT
      The number of buckets tracking latency with 10ms granularity.
      See Also:

    • HUNDRED_MS_BUCKET_COUNT

      public static final int HUNDRED_MS_BUCKET_COUNT
      The number of buckets tracking latency with 100ms granularity.
      See Also:

  • Method Details

    • constructHistogram

      public static org.HdrHistogram_voltpatches.Histogram constructHistogram()

    • getProcedureName

      public String getProcedureName()
      Get the name of the procedure this statistics instance applies to.
      Returns:
      The name of the procedure or the empty string if this stats instance covers more than one procedure.

    • getStartTimestamp

      public long getStartTimestamp()
      Get the Date-compatible timestamp that describes the start of the range of time this stats instance covers.
      Returns:
      A timestamp in milliseconds since the epoch.

    • getEndTimestamp

      public long getEndTimestamp()
      Get the Date-compatible timestamp that describes the end of the range of time this stats instance covers.
      Returns:
      A timestamp in milliseconds since the epoch.

    • getDuration

      public long getDuration()
      Get the number of milliseconds this stats instance covers.
      Returns:
      The number of milliseconds this stats instance covers.

    • getConnectionId

      public long getConnectionId()
      Get the id of the individual socket connection this statistics instance applies to. Note that hostname and port combos might not be unique, but connection ids will be.
      Returns:
      The id of the connection or -1 if this stats instance covers more than one connection.

    • getHostname

      public String getHostname()
      The hostname or IP (as string) of the connection this stats instance covers.
      Returns:
      The hostname or ip as string, or the empty string if this stats instance covers more than one connection.

    • getPort

      public int getPort()
      The port number of the connection this stats instance covers.
      Returns:
      The port number, or -1 if this stats instance covers more than one connection.

    • getInvocationsCompleted

      public long getInvocationsCompleted()
      Get the number of transactions acknowledged by the VoltDB server(s) during the time period covered by this stats instance.
      Returns:
      The number of transactions completed.

    • getInvocationAborts

      public long getInvocationAborts()
      Get the number of transactions aborted by the VoltDB server(s) during the time period covered by this stats instance.
      Returns:
      The number of transactions aborted.

    • getInvocationErrors

      public long getInvocationErrors()
      Get the number of transactions failed by the VoltDB server(s) during the time period covered by this stats instance.
      Returns:
      The number of transactions that failed.

    • getInvocationTimeouts

      public long getInvocationTimeouts()
      Get the number of transactions timed out before being sent to or responded by VoltDB server(s) during the time period covered by this stats instance.
      Returns:
      The number of transactions that failed.

    • getAverageLatency

      public double getAverageLatency()
      Get the average latency in milliseconds for the time period covered by this stats instance. This is computed by summing the client-measured round trip times of all transactions and dividing by the competed invocation count.
      Returns:
      Average latency in milliseconds.

    • getAverageInternalLatency

      public double getAverageInternalLatency()

      Get the server-side average latency in milliseconds for the time period covered by this stats instance. This is computed by summing the server-reported latency times of all transactions and dividing by the competed invocation count.

      The server reported latency number measures the time from when a transaction is accepted from the socket to when the response is written back. It will be higher for multi-node clusters, for clusters with too much load, or for clusters with longer running transactions.

      Returns:
      Average latency in milliseconds.

    • getLatencyBucketsBy1ms

      public long[] getLatencyBucketsBy1ms()

      Get the raw buckets used for latency tracking in 1ms increments. For example, if a transaction returns in 3.2ms, then the array at index 3 will be incremented by one. It can be thought of as a histogram of latencies. It has ONE_MS_BUCKET_COUNT buckets, for a range of ONE_MS_BUCKET_COUNT x 1ms

      This raw data, along with other bucket sets of different granularity, is used to support the kPercentileLatency(double) method. This returns a copy of the internal array so it is threadsafe and mutable if you wish. Note that the buckets

      Returns:
      An array containing counts for different latency values.

    • getLatencyBucketsBy10ms

      public long[] getLatencyBucketsBy10ms()

      Get the raw buckets used for latency tracking in 10ms increments. For example, if a transaction returns in 42ms, then the array at index 4 will be incremented by one. It can be thought of as a histogram of latencies. It has TEN_MS_BUCKET_COUNT buckets, for a range of TEN_MS_BUCKET_COUNT x 10ms.

      This raw data, along with other bucket sets of different granularity, is used to support the kPercentileLatency(double) method. This returns a copy of the internal array so it is threadsafe and mutable if you wish. Note that the buckets

      Returns:
      An array containing counts for different latency values.

    • getLatencyBucketsBy100ms

      public long[] getLatencyBucketsBy100ms()

      Get the raw buckets used for latency tracking in 1ms increments. For example, if a transaction returns in 3.2ms, then the array at index 3 will be incremented by one. It can be thought of as a histogram of latencies. It has HUNDRED_MS_BUCKET_COUNT buckets, for a range of HUNDRED_MS_BUCKET_COUNT x 100ms.

      This raw data, along with other bucket sets of different granularity, is used to support the kPercentileLatency(double) method. This returns a copy of the internal array so it is threadsafe and mutable if you wish. Note that the buckets

      Returns:
      An array containing counts for different latency values.

    • getBytesWritten

      public long getBytesWritten()
      Return the number of bytes written over the network during the time period covered by this stats instance. This can be specific to a connection or global, but is not recorded for per-procedure statistics.
      Returns:
      The number of bytes written or 0 for per-procedure statistics.

    • getBytesRead

      public long getBytesRead()
      Return the number of bytes read from the network during the time period covered by this stats instance. This can be specific to a connection or global, but is not recorded for per-procedure statistics.
      Returns:
      The number of bytes read or 0 for per-procedure statistics.

    • kPercentileLatency

      public int kPercentileLatency(double percentile)

      Using the latency bucketing statistics gathered by the client, estimate the k-percentile latency value for the time period covered by this stats instance.

      For example, k=.5 returns an estimate of the median. k=0 returns the minimum. k=1.0 returns the maximum.

      Latencies longer than the highest trackable value (10 seconds) will be reported as multiple entries at the highest trackable value

      Parameters:
      percentile - A floating point number between 0.0 and 1.0.
      Returns:
      An estimate of k-percentile latency in whole milliseconds.

    • kPercentileLatencyAsDouble

      public double kPercentileLatencyAsDouble(double percentile)

      Using the latency bucketing statistics gathered by the client, estimate the k-percentile latency value for the time period covered by this stats instance.

      For example, k=.5 returns an estimate of the median. k=0 returns the minimum. k=1.0 returns the maximum.

      Latencies longer than the highest trackable value (10 seconds) will be reported as multiple entries at the highest trackable value

      Parameters:
      percentile - A floating point number between 0.0 and 1.0.
      Returns:
      An estimate of k-percentile latency in whole milliseconds.

    • latencyHistoReport

      public String latencyHistoReport()
      Generate a human-readable report of latencies in the form of a histogram. Latency is in milliseconds
      Returns:
      String containing human-readable report.

    • getTxnThroughput

      public long getTxnThroughput()

      Return an average throughput of transactions acknowledged per second for the duration covered by this stats instance.

      Essentially getInvocationsCompleted() divided by (getStartTimestamp() - getEndTimestamp() / 1000.0), but with additional safety checks.

      Returns:
      Throughput in transactions acknowledged per second.

    • getIOWriteThroughput

      public long getIOWriteThroughput()

      Return an average throughput of bytes sent per second over the network for the duration covered by this stats instance.

      Essentially getBytesWritten() divided by (getStartTimestamp() - getEndTimestamp() / 1000.0), but with additional safety checks.

      Returns:
      Throughput in bytes sent per second.

    • getIOReadThroughput

      public long getIOReadThroughput()

      Return an average throughput of bytes read per second from the network for the duration covered by this stats instance.

      Essentially getBytesRead() divided by (getStartTimestamp() - getEndTimestamp() / 1000.0), but with additional safety checks.

      Returns:
      Throughput in bytes read per second.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • clone

      protected Object clone()
      Overrides:
      clone in class Object