# `Prometheus.Metric.Gauge`
[🔗](https://github.com/prometheus-erl/prometheus.ex/blob/v5.1.0/lib/prometheus/metric/gauge.ex#L1)

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.

Example use cases for Gauges:
  - In progress requests;
  - Number of items in a queue;
  - Free memory;
  - Total memory;
  - Temperature.

Example:

```
defmodule MyPoolInstrumenter do

  use Prometheus.Metric

  ## to be called at app/supervisor startup.
  ## to tolerate restarts use declare.
  def setup() do
    Gauge.declare([name: :my_pool_size,
                   help: "Pool size."])

    Gauge.declare([name: :my_pool_checked_out,
                   help: "Number of sockets checked out from the pool"])
  end

  def set_size(size) do
    Gauge.set([name: :my_pool_size], size)
  end

  def track_checked_out_sockets(checkout_fun) do
    Gauge.track_inprogress([name: :my_pool_checked_out], checkout_fun.())
  end

  def track_checked_out_sockets_block(socket) do
    Gauge.track_inprogress([name: :my_pool_checked_out]) do
      # checkout code
      socket
    end
  end

end

```

# `dec`

Decrements the gauge identified by `spec` by `value`.

Raises `Prometheus.InvalidValueError` exception if `value` isn't a number.<br>
Raises `Prometheus.UnknownMetricError` exception if a gauge for `spec`
can't be found.<br>
Raises `Prometheus.InvalidMetricArityError` exception if labels count mismatch.

# `declare`

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

Raises `Prometheus.MissingMetricSpecKeyError` if required `spec` key is missing.<br>
Raises `Prometheus.InvalidMetricNameError` if metric name is invalid.<br>
Raises `Prometheus.InvalidMetricHelpError` if help is invalid.<br>
Raises `Prometheus.InvalidMetricLabelsError` if labels isn't a list.<br>
Raises `Prometheus.InvalidMetricNameError` if label name is invalid.<br>
Raises `Prometheus.InvalidValueError` exception if duration_unit is unknown or
doesn't match metric name.

# `inc`

Increments the gauge identified by `spec` by `value`.

Raises `Prometheus.InvalidValueError` exception if `value` isn't a number.<br>
Raises `Prometheus.UnknownMetricError` exception if a gauge for `spec`
can't be found.<br>
Raises `Prometheus.InvalidMetricArityError` exception if labels count mismatch.

# `new`

Creates a gauge using `spec`.

Raises `Prometheus.MissingMetricSpecKeyError` if required `spec` key is missing.<br>
Raises `Prometheus.InvalidMetricNameError` if metric name is invalid.<br>
Raises `Prometheus.InvalidMetricHelpError` if help is invalid.<br>
Raises `Prometheus.InvalidMetricLabelsError` if labels isn't a list.<br>
Raises `Prometheus.InvalidMetricNameError` if label name is invalid.<br>
Raises `Prometheus.InvalidValueError` exception if duration_unit is unknown or
doesn't match metric name.<br>
Raises `Prometheus.MFAlreadyExistsError` if a gauge with the same `spec` exists.

# `remove`

Removes gauge series identified by spec.

Raises `Prometheus.UnknownMetricError` exception if a gauge
for `spec` can't be found.<br>
Raises `Prometheus.InvalidMetricArityError` exception if labels count mismatch.

# `reset`

Resets the value of the gauge identified by `spec`.

Raises `Prometheus.UnknownMetricError` exception if a gauge
for `spec` can't be found.<br>
Raises `Prometheus.InvalidMetricArityError` exception if labels count mismatch.

# `set`

Sets the gauge identified by `spec` to `value`.

Raises `Prometheus.InvalidValueError` exception if `value` isn't
a number or `:undefined`.<br>
Raises `Prometheus.UnknownMetricError` exception if a gauge for `spec`
can't be found.<br>
Raises `Prometheus.InvalidMetricArityError` exception if labels count mismatch.

# `set_duration`
*macro* 

Tracks the amount of time spent executing `body`.

Raises `Prometheus.UnknownMetricError` exception if a gauge
for `spec` can't be found.<br>
Raises `Prometheus.InvalidMetricArityError` exception if labels count mismatch.
Raises `Prometheus.InvalidValueError` exception if `fun` isn't a function or block.

# `set_to_current_time`

Sets the gauge identified by `spec` to the current unix time.

Raises `Prometheus.UnknownMetricError` exception if a gauge
for `spec` can't be found.<br>
Raises `Prometheus.InvalidMetricArityError` exception if labels count mismatch.

# `track_inprogress`
*macro* 

Sets the gauge identified by `spec` to the number of currently executing `body`s.

Raises `Prometheus.UnknownMetricError` exception if a gauge
for `spec` can't be found.<br>
Raises `Prometheus.InvalidMetricArityError` exception if labels count mismatch.
Raises `Prometheus.InvalidValueError` exception if fun isn't a function or block.

# `value`

Returns the value of the gauge identified by `spec`.

If duration unit set, value will be converted to the duration unit.
[Read more here.](time.html)

Raises `Prometheus.UnknownMetricError` exception if a gauge
for `spec` can't be found.<br>
Raises `Prometheus.InvalidMetricArityError` exception if labels count mismatch.

---

*Consult [api-reference.md](api-reference.md) for complete listing*