rob.cogit8.org

Introducing the Django Debug Toolbar

Genesis

For some time I've been subscribed to the Symfony Project's RSS feed and have enjoyed their weekly summaries and watching another web framework grow. One of the ideas that I found while scanning a particular blog post was their "Web Debug Toolbar". I was inspired and the very same day I started the Django Debug Toolbar.

Basic Structure

I liked the fact that Symfony's Debug Toolbar was made up of distinct panels, each of which had their own rendering methods. I created the Django Debug Toolbar similarly with a single toolbar that contained many panels. The toolbar itself is a piece of middleware that instantiates each panel object on request, and performs processing and rendering as the response is being written back to the browser. In this way it is essentially a set of middleware classes (the panels) grouped together to display a single toolbar. Each panel subclasses a base panel class and overrides a few methods to render the toolbar.

What's nice about Django's middleware is that they are specified like normal Python imports and anything on the Python path can be middleware provided they have the appropriate method definitions. I made the panels of the Django Debug Toolbar in a similar way — in fact, the panel loading code is Django's middleware loading code slightly modified — so that panels can be easily loaded into the toolbar from anywhere on your Python path. This will, hopefully, make extending and customizing the panels very easy.

Inspiration at DjangoCon

I worked on the Django Debug Toolbar for a few days and got the proof of concept working. At initial commit I had a panel to display the Django version and a panel to display SQL queries. The next day I added a timing panel. After that I didn't do much for about a week until I headed to DjangoCon. On the flight I continued to work on the project, converting the project to use file based templates that could be easily overridden for customization and adding a panel to display HTTP headers.

At the end of the first day of DjangoCon a surprising moment came during Cal Henderson's talk titled, Why I Hate Django. One of the talking points was that Django needed some strong debugging tools as he displayed a screenshot of Pownce with what was essentially a debugging toolbar like I had created. For a second I felt the wind get knocked out of my sail. For another second I was wondering why Pownce didn't open source it. Then I felt a desire to keep working on it in earnest. The next morning I mentioned the project on Twitter, to which Kevin from This Week in Django mistakenly thought I had created this overnight. That would have been cool but I'm nowhere near that awesome and I enjoy sleeping. But the project did get a lot of interest thanks to Cal's talk and Kevin's mention, and I got a lot of people watching and forking the project on github. GitHub is the social network for code because that day, 4 hours later, I started getting pull requests from people wanting to work on it, which was freakin' awesome.

Later that day I saw a tweet from zeeg commenting that he, also, was working on something similar to what we saw on the slide and mentioned collaboration. I didn't realize at the time that I had just sat next to David Cramer and we chatted about random Django stuff. In the evening the hotel where most DjangoCon attendees were staying, many of us were gathered in the "Hi-Fi Room". I glanced over and saw David's screen and saw his version of the debugging toolbar and finally realized that he was @zeeg. We introduced ourselves formally as our twitter names and immediately started working to get his work adapted to use my system of panels. The next day on the flight back I merged much of David's contributions, which included some styling and Javascript changes, a panel to display Caching statistics, and a panel to display GET, POST, session, and cookie variables.

Current Status

Currently the Django Debug Toolbar has 7 panels:

Django Debug Toolbar

1. Version, which simply displays the content from django.get_version().
2. Time, which displays the time it takes from request to response.
3. Http Headers, showing common HTTP request headers.
4. Request variables, which displays the GET, POST, cookie, and session information.
5. SQL queries showing the number of queries run during response creation and how long was spent on all queries, plus each query statement, and the time each statement took. This has already helped me tremendously to hone my queries.
6. Cache statistics showing total calls, time, hits and misses of the cache.
7. Templates, which displays the trace of which templates were rendered and the context provided to each template.

Have Fun Debugging

That's the story so far. If you're interested in checking it out, install it by downloading it (via the Download button or using git) and reading the README. Forking, hacking, and submitting pull requests is encouraged and is the way of the GitHub. And I'd love to hear back from people as to whether it worked, helped, broke, or have feature ideas, etc. Have fun!

Updates

• Sep 29, 2008: Bug reports can be filed at the Google Code project page. Thanks.