Django Orbit Documentation¶

Welcome to the Django Orbit documentation. This guide covers installation, configuration, usage, and customization.

Table of Contents¶

What is Django Orbit?¶

Django Orbit is a debugging and observability tool for Django applications. Unlike Django Debug Toolbar, which injects HTML into your templates, Orbit runs on its own isolated URL and provides a modern, reactive dashboard for monitoring your application.

Key Concepts¶

OrbitEntry: The central model that stores all telemetry data
Middleware: Captures HTTP requests and coordinates recording
Watchers: Specialized components for SQL, logging, jobs, Redis, permissions, etc.
Family Hash: Links related events (e.g., all queries for one request)

Why Orbit?¶

Feature	Django Debug Toolbar	Django Orbit
DOM Injection	Yes	No
Works with APIs	Limited	Full
Works with SPAs	Limited	Full
Persistent Storage	No	Yes
Historical Data	No	Yes
Stats & Analytics	No	Yes
Modern UI	Basic	Space-themed

What's New in v0.8.1¶

HTML Email Preview: Emails sent with EmailMultiAlternatives now show a Plain text / HTML preview tab switcher in the dashboard. The HTML body renders in a sandboxed iframe — great for testing email templates. See Email Preview.
MySQL max_allowed_packet fix: New BULK_CREATE_BATCH_SIZE config key prevents OperationalError (2006, 'Server has gone away') on requests that trigger thousands of SQL queries. See BULK_CREATE_BATCH_SIZE.

What's New in v0.8.0¶

External Storage Backends: Route all Orbit writes to a dedicated Django database alias — keep telemetry out of your app's main database. See Storage Backends.

What's New in v0.7.0¶

MCP Server: Connect Claude, Cursor, Windsurf, or any MCP-compatible AI assistant to your live Django telemetry. Ask questions like "Why is this endpoint slow?" directly against real data. See MCP Server.

What's New in v0.6.0¶

Transaction Watcher: Track database transactions (commits/rollbacks)
Storage Watcher: Monitor file operations (save, open, delete, exists)
Improved Summaries: More informative entry summaries with duration and sizes
Enhanced Analytics: Transaction and storage metrics in Stats Dashboard

What's New in v0.5.0¶

Jobs Watcher: Track Celery, Django-Q, RQ, APScheduler tasks
Redis Watcher: Monitor Redis operations
Gates Watcher: Audit permission checks
Stats Dashboard: Apdex, percentiles, interactive charts
N+1 Navigation: Click through duplicate queries