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

.. _debug_channels:

Debug Channels
==============

In *CubicWeb* 3.27 a new debug channels mechanism has been added to help build
the pyramid debug toolbar custom panels. It isn't meant to do regular CW
development but can be used for tools building (like the custom panel) if desired.

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

.. code-block:: python

    from cubicweb.debug import subscribe_to_debug_channel, unsubscribe_to_debug_channel


    # the callback will only receive one argument which is a python dict
    # containing debug information
    def example_debug_callback(message):
        print(message)


    # "channel" must be one of: controller, rql, sql, vreg, registry_decisions
    subscribe_to_debug_channel(channel, example_debug_callback)

    # when it is not needed anymore (and to avoid dandling references)
    unsubscribe_to_debug_channel(channel, example_debug_callback)

Channels documentation
----------------------

The list of sent messages by channels:

Controller
~~~~~~~~~~

**This debug message will only be sent in a pyramid context**.
Emitted for each request.

.. code-block:: python

    {
        "kind": ctrlid,
        "request": request_object,
        "path": request_object.path,
        "controller": controller,
        "config": repo_configuration,
    }

RQL
~~~

Emitted for each query.

.. code-block:: python

    {
        "rql": rql_as_a_string,
        # arguments used to format the query
        "args": args,
        # used to link rql and sql queries
        "rql_query_tracing_token": rql_query_tracing_token,
        "callstack": python_call_stack,
        "time": time_taken_in_ms_by_the_query,
        "result": the_result_as_python_data,
        "description": description_object,
    }

SQL
~~~

Emitted for each query. Be advised that a SQL query generated by a RQL query
will be emitted before the corresponding RQL query.

.. code-block:: python

    {
        "sql": sql_as_a_string,
        # arguments used to format the query
        "args": args,
        "rollback": True|False,
        "callstack": "".join(traceback.format_stack()[:-1]),
        # used to link rql and sql queries
        "rql_query_tracing_token": rql_query_tracing_token,
        "time": time_taken_in_ms_by_the_query,
    }

vreg
~~~~

**This debug message will only be sent in a pyramid context**.
Emitted for each request.

.. code-block:: python

    {
        "vreg": vreg,
    }

registry_decisions
~~~~~~~~~~~~~~~~~~

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

.. code-block:: python

    {
        "all_objects": [],
        "end_score": int,
        "winners": [],
        "winner": obj or None,
        "registry": obj,
        "args": args,
        "kwargs": kwargs,
    }

API Reference
=============

.. autofunction:: cubicweb.debug.subscribe_to_debug_channel
.. autofunction:: cubicweb.debug.unsubscribe_to_debug_channel