prometheus_gauge (prometheus v5.1.1)

View Source

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

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

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

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

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.

Removes gauge series identified by Registry, Name and LabelValues.

Resets the value of the gauge identified by Registry, Name and LabelValues.

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

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

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

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

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

Functions

dec(Name)

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

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)

-spec dec(Registry, Name, LabelValues, Value) -> ok
             when
                 Registry :: prometheus_registry:registry(),
                 Name :: prometheus_metric:name(),
                 LabelValues :: prometheus_metric:label_values(),
                 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)

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

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)

-spec inc(Registry, Name, LabelValues, Value) -> ok
             when
                 Registry :: prometheus_registry:registry(),
                 Name :: prometheus_metric:name(),
                 LabelValues :: prometheus_metric:label_values(),
                 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)

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

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

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

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

set_duration(Name, LabelValues, Fun)

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

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

set_duration(Registry, Name, LabelValues, Fun)

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

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

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

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

track_inprogress(Name, LabelValues, Fun)

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

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

track_inprogress(Registry, Name, LabelValues, Fun)

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

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

Equivalent to value(default, Name, LabelValues).

value(Registry, Name, LabelValues)

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

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