Prometheus.ex v1.0.0-alpha4 Prometheus.Metric.Gauge

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:

  • Inprogress 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

end

Summary

Macros

Decrements the gauge identified by spec by value. If value happened to be a float number even one time(!) you shouldn’t use inc/2 or dec/2 after ddec

Decrements the gauge identified by spec by value

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

Increments the gauge identified by spec by value. If value happened to be a float number even one time(!) you shouldn’t use inc/2 or dec/2 after dinc

Increments the gauge identified by spec by value

Creates a gauge using spec

Removes gauge series identified by spec

Resets the value of the gauge identified by spec

Sets the gauge identified by spec to value

Tracks the amount of seconds spent executing fun

Sets the gauge identified by spec to the current unixtime

Tracks inprogress functions

Returns the value of the gauge identified by spec

Macros

ddec(spec, value \\ 1)

Decrements the gauge identified by spec by value. If value happened to be a float number even one time(!) you shouldn’t use inc/2 or dec/2 after ddec.

Raises Prometheus.Error.InvalidValue exception if value isn’t a number.
Raises Prometheus.Error.UnknownMetric exception if a counter for spec can’t be found.
Raises Prometheus.Error.InvalidMetricArity exception if labels count mismatch.

dec(spec, value \\ 1)

Decrements the gauge identified by spec by value.

Raises Prometheus.Error.InvalidValue exception if value isn’t an integer.
Raises Prometheus.Error.UnknownMetric exception if a counter for spec can’t be found.
Raises Prometheus.Error.InvalidMetricArity exception if labels count mismatch.

declare(spec)

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

Raises Prometheus.Error.MissingMetricSpecKey if required spec key is missing.
Raises Prometheus.Error.InvalidMetricName if metric name is invalid.
Raises Prometheus.Error.InvalidMetricHelp if help is invalid.
Raises Prometheus.Error.InvalidMetricLabels if labels isn’t a list.
Raises Prometheus.Error.InvalidMetricName if label name is invalid.

dinc(spec, value \\ 1)

Increments the gauge identified by spec by value. If value happened to be a float number even one time(!) you shouldn’t use inc/2 or dec/2 after dinc.

Raises Prometheus.Error.InvalidValue exception if value isn’t a number.
Raises Prometheus.Error.UnknownMetric exception if a counter for spec can’t be found.
Raises Prometheus.Error.InvalidMetricArity exception if labels count mismatch.

inc(spec, value \\ 1)

Increments the gauge identified by spec by value.

Raises Prometheus.Error.InvalidValue exception if value isn’t an integer.
Raises Prometheus.Error.UnknownMetric exception if a counter for spec can’t be found.
Raises Prometheus.Error.InvalidMetricArity exception if labels count mismatch.

new(spec)

Creates a gauge using spec.

Raises Prometheus.Error.MissingMetricSpecKey if required spec key is missing.
Raises Prometheus.Error.InvalidMetricName if metric name is invalid.
Raises Prometheus.Error.InvalidMetricHelp if help is invalid.
Raises Prometheus.Error.InvalidMetricLabels if labels isn’t a list.
Raises Prometheus.Error.InvalidMetricName if label name is invalid.
Raises Prometheus.Error.MFAlreadyExists if a gauge with the same spec exists.

remove(spec)

Removes gauge series identified by spec.

Raises Prometheus.Error.UnknownMetric exception if a gauge for spec can’t be found.
Raises Prometheus.Error.InvalidMetricArity exception if labels count mismatch.

reset(spec)

Resets the value of the gauge identified by spec.

Raises Prometheus.Error.UnknownMetric exception if a gauge for spec can’t be found.
Raises Prometheus.Error.InvalidMetricArity exception if labels count mismatch.

set(spec, value)

Sets the gauge identified by spec to value.

Raises Prometheus.Error.InvalidValue exception if value isn’t a number.
Raises Prometheus.Error.UnknownMetric exception if a gauge for spec can’t be found.
Raises Prometheus.Error.InvalidMetricArity exception if labels count mismatch.

set_duration(spec, fun)

Tracks the amount of seconds spent executing fun.

Raises Prometheus.Error.UnknownMetric exception if a gauge for spec can’t be found.
Raises Prometheus.Error.InvalidMetricArity exception if labels count mismatch.

set_to_current_time(spec)

Sets the gauge identified by spec to the current unixtime.

Raises Prometheus.Error.UnknownMetric exception if a gauge for spec can’t be found.
Raises Prometheus.Error.InvalidMetricArity exception if labels count mismatch.

track_inprogress(spec, fun)

Tracks inprogress functions.

Raises Prometheus.Error.UnknownMetric exception if a gauge for spec can’t be found.
Raises Prometheus.Error.InvalidMetricArity exception if labels count mismatch.

value(spec)

Returns the value of the gauge identified by spec.

Raises Prometheus.Error.UnknownMetric exception if a gauge for spec can’t be found.
Raises Prometheus.Error.InvalidMetricArity exception if labels count mismatch.