prometheus_summary (prometheus v6.0.1)

View Source

Summary metric, to track the size of events.

Example use cases for Summaries:

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

This keeps track of the number of events, and the sum of their values. This allows you to calculate the average value of each event, and with enough datapoints, to keep track of its average.

Example:

-module(my_proxy_instrumenter).

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

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

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

Summary

Functions

declare(Spec)

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

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, Fun)

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.

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:label_values(), 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:label_values(),
                     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(() -> dynamic())) -> dynamic().

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

observe_duration(Name, LabelValues, Fun)

-spec observe_duration(Name, LabelValues, Fun) -> dynamic()
                          when
                              Name :: prometheus_metric:name(),
                              LabelValues :: prometheus_metric:label_values(),
                              Fun :: fun(() -> dynamic()).

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

observe_duration(Registry, Name, LabelValues, Fun)

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

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:label_values()) -> boolean().

Equivalent to remove(default, Name, LabelValues).

remove(Registry, Name, LabelValues)

-spec remove(Registry, Name, LabelValues) -> boolean()
                when
                    Registry :: prometheus_registry:registry(),
                    Name :: prometheus_metric:name(),
                    LabelValues :: prometheus_metric:label_values().

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:label_values()) -> boolean().

Equivalent to reset(default, Name, LabelValues).

reset(Registry, Name, LabelValues)

-spec reset(Registry, Name, LabelValues) -> boolean()
               when
                   Registry :: prometheus_registry:registry(),
                   Name :: prometheus_metric:name(),
                   LabelValues :: prometheus_metric:label_values().

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:label_values()) ->
               {integer(), number()} | undefined.

Equivalent to value(default, Name, LabelValues).

value(Registry, Name, LabelValues)

-spec value(Registry, Name, LabelValues) -> {integer(), number()} | undefined
               when
                   Registry :: prometheus_registry:registry(),
                   Name :: prometheus_metric:name(),
                   LabelValues :: prometheus_metric:label_values().

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'()].