Skip to content

aiocop

Non-intrusive monitoring for Python asyncio.

aiocop detects, pinpoints, and logs blocking I/O and CPU calls that freeze your event loop. It's designed to be production-safe with minimal overhead, leveraging Python's sys.audit hooks.

Why aiocop?

Blocking calls in async code are a common source of performance issues. A single time.sleep() or synchronous file read can freeze your entire event loop, causing latency spikes and degraded user experience.

aiocop helps you:

  • Detect blocking I/O operations in your async code automatically
  • Pinpoint exactly where blocking calls originate with full stack traces
  • Prioritize fixes with severity scoring
  • Monitor in production with minimal overhead
  • Enforce async best practices during development

Quick Example

import aiocop

def on_slow_task(event: aiocop.SlowTaskEvent) -> None:
    if event.exceeded_threshold:
        print(f"Blocking detected: {event.elapsed_ms:.1f}ms")
        for evt in event.blocking_events:
            print(f"  - {evt['event']}")

aiocop.patch_audit_functions()
aiocop.start_blocking_io_detection()
aiocop.detect_slow_tasks(threshold_ms=30, on_slow_task=on_slow_task)
aiocop.activate()

Documentation

Features

  • Production-Safe: Minimal runtime overhead using Python's audit hooks
  • Blocking I/O Detection: Detects file operations, network calls, subprocess, time.sleep, and more
  • Stack Trace Capture: Full stack traces to pinpoint blocking calls
  • Severity Scoring: Prioritize fixes based on impact
  • Callback System: Handle events however you need (logging, metrics, alerts)
  • Dynamic Controls: Enable/disable monitoring at runtime
  • Context Providers: Capture request IDs, tracing spans, and other context
  • Exception Mode: Raise exceptions on high-severity blocking for strict enforcement

License

aiocop is released under the MIT License.