View Source prometheus_counter (prometheus v4.13.0)

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_gauge.

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

Examople use cases for Counters:

Number of requests processed
Number of items that were inserted into a queue
Total amount of data 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/1 will raise {mf_already_exists, {Registry, Name}, Message} error if counter with the same Registry, Name and Labels combination already exists. Both accept Spec proplists:proplist/0 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:

-module(my_service_instrumenter).

-export([setup/0, inc/1]).

setup() ->
    prometheus_counter:declare([{name, my_service_requests_total},
                                {help, \"Requests count\"},
                                {labels, caller}]).

inc(Caller) ->
    prometheus_counter:inc(my_service_requests_total, [Caller]).

Summary

Functions

declare(Spec)

Creates a counter using Spec, if a counter with the same Spec exists returns false.

deregister(Name)

Equivalent to deregister(default, Name).

deregister(Registry, Name)

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

inc(Name)

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)

Increments the counter identified by Registry, Name and LabelValues by Value.

new(Spec)

Creates a counter using Spec.

remove(Name)

Equivalent to remove(default, Name, []).

remove(Name, LabelValues)

Equivalent to remove(default, Name, LabelValues).

remove(Registry, Name, LabelValues)

Removes counter series identified by Registry, Name and LabelValues.

reset(Name)

Equivalent to reset(default, Name, []).

reset(Name, LabelValues)

Equivalent to reset(default, Name, LabelValues).

reset(Registry, Name, LabelValues)

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

value(Name)

Equivalent to value(default, Name, []).

value(Name, LabelValues)

Equivalent to value(default, Name, LabelValues).

value(Registry, Name, LabelValues)

Returns the value of the counter identified by Registry, Name and LabelValues.

values(Registry, Name)

Functions

declare(Spec)

-spec declare(prometheus_metric:spec()) -> boolean().

Creates a counter using Spec, if a counter 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.

deregister(Name)

-spec deregister(prometheus_metric:name()) -> {boolean(), boolean()}.

Equivalent to deregister(default, Name).

deregister(Registry, Name)

-spec deregister(prometheus_registry:registry(), prometheus_metric:name()) -> {boolean(), boolean()}.

Removes all counter 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 counter. Otherwise returns {true, _}.

inc(Name)

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

Equivalent to inc(default, Name, [], 1).

inc/2

-spec inc(prometheus_metric:name(), prometheus_metric:labels() | non_neg_integer()) -> ok.

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)

-spec inc(prometheus_metric:name(), prometheus_metric:labels(), non_neg_integer()) -> ok.

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:labels(),
                 Value :: non_neg_integer() | float().

Increments the counter identified by Registry, Name and LabelValues by Value.

Raises:

{invalid_value, Value, Message} if Value isn't a positive number.
{unknown_metric, Registry, Name} error if counter 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 counter 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.
{mf_already_exists, {Registry, Name}, Message} error if a counter with the same Spec already exists.

remove(Name)

-spec remove(prometheus_metric:name()) -> boolean().

Equivalent to remove(default, Name, []).

remove(Name, LabelValues)

-spec remove(prometheus_metric:name(), prometheus_metric:labels()) -> boolean().

Equivalent to remove(default, Name, LabelValues).

remove(Registry, Name, LabelValues)

-spec remove(prometheus_registry:registry(), prometheus_metric:name(), prometheus_metric:labels()) ->
                boolean().

Removes counter series identified by Registry, Name and LabelValues.

Raises:

{unknown_metric, Registry, Name} error if counter 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)

-spec reset(prometheus_metric:name(), prometheus_metric:labels()) -> boolean().

Equivalent to reset(default, Name, LabelValues).

reset(Registry, Name, LabelValues)

-spec reset(prometheus_registry:registry(), prometheus_metric:name(), prometheus_metric:labels()) ->
               boolean().

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

Raises:

{unknown_metric, Registry, Name} error if counter with name Name can't be found in Registry.
{invalid_metric_arity, Present, Expected} error if labels count mismatch.

value(Name)

-spec value(prometheus_metric:name()) -> number() | undefined.

Equivalent to value(default, Name, []).

value(Name, LabelValues)

-spec value(prometheus_metric:name(), prometheus_metric:labels()) -> number() | undefined.

Equivalent to value(default, Name, LabelValues).

value(Registry, Name, LabelValues)

-spec value(prometheus_registry:registry(), prometheus_metric:name(), prometheus_metric:labels()) ->
               number() | undefined.

Returns the value of the counter identified by Registry, Name and LabelValues.

If there is no counter for LabelValues, returns undefined.

Raises:

{unknown_metric, Registry, Name} error if counter 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(), number()}].