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.


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

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

This method should enable the monitor.


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.

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

fn : callable

A MonitorAttach instance.


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.
YappiProfiler A pikos compatible profiler class using the yappi library.


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


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.


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.


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.


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.


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.