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

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 [proplist](http://erlang.org/doc/man/proplists.html) 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 Soec 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.

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.

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()

Generated by EDoc