prometheus_counter (prometheus v5.1.1)

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_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

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

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

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.

Removes counter series identified by Registry, Name and LabelValues.

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

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

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)

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

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)

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

Equivalent to remove(default, Name, LabelValues).

remove(Registry, 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 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)

Equivalent to reset(default, Name, LabelValues).

reset(Registry, 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 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:label_values()) -> number() | undefined.

Equivalent to value(default, Name, LabelValues).

value(Registry, 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 named Name can't be found in Registry.
  • {invalid_metric_arity, Present, Expected} error if labels count mismatch.

values(Registry, Name)