doc/dev: Debuggging with gdb

Signed-off-by: Matan Breizman <mbreizma@redhat.com>

diff --git a/doc/dev/developer_guide/debugging-gdb.rst b/doc/dev/developer_guide/debugging-gdb.rst
new file mode 100644 (file)
index 0000000..18aed02
--- /dev/null
+++ b/doc/dev/developer_guide/debugging-gdb.rst
@@ -0,0 +1,43 @@
+GDB - The GNU Project Debugger
+==============================
+
+`The GNU Project Debugger (GDB) <https://www.sourceware.org/gdb>`_ is
+a powerful tool that allows you to analyze the execution flow
+of a process.
+GDB can help to find bugs, uncover crash errors or track the
+source code during execution of a development cluster.
+It can also be used to debug Teuthology tests runs.
+
+GET STARTED WITH GDB
+--------------------
+
+Basic usage with examples can be found `here. <https://geeksforgeeks.org/gdb-command-in-linux-with-examples>`_
+GDB can be attached to a running process. For instance, after deploying a
+development cluster, the process number (PID) of a ``ceph-osd`` daemon can be found in::
+
+    $ cd build
+    $ cat out/osd.0.pid
+
+Attaching gdb to the process::
+
+    $ gdb ./bin/ceph-osd -p <pid>
+
+.. note::
+    It is recommended to compile without any optimizations (``-O0`` gcc flag)
+    in order to avoid elimintaion of intermediate values.
+
+Stopping for breakpoints while debugging may cause timeouts, so the following
+configuration options are suggested::
+
+        [osd]
+        osd_op_thread_timeout = 1500
+        osd_op_thread_suicide_timeout = 1500
+
+Debugging Teuthology Tests
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``src/script/ceph-debug-docker.sh`` can be used to analyze Teuthology failures::
+
+    $ ./ceph-debug-docker.sh <branch-name>
+
+Refer to the script header for more information.

diff --git a/doc/dev/developer_guide/index.rst b/doc/dev/developer_guide/index.rst
index a924adf11349dbf6eecc091174fb7d06805d9fd3..e9832bea6019a884ce1090f3de54f0b2bacb53de 100644 (file)
--- a/doc/dev/developer_guide/index.rst
+++ b/doc/dev/developer_guide/index.rst
@@ -22,3 +22,4 @@ Contributing to Ceph: A Guide for Developers
    Ceph Dashboard Developer Documentation (formerly HACKING.rst) <dash-devel>
    Tracing Developer Documentation <jaegertracing>
    Cephadm Developer Documentation  <../cephadm/index>
+   Debugging with GDB <debugging-gdb>