author | Laurent Peuch <cortex@worlddomination.be> |
Thu, 19 Dec 2019 06:33:49 +0100 | |
changeset 12831 | b1ef9690f357 |
parent 12818 | 3954554f5b48 |
permissions | -rw-r--r-- |
12818
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
1 |
.. -*- coding: utf-8 -*- |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
2 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
3 |
.. _debug_channels: |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
4 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
5 |
Debug Channels |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
6 |
============== |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
7 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
8 |
In *CubicWeb* 3.27 a new debug channels mechanism has been added to help build |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
9 |
the pyramid debug toolbar custom panels. It isn't meant to do regular CW |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
10 |
development but can be used for tools building (like the custom panel) if desired. |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
11 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
12 |
The API is really simple to use and is used like this: |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
13 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
14 |
.. code-block:: python |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
15 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
16 |
from cubicweb.debug import subscribe_to_debug_channel, unsubscribe_to_debug_channel |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
17 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
18 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
19 |
# the callback will only receive one argument which is a python dict |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
20 |
# containing debug information |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
21 |
def example_debug_callback(message): |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
22 |
print(message) |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
23 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
24 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
25 |
# "channel" must be one of: controller, rql, sql, vreg, registry_decisions |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
26 |
subscribe_to_debug_channel(channel, example_debug_callback) |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
27 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
28 |
# when it is not needed anymore (and to avoid dandling references) |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
29 |
unsubscribe_to_debug_channel(channel, example_debug_callback) |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
30 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
31 |
Channels documentation |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
32 |
---------------------- |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
33 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
34 |
The list of sent messages by channels: |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
35 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
36 |
Controller |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
37 |
~~~~~~~~~~ |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
38 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
39 |
**This debug message will only be sent in a pyramid context**. |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
40 |
Emitted for each request. |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
41 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
42 |
.. code-block:: python |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
43 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
44 |
{ |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
45 |
"kind": ctrlid, |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
46 |
"request": request_object, |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
47 |
"path": request_object.path, |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
48 |
"controller": controller, |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
49 |
"config": repo_configuration, |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
50 |
} |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
51 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
52 |
RQL |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
53 |
~~~ |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
54 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
55 |
Emitted for each query. |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
56 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
57 |
.. code-block:: python |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
58 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
59 |
{ |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
60 |
"rql": rql_as_a_string, |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
61 |
# arguments used to format the query |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
62 |
"args": args, |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
63 |
# used to link rql and sql queries |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
64 |
"rql_query_tracing_token": rql_query_tracing_token, |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
65 |
"callstack": python_call_stack, |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
66 |
"time": time_taken_in_ms_by_the_query, |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
67 |
"result": the_result_as_python_data, |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
68 |
"description": description_object, |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
69 |
} |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
70 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
71 |
SQL |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
72 |
~~~ |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
73 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
74 |
Emitted for each query. Be advised that a SQL query generated by a RQL query |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
75 |
will be emitted before the corresponding RQL query. |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
76 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
77 |
.. code-block:: python |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
78 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
79 |
{ |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
80 |
"sql": sql_as_a_string, |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
81 |
# arguments used to format the query |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
82 |
"args": args, |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
83 |
"rollback": True|False, |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
84 |
"callstack": "".join(traceback.format_stack()[:-1]), |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
85 |
# used to link rql and sql queries |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
86 |
"rql_query_tracing_token": rql_query_tracing_token, |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
87 |
"time": time_taken_in_ms_by_the_query, |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
88 |
} |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
89 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
90 |
vreg |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
91 |
~~~~ |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
92 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
93 |
**This debug message will only be sent in a pyramid context**. |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
94 |
Emitted for each request. |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
95 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
96 |
.. code-block:: python |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
97 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
98 |
{ |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
99 |
"vreg": vreg, |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
100 |
} |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
101 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
102 |
registry_decisions |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
103 |
~~~~~~~~~~~~~~~~~~ |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
104 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
105 |
This is emitted each time a decision is taken in a registry. |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
106 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
107 |
.. code-block:: python |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
108 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
109 |
{ |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
110 |
"all_objects": [], |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
111 |
"end_score": int, |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
112 |
"winners": [], |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
113 |
"winner": obj or None, |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
114 |
"registry": obj, |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
115 |
"args": args, |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
116 |
"kwargs": kwargs, |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
117 |
} |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
118 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
119 |
API Reference |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
120 |
============= |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
121 |
|
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
122 |
.. autofunction:: cubicweb.debug.subscribe_to_debug_channel |
3954554f5b48
[doc] document new debug channels mechanism
Laurent Peuch <cortex@worlddomination.be>
parents:
diff
changeset
|
123 |
.. autofunction:: cubicweb.debug.unsubscribe_to_debug_channel |