[Minios-devel] [UNIKRAFT PATCH 8/8] doc/guides: Add section about tracepoints

[Yuri Volchkov <yuri.volchkov@xxxxxxxxx>]

Signed-off-by: Yuri Volchkov <yuri.volchkov@xxxxxxxxx>
---
 doc/guides/developers-debugging.rst | 48 +++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/doc/guides/developers-debugging.rst 
b/doc/guides/developers-debugging.rst
index 0e8799c4..cc7bc0ea 100644
--- a/doc/guides/developers-debugging.rst
+++ b/doc/guides/developers-debugging.rst
@@ -72,3 +72,51 @@ You can then connect gdb within a separate console and 
you're ready to debug: ::
 You should be also able to use the debugging file
 (``build/helloworld_linuxu-x86_64.dbg``) for gdb instead passing the kernel
 image.
+
+============================
+Trace points
+============================
+
+Tracepoints are provided by libukdebug. To make Unikraft collect
+tracing data enable the option `CONFIG_LIBUKDEBUG_TRACEPOINTS` in your
+config (via ``make menuconfig``).
+
+Because tracepoints can noticeably affect performance, selective
+enabling is implemented. Option `CONFIG_LIBUKDEBUG_TRACEPOINTS` just
+enables the functionality, but all the tracepoints are compiled into
+nothing by default (have no effect). If you would like one library to
+collect tracing data, add to it's Makefile.uk ::
+
+   LIBAPPNAME_CFLAGS += -DUK_DEBUG_TRACE
+
+If you need just the information about tracepoints in one file, just
+define `UK_DEBUG_TRACE` **before** ``#include <uk/trace.h>``.
+
+If you wish to enable **ALL** existing tracepoints, enable
+`CONFIG_LIBUKDEBUG_ALL_TRACEPOINTS` in menuconfig.
+
+To read the collected data you have 2 options:
+
+1. Inside gdb
+
+2. Using trace.py
+
+For the first option, attach gdb to your running instance, and load
+Unikraft gdb extension: ::
+
+  source support/scripts/uk-gdb.py
+
+Now you can print tracing log by issuing command ``uk
+trace``. Alternatively, you can save all trace data into a binary file
+with ``uk trace save <filename>``. This tracefile can be processed
+later offline with trace.py script: ::
+
+  support/scripts/trace.py list <filename>
+
+Which brings us to the second option. Trace.py can run gdb and fetch
+the tracefile for you. Just run: ::
+
+  support/scripts/trace.py fetch  <your_unikraft_image>.dbg
+
+.. note:: The *.dbg image is required, as it have offline data needed
+          for parsing the trace buffer.
-- 
2.19.2


_______________________________________________
Minios-devel mailing list
Minios-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/minios-devel