Skip to main content

aiomonitor adds monitor and python REPL capabilities for asyncio application

Project description

aiomonitor Maintainability Documentation Status Chat on Gitter

aiomonitor is Python 3.5+ module that adds monitor and cli capabilities for asyncio application. Idea and code borrowed from curio project. Task monitor that runs concurrently to the asyncio loop (or fast drop in replacement uvloop) in a separate thread as result monitor will work even if event loop is blocked for some reason.

Library provides an python console using aioconsole module, it is possible to execute asynchronous command inside your running application. Extensible with you own commands, in the style of the standard library’s cmd module


Installation process is simple, just:

$ pip install aiomonitor


Monitor has context manager interface:

import aiomonitor

loop = asyncio.get_event_loop()
with aiomonitor.start_monitor(loop=loop):

Now from separate terminal it is possible to connect to the application:

$ nc localhost 50101

or using included python client:

$ python -m aiomonitor.cli


Lets create simple aiohttp application, and see how aiomonitor can integrates with it.

import asyncio

import aiomonitor
from aiohttp import web

# Simple handler that returns response after 100s
async def simple(request):
    loop =

    print('Start sleeping')
    await asyncio.sleep(100, loop=loop)
    return web.Response(text="Simple answer")

loop = asyncio.get_event_loop()
# create application and register route
app = web.Application(loop=loop)
app.router.add_get('/simple', simple)

# it is possible to pass dictionary with local variables
# to the python console environment
host, port = "localhost", 8090
locals_ = {"port": port, "host": host}
# init monitor just before run_app
with aiomonitor.start_monitor(loop=loop, locals=locals_):
    # run application with built in aiohttp run_app function
    web.run_app(app, port=port, host=host)

Lets save this code in file, so we can run it with command:

$ python
======== Running on http://localhost:8090 ========
(Press CTRL+C to quit)

And now one can connect running application from separate terminal, with nc command, immediately aiomonitor will respond with prompt:

$ nc localhost 50101
Asyncio Monitor: 1 tasks running
Type help for commands
monitor >>>

Now you can type commands, for instance help:

monitor >>> help
             ps               : Show task table
             where taskid     : Show stack frames for a task
             cancel taskid    : Cancel an indicated task
             signal signame   : Send a Unix signal
             stacktrace       : Print a stack trace from the event loop thread
             console          : Switch to async Python REPL
             quit             : Leave the monitor

aiomonitor supports also async python console inside running event loop so you can explore state of your application:

monitor >>> console
Python 3.5.2 (default, Oct 11 2016, 05:05:28)
[GCC 4.2.1 Compatible Apple LLVM 8.0.0 (clang-800.0.38)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
This console is running in an asyncio event loop.
It allows you to wait for coroutines using the 'await' syntax.
Try: await asyncio.sleep(1, result=3, loop=loop)
>>> await asyncio.sleep(1, result=3, loop=loop)

To leave console type exit():

>>> exit()
monitor >>>

aiomonitor is very easy to extend with your own console commands.

class WebMonitor(aiomonitor.Monitor):
    def do_hello(self, sin, sout, name=None):
        """Using the /hello GET interface

        There is one optional argument, "name".  This name argument must be
        provided with proper URL excape codes, like %20 for spaces.
        name = '' if name is None else '/' + name
        r = requests.get('http://localhost:8090/hello' + name)
        sout.write(r.text + '\n')



0.4.5 (2019-11-03)

  • Fixed endless loop on EOF (thanks @apatrushev)

0.4.4 (2019-03-23)

  • Simplified python console start end #175

  • Added python 3.7 compatibility #176

0.4.3 (2019-02-02)

  • Reworked console server start/close logic #169

0.4.2 (2019-01-13)

  • Fixed issue with type annotations from 0.4.1 release #164

0.4.1 (2019-01-10)

  • Fixed Python 3.5 support #161 (thanks @bmerry)

0.4.0 (2019-01-04)

  • Added support for custom commands #133 (thanks @yggdr)

  • Fixed OptLocals being passed as the default value for “locals” #122 (thanks @agronholm)

  • Added an API inspired by the standard library’s cmd module #135 (thanks @yggdr)

  • Correctly report the port running aioconsole #124 (thanks @bmerry)

0.3.1 (2018-07-03)

  • Added the stacktrace command #120 (thanks @agronholm)

0.3.0 (2017-09-08)

  • Added _locals_ parameter for passing environment to python REPL

0.2.1 (2016-01-03)

  • Fixed import in telnet cli in #12 (thanks @hellysmile)

0.2.0 (2016-01-01)

  • Added basic documentation

  • Most of methods of Monitor class are not not private api

0.1.0 (2016-12-14)

  • Added missed LICENSE file

  • Updated API, added start_monitor() function

0.0.3 (2016-12-11)

  • Fixed README.rst

0.0.2 (2016-12-11)

  • Tests more stable now

  • Added simple tutorial to README.rst

0.0.1 (2016-12-10)

  • Initial release.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

aiomonitor-0.4.5.tar.gz (17.7 kB view hashes)

Uploaded source

Built Distribution

aiomonitor-0.4.5-py3-none-any.whl (15.7 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page