API

aiomonitor has tiny and simple to use API, just factory function and class that support context management protocol. Starting a monitor is as simple as opening a file.

import asyncio
import aiomonitor

loop = asyncio.get_event_loop()
with aiomonitor.start_monitor(loop):
    print("Now you can connect with: nc localhost 20101")
    loop.run_forever()

Alternatively you can use more verbose try/finally approach but do not forget call close() methods, to join thread and finalize resources:

m = Monitor()
m.start()
try:
    loop.run_forever()
finally:
    m.close()

It is possible to subclass Monitor to add custom commands to it. These custom commands are methods with names starting with do_. See examples.

Reference

MONITOR_HOST = '127.0.0.1'

Specifies the default host to bind the services for the monitor

Warning

Since aiomonitor exposes the internal states of the traced process, never bind it to publicly accessible address to prevent potential security breaches and denial of services!

MONITOR_TERMUI_PORT = 20101

Specifies the default telnet port for teh monitor where you can connect using a telnet client

MONITOR_WEBUI_PORT = 20102

Specifies the default HTTP port for the monitor where you can connect using a web browser

CONSOLE_PORT = 20103

Specifies the default port for asynchronous python REPL

aiomonitor.start_monitor(loop, monitor=Monitor, host=None, port=MONITOR_TERMUI_PORT, webui_port=MONITOR_WEBUI_PORT, console_port=CONSOLE_PORT, console_enabled=True, locals=None)[source]

Factory function, creates instance of Monitor and starts monitoring thread.

Parameters:

  • monitor (Type[Monitor]) – Monitor class to use

  • host (str) – hostname to serve monitor telnet server

  • port (int) – monitor port (terminal UI), by default 20101

  • webui_port (int) – monitor port (web UI), by default 20102

  • console_port (int) – python REPL port, by default 20103

  • console_enabled (bool) – flag indicates if python REPL is requred to start with instance of monitor.

  • locals (dict) – dictionary with variables exposed in python console environment

class aiomonitor.Monitor[source]

Class has same arguments as start_monitor(), except for the monitor argument.

start()[source]

Starts monitoring thread, where telnet server is executed.

close()[source]

Joins background thread, and cleans up resources.

closed

Flag indicates if monitor was closed, currntly instance of Monitor can not be reused. For new monitor, new instance should be created.

prompt

The string that prompts you to enter a command, defaults to ‘monitor >>> ‘

intro

Template for the intro text you see when you connect to the running monitor. Available fields to be filled in are: - tasknum: Number of tasks in the event loop - s: ‘s’ if tasknum is >1 or 0

help_template

Template string that gets filled in and displayed when help <COMMAND> is executed. Available fields to be filled in are: - cmd_name: the commands name - arg_list: the arguments it takes - doc: the docstring of the command method - doc_firstline: first line of the docstring

help_short_template

Like help_template, but gets called when help is executed, once per available command

lastcmd

Stores the last entered command line, whether it properly executed or not.

precmd(comm: str, args: Sequence[str]) → Tuple[do_<COMMAND> function: Callable, args: Sequence[Any]]

Gets executed by the loop before the command is run, and is acutally resonsible for resolving the entered command string to the method that gets called. If you overwrite this method, you can use self._getcmd(comm) to resolve it. Afterwards the default implementation uses list(self._map_args(cmd_method, args)) to map the given arguments to the methods type annotation.

postcmd(comm: str, args: Sequence[Any], result: Any, exception: Exception | None) → None

Runs after the command unconditionally. It takes the entered command string, the arguments (with type annotation applied, see above), the return value of the command, and the exception the command raised. If the command raised an exception, the result will be set to self._empty_result; if no exception was raised, it will be set to None. The default implementation does nothing.

emptyline()

Gets executed when an empty line is entered. A line is considered empty when line.strip() == ‘’ is true. By default takes the last run command (stored in self.lastcmd) and runs it again, using self._command_dispatch(self.lastcmd)

default(comm: str, args: Sequence[str]) → None

Gets run when precmd cannot find a command method to execute.

do_<COMMAND>(...)

Subclasses of the Monitor class can define their own commands available in the REPL. See the tutorial Adding custom commands.

@aiomonitor.utils.alt_names(names)

A decorator for the custom commands to define aliases, like h and ? are aliases for the help command. names is a single string with a space separated list of aliases.