C# Class HdrHistogram.HistogramExtensions

Extension methods for the Histogram types.

Mostra file Open project: HdrHistogram/HdrHistogram.NET

Public Methods

Method	Description
CopyInto ( this source, HistogramBase targetHistogram ) : void	Copy this histogram into the target histogram, overwriting it's contents.
GetMaxValue ( this histogram ) : long	Get the highest recorded value level in the histogram
GetMean ( this histogram ) : double	Get the computed mean value of all recorded values in the histogram
GetStdDeviation ( this histogram ) : double	Get the computed standard deviation of all recorded values in the histogram
HighestEquivalentValue ( this histogram, long value ) : long	Get the highest 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.
OutputPercentileDistribution ( this histogram, TextWriter writer, int percentileTicksPerHalfDistance = 5, double outputValueUnitScalingRatio = OutputScalingFactor.None, bool useCsvFormat = false ) : void	Produce textual representation of the value distribution of histogram data by percentile. The distribution is output with exponentially increasing resolution, with each exponentially decreasing half-distance containing percentileTicksPerHalfDistance percentile reporting tick points.
Percentiles ( this histogram, int percentileTicksPerHalfDistance ) : IEnumerable	Provide a means of iterating through histogram values according to percentile levels. The iteration is performed in steps that start at 0% and reduce their distance to 100% according to the percentileTicksPerHalfDistance parameter, ultimately reaching 100% when all recorded histogram values are exhausted.
Record ( this recorder, System.Action action ) : void	Executes the action and records the time to complete the action. The time is recorded in system clock ticks. This time may vary between frameworks and platforms, but is equivalent to `(1/Stopwatch.Frequency)` seconds. Note this is a convenience method and can carry a cost. If the action delegate is not cached, then it may incur an allocation cost for each invocation of Record The units returned from `Stopwatch.GetTimestamp()` are used as the unit of recording here as they are the smallest unit that .NET can measure and require no conversion at time of recording. Instead conversion (scaling) can be done at time of output to microseconds, milliseconds, seconds or other appropriate unit. These units are sometimes referred to as ticks, but should not not to be confused with ticks used in DateTime or TimeSpan. If you are able to cache the action delegate, then doing so is encouraged. Here are two examples. The first does not cache the delegate `for (long i = 0; i < loopCount; i++) { histogram.Record(IncrementNumber); }` This second example does cache the delegate `Action incrementNumber = IncrementNumber; for (long i = 0; i < loopCount; i++) { histogram.Record(incrementNumber); }` In the second example, we will not be making allocations each time i.e. an allocation of an Action from `IncrementNumber`. This will reduce memory pressure and therefore garbage collection penalties. For performance sensitive applications, this method may not be suitable. As always, you are encouraged to test and measure the impact for your scenario.

Method Details

CopyInto() public static method

Copy this histogram into the target histogram, overwriting it's contents.

public static CopyInto ( this source, HistogramBase targetHistogram ) : void
source	this	The source histogram
targetHistogram	HistogramBase	the histogram to copy into
return	void

GetMaxValue() public static method

Get the highest recorded value level in the histogram

public static GetMaxValue ( this histogram ) : long
histogram	this
return	long

GetMean() public static method

Get the computed mean value of all recorded values in the histogram

public static GetMean ( this histogram ) : double
histogram	this
return	double

GetStdDeviation() public static method

Get the computed standard deviation of all recorded values in the histogram

public static GetStdDeviation ( this histogram ) : double
histogram	this
return	double

HighestEquivalentValue() public static method

Get the highest 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 static HighestEquivalentValue ( this histogram, long value ) : long
histogram	this	The histogram to operate on
value	long	The given value
return	long

OutputPercentileDistribution() public static method

Produce textual representation of the value distribution of histogram data by percentile. The distribution is output with exponentially increasing resolution, with each exponentially decreasing half-distance containing percentileTicksPerHalfDistance percentile reporting tick points.

public static OutputPercentileDistribution ( this histogram, TextWriter writer, int percentileTicksPerHalfDistance = 5, double outputValueUnitScalingRatio = OutputScalingFactor.None, bool useCsvFormat = false ) : void
histogram	this	The histogram to operate on
writer	System.IO.TextWriter	The into which the distribution will be output
percentileTicksPerHalfDistance	int	/// The number of reporting points per exponentially decreasing half-distance ///
outputValueUnitScalingRatio	double	/// The scaling factor by which to divide histogram recorded values units in output. /// Use the constant values to help choose an appropriate output measurement. ///
useCsvFormat	bool	Output in CSV (Comma Separated Values) format if true, else use plain text form.
return	void

Percentiles() public static method

Provide a means of iterating through histogram values according to percentile levels. The iteration is performed in steps that start at 0% and reduce their distance to 100% according to the percentileTicksPerHalfDistance parameter, ultimately reaching 100% when all recorded histogram values are exhausted.

public static Percentiles ( this histogram, int percentileTicksPerHalfDistance ) : IEnumerable
histogram	this	The histogram to operate on
percentileTicksPerHalfDistance	int	/// The number of iteration steps per half-distance to 100%. ///
return	IEnumerable

Record() public static method

Executes the action and records the time to complete the action. The time is recorded in system clock ticks. This time may vary between frameworks and platforms, but is equivalent to (1/Stopwatch.Frequency) seconds. Note this is a convenience method and can carry a cost. If the action delegate is not cached, then it may incur an allocation cost for each invocation of Record

The units returned from Stopwatch.GetTimestamp() are used as the unit of recording here as they are the smallest unit that .NET can measure and require no conversion at time of recording. Instead conversion (scaling) can be done at time of output to microseconds, milliseconds, seconds or other appropriate unit. These units are sometimes referred to as ticks, but should not not to be confused with ticks used in DateTime or TimeSpan.

If you are able to cache the action delegate, then doing so is encouraged. Here are two examples. The first does not cache the delegate for (long i = 0; i < loopCount; i++) { histogram.Record(IncrementNumber); } This second example does cache the delegate Action incrementNumber = IncrementNumber; for (long i = 0; i < loopCount; i++) { histogram.Record(incrementNumber); } In the second example, we will not be making allocations each time i.e. an allocation of an Action from IncrementNumber. This will reduce memory pressure and therefore garbage collection penalties. For performance sensitive applications, this method may not be suitable. As always, you are encouraged to test and measure the impact for your scenario.

public static Record ( this recorder, System.Action action ) : void
recorder	this	The instance to record the latency in.
action	System.Action	The functionality to execute and measure
return	void