View Source prometheus_histogram (prometheus v4.13.0)

A Histogram tracks the size and number of events in buckets. You can use Histograms for aggregatable calculation of quantiles.

Example use cases for Histograms:

Response latency
Request size

Histogram expects buckets key in a metric spec. Buckets can be:

a list of numbers in increasing order;
default;
{linear, Start, Step, Count;
{exponential, Start, Step, Count}

Example:

-module(example_instrumenter).

setup() ->
    prometheus_histogram:declare([{name, http_request_duration_milliseconds},
                                  {labels, [method]},
                                  {buckets, [100, 300, 500, 750, 1000]},
                                  {help, \"Http Request execution time.\"}]).

instrument(Time, Method) ->
    %% Time must be in native units, otherwise duration_unit must be false
    prometheus_histogram:observe(http_request_duration_milliseconds, [Method], Time).

The prometheus_histogram:observe_n/3,4,5 adds limited support for the \"weighted\" histograms. It accepts the extra integer argument \"Count\" to update the number of observations in the bucket by adding that number. This allows for better accuracy in the case of irregular measurements, assuming that the \"Count\" conveys the observation time interval (for example, the number of time ticks when the recent value was observed).

Summary

Functions

buckets(Name)

Equivalent to buckets(default, Name, []).

buckets(Name, LabelValues)

Equivalent to buckets(default, Name, LabelValues).

buckets(Registry, Name, LabelValues)

Returns buckets of the histogram identified by Registry, Name and LabelValues.

declare(Spec)

Creates a histogram using Spec. If a histogram with the same Spec exists returns false.

deregister(Name)

Equivalent to deregister(default, Name).

deregister(Registry, Name)

Removes all histogram series with name Name and removes Metric Family from Registry.

new(Spec)

Creates a histogram using Spec.

observe(Name, Value)

Equivalent to observe(default, Name, [], Value).

observe(Name, LabelValues, Value)

Equivalent to observe(default, Name, LabelValues, Value).

observe(Registry, Name, LabelValues, Value)

Observes the given Value.

observe_duration(Name, Fun)

Equivalent to observe_duration(default, Name, [], Fun).

observe_duration(Name, LabelValues, Fun)

Equivalent to observe_duration(default, Name, LabelValues, Fun).

observe_duration(Registry, Name, LabelValues, Fun)

Tracks the amount of time spent executing Fun.

observe_n(Name, Value, Count)

Equivalent to observe_n(default, Name, [], Value, Count).

observe_n(Name, LabelValues, Value, Count)

Equivalent to observe_n(default, Name, LabelValues, Value, Count).

observe_n(Registry, Name, LabelValues, Value, Count)

Observes the given Value, Count times.

pobserve(Registry, Name, LabelValues, Buckets, BucketPos, Value)

Observes the given Value, Count times, in the bucket position of the bucket list.

remove(Name)

Equivalent to remove(default, Name, []).

remove(Name, LabelValues)

Equivalent to remove(default, Name, LabelValues).

remove(Registry, Name, LabelValues)

Removes histogram series identified by Registry, Name and LabelValues.

reset(Name)

Equivalent to reset(default, Name, []).

reset(Name, LabelValues)

Equivalent to reset(default, Name, LabelValues).

reset(Registry, Name, LabelValues)

Resets the value of the histogram identified by Registry, Name and LabelValues.

value(Name)

Equivalent to value(default, Name, []).

value(Name, LabelValues)

Equivalent to value(default, Name, LabelValues).

value(Registry, Name, LabelValues)

Returns the value of the histogram identified by Registry, Name and LabelValues. If there is no histogram for LabelValues, returns undefined.

values(Registry, Name)

Functions

buckets(Name)

-spec buckets(prometheus_metric:name()) -> [number()].

Equivalent to buckets(default, Name, []).

buckets(Name, LabelValues)

-spec buckets(prometheus_metric:name(), prometheus_metric:labels()) -> [number()].

Equivalent to buckets(default, Name, LabelValues).

buckets(Registry, Name, LabelValues)

-spec buckets(Registry, Name, LabelValues) -> [number()]
                 when
                     Registry :: prometheus_registry:registry(),
                     Name :: prometheus_metric:name(),
                     LabelValues :: prometheus_metric:labels().

Returns buckets of the histogram identified by Registry, Name and LabelValues.

declare(Spec)

-spec declare(prometheus_metric:spec()) -> boolean().

Creates a histogram using Spec. If a histogram with the same Spec exists returns false.

Raises:

{missing_metric_spec_key, Key, Spec} error if required Spec key is missing.
{invalid_metric_name, Name, Message} error if metric Name is invalid.
{invalid_metric_help, Help, Message} error if metric Help is invalid.
{invalid_metric_labels, Labels, Message} error if Labels isn't a list.
{invalid_label_name, Name, Message} error if Name isn't a valid label name.
{invalid_value_error, Value, MessagE} error if duration_unit is unknown or doesn't match metric name.

Histogram-specific errors:

Raises:

{no_buckets, Buckets} error if Buckets are missing, not a list, empty list or not known buckets spec.
{invalid_buckets, Buckets, Message} error if Buckets aren't in increasing order.
{invalid_bound, Bound} error if Bound isn't a number.

deregister(Name)

-spec deregister(prometheus_metric:name()) -> {boolean(), boolean()}.

Equivalent to deregister(default, Name).

deregister(Registry, Name)

-spec deregister(prometheus_registry:registry(), prometheus_metric:name()) -> {boolean(), boolean()}.

Removes all histogram series with name Name and removes Metric Family from Registry.

After this call new/1 for Name and Registry will succeed.

Returns {true, _} if Name was a registered histogram. Otherwise returns {false, _}.

new(Spec)

-spec new(prometheus_metric:spec()) -> ok.

Creates a histogram using Spec.

Raises:

{missing_metric_spec_key, Key, Spec} error if required Spec key is missing.
{invalid_metric_name, Name, Message} error if metric Name is invalid.
{invalid_metric_help, Help, Message} error if metric Help is invalid.
{invalid_metric_labels, Labels, Message} error if Labels isn't a list.
{invalid_label_name, Name, Message} error if Name isn't a valid label name.
{invalid_value_error, Value, Message} error if duration_unit is unknown or doesn't match metric name.
{mf_already_exists, {Registry, Name}, Message} error if a histogram with the same Spec already exists.

Histogram-specific errors:

Raises:

{no_buckets, Buckets} error if Buckets are missing, not a list, empty list or not known buckets spec.
{invalid_buckets, Buckets, Message} error if Buckets aren't in increasing order.
{invalid_bound, Bound} error if Bound isn't a number.

observe(Name, Value)

-spec observe(prometheus_metric:name(), number()) -> ok.

Equivalent to observe(default, Name, [], Value).

observe(Name, LabelValues, Value)

-spec observe(prometheus_metric:name(), prometheus_metric:labels(), number()) -> ok.

Equivalent to observe(default, Name, LabelValues, Value).

observe(Registry, Name, LabelValues, Value)

-spec observe(Registry, Name, LabelValues, Value) -> ok
                 when
                     Registry :: prometheus_registry:registry(),
                     Name :: prometheus_metric:name(),
                     LabelValues :: prometheus_metric:labels(),
                     Value :: number().

Observes the given Value.

Raises:

{invalid_value, Value, Message} if Value isn't a number.
{unknown_metric, Registry, Name} error if histogram with named Name can't be found in Registry.
{invalid_metric_arity, Present, Expected} error if labels count mismatch.

observe_duration(Name, Fun)

-spec observe_duration(prometheus_metric:name(), fun(() -> term())) -> term().

Equivalent to observe_duration(default, Name, [], Fun).

observe_duration(Name, LabelValues, Fun)

-spec observe_duration(prometheus_metric:name(), prometheus_metric:labels(), fun(() -> term())) ->
                          term().

Equivalent to observe_duration(default, Name, LabelValues, Fun).

observe_duration(Registry, Name, LabelValues, Fun)

-spec observe_duration(Registry, Name, LabelValues, Fun) -> any()
                          when
                              Registry :: prometheus_registry:registry(),
                              Name :: prometheus_metric:name(),
                              LabelValues :: prometheus_metric:labels(),
                              Fun :: fun(() -> any()).

Tracks the amount of time spent executing Fun.

Raises:

{unknown_metric, Registry, Name} error if histogram with named Name can't be found in Registry.
{invalid_metric_arity, Present, Expected} error if labels count mismatch.
{invalid_value, Value, Message} if Fun isn't a function.

observe_n(Name, Value, Count)

-spec observe_n(prometheus_metric:name(), number(), integer()) -> ok.

Equivalent to observe_n(default, Name, [], Value, Count).

observe_n(Name, LabelValues, Value, Count)

-spec observe_n(prometheus_metric:name(), prometheus_metric:labels(), number(), integer()) -> ok.

Equivalent to observe_n(default, Name, LabelValues, Value, Count).

observe_n(Registry, Name, LabelValues, Value, Count)

-spec observe_n(Registry, Name, LabelValues, Value, Count) -> ok
                   when
                       Registry :: prometheus_registry:registry(),
                       Name :: prometheus_metric:name(),
                       LabelValues :: prometheus_metric:labels(),
                       Value :: number(),
                       Count :: integer().

Observes the given Value, Count times.

Raises:

{invalid_value, Value, Message} if Value isn't a number.
{invalid_count, Count, Message} if Count isn't integer.
{unknown_metric, Registry, Name} error if histogram with named Name can't be found in Registry.
{invalid_metric_arity, Present, Expected} error if labels count mismatch.

pobserve(Registry, Name, LabelValues, Buckets, BucketPos, Value)

-spec pobserve(Registry, Name, LabelValues, Buckets, BucketPos, Value) -> ok
                  when
                      Registry :: prometheus_registry:registry(),
                      Name :: prometheus_metric:name(),
                      LabelValues :: prometheus_metric:labels(),
                      Buckets :: prometheus_buckets:buckets(),
                      BucketPos :: integer(),
                      Value :: number().

Observes the given Value, Count times, in the bucket position of the bucket list.

Useful when the bucket position is known in advance, as it avoids having to compute such value during the observation.

remove(Name)

-spec remove(prometheus_metric:name()) -> boolean().

Equivalent to remove(default, Name, []).

remove(Name, LabelValues)

-spec remove(prometheus_metric:name(), prometheus_metric:labels()) -> boolean().

Equivalent to remove(default, Name, LabelValues).

remove(Registry, Name, LabelValues)

-spec remove(prometheus_registry:registry(), prometheus_metric:name(), prometheus_metric:labels()) ->
                boolean().

Removes histogram series identified by Registry, Name and LabelValues.

Raises:

{unknown_metric, Registry, Name} error if histogram with name Name can't be found in Registry.
{invalid_metric_arity, Present, Expected} error if labels count mismatch.

reset(Name)

-spec reset(prometheus_metric:name()) -> boolean().

Equivalent to reset(default, Name, []).

reset(Name, LabelValues)

-spec reset(prometheus_metric:name(), prometheus_metric:labels()) -> boolean().

Equivalent to reset(default, Name, LabelValues).

reset(Registry, Name, LabelValues)

-spec reset(prometheus_registry:registry(), prometheus_metric:name(), prometheus_metric:labels()) ->
               boolean().

Resets the value of the histogram identified by Registry, Name and LabelValues.

Raises:

{unknown_metric, Registry, Name} error if histogram with name Name can't be found in Registry.
{invalid_metric_arity, Present, Expected} error if labels count mismatch.

value(Name)

-spec value(prometheus_metric:name()) -> {number(), infinity | number()} | undefined.

Equivalent to value(default, Name, []).

value(Name, LabelValues)

-spec value(prometheus_metric:name(), prometheus_metric:labels()) ->
               {number(), infinity | number()} | undefined.

Equivalent to value(default, Name, LabelValues).

value(Registry, Name, LabelValues)

-spec value(prometheus_registry:registry(), prometheus_metric:name(), prometheus_metric:labels()) ->
               {number(), infinity | number()} | undefined.

Returns the value of the histogram identified by Registry, Name and LabelValues. If there is no histogram for LabelValues, returns undefined.

If duration unit set, sum will be converted to the duration unit. Read more here.

Raises:

{unknown_metric, Registry, Name} error if histogram named Name can't be found in Registry.
{invalid_metric_arity, Present, Expected} error if labels count mismatch.

values(Registry, Name)

-spec values(prometheus_registry:registry(), prometheus_metric:name()) -> [{list(), number()}].