qtquick-profiler.qdoc 24.4 KB
Newer Older
1 2
/****************************************************************************
**
3 4
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
5
**
6
** This file is part of the Qt Creator documentation.
7
**
8 9 10 11 12 13 14
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
15
**
16
** GNU Free Documentation License Usage
17 18
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
19 20 21 22
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
23 24 25 26 27 28 29 30 31 32
**
****************************************************************************/

// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************

/*!
33
    \contentspage {Qt Creator Manual}
34 35
    \previouspage creator-analyze-mode.html
    \page creator-qml-performance-monitor.html
36
    \nextpage creator-valgrind-overview.html
37 38 39

    \title Profiling QML Applications

40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
    You can use the QML Profiler to find causes for typical performance problems
    in your applications, such as slowness and unresponsive, stuttering user
    interfaces. Typical causes include executing too much JavaScript in too few
    frames. All JavaScript must return before the GUI thread can proceed, and
    frames are delayed or dropped if the GUI thread is not ready.

    Another typical cause for similar performance problems is creating,
    painting, or updating invisible items, which takes time in the GUI thread.

    Triggering long-running C++ functions, such as paint methods and signal
    handlers, also takes time in the GUI thread, but is more difficult to see in
    the QML Profiler, because it does not profile C++ code.

    To find excessive use of JavaScript, check the frame rate in animations and
    Scene Graph events, look for gaps, and check whether the application behaves
    as expected. The JavaScript category displays the run time of functions,
    which you should try to keep below 16 ms per frame.

    To find problems caused by handling invisible items, look for dropped
    frames and check that you are not using too many short bindings or signal
    handlers that are updated per frame. You can also \l{Visualizing Overdraw}
    {visualize Scene Graph overdraw} to check scene layout and find items that
    are never visible to the users, because they are located outside the screen
    or hidden beneath other, visible elements.

    If frames get dropped even though JavaScript is not being run, and there are
    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.

    \section1 Using QML Profiler

72 73 74 75
    To monitor the performance of an application in the QML Profiler:

    \list 1

76
        \li To be able to profile an application, you must set up QML debugging
77 78 79
            for the project. For more information, see
            \l{Setting Up QML Debugging}.

80
        \li In the \uicontrol Projects mode, select a \l{glossary-buildandrun-kit}
81
            {kit} with Qt version 4.7.4 or later.
82 83 84 85

            \note To profile applications on devices, you must install Qt 4.7.4
            or later libraries on them.

86
        \li Select \uicontrol {Analyze > QML Profiler} to profile the current
87 88
            application.

89
        \li Select the
Leena Miettinen's avatar
Leena Miettinen committed
90
            \inlineimage qtcreator-analyze-start-button.png
91
            (\uicontrol Start) button to start the application from the
Leena Miettinen's avatar
Leena Miettinen committed
92
            QML Profiler.
93 94

            \note If data collection does not start automatically, select the
Leena Miettinen's avatar
Leena Miettinen committed
95
            \inlineimage qtcreator-analyzer-button.png
96
            (\uicontrol {Enable Profiling}) button.
97 98 99 100 101

    \endlist

    When you start analyzing an application, the application is launched, and
    the QML Profiler immediately begins to collect data. This is indicated by
102
    the time running in the \uicontrol Elapsed field.
103

104
    Data is collected until you select the \uicontrol {Enable Profiling} button. Data
105
    collection
Leena Miettinen's avatar
Leena Miettinen committed
106
    takes time, and therefore, there might be a delay
107 108 109
    before the data is displayed.

    Do not use application commands to exit the application, because data is
110
    sent to the QML Profiler when you select the \uicontrol {Enable Profiling} button.
111 112 113
    The application continues to run for some seconds, after which it is stopped
    automatically. If you exit the application, the data is not sent.

114
    Select the \uicontrol {Disable Profiling} button to disable the automatic
Leena Miettinen's avatar
Leena Miettinen committed
115
    start of the data collection when an
116 117 118
    application is launched. Data collection starts when you select the button
    again.

Leena Miettinen's avatar
Leena Miettinen committed
119
    To save all the collected data, right-click any QML Profiler view to open
120 121
    the context menu, and then select \uicontrol {Save QML Trace}. To view the saved
    data, select \uicontrol {Load QML Trace}. You can also deliver the saved data to
Leena Miettinen's avatar
Leena Miettinen committed
122
    other developers for examination or load data saved by them.
123 124 125 126 127 128 129 130

    \section1 Specifying Flushing Settings

    You can specify flushing settings for the QML Profiler either globally for
    all projects or separately for each project. To specify global settings,
    select \uicontrol Tools > \uicontrol Options > \uicontrol Analyzer.

    To specify custom QML Profiler settings for a particular project, select
131 132 133
    \uicontrol Projects > \uicontrol Run and then select \uicontrol Custom in
    \uicontrol {QML Profiler Settings}. To restore the global settings for the
    project, select \uicontrol {Restore Global}.
134 135 136 137 138 139 140 141 142 143 144 145 146

    \image qml-profiler-settings.png "QML Profiler Settings"

    Select the \uicontrol {Flush data while profiling} check box to flush the
    data periodically instead of flushing all data when profiling stops. This
    saves memory on the target device and shortens the wait between the
    profiling being stopped and the data being displayed.

    In the \uicontrol {Flush interval} field, set the flush interval in
    milliseconds. The shorter the interval, the more often the data is flushed.
    The longer the interval, the more data has to be buffered in the target
    application, potentially wasting memory. However, the flushing itself takes
    time, which can distort the profiling results.
Leena Miettinen's avatar
Leena Miettinen committed
147

148 149 150 151 152
    If you have multiple QML engines and you want to aggregate the data produced
    by all of them into one trace, select the \uicontrol {Process data only when
    process ends} check box. Otherwise, the profiling stops when one of the
    engines stops.

153 154 155
    \section1 Attaching to Running Qt Quick Applications

    To profile Qt Quick applications that are not launched by \QC, select
156
    \uicontrol {Analyze > QML Profiler (External)}. You must enable QML debugging and profiling for
157 158 159
    the application in the project build settings. For more information, see
    \l{Setting Up QML Debugging}.

160
    In the \uicontrol {QML Profiler} dialog, \uicontrol Port field, specify the port to
161 162
    listen to.

163 164
    \section1 Analyzing Collected Data

165
    The \uicontrol Timeline view displays graphical representations of QML and
166
    JavaScript execution and a condensed view of all recorded events.
167 168 169

    \image qtcreator-qml-performance-monitor.png "QML Profiler"

Leena Miettinen's avatar
Leena Miettinen committed
170 171 172
    Each row in the timeline (6) describes a type of QML events that were
    recorded. Move the cursor on an event on a row to see how long it takes and
    where in the source it is being called. To display the information only when
173
    an event is selected, disable the \uicontrol {View Event Information on Mouseover}
Leena Miettinen's avatar
Leena Miettinen committed
174 175 176 177
    button (5).

    The outline (10) summarizes the period for which data was collected. Drag
    the zoom range (8) or click the outline to move on the outline. You can
178 179
    also move between events by selecting the \uicontrol {Jump to Previous Event} (1)
    and \uicontrol {Jump to Next Event} (2) buttons.
Leena Miettinen's avatar
Leena Miettinen committed
180

181
    Select the \uicontrol {Show Zoom Slider} button (3) to open a slider that you can
Leena Miettinen's avatar
Leena Miettinen committed
182 183
    use to set the zoom level. You can also drag the zoom handles (9). To reset
    the default zoom level, right-click the timeline to open the context menu,
184
    and select \uicontrol {Reset Zoom}.
Leena Miettinen's avatar
Leena Miettinen committed
185 186 187 188 189

    \section2 Selecting Event Ranges

    You can select an event range (7) to view the frame rate of events and to
    compare it with the frame rate of similar events. Select the
190
    \uicontrol {Select Range} button (4) to activate the selection tool. Then click in
Leena Miettinen's avatar
Leena Miettinen committed
191 192 193 194 195 196
    the timeline to specify the beginning of the event range. Drag the selection
    handle to define the end of the range. The length of the range indicates the
    frame rate of the event.

    You can use event ranges also to measure delays between two subsequent
    events. Place a range between the end of the first event and the beginning
197
    of the second event. The \uicontrol Duration field displays the delay between the
Leena Miettinen's avatar
Leena Miettinen committed
198
    events in milliseconds.
199

Leena Miettinen's avatar
Leena Miettinen committed
200
    To zoom into an event range, double-click it.
201

202
    To remove an event range, close the \uicontrol Selection dialog.
203

204 205 206 207 208 209 210 211 212 213 214 215
    \section2 Understanding the Data

    Generally, events in the timeline view indicate how long QML or JavaScript
    execution took. Move the mouse over them to see details. For most events,
    they include location in source code, duration and some relevant parts of
    the source code itself.

    You can click on an event to move the cursor in the code editor to the part
    of the code the event is associated with.

    The following types of events are displayed in the timeline view on one or
    several rows. The availability of event types depends on the version of Qt
216
    the application was compiled with and the version of Qt Quick it is using.
217 218 219 220

    \table

    \header
221
        \li Event Category
222 223 224 225 226
        \li Description
        \li Minimum Qt Version
        \li Qt Quick Version

    \row
227
        \li \uicontrol {Pixmap Cache}
228 229 230 231 232 233 234
        \li Displays the general amount of pixmap data cached, in pixels. In
            addition, displays a separate event for each picture being loaded,
            with specifics about its file name and size.
        \li Qt 5.1
        \li Qt Quick 2

    \row
235
        \li \uicontrol {Scene Graph}
236 237 238 239 240
        \li Displays the time when scene graph frames are rendered and some
            additional timing information for the various stages executed to do
            so.
        \li Qt 5.1
        \li Qt Quick 2
241

242
    \row
243
        \li \uicontrol {Memory Usage}
244 245 246 247 248 249 250 251 252 253 254 255 256
        \li Displays block allocations of the JavaScript memory manager.
            Generally, the memory manager will reserve larger blocks of memory
            in one piece and later hand them out to the application in smaller
            bits. If the application requests single blocks of memory
            surpassing a certain size, the memory manager will allocate those
            separately. Those two modes of operation are shown as events of
            different colors.
            The second row displays the actual usage of the allocated memory.
            This is the amount of JavaScript heap the application has actually
            requested.
        \li Qt 5.4
        \li Qt Quick 2

257
    \row
258
        \li \uicontrol {Input Events}
259 260 261 262
        \li Displays mouse and keyboard events.
        \li Qt 4.7.4
        \li Qt Quick 1 or Qt Quick 2

263
    \row
264
        \li \uicontrol Painting
265 266 267 268 269
        \li Displays the time spent painting the scene for each frame.
        \li Qt 4.7.4
        \li Qt Quick 1

    \row
270
        \li \uicontrol Animations
271 272 273 274 275 276 277 278 279
        \li Displays the amount of animations that are active and the frame
            rate that they are running at.
            Information about render thread animations is displayed for
            applications that are built with Qt 5.3 or later. Render thread
            animations are shown in a separate row then.
        \li Qt 5.0 (Qt 5.3)
        \li Qt Quick 2

    \row
280
        \li \uicontrol Compiling
281 282 283 284 285
        \li Displays the time spent compiling the QML files.
        \li Qt 4.7.4
        \li Qt Quick 1 or Qt Quick 2

    \row
286
        \li \uicontrol Creating
287 288 289 290 291 292 293 294 295 296 297 298 299
        \li Displays the time spent creating the elements in the scene. In Qt
            Quick 2, creation of elements takes place in two stages. The first
            stage is for the creation of the data structures, including child
            elements. The second stage represents the completion callbacks. Not
            all elements trigger completion callbacks, though. The stages are
            shown as separate events in the timeline.
            For Qt Quick 2 applications compiled with versions of Qt before
            5.2.1 only the creation of top-level elements is shown, as single
            events.
        \li Qt 4.7.4 (Qt 5.2.1)
        \li Qt Quick 1 or Qt Quick 2

    \row
300
        \li \uicontrol Binding
301 302 303 304 305 306
        \li Displays the time when a binding is evaluated and how long the
            evaluation takes.
        \li Qt 4.7.4
        \li Qt Quick 1 or Qt Quick 2

    \row
307
        \li \uicontrol {Handling Signal}
308 309 310 311 312 313
        \li Displays the time when a signal is handled and how long the
            handling takes.
        \li Qt 4.7.4
        \li Qt Quick 1 or Qt Quick 2

    \row
314
        \li \uicontrol JavaScript
315 316 317 318 319 320 321
        \li Displays the time spent executing the actual JavaScript behind
            bindings and signal handlers. It lists all the JavaScript functions
            you may be using to evaluate bindings or handle signals.
        \li Qt 5.3
        \li Qt Quick 2

    \endtable
322

323 324 325 326 327 328
    \section2 Analyzing Scene Graph Events

    In order to understand the scene graph category, it's important to
    understand how the Qt Quick scene graph works. See
    \l {Qt Quick Scene Graph} and \l {Qt Quick Scene Graph Renderer} for a
    detailed description. The following events are reported in the
329
    \uicontrol {Scene Graph} category. Not all events are generated by all render
330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346
    loops. In the Windows and Basic render loops everything runs in the same
    thread and the distinction between GUI thread and render thread is
    meaningless.

    If you set the environment variable QSG_RENDER_TIMING, you get a textual
    output of similar, but slightly different timings from the application
    being profiled. For easier orientation, the differences are listed below.

    \table
    \header
        \li Event Type
        \li Thread
        \li Render Loop Types
        \li Label in output of QSG_RENDER_TIMING
        \li Description
        \li Caveats
    \row
347
        \li \uicontrol {Polish}
348 349 350 351 352 353 354 355
        \li GUI
        \li Threaded, Basic, Windows
        \li polish
        \li Final touch-up of items before they are rendered using
            QQuickItem::updatePolish().
        \li Versions of Qt prior to Qt 5.4 record no polish times for the basic
            render loop and incorrect ones for the windows render loop.
    \row
356
        \li \uicontrol {GUI Thread Wait}
357 358 359 360 361
        \li GUI
        \li Threaded
        \li lock
        \li Executing slots connected to the QQuickWindow::afterAnimating()
            signal and then locking the render thread's mutex before waiting on
362 363
            the same mutex at \uicontrol {GUI Thread Sync}. If this starts long
            before \uicontrol {Render Thread Sync}, there is \e free  time in the GUI
364 365 366
            thread you could be using for running additional QML or JavaScript.
        \li None
    \row
367
        \li \uicontrol {GUI Thread Sync}
368 369 370 371 372 373 374
        \li GUI
        \li Threaded
        \li blockedForSync
        \li The time the GUI thread is blocked, waiting for the render thread
            to synchronize the QML state into the scene graph.
        \li None
    \row
375
        \li \uicontrol {Animations}
376 377 378 379 380 381
        \li GUI
        \li Threaded, Windows
        \li animations
        \li Advancing animations in the GUI thread. The basic render loop does
            not drive animations in sync with the rendering. This is why no
            animation events will be shown when using the basic render loop.
382
            Watch the \uicontrol {Animations} category to see animation timing in
383 384 385
            this case.
        \li None
    \row
386
        \li \uicontrol {Render Thread Sync}
387 388 389 390 391 392 393
        \li Render
        \li Threaded, Basic, Windows
        \li Frame rendered ... sync
        \li Synchronizing the QML state into the scene graph using
            QQuickItem::updatePaintNode().
        \li None
    \row
394
        \li \uicontrol {Render}
395 396 397 398 399
        \li Render
        \li Threaded, Basic, Windows
        \li Frame rendered ... render
        \li Total time spent rendering the frame, including preparing and
            uploading all the necessary data to the GPU. This is the \e gross
400
            render time. Do not confuse it with the \e net \uicontrol{Render Render}
401 402 403 404
            time below.
        \li With versions of Qt prior to Qt 5.5, the gross render time and the
            below breakup of render times may be misaligned by some
            microseconds due to different, unsynchronized timers being used to
405 406
            measure them. For example \uicontrol {Render Preprocess} might seem to
            start before \uicontrol {Render Thread Sync} is finished.
407
    \row
408
        \li \uicontrol {Swap}
409 410 411 412 413 414 415 416
        \li Render
        \li Threaded, Basic, Windows
        \li Frame rendered ... swap
        \li Swapping frames after rendering.
        \li The output of swap times triggered by setting QSG_RENDER_TIMING is
            incorrect for the basic render loop and versions of Qt prior to
            Qt 5.4. The QML profiler shows the correct swap times.
    \row
417
        \li \uicontrol {Render Preprocess}
418 419 420 421
        \li Render
        \li Threaded, Basic, Windows
        \li time in renderer ... preprocess
        \li Calling QSGNode::preprocess() on all nodes that need to be
422 423
            preprocessed. This is part of the gross \uicontrol {Render} step.
        \li May not be properly aligned with \uicontrol {Render} with versions of Qt
424 425
            prior to Qt 5.5.
    \row
426
        \li \uicontrol {Render Update}
427 428 429 430 431
        \li Render
        \li Threaded, Basic, Windows
        \li time in renderer ... updates
        \li Iterating and processing all the nodes in the scene graph to update
            their geometry, transformations, opacity, and other state. In the
432 433
            \uicontrol {Render Thread Sync} stage, each node is updated separately
            with state from the GUI thread. In \uicontrol {Render Update}, all the
434
            nodes are combined to create the final scene. This is part of the
435 436
            gross \uicontrol {Render} step.
        \li May not be properly aligned with \uicontrol {Render} with versions of Qt
437 438
            prior to Qt 5.5.
    \row
439
        \li \uicontrol {Render Bind}
440 441 442 443
        \li Render
        \li Threaded, Basic, Windows
        \li time in renderer ... binding
        \li Binding the correct framebuffer for OpenGL rendering. This is part
444 445
            of the gross \uicontrol {Render} step.
        \li May not be properly aligned with \uicontrol {Render} with versions of Qt
446 447
            prior to Qt 5.5.
    \row
448
        \li \uicontrol {Render Render}
449 450 451 452
        \li Render
        \li Threaded, Basic, Windows
        \li time in renderer ... rendering
        \li The actual process of sending all the data to the GPU via OpenGL.
453 454
            This is part of the gross \uicontrol {Render} step.
        \li May not be properly aligned with \uicontrol {Render} with versions of Qt
455 456
            prior to Qt 5.5.
    \row
457
        \li \uicontrol {Material Compile}
458 459 460 461 462 463
        \li Render
        \li Threaded, Basic, Windows
        \li shader compiled
        \li Compiling GLSL shader programs.
        \li None
    \row
464
        \li \uicontrol {Glyph Render}
465 466 467 468 469 470 471
        \li Render
        \li Threaded, Basic, Windows
        \li glyphs ... rendering
        \li Rendering of font glyphs into textures.
        \li Versions of Qt prior to Qt 5.4 report incorrect times for these
            events.
    \row
472
        \li \uicontrol {Glyph Upload}
473 474 475 476 477 478 479
        \li Render
        \li Threaded, Basic, Windows
        \li glyphs ... upload
        \li Uploading of glyph textures to the GPU.
        \li Versions of Qt prior to Qt 5.4 report incorrect times for these
            events.
    \row
480
        \li \uicontrol {Texture Bind}
481 482 483 484 485 486
        \li Render
        \li Threaded, Basic, Windows
        \li plain texture ... bind
        \li Binding a texture in the OpenGL context using glBindTextures.
        \li None
    \row
487
        \li \uicontrol {Texture Convert}
488 489 490 491 492 493 494
        \li Render
        \li Threaded, Basic, Windows
        \li plain texture ... convert
        \li Converting the format and downscaling an image to make it suitable
            for usage as a texture.
        \li None
    \row
495
        \li \uicontrol {Texture Swizzle}
496 497 498 499 500 501
        \li Render
        \li Threaded, Basic, Windows
        \li plain texture ... swizzle
        \li Swizzling the texture data on the CPU if necessary.
        \li None
    \row
502
        \li \uicontrol {Texture Upload}
503 504 505 506 507 508
        \li Render
        \li Threaded, Basic, Windows
        \li plain texture ... upload / atlastexture uploaded
        \li Uploading the texture data to the GPU.
        \li None
    \row
509
        \li \uicontrol {Texture Mipmap}
510 511 512 513 514 515
        \li Render
        \li Threaded, Basic, Windows
        \li plain texture ... mipmap
        \li Mipmapping a texture on the GPU.
        \li None
    \row
516
        \li \uicontrol {Texture Delete}
517 518 519 520 521 522 523
        \li Render
        \li Threaded, Basic, Windows
        \li plain texture deleted
        \li Deleting a texture from the GPU that became unnecessary.
        \li None
    \endtable

524
    \section1 Viewing Statistics
525

526
    The \uicontrol Statistics view displays the number of times each binding, create,
527 528 529 530
    compile, JavaScript, or signal event is triggered and the average time it
    takes. This allows you to examine which events you need to optimize. A high
    number of occurrences might indicate that an event is triggered
    unnecessarily. To view the median, longest, and shortest time for the
531
    occurrences, select \uicontrol {Extended Event Statistics} in the context menu.
532 533

    Click on an event to move to it in the source code
534 535
    in the code editor.

536
    \image qml-profiler-statistics.png "Statistics view"
537

538
    The \uicontrol Callers and \uicontrol Callees panes show dependencies between events.
539
    They allow you to examine the internal functions of the application.
540
    The \uicontrol Callers pane summarizes the QML events that trigger a binding.
Leena Miettinen's avatar
Leena Miettinen committed
541
    This tells you what caused a change in a binding.
542
    The \uicontrol Callees pane summarizes the QML events that a binding triggers.
543 544
    This tells you which QML events are affected if you change a binding.

545
    Click on an event to move to it in the source code in the code editor.
546

547
    When you select an event in the \uicontrol Timeline view, information about it is
548
    displayed in the \uicontrol Statistics view. To view an event range in the
549
    \uicontrol Statistics view, select \uicontrol {Analyze Current Range}
550
    in the context menu in the \uicontrol Timeline view.
551

Leena Miettinen's avatar
Leena Miettinen committed
552
    To copy the contents of one view or row to the clipboard, select
553
    \uicontrol {Copy Table} or \uicontrol {Copy Row} in the context menu.
554

555
    JavaScript events are shown in the \uicontrol Statistics view only for applications
Ulf Hermann's avatar
Ulf Hermann committed
556
    that use Qt Quick 2 and are compiled with Qt 5.3 or later.
557 558 559 560 561 562 563 564 565 566 567 568 569 570

    \section2 Visualizing Statistics as Flame Graphs

    The \uicontrol Flamegraph view shows a more concise statistical overview
    of QML and JavaScript execution. The horizontal bars show the amount of
    time all invocations of a certain function took together, relative to the
    total runtime of all JavaScript and QML events. The nesting shows which
    functions were called by which other ones. Mind that, unlike the
    \uicontrol Timeline view, the \uicontrol Flamegraph view does not show the
    time spans when no QML or JavaScript is running at all. Thus, it is not
    suitable for analyzing per frame execution times. However, it is very easy
    to see the total impact of the various QML and JavaScript events there.

    \image qml-profiler-flamegraph.png "Flame Graph View"
571
*/