Doc: Describe collecting LTTng data and converting it into CTF

...for viewing in the Chrome Trace Format Visualizer.

Based on a QtWS19 talk by Milian Wolff:
https://resources.qt.io/qt-world-summit-2019/lttng-for-full-stack-tracing

Fixes: QTCREATORBUG-23471
Change-Id: I173aa68e7198c7f13aecb73f28000af02d7ec0ed
Reviewed-by: Milian Wolff <milian.wolff@kdab.com>

2 files changed, 134 insertions, 2 deletions

diff --git a/doc/src/analyze/creator-ctf-visualizer.qdoc b/doc/src/analyze/creator-ctf-visualizer.qdoc
index 20362accbe..e9680897d3 100644
--- a/doc/src/analyze/creator-ctf-visualizer.qdoc
+++ b/doc/src/analyze/creator-ctf-visualizer.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2019 The Qt Company Ltd.
+** Copyright (C) 2020 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -37,6 +37,19 @@
 
     \title Visualizing Chrome Trace Events
 
+    You can use \e {full stack tracing} to trace from the top level QML or
+    JavaScript down to the C++ and all the way to the kernel space. This
+    enables you to measure the performance of an application and to check
+    whether it is CPU or I/O bound or influenced by other applications
+    running on the same system. Tracing provides insight into what a system is
+    doing and why an application is performing in a particular way. It indicates
+    how the hardware is utilized and what the kernel and application are doing.
+
+    Tracing information can also provide you additional insight into the data
+    collected by \l{Profiling QML Applications}{QML Profiler}. For example, you
+    could check why a trivial binding evaluation is taking so long. This might
+    be caused by C++ being executed or the disk I/O being slow.
+
     Several tracing tools (such as \c {chrome://about}) can generate information
     about Chrome trace events in Chrome Trace Format (CTF). You can open CTF
     files in \QC for viewing. This is especially useful when viewing trace files
@@ -110,4 +123,118 @@
     stack (called \c self). This allows you to examine which functions you need
     to optimize. A high number of occurrences might indicate that a function is
     triggered unnecessarily or takes very long to execute.
+
+    \section1 Collecting LTTng Data
+
+    LTTng is a tracing toolkit for Linux that you can apply on embedded Linux
+    systems to find out how to optimize the startup time of an application.
+
+    Since Qt 5.13, Qt provides a set of kernel trace points and a tracing
+    subsystem for custom user space trace points.
+
+    \section2 Configuring the Kernel
+
+    To use LTTng, you have to set the following configuration options for the
+    kernel before building it:
+
+    \list
+        \li \c CONFIG_HIGH_RES_TIMERS
+        \li \c CONFIG_KALLSYMS
+        \li \c CONFIG_MODULES
+        \li \c CONFIG_TRACEPOINTS
+    \endlist
+
+    We recommend that you set the following additional options:
+
+    \list
+        \li \c CONFIG_EVENT_TRACING
+        \li \c CONFIG_HAVE_SYSCALL_TRACEPOINTS
+        \li \c CONFIG_KALLSYMS_ALL
+    \endlist
+
+    In Yocto, you can activate the above options in \uicontrol Menu >
+    \uicontrol Config > \uicontrol {Kernel Hacking} > \uicontrol Tracers.
+
+    \section2 Installing LTTng
+
+    After you build the kernel and deploy it on your device, you'll need to
+    install the following LTTng packages on your device:
+
+     \list
+        \li \c lttng-tools to control the tracing session
+        \li \c lttng-modules for kernel trace points
+        \li \c lttng-ust for user space trace points
+    \endlist
+
+    In Yocto, you just need to enable
+    \c {EXTRA_IMAGE_FEATURES += "tools profile"}.
+
+    \section2 Building Qt with Tracepoints
+
+    Trace points are continuously being added to Qt versions. To use them, you
+    need to build Qt yourself with the \c {configure -trace lttng} option.
+
+    \section2 Recording Events
+
+    To create a session, you call the \c {lttng create} command. Then you
+    call \c {lttng enable-channel kernel -k} to enable the kernel channel.
+    Within the kernel channel, you specify the appropriate trace points as
+    \c {kernel_events} and call \c {lttng enable-event} to enable them.
+    Finally, you call \c {lttng start} to start tracing.
+
+    You call \c {lttng stop} to stop tracing. You can use \c sleep to set the
+    length of the session. After stopping, you can call \c {lttng destroy} to
+    destroy the session.
+
+    You can write and run scripts that contain the above commands to start and
+    stop full-stack tracing. You can use \c systemd to execute the scripts.
+
+    \section2 Enabling Trace Points
+
+    Data is recorded according to the trace points that you enable in the LTTng
+    session. Usually, it is useful to enable scheduler switch, syscall, and Qt
+    trace points.
+
+    \section3 Scheduler Switch Trace Points
+
+    Scheduler switch trace points are reached when an application is switched
+    out due to predemption, for example, when another process gets the chance
+    to run on the CPU core. Enable scheduler schwitch trace points to record
+    the thread that is currently running and the process it belongs to, as
+    well as the time when the process started and stopped.
+
+    \section3 Syscall Trace Points
+
+    Syscall trace points help you to understand why a scheduler switch happened.
+    The following are examples of syscalls to trace:
+
+    \list
+        \li \c openat and \c close map file descriptors to file names
+        \li \c mmap maps page faults to files
+        \li \c read and \c write are triggered by I/O operations
+        \li \c nanosleep, \c futex, and \c poll explain scheduler switches
+        \li \c ioctl controls the GPU and display
+    \endlist
+
+    \section1 Converting LTTng Data to CTF
+
+    The \l{https://github.com/KDAB/ctf2ctf}{ctf2ctf} tool uses \c babeltrace to
+    parse binary Common Trace Format (CTF) and converts it to Chrome Trace
+    Format (CTF). It performs the following custom tasks to make the recording
+    more human-readable:
+
+    \list
+        \li Map file descriptors to file names
+        \li Map page faults to file names
+        \li Annotate interrupts and block devices with names
+        \li Convert UTF-16 QString data to UTF-8 strings
+        \li Count memory page allocations
+    \endlist
+
+    To generate JSON files that contain the trace data in Chrome Trace Format,
+    enter the following command on the command line:
+
+    \code
+    ctf2ctf -o trace.json path/to/lttng trace/
+    \endcode
 */
diff --git a/doc/src/qtquick/qtquick-profiler.qdoc b/doc/src/qtquick/qtquick-profiler.qdoc
index fef88195d7..7b8936b911 100644
--- a/doc/src/qtquick/qtquick-profiler.qdoc
+++ b/doc/src/qtquick/qtquick-profiler.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2019 The Qt Company Ltd.
+** Copyright (C) 2020 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -74,6 +74,11 @@
     large, unexplained gaps in the timeline, check your custom QQuickItem
     implementations. You can use \l{Using Valgrind Code Analysis Tools}
     {Valgrind} or other general purpose profilers to analyze C++ code.
+
+    You can use \e {full stack tracing} to trace from the top level QML or
+    JavaScript down to the C++ and all the way to the kernel space. You can
+    view the collected data in the \l{Visualizing Chrome Trace Events}
+    {Chrome Trace Format Viewer}.
     \endif
 
     \section1 Using QML Profiler