prometheus_buckets (prometheus v6.1.1)

View Source

Summary

Types

bucket_bound()
buckets()
config()

Histogram buckets configuration.

Functions

ddsketch/2

Creates preallocated buckets according to the DDSketch algorithm.

default()

Default histogram buckets.

exponential/3

Creates Count buckets, where the lowest bucket has an upper bound of Start and each following bucket's upper bound is Factor times the previous bucket's upper bound. The returned list is meant to be used for the buckets key of histogram constructors options.

linear/3

Creates Count buckets, each Width wide, where the lowest bucket has an upper bound of Start.

new()

Histogram buckets constructor, returns default/0 plus infinity

new/1

Histogram buckets constructor

position/2

Find the first index that is greater than or equal to the given value.

Types

bucket_bound()

-type bucket_bound() :: number() | infinity.

buckets()

-type buckets() :: [bucket_bound(), ...].

config()

-type config() ::
          undefined | default |
          {linear, number(), number(), pos_integer()} |
          {exponential, number(), number(), pos_integer()} |
          {ddsketch, float(), pos_integer()} |
          buckets().

Histogram buckets configuration.

Setting the buckets key of a histogram to

  • default: will use the default buckets
  • linear: will use Start, Step, and Count to generate the buckets as in linear/3
  • exponential: will use Start, Factor, and Count to generate the buckets as in exponential/3

You can also specify your own buckets if desired instead.

Functions

ddsketch/2

-spec ddsketch(float(), pos_integer()) -> buckets().

Creates preallocated buckets according to the DDSketch algorithm.

For example, if you measure microseconds and you expect no operation to take more than a day, for a desired error of 1%, 1260 buckets is sufficient.

3> prometheus_buckets:ddsketch(0.01, 1260).
[1.0, 1.02020202020202, 1.040812162024283, 1.0618386703480058 |...]

The function raises {invalid_value, Value, Message} error if Error isn't positive, or if Bound is less than or equals to 1.

default()

-spec default() -> buckets().

Default histogram buckets.

1> prometheus_buckets:default().
[0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]

Please note these buckets are floats and represent seconds so you'll have to use prometheus_histogramdobserve/3 or configure duration_unit as seconds.

exponential/3

-spec exponential(number(), number(), pos_integer()) -> buckets().

Creates Count buckets, where the lowest bucket has an upper bound of Start and each following bucket's upper bound is Factor times the previous bucket's upper bound. The returned list is meant to be used for the buckets key of histogram constructors options.

3> prometheus_buckets:exponential(100, 1.2, 3).
[100, 120, 144]

The function raises {invalid_value, Value, Message} error if Count isn't positive, if Start isn't positive, or if Factor is less than or equals to 1.

linear/3

-spec linear(number(), number(), pos_integer()) -> buckets().

Creates Count buckets, each Width wide, where the lowest bucket has an upper bound of Start.

The returned list is meant to be used for the buckets key of histogram constructors options.

2> prometheus_buckets:linear(10, 5, 6).
[10, 15, 20, 25, 30, 35]

The function raises {invalid_value, Value, Message} error if Count is zero or negative.

new()

-spec new() -> buckets().

Histogram buckets constructor, returns default/0 plus infinity

new/1

-spec new(config()) -> buckets().

Histogram buckets constructor

position/2

-spec position(buckets() | tuple(), number()) -> pos_integer().

Find the first index that is greater than or equal to the given value.