[Minios-devel] [UNIKRAFT PATCH] doc: Update tracepoint section under debugging

[Simon Kuenzer <simon.kuenzer@xxxxxxxxx>]

Updates the debugging documentation: tracepoints

Signed-off-by: Simon Kuenzer <simon.kuenzer@xxxxxxxxx>
---
 doc/guides/developers-debugging.rst | 185 ++++++++++++++--------------
 1 file changed, 95 insertions(+), 90 deletions(-)

diff --git a/doc/guides/developers-debugging.rst 
b/doc/guides/developers-debugging.rst
index 49207397..b80a39b0 100644
--- a/doc/guides/developers-debugging.rst
+++ b/doc/guides/developers-debugging.rst
@@ -100,105 +100,129 @@ You should be also able to use the debugging file
 image.
 
 ============================
-Trace points
+Tracepoints
 ============================
 
 ----------------------------
 Dependencies
 ----------------------------
-The file ``support/scripts/uk_trace/trace.py`` depends on the click
-and tabulate Python modules; you can install them by running: ::
+We provide some tools to read and export trace data that were collected with
+Unikraft's tracepoint system. The tools depend on Python3, as well as the
+`click` and `tabulate` modules. You can install them by running
+(Debian/Ubuntu):
 
-  sudo apt-get install python3-click python3-tabulate
+.. code-block:: sh
 
-Or, you can install trace.py into a local virtual environment: ::
+  sudo apt-get install python3 python3-click python3-tabulate
 
-  python3 -m venv env
-  . env/bin/activate
-  cd support/scripts/uk_trace
-  pip install --upgrade pip setuptools wheel
-  pip install --editable .
-  deactivate
-  cd -
+----------------
+Enabling Tracing
+----------------
+Tracepoints are provided by `lib/ukdebug`. To enable Unikraft to collect
+trace data, enable the option ``CONFIG_LIBUKDEBUG_TRACEPOINTS`` in your
+configuration (via ``make menuconfig`` under `Library Configuration` ->
+`ukdebug` -> `Enable tracepoints`).
 
-All the dependencies will be installed in the 'env' folder, not
-your machine. You do not have to enter your virtual environment, you
-can call the installed script directly: ::
+The configuration option ``CONFIG_LIBUKDEBUG_ALL_TRACEPOINTS`` activates
+**all** existing tracepoints. Because tracepoints may noticeably
+affect performance, you can alternatively enable tracepoints only for
+compilation units that you are interested in.
 
-  env/bin/uk-trace --help
+This can be done with the ``Makefile.uk`` of each library:
 
-Because of the ``--editable`` flag, any modifications made to
-``support/scripts/uk_trace/trace.py`` will be reflected in the
-installed file.
+.. code-block:: make
 
-----------------------------
-Reading Tracepoints
-----------------------------
+   # Enable tracepoints for a whole library
+   LIBNAME_CFLAGS-y += -DUK_DEBUG_TRACE
+   LIBNAME_CXXFLAGS-y += -DUK_DEBUG_TRACE
 
-Tracepoints are provided by ``libukdebug``. To make Unikraft collect
-tracing data, enable the option ``CONFIG_LIBUKDEBUG_TRACEPOINTS`` in your
-config (via ``make menuconfig``).
+   # Alternatively, enable tracepoints of source files you are interested in
+   LIBNAME_FILENAME1_FLAGS-y += -DUK_DEBUG_TRACE
+   LIBNAME_FILENAME2_FLAGS-y += -DUK_DEBUG_TRACE
 
-Because tracepoints can noticeably affect performance, selective
-enabling is implemented. The ``CONFIG_LIBUKDEBUG_TRACEPOINTS`` option
-just enables the functionality, but all the tracepoints are compiled
-into nothing by default (i.e., they have no effect). If you would like
-a library to collect tracing data, add the following to its Makefile.uk: ::
+This can also be done by defining ``UK_DEBUG_TRACE`` in the head of your source
+file(s). Please make sure that ``UK_DEBUG_TRACE`` is defined **before**
+``<uk/trace.h>`` is included:
 
-.. code-block:: make
+.. code-block:: c
 
-   LIBAPPNAME_CFLAGS += -DUK_DEBUG_TRACE
+   #ifndef UK_DEBUG_TRACE
+   #define UK_DEBUG_TRACE
+   #endif
 
-If you need just the information about tracepoints in one file, define
-``UK_DEBUG_TRACE`` **before** ``#include <uk/trace.h>``.
+   #include <uk/trace.h>
 
-If you wish to enable **ALL** existing tracepoints, enable
-``CONFIG_LIBUKDEBUG_ALL_TRACEPOINTS`` in menuconfig.
+As soon as tracing is enabled, Unikraft will store samples of each enabled
+tracepoint into an internal trace buffer. Currently this is not a circular
+buffer. This means that as soon as it is full, Unikraft will stop collecting
+further samples.
 
-When tracing is enabled, Unikraft will write samples into an internal
-trace buffer. Currently this is not a circular buffer, so as soon as
-it overflows, Unikraft will stop collecting data.
+------------------
+Reading Trace Data
+------------------
+Unikraft is storing trace data to an internal buffer that resides in the
+guest's main memory. You can use `gdb` to read and export it.
+For this purpose, you will need to load ``uk-gdb.py`` helper into your
+`gdb` session. It adds additional commands that allow you to list and store
+the trace data. We recommend to automatically load the script to `gdb`.
+For this purpose, add the following line to your
+``~/.gdbinit``: ::
 
-To read the collected data you have 2 options:
+  source /path/to/your/build/uk-gdb.py
 
-1. Use gdb
+In order to collect the data, open `gdb` with the debug image and connect to
+your Unikraft instance as described in Section :ref:`Using GDB`:
 
-2. Use trace.py
+.. code-block:: sh
 
-For the first option, you need the 'uk-gdb.py' helper loaded into the
-gdb session. To make this happen all you need to do is add the
-following line into ~/.gdbinit: ::
+  gdb helloworld/build/helloworld_kvm-x86_64.dbg
 
-  add-auto-load-safe-path /path/to/your/build/directory
+.. note:: The ``.dbg`` image is required because it contains offline data 
needed
+          for parsing the trace buffer.
 
-With this, gdb will load the helper automatically each time you start gdb
-with a \*.dbg image. For example ::
+As soon as you let run your guest, samples should be stored in Unikraft's trace
+buffer. You can print them by issuing the `gdb` command ``uk trace``: ::
 
-  gdb helloworld/build/helloworld_kvm-x86_64.dbg
+  (gdb) uk trace
 
-Now you can print the tracing log by issuing the 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 using the trace.py script: ::
+Alternatively, you can save all trace data to disk with
+``uk trace save <filename>``: ::
 
-  support/scripts/uk_trace/trace.py list <filename>
+  (gdb) uk save traces.dat
 
-Which brings us to the second option: trace.py can run gdb and fetch
-the tracefile for you. Just run: ::
+.. note:: It may make sense to connect with `gdb` after the guest execution has
+         been finished (and the trace buffer got filled). For this purpose,
+         make sure that your hypervisor is not destroying the instance after
+         guest shut down (on `qemu`, add ``--no-shutdown`` and ``--no-reboot``
+         parameters).
 
-  support/scripts/uk_trace/trace.py fetch  <your_unikraft_image>.dbg
+.. note:: If you are seeing the error message
+         ``Error getting the trace buffer. Is tracing enabled?``, you
+         probably did not enable tracing or Unikraft's trace buffer is
+         empty. This can happen when no tracepoint was ever called.
 
-.. note:: The \*.dbg image is required, as it have offline data needed
-          for parsing the trace buffer.
 
-----------------------------
-Adding your tracepoints
-----------------------------
-Bellow is a snippet for using tracepoints:
+Any saved trace file can be later processed with the ``trace.py`` script.
+In our example:
+
+.. code-block:: sh
+
+  support/scripts/uk_trace/trace.py list traces.dat
+
+--------------------
+Creating Tracepoints
+--------------------
+Instrumenting your code with tracepoints is done by two steps. First, you 
define
+and register a tracepoint handler with the ``UK_TRACEPOINT()`` macro.
+Second, you place calls to the generated handler at those places in your code
+where your want to trace an event:
 
 .. code-block:: c
 
+  #include <uk/trace.h>
+
   UK_TRACEPOINT(trace_vfs_open, "\"%s\" 0x%x 0%0o", const char*, int, mode_t);
+
   int open(const char *pathname, int flags, ...)
   {
        trace_vfs_open(pathname, flags, mode);
@@ -208,30 +232,11 @@ Bellow is a snippet for using tracepoints:
        return 0;
   }
 
-The macro ``UK_TRACEPOINT(trace_name, fmt, type1, type2, ... typeN)``
-generates a static function `trace_name()`, accepting N parameters of
-types **type1**, **type2** and so on. Up to 7 parameters are supported. The
-**fmt** is a printf-style format which will be used to form a message
-corresponding to the trace sample.
-
-The **fmt** is static and stored offline. Only parameter values are
-saved on the trace buffer. It is the job of the offline parser to
-match them together and print out resulting messages.
-
-Now you can call the generated function from the point of
-interest. You are expected to call one tracepoint from exactly one
-place in your code.
-
-----------------------------
-Troubleshooting
-----------------------------
-If you are getting the message::
-
-  Error getting the trace buffer. Is tracing enabled?
-
-This might be because:
-
-1. You indeed need to enable tracing.
-
-2. Not a single tracepoint has been called, and dead-code elimination
-   removed (rightfully) the tracing functionality.
+``UK_TRACEPOINT(trace_name, fmt, type1, type2, ... typeN)`` generates
+the handler ``trace_name()`` (static function). It will accept up
+to 7 parameters of type ``type1``, ``type2``, etc. The given format string
+``fmt`` is a `printf`-style format which will be used to create meaningful
+messages based on the collected trace parameters. This format string is
+only kept in the debug image and is used by the tools to read and parse the
+trace data. Unikraft's trace buffer stores for each sample a timestamp,
+the name of the tracepoint, and the given parameters.
-- 
2.20.1


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