C# Class HdrHistogram.HistogramBase

Base class for High Dynamic Range (HDR) Histograms

HistogramBase supports the recording and analyzing sampled data value counts across a configurable integer value range with configurable value precision within the range. Value precision is expressed as the number of significant digits in the value recording, and provides control over value quantization behavior across the value range and the subsequent value resolution at any given level.

For example, a Histogram could be configured to track the counts of observed integer values between 0 and 36,000,000,000 while maintaining a value precision of 3 significant digits across that range. Value quantization within the range will thus be no larger than 1/1,000th (or 0.1%) of any value. This example Histogram could be used to track and analyze the counts of observed response times ranging between 100 nanoseconds and 1 hour in magnitude, while maintaining a value resolution of 100 nanosecond up to 100 microseconds, a resolution of 1 millisecond(or better) up to one second, and a resolution of 1 second (or better) up to 1,000 seconds. At it's maximum tracked value(1 hour), it would still maintain a resolution of 3.6 seconds (or better).

Inheritance: IRecorder

Mostra file Open project: HdrHistogram/HdrHistogram.NET Class Usage Examples

Private Properties

Property	Type	Description
CountsArrayIndex	int
EstablishInternalTackingValues	void
FillCountsFromBuffer	int
GetBucketIndex	int
GetBucketIndex	int
GetBucketsNeededToCoverValue	int
GetCountAt	long
GetData	IRecordedData
GetLengthForNumberOfBuckets	int
GetNeededByteBufferCapacity	int
GetRelevantCounts	long[]
GetSubBucketIndex	int
RecordSingleValue	void
RecordValueWithCountAndExpectedInterval	void
ResetMaxValue	void
ResetMinNonZeroValue	void
UpdateMinNonZeroValue	void
UpdatedMaxValue	void
ValueFromIndex	long
ValueFromIndex	long

Public Methods

Method	Description
Add ( HistogramBase fromHistogram ) : void	Add the contents of another histogram to this one.
AllValues ( ) : IEnumerable	Provide a means of iterating through all histogram values using the finest granularity steps supported by the underlying representation. The iteration steps through all possible unit value levels, regardless of whether or not there were recorded values for that value level, and terminates when all recorded histogram values are exhausted.
Copy ( ) : HistogramBase	Copies the data from this instance to a new instance.
Encode ( ByteBuffer targetBuffer, IEncoder encoder ) : int	Encode this histogram into a ByteBuffer
GetCountAtValue ( long value ) : long	Get the count of recorded values at a specific value
GetEstimatedFootprintInBytes ( ) : int	Provide a (conservatively high) estimate of the Histogram's total footprint in bytes
GetNeededByteBufferCapacity ( ) : int	Get the capacity needed to encode this histogram into a ByteBuffer
GetValueAtPercentile ( double percentile ) : long	Get the value at a given percentile
HasOverflowed ( ) : bool	Determine if this histogram had any of it's value counts overflow. Since counts are kept in fixed integer form with potentially limited range (e.g. int and short), a specific value range count could potentially overflow, leading to an inaccurate and misleading histogram representation. This method accurately determines whether or not an overflow condition has happened in an IntHistogram or ShortHistogram.
LowestEquivalentValue ( long value ) : long	Get the lowest value that is equivalent to the given value within the histogram's resolution. Where "equivalent" means that value samples recorded for any two equivalent values are counted in a common total count.
MedianEquivalentValue ( long value ) : long	Get a value that lies in the middle (rounded up) of the range of values equivalent the given value. Where "equivalent" means that value samples recorded for any two equivalent values are counted in a common total count.
NextNonEquivalentValue ( long value ) : long	Get the next value that is not equivalent to the given value within the histogram's resolution. Where "equivalent" means that value samples recorded for any two equivalent values are counted in a common total count.
RecordValue ( long value ) : void	Records a value in the histogram
RecordValueWithCount ( long value, long count ) : void	Record a value in the histogram (adding to the value's current count)
RecordValueWithExpectedInterval ( long value, long expectedIntervalBetweenValueSamples ) : void	Record a value in the histogram. To compensate for the loss of sampled values when a recorded value is larger than the expected interval between value samples, Histogram will auto-generate an additional series of decreasingly-smaller (down to the expectedIntervalBetweenValueSamples) value records. Note: This is a at-recording correction method, as opposed to the post-recording correction method provided by CopyCorrectedForCoordinatedOmission. The two methods are mutually exclusive, and only one of the two should be be used on a given data set to correct for the same coordinated omission issue. See notes in the description of the Histogram calls for an illustration of why this corrective behavior is important.
RecordedValues ( ) : IEnumerable	Provide a means of iterating through all recorded histogram values using the finest granularity steps supported by the underlying representation. The iteration steps through all non-zero recorded value counts, and terminates when all recorded histogram values are exhausted.
Reset ( ) : void	Reset the contents and stats of this histogram
SizeOfEquivalentValueRange ( long value ) : long	Get the size (in value units) of the range of values that are equivalent to the given value within the histogram's resolution. Where "equivalent" means that value samples recorded for any two equivalent values are counted in a common total count.

Protected Methods

Method	Description
AddToCountAtIndex ( int index, long addend ) : void	Adds the specified amount to the count of the provided index. Also increments the TotalCount by the same amount.
ClearCounts ( ) : void	Clears the counts of this implementation.
CopyCountsInto ( long target ) : void	Copies the internal counts array into the supplied array.
GetCountAtIndex ( int index ) : long	Gets the number of recorded values at a given index.
HistogramBase ( long lowestTrackableValue, long highestTrackableValue, int numberOfSignificantValueDigits ) : System	Construct a histogram given the lowest and highest values to be tracked and a number of significant decimal digits. Providing a lowestTrackableValue is useful in situations where the units used for the histogram's values are much smaller that the minimal accuracy required. For example when tracking time values stated in nanoseconds, where the minimal accuracy required is a microsecond, the proper value for lowestTrackableValue would be 1000.
HistogramBase ( long instanceId, long lowestTrackableValue, long highestTrackableValue, int numberOfSignificantValueDigits ) : System	Construct a histogram given the lowest and highest values to be tracked and a number of significant decimal digits. Providing a lowestTrackableValue is useful in situations where the units used for the histogram's values are much smaller that the minimal accuracy required. For example when tracking time values stated in ticks (100 nanoseconds), where the minimal accuracy required is a microsecond, the proper value for lowestTrackableValue would be 10.
IncrementCountAtIndex ( int index ) : void	Increments the count at the given index. Will also increment the TotalCount.
SetCountAtIndex ( int index, long value ) : void	Sets the count at the given index.

Private Methods

Method	Description
CountsArrayIndex ( int bucketIndex, int subBucketIndex ) : int
EstablishInternalTackingValues ( int lengthToCover ) : void
FillCountsFromBuffer ( ByteBuffer buffer, int length, int wordSizeInBytes ) : int	Copies data from the provided buffer into the internal counts array.
GetBucketIndex ( long value ) : int
GetBucketIndex ( long value, long subBucketMask, int bucketIndexOffset ) : int
GetBucketsNeededToCoverValue ( long value ) : int
GetCountAt ( int bucketIndex, int subBucketIndex ) : long
GetData ( ) : IRecordedData
GetLengthForNumberOfBuckets ( int numberOfBuckets ) : int
GetNeededByteBufferCapacity ( int relevantLength ) : int
GetRelevantCounts ( ) : long[]
GetSubBucketIndex ( long value, int bucketIndex ) : int
RecordSingleValue ( long value ) : void
RecordValueWithCountAndExpectedInterval ( long value, long count, long expectedIntervalBetweenValueSamples ) : void
ResetMaxValue ( long maxValue ) : void
ResetMinNonZeroValue ( long minNonZeroValue ) : void
UpdateMinNonZeroValue ( long value ) : void	Set internally tracked _minNonZeroValue to new value if new value is smaller than current one. May be overridden by subclasses for synchronization or atomicity purposes.
UpdatedMaxValue ( long value ) : void	Set internally tracked _maxValue to new value if new value is greater than current one. May be overridden by subclasses for synchronization or atomicity purposes.
ValueFromIndex ( int index ) : long
ValueFromIndex ( int bucketIndex, int subBucketIndex ) : long

Method Details

Add() public method

Add the contents of another histogram to this one.

if values in fromHistogram's are higher than highestTrackableValue.

public Add ( HistogramBase fromHistogram ) : void
fromHistogram	HistogramBase	The other histogram.
return	void

AddToCountAtIndex() protected abstract method

Adds the specified amount to the count of the provided index. Also increments the TotalCount by the same amount.

protected abstract AddToCountAtIndex ( int index, long addend ) : void
index	int	The index to increment.
addend	long	The amount to increment by.
return	void

AllValues() public method

Provide a means of iterating through all histogram values using the finest granularity steps supported by the underlying representation. The iteration steps through all possible unit value levels, regardless of whether or not there were recorded values for that value level, and terminates when all recorded histogram values are exhausted.

public AllValues ( ) : IEnumerable
return	IEnumerable

ClearCounts() protected abstract method

Clears the counts of this implementation.

protected abstract ClearCounts ( ) : void
return	void

Copy() public abstract method

Copies the data from this instance to a new instance.

public abstract Copy ( ) : HistogramBase
return	HistogramBase

CopyCountsInto() protected abstract method

Copies the internal counts array into the supplied array.

protected abstract CopyCountsInto ( long target ) : void
target	long	The array to write each count value into.
return	void

Encode() public method

Encode this histogram into a ByteBuffer

public Encode ( ByteBuffer targetBuffer, IEncoder encoder ) : int
targetBuffer	ByteBuffer	The buffer to encode into
encoder	IEncoder	The encoder to use
return	int

GetCountAtIndex() protected abstract method

Gets the number of recorded values at a given index.

protected abstract GetCountAtIndex ( int index ) : long
index	int	The index to get the count for
return	long

GetCountAtValue() public method

Get the count of recorded values at a specific value

On parameters that are outside the tracked value range

public GetCountAtValue ( long value ) : long
value	long	The value for which to provide the recorded count
return	long

GetEstimatedFootprintInBytes() public method

Provide a (conservatively high) estimate of the Histogram's total footprint in bytes

public GetEstimatedFootprintInBytes ( ) : int
return	int

GetNeededByteBufferCapacity() public method

Get the capacity needed to encode this histogram into a ByteBuffer

public GetNeededByteBufferCapacity ( ) : int
return	int

GetValueAtPercentile() public method

Get the value at a given percentile

public GetValueAtPercentile ( double percentile ) : long
percentile	double	The percentile to get the value for
return	long

HasOverflowed() public method

Determine if this histogram had any of it's value counts overflow.

Since counts are kept in fixed integer form with potentially limited range (e.g. int and short), a specific value range count could potentially overflow, leading to an inaccurate and misleading histogram representation. This method accurately determines whether or not an overflow condition has happened in an IntHistogram or ShortHistogram.

public HasOverflowed ( ) : bool
return	bool

HistogramBase() protected method

Construct a histogram given the lowest and highest values to be tracked and a number of significant decimal digits.

Providing a lowestTrackableValue is useful in situations where the units used for the histogram's values are much smaller that the minimal accuracy required. For example when tracking time values stated in nanoseconds, where the minimal accuracy required is a microsecond, the proper value for lowestTrackableValue would be 1000.

protected HistogramBase ( long lowestTrackableValue, long highestTrackableValue, int numberOfSignificantValueDigits ) : System
lowestTrackableValue	long	The lowest value that can be tracked (distinguished from 0) by the histogram. /// Must be a positive integer that is >= 1. /// May be internally rounded down to nearest power of 2. ///
highestTrackableValue	long	The highest value to be tracked by the histogram. /// Must be a positive integer that is >= (2 * lowestTrackableValue). ///
numberOfSignificantValueDigits	int	/// The number of significant decimal digits to which the histogram will maintain value resolution and separation. /// Must be a non-negative integer between 0 and 5. ///
return	System

HistogramBase() protected method

Construct a histogram given the lowest and highest values to be tracked and a number of significant decimal digits.

Providing a lowestTrackableValue is useful in situations where the units used for the histogram's values are much smaller that the minimal accuracy required. For example when tracking time values stated in ticks (100 nanoseconds), where the minimal accuracy required is a microsecond, the proper value for lowestTrackableValue would be 10.

protected HistogramBase ( long instanceId, long lowestTrackableValue, long highestTrackableValue, int numberOfSignificantValueDigits ) : System
instanceId	long	An identifier for this instance.
lowestTrackableValue	long	The lowest value that can be tracked (distinguished from 0) by the histogram. /// Must be a positive integer that is >= 1. /// May be internally rounded down to nearest power of 2. ///
highestTrackableValue	long	The highest value to be tracked by the histogram. /// Must be a positive integer that is >= (2 * lowestTrackableValue). ///
numberOfSignificantValueDigits	int	/// The number of significant decimal digits to which the histogram will maintain value resolution and separation. /// Must be a non-negative integer between 0 and 5. ///
return	System

IncrementCountAtIndex() protected abstract method

Increments the count at the given index. Will also increment the TotalCount.

protected abstract IncrementCountAtIndex ( int index ) : void
index	int	The index to increment the count at.
return	void

LowestEquivalentValue() public method

Get the lowest value that is equivalent to the given value within the histogram's resolution. Where "equivalent" means that value samples recorded for any two equivalent values are counted in a common total count.

public LowestEquivalentValue ( long value ) : long
value	long	The given value
return	long

MedianEquivalentValue() public method

Get a value that lies in the middle (rounded up) of the range of values equivalent the given value. Where "equivalent" means that value samples recorded for any two equivalent values are counted in a common total count.

public MedianEquivalentValue ( long value ) : long
value	long	The given value
return	long

NextNonEquivalentValue() public method

Get the next value that is not equivalent to the given value within the histogram's resolution. Where "equivalent" means that value samples recorded for any two equivalent values are counted in a common total count.

public NextNonEquivalentValue ( long value ) : long
value	long	The given value
return	long

RecordValue() public method

Records a value in the histogram

if value is exceeds highestTrackableValue

public RecordValue ( long value ) : void
value	long	The value to be recorded
return	void

RecordValueWithCount() public method

Record a value in the histogram (adding to the value's current count)

if value is exceeds highestTrackableValue

public RecordValueWithCount ( long value, long count ) : void
value	long	The value to be recorded
count	long	The number of occurrences of this value to record
return	void

RecordValueWithExpectedInterval() public method

Record a value in the histogram.

To compensate for the loss of sampled values when a recorded value is larger than the expected interval between value samples, Histogram will auto-generate an additional series of decreasingly-smaller (down to the expectedIntervalBetweenValueSamples) value records.

Note: This is a at-recording correction method, as opposed to the post-recording correction method provided by CopyCorrectedForCoordinatedOmission. The two methods are mutually exclusive, and only one of the two should be be used on a given data set to correct for the same coordinated omission issue.

See notes in the description of the Histogram calls for an illustration of why this corrective behavior is important.

if value is exceeds highestTrackableValue

public RecordValueWithExpectedInterval ( long value, long expectedIntervalBetweenValueSamples ) : void
value	long	The value to record
expectedIntervalBetweenValueSamples	long	If is larger than 0, add auto-generated value records as appropriate if is larger than
return	void

RecordedValues() public method

Provide a means of iterating through all recorded histogram values using the finest granularity steps supported by the underlying representation. The iteration steps through all non-zero recorded value counts, and terminates when all recorded histogram values are exhausted.

public RecordedValues ( ) : IEnumerable
return	IEnumerable

Reset() public method

Reset the contents and stats of this histogram

public Reset ( ) : void
return	void

SetCountAtIndex() protected abstract method

Sets the count at the given index.

protected abstract SetCountAtIndex ( int index, long value ) : void
index	int	The index to be set
value	long	The value to set
return	void

SizeOfEquivalentValueRange() public method

Get the size (in value units) of the range of values that are equivalent to the given value within the histogram's resolution. Where "equivalent" means that value samples recorded for any two equivalent values are counted in a common total count.

public SizeOfEquivalentValueRange ( long value ) : long
value	long	The given value
return	long