View Source prometheus_quantile_summary (prometheus v4.13.0)

Summary metric, to track the size of events and report quantiles Based on prometheus_summary

Example use cases for Summaries:

  • Response latency;
  • Request size;
  • Response size.

Example:

-module(my_proxy_instrumenter).

setup() ->
    prometheus_quantile_summary:declare([{name, request_size_bytes},
                                         {help, \"Request size in bytes.\"}]),
    prometheus_quantile_summary:declare([{name, response_size_bytes},
                                         {help, \"Response size in bytes.\"}]).

observe_request(Size) ->
    prometheus_quantile_summary:observe(request_size_bytes, Size).

observe_response(Size) ->
    prometheus_quantile_summary:observe(response_size_bytes, Size).

Reports:

request_size_bytes_size
request_size_bytes_count
request_size_bytes\{quantile=\"0.5\"\}
request_size_bytes\{quantile=\"0.9\"\}
request_size_bytes\{quantile=\"0.95\"\}

Configuration

The specs cannot have a key called quantile, as this key is reserved by the implementation.

Passing targets, the quantile estimator can be fine-tuned, as in quantile_estimator:f_targeted/1. See default_targets/0 for the default values.

Passing compress_limit we can configure how often to run compressions into the quantile summary algorithm.

Notes

The underlying algorithm implemented in quantile_estimator does not support mergeability of summaries, therefore a summary in this implementation is linear, that is, all updates happen on the same ets record. Because of this, race conditions can imply datapoint loss. Statistically, this might not be relevant, but such impact is not ensured.

Because of this, support for quantile summaries is rather experimental and histograms are recommended instead.

Summary

Functions

declare(Spec)

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

default_targets()
deregister(Name)

Equivalent to deregister(default, Name).

deregister(Registry, Name)

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

new(Spec)

Creates a summary 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, Value)

Tracks the amount of time spent executing Fun.

remove(Name)

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

remove(Name, LabelValues)

Equivalent to remove(default, Name, LabelValues).

remove(Registry, Name, LabelValues)

Removes summary 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 summary 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 summary identified by Registry, Name and LabelValues. If there is no summary for LabelValues, returns undefined.

values(Registry, Name)

Functions

declare(Spec)

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

Creates a summary using Spec. If a summary 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.

default_targets()

-spec default_targets() -> [{float(), float()}].

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 summary 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 summary. Otherwise returns {false, _}.

new(Spec)

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

Creates a summary 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 summary with the same Spec already exists.

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 an integer.
  • {unknown_metric, Registry, Name} error if summary 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, Value)

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

Tracks the amount of time spent executing Fun.

Raises:

  • {unknown_metric, Registry, Name} error if summary 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.

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 summary series identified by Registry, Name and LabelValues.

Raises:

  • {unknown_metric, Registry, Name} error if summary 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 summary identified by Registry, Name and LabelValues.

Raises:

  • {unknown_metric, Registry, Name} error if summary 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()) -> {integer(), number()} | undefined.

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

value(Name, LabelValues)

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

Equivalent to value(default, Name, LabelValues).

value(Registry, Name, LabelValues)

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

Returns the value of the summary identified by Registry, Name and LabelValues. If there is no summary 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 summary 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()) -> [prometheus_model:'Summary'()].