prometheus_counter.md

Module prometheus_counter

• Description
• Function Index
• Function Details

Counter is a Metric that represents a single numerical value that only ever goes up.

Behaviours: prometheus_collector, prometheus_metric.

Description

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 proplist 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]).

Function Index

declare/1	Creates a counter using Spec, if a counter with the same Spec exists returns false.
deregister/1	Equivalent to deregister(default, Name).
deregister/2	Removes all counter series with name Name and removes Metric Family from Registry.
inc/1	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/3	Equivalent to inc(default, Name, LabelValues, Value).
inc/4	Increments the counter identified by Registry, Name and LabelValues by Value.
new/1	Creates a counter using Spec.
remove/1	Equivalent to remove(default, Name, []).
remove/2	Equivalent to remove(default, Name, LabelValues).
remove/3	Removes counter series identified by Registry, Name and LabelValues.
reset/1	Equivalent to reset(default, Name, []).
reset/2	Equivalent to reset(default, Name, LabelValues).
reset/3	Resets the value of the counter identified by Registry, Name and LabelValues.
value/1	Equivalent to value(default, Name, []).
value/2	Equivalent to value(default, Name, LabelValues).
value/3	Returns the value of the counter identified by Registry, Name and LabelValues.
values/2

Function Details

declare/1

declare(Spec) -> any()

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.
Raises {invalid_metric_name, Name, Message} error if metric Name is invalid.
Raises {invalid_metric_help, Help, Message} error if metric Help is invalid.
Raises {invalid_metric_labels, Labels, Message} error if Labels isn't a list.
Raises {invalid_label_name, Name, Message} error if Name isn't a valid label name.

deregister/1

deregister(Name) -> any()

Equivalent to deregister(default, Name).

deregister/2

deregister(Registry, Name) -> any()

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/1

inc(Name) -> any()

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

inc/2

inc(Name, LabelValues) -> any()

If the second argument is a list, equivalent to inc(default, Name, LabelValues, 1) otherwise equivalent to inc(default, Name, [], Value).

inc/3

inc(Name, LabelValues, Value) -> any()

Equivalent to inc(default, Name, LabelValues, Value).

inc/4

inc(Registry, Name, LabelValues, Value) -> any()

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

Raises {invalid_value, Value, Message} if Value isn't a positive number.
Raises {unknown_metric, Registry, Name} error if counter with named Name can't be found in Registry.
Raises {invalid_metric_arity, Present, Expected} error if labels count mismatch.

new/1

new(Spec) -> any()

Creates a counter using Spec.

Raises {missing_metric_spec_key, Key, Spec} error if required Spec key is missing.
Raises {invalid_metric_name, Name, Message} error if metric Name is invalid.
Raises {invalid_metric_help, Help, Message} error if metric Help is invalid.
Raises {invalid_metric_labels, Labels, Message} error if Labels isn't a list.
Raises {invalid_label_name, Name, Message} error if Name isn't a valid label name.
Raises {mf_already_exists, {Registry, Name}, Message} error if a counter with the same Spec already exists.

remove/1

remove(Name) -> any()

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

remove/2

remove(Name, LabelValues) -> any()

Equivalent to remove(default, Name, LabelValues).

remove/3

remove(Registry, Name, LabelValues) -> any()

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.
Raises {invalid_metric_arity, Present, Expected} error if labels count mismatch.

reset/1

reset(Name) -> any()

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

reset/2

reset(Name, LabelValues) -> any()

Equivalent to reset(default, Name, LabelValues).

reset/3

reset(Registry, Name, LabelValues) -> any()

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.
Raises {invalid_metric_arity, Present, Expected} error if labels count mismatch.

value/1

value(Name) -> any()

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

value/2

value(Name, LabelValues) -> any()

Equivalent to value(default, Name, LabelValues).

value/3

value(Registry, Name, LabelValues) -> any()

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.
Raises {invalid_metric_arity, Present, Expected} error if labels count mismatch.

values/2

values(Registry, Name) -> any()