aiocop

What it is and what it does

aiocop is a non-intrusive monitoring tool for asyncio and uvloop that catches blocking I/O and CPU calls that freeze your event loop. It wraps the event loop's scheduling methods and uses Python's sys.audit hooks to detect when blocking functions like open(), network calls, or subprocess operations run in async code, then captures the full stack trace to show you exactly where the problem is.

The tool is designed for production use with minimal overhead (approximately 13 microseconds per task). You register callbacks to handle detected blocking events, can enable or disable monitoring at runtime, and optionally raise exceptions on high-severity violations during development or testing. It works with both standard asyncio and uvloop, and integrates into ASGI frameworks like FastAPI.

Use it for:

• Detect blocking file I/O (open, read, write) in async handlers before they reach production.
• Monitor long-running async tasks in web services to find where event loop delays originate.
• Enforce async best practices in CI/CD by raising exceptions on blocking calls during test runs.
• Debug performance issues in uvloop-based applications by pinpointing blocking calls with stack traces.
• Integrate with monitoring systems (Datadog, Prometheus) to track blocking events and severity over time.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Detects and logs blocking I/O and CPU calls in asyncio code using Python's sys.audit hooks, helping you identify where your event loop is being frozen.

Yes. It solves a real problem (finding blocking calls in asyncio code) with low overhead, no runtime dependencies, and a permissive license. Active maintenance, Production/Stable status, and zero known vulnerabilities. Suitable for both development debugging and production monitoring. Install if you run asyncio or uvloop and want to catch event loop freezes early.

Install

aiocop on PyPI

pip install aiocop

uv add aiocop

poetry add aiocop

Installing aiocop

Before you install

Low friction: pure Python wheel with no runtime dependencies. Active maintenance (last commit 2026-07-20, first release 2026-01-05) and marked Production/Stable.

License in practice

MIT license (permissive) — you can use, modify, and distribute freely with minimal restrictions.

Quickstart

pip install aiocop

import asyncio
import aiocop

def on_slow_task(event):
    print(f"Blocking detected: {event.elapsed_ms}ms")

async def main():
    aiocop.patch_audit_functions()
    aiocop.start_blocking_io_detection()
    aiocop.detect_slow_tasks(threshold_ms=10, on_slow_task=on_slow_task)
    aiocop.activate()
    # your async code here

asyncio.run(main())

Requires Python 3.10 or later (sys.audit hooks are the foundation).

Verify before relying

• Whether the ~13 microseconds overhead claim holds across different workload patterns and Python versions.
• Compatibility with other instrumentation tools beyond APMs (e.g., profilers, tracing libraries).
• How well context propagation works with libraries that use contextvars in non-standard ways.

Package facts

Evidence: aiocop-1.1.5-py3-none-any.whl

Keywords: asyncio, blocking-io, debugging, event-loop, monitoring, performance, uvloop

Tags

More Monitoring packages