Metadata-Version: 2.4
Name: fastapi-flowtracer
Version: 0.1.0
Summary: Plug-and-play request/response flow tracer for FastAPI — shows async/sync execution context, blocking call detection, and full call trees.
Project-URL: Homepage, https://github.com/himanshuyadav/fastapi-flowtracer
Project-URL: Repository, https://github.com/himanshuyadav/fastapi-flowtracer
Project-URL: Issues, https://github.com/himanshuyadav/fastapi-flowtracer/issues
Author: Himanshu Yadav
License: MIT
License-File: LICENSE
Keywords: async,asyncio,debugging,fastapi,profiling,tracing
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: colorama>=0.4.6
Requires-Dist: fastapi>=0.100.0
Description-Content-Type: text/markdown

# 🔍 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

```bash
pip install fastapi-flowtracer
```

Or with `uv`:

```bash
uv add fastapi-flowtracer
```

## 🚀 Quick Start

```python
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

```bash
# 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
