PyCounters - instrumenting production code

A light weight library to monitor performance and events in production systems.

Typical use cases

  • Number of items/requests processed per second.
  • Average processing time of items.
  • Average waiting time on resources/locks.
  • Time spent in DB layer.
  • Cache hit/miss rates.

Some simple examples

Measuring execution frequency

Count the number of times per second a function is executed:

from pycounters.shortcuts import frequency

def f():
    """ some interesting work like serving a request """


Measurements are done by averaging out a sliding window of 5 minutes. Window size is configurable.

Measuring average executing time

Count the average wall clock time a function runs:

from pycounters.shortcuts import time

def f():
    """ some interesting work like serving a request """


PyCounter’s shortcut decorator will use the function name in it’s output. This can be configured (see Shortcut functions).

Measuring custom event frequency

Counting some event somewhere in your code:

from pycounters.shortcuts import occurrence

def some_code():

Nice, but is it just that simple?

Well, almost (see Moving Parts for a complete answer.) To let the counters report their statistics you need to initialize an instance of the LogReporter:

import pycounters
import logging


Once adding this code, all the counters will periodically report their stats to a log named “counters”. Here is an example:

2011-06-03 18:12:44,881 | 9130|1286490432 | counters | INFO | posting 0.589342236519
2011-06-03 18:12:44,888 | 9130|1286490432 | counters | INFO | search 1.47849245866


The above logs indicate that the search function took 1.48 seconds on average to execute. The posting function took only 0.59 seconds.


Easy install PyCounters to get it up and running:

easy_install pycounters

Take a look at the Tutorial for more details.

Cool, but it would be great if ...

PyCounters is in it’s early stages. If you have any ideas for improvements, features which are aboslutely a must or things you feel are outright stupid - I’d love to hear. Make ticket on .

Here is what I have in mind so far:

Of course, you are more then welcome to browse and/or fork the code: