From 5f8fe92105444ca3d49d263d4960ce9957fdbbc4 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Tue, 14 Jan 2020 14:45:08 +0100 Subject: 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 --- doc/src/analyze/creator-ctf-visualizer.qdoc | 129 +++++++++++++++++++++++++++- doc/src/qtquick/qtquick-profiler.qdoc | 7 +- 2 files changed, 134 insertions(+), 2 deletions(-) (limited to 'doc') 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 -- cgit v1.2.1