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.Metric.Gauge.

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

Example use cases for Counters:

• Number of requests processed;
• Number of items that were inserted into a queue;
• Total amount of data that 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/, the difference is that new/ will raise Prometheus.Error.MFAlreadyExists exception if counter with the same registry, name and labels combination already exists. Both accept spec Keyword 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:

defmodule MyServiceInstrumenter do

  use Prometheus.Metric

  ## to be called at app/supervisor startup.
  ## to tolerate restarts use declare.
  def setup() do
    Counter.declare([name: :my_service_total_requests,
                     help: "Total requests.",
                     labels: [:caller]])
  end

  def inc(caller) do
    Counter.inc([name: :my_service_total_requests,
                 labels: [caller]])
  end

end