Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 235 lines (176 sloc) 8.453 kB
ab06fbe @robhudson Initial commit of basic working Debug Toolbar (that needs a lot of CS…
robhudson authored
1 ====================
2 Django Debug Toolbar
3 ====================
4
d2b803f @jezdez Added Travis build status image.
jezdez authored
5 .. image:: https://secure.travis-ci.org/django-debug-toolbar/django-debug-toolbar.png
6 :alt: Build Status
7 :target: http://travis-ci.org/django-debug-toolbar/django-debug-toolbar
8
ab06fbe @robhudson Initial commit of basic working Debug Toolbar (that needs a lot of CS…
robhudson authored
9 The Django Debug Toolbar is a configurable set of panels that display various
52dbdd5 provide an option to see stuff indjango in the sql stack trace
Alex Gaynor authored
10 debug information about the current request/response and when clicked, display
48179ed @robhudson Updated README a bit and added many of the suggestions to the TODO.
robhudson authored
11 more details about the panel's content.
ab06fbe @robhudson Initial commit of basic working Debug Toolbar (that needs a lot of CS…
robhudson authored
12
13 Currently, the following panels have been written and are working:
14
ef40163 @robhudson reverting all last readme changes
robhudson authored
15 - Django version
cc8eaee @robhudson editing README
robhudson authored
16 - Request timer
7360299 @robhudson Merging in new settings panel from 'binarydud/master'. Thanks!
robhudson authored
17 - A list of settings in settings.py
5d2f897 @robhudson Updated README: Added note about depending on jQuery for now. Added …
robhudson authored
18 - Common HTTP headers
48179ed @robhudson Updated README a bit and added many of the suggestions to the TODO.
robhudson authored
19 - GET/POST/cookie/session variable display
7360299 @robhudson Merging in new settings panel from 'binarydud/master'. Thanks!
robhudson authored
20 - Templates and context used, and their template paths
48179ed @robhudson Updated README a bit and added many of the suggestions to the TODO.
robhudson authored
21 - SQL queries including time to execute and links to EXPLAIN each query
1956ee5 @alex Adding a signals panel to display list of signals and their providing…
alex authored
22 - List of signals, their args and receivers
1d90d8e @nvie Added support for LogBook. Thanks to Vincent Driessen for the idea and
nvie authored
23 - Logging output via Python's built-in logging, or via the `logbook <http://logbook.pocoo.org>`_ module
ab06fbe @robhudson Initial commit of basic working Debug Toolbar (that needs a lot of CS…
robhudson authored
24
065162d @robhudson Added notes to README on `debugsqlshell` management command
robhudson authored
25 There is also one Django management command currently:
26
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
27 - ``debugsqlshell``: Outputs the SQL that gets executed as you work in the
28 Python interactive shell. (See example below)
065162d @robhudson Added notes to README on `debugsqlshell` management command
robhudson authored
29
ab06fbe @robhudson Initial commit of basic working Debug Toolbar (that needs a lot of CS…
robhudson authored
30 If you have ideas for other panels please let us know.
31
de515e2 @jezdez Updated minimal requirement for the toolbar to 1.1.
jezdez authored
32 * Note: The Debug Toolbar only works on Django 1.2 and newer.
c61daab @dcramer Change __import__ usage to to be import_module, adjust test reqs to s…
dcramer authored
33
ab06fbe @robhudson Initial commit of basic working Debug Toolbar (that needs a lot of CS…
robhudson authored
34 Installation
35 ============
36
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
37 #. Add the ``debug_toolbar`` directory to your Python path.
ab06fbe @robhudson Initial commit of basic working Debug Toolbar (that needs a lot of CS…
robhudson authored
38
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
39 #. Add the following middleware to your project's ``settings.py`` file::
ab06fbe @robhudson Initial commit of basic working Debug Toolbar (that needs a lot of CS…
robhudson authored
40
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
41 MIDDLEWARE_CLASSES = (
42 # ...
43 'debug_toolbar.middleware.DebugToolbarMiddleware',
44 # ...
45 )
ab06fbe @robhudson Initial commit of basic working Debug Toolbar (that needs a lot of CS…
robhudson authored
46
cc8eaee @robhudson editing README
robhudson authored
47 Tying into middleware allows each panel to be instantiated on request and
48 rendering to happen on response.
49
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
50 The order of ``MIDDLEWARE_CLASSES`` is important: the Debug Toolbar
51 middleware must come after any other middleware that encodes the
52 response's content (such as GZipMiddleware).
545c387 @robhudson Adding special note about middleware ordering.
robhudson authored
53
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
54 **Note**: The debug toolbar will only display itself if the mimetype of the
55 response is either ``text/html`` or ``application/xhtml+xml`` and contains a
56 closing ``</body>`` tag.
b9b0cbe @robhudson New configuration option to provide your own 'show_toolbar' method.
robhudson authored
57
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
58 **Note**: Be aware of middleware ordering and other middleware that may
59 intercept requests and return responses. Putting the debug toolbar
0571028 @robhudson Added note about middleware ordering and flat pages.
robhudson authored
60 middleware *after* the Flatpage middleware, for example, means the
61 toolbar will not show up on flatpages.
62
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
63 #. Make sure your IP is listed in the ``INTERNAL_IPS`` setting. If you are
d4d5124 @adewinter Make formatting consistent and have point #4 in installation stand ou…
adewinter authored
64 working locally this will be::
ca99f46 @orcasrob Adding notes about the INTERNAL_IPS setting for this to work.
orcasrob authored
65
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
66 INTERNAL_IPS = ('127.0.0.1',)
ca99f46 @orcasrob Adding notes about the INTERNAL_IPS setting for this to work.
orcasrob authored
67
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
68 **Note**: This is required because of the built-in requirements of the
69 ``show_toolbar`` method. See below for how to define a method to determine
b9b0cbe @robhudson New configuration option to provide your own 'show_toolbar' method.
robhudson authored
70 your own logic for displaying the toolbar.
71
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
72 #. Add ``debug_toolbar`` to your ``INSTALLED_APPS`` setting so Django can
73 find the template files associated with the Debug Toolbar::
1956ee5 @alex Adding a signals panel to display list of signals and their providing…
alex authored
74
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
75 INSTALLED_APPS = (
76 ...
77 'debug_toolbar',
78 )
ec38c74 @orcasrob Moving default list of panels into the loader to skip an install step…
orcasrob authored
79
b9b0cbe @robhudson New configuration option to provide your own 'show_toolbar' method.
robhudson authored
80 Configuration
81 =============
82
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
83 The debug toolbar has two settings that can be set in ``settings.py``:
b9b0cbe @robhudson New configuration option to provide your own 'show_toolbar' method.
robhudson authored
84
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
85 #. Optional: Add a tuple called ``DEBUG_TOOLBAR_PANELS`` to your ``settings.py``
52dbdd5 provide an option to see stuff indjango in the sql stack trace
Alex Gaynor authored
86 file that specifies the full Python path to the panel that you want included
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
87 in the Toolbar. This setting looks very much like the ``MIDDLEWARE_CLASSES``
88 setting. For example::
89
90 DEBUG_TOOLBAR_PANELS = (
91 'debug_toolbar.panels.version.VersionDebugPanel',
92 'debug_toolbar.panels.timer.TimerDebugPanel',
93 'debug_toolbar.panels.settings_vars.SettingsVarsDebugPanel',
94 'debug_toolbar.panels.headers.HeaderDebugPanel',
95 'debug_toolbar.panels.request_vars.RequestVarsDebugPanel',
96 'debug_toolbar.panels.template.TemplateDebugPanel',
97 'debug_toolbar.panels.sql.SQLDebugPanel',
98 'debug_toolbar.panels.signals.SignalDebugPanel',
99 'debug_toolbar.panels.logger.LoggingPanel',
100 )
ab06fbe @robhudson Initial commit of basic working Debug Toolbar (that needs a lot of CS…
robhudson authored
101
cc8eaee @robhudson editing README
robhudson authored
102 You can change the ordering of this tuple to customize the order of the
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
103 panels you want to display, or add/remove panels. If you have custom panels
b9b0cbe @robhudson New configuration option to provide your own 'show_toolbar' method.
robhudson authored
104 you can include them in this way -- just provide the full Python path to
105 your panel.
106
107 #. Optional: There are a few configuration options to the debug toolbar that
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
108 can be placed in a dictionary called ``DEBUG_TOOLBAR_CONFIG``:
b9b0cbe @robhudson New configuration option to provide your own 'show_toolbar' method.
robhudson authored
109
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
110 * ``INTERCEPT_REDIRECTS``
111
112 If set to True (default), the debug toolbar will
b9b0cbe @robhudson New configuration option to provide your own 'show_toolbar' method.
robhudson authored
113 show an intermediate page upon redirect so you can view any debug
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
114 information prior to redirecting. This page will provide a link to the
115 redirect destination you can follow when ready. If set to False, redirects
b9b0cbe @robhudson New configuration option to provide your own 'show_toolbar' method.
robhudson authored
116 will proceed as normal.
117
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
118 * ``SHOW_TOOLBAR_CALLBACK``
119
120 If not set or set to None, the debug_toolbar
b9b0cbe @robhudson New configuration option to provide your own 'show_toolbar' method.
robhudson authored
121 middleware will use its built-in show_toolbar method for determining whether
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
122 the toolbar should show or not. The default checks are that DEBUG must be
123 set to True or the IP of the request must be in INTERNAL_IPS. You can
b9b0cbe @robhudson New configuration option to provide your own 'show_toolbar' method.
robhudson authored
124 provide your own method for displaying the toolbar which contains your
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
125 custom logic. This method should return True or False.
126
127 * ``EXTRA_SIGNALS``
b9b0cbe @robhudson New configuration option to provide your own 'show_toolbar' method.
robhudson authored
128
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
129 An array of custom signals that might be in your project,
1956ee5 @alex Adding a signals panel to display list of signals and their providing…
alex authored
130 defined as the python path to the signal.
131
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
132 * ``HIDE_DJANGO_SQL``
133
134 If set to True (the default) then code in Django itself
9801c8b @robhudson Merge remote branch 'alex/master'
robhudson authored
135 won't be shown in SQL stacktraces.
52dbdd5 provide an option to see stuff indjango in the sql stack trace
Alex Gaynor authored
136
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
137 * ``SHOW_TEMPLATE_CONTEXT``
138
139 If set to True (the default) then a template's
140 context will be included with it in the Template debug panel. Turning this
89a0b38 allow for handling the pathological case of an insanely large templat…
Alex Gaynor authored
141 off is useful when you have large template contexts, or you have template
142 contexts with lazy datastructures that you don't want to be evaluated.
143
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
144 * ``TAG``
145
146 If set, this will be the tag to which debug_toolbar will attach the
29775b0 @brokenseal Added configurable HTML tag to attach toolbar to
brokenseal authored
147 debug toolbar. Defaults to 'body'.
148
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
149 * ``ENABLE_STACKTRACES``
150
151 If set, this will show stacktraces for SQL queries
12fdf7e @jezdez Updated cache panel to handle multiple backends and look more like th…
jezdez authored
152 and cache calls. Enabling stacktraces can increase the CPU time used when
153 executing queries. Defaults to True.
295f6f8 @colinhowe Make stacktraces configurable
colinhowe authored
154
b9b0cbe @robhudson New configuration option to provide your own 'show_toolbar' method.
robhudson authored
155 Example configuration::
156
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
157 def custom_show_toolbar(request):
158 return True # Always show toolbar, for example purposes only.
159
160 DEBUG_TOOLBAR_CONFIG = {
161 'INTERCEPT_REDIRECTS': False,
162 'SHOW_TOOLBAR_CALLBACK': custom_show_toolbar,
163 'EXTRA_SIGNALS': ['myproject.signals.MySignal'],
164 'HIDE_DJANGO_SQL': False,
165 'TAG': 'div',
166 'ENABLE_STACKTRACES' : True,
167 }
168
169 ``debugsqlshell``
170 =================
29c429d @myaser Update README.rst
myaser authored
171
065162d @robhudson Added notes to README on `debugsqlshell` management command
robhudson authored
172 The following is sample output from running the `debugsqlshell` management
73af56d @jezdez Cosmetic fixes to the README file.
jezdez authored
173 command. Each ORM call that results in a database query will be beautifully
065162d @robhudson Added notes to README on `debugsqlshell` management command
robhudson authored
174 output in the shell::
175
176 $ ./manage.py debugsqlshell
177 Python 2.6.1 (r261:67515, Jul 7 2009, 23:51:51)
178 [GCC 4.2.1 (Apple Inc. build 5646)] on darwin
179 Type "help", "copyright", "credits" or "license" for more information.
180 (InteractiveConsole)
181 >>> from page.models import Page
182 >>> ### Lookup and use resulting in an extra query...
183 >>> p = Page.objects.get(pk=1)
184 SELECT "page_page"."id",
185 "page_page"."number",
186 "page_page"."template_id",
187 "page_page"."description"
188 FROM "page_page"
189 WHERE "page_page"."id" = 1
190
191 >>> print p.template.name
192 SELECT "page_template"."id",
193 "page_template"."name",
194 "page_template"."description"
195 FROM "page_template"
196 WHERE "page_template"."id" = 1
197
198 Home
199 >>> ### Using select_related to avoid 2nd database call...
200 >>> p = Page.objects.select_related('template').get(pk=1)
201 SELECT "page_page"."id",
202 "page_page"."number",
203 "page_page"."template_id",
204 "page_page"."description",
205 "page_template"."id",
206 "page_template"."name",
207 "page_template"."description"
208 FROM "page_page"
209 INNER JOIN "page_template" ON ("page_page"."template_id" = "page_template"."id")
210 WHERE "page_page"."id" = 1
211
212 >>> print p.template.name
213 Home
214
9514b00 @dcramer Add support for __traceback_hide__ (tidy_stacktrace now inspects insp…
dcramer authored
215 Running the Tests
216 =================
217
218 The Debug Toolbar includes a limited (and growing) test suite. If you commit code, please consider
219 adding proper coverage (especially if it has a chance for a regression) in the test suite.
220
221 ::
222
223 python setup.py test
224
929c6be @robhudson Added a message about the 3rd party panel list wiki page
robhudson authored
225
226 3rd Party Panels
227 ================
228
229 A list of 3rd party panels can be found on the Django Debug Toolbar Github wiki:
230 https://github.com/django-debug-toolbar/django-debug-toolbar/wiki/3rd-Party-Panels
231
d3dde12 @robhudson README update to point to issues list on Google code.
robhudson authored
232 TODOs and BUGS
233 ==============
bf39bb0 @dcramer Update URLs to reflect organization change
dcramer authored
234 See: https://github.com/django-debug-toolbar/django-debug-toolbar/issues
Something went wrong with that request. Please try again.