1 .. -*- coding: utf-8 -*-

     2 

     3 .. _debug_channels:

     4 

     5 Debug Channels

     6 ==============

     7 

     8 In *CubicWeb* 3.27 a new debug channels mechanism has been added to help build

     9 the pyramid debug toolbar custom panels. It isn't meant to do regular CW

    10 development but can be used for tools building (like the custom panel) if desired.

    11 

    12 The API is really simple to use and is used like this:

    13 

    14 .. code-block:: python

    15 

    16     from cubicweb.debug import subscribe_to_debug_channel, unsubscribe_to_debug_channel

    17 

    18 

    19     # the callback will only receive one argument which is a python dict

    20     # containing debug information

    21     def example_debug_callback(message):

    22         print(message)

    23 

    24 

    25     # "channel" must be one of: controller, rql, sql, vreg, registry_decisions

    26     subscribe_to_debug_channel(channel, example_debug_callback)

    27 

    28     # when it is not needed anymore (and to avoid dandling references)

    29     unsubscribe_to_debug_channel(channel, example_debug_callback)

    30 

    31 Channels documentation

    32 ----------------------

    33 

    34 The list of sent messages by channels:

    35 

    36 Controller

    37 ~~~~~~~~~~

    38 

    39 **This debug message will only be sent in a pyramid context**.

    40 Emitted for each request.

    41 

    42 .. code-block:: python

    43 

    44     {

    45         "kind": ctrlid,

    46         "request": request_object,

    47         "path": request_object.path,

    48         "controller": controller,

    49         "config": repo_configuration,

    50     }

    51 

    52 RQL

    53 ~~~

    54 

    55 Emitted for each query.

    56 

    57 .. code-block:: python

    58 

    59     {

    60         "rql": rql_as_a_string,

    61         # arguments used to format the query

    62         "args": args,

    63         # used to link rql and sql queries

    64         "rql_query_tracing_token": rql_query_tracing_token,

    65         "callstack": python_call_stack,

    66         "time": time_taken_in_ms_by_the_query,

    67         "result": the_result_as_python_data,

    68         "description": description_object,

    69     }

    70 

    71 SQL

    72 ~~~

    73 

    74 Emitted for each query. Be advised that a SQL query generated by a RQL query

    75 will be emitted before the corresponding RQL query.

    76 

    77 .. code-block:: python

    78 

    79     {

    80         "sql": sql_as_a_string,

    81         # arguments used to format the query

    82         "args": args,

    83         "rollback": True|False,

    84         "callstack": "".join(traceback.format_stack()[:-1]),

    85         # used to link rql and sql queries

    86         "rql_query_tracing_token": rql_query_tracing_token,

    87         "time": time_taken_in_ms_by_the_query,

    88     }

    89 

    90 vreg

    91 ~~~~

    92 

    93 **This debug message will only be sent in a pyramid context**.

    94 Emitted for each request.

    95 

    96 .. code-block:: python

    97 

    98     {

    99         "vreg": vreg,

   100     }

   101 

   102 registry_decisions

   103 ~~~~~~~~~~~~~~~~~~

   104 

   105 This is emitted each time a decision is taken in a registry.

   106 

   107 .. code-block:: python

   108 

   109     {

   110         "all_objects": [],

   111         "end_score": int,

   112         "winners": [],

   113         "winner": obj or None,

   114         "registry": obj,

   115         "args": args,

   116         "kwargs": kwargs,

   117     }

   118 

   119 API Reference

   120 =============

   121 

   122 .. autofunction:: cubicweb.debug.subscribe_to_debug_channel

   123 .. autofunction:: cubicweb.debug.unsubscribe_to_debug_channel