🛰️ Django Orbit

Satellite Observability for Django

A debugging and observability dashboard that orbits your app without touching it.

📚 Documentation · 🎮 Try the Demo · ⭐ Star on GitHub

Table of Contents

• Why Orbit?
• What Orbit tracks
• Installation
• Quick Start
• Try the Demo
• Configuration
• Dashboards
• MCP Server — AI Assistant Integration
• Background Job Integrations
• Health & Plug-and-Play
• Storage Backends
• Security
• Roadmap
• Contributing

🎯 Why Orbit?

Unlike Django Debug Toolbar — which injects HTML into your templates — Django Orbit lives at its own isolated URL (/orbit/). It observes your application from a distance, like a satellite, without interfering with it.

Inspired by Laravel Telescope.

📡 What Orbit tracks

All events are linked by family_hash, so you can see every query, log, and exception that occurred within a single request.

📦 Installation

pip install django-orbit

# With MCP support (AI assistant integration — Claude, Cursor, Copilot)
pip install django-orbit[mcp]

🚀 Quick Start

1. Add to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    'orbit',
]

2. Add middleware (early in the list):

MIDDLEWARE = [
    'orbit.middleware.OrbitMiddleware',
    # ...
]

3. Include URLs:

from django.urls import path, include

urlpatterns = [
    path('orbit/', include('orbit.urls')),
    # ...
]

4. Migrate and run:

python manage.py migrate orbit
python manage.py runserver

Visit http://localhost:8000/orbit/ 🚀

🎮 Try the Demo

git clone https://github.com/astro-stack/django-orbit.git
cd django-orbit
pip install -e .
python demo.py setup
python manage.py runserver

⚙️ Configuration

All settings go in ORBIT_CONFIG (or ORBIT) in your settings.py. Everything has a sensible default — you only need to set what you want to change.

ORBIT_CONFIG = {
    'ENABLED': True,                      # set to DEBUG to auto-disable in production
    'SLOW_QUERY_THRESHOLD_MS': 500,
    'STORAGE_LIMIT': 1000,                # max entries to keep

    # Watchers — all enabled by default
    'RECORD_REQUESTS': True,
    'RECORD_QUERIES': True,
    'RECORD_LOGS': True,
    'RECORD_EXCEPTIONS': True,
    'RECORD_COMMANDS': True,
    'RECORD_CACHE': True,
    'RECORD_MODELS': True,
    'RECORD_HTTP_CLIENT': True,
    'RECORD_MAIL': True,
    'RECORD_SIGNALS': True,
    'RECORD_JOBS': True,
    'RECORD_REDIS': True,
    'RECORD_GATES': True,
    'RECORD_TRANSACTIONS': True,
    'RECORD_STORAGE': True,

    # Security
    'AUTH_CHECK': lambda request: request.user.is_staff,
    'IGNORE_PATHS': ['/orbit/', '/static/', '/media/'],

    # Resilience
    'WATCHER_FAIL_SILENTLY': True,        # failed watchers log errors but don't crash the app
}

📊 Dashboards

Main Dashboard — /orbit/

HTMX-powered live feed with 3-second polling. Filter by event type, search by keyword, export to JSON, and click any entry to see its full detail in a slide-over panel.

Stats Dashboard — /orbit/stats/

Time range filters: 1h · 6h · 24h · 7d

Health Dashboard — /orbit/health/

Shows the status of every Orbit module:

• 🟢 Healthy — working normally
• 🔴 Failed — initialization error (click for full traceback)
• 🟡 Disabled — turned off via config

🤖 MCP Server — AI Assistant Integration

Django Orbit exposes your telemetry as an MCP (Model Context Protocol) server. Connect Claude, Cursor, Windsurf, or any MCP-compatible AI assistant and ask questions directly against your app's live data.

Examples:

• "Why is /api/orders/ slow?"
• "What exceptions occurred in the last hour?"
• "Find all N+1 patterns in the app"
• "Show me everything that happened during this request"

Setup

pip install django-orbit[mcp]

// Claude Desktop → claude_desktop_config.json
// Cursor → .cursor/mcp.json
// Windsurf → .windsurfrc
{
  "mcpServers": {
    "django-orbit": {
      "command": "python",
      "args": ["manage.py", "orbit_mcp"],
      "cwd": "/path/to/your/django/project"
    }
  }
}

The MCP server launches on-demand when your AI assistant needs it. No extra process to manage.

Available tools

🔧 Background Job Integrations

💚 Health & Plug-and-Play

Each watcher initializes independently. If Celery isn't installed, only the Celery watcher fails — everything else keeps working.

from orbit import get_watcher_status, get_failed_watchers

get_watcher_status()
# {'cache': {'installed': True, 'error': None, 'disabled': False}, ...}

get_failed_watchers()
# {'celery': 'ModuleNotFoundError: No module named celery'}

🗄️ Storage Backends

By default Orbit stores events in your project's default database. For production you can route all Orbit writes to a dedicated database so telemetry doesn't compete with application traffic.

# settings.py
DATABASES = {
    "default": { ... },
    "orbit": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": BASE_DIR / "orbit.sqlite3",
    },
}

ORBIT_CONFIG = {
    "STORAGE_BACKEND": "orbit.backends.django_db.DjangoDBBackend",
    "STORAGE_DB_ALIAS": "orbit",
}

python manage.py migrate orbit --database=orbit

🛡️ Security

Restrict access using any callable:

ORBIT_CONFIG = {
    # Staff only
    'AUTH_CHECK': lambda request: request.user.is_staff,

    # Disable entirely in production
    'ENABLED': DEBUG,
}

Orbit automatically redacts sensitive fields (passwords, tokens, API keys) from request bodies and headers.

🗺️ Roadmap

What's next

• AI Insights engine — automatic pattern detection and plain-English summaries powered by LLMs
• VS Code / Cursor extension — surface Orbit data in your editor sidebar while you code
• Alerting — Slack, email, and webhook notifications for exceptions and slow requests
• Orbit Cloud — shared team dashboards with historical data retention

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

📄 License

MIT — see LICENSE.

Inspired by Laravel Telescope, Spatie Ray, and Django Debug Toolbar.

⭐ Star on GitHub · 📚 Documentation · 🐛 Issues