api-watch
Real-time API monitoring for Flask and FastAPI with zero-blocking async logging.
A lightweight, developer-focused tool that streams your API requests, responses, and metadata to a beautiful real-time dashboard. Perfect for debugging, development, and understanding your API traffic.
Features
- Zero Performance Impact - Fire-and-forget async logging that never blocks your API
- Real-time Streaming - WebSocket-powered dashboard shows requests as they happen
- Auto-Start Dashboard - Just import and use, dashboard starts automatically
- Full Visibility - Method, path, status, timing, headers, request/response data
- Filter by Status - Quickly filter requests by status code
- Request Statistics - Visual metrics and charts
- Minimal UI - Clean, fast dashboard focused on what matters
- Multi-Framework - Works with Flask and FastAPI
- Production Ready - Standalone mode for Docker/Kubernetes
- Optimized Dependencies - Only install what you need
Quick Start
Installation
For Flask:
pip install api-watch[flask]
For FastAPI:
pip install api-watch[fastapi]
For both:
pip install api-watch[all]
Flask Integration (Auto-Start)
from flask import Flask
from apiwatch import ApiWatcher
from apiwatch.middleware_flask import FlaskWatchMiddleware
app = Flask(__name__)
# Dashboard auto-starts
api_watcher = ApiWatcher(service_name='my-flask-app')
FlaskWatchMiddleware(app, api_watcher)
@app.route('/api/health', methods=['GET'])
def health():
return jsonify({
"status": "healthy",
"service": "flask-service"
})
if __name__ == '__main__':
app.run(port=5000)
Terminal run:
python -m apiwatch
Docker run: easiest
docker pull theisaac/api-watch:latest
docker compose up -d
Open dashboard:
http://localhost:22222
FastAPI Integration
from fastapi import FastAPI
from pydantic import BaseModel
from apiwatch import ApiWatcher
from apiwatch.middleware_fastapi import FastAPIWatchMiddleware
app = FastAPI()
api_watcher = ApiWatcher(
service_name='fastapi-service',
dashboard_host='localhost',
auto_start_dashboard=False
)
app.add_middleware(FastAPIWatchMiddleware, watcher=api_watcher)
@app.get("/api/health")
async def health():
return {
"status": "healthy",
"service": "fastapi-service"
}
if __name__ == '__main__':
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
Run it:
uvicorn app:app --port 8000
📊 Dashboard Features
Real-time Request Monitoring
- Live streaming of API requests
- Color-coded HTTP methods (GET, POST, PUT, DELETE)
- Status code highlighting (success/error)
- Response time tracking
- Service name badges (multi-service support)
Filters & Search
- Filter by status code (2xx, 3xx, 4xx, 5xx, All)
- Sort by newest, oldest, fastest, sloweset, status(high-low)
- Filter by HTTP method
Request Details
- Full request/response bodies
- Query parameters
- Headers (sensitive headers filtered)
- Timestamp and duration
Configuration
Basic Options
api_watcher = ApiWatcher(
service_name='my-app', # Service identifier
max_history=1000, # Requests to keep in memory
dashboard_host='localhost', # Dashboard host
dashboard_port=22222, # Dashboard port
auto_start_dashboard=True # Auto-start if not running
)
Middleware Options
Flask:
FlaskWatchMiddleware(
app,
api_watcher,
capture_request_body=True, # Log request bodies
capture_response_body=True # Log response bodies
)
FastAPI:
app.add_middleware(
FastAPIWatchMiddleware,
watcher=api_watcher,
capture_request_body=True, # Log request bodies
capture_response_body=True # Log response bodies
)
Production Deployment
Standalone Mode
For production, run the dashboard as a separate service:
Terminal 1: Start Dashboard
python -m apiwatch
Terminal 2: Start Your App
from apiwatch import ApiWatcher
api_watcher = ApiWatcher(
service_name='my-app',
auto_start_dashboard=False # Don't auto-start in production
)
Docker Compose
services:
apiwatch:
image: theisaac/api-watch:latest
container_name: apiwatch
networks:
- test-network
ports:
- "22222:22222"
restart: unless-stopped
environment:
- PYTHONUNBUFFERED=1
- WATCHDOG_USERNAME=admin
- WATCHDOG_PASSWORD=admin
- API_WATCH_DASHBOARD_HOST=0.0.0.
- API_WATCH_DASHBOARD_PORT=22222
command: python -m apiwatch
services:
test_flask_app:
image: theisaac/files-webapp:latest
restart: always
networks:
- test-network
environment:
- API_WATCH_MAX_HISTORY=3000
- API_WATCH_DASHBOARD_HOST=apiwatch
- API_WATCH_DASHBOARD_PORT=22222
- API_WATCH_AUTO_START=false
ports:
- 1515:1515
#### NOTE
In Dockerized applications, ensure that the **apiwatch** container and your **Flask/FastAPI** containers are on the same network.
Also, use the container name `apiwatch` as the host name in your Flask app.
**Service code:**
```python
import os
from apiwatch import ApiWatcher
api_watcher = ApiWatcher(
service_name=os.getenv('SERVICE_NAME', 'api-service'),
dashboard_host=os.getenv('WATCHDOG_HOST', 'localhost'),
dashboard_port=int(os.getenv('WATCHDOG_PORT', 22222)),
auto_start_dashboard=False
)
How It Works
Flask/FastAPI Request
↓
Middleware intercepts
↓
Queue.put_nowait() (non-blocking, <0.1ms)
↓
App continues normally
↓
Background Async Worker
↓
HTTP POST to Dashboard
↓
Dashboard broadcasts via WebSocket
↓
Browser UI updates in real-time
Zero blocking! Your API never waits for logging.
Requirements
- Python 3.7+
- aiohttp 3.8+ (always required)
- Flask 2.0+ (optional - only for Flask integration)
- FastAPI 0.68+ & Starlette 0.14+ (optional - only for FastAPI integration)
Metadata
Release files for api-watch 0.1.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| api_watch-0.1.5.tar.gz | 17.2 MB | Without provenance | Details for api_watch-0.1.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| api_watch-0.1.5-py3-none-any.whl | Python 3 | none | any | Details for api_watch-0.1.5-py3-none-any.whl |
Total release size: 17.2 MB
Release files / api_watch-0.1.5.tar.gz
| Download URL | api_watch-0.1.5.tar.gz |
|---|---|
| Size | 17.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
78235c673f2615f45ce0635f95402bf15a0ab60a9b207e7283d76a54429f346f
|
|
BLAKE2b-256 checksum How to use checksums |
4183c00b39f17f90a17c563016f581885ee7013117352ea7693f0f3e9c45f377
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.0
|
Release files / api_watch-0.1.5-py3-none-any.whl
| Download URL | api_watch-0.1.5-py3-none-any.whl |
|---|---|
| Size | 22.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dffcc18bf57dffc156bb0c64668d8ac2ae8ff91c627742c16d14420ea941aa6c
|
|
BLAKE2b-256 checksum How to use checksums |
807d9da63e9ff182218076e48d78913bdbb1d2bc98449c943afa0a920ca94f29
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.0
|
Security for api-watch 0.1.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.