.. PyCounters documentation master file, created by sphinx-quickstart on Fri Jun 3 15:32:05 2011. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. ========================================== 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. .. _simple_examples: -------------------- Some simple examples -------------------- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Measuring execution frequency ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Count the number of times per second a function is executed:: from pycounters.shortcuts import frequency @frequency() def f(): """ some interesting work like serving a request """ pass .. note:: 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 @time() def f(): """ some interesting work like serving a request """ pass .. note:: PyCounter's shortcut decorator will use the function name in it's output. This can be configured (see :ref:`shortcut_functions`). ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Measuring custom event frequency ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Counting some event somewhere in your code:: from pycounters.shortcuts import occurrence def some_code(): ... if TEST_FOR_SOMETHING: occurrence("event_name") ... --------------------------------- Nice, but is it just that simple? --------------------------------- Well, almost (see :ref:`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 reporter=pycounters.reporters.LogReporter(logging.getLogger("counters")) pycounters.register_reporter(reporter) pycounters.start_auto_reporting(seconds=300) 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 .. note:: The above logs indicate that the search function took 1.48 seconds on average to execute. The posting function took only 0.59 seconds. ----------------------------------- Installation ----------------------------------- Easy install PyCounters to get it up and running: :: easy_install pycounters Take a look at the :ref:`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 https://bitbucket.org/bleskes/pycounters/issues . Here is what I have in mind so far: * `Django `_ integration (I'm currently working on this) * `Geckoboard `_ output Of course, you are more then welcome to browse and/or fork the code: https://bitbucket.org/bleskes/pycounters --------------- Further reading --------------- .. toctree:: :maxdepth: 3 tutorial moving_parts reference utilities