api-watch 0.1.0

Real-time API monitoring for Flask/FastAPI with async, zero-blocking logging

api-watch-dog

Real-time API monitoring for Flask/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-dog[flask]

For FastAPI:

pip install api-watch-dog[fastapi]

For both:

pip install api-watch-dog[all]

Flask Integration (Auto-Start)

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:

python app.py

Open dashboard:

http://localhost:22222

---

FastAPI Integration

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:

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

# See exactly what's hitting your API in real-time
# No more print() debugging!

API Testing

# Watch your integration tests run
# Verify request/response data instantly

Microservices Monitoring

# Monitor traffic between multiple services
# Debug complex request flows

---

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:

FlaskWatchdogMiddleware(
    app, 
    api_watcher,
    capture_request_body=True,   # Log request bodies
    capture_response_body=True   # Log response bodies
)

FastAPI:

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

python -m apiwatchdog

Terminal 2: Start Your App

from apiwatchdog import ApiWatcher

api_watcher = ApiWatcher(
    service_name='my-app',
    auto_start_dashboard=False  # Don't auto-start in production
)

Docker Compose

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:

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)

---