# HG changeset patch
# User Laurent Peuch <cortex@worlddomination.be>
# Date 1576018224 -3600
# Node ID 3954554f5b4868f3765fc6a4c75c0195e9bf1f96
# Parent  91bb2f0fbadd1f2e56b92209e96e6fc8a07a9cce
[doc] document new debug channels mechanism

diff -r 91bb2f0fbadd -r 3954554f5b48 doc/book/devrepo/debug_channels.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/devrepo/debug_channels.rst	Tue Dec 10 23:50:24 2019 +0100
@@ -0,0 +1,123 @@
+.. -*- 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
diff -r 91bb2f0fbadd -r 3954554f5b48 doc/book/devrepo/index.rst
--- a/doc/book/devrepo/index.rst	Tue Dec 17 21:20:46 2019 +0100
+++ b/doc/book/devrepo/index.rst	Tue Dec 10 23:50:24 2019 +0100
@@ -23,3 +23,4 @@
    profiling.rst
    fti.rst
    dataimport
+   debug_channels