Library Reference¶

Pikos is designed in layers. At the top layer we find the Monitor a decorator that acts as the entry point for the monitors provided by pikos. The next layer is the various monitors that are responsible to collect information (e.g. memory) during the execution of the decorated function. The retrieved information is recorded through the recorders and controlled with the filters.

Monitor Decorator¶

class pikos.monitors.monitor.Monitor[source]¶

Bases: object

Base class of Pikos provided monitors.

The class provides the .attach decorating method to attach a pikos monitor to a function or method. Subclasses might need to provide their own implementation if required.

__init__()¶: x.__init__(...) initializes x; see help(type(x)) for signature

__call__(...) <==> x(...)¶

enable()[source]¶: This method should enable the monitor.

disable()[source]¶: This method should disable the monitor.

attach(instance, function)¶

Attach (i.e. wrap) the monitor to the decorated function.

Basic decoration functionality without any arguments.

Parameters:

instance (object) – The monitor instance to attach.
function (callable) – The function to wrap

Returns:

fn : callable: A MonitorAttach instance.

Monitors¶

A monitor is a context manager object. The class is initialized with a recorder class. Each instance of a monitor class can be reused, the __enter__ method makes sure that the code that is executed inside the context will be monitored and that the associated recorder has been initialized. During the execution of the decorated function The information is collected into a name tuple and the tuple is forwarded to recorder that has been associated with the current monitor.

Pikos currently provides the following monitors:

`FunctionMonitor`	Record python function events.
`LineMonitor`	Record python line events.
`FunctionMemoryMonitor`	Record process memory on python function events.
`LineMemoryMonitor`	Record process memory on python line events.
`FocusedFunctionMonitor`	Record python function events.
`FocusedLineMonitor`	Record python line events.
`FocusedFunctionMemoryMonitor`	Record process memory on python function events.
`FocusedLineMemoryMonitor`	Record process memory on python function events.

External Monitors¶

Pikos can act as entry point for external libraries and profilers.

`PythonCProfiler`	The normal python `Profile` subclassed and adapted to work with the pikos Monitor decorator.
`LineProfiler`
`YappiProfiler`	A pikos compatible profiler class using the yappi library.

Note

These profilers are experimental and not yet integrated fully with the pikos framework. Please check individual documentation for more information.

Recorders¶

The recorder (a subclass of AbstractRecorder) is responsible for recording the tuples from the monitor. What is recordered is controlled by a filter function

Pikos currently provides the following recorders:

`TextStreamRecorder`	The TextStreamRecorder is simple recorder that formats and writes the records directly to a stream.
`TextFileRecorder`	The TextStreamRecorder that creates the file for the records.
`CSVRecorder`	The CSV Recorder is a simple text based recorder that records the tuple of values using a scv writer.
`CSVFileRecorder`	A CSVRecorder that creates the stream (i.e.
`ListRecorder`	The ListRecorder is simple recorder that records the tuple of values in memory as a list.
`ZeroMQRecorder`	The ZeroMQ Recorder is a recorder that publishes each set of values on a 0MQ publish socket.

Note

The standard Recorders are record type agnostic so it is possible to use the same recorder for multiple monitors. However, this feature is experimental and users are advised to use with care.

Filters¶

A filter controls if a record tuple will be recorded or not. The callable accepts the record and makes a decision based on that (i.e. return True or False. Functions (normal and lamda) and callable classes can be used in this case to remove clutter and speed up monitoring only of the desired code.

Pikos currently provides the following predefined filters:

`OnValue`	A record filter that returns True if record has a specific value.
`OnChange`	A record filter that checks if the record field has changed.

Records¶

Each monitor uses a specific record. A record is a subclass of named tuple augmented with two methods, header, line that can be optionally used to format the output.

Note

Currently only the TextStreamRecorder can take advantage of the additional format information.

The monitor records available are:

`FunctionRecord`	The record tuple for function events.
`LineRecord`	The record for line trace events.
`FunctionMemoryRecord`	The record tuple for memory usage on function events.
`LineMemoryRecord`	The record tuple for memory usage on line events.