Skip to content

Latest commit

 

History

History
228 lines (146 loc) · 7.39 KB

exometer_histogram.md

File metadata and controls

228 lines (146 loc) · 7.39 KB

Module exometer_histogram

Exometer histogram probe behavior This module implements histogram metrics.

Behaviours: exometer_probe.

Description

Each histogram is a sliding window, for which the following datapoints are calculated:

  • max: the maximum value
  • min: the minimum value
  • mean: the arithmetic mean
  • median: the median
  • 50|75|90|95|97|99: percentiles
  • 999: the 99.9th percentile
  • n: the number of values used in the calculation (Note)

Two histogram implementations are supported and can be selected using the option histogram_module:

  • exometer_slide implements a sliding window, which saves all elements within the window. Updating the histogram is cheap, but calculating the datapoints may be expensive depending on the size of the window.

  • exometer_slot_slide (default), aggregates mean, min and max values within given time slots, thereby reducing the amount of data kept for datapoint calculation. The update overhead should be insignificant. However, some loss of precision must be expected. To achieve slightly better accuracy of percentiles, 'extra values' are kept (every 4th value). For the calculation, extra vaules are included in the set until a suitable number has been reached (up to 600). Note that n reflects the number of values used in the calculation - not the number of updates made within the time window.

Supported options:

  • time_span (default: 60000) size of the window in milliseconds.
  • slot_period (default: 10) size of the time slots in milliseconds.
  • histogram_module (default: exometer_slot_slide).
  • truncate (default: true) whether to truncate the datapoint values. Supported values: true | false | round, where round means to round the value rather than truncating it.
  • keep_high (default: 0) number of top values to actually keep.

The keep_high option can be used to get better precision for the higher percentiles. A bounded buffer (see exometer_shallowtree) is used to store the highest values, and these values are used to calculate the exact higher percentiles, as far as they go. For example, if the window saw 10,000 values, and the 1000 highest values are kept, these can be used to determine the percentiles 90 and up.

Function Index

average_sample/3
average_transform/2
behaviour/0
datapoints/0
probe_code_change/3
probe_get_datapoints/1
probe_get_value/2
probe_handle_msg/2
probe_init/3
probe_reset/1
probe_sample/1
probe_setopts/3
probe_terminate/1
probe_update/2
test_run/1Equivalent to test_run(Module, 1).
test_run/2Test the performance and accuracy of a histogram callback module.
test_series/0Create a series of values for histogram testing.

Function Details

average_sample/3

average_sample(TS, Val, Sample) -> any()

average_transform/2

average_transform(TS, Sample) -> any()

behaviour/0


behaviour() -> exometer:behaviour()

datapoints/0

datapoints() -> any()

probe_code_change/3

probe_code_change(X1, S, X3) -> any()

probe_get_datapoints/1

probe_get_datapoints(St) -> any()

probe_get_value/2

probe_get_value(DPs, St) -> any()

probe_handle_msg/2

probe_handle_msg(X1, S) -> any()

probe_init/3

probe_init(Name, Type, Options) -> any()

probe_reset/1

probe_reset(St) -> any()

probe_sample/1

probe_sample(St) -> any()

probe_setopts/3

probe_setopts(Entry, Opts, St) -> any()

probe_terminate/1

probe_terminate(St) -> any()

probe_update/2

probe_update(Value, St) -> any()

test_run/1

test_run(Module) -> any()

Equivalent to test_run(Module, 1).

test_run/2

test_run(Module, Interval) -> any()

Test the performance and accuracy of a histogram callback module.

This function uses a test set (test_series/0) and initializes and updates a histogram using the callback module Module.

The Module argument can either be the module name, or {ModName, Opts} where Opts are options passed on to the histogram module.

Interval is the gap in milliseconds between the inserts. The test run will not actually wait, but instead manipulate the timestamp.

Return value: [Result1, Result2], where the results are {Time1, Time2, Datapoints}. Time1 is the time (in microsecs) it took to insert the values. Time2 is the time it took to calculate all default datapoints. The data set is shuffled between the two runs.

test_series/0


test_series() -> [integer()]

Create a series of values for histogram testing.

These are the properties of the current test set (note: bear no longer in use):

  1> rp(bear:get_statistics(exometer_histogram:test_series())).
  [{min,3},
   {max,100},
   {arithmetic_mean,6.696},
   {geometric_mean,5.546722009408586},
   {harmonic_mean,5.033909932832006},
   {median,5},
   {variance,63.92468674297564},
   {standard_deviation,7.995291535833802},
   {skewness,7.22743137858698},
   {kurtosis,59.15674033499604},
   {percentile,[{50,5},{75,7},{90,8},{95,9},{99,50},{999,83}]},
   {histogram,[{4,2700},
               {5,1800},
               {6,900},
               {7,1800},
               {8,900},
               {9,720},
               {53,135},
               {83,36},
               {103,9}]},
   {n,9000}]