View Source prometheus_quantile_summary (prometheus v5.0.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
Creates a summary using Spec
. If a summary with the same Spec
exists returns false
.
Equivalent to deregister(default, Name)
.
Removes all summary series with name Name
and removes Metric Family from Registry
.
Creates a summary using Spec
.
Equivalent to observe(default, Name, [], Value)
.
Observes the given Value
.
Equivalent to observe_duration(default, Name, LabelValues, Fun)
.
Tracks the amount of time spent executing Fun
.
Equivalent to remove(default, Name, [])
.
Equivalent to remove(default, Name, LabelValues)
.
Removes summary series identified by Registry
, Name
and LabelValues
.
Equivalent to reset(default, Name, [])
.
Equivalent to reset(default, Name, LabelValues)
.
Resets the value of the summary identified by Registry
, Name
and LabelValues
.
Equivalent to value(default, Name, [])
.
Equivalent to value(default, Name, LabelValues)
.
Returns the value of the summary identified by Registry
, Name
and LabelValues
.
If there is no summary for LabelValues
, returns undefined
.
Functions
-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 requiredSpec
key is missing.{invalid_metric_name, Name, Message}
error if metricName
is invalid.{invalid_metric_help, Help, Message}
error if metricHelp
is invalid.{invalid_metric_labels, Labels, Message}
error ifLabels
isn't a list.{invalid_label_name, Name, Message}
error ifName
isn't a valid label name.{invalid_value_error, Value, MessagE}
error ifduration_unit
is unknown or doesn't match metric name.
-spec deregister(prometheus_metric:name()) -> {boolean(), boolean()}.
Equivalent to deregister(default, 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, _}
.
-spec new(prometheus_metric:spec()) -> ok.
Creates a summary using Spec
.
Raises:
{missing_metric_spec_key, Key, Spec}
error if requiredSpec
key is missing.{invalid_metric_name, Name, Message}
error if metricName
is invalid.{invalid_metric_help, Help, Message}
error if metricHelp
is invalid.{invalid_metric_labels, Labels, Message}
error ifLabels
isn't a list.{invalid_label_name, Name, Message}
error ifName
isn't a valid label name.{invalid_value_error, Value, Message}
error ifduration_unit
is unknown or doesn't match metric name.{mf_already_exists, {Registry, Name}, Message}
error if a summary with the sameSpec
already exists.
-spec observe(prometheus_metric:name(), number()) -> ok.
Equivalent to observe(default, Name, [], Value)
.
-spec observe(prometheus_metric:name(), prometheus_metric:labels(), number()) -> ok.
Equivalent to observe(default, 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}
ifValue
isn't an integer.{unknown_metric, Registry, Name}
error if summary with namedName
can't be found inRegistry
.{invalid_metric_arity, Present, Expected}
error if labels count mismatch.
-spec observe_duration(prometheus_metric:name(), fun(() -> term())) -> term().
Equivalent to observe_duration(default, Name, [], Fun)
.
-spec observe_duration(prometheus_metric:name(), prometheus_metric:labels(), fun(() -> term())) -> term().
Equivalent to observe_duration(default, Name, LabelValues, Fun)
.
-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 namedName
can't be found inRegistry
.{invalid_metric_arity, Present, Expected}
error if labels count mismatch.{invalid_value, Value, Message}
ifFun
isn't a function.
-spec remove(prometheus_metric:name()) -> boolean().
Equivalent to remove(default, Name, [])
.
-spec remove(prometheus_metric:name(), prometheus_metric:labels()) -> boolean().
Equivalent to remove(default, 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 nameName
can't be found inRegistry
.{invalid_metric_arity, Present, Expected}
error if labels count mismatch.
-spec reset(prometheus_metric:name()) -> boolean().
Equivalent to reset(default, Name, [])
.
-spec reset(prometheus_metric:name(), prometheus_metric:labels()) -> boolean().
Equivalent to reset(default, 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 nameName
can't be found inRegistry
.{invalid_metric_arity, Present, Expected}
error if labels count mismatch.
-spec value(prometheus_metric:name()) -> {integer(), number()} | undefined.
Equivalent to value(default, Name, [])
.
-spec value(prometheus_metric:name(), prometheus_metric:labels()) -> {integer(), number()} | undefined.
Equivalent to value(default, 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 namedName
can't be found inRegistry
.{invalid_metric_arity, Present, Expected}
error if labels count mismatch.
-spec values(prometheus_registry:registry(), prometheus_metric:name()) -> [prometheus_model:'Summary'()].