View Source prometheus_gauge (prometheus v4.13.0)

Gauge metric, to report instantaneous values.

Gauge is a metric that represents a single numerical value that can arbitrarily go up and down.

A Gauge is typically used for measured values like temperatures or current memory usage, but also \"counts\" that can go up and down, like the number of running processes.

It can take the value of undefined when the value is not known. In that case, increments and decrements will not be possible and explicitly setting to a new value will be necessary.

Example use cases for Gauges:

In-progress requests
Number of items in a queue
Free memory
Total memory
Temperature

Example:

-module(my_pool_instrumenter).

-export([setup/0, set_size/1]).

setup() ->
    prometheus_gauge:declare([{name, my_pool_size},
                              {help, \"Pool size.\"}]),
    prometheus_gauge:declare([{name, my_pool_checked_out},
                              {help, \"Number of checked out sockets\"}]).

set_size(Size) ->
    prometheus_gauge:set(my_pool_size, Size)

track_checked_out_sockets(CheckoutFun) ->
    prometheus_gauge:track_inprogress(my_pool_checked_out, CheckoutFun)..

Summary

Functions

dec(Name)

Equivalent to inc(default, Name, [], -1).

dec/2

If the second argument is a list, equivalent to inc(default, Name, LabelValues, -1) otherwise equivalent to inc(default, Name, [], -Value).

dec/3

Equivalent to inc(default, Name, LabelValues, -Value).

dec(Registry, Name, LabelValues, Value)

Equivalent to inc(Registry, Name, LabelValues, -Value).

declare(Spec)

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

deregister(Name)

Equivalent to deregister(default, Name).

deregister(Registry, Name)

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

inc(Name)

Equivalent to inc(default, Name, [], 1).

inc/2

If the second argument is a list, equivalent to inc(default, Name, LabelValues, 1) otherwise equivalent to inc(default, Name, [], Value).

inc(Name, LabelValues, Value)

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

inc(Registry, Name, LabelValues, Value)

Increments the gauge identified by Registry, Name and LabelValues by Value.

new(Spec)

Creates a gauge using Spec.

remove(Name)

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

remove(Name, LabelValues)

Equivalent to remove(default, Name, LabelValues).

remove(Registry, Name, LabelValues)

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

set(Name, Value)

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

set(Name, LabelValues, Value)

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

set(Registry, Name, LabelValues, Value)

Sets the gauge identified by Registry, Name and LabelValues to Value.

set_duration(Name, Fun)

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

set_duration(Name, LabelValues, Fun)

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

set_duration(Registry, Name, LabelValues, Fun)

Sets the gauge identified by Registry, Name and LabelValues to the the amount of time spent executing Fun.

set_to_current_time(Name)

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

set_to_current_time(Name, LabelValues)

Equivalent to set_to_current_time(default, Name, LabelValues).

set_to_current_time(Registry, Name, LabelValues)

Sets the gauge identified by Registry, Name and LabelValues to the current unixtime.

track_inprogress(Name, Fun)

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

track_inprogress(Name, LabelValues, Fun)

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

track_inprogress(Registry, Name, LabelValues, Fun)

Sets the gauge identified by Registry, Name and LabelValues to the number of currently executing Funs.

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

values(Registry, Name)

Functions

dec(Name)

-spec dec(prometheus_metric:name()) -> ok.

Equivalent to inc(default, Name, [], -1).

dec/2

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

If the second argument is a list, equivalent to inc(default, Name, LabelValues, -1) otherwise equivalent to inc(default, Name, [], -Value).

dec/3

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

Equivalent to inc(default, Name, LabelValues, -Value).

dec(Registry, Name, LabelValues, Value)

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

Equivalent to inc(Registry, Name, LabelValues, -Value).

declare(Spec)

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

Creates a gauge using Spec. If a gauge 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 gauge 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 gauge. Otherwise returns {false, _}.

inc(Name)

-spec inc(prometheus_metric:name()) -> ok.

Equivalent to inc(default, Name, [], 1).

inc/2

-spec inc(prometheus_metric:name(), prometheus_metric:labels() | non_neg_integer()) -> ok.

If the second argument is a list, equivalent to inc(default, Name, LabelValues, 1) otherwise equivalent to inc(default, Name, [], Value).

inc(Name, LabelValues, Value)

-spec inc(prometheus_metric:name(), prometheus_metric:labels(), non_neg_integer()) -> ok.

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

inc(Registry, Name, LabelValues, Value)

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

Increments the gauge identified by Registry, Name and LabelValues by Value.

Raises:

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

new(Spec)

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

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

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

Raises:

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

Raises:

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

set(Name, Value)

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

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

set(Name, LabelValues, Value)

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

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

set(Registry, Name, LabelValues, Value)

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

Sets the gauge identified by Registry, Name and LabelValues to Value.

Raises:

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

set_duration(Name, Fun)

-spec set_duration(prometheus_metric:name(), fun(() -> any())) -> any().

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

set_duration(Name, LabelValues, Fun)

-spec set_duration(prometheus_metric:name(), prometheus_metric:labels(), fun(() -> any())) -> any().

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

set_duration(Registry, Name, LabelValues, Fun)

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

Sets the gauge identified by Registry, Name and LabelValues to the the amount of time spent executing Fun.

Raises:

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

set_to_current_time(Name)

-spec set_to_current_time(prometheus_metric:name()) -> ok.

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

set_to_current_time(Name, LabelValues)

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

Equivalent to set_to_current_time(default, Name, LabelValues).

set_to_current_time(Registry, Name, LabelValues)

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

Sets the gauge identified by Registry, Name and LabelValues to the current unixtime.

Raises:

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

track_inprogress(Name, Fun)

-spec track_inprogress(prometheus_metric:name(), fun(() -> any())) -> any().

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

track_inprogress(Name, LabelValues, Fun)

-spec track_inprogress(prometheus_metric:name(), prometheus_metric:labels(), fun(() -> any())) -> any().

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

track_inprogress(Registry, Name, LabelValues, Fun)

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

Sets the gauge identified by Registry, Name and LabelValues to the number of currently executing Funs.

Raises:

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

value(Name)

-spec value(prometheus_metric:name()) -> number() | undefined.

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

value(Name, LabelValues)

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

Equivalent to value(default, Name, LabelValues).

value(Registry, Name, LabelValues)

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

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

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

Raises:

{unknown_metric, Registry, Name} error if gauge 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(), infinity | number()}].