Pikos is designed in layers. At the top layer we find the Monitor a decorator that acts as an the entry point for the monitors provided to wrap methods to be monitored. 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.
Bases: object
The monitor class decorator.
This is the main entry point for all the monitors, inspectors, loggers and profilers that are supported by pikos. The Monitor is simplifies setting up and invoking the actual monitoring/profiling class.
Private
The callable to execute inside the monitor context manager. It can be a normal callable object or a generator.
The monitor object that implements the context manager interface.
The class can be instanciated by the user or used as a decorator for functions, methods and generators.
Usage
# as a decorator
@Monitor(FunctionMonitor())
def my_function():
...
return
# as an instance
def my_function():
...
return
logfunctions = Monitor(FunctionMonitor())
logfunctions(my_function, *args, **kwrgs)
...
Tip
Easy to use decorators are provided in pikos.api.
Class initialization.
| Parameters: | obj (object) – A contect manager to monitor, inspect or profile the decorated function while it is executed. |
|---|
Wrap function for monitoring.
| Parameters: | function (callable) – The callable to wrap |
|---|---|
| Returns: | fn (callable) – The wrapped function. fn has the same signature as function. Executing fn will run function inside the _monitor_object context. |
| Raises : | ValueError – Raised if the provided _monitor_object does not support the context manager interface. |
Wrap the callable.
| Returns: | fn (callable) – The wrapped function. fn has the same signature as function. Special care it taken if the callable is a generator. |
|---|
Wrap a normal callable object.
Wrap a generator function.
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:
| pikos.monitors.function_monitor.FunctionMonitor(...) | Record python function events. |
| pikos.monitors.line_monitor.LineMonitor(recorder) | Record python line events. |
| pikos.monitors.function_memory_monitor.FunctionMemoryMonitor(...) | Record process memory on python function events. |
| pikos.monitors.line_memory_monitor.LineMemoryMonitor(...) | Record process memory on python function events. |
| pikos.monitors.focused_function_monitor.FocusedFunctionMonitor(...) | Record python function events. |
| pikos.monitors.focused_line_monitor.FocusedLineMonitor(...) | Record python line events. |
| pikos.monitors.focused_function_memory_monitor.FocusedFunctionMemoryMonitor(...) | Record process memory on python function events. |
| pikos.monitors.focused_line_memory_monitor.FocusedLineMemoryMonitor(...) | Record process memory on python function events. |
Pikos can act as entry point for external libraries and profilers.
| pikos.external.python_cprofiler.PythonCProfiler(...) | The normal python Profile subclassed and adapted to |
| pikos.external.line_profiler.LineProfiler | A class wrapper for CLineProfiler. |
| pikos.external.yappi_profiler.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.
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:
| pikos.recorders.text_stream_recorder.TextStreamRecorder(...) | The TextStreamRecorder is simple recorder that formats and writes the |
| pikos.recorders.csv_recorder.CSVRecorder(stream) | The CSV Recorder is a simple text based recorder that records the |
| pikos.recorders.list_recorder.ListRecorder([...]) | The ListRecorder is simple recorder that records the |
| pikos.recorders.zeromq_recorder.ZeroMQRecorder([...]) | The ZeroMQ Recorder is a recorder that publishes each set of |
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.
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:
| pikos.filters.on_value.OnValue(field, *args) | A record filter that checks the value of a record field. |
| pikos.filters.on_change.OnChange(field) | 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.
Note
Currently only the TextStreamRecorder can take advantage of the additional format information.
The monitor records available are:
| pikos.monitors.function_monitor.FunctionRecord | |
| pikos.monitors.line_monitor.LineRecord | |
| pikos.monitors.function_memory_monitor.FunctionMemoryRecord | |
| pikos.monitors.line_memory_monitor.LineMemoryRecord |