From feeaf8a01596123edabe1cccc268783e05c13c27 Mon Sep 17 00:00:00 2001 From: Aymeric Augustin Date: Mon, 11 Nov 2013 22:53:55 +0100 Subject: Rewrite performance docs to reflect recent improvements. --- docs/tips.rst | 69 +++++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 48 insertions(+), 21 deletions(-) (limited to 'docs') diff --git a/docs/tips.rst b/docs/tips.rst index d92e5ab..25aed5e 100644 --- a/docs/tips.rst +++ b/docs/tips.rst @@ -13,32 +13,59 @@ requests and return responses. Putting the debug toolbar middleware *after* the Flatpage middleware, for example, means the toolbar will not show up on flatpages. - Performance considerations -------------------------- -The Debug Toolbar adds some overhead to the rendering of each page. Depending -on your project, this overhead may slow down page loads significantly. If that -makes development impractical, you can disable the most expensive features to -restore decent response times. +The Debug Toolbar is designed to introduce as little overhead as possible in +the rendering of pages. However, depending on your project, the overhad may +become noticeable. In extreme cases, it can make development impractical. +Here's a breakdown of the performance issues you can run into and their +solutions. + +Problems +~~~~~~~~ + +The Debug Toolbar works in two phases. First, it gathers data while Django +handles a request and stores this data in memory. Second, when you open a +panel in the browser, it fetches the data on the server and displays it. + +If you're seeing excessive CPU or memory consumption while browsing your site, +you must optimize the "gathering" phase. If displaying a panel is slow, you +must optimize the "rendering" phase. + +Culprits +~~~~~~~~ The SQL panel may be the culprit if your view performs many SQL queries. You should attempt to minimize the number of SQL queries, but this isn't always -possible, for instance if you're using a CMS and have turned off caching for -development. In that case, setting ``ENABLE_STACKTRACES`` to ``False`` in the -``DEBUG_TOOLBAR_CONFIG`` setting will help. +possible, for instance if you're using a CMS and have disabled caching for +development. The cache panel is very similar to the SQL panel, except it isn't always a bad -practice to make many cache queries in a view. Setting ``ENABLE_STACKTRACES`` -to ``False`` will help there too. - -The template panel may be slow if your views or context processors return -large contexts and your templates have complex inheritance or inclusion -schemes. In that case, you should set ``SHOW_TEMPLATE_CONTEXT`` to ``False`` -in the ``DEBUG_TOOLBAR_CONFIG`` setting. - -If you don't need the panels that are slowing down your application, you can -disable them temporarily by deselecting the checkbox at the top right of each -panel. Depending on implementation details, there may be a residual overhead. -To remove them entirely, you can customize the ``DEBUG_TOOLBAR_PANELS`` -setting to include only the panels you actually use. +practice to make many cache queries in a view. + +The template panel becomes slow your views or context processors return large +contexts and your templates have complex inheritance or inclusion schemes. + +Solutions +~~~~~~~~~ + +If the "gathering" phase is too slow, you can disable problematic panels +temporarily by deselecting the checkbox at the top right of each panel. That +change will apply to the next request. If you don't use some panels at all, +you can remove them permanently by customizing the ``DEBUG_TOOLBAR_PANELS`` +setting. + +By default, data gathered during the last 10 requests is kept in memory. This +allows you to use the toolbar on a page even if you have browsed to a few +other pages since you first loaded that page. You can reduce memory +consumption by setting the ``PANELS_CACHE_SIZE`` configuration option to a +lower value. At worst, the toolbar will tell you that the data you're looking +for isn't available anymore. + +If the "rendering" phase is too slow, refrain from clicking on problematic +panels :) Or reduce the amount of data gathered and rendered by these panels +by disabling some configuration options that are enabled by default: + +- ``ENABLE_STACKTRACES`` for the SQL and cache panels, +- ``SHOW_TEMPLATE_CONTEXT`` for the template panel. -- cgit v1.2.3