FastAPI Radar

A debugging dashboard for FastAPI applications providing real-time request, database query, and exception monitoring.

Just one line to add powerful monitoring to your FastAPI app!

See it in Action

Installation

pip install fastapi-radar

Or with your favorite package manager:

# Using poetry
poetry add fastapi-radar

# Using pipenv
pipenv install fastapi-radar

Note: The dashboard comes pre-built! No need to build anything - just install and use.

Quick Start

With SQL Database (Full Monitoring)

from fastapi import FastAPI
from fastapi_radar import Radar
from sqlalchemy import create_engine

app = FastAPI()
engine = create_engine("sqlite:///./app.db")

# Full monitoring with SQL query tracking
radar = Radar(app, db_engine=engine)
radar.create_tables()

# Your routes work unchanged
@app.get("/users")
async def get_users():
    return {"users": []}

Without SQL Database (HTTP & Exception Monitoring)

from fastapi import FastAPI
from fastapi_radar import Radar

app = FastAPI()

# Monitor HTTP requests and exceptions only
# Perfect for NoSQL databases, external APIs, or database-less apps
radar = Radar(app)  # No db_engine parameter needed!
radar.create_tables()

@app.get("/api/data")
async def get_data():
    # Your MongoDB, Redis, or external API calls here
    return {"data": []}

Access your dashboard at: http://localhost:8000/__radar/

Features

• Zero Configuration - Works with any FastAPI app (SQL database optional)
• Request Monitoring - Complete HTTP request/response capture with timing
• Database Monitoring - SQL query logging with execution times (when using SQLAlchemy)
• Exception Tracking - Automatic exception capture with stack traces
• Real-time Updates - Live dashboard updates as requests happen
• Flexible Integration - Use with SQL, NoSQL, or no database at all

Configuration

radar = Radar(
    app,
    db_engine=engine,            # Optional: SQLAlchemy engine for SQL query monitoring
    dashboard_path="/__radar",   # Custom dashboard path (default: "/__radar")
    max_requests=1000,           # Max requests to store (default: 1000)
    retention_hours=24,          # Data retention period (default: 24)
    slow_query_threshold=100,    # Mark queries slower than this as slow (ms)
    capture_sql_bindings=True,   # Capture SQL query parameters
    exclude_paths=["/health"],   # Paths to exclude from monitoring
    theme="auto",                # Dashboard theme: "light", "dark", or "auto"
    db_path="/path/to/db",       # Custom path for radar.duckdb file (default: current directory)
    auth_dependency=None,        # Optional: Authentication dependency for dashboard and API access
)

Securing the Dashboard

By default, FastAPI Radar is accessible without authentication. For production environments, you should add authentication to protect your monitoring dashboard:

HTTP Basic Authentication

from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import HTTPBasic, HTTPBasicCredentials
from fastapi_radar import Radar
import secrets

app = FastAPI()
security = HTTPBasic()

def verify_credentials(credentials: HTTPBasicCredentials = Depends(security)):
    correct_username = secrets.compare_digest(credentials.username, "admin")
    correct_password = secrets.compare_digest(credentials.password, "secret")
    if not (correct_username and correct_password):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid credentials",
            headers={"WWW-Authenticate": "Basic"},
        )
    return credentials

radar = Radar(app, auth_dependency=verify_credentials)
radar.create_tables()

Bearer Token Authentication

from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
from fastapi_radar import Radar

app = FastAPI()
security = HTTPBearer()

def verify_token(credentials: HTTPAuthorizationCredentials = Depends(security)):
    if credentials.credentials != "your-secret-token":
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid token",
        )
    return credentials

radar = Radar(app, auth_dependency=verify_token)
radar.create_tables()

Custom Authentication

You can use any FastAPI dependency for authentication:

from fastapi import FastAPI, Depends, HTTPException, Request
from fastapi_radar import Radar

app = FastAPI()

async def custom_auth(request: Request):
    # Your custom authentication logic
    api_key = request.headers.get("X-API-Key")
    if api_key != "your-api-key":
        raise HTTPException(status_code=401, detail="Unauthorized")
    return True

radar = Radar(app, auth_dependency=custom_auth)
radar.create_tables()

The auth_dependency parameter accepts any FastAPI dependency function, giving you full flexibility to implement OAuth2, JWT, API keys, or any other authentication mechanism.

Custom Database Location

By default, FastAPI Radar stores its monitoring data in a radar.duckdb file in your current working directory. You can customize this location using the db_path parameter:

# Store in a specific directory
radar = Radar(app, db_path="/var/data/monitoring")
# Creates: /var/data/monitoring/radar.duckdb

# Store with a specific filename
radar = Radar(app, db_path="/var/data/my_app_monitoring.duckdb")
# Creates: /var/data/my_app_monitoring.duckdb

# Use a relative path
radar = Radar(app, db_path="./data")
# Creates: ./data/radar.duckdb

If the specified path cannot be created, FastAPI Radar will fallback to using the current directory with a warning.

Development Mode with Auto-Reload

When running your FastAPI application with fastapi dev (which uses auto-reload), FastAPI Radar automatically switches to an in-memory database to avoid file locking issues. This means:

• No file locking errors - The dashboard will work seamlessly in development
• Data doesn't persist between reloads - Each reload starts with a fresh database
• Production behavior unchanged - When using fastapi run or deploying, the normal file-based database is used

# With fastapi dev (auto-reload enabled):
# Automatically uses in-memory database - no configuration needed!
radar = Radar(app)
radar.create_tables()  # Safe to call - handles multiple processes gracefully

This behavior only applies when using the development server with auto-reload (fastapi dev). In production or when using fastapi run, the standard file-based DuckDB storage is used.

What Gets Captured?

• ✅ HTTP requests and responses
• ✅ Response times and performance metrics
• ✅ SQL queries with execution times
• ✅ Query parameters and bindings
• ✅ Slow query detection
• ✅ Exceptions with stack traces
• ✅ Request/response bodies and headers

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

For contributors who want to modify the codebase:

1. Clone the repository:

git clone https://github.com/doganarif/fastapi-radar.git
cd fastapi-radar

2. Install development dependencies:

pip install -e ".[dev]"

3. (Optional) If modifying the dashboard UI:

cd fastapi_radar/dashboard
npm install
npm run dev  # For development with hot reload
# or
npm run build  # To rebuild the production bundle

4. Run the example apps:

# Example with SQL database
python example_app.py

# Example without SQL database (NoSQL/in-memory)
python example_nosql_app.py

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with FastAPI
• Dashboard powered by React and shadcn/ui