django-orbit: Instructions file for Codex

AGENTS.md

Shared guidance for AI coding agents (Codex, Claude Code, Cursor, etc.) working in this repository. CLAUDE.md imports this file, so keep a single source of truth here.

What This Is

Django Orbit is a reusable Django app (published to PyPI as django-orbit) that provides "satellite observability" — a debugging/monitoring dashboard at /orbit/ that records requests, SQL queries, logs, exceptions, cache operations, model events, background jobs, and more. It is inspired by Laravel Telescope.

The key design constraint: Orbit must never interfere with the host app. Every watcher must fail gracefully (WATCHER_FAIL_SILENTLY), and all writes to OrbitEntry must be guarded by _table_exists() to prevent poisoning migrations on a fresh database.

Commands

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run a single test file
pytest tests/test_core.py

# Run a single test by name
pytest tests/test_core.py::test_middleware_captures_request

# Run with coverage
pytest --cov=orbit --cov-report=html

# Format and lint
black orbit tests
isort orbit tests
flake8 orbit tests
mypy orbit

# Run the demo server
python demo.py setup    # Populate sample data
python manage.py runserver

Architecture

Central model: OrbitEntry (orbit/models.py)

A single polymorphic model storing all telemetry. All event types share one table with a type discriminator and a JSONField payload. Entries are grouped across a request lifecycle via family_hash.

Data flow

HTTP Request
    → OrbitMiddleware (orbit/middleware.py)
        → installs OrbitQueryWrapper on connection (orbit/recorders.py)
        → sets family_hash context for log handler (orbit/handlers.py)
        → calls get_response()
    → Response captured → OrbitEntry(type='request') saved
    → All SQL queries → OrbitEntry(type='query') saved
    → All log calls → OrbitEntry(type='log') via OrbitLogHandler

Watcher system (orbit/watchers.py)