-
Notifications
You must be signed in to change notification settings - Fork 1k
/
panels.rst
439 lines (271 loc) · 11.9 KB
/
panels.rst
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
Panels
======
The Django Debug Toolbar ships with a series of built-in panels. In addition,
several third-party panels are available.
Default built-in panels
-----------------------
The following panels are enabled by default.
History
~~~~~~~
.. class:: debug_toolbar.panels.history.HistoryPanel
This panel shows the history of requests made and allows switching to a past
snapshot of the toolbar to view that request's stats.
.. caution::
If :ref:`RENDER_PANELS <RENDER_PANELS>` configuration option is set to
``True`` or if the server runs with multiple processes, the History Panel
will be disabled.
Versions
~~~~~~~~
.. class:: debug_toolbar.panels.versions.VersionsPanel
Shows versions of Python, Django, and installed apps if possible.
Timer
~~~~~
.. class:: debug_toolbar.panels.timer.TimerPanel
Request timer.
Settings
~~~~~~~~
.. class:: debug_toolbar.panels.settings.SettingsPanel
A list of settings in settings.py.
Headers
~~~~~~~
.. class:: debug_toolbar.panels.headers.HeadersPanel
This panels shows the HTTP request and response headers, as well as a
selection of values from the WSGI environment.
Note that headers set by middleware placed before the debug toolbar middleware
in ``MIDDLEWARE`` won't be visible in the panel. The WSGI server itself may
also add response headers such as ``Date`` and ``Server``.
Request
~~~~~~~
.. class:: debug_toolbar.panels.request.RequestPanel
GET/POST/cookie/session variable display.
SQL
~~~
.. class:: debug_toolbar.panels.sql.SQLPanel
SQL queries including time to execute and links to EXPLAIN each query.
Static files
~~~~~~~~~~~~
.. class:: debug_toolbar.panels.staticfiles.StaticFilesPanel
Used static files and their locations (via the ``staticfiles`` finders).
Templates
~~~~~~~~~
.. class:: debug_toolbar.panels.templates.TemplatesPanel
Templates and context used, and their template paths.
Alerts
~~~~~~~
.. class:: debug_toolbar.panels.alerts.AlertsPanel
This panel shows alerts for a set of pre-defined cases:
- Alerts when the response has a form without the
``enctype="multipart/form-data"`` attribute and the form contains
a file input.
Cache
~~~~~
.. class:: debug_toolbar.panels.cache.CachePanel
Cache queries. Is incompatible with Django's per-site caching.
Signals
~~~~~~~
.. class:: debug_toolbar.panels.signals.SignalsPanel
List of signals and receivers.
Redirects
~~~~~~~~~
.. class:: debug_toolbar.panels.redirects.RedirectsPanel
When this panel is enabled, the debug toolbar will show an intermediate page
upon redirect so you can view any debug information prior to redirecting. This
page will provide a link to the redirect destination you can follow when
ready.
Since this behavior is annoying when you aren't debugging a redirect, this
panel is included but inactive by default. You can activate it by default with
the ``DISABLE_PANELS`` configuration option.
.. _profiling-panel:
Profiling
~~~~~~~~~
.. class:: debug_toolbar.panels.profiling.ProfilingPanel
Profiling information for the processing of the request.
This panel is included but inactive by default. You can activate it by default
with the ``DISABLE_PANELS`` configuration option.
For version of Python 3.12 and later you need to use
``python -m manage runserver --nothreading``
Concurrent requests don't work with the profiling panel.
The panel will include all function calls made by your project if you're using
the setting ``settings.BASE_DIR`` to point to your project's root directory.
If a function is in a file within that directory and does not include
``"/site-packages/"`` or ``"/dist-packages/"`` in the path, it will be
included.
Third-party panels
------------------
.. note:: Third-party panels aren't officially supported!
The authors of the Django Debug Toolbar maintain a list of third-party
panels, but they can't vouch for the quality of each of them. Please
report bugs to their authors.
If you'd like to add a panel to this list, please submit a pull request!
Flame Graphs
~~~~~~~~~~~~
URL: https://gitlab.com/living180/pyflame
Path: ``pyflame.djdt.panel.FlamegraphPanel``
Displays a flame graph for visualizing the performance profile of the request,
using Brendan Gregg's `flamegraph.pl script
<https://github.com/brendangregg/FlameGraph/flamegraph.pl>`_ to perform the
heavy lifting.
LDAP Tracing
~~~~~~~~~~~~
URL: https://github.com/danyi1212/django-windowsauth
Path: ``windows_auth.panels.LDAPPanel``
LDAP Operations performed during the request, including timing, request and response messages,
the entries received, write changes list, stack-tracing and error debugging.
This panel also shows connection usage metrics when it is collected.
`Check out the docs <https://django-windowsauth.readthedocs.io/en/latest/howto/debug_toolbar.html>`_.
Line Profiler
~~~~~~~~~~~~~
URL: https://github.com/mikekeda/django-debug-toolbar-line-profiler
Path: ``debug_toolbar_line_profiler.panel.ProfilingPanel``
This package provides a profiling panel that incorporates output from
line_profiler_.
.. _line_profiler: https://github.com/rkern/line_profiler
Mail
~~~~~~~~
URL: https://github.com/scuml/django-mail-panel
Path: ``mail_panel.panels.MailToolbarPanel``
This panel captures and displays emails sent from your application.
Memcache
~~~~~~~~
URL: https://github.com/ross/memcache-debug-panel
Path: ``memcache_toolbar.panels.memcache.MemcachePanel`` or
``memcache_toolbar.panels.pylibmc.PylibmcPanel``
This panel tracks memcached usage. It currently supports both the pylibmc and
memcache libraries.
MongoDB
~~~~~~~
URL: https://github.com/hmarr/django-debug-toolbar-mongo
Path: ``debug_toolbar_mongo.panel.MongoDebugPanel``
Adds MongoDB debugging information.
MrBenn Toolbar Plugin
~~~~~~~~~~~~~~~~~~~~~
URL: https://github.com/andytwoods/mrbenn
Path: ``mrbenn_panel.panel.MrBennPanel``
Allows you to quickly open template files and views directly in your IDE!
In addition to the path above, you need to add ``mrbenn_panel`` in
``INSTALLED_APPS``
Neo4j
~~~~~
URL: https://github.com/robinedwards/django-debug-toolbar-neo4j-panel
Path: ``neo4j_panel.Neo4jPanel``
Trace neo4j rest API calls in your Django application, this also works for
neo4django and neo4jrestclient, support for py2neo is on its way.
Pympler
~~~~~~~
URL: https://pythonhosted.org/Pympler/django.html
Path: ``pympler.panels.MemoryPanel``
Shows process memory information (virtual size, resident set size) and model
instances for the current request.
Request History
~~~~~~~~~~~~~~~
URL: https://github.com/djsutho/django-debug-toolbar-request-history
Path: ``ddt_request_history.panels.request_history.RequestHistoryPanel``
Switch between requests to view their stats. Also adds support for viewing
stats for AJAX requests.
Requests
~~~~~~~~
URL: https://github.com/marceltschoppch/django-requests-debug-toolbar
Path: ``requests_panel.panel.RequestsDebugPanel``
Lists HTTP requests made with the popular `requests <https://requests.readthedocs.io/>`_ library.
Template Profiler
~~~~~~~~~~~~~~~~~
URL: https://github.com/node13h/django-debug-toolbar-template-profiler
Path: ``template_profiler_panel.panels.template.TemplateProfilerPanel``
Shows template render call duration and distribution on the timeline.
Lightweight. Compatible with WSGI servers which reuse threads for multiple
requests (Werkzeug).
Template Timings
~~~~~~~~~~~~~~~~
URL: https://github.com/orf/django-debug-toolbar-template-timings
Path: ``template_timings_panel.panels.TemplateTimings.TemplateTimings``
Displays template rendering times for your Django application.
VCS Info
~~~~~~~~
URL: https://github.com/giginet/django-debug-toolbar-vcs-info
Path: ``vcs_info_panel.panels.GitInfoPanel``
Displays VCS status (revision, branch, latest commit log and more) of your
Django application.
uWSGI Stats
~~~~~~~~~~~
URL: https://github.com/unbit/django-uwsgi
Path: ``django_uwsgi.panels.UwsgiPanel``
Displays uWSGI stats (workers, applications, spooler jobs and more).
API for third-party panels
--------------------------
Third-party panels must subclass :class:`~debug_toolbar.panels.Panel`,
according to the public API described below. Unless noted otherwise, all
methods are optional.
Panels can ship their own templates, static files and views.
Any views defined for the third-party panel use the following decorators:
- ``debug_toolbar.decorators.require_show_toolbar`` - Prevents unauthorized
access to the view.
- ``debug_toolbar.decorators.render_with_toolbar_language`` - Supports
internationalization for any content rendered by the view. This will render
the response with the :ref:`TOOLBAR_LANGUAGE <TOOLBAR_LANGUAGE>` rather than
:setting:`LANGUAGE_CODE`.
There is no public CSS API at this time.
.. autoclass:: debug_toolbar.panels.Panel
.. autoattribute:: debug_toolbar.panels.Panel.nav_title
.. autoattribute:: debug_toolbar.panels.Panel.nav_subtitle
.. autoattribute:: debug_toolbar.panels.Panel.has_content
.. autoattribute:: debug_toolbar.panels.Panel.title
.. autoattribute:: debug_toolbar.panels.Panel.template
.. autoattribute:: debug_toolbar.panels.Panel.content
.. autoattribute:: debug_toolbar.panels.Panel.scripts
.. automethod:: debug_toolbar.panels.Panel.ready
.. automethod:: debug_toolbar.panels.Panel.get_urls
.. automethod:: debug_toolbar.panels.Panel.enable_instrumentation
.. automethod:: debug_toolbar.panels.Panel.disable_instrumentation
.. automethod:: debug_toolbar.panels.Panel.record_stats
.. automethod:: debug_toolbar.panels.Panel.get_stats
.. automethod:: debug_toolbar.panels.Panel.process_request
.. automethod:: debug_toolbar.panels.Panel.generate_server_timing
.. automethod:: debug_toolbar.panels.Panel.generate_stats
.. automethod:: debug_toolbar.panels.Panel.get_headers
.. automethod:: debug_toolbar.panels.Panel.run_checks
.. _javascript-api:
JavaScript API
~~~~~~~~~~~~~~
Panel templates should include any JavaScript files they need. There are a few
common methods available.
.. js:function:: djdt.close
Closes the topmost level (window/panel/toolbar)
.. js:function:: djdt.cookie.get(key)
This is a helper function to fetch values stored in the cookies.
:param key: The key for the value to be fetched.
.. js:function:: djdt.cookie.set(key, value, options)
This is a helper function to set a value stored in the cookies.
:param key: The key to be used.
:param value: The value to be set.
:param options: The options for the value to be set. It should contain the
properties ``expires`` and ``path``. The properties ``domain``,
``secure`` and ``samesite`` are also supported. ``samesite`` defaults
to ``lax`` if not provided.
.. js:function:: djdt.hide_toolbar
Closes any panels and hides the toolbar.
.. js:function:: djdt.show_toolbar
Shows the toolbar. This can be used to re-render the toolbar when reloading the
entire DOM. For example, then using `HTMX's boosting`_.
.. _HTMX's boosting: https://htmx.org/docs/#boosting
Events
^^^^^^
.. js:attribute:: djdt.panel.render
This is an event raised when a panel is rendered. It has the property
``detail.panelId`` which identifies which panel has been loaded. This
event can be useful when creating custom scripts to process the HTML
further.
An example of this for the ``CustomPanel`` would be:
.. code-block:: javascript
import { $$ } from "./utils.js";
function addCustomMetrics() {
// Logic to process/add custom metrics here.
// Be sure to cover the case of this function being called twice
// due to file being loaded asynchronously.
}
const djDebug = document.getElementById("djDebug");
$$.onPanelRender(djDebug, "CustomPanel", addCustomMetrics);
// Since a panel's scripts are loaded asynchronously, it's possible that
// the above statement would occur after the djdt.panel.render event has
// been raised. To account for that, the rendering function should be
// called here as well.
addCustomMetrics();