Prometheus.ex v3.0.5 Prometheus.Metric.Counter View Source

Counter is a Metric that represents a single numerical value that only ever goes up. That implies that it cannot be used to count items whose number can also go down, e.g. the number of currently running processes. Those "counters" are represented by Prometheus.Metric.Gauge.

A Counter is typically used to count requests served, tasks completed, errors occurred, etc.

Example use cases for Counters:

Number of requests processed;
Number of items that were inserted into a queue;
Total amount of data that a system has processed.

Use the rate()/ irate() functions in Prometheus to calculate the rate of increase of a Counter. By convention, the names of Counters are suffixed by _total.

To create a counter use either new/1 or declare/1, the difference is that new/ will raise Prometheus.MFAlreadyExistsError exception if counter with the same registry, name and labels combination already exists. Both accept spec Keyword with the same set of keys:

:registry - optional, default is :default;
:name - required, can be an atom or a string;
:help - required, must be a string;
:labels - optional, default is [].

Example:

defmodule MyServiceInstrumenter do

  use Prometheus.Metric

  ## to be called at app/supervisor startup.
  ## to tolerate restarts use declare.
  def setup() do
    Counter.declare([name: :my_service_requests_total,
                     help: "Requests count.",
                     labels: [:caller]])
  end

  def inc(caller) do
    Counter.inc([name: :my_service_requests_total,
                labels: [caller]])
  end

end

Link to this section Summary

Functions

count(spec, body)

Increments the counter identified by spec by 1 when body executed

count_exceptions(spec, exception \\ :_, body)

Increments the counter identified by spec by 1 when body raises exception

count_no_exceptions(spec, body)

Increments the counter identified by spec by 1 when body raises no exceptions

declare(spec)

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

inc(spec, value \\ 1)

Increments the counter identified by spec by value

new(spec)

Creates a counter using spec

remove(spec)

Removes counter series identified by spec

reset(spec)

Resets the value of the counter identified by spec

value(spec)

Returns the value of the counter identified by spec. If there is no counter for given labels combination, returns :undefined

Link to this section Functions

count(spec, body) View Source (macro)

Increments the counter identified by spec by 1 when body executed.

Read more about bodies: Prometheus.Injector.

Raises Prometheus.UnknownMetricError exception if a counter for spec can't be found.
Raises Prometheus.InvalidMetricArityError exception if labels count mismatch.

count_exceptions(spec, exception \\ :_, body) View Source (macro)

Increments the counter identified by spec by 1 when body raises exception.

Read more about bodies: Prometheus.Injector.

Raises Prometheus.UnknownMetricError exception if a counter for spec can't be found.
Raises Prometheus.InvalidMetricArityError exception if labels count mismatch.

count_no_exceptions(spec, body) View Source (macro)

Increments the counter identified by spec by 1 when body raises no exceptions.

Read more about bodies: Prometheus.Injector.

Raises Prometheus.UnknownMetricError exception if a counter for spec can't be found.
Raises Prometheus.InvalidMetricArityError exception if labels count mismatch.

declare(spec) View Source

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

Raises Prometheus.MissingMetricSpecKeyError if required spec key is missing.
Raises Prometheus.InvalidMetricNameError if metric name is invalid.
Raises Prometheus.InvalidMetricHelpError if help is invalid.
Raises Prometheus.InvalidMetricLabelsError if labels isn't a list.
Raises Prometheus.InvalidLabelNameError if label name is invalid.

inc(spec, value \\ 1) View Source

Increments the counter identified by spec by value.

Raises Prometheus.InvalidValueError exception if value isn't a positive number.
Raises Prometheus.UnknownMetricError exception if a counter for spec can't be found.
Raises Prometheus.InvalidMetricArityError exception if labels count mismatch.

new(spec) View Source

Creates a counter using spec.

remove(spec) View Source

Removes counter series identified by spec.

Raises Prometheus.UnknownMetricError exception if a counter for spec can't be found.
Raises Prometheus.InvalidMetricArityError exception if labels count mismatch.

reset(spec) View Source

Resets the value of the counter identified by spec.

Raises Prometheus.UnknownMetricError exception if a counter for spec can't be found.
Raises Prometheus.InvalidMetricArityError exception if labels count mismatch.

value(spec) View Source

Returns the value of the counter identified by spec. If there is no counter for given labels combination, returns :undefined.

Raises Prometheus.UnknownMetricError exception if a counter for spec can't be found.
Raises Prometheus.InvalidMetricArityError exception if labels count mismatch.