From 853f85ea868e8b5b392ef0322d941bb8fd0ad109 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Blin?=
 <sebastien.blin@savoirfairelinux.com>
Date: Fri, 4 Nov 2022 09:03:38 -0400
Subject: [PATCH] developer: add documentation about debugging tools

Change-Id: I63687b39a2203202e638fd6d0357fde698a8e168
---
 developer/debugging-tools.rst | 71 +++++++++++++++++++++++++++++++++++
 developer/index.rst           |  1 +
 2 files changed, 72 insertions(+)
 create mode 100644 developer/debugging-tools.rst

diff --git a/developer/debugging-tools.rst b/developer/debugging-tools.rst
new file mode 100644
index 00000000..1203d8ca
--- /dev/null
+++ b/developer/debugging-tools.rst
@@ -0,0 +1,71 @@
+Debugging Tools
+---------------
+
+There are several ways to debug Jami from a developer perspective, depending on what you want to debug.
+
+Loggers
+~~~~~~~
+
+The first way is to use runtime loggers. Starting `jami` with `-d` will enable logging by the deamon
+(or the Troubleshoot section in the General settings). Because Jami uses several libraries, we do not
+enable all logs by default. But you can pass some environment variables to show it:
+
++ `SIPLOGLEVEL=5` for enabling logs from PJSIP.
++ `DHTLOGLEVEL=5` for enabling logs from OpenDHT.
++ `AVLOGLEVEL=50` for enabling logs from ffmpeg.
+
+Debuggers
+~~~~~~~~~
+
+Generally your IDE has an embedded debuggger. Else, you can use `gdb` for example to be able to
+add breakpoints, backtraces from crashes, print internal structures, etc. You need to compile the
+project in *DEBUG* mode to get debug symbols.
+
+Some useful commands:
+
++ `b file.cpp:line` - Add a breakpoint (*file.cpp:line* can be replaced by a symbol)
++ `t a a bt` - (thread apply all backtrace) to get all backtraces
++ `Ctrl + X / A` - pass in graphical view
++ `p` - print an internal value.
+
+Profilers
+~~~~~~~~~
+
+Debuggers are useful, but they do not show real-time memory consumption/network activity/CPU usage.
+For this, you can use the embedded profiler in your IDE (from Android Studio or Qt Creator/Visual Studio
+for example).
+
+Address Sanitizer
+~~~~~~~~~~~~~~~~~
+
+This can be useful to detect leaks, crashes, potential deadlocks at runtime. To enable this, you can
+compile the daemon with `CXXFLAGS+="-fsanitize=address"`. Other flags like `tsan` may be useful.
+
+Valgrind/Callgrind
+~~~~~~~~~~~~~~~~~~
+
+Valgrind is a tool to watch allocations, CPU usage and more and can be used via:
+`valgrind --tool=callgrind ./jami -d`. This will make the application very slow but can provide useful
+reports about memory allocation/performance usage (**KCacheGrind** can be used to read reports).
+
+Tests
+~~~~~
+
+Daemon has many tests and coverage enabled. If the daemon is built in static (else private symbols will
+not be available), adding new tests can help to reproduce bugs, solve bugs and avoid any regression.
+(cf. `daemon/tests/unitTests``)
+
+Agent
+~~~~~
+
+Tests are only using one daemon to simulate both peers. So it can be difficult to test in various
+environments. Another possibility is to write a scenario and run an agent (documentation is available
+in the daemon's repository).
+
+LTTng
+~~~~~
+
+Finally, tracepoints can be created and analyzed. `daemon/tools/trace` provide the documentation
+and some examples. The advantage of LTTng is that it is quicker than logs, can be triggered by system
+events and can be used with tracepoints already present in the kernel (so that it can be used with
+tracepoints from network interfaces).
\ No newline at end of file
diff --git a/developer/index.rst b/developer/index.rst
index fb9dab1a..e961937b 100644
--- a/developer/index.rst
+++ b/developer/index.rst
@@ -21,6 +21,7 @@ designed and how its various parts work together.
    setting-up-your-own-turn-server
    synchronizing-profiles
    submitting-your-first-patch
+   debugging-tools
    feature-requests
    connection-manager
    calls-in-swarm
-- 
GitLab