com.netflix.hystrix.util
Class HystrixRollingNumber

java.lang.Object
  com.netflix.hystrix.util.HystrixRollingNumber

@ThreadSafe
public class HystrixRollingNumber
extends java.lang.Object

A number which can be used to track counters (increment) or set values over time.

It is "rolling" in the sense that a 'timeInMilliseconds' is given that you want to track (such as 10 seconds) and then that is broken into buckets (defaults to 10) so that the 10 second window doesn't empty out and restart every 10 seconds, but instead every 1 second you have a new bucket added and one dropped so that 9 of the buckets remain and only the newest starts from scratch.

This is done so that the statistics are gathered over a rolling 10 second window with data being added/dropped in 1 second intervals (or whatever granularity is defined by the arguments) rather than each 10 second window starting at 0 again.

Performance-wise this class is optimized for writes, not reads. This is done because it expects far higher write volume (thousands/second) than reads (a few per second).

For example, on each read to getSum/getCount it will iterate buckets to sum the data so that on writes we don't need to maintain the overall sum and pay the synchronization cost at each write to ensure the sum is up-to-date when the read can easily iterate each bucket to get the sum when it needs it.

See inner-class UnitTest for usage and expected behavior examples.

Constructor Summary

HystrixRollingNumber(HystrixProperty<java.lang.Integer> timeInMilliseconds, HystrixProperty<java.lang.Integer> numberOfBuckets)

Method Summary

void	add(HystrixRollingNumberEvent type, long value) Add to the counter in the current bucket for the given HystrixRollingNumberEvent type.
long	getCumulativeSum(HystrixRollingNumberEvent type) Get the cumulative sum of all buckets ever since the JVM started without rolling for the given HystrixRollingNumberEvent type.
long	getRollingMaxValue(HystrixRollingNumberEvent type) Get the max value of values in all buckets for the given HystrixRollingNumberEvent type.
long	getRollingSum(HystrixRollingNumberEvent type) Get the sum of all buckets in the rolling counter for the given HystrixRollingNumberEvent type.
long	getValueOfLatestBucket(HystrixRollingNumberEvent type) Get the value of the latest (current) bucket in the rolling counter for the given HystrixRollingNumberEvent type.
long[]	getValues(HystrixRollingNumberEvent type) Get an array of values for all buckets in the rolling counter for the given HystrixRollingNumberEvent type.
void	increment(HystrixRollingNumberEvent type) Increment the counter in the current bucket by one for the given HystrixRollingNumberEvent type.
void	reset() Force a reset of all rolling counters (clear all buckets) so that statistics start being gathered from scratch.
void	updateRollingMax(HystrixRollingNumberEvent type, long value) Update a value and retain the max value.

Methods inherited from class java.lang.Object

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

Constructor Detail

HystrixRollingNumber

public HystrixRollingNumber(HystrixProperty<java.lang.Integer> timeInMilliseconds,
                            HystrixProperty<java.lang.Integer> numberOfBuckets)

Method Detail

increment

public void increment(HystrixRollingNumberEvent type)

Increment the counter in the current bucket by one for the given HystrixRollingNumberEvent type.

The HystrixRollingNumberEvent must be a "counter" type HystrixRollingNumberEvent.isCounter() == true.

Parameters:

type - HystrixRollingNumberEvent defining which counter to increment

add

public void add(HystrixRollingNumberEvent type,
                long value)

Add to the counter in the current bucket for the given HystrixRollingNumberEvent type.

The HystrixRollingNumberEvent must be a "counter" type HystrixRollingNumberEvent.isCounter() == true.

Parameters:

type - HystrixRollingNumberEvent defining which counter to add to

value - long value to be added to the current bucket

updateRollingMax

public void updateRollingMax(HystrixRollingNumberEvent type,
                             long value)

Update a value and retain the max value.

The HystrixRollingNumberEvent must be a "max updater" type HystrixRollingNumberEvent.isMaxUpdater() == true.

Parameters:

type -

value -

reset

public void reset()

Force a reset of all rolling counters (clear all buckets) so that statistics start being gathered from scratch.

This does NOT reset the CumulativeSum values.

getCumulativeSum

public long getCumulativeSum(HystrixRollingNumberEvent type)

Get the cumulative sum of all buckets ever since the JVM started without rolling for the given HystrixRollingNumberEvent type.

See HystrixRollingNumber.getRollingSum(HystrixRollingNumberEvent) for the rolling sum.

The HystrixRollingNumberEvent must be a "counter" type HystrixRollingNumberEvent.isCounter() == true.

Parameters:

type -

Returns:

cumulative sum of all increments and adds for the given HystrixRollingNumberEvent counter type

getRollingSum

public long getRollingSum(HystrixRollingNumberEvent type)

Get the sum of all buckets in the rolling counter for the given HystrixRollingNumberEvent type.

The HystrixRollingNumberEvent must be a "counter" type HystrixRollingNumberEvent.isCounter() == true.

Parameters:

type - HystrixRollingNumberEvent defining which counter to retrieve values from

Returns:

value from the given HystrixRollingNumberEvent counter type

getValueOfLatestBucket

public long getValueOfLatestBucket(HystrixRollingNumberEvent type)

Get the value of the latest (current) bucket in the rolling counter for the given HystrixRollingNumberEvent type.

The HystrixRollingNumberEvent must be a "counter" type HystrixRollingNumberEvent.isCounter() == true.

Parameters:

type - HystrixRollingNumberEvent defining which counter to retrieve value from

Returns:

value from latest bucket for given HystrixRollingNumberEvent counter type

getValues

public long[] getValues(HystrixRollingNumberEvent type)

Get an array of values for all buckets in the rolling counter for the given HystrixRollingNumberEvent type.

Index 0 is the oldest bucket.

The HystrixRollingNumberEvent must be a "counter" type HystrixRollingNumberEvent.isCounter() == true.

Parameters:

type - HystrixRollingNumberEvent defining which counter to retrieve values from

Returns:

array of values from each of the rolling buckets for given HystrixRollingNumberEvent counter type

getRollingMaxValue

public long getRollingMaxValue(HystrixRollingNumberEvent type)

Get the max value of values in all buckets for the given HystrixRollingNumberEvent type.

The HystrixRollingNumberEvent must be a "max updater" type HystrixRollingNumberEvent.isMaxUpdater() == true.

Parameters:

type - HystrixRollingNumberEvent defining which "max updater" to retrieve values from

Returns:

max value for given HystrixRollingNumberEvent type during rolling window