doc/book/pyramid/debug_toolbar.rst
author Laurent Peuch <cortex@worlddomination.be>
Wed, 18 Dec 2019 05:39:42 +0100
changeset 12819 053329493511
child 12852 a5c7cea1c070
permissions -rw-r--r--
[doc] document debug toolbar
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
12819
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
     1
.. _debug-toolbar_pyramid:
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
     2
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
     3
The pyramid debug toolbar
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
     4
=========================
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
     5
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
     6
The pyramid webserver comes with an integrated `debug toolbar
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
     7
<https://docs.pylonsproject.org/projects/pyramid_debugtoolbar/>`_ that offers a
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
     8
lot of information to ease development. To ease the development process in
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
     9
CubicWeb a series of custom debug panels have been developped especially for
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    10
that purpose.
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    11
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    12
To use the pyramid debug toolbar in CubicWeb, you need to:
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    13
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    14
* install it either by doing a `pip install pyramid_debugtoobar` or following
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    15
  `the official installation instructions
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    16
  <https://docs.pylonsproject.org/projects/pyramid_debugtoolbar/#installation>`_
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    17
* launch the pyramid command adding the `-t/--toolbar` argument to enable it
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    18
  like so: `cubicweb-ctl pyramid my_instance -t` (you probably want to add `-D`
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    19
  to activate the debug mode during development)
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    20
* navigate to the website and click on the icon on the right like on this screenshot:
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    21
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    22
.. image:: ../../images/debug_toolbar_icon.png
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    23
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    24
And you'll have access to the debug toolbar content for this page.
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    25
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    26
Custom panels
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    27
-------------
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    28
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    29
A series of custom debug panels have been written to offer more useful debug
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    30
information during development. Here is the list:
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    31
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    32
General 'CubicWeb' Panel
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    33
~~~~~~~~~~~~~~~~~~~~~~~~
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    34
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    35
Provides:
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    36
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    37
* currently selected controller for this with and uri/requests information
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    38
* current instance configuration, options that differs from default ones are in bold
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    39
* a list of useful links like on the default CW home
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    40
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    41
Screenshot:
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    42
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    43
.. image:: ../../images/debugtoolbar_general_panel.png
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    44
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    45
Registry Decisions Panel
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    46
~~~~~~~~~~~~~~~~~~~~~~~~
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    47
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    48
Provides:
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    49
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    50
* a list of all decisions taken in all registry during this page construction
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    51
* the arguments given to take the decision
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    52
* all the selection entities during decisions with their score
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    53
* which one has won if any
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    54
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    55
.. image:: ../../images/debugtoolbar_registry_decisions_panel.png
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    56
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    57
Registry Store
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    58
~~~~~~~~~~~~~~
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    59
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    60
Provides:
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    61
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    62
* a listing of all the content of the different registries
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    63
* for each entity its detailed information
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    64
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    65
.. image:: ../../images/debugtoolbar_registry_content_panel.png
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    66
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    67
RQL
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    68
~~~
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    69
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    70
Provides:
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    71
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    72
* a list of all executed RQL queries during this page creation
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    73
* for each RQL query all the generated SQL queries
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    74
* detail information like the result, the args and the description of each query
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    75
* the call stack on each query to see where it has been called
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    76
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    77
.. image:: ../../images/debugtoolbar_rql_panel.png
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    78
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    79
.. image:: ../../images/debugtoolbar_rql_traceback_panel.png
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    80
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    81
SQL
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    82
~~~
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    83
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    84
Provides:
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    85
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    86
* a list of all executed SQL queries during this page creation
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    87
* for each SQL query the RQL query that has generated it, if any (some aren't)
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    88
* detail information like the result, the args and if the query has rollback
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    89
* the call stack on each query to see where it has been called
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    90
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    91
.. image:: ../../images/debugtoolbar_sql_panel.png
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    92
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    93
Accessing the sources of the class/functions/method listing the debug panels
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    94
----------------------------------------------------------------------------
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    95
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    96
A traversal of all those custom panels is the see the source code of all
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    97
listing class/functions/methods. You can access those by:
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    98
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
    99
* clicking on the `[source]` close to the target when available
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
   100
* clicking on the file path in the traceback stack
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
   101
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
   102
.. image:: ../../images/debugtoolbar_show_source_link.png
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
   103
.. image:: ../../images/debugtoolbar_traceback_source_link.png
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
   104
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
   105
You be sent to a page looking like this:
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
   106
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
   107
.. image:: ../../images/debugtoolbar_show_source.png
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
   108
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
   109
Contributing
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
   110
------------
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
   111
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
   112
All source code for the custom panels is located `here
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
   113
<https://hg.logilab.org/master/cubicweb/file/tip/cubicweb/pyramid/debugtoolbar_panels.py>`_
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
   114
and the documentation of how to write `custom toolbar panels here
053329493511 [doc] document debug toolbar
Laurent Peuch <cortex@worlddomination.be>
parents:
diff changeset
   115
<https://docs.pylonsproject.org/projects/pyramid_debugtoolbar/en/latest/#adding-custom-panels>`_.