Gauge metric, to report instantaneous values.
Behaviours: prometheus_collector, prometheus_metric.
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.
Example use cases for Gauges:
-
Inprogress 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)..| dec/1 | 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, [], -1 * Value). |
| dec/3 | Equivalent to inc(default, Name, LabelValues, -1 * Value). |
| dec/4 | Equivalent to inc(Registry, Name, LabelValues, -1 * Value). |
| declare/1 | Creates a gauge using Spec. |
| deregister/1 | Equivalent to deregister(default, Name). |
| deregister/2 |
Removes all gauge series with name Name and
removes Metric Family from Registry. |
| inc/1 | 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/3 | Equivalent to inc(default, Name, LabelValues, Value). |
| inc/4 | Increments the gauge identified by Registry, Name
and LabelValues by Value. |
| new/1 | Creates a gauge using Spec. |
| remove/1 | Equivalent to remove(default, Name, []). |
| remove/2 | Equivalent to remove(default, Name, LabelValues). |
| remove/3 | Removes gauge 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 gauge identified by Registry, Name
and LabelValues. |
| set/2 | Equivalent to set(default, Name, [], Value). |
| set/3 | Equivalent to set(default, Name, LabelValues, Value). |
| set/4 | Sets the gauge identified by Registry, Name
and LabelValues to Value. |
| set_duration/2 | Equivalent to set_duration(default, Name, [], Fun). |
| set_duration/3 | Equivalent to set_duration(default, Name, LabelValues, Fun). |
| set_duration/4 | Sets the gauge identified by Registry, Name
and LabelValues to the the amount of time spent executing Fun. |
| set_to_current_time/1 | Equivalent to set_to_current_time(default, Name, []). |
| set_to_current_time/2 | Equivalent to set_to_current_time(default, Name, LabelValues). |
| set_to_current_time/3 | Sets the gauge identified by Registry, Name
and LabelValues to the current unixtime. |
| track_inprogress/2 | Equivalent to track_inprogress(default, Name, [], Fun). |
| track_inprogress/3 | Equivalent to track_inprogress(default, Name, LabelValues, Fun). |
| track_inprogress/4 | Sets the gauge identified by Registry, Name
and LabelValues to the number of currently executing Funs. |
| value/1 | Equivalent to value(default, Name, []). |
| value/2 | Equivalent to value(default, Name, LabelValues). |
| value/3 | Returns the value of the gauge identified by Registry, Name
and LabelValues. |
| values/2 |
dec(Name) -> any()
Equivalent to inc(default, Name, [], -1).
dec(Name, LabelValues) -> any()
If the second argument is a list, equivalent to
inc(default, Name, LabelValues, -1)
otherwise equivalent to
inc(default, Name, [], -1 * Value).
dec(Name, LabelValues, Value) -> any()
Equivalent to inc(default, Name, LabelValues, -1 * Value).
dec(Registry, Name, LabelValues, Value) -> any()
Equivalent to inc(Registry, Name, LabelValues, -1 * Value).
declare(Spec) -> any()
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.
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(Name) -> any()
Equivalent to deregister(default, Name).
deregister(Registry, Name) -> any()
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) -> any()
Equivalent to inc(default, Name, [], 1).
inc(Name, LabelValues) -> any()
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) -> any()
Equivalent to inc(default, Name, LabelValues, Value).
inc(Registry, Name, LabelValues, Value) -> any()
Increments the gauge identified by Registry, Name
and LabelValues by Value.
Raises {invalid_value, Value, Message} if Value
isn't an integer.
Raises {unknown_metric, Registry, Name} error if gauge with named Name
can't be found in Registry.
Raises {invalid_metric_arity, Present, Expected} error if labels count
mismatch.
new(Spec) -> any()
Creates a gauge using Spec.
Raises {missing_metric_spec_key, Key, Spec} error if required Spec 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 gauge
with the same Spec already exists.
remove(Name) -> any()
Equivalent to remove(default, Name, []).
remove(Name, LabelValues) -> any()
Equivalent to remove(default, Name, LabelValues).
remove(Registry, Name, LabelValues) -> any()
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.
Raises {invalid_metric_arity, Present, Expected} error if labels count
mismatch.
reset(Name) -> any()
Equivalent to reset(default, Name, []).
reset(Name, LabelValues) -> any()
Equivalent to reset(default, Name, LabelValues).
reset(Registry, Name, LabelValues) -> any()
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.
Raises {invalid_metric_arity, Present, Expected} error if labels count
mismatch.
set(Name, Value) -> any()
Equivalent to set(default, Name, [], Value).
set(Name, LabelValues, Value) -> any()
Equivalent to set(default, Name, LabelValues, Value).
set(Registry, Name, LabelValues, Value) -> any()
Sets the gauge identified by Registry, Name
and LabelValues to Value.
Raises {invalid_value, Value, Message} if Value
isn't a number or undefined.
Raises {unknown_metric, Registry, Name} error if gauge with named Name
can't be found in Registry.
Raises {invalid_metric_arity, Present, Expected} error if labels count
mismatch.
set_duration(Name, Fun) -> any()
Equivalent to set_duration(default, Name, [], Fun).
set_duration(Name, LabelValues, Fun) -> any()
Equivalent to set_duration(default, Name, LabelValues, Fun).
set_duration(Registry, Name, LabelValues, 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.
Raises {invalid_metric_arity, Present, Expected} error if labels count
mismatch.
Raises {invalid_value, Value, Message} if Fun
isn't a function.
set_to_current_time(Name) -> any()
Equivalent to set_to_current_time(default, Name, []).
set_to_current_time(Name, LabelValues) -> any()
Equivalent to set_to_current_time(default, Name, LabelValues).
set_to_current_time(Registry, Name, LabelValues) -> any()
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.
Raises {invalid_metric_arity, Present, Expected} error if labels count
mismatch.
track_inprogress(Name, Fun) -> any()
Equivalent to track_inprogress(default, Name, [], Fun).
track_inprogress(Name, LabelValues, Fun) -> any()
Equivalent to track_inprogress(default, Name, LabelValues, Fun).
track_inprogress(Registry, Name, LabelValues, 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.
Raises {invalid_metric_arity, Present, Expected} error if labels count
mismatch.
Raises {invalid_value, Value, Message} if Fun
isn't a function.
value(Name) -> any()
Equivalent to value(default, Name, []).
value(Name, LabelValues) -> any()
Equivalent to value(default, Name, LabelValues).
value(Registry, Name, LabelValues) -> any()
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.
Raises {invalid_metric_arity, Present, Expected} error if labels count
mismatch.
values(Registry, Name) -> any()