# Dashboard Module

Simple web dashboard for monitoring Python CAS server metrics.

## Features

- **Real-time Updates** - Auto-refreshes every 2 seconds
- **JSON API** - `/api/stats` endpoint for programmatic access
- **Responsive UI** - Clean, modern dashboard design
- **Zero Dependencies** - Self-contained HTML with vanilla JavaScript

## Architecture

### Components

1. **FastAPI Application** (`app.py`)
   - Minimal FastAPI app with 3 endpoints
   - `/` - Returns HTML dashboard
   - `/api/stats` - Returns JSON metrics
   - `/health` - Health check endpoint

2. **HTML Dashboard** (`templates/dashboard.html`)
   - Vanilla JavaScript for stats fetching
   - Auto-refresh every 2 seconds
   - Human-readable formatting (bytes, uptime)
   - Responsive grid layout

3. **ServerMetrics** (`monitoring/metrics.py`)
   - Wraps CacheMetrics with operational counters
   - Thread-safe for concurrent access
   - Tracks: reads, writes, deletes, evictions
   - Records: eviction run times

## Usage

### Enable Dashboard

```bash
# Install dashboard dependencies
uv pip install -e ".[dashboard]"

# Start server with dashboard (easiest)
just serve-dashboard

# Or manually with environment variables
export CAS_DASHBOARD_ENABLED=true
export CAS_DASHBOARD_PORT=8080
just serve
```

Dashboard will be available at `http://localhost:8080`

### Access Metrics Programmatically

```python
import requests

# Get all stats
response = requests.get("http://localhost:8080/api/stats")
stats = response.json()

# Check health
response = requests.get("http://localhost:8080/health")
print(response.json()["status"])  # "ok"
```

## Implementation Details

### Metrics Collection

```python
from cascache_server.monitoring.metrics import ServerMetrics

# Create metrics tracker
metrics = ServerMetrics()

# Record operations
metrics.record_read()
metrics.record_write()
metrics.record_eviction(count=5)

# Get stats
stats = metrics.get_stats()
```

### Dashboard Integration

The dashboard runs in a separate thread alongside the gRPC server:

```python
# In server.py
server_metrics = ServerMetrics()

if config.dashboard_enabled:
    dashboard_app = create_dashboard_app(server_metrics)
    # Run in background thread
    threading.Thread(target=lambda: uvicorn.run(...), daemon=True).start()
```

### Thread Safety

All metrics operations are protected with locks:
- Counter increments are atomic
- `get_stats()` returns consistent snapshot
- No race conditions under concurrent access

## Testing

Dashboard tests use `httpx` for async HTTP testing:

```bash
# Install test dependencies
uv pip install httpx pytest-asyncio

# Run dashboard tests
pytest tests/unit/test_dashboard.py -v
```

**Note:** Dashboard tests require Python 3.13 or lower due to FastAPI/Pydantic compatibility with Python 3.14.

## Performance

- **Minimal Overhead** - Dashboard runs in separate thread
- **Non-Blocking** - Doesn't impact gRPC server performance
- **Lightweight** - ~80MB memory with dashboard enabled
- **Fast Rendering** - Vanilla JavaScript, no heavy frameworks

## Future Enhancements (Optional)

- Configuration UI (edit settings via web)
- Historical graphs (time-series metrics)
- Export metrics (CSV, JSON download)
- Prometheus `/metrics` endpoint
- Authentication for dashboard access
