fastapi-flowtracer 0.1.0

Plug-and-play request/response flow tracer for FastAPI — shows async/sync execution context, blocking call detection, and full call trees.

🔍 FastAPI FlowTracer

Plug-and-play request/response flow tracer for FastAPI — automatically shows async/sync execution context, blocking call detection, and full call trees for every request.

✨ Features

• Zero config — just FlowTracer(app) and you're done
• Full call trees — traces every function your request touches
• Execution context — shows [event_loop] vs [threadpool:worker-N]
• Blocking detection — flags sync functions running on the event loop with ⚠️ BLOCKING
• Await tracking — marks async I/O calls with ⏳ await
• Smart filtering — traces your code + I/O libraries, skips framework internals
• Colorized output — green, yellow, red, cyan color-coding in terminal

📦 Installation

pip install fastapi-flowtracer

Or with uv:

uv add fastapi-flowtracer

🚀 Quick Start

from fastapi import FastAPI
from fastapi_flowtracer import FlowTracer

app = FastAPI()
FlowTracer(app)  # That's it!

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    user = await fetch_user_from_db(user_id)
    total = calculate_total(user.orders)  # sync on event loop!
    report = await asyncio.to_thread(generate_report, user)
    return {"user": user, "total": total}

📊 Output

Every request prints a trace tree to stderr:

[REQ-a1b2c3d4] → GET /users/42
  ├─ [event_loop] get_user (routes/users.py:15) ⏱ 120ms
  │  ├─ [event_loop] fetch_user_from_db (db/queries.py:42) ⏱ 45ms  ⏳ await
  │  ├─ [event_loop] ⚠️ BLOCKING calculate_total (utils/pricing.py:8) ⏱ 15ms
  │  │  └─ [event_loop] ⚠️ BLOCKING apply_tax (utils/pricing.py:22) ⏱ 3ms
  │  └─ [threadpool:worker-2] generate_report (services/pdf.py:31) ⏱ 55ms
  │     └─ [threadpool:worker-2] format_report_text (services/pdf.py:58) ⏱ 40ms
  └─ Response: 200 OK ⏱ 122ms total

Reading the output

Marker	Meaning
[event_loop]	Function running on the asyncio event loop thread
[threadpool:worker-N]	Function running in a threadpool worker
⚠️ BLOCKING	Sync function on the event loop — blocks all other requests!
⏳ await	Async I/O call (non-blocking)
⏱ Nms	Function execution time

🔧 How It Works

1. FlowTracer(app) installs an ASGI middleware on your FastAPI app
2. For each request, it activates Python's sys.setprofile to capture every function call
3. It auto-detects your project root and only traces your code + known I/O libraries
4. Framework internals (Starlette, Pydantic, uvicorn, etc.) are filtered out
5. After the request completes, it prints the colorized call tree

🧪 Development

# Clone and install
git clone https://github.com/himanshuyadav/fastapi-flowtracer.git
cd fastapi-flowtracer
uv sync

# Run tests
uv run pytest tests/ -v

# Run example app
uv run uvicorn examples.basic.main:app --reload

📄 License

MIT