prometheus_quantile_summary.md

Module prometheus_quantile_summary

• Description
• Function Index
• Function Details

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

Behaviours: prometheus_collector, prometheus_metric.

Description

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"}

Function Index

declare/1	Creates a summary using Spec.
deregister/1	Equivalent to deregister(default, Name).
deregister/2	Removes all summary series with name Name and removes Metric Family from Registry.
new/1	Creates a summary using Spec.
observe/2	Equivalent to observe(default, Name, [], Value).
observe/3	Equivalent to observe(default, Name, LabelValues, Value).
observe/4	Observes the given Value.
observe_duration/2	Equivalent to observe_duration(default, Name, [], Fun).
observe_duration/3	Equivalent to observe_duration(default, Name, LabelValues, Fun).
observe_duration/4	Tracks the amount of time spent executing Fun.
remove/1	Equivalent to remove(default, Name, []).
remove/2	Equivalent to remove(default, Name, LabelValues).
remove/3	Removes summary series identified by Registry, Name and LabelValues.
reset/1	Equivalent to reset(default, Name, []).
reset/2	Equivalent to reset(default, Name, LabelValues).
reset/3	Resets the value of the summary identified by Registry, Name and LabelValues.
value/1	Equivalent to value(default, Name, []).
value/2	Equivalent to value(default, Name, LabelValues).
value/3	Returns the value of the summary identified by Registry, Name and LabelValues.
values/2

Function Details

declare/1

declare(Spec) -> any()

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 Soec key is missing.
Raises {invalid_metric_name, Name, Message} error if metric Name is invalid.
Raises {invalid_metric_help, Help, Message} error if metric Help is invalid.
Raises {invalid_metric_labels, Labels, Message} error if Labels isn't a list.
Raises {invalid_label_name, Name, Message} error if Name isn't a valid label name.
Raises {invalid_value_error, Value, MessagE} error if duration_unit is unknown or doesn't match metric name.

deregister/1

deregister(Name) -> any()

Equivalent to deregister(default, Name).

deregister/2

deregister(Registry, Name) -> any()

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/1

new(Spec) -> any()

Creates a summary using Spec.

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

observe/2

observe(Name, Value) -> any()

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

observe/3

observe(Name, LabelValues, Value) -> any()

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

observe/4

observe(Registry, Name, LabelValues, Value) -> any()

Observes the given Value.

Raises {invalid_value, Value, Message} if Value isn't an integer.
Raises {unknown_metric, Registry, Name} error if summary with named Name can't be found in Registry.
Raises {invalid_metric_arity, Present, Expected} error if labels count mismatch.

observe_duration/2

observe_duration(Name, Fun) -> any()

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

observe_duration/3

observe_duration(Name, LabelValues, Fun) -> any()

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

observe_duration/4

observe_duration(Registry, Name, LabelValues, Fun) -> any()

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.
Raises {invalid_metric_arity, Present, Expected} error if labels count mismatch. Raises {invalid_value, Value, Message} if Fun isn't a function.

remove/1

remove(Name) -> any()

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

remove/2

remove(Name, LabelValues) -> any()

Equivalent to remove(default, Name, LabelValues).

remove/3

remove(Registry, Name, LabelValues) -> any()

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.
Raises {invalid_metric_arity, Present, Expected} error if labels count mismatch.

reset/1

reset(Name) -> any()

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

reset/2

reset(Name, LabelValues) -> any()

Equivalent to reset(default, Name, LabelValues).

reset/3

reset(Registry, Name, LabelValues) -> any()

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.
Raises {invalid_metric_arity, Present, Expected} error if labels count mismatch.

value/1

value(Name) -> any()

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

value/2

value(Name, LabelValues) -> any()

Equivalent to value(default, Name, LabelValues).

value/3

value(Registry, Name, LabelValues) -> any()

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.
Raises {invalid_metric_arity, Present, Expected} error if labels count mismatch.

values/2

values(Registry, Name) -> any()