# api-watch-dog
**Real-time API monitoring for Flask/FastAPI with zero-blocking async logging**
[](https://badge.fury.io/py/api-watch-dog)
[](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-dog[flask]
```
**For FastAPI:**
```bash
pip install api-watch-dog[fastapi]
```
**For both:**
```bash
pip install api-watch-dog[all]
```
### Flask Integration (Auto-Start)
```python
from flask import Flask
from apiwatchdog import ApiWatcher
from apiwatchdog.middleware_flask import FlaskWatchdogMiddleware
app = Flask(__name__)
# Dashboard auto-starts
api_watcher = ApiWatcher(service_name='my-flask-app')
FlaskWatchdogMiddleware(app, api_watcher)
@app.route('/api/users')
def get_users():
return {"users": [...]}
if __name__ == '__main__':
app.run(port=5000)
```
**Run it:**
```bash
python app.py
```
**Open dashboard:**
```
http://localhost:22222
```
---
### FastAPI Integration
```python
from fastapi import FastAPI
from apiwatchdog import ApiWatcher
from apiwatchdog.middleware_fastapi import FastAPIWatchdogMiddleware
app = FastAPI()
# Dashboard auto-starts
api_watcher = ApiWatcher(service_name='my-fastapi-app')
app.add_middleware(FastAPIWatchdogMiddleware, watcher=api_watcher)
@app.get("/api/users")
async def get_users():
return {"users": [...]}
```
**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
FlaskWatchdogMiddleware(
app,
api_watcher,
capture_request_body=True, # Log request bodies
capture_response_body=True # Log response bodies
)
```
**FastAPI:**
```python
app.add_middleware(
FastAPIWatchdogMiddleware,
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 apiwatchdog
```
**Terminal 2: Start Your App**
```python
from apiwatchdog import ApiWatcher
api_watcher = ApiWatcher(
service_name='my-app',
auto_start_dashboard=False # Don't auto-start in production
)
```
### Docker Compose
```yaml
services:
apiwatchdog:
image: theisaac/api-watch-dog:latest
container_name: apiwatchdog
ports:
- "22222:22222"
restart: unless-stopped
environment:
- PYTHONUNBUFFERED=1
- WATCHDOG_USERNAME=admin
- WATCHDOG_PASSWORD=admin
command: python -m apiwatchdog
```
**Service code:**
```python
import os
from apiwatchdog 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-dog",
"name": "live-api-monitor",
"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/96/6e/c696ebfeac7f37e1ea59c334b008afc3d7e3581675723622e839e67fb5e5/live_api_monitor-0.1.0.tar.gz",
"platform": null,
"description": "# api-watch-dog\n\n**Real-time API monitoring for Flask/FastAPI with zero-blocking async logging**\n\n[](https://badge.fury.io/py/api-watch-dog)\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-dog[flask]\n```\n\n**For FastAPI:**\n```bash\npip install api-watch-dog[fastapi]\n```\n\n**For both:**\n```bash\npip install api-watch-dog[all]\n```\n\n### Flask Integration (Auto-Start)\n\n```python\nfrom flask import Flask\nfrom apiwatchdog import ApiWatcher\nfrom apiwatchdog.middleware_flask import FlaskWatchdogMiddleware\n\napp = Flask(__name__)\n\n# Dashboard auto-starts\napi_watcher = ApiWatcher(service_name='my-flask-app')\nFlaskWatchdogMiddleware(app, api_watcher)\n\n@app.route('/api/users')\ndef get_users():\n return {\"users\": [...]}\n\nif __name__ == '__main__':\n app.run(port=5000)\n```\n\n**Run it:**\n```bash\npython app.py\n```\n\n**Open dashboard:**\n```\nhttp://localhost:22222\n```\n\n---\n\n### FastAPI Integration\n\n```python\nfrom fastapi import FastAPI\nfrom apiwatchdog import ApiWatcher\nfrom apiwatchdog.middleware_fastapi import FastAPIWatchdogMiddleware\n\napp = FastAPI()\n\n# Dashboard auto-starts\napi_watcher = ApiWatcher(service_name='my-fastapi-app')\napp.add_middleware(FastAPIWatchdogMiddleware, watcher=api_watcher)\n\n@app.get(\"/api/users\")\nasync def get_users():\n return {\"users\": [...]}\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\nFlaskWatchdogMiddleware(\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 FastAPIWatchdogMiddleware,\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 apiwatchdog\n```\n\n**Terminal 2: Start Your App**\n```python\nfrom apiwatchdog 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 apiwatchdog:\n image: theisaac/api-watch-dog:latest\n container_name: apiwatchdog\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 apiwatchdog\n\n```\n\n**Service code:**\n```python\nimport os\nfrom apiwatchdog 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.0",
"project_urls": {
"Bug Tracker": "https://github.com/mount-isaac/api-watch-dog/issues",
"Documentation": "https://github.com/mount-isaac/api-watch-dog#readme",
"Homepage": "https://github.com/mount-isaac/api-watch-dog",
"Repository": "https://github.com/mount-isaac/api-watch-dog"
},
"split_keywords": [
"api",
" monitoring",
" flask",
" fastapi",
" logging",
" debugging",
" websocket",
" real-time"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c954e5d57d4733c53febd6c92d72383b3e4e9692305303bd4bab3ee078c80a21",
"md5": "ea21d9a6c450148d750433c5ab2a7d18",
"sha256": "0148399793f64843369fae54965f643e717d3786a2577b5d31ade38f547aee0b"
},
"downloads": -1,
"filename": "live_api_monitor-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ea21d9a6c450148d750433c5ab2a7d18",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 19619,
"upload_time": "2025-10-11T20:49:46",
"upload_time_iso_8601": "2025-10-11T20:49:46.517390Z",
"url": "https://files.pythonhosted.org/packages/c9/54/e5d57d4733c53febd6c92d72383b3e4e9692305303bd4bab3ee078c80a21/live_api_monitor-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "966ec696ebfeac7f37e1ea59c334b008afc3d7e3581675723622e839e67fb5e5",
"md5": "26288b4c054dcf49ff4fc1f51502a92d",
"sha256": "afbc14f887fcbee7dbf482fcd77d3f949ef3089d01efe7bdedc1b0df2cbcea60"
},
"downloads": -1,
"filename": "live_api_monitor-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "26288b4c054dcf49ff4fc1f51502a92d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 98715,
"upload_time": "2025-10-11T20:49:49",
"upload_time_iso_8601": "2025-10-11T20:49:49.383051Z",
"url": "https://files.pythonhosted.org/packages/96/6e/c696ebfeac7f37e1ea59c334b008afc3d7e3581675723622e839e67fb5e5/live_api_monitor-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-11 20:49:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mount-isaac",
"github_project": "api-watch-dog",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "aiohttp",
"specs": [
[
">=",
"3.8.0"
]
]
}
],
"lcname": "live-api-monitor"
}
JSON
