Prometheus.Metric.Gauge (Prometheus.ex v4.0.0)

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.

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

Summary

Functions

dec(spec, value \\ 1)

Decrements the gauge identified by spec by value.

declare(spec)

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

inc(spec, value \\ 1)

Increments the gauge identified by spec by value.

new(spec)

Creates a gauge using spec.

remove(spec)

Removes gauge series identified by spec.

reset(spec)

Resets the value of the gauge identified by spec.

set(spec, value)

Sets the gauge identified by spec to value.

set_duration(spec, body)

Tracks the amount of time spent executing body.

set_to_current_time(spec)

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

track_inprogress(spec, body)

Sets the gauge identified by spec to the number of currently executing bodys.

value(spec)

Returns the value of the gauge identified by spec.

Functions

dec(spec, value \\ 1)

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

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(spec, value \\ 1)

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

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

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

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(spec, value)

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(spec, body)

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

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(spec, body)

(macro)

Sets the gauge identified by spec to the number of currently executing bodys.

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

Returns the value of the gauge identified by spec.

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

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