Skip to content


A Counter is a metric that only increases in value, it could also reset to 0 for example in case of a service restart.

As the name suggests it's useful to count things, for example cache hits, number of connections or even count exceptions.


If you need a metric that can go up and down in value, checkout the Gauge.


To create a Counter import it and instantiate:

from pytheus.metrics import Counter

cache_hit_total = Counter(name='cache_hit_total', description='number of times the cache got it')

Increment the value

Now it's possible to increment the count by calling the inc():

# increases value by 1

it is also possible to specify by which amount to increase:

# increases value by 7


inc() accepts only positive values as counters cannot decrease.

Count Exceptions

As counters are a good fit for counting exceptions there are some nicities included, you can count exceptions within a with statement with count_exceptions:


the following examples assume a Counter called counter.

with counter.count_exceptions():
    raise ValueError  # increases counter by 1

It is also possible to specify which Exceptions to count:

with counter.count_exceptions((IndexError, ValueError)):
    raise KeyError. # does not increase as it's not included in the list


count_exceptions accepts an Exception or a tuple of exceptions.

As a Decorator

When used as a decorator the Counter will count exceptions, syntactic sugar to count_exceptions:

def my_func():
    raise ValueError  # increases counter by 1 when it raises

you are still able to specify which exceptions you want to count:

@counter(exceptions=(IndexError, ValueError))
def my_func():
    raise KeyError  # won't increase when raised as it's not in the list