prometheus_counter (prometheus v6.0.1)
View SourceCounter 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 isdefault
;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
Creates a counter using Spec
, if a counter with the same Spec
exists returns false
.
Equivalent to deregister(default, Name)
.
Removes all counter series with name Name
and removes Metric Family from Registry
.
Equivalent to inc(default, Name, [], 1)
.
If the second argument is a list, equivalent to inc(default, Name, LabelValues, 1) otherwise equivalent to inc(default, Name, [], Value).
Increments the counter identified by Registry
, Name
and LabelValues
by Value
.
Creates a counter using Spec
.
Equivalent to remove(default, Name, []).
Equivalent to remove(default, Name, LabelValues).
Removes counter series identified by Registry
, Name
and LabelValues
.
Equivalent to reset(default, Name, [])
.
Equivalent to reset(default, Name, LabelValues)
.
Resets the value of the counter identified by Registry
, Name
and LabelValues
.
Equivalent to value(default, Name, [])
.
Equivalent to value(default, Name, LabelValues)
.
Returns the value of the counter identified by Registry
, Name
and LabelValues
.
Functions
-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 requiredSpec
key is missing.{invalid_metric_name, Name, Message}
error if metricName
is invalid.{invalid_metric_help, Help, Message}
error if metricHelp
is invalid.{invalid_metric_labels, Labels, Message}
error ifLabels
isn't a list.{invalid_label_name, Name, Message}
error ifName
isn't a valid label name.
-spec deregister(prometheus_metric:name()) -> {boolean(), boolean()}.
Equivalent to deregister(default, 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, _}
.
-spec inc(prometheus_metric:name()) -> ok.
Equivalent to inc(default, Name, [], 1)
.
-spec inc(prometheus_metric:name(), prometheus_metric:label_values() | 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).
-spec inc(prometheus_metric:name(), prometheus_metric:label_values(), non_neg_integer()) -> ok.
Equivalent to inc(default, Name, LabelValues, Value)
.
-spec inc(Registry, Name, LabelValues, Value) -> ok when Registry :: prometheus_registry:registry(), Name :: prometheus_metric:name(), LabelValues :: prometheus_metric:label_values(), Value :: non_neg_integer() | float().
Increments the counter identified by Registry
, Name
and LabelValues
by Value
.
Raises:
{invalid_value, Value, Message}
ifValue
isn't a positive number.{unknown_metric, Registry, Name}
error if counter with namedName
can't be found inRegistry
.{invalid_metric_arity, Present, Expected}
error if labels count mismatch.
-spec new(prometheus_metric:spec()) -> ok.
Creates a counter using Spec
.
Raises:
{missing_metric_spec_key, Key, Spec}
error if requiredSpec
key is missing.{invalid_metric_name, Name, Message}
error if metricName
is invalid.{invalid_metric_help, Help, Message}
error if metricHelp
is invalid.{invalid_metric_labels, Labels, Message}
error ifLabels
isn't a list.{invalid_label_name, Name, Message}
error ifName
isn't a valid label name.{mf_already_exists, {Registry, Name}, Message}
error if a counter with the sameSpec
already exists.
-spec remove(prometheus_metric:name()) -> boolean().
Equivalent to remove(default, Name, []).
-spec remove(prometheus_metric:name(), prometheus_metric:label_values()) -> boolean().
Equivalent to remove(default, Name, LabelValues).
-spec remove(Registry, Name, LabelValues) -> boolean() when Registry :: prometheus_registry:registry(), Name :: prometheus_metric:name(), LabelValues :: prometheus_metric:label_values().
Removes counter series identified by Registry
, Name
and LabelValues
.
Raises:
{unknown_metric, Registry, Name}
error if counter with nameName
can't be found inRegistry
.{invalid_metric_arity, Present, Expected}
error if labels count mismatch.
-spec reset(prometheus_metric:name()) -> boolean().
Equivalent to reset(default, Name, [])
.
-spec reset(prometheus_metric:name(), prometheus_metric:label_values()) -> boolean().
Equivalent to reset(default, Name, LabelValues)
.
-spec reset(Registry, Name, LabelValues) -> boolean() when Registry :: prometheus_registry:registry(), Name :: prometheus_metric:name(), LabelValues :: prometheus_metric:label_values().
Resets the value of the counter identified by Registry
, Name
and LabelValues
.
Raises:
{unknown_metric, Registry, Name}
error if counter with nameName
can't be found inRegistry
.{invalid_metric_arity, Present, Expected}
error if labels count mismatch.
-spec value(prometheus_metric:name()) -> number() | undefined.
Equivalent to value(default, Name, [])
.
-spec value(prometheus_metric:name(), prometheus_metric:label_values()) -> number() | undefined.
Equivalent to value(default, Name, LabelValues)
.
-spec value(Registry, Name, LabelValues) -> number() | undefined when Registry :: prometheus_registry:registry(), Name :: prometheus_metric:name(), LabelValues :: prometheus_metric:label_values().
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 namedName
can't be found inRegistry
.{invalid_metric_arity, Present, Expected}
error if labels count mismatch.
-spec values(prometheus_registry:registry(), prometheus_metric:name()) -> [{list(), number()}].