fastapi-loopguard 0.4.0

Detect event-loop blocking in FastAPI/Starlette with per-request attribution

Catch event-loop blocking in FastAPI with per-request attribution.

---

When a request blocks your event loop (via time.sleep(), blocking I/O, or CPU work), LoopGuard detects it and tells you which endpoint caused it.

Install

pip install fastapi-loopguard

Quick Start

from fastapi import FastAPI
from fastapi_loopguard import LoopGuardMiddleware

app = FastAPI()
app.add_middleware(LoopGuardMiddleware)

Enforcement Modes

Mode	Behavior	Use Case
"warn"	Console warnings + headers	Default
"strict"	HTTP 503 + error page	Development / CI
"log"	Silent logging	Production

from fastapi_loopguard import LoopGuardConfig

# Development: strict enforcement (503 on blocking)
config = LoopGuardConfig(dev_mode=True)

# Production: silent logging
config = LoopGuardConfig(enforcement_mode="log")

app.add_middleware(LoopGuardMiddleware, config=config)

What You Get

Strict Mode

Returns an educational 503 page that explains what went wrong and how to fix it:

---

Warn Mode

Adds diagnostic headers to every response for debugging:

---

Log Mode

Writes structured logs with full request attribution:

---