Debug Djangowith runtimeevidence.
Orbit records requests, queries, logs, exceptions, jobs, cache activity, and more, then turns them into safe debugging context for developers and AI coding tools.
pip install django-orbit
real dashboard captureProduct thesis
Agents cannot debug what they cannot see.
Repository search is not enough for live Django behavior. The useful context is in the request timeline: the exception, the query shape, the logs, the job, the cache miss, and the operation that connected them.
The wedge
Orbit is a Django-native runtime context layer. The package captures evidence locally, connects it by request family, and makes it useful to developers and AI coding tools.
The difference
Broad observability platforms add AI on top of generic telemetry. Orbit starts from the opposite direction: give coding agents the structured Django evidence they need to investigate correctly.
Django-native coverage
Evidence across the parts of Django where bugs hide.
Each watcher maps to an investigation surface, so developers can follow an issue from the route to the database, background job, permission check, or external dependency involved.
Methods, paths, status codes, body metadata, durations, and related entries.
SQL timings, slow queries, duplicate-query signals, N+1 evidence, waterfall timing, and EXPLAIN.
Exceptions, tracebacks, Python logs, model events, signals, commands, and manual dumps.
Cache hits/misses, Redis commands, storage operations, outgoing HTTP clients, and mail previews.
Celery, Django-Q, RQ, APScheduler, and celery-beat hooks for job evidence.
Permission checks, masking policy, watcher health, disabled modules, and agent exposure audits.
Evidence stays connected
family_hashGroups every request, query, log, exception, and related operation into one timeline.OrbitEntryOne polymorphic event table keeps telemetry queryable and exportable.dashboardLive feed, filters, JSON export, detail panels, stats, and health views.
Host-app safety is part of the design
_table_exists()Write paths guard fresh databases and migration-time states.WATCHER_FAIL_SILENTLYWatcher failures are isolated instead of taking down the app.healthFailed, disabled, and installed watchers are visible at/orbit/health/.
Core workflow
From vague ticket to evidence-backed handoff.
Orbit shortens the path from "checkout returns 500" to a focused incident bundle, likely root-cause hypotheses, and a regression test plan a coding agent can act on.
Requests, SQL, logs, exceptions, jobs, cache, storage, mail, and permissions are captured without injecting UI into the app.
family_hash ties every related event to one operation, so the timeline stays coherent.
MCP tools turn evidence into bounded summaries, incident bundles, hypotheses, and next actions.
Humans or agents receive enough context to inspect the right code, write the right test, and avoid broad guessing.
Agent-ready context
Local MCP turns Orbit evidence into debugging primitives.
Introduced in v0.10.0, Orbit can feed a coding agent with masked, bounded runtime context instead of guesses.
The agent receives evidence, not authority
Orbit does not mutate code or production systems. It produces briefs, bundles, hypotheses, and test plans that a human or coding agent can inspect before acting.
build_debug_briefMatch ticket text to recent requests, exceptions, logs, and related entries.investigate_requestDiagnose one request family with timeline, signals, queries, and next actions.create_incident_bundleGenerate JSON or Markdown handoff from request, fingerprint, or ticket text.propose_fix_hypothesesRank likely fix directions from captured signals.propose_test_planSuggest regression and performance tests before implementation.
Safety model
Give agents context without giving them control.
This section explains why Orbit can be useful in AI workflows: it exposes bounded runtime evidence, keeps MCP read-only, masks sensitive fields, and isolates watcher failures from the host app.
Runtime safety
_table_exists()Prevents writes before migrations create Orbit tables.WATCHER_FAIL_SILENTLYWatcher failures are isolated from the host application./orbit/health/Installed, failed, and disabled modules are visible.
Agent exposure safety
MASK_KEYSSensitive keys are redacted recursively.MCP_INCLUDE_PAYLOADSPayloads can be disabled for metadata-only agent access.MCP_ENABLED: FalseAll MCP tools return a stable disabled response.
Install path
Start local. Add MCP only when agents need evidence.
Install package
pip install django-orbitpip install django-orbit[mcp] for MCP tools.
Register app
Add 'orbit' to INSTALLED_APPS and run migrations.
Capture requests
Add OrbitMiddleware near the top of MIDDLEWARE.
Open dashboard
Mount orbit.urls, visit /orbit/, then connect MCP when needed.
Market position
Where Orbit fits in the Django debugging stack.
Orbit sits between request-time developer tools and broad observability platforms: focused on Django evidence, persistent timelines, and agent-ready context.
Django runtime evidence