Object and function reference

Event reporting

pycounters.report_start(name)

reports an event’s start. NOTE: you must fire off a corresponding event end with report_end

pycounters.report_end(name)

reports an event’s end. NOTE: you must have fired off a corresponding event start with report_start

pycounters.report_start_end(name=None)

returns a function decorator and/or context manager which raises start and end events. If name is None events name is set to the name of the decorated function. In that case report_start_end can not be used as a context manager.

pycounters.report_value(name, value)

reports a value event to the counters.

Counters

class pycounters.counters.EventCounter(name, events=None)

Counts the number of times an end event has fired.

clear(dump=True)

Clears the stored information

get_value()

gets the value of this counter

report_event(name, property, param)

reports an event to this counter

class pycounters.counters.TotalCounter(name, events=None)

Counts the total of events’ values.

clear(dump=True)

Clears the stored information

get_value()

gets the value of this counter

report_event(name, property, param)

reports an event to this counter

class pycounters.counters.AverageWindowCounter(*args, **kwargs)

Calculates a running average of arbitrary values

clear(dump=True)

Clears the stored information

get_value()

gets the value of this counter

report_event(name, property, param)

reports an event to this counter

class pycounters.counters.AverageTimeCounter(*args, **kwargs)

Counts the average time between start and end events

clear(dump=True)

Clears the stored information

get_value()

gets the value of this counter

report_event(name, property, param)

reports an event to this counter

class pycounters.counters.FrequencyCounter(*args, **kwargs)

Use to count the frequency of some occurrences in a sliding window. Occurrences can be reported directly via a value event (X occurrences has happened now) or via an end event which will be interpreted as a single occurrence.

clear(dump=True)

Clears the stored information

get_value()

gets the value of this counter

report_event(name, property, param)

reports an event to this counter

class pycounters.counters.WindowCounter(*args, **kwargs)

Counts the number of end events in a sliding window

clear(dump=True)

Clears the stored information

get_value()

gets the value of this counter

report_event(name, property, param)

reports an event to this counter

class pycounters.counters.MaxWindowCounter(*args, **kwargs)

Counts maximum of events values in window

clear(dump=True)

Clears the stored information

get_value()

gets the value of this counter

report_event(name, property, param)

reports an event to this counter

class pycounters.counters.MinWindowCounter(*args, **kwargs)

Counts minimum of events values in window

clear(dump=True)

Clears the stored information

get_value()

gets the value of this counter

report_event(name, property, param)

reports an event to this counter

Reporters

class pycounters.reporters.LogReporter(output_log=None)

Log based reporter.

class pycounters.reporters.JSONFileReporter(output_file=None)

Reports to a file in a JSON format.

static safe_read(filename)

safely reads a value in a JSON format frome file

static safe_write(value, filename)

safely writes value in a JSON format to file

pycounters.register_reporter(reporter=None)

add a reporter to PyCounters. Registered reporters will output collected metrics

pycounters.unregister_reporter(reporter=None)

remove a reporter from PyCounters.

pycounters.output_report()

Manually cause the current values of all registered counters to be reported.

pycounters.start_auto_reporting(seconds=300)

Start reporting in a background thread. Reporting frequency is set by seconds param.

Multi-process reporting

pycounters.configure_multi_process_collection(collecting_address=[('', 60907), ('', 60906)], timeout_in_sec=120, role=2)

configures PyCounters to collect values from multiple processes

Parameters:
  • collecting_address – a list of (address,port) tuples address of machines and ports data should be collected on. the extra tuples are used as backup in case the first address/port combination is (temporarily) unavailable. PyCounters would automatically start using the preferred address/port when it becomes available again. This behavior is handy when restarting the program and the old port is not yet freed by the OS.
  • timeout_in_sec – timeout configuration for connections. Default should be good enough for pratically everyone.
  • role – the role of this process. Leave at the default of AUTO_ROLE for pycounters to automatically choose a collecting leader.

Registering counters

pycounters.register_counter(counter, throw_if_exists=True)

Register a counter with PyCounters

pycounters.unregister_counter(counter=None, name=None)

Removes a previously registered counter

Shortcut functions

pycounters.shortcuts.count(name=None, auto_add_counter=<class 'pycounters.counters.types.EventCounter'>)

A shortcut decorator to count the number times a function is called. Uses the counters.EventCounter counter by default. If the parameter name is not supplied events are reported under the name of the wrapped function.

pycounters.shortcuts.frequency(name=None, auto_add_counter=<class 'pycounters.counters.types.FrequencyCounter'>)

A shortcut decorator to count the frequency in which a function is called. Uses the counters.FrequencyCounter counter by default. If the parameter name is not supplied events are reported under the name of the wrapped function.

pycounters.shortcuts.occurrence(name, auto_add_counter=<class 'pycounters.counters.types.FrequencyCounter'>)

A shortcut function reports an occurrence of something. Uses the counters.FrequencyCounter counter by default.

pycounters.shortcuts.time(name=None, auto_add_counter=<class 'pycounters.counters.types.AverageTimeCounter'>)

A shortcut decorator to count the average execution time of a function. Uses the counters.AverageTimeCounter counter by default. If the parameter name is not supplied events are reported under the name of the wrapped function.

pycounters.shortcuts.value(name, value, auto_add_counter=<class 'pycounters.counters.types.AverageWindowCounter'>)

A shortcut function to report a value of something. Uses the counters.AverageWindowCounter counter by default.

Table Of Contents

Previous topic

Moving Parts

Next topic

Utilities reference

This Page