View Source prometheus_gauge (prometheus v5.0.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
Equivalent to inc(default, Name, [], -1)
.
If the second argument is a list, equivalent to inc(default, Name, LabelValues, -1) otherwise equivalent to inc(default, Name, [], -Value).
Equivalent to inc(default, Name, LabelValues, -Value)
.
Creates a gauge using Spec
. If a gauge with the same Spec
exists returns false
.
Equivalent to deregister(default, Name)
.
Removes all gauge series with name Name
and removes Metric Family from Registry
.
Equivalent to inc(default, Name, [], 1)
.
If the second argument is a list, equivalent to inc(default, Name, LabelValues, 1) otherwise equivalent to inc(default, Name, [], Value).
Increments the gauge identified by Registry
, Name
and LabelValues
by Value
.
Creates a gauge using Spec
.
Equivalent to remove(default, Name, [])
.
Equivalent to remove(default, Name, LabelValues)
.
Removes gauge series identified by Registry
, Name
and LabelValues
.
Equivalent to reset(default, Name, [])
.
Equivalent to reset(default, Name, LabelValues)
.
Resets the value of the gauge identified by Registry
, Name
and LabelValues
.
Equivalent to set(default, Name, [], Value)
.
Sets the gauge identified by Registry
, Name
and LabelValues
to Value
.
Equivalent to set_duration(default, Name, [], Fun)
.
Sets the gauge identified by Registry
, Name
and LabelValues
to the the amount of time
spent executing Fun
.
Equivalent to set_to_current_time(default, Name, [])
.
Equivalent to set_to_current_time(default, Name, LabelValues)
.
Sets the gauge identified by Registry
, Name
and LabelValues
to the current unixtime.
Equivalent to track_inprogress(default, Name, LabelValues, Fun)
.
Sets the gauge identified by Registry
, Name
and LabelValues
to the number of
currently executing Fun
s.
Equivalent to value(default, Name, [])
.
Equivalent to value(default, Name, LabelValues)
.
Returns the value of the gauge identified by Registry
, Name
and LabelValues
.
If there is no gauge for LabelValues
, returns undefined
.
Functions
-spec dec(prometheus_metric:name()) -> ok.
Equivalent to inc(default, Name, [], -1)
.
-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).
-spec dec(prometheus_metric:name(), prometheus_metric:labels(), number()) -> ok.
Equivalent to inc(default, 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)
.
-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 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 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, _}
.
-spec inc(prometheus_metric:name()) -> ok.
Equivalent to inc(default, Name, [], 1)
.
-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).
-spec inc(prometheus_metric:name(), prometheus_metric:labels(), non_neg_integer()) -> ok.
Equivalent to inc(default, 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}
ifValue
isn't an integer.{unknown_metric, Registry, Name}
error if gauge with namedName
can't be found inRegistry
.{invalid_metric_arity, Present, Expected}
error if labels count mismatch.
-spec new(prometheus_metric:spec()) -> ok.
Creates a gauge 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 gauge with the sameSpec
already exists.
-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 gauge series identified by Registry
, Name
and LabelValues
.
Raises:
{unknown_metric, Registry, Name}
error if gauge 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 gauge identified by Registry
, Name
and LabelValues
.
Raises:
{unknown_metric, Registry, Name}
error if gauge with nameName
can't be found inRegistry
.{invalid_metric_arity, Present, Expected}
error if labels count mismatch.
-spec set(prometheus_metric:name(), number()) -> ok.
Equivalent to set(default, Name, [], Value)
.
-spec set(prometheus_metric:name(), prometheus_metric:labels(), number()) -> ok.
Equivalent to set(default, 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}
ifValue
isn't a number orundefined
.{unknown_metric, Registry, Name}
error if gauge with namedName
can't be found inRegistry
.{invalid_metric_arity, Present, Expected}
error if labels count mismatch.
-spec set_duration(prometheus_metric:name(), fun(() -> any())) -> any().
Equivalent to set_duration(default, Name, [], Fun)
.
-spec set_duration(prometheus_metric:name(), prometheus_metric:labels(), fun(() -> any())) -> any().
Equivalent to set_duration(default, 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 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 set_to_current_time(prometheus_metric:name()) -> ok.
Equivalent to set_to_current_time(default, Name, [])
.
-spec set_to_current_time(prometheus_metric:name(), prometheus_metric:labels()) -> ok.
Equivalent to set_to_current_time(default, 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 namedName
can't be found inRegistry
.{invalid_metric_arity, Present, Expected}
error if labels count mismatch.
-spec track_inprogress(prometheus_metric:name(), fun(() -> any())) -> any().
Equivalent to track_inprogress(default, Name, [], Fun)
.
-spec track_inprogress(prometheus_metric:name(), prometheus_metric:labels(), fun(() -> any())) -> any().
Equivalent to track_inprogress(default, 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 Fun
s.
Raises:
{unknown_metric, Registry, Name}
error if gauge 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 value(prometheus_metric:name()) -> number() | undefined.
Equivalent to value(default, Name, [])
.
-spec value(prometheus_metric:name(), prometheus_metric:labels()) -> number() | undefined.
Equivalent to value(default, 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 namedName
can't be found inRegistry
.{invalid_metric_arity, Present, Expected}
error if labels count mismatch.
-spec values(prometheus_registry:registry(), prometheus_metric:name()) -> [{list(), infinity | number()}].