---
id: aiocop
version: "1.1.5"
license: MIT
license_treatment: permissive
maintenance: active
---

# aiocop — Non-intrusive monitoring for Python asyncio and uvloop. Detects, pinpoints, and logs blocking IO and CPU calls that freeze your event loop.

License: permissive · Maintenance: active · Downloads: 145.0K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 145.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

asyncio blocking io detection, event loop monitoring, async performance debugging, blocking call detection, asyncio profiling, uvloop monitoring, async bottleneck finder, asyncio-debugging, event-loop-profiling, production-monitoring

[View on SkillFed](https://skillfed.io/packages/aiocop) · [View on PyPI](https://pypi.org/project/aiocop/)