Metadata-Version: 2.4
Name: api-watch
Version: 0.1.2
Summary: Real-time API monitoring for Flask/FastAPI with async, zero-blocking logging
Home-page: https://github.com/mount-isaac/api-watch
Author: Isaac Kyalo
Author-email: Isaac Kyalo <isadechair019@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/mount-isaac/api-watch
Project-URL: Documentation, https://github.com/mount-isaac/api-watch#readme
Project-URL: Repository, https://github.com/mount-isaac/api-watch
Project-URL: Bug Tracker, https://github.com/mount-isaac/api-watch/issues
Keywords: api,monitoring,flask,fastapi,logging,debugging,websocket,real-time
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Framework :: Flask
Classifier: Framework :: FastAPI
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: aiohttp>=3.8.0
Provides-Extra: flask
Requires-Dist: flask>=2.0.0; extra == "flask"
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100.0; extra == "fastapi"
Requires-Dist: uvicorn>=0.23.0; extra == "fastapi"
Provides-Extra: all
Requires-Dist: flask>=2.0.0; extra == "all"
Requires-Dist: fastapi>=0.100.0; extra == "all"
Requires-Dist: uvicorn>=0.23.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flask>=2.0.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: fastapi>=0.100.0; extra == "dev"
Requires-Dist: uvicorn>=0.23.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# api-watch

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

[![PyPI version](https://badge.fury.io/py/api-watch.svg)](https://badge.fury.io/py/api-watch)
[![Python 3.7+](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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.

![api-watch Dashboard](./images/watch.png)

---

## 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 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 apiwatch import ApiWatcher
from apiwatch.middleware_fastapi import FastapiwatchMiddleware

app = FastAPI()

# Dashboard auto-starts
api_watcher = ApiWatcher(service_name='my-fastapi-app')
app.add_middleware(FastapiwatchMiddleware, 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(
    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)

---
