monitored-ioloop

Monitored IO Loop

A production ready monitored IO loop for Python.
No more wondering why your event loop (or random pieces of your code) are suddenly popping up as slow in your monitoring.

Getting started

Installation

pip install monitored_ioloop  # For the default event loop
pip install monitored_ioloop[uvloop]  # For the the additional support of the uvloop event loop

Demo

📺 Play with the demo in sandbox

Usage

Recommended: Loop Factory (New Interface)

The loop factory approach is the recommended way to use monitored event loops. This approach is preferred by Python's asyncio documentation as it provides more flexibility and allows running asyncio without the policy system.

Asyncio event loop

from monitored_ioloop.monitored_asyncio import monitored_asyncio_loop_factory
from monitored_ioloop.monitoring import IoLoopMonitorState
import asyncio
import time


def monitor_callback(ioloop_state: IoLoopMonitorState) -> None:
    print(ioloop_state)


async def test_coroutine() -> None:
    time.sleep(2)


def main():
    loop_factory = monitored_asyncio_loop_factory(monitor_callback)
    asyncio.run(test_coroutine(), loop_factory=loop_factory)


if __name__ == "__main__":
    main()

Uvloop event loop

In order to use the uvloop event loop, please make sure to install monitored_ioloop[uvloop].

from monitored_ioloop.monitored_uvloop import monitored_uvloop_loop_factory
from monitored_ioloop.monitoring import IoLoopMonitorState
import asyncio
import time


def monitor_callback(ioloop_state: IoLoopMonitorState) -> None:
    print(ioloop_state)


async def test_coroutine() -> None:
    time.sleep(2)


def main():
    loop_factory = monitored_uvloop_loop_factory(monitor_callback)
    asyncio.run(test_coroutine(), loop_factory=loop_factory)


if __name__ == "__main__":
    main()

Legacy: Event Loop Policy Interface

For backward compatibility, you can still use the event loop policy interface:

from monitored_ioloop.monitored_asyncio import MonitoredAsyncIOEventLoopPolicy
from monitored_ioloop.monitoring import IoLoopMonitorState
import asyncio
import time


def monitor_callback(ioloop_state: IoLoopMonitorState) -> None:
    print(ioloop_state)


async def test_coroutine() -> None:
    time.sleep(2)


def main():
    asyncio.set_event_loop_policy(MonitoredAsyncIOEventLoopPolicy(monitor_callback))
    asyncio.run(test_coroutine())

The monitor callback

The monitor callback will be called for every execution that the event loop initiates.
With every call you will receive an IoLoopMonitorState object that contains the following information:

• callback_wall_time: Wall executing time of the callback.
• loop_handles_count: The amount of handles (think about them as tasks) that the IO loop is currently handling.
• loop_lag: The amount of time it took from the moment the task was added to the loop until it was executed.
• callback_pretty_name: The pretty name of the callback that was executed
  Please Note: This is a best effort, the name of the callback may still be of little help, depending on the specific callback implementation.

Performance impact

As many of you might be concerned about the performance impact of this library, I have run some benchmarks to measure the performance impact of this library.
In summary the performance impact is negligible for most use cases.
You can find the more detailed information in the following README.md.

Usage examples

You can find examples projects showing potential use cases in the examples folder.
Currently there is only the fastapi with prometheus exporter example but more will be added in the future.

Roadmap

• Add support for the amount of Handle's on the event loop
• Add an examples folder
• Add loop lag metric (Inspired from nodejs loop monitoring)
• Add visibility into which Handle are making the event loop slower
• Migrate to new loop factory interface
• Add easier integration with uvicorn
• Add easier integration with popular monitoring tools like Prometheus

Credits

• I took a lot of inspiration from the uvloop project with everything regarding the user interface of swapping the IO loop.
• The great pycon talk - https://www.youtube.com/watch?v=GSiZkP7cI80&t=16s