# api-watch
**Real-time API monitoring for Flask/FastAPI with zero-blocking async logging**
[](https://badge.fury.io/py/api-watch)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
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:**
```bash
pip install api-watch[flask]
```
**For FastAPI:**
```bash
pip install api-watch[fastapi]
```
**For both:**
```bash
pip install api-watch[all]
```
### Flask Integration (Auto-Start)
```python
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:**
```bash
python -m apiwatch
```
**Docker run: easiest**
```bash
docker pull theisaac/api-watch:latest
docker compose up -d
```
**Open dashboard:**
```
http://localhost:22222
```
---
### FastAPI Integration
```python
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:**
```bash
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
---
## Use Cases
### Development & Debugging
```python
# See exactly what's hitting your API in real-time
# No more print() debugging!
```
### API Testing
```python
# Watch your integration tests run
# Verify request/response data instantly
```
### Microservices Monitoring
```python
# Monitor traffic between multiple services
# Debug complex request flows
```
---
## Configuration
### Basic Options
```python
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:**
```python
FlaskWatchMiddleware(
app,
api_watcher,
capture_request_body=True, # Log request bodies
capture_response_body=True # Log response bodies
)
```
**FastAPI:**
```python
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**
```bash
python -m apiwatch
```
**Terminal 2: Start Your App**
```python
from apiwatch import ApiWatcher
api_watcher = ApiWatcher(
service_name='my-app',
auto_start_dashboard=False # Don't auto-start in production
)
```
### Docker Compose
```yaml
services:
apiwatch:
image: theisaac/api-watch:latest
container_name: apiwatch
ports:
- "22222:22222"
restart: unless-stopped
environment:
- PYTHONUNBUFFERED=1
- WATCHDOG_USERNAME=admin
- WATCHDOG_PASSWORD=admin
command: python -m apiwatch
```
**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)
---
Raw data
{
"_id": null,
"home_page": "https://github.com/mount-isaac/api-watch",
"name": "api-watch",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "api, monitoring, flask, fastapi, logging, debugging, websocket, real-time",
"author": "Isaac Kyalo",
"author_email": "Isaac Kyalo <isadechair019@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/65/44/ef08d7a89782353399dcb53daeb16ddeb77653058f43dd135384fcec32fd/api_watch-0.1.4.tar.gz",
"platform": null,
"description": "# api-watch\n\n**Real-time API monitoring for Flask/FastAPI with zero-blocking async logging**\n\n[](https://badge.fury.io/py/api-watch)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\nA 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.\n\n\n\n---\n\n## Features\n\n- **Zero Performance Impact** - Fire-and-forget async logging that never blocks your API\n- **Real-time Streaming** - WebSocket-powered dashboard shows requests as they happen\n- **Auto-Start Dashboard** - Just import and use, dashboard starts automatically\n- **Full Visibility** - Method, path, status, timing, headers, request/response data\n- **Filter by Status** - Quickly filter requests by status code\n- **Request Statistics** - Visual metrics and charts\n- **Minimal UI** - Clean, fast dashboard focused on what matters\n- **Multi-Framework** - Works with Flask and FastAPI\n- **Production Ready** - Standalone mode for Docker/Kubernetes\n- **Optimized Dependencies** - Only install what you need\n\n---\n\n## Quick Start\n\n### Installation\n\n**For Flask:**\n```bash\npip install api-watch[flask]\n```\n\n**For FastAPI:**\n```bash\npip install api-watch[fastapi]\n```\n\n**For both:**\n```bash\npip install api-watch[all]\n```\n\n### Flask Integration (Auto-Start)\n\n```python\nfrom flask import Flask\nfrom apiwatch import ApiWatcher\nfrom apiwatch.middleware_flask import FlaskWatchMiddleware\n\napp = Flask(__name__)\n\n# Dashboard auto-starts\napi_watcher = ApiWatcher(service_name='my-flask-app')\nFlaskWatchMiddleware(app, api_watcher)\n\n@app.route('/api/health', methods=['GET'])\ndef health():\n return jsonify({\n \"status\": \"healthy\",\n \"service\": \"flask-service\"\n })\n\nif __name__ == '__main__':\n app.run(port=5000)\n```\n\n**Terminal run:**\n```bash\npython -m apiwatch\n```\n\n**Docker run: easiest**\n```bash\ndocker pull theisaac/api-watch:latest\ndocker compose up -d \n```\n\n**Open dashboard:**\n```\nhttp://localhost:22222\n```\n\n---\n\n### FastAPI Integration\n\n```python\nfrom fastapi import FastAPI\nfrom pydantic import BaseModel\nfrom apiwatch import ApiWatcher\nfrom apiwatch.middleware_fastapi import FastAPIWatchMiddleware\n\napp = FastAPI()\n\napi_watcher = ApiWatcher(\n service_name='fastapi-service',\n dashboard_host='localhost',\n auto_start_dashboard=False\n)\n\napp.add_middleware(FastAPIWatchMiddleware, watcher=api_watcher)\n\n@app.get(\"/api/health\")\nasync def health():\n return {\n \"status\": \"healthy\",\n \"service\": \"fastapi-service\"\n }\n\nif __name__ == '__main__':\n import uvicorn\n uvicorn.run(app, host=\"0.0.0.0\", port=8000)\n```\n\n**Run it:**\n```bash\nuvicorn app:app --port 8000\n```\n\n---\n\n## \ud83d\udcca Dashboard Features\n\n### Real-time Request Monitoring\n- \u2705 Live streaming of API requests\n- \u2705 Color-coded HTTP methods (GET, POST, PUT, DELETE)\n- \u2705 Status code highlighting (success/error)\n- \u2705 Response time tracking\n- \u2705 Service name badges (multi-service support)\n\n### Filters & Search\n- Filter by status code (2xx, 3xx, 4xx, 5xx, All)\n- Sort by newest, oldest, fastest, sloweset, status(high-low)\n- Filter by HTTP method\n\n### Request Details\n- Full request/response bodies\n- Query parameters\n- Headers (sensitive headers filtered)\n- Timestamp and duration\n\n---\n\n## Use Cases\n\n### Development & Debugging\n```python\n# See exactly what's hitting your API in real-time\n# No more print() debugging!\n```\n\n### API Testing\n```python\n# Watch your integration tests run\n# Verify request/response data instantly\n```\n\n### Microservices Monitoring\n```python\n# Monitor traffic between multiple services\n# Debug complex request flows\n```\n\n---\n\n## Configuration\n\n### Basic Options\n\n```python\napi_watcher = ApiWatcher(\n service_name='my-app', # Service identifier\n max_history=1000, # Requests to keep in memory\n dashboard_host='localhost', # Dashboard host\n dashboard_port=22222, # Dashboard port\n auto_start_dashboard=True # Auto-start if not running\n)\n```\n\n### Middleware Options\n\n**Flask:**\n```python\nFlaskWatchMiddleware(\n app, \n api_watcher,\n capture_request_body=True, # Log request bodies\n capture_response_body=True # Log response bodies\n)\n```\n\n**FastAPI:**\n```python\napp.add_middleware(\n FastAPIWatchMiddleware,\n watcher=api_watcher,\n capture_request_body=True, # Log request bodies\n capture_response_body=True # Log response bodies\n)\n```\n\n---\n\n## Production Deployment\n\n### Standalone Mode\n\nFor production, run the dashboard as a separate service:\n\n**Terminal 1: Start Dashboard**\n```bash\npython -m apiwatch\n```\n\n**Terminal 2: Start Your App**\n```python\nfrom apiwatch import ApiWatcher\n\napi_watcher = ApiWatcher(\n service_name='my-app',\n auto_start_dashboard=False # Don't auto-start in production\n)\n```\n\n### Docker Compose\n\n```yaml\nservices:\n apiwatch:\n image: theisaac/api-watch:latest\n container_name: apiwatch\n ports:\n - \"22222:22222\"\n restart: unless-stopped\n environment:\n - PYTHONUNBUFFERED=1\n - WATCHDOG_USERNAME=admin\n - WATCHDOG_PASSWORD=admin\n command: python -m apiwatch\n\n```\n\n**Service code:**\n```python\nimport os\nfrom apiwatch import ApiWatcher\n\napi_watcher = ApiWatcher(\n service_name=os.getenv('SERVICE_NAME', 'api-service'),\n dashboard_host=os.getenv('WATCHDOG_HOST', 'localhost'),\n dashboard_port=int(os.getenv('WATCHDOG_PORT', 22222)),\n auto_start_dashboard=False\n)\n```\n\n---\n\n## How It Works\n\n```\nFlask/FastAPI Request\n \u2193\n Middleware intercepts\n \u2193\n Queue.put_nowait() (non-blocking, <0.1ms)\n \u2193\n App continues normally\n \u2193\nBackground Async Worker\n \u2193\nHTTP POST to Dashboard\n \u2193\nDashboard broadcasts via WebSocket\n \u2193\nBrowser UI updates in real-time\n```\n\n**Zero blocking!** Your API never waits for logging.\n\n---\n\n## Requirements\n\n- Python 3.7+\n- aiohttp 3.8+ (always required)\n- Flask 2.0+ (optional - only for Flask integration)\n- FastAPI 0.68+ & Starlette 0.14+ (optional - only for FastAPI integration)\n\n---\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Real-time API monitoring for Flask/FastAPI with async, zero-blocking logging",
"version": "0.1.4",
"project_urls": {
"Bug Tracker": "https://github.com/mount-isaac/api-watch/issues",
"Documentation": "https://github.com/mount-isaac/api-watch#readme",
"Homepage": "https://github.com/mount-isaac/api-watch",
"Repository": "https://github.com/mount-isaac/api-watch"
},
"split_keywords": [
"api",
" monitoring",
" flask",
" fastapi",
" logging",
" debugging",
" websocket",
" real-time"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c3611c2558de952e156768c4a4fe8cffc14b911856c89e8aac587cc4e1b4f5ac",
"md5": "0d62f60853a806c1561b1d1ad9bb3254",
"sha256": "fdd3ba6f9ab38493f615c5a5094045fe9d768887ae37b762f10019f47d4b9eb5"
},
"downloads": -1,
"filename": "api_watch-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0d62f60853a806c1561b1d1ad9bb3254",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 19712,
"upload_time": "2025-10-12T17:41:21",
"upload_time_iso_8601": "2025-10-12T17:41:21.280404Z",
"url": "https://files.pythonhosted.org/packages/c3/61/1c2558de952e156768c4a4fe8cffc14b911856c89e8aac587cc4e1b4f5ac/api_watch-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6544ef08d7a89782353399dcb53daeb16ddeb77653058f43dd135384fcec32fd",
"md5": "05a982890aba4f6dfcb664da2d0f502d",
"sha256": "83d4fc2bd61acb50ff89c81a5624198d0aaecc088e3aa0c86238628c549ebaf7"
},
"downloads": -1,
"filename": "api_watch-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "05a982890aba4f6dfcb664da2d0f502d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 98898,
"upload_time": "2025-10-12T17:41:24",
"upload_time_iso_8601": "2025-10-12T17:41:24.039825Z",
"url": "https://files.pythonhosted.org/packages/65/44/ef08d7a89782353399dcb53daeb16ddeb77653058f43dd135384fcec32fd/api_watch-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-12 17:41:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mount-isaac",
"github_project": "api-watch",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "aiohttp",
"specs": [
[
">=",
"3.8.0"
]
]
}
],
"lcname": "api-watch"
}
JSON
