From 28b08874aedee8fbc09d08a3693053dfba5dafa2 Mon Sep 17 00:00:00 2001 From: Kefu Chai Date: Tue, 1 Jun 2021 19:58:47 +0800 Subject: [PATCH] doc/mgr/modules: add a "debugging" section Signed-off-by: Kefu Chai --- doc/mgr/modules.rst | 64 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/doc/mgr/modules.rst b/doc/mgr/modules.rst index 4064e34114ec..9fb3b87ae3f3 100644 --- a/doc/mgr/modules.rst +++ b/doc/mgr/modules.rst @@ -46,6 +46,8 @@ Note that the MgrModule interface is not stable, so any modules maintained outside of the Ceph tree are liable to break when run against any newer or older versions of Ceph. +.. _mgr module dev logging: + Logging ------- @@ -465,6 +467,68 @@ this point will result in an assertion failure in ceph-mgr. For modules that implement the ``serve()`` method, it usually makes sense to do most initialization inside that method instead. +Debugging +--------- + +Apparently, we can always use the :ref:`mgr module dev logging` facility +for debugging a ceph-mgr module. But some of us might miss `PDB`_ and the +interactive Python interpreter. Yes, we can have them as well when developing +ceph-mgr modules! ``ceph_mgr_repl.py`` can drop you into an interactive shell +talking to ``selftest`` module. With this tool, one can peek and poke the +ceph-mgr module, and use all the exposed facilities in quite the same way +how we use the Python command line interpreter. For using ``ceph_mgr_repl.py``, +we need to + +#. ready a Ceph cluster +#. enable the ``selftest`` module +#. setup the necessary environment variables +#. launch the tool + +.. _PDB: https://docs.python.org/3/library/pdb.html + +Following is a sample session, in which the Ceph version is queried by +inputting ``print(mgr.version)`` at the prompt. And later +``timeit`` module is imported to measure the execution time of +`mgr.get_mgr_id()`. + +.. code-block:: console + + $ cd build + $ MDS=0 MGR=1 OSD=3 MON=1 ../src/vstart.sh -n -x + $ bin/ceph mgr module enable selftest + $ ../src/pybind/ceph_mgr_repl.py --show-env + $ export PYTHONPATH=/home/me/ceph/src/pybind:/home/me/ceph/build/lib/cython_modules/lib.3:/home/me/ceph/src/python-common:$PYTHONPATH + $ export LD_LIBRARY_PATH=/home/me/ceph/build/lib:$LD_LIBRARY_PATH + $ export PYTHONPATH=/home/me/ceph/src/pybind:/home/me/ceph/build/lib/cython_modules/lib.3:/home/me/ceph/src/python-common:$PYTHONPATH + $ export LD_LIBRARY_PATH=/home/me/ceph/build/lib:$LD_LIBRARY_PATH + $ ../src/pybind/ceph_mgr_repl.py + $ ../src/pybind/ceph_mgr_repl.py + Python 3.9.2 (default, Feb 28 2021, 17:03:44) + [GCC 10.2.1 20210110] on linux + Type "help", "copyright", "credits" or "license" for more information. + (MgrModuleInteractiveConsole) + [mgr self-test eval] >>> print(mgr.version) + ceph version Development (no_version) quincy (dev) + [mgr self-test eval] >>> from timeit import timeit + [mgr self-test eval] >>> timeit(mgr.get_mgr_id) + 0.16303414600042743 + [mgr self-test eval] >>> + +If you want to "talk" to a ceph-mgr module other than ``selftest`` using +this tool, you can either add a command to the module you want to debug +exactly like how ``mgr self-test eval`` command was added to ``selftest``. Or +we can make this simpler by promoting the ``eval()`` method to a dedicated +`Mixin`_ class and inherit your ``MgrModule`` subclass from it. And define +a command with it. Assuming the prefix of the command is ``mgr my-module eval``, +one can just put + +.. prompt:: bash $ + + ../src/pybind/ceph_mgr_repl.py --prefix "mgr my-module eval" + + +.. _Mixin: _https://en.wikipedia.org/wiki/Mixin + Is something missing? --------------------- -- 2.47.3