qtquick-profiler.qdoc 8.69 KB
Newer Older
1
2
/****************************************************************************
**
3
** Copyright (c) 2013 Digia Plc and/or its subsidiary(-ies).
hjk's avatar
hjk committed
4
** Contact: http://www.qt-project.org/legal
5
**
hjk's avatar
hjk committed
6
** This file is part of Qt Creator
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
**
**
** GNU Free Documentation License
**
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
**
****************************************************************************/

// **********************************************************************
// 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.
// **********************************************************************

/*!
    \contentspage index.html
    \previouspage creator-analyze-mode.html
    \page creator-qml-performance-monitor.html
29
    \nextpage creator-valgrind-overview.html
30
31
32
33
34
35
36

    \title Profiling QML Applications

    To monitor the performance of an application in the QML Profiler:

    \list 1

37
        \li To be able to profile an application, you must set up QML debugging
38
39
40
            for the project. For more information, see
            \l{Setting Up QML Debugging}.

41
42
        \li In the \gui Projects mode, select a \l{glossary-buildandrun-kit}
            {kit} with Qt version 4.7.4 or later.
43
44
45
46

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

47
        \li Select \gui {Analyze > QML Profiler} to profile the current
48
49
            application.

50
        \li Select the
Leena Miettinen's avatar
Leena Miettinen committed
51
52
            \inlineimage qtcreator-analyze-start-button.png
            (\gui Start) button to start the application from the
Leena Miettinen's avatar
Leena Miettinen committed
53
            QML Profiler.
54
55

            \note If data collection does not start automatically, select the
Leena Miettinen's avatar
Leena Miettinen committed
56
57
            \inlineimage qtcreator-analyzer-button.png
            (\gui {Enable Profiling}) button.
58
59
60
61
62

    \endlist

    When you start analyzing an application, the application is launched, and
    the QML Profiler immediately begins to collect data. This is indicated by
Leena Miettinen's avatar
Leena Miettinen committed
63
    the time running in the \gui Elapsed field.
64

Leena Miettinen's avatar
Leena Miettinen committed
65
66
67
    Data is collected until you select the
    \inlineimage qtcreator-debug-button-stop.png
    (\gui Stop) button. Data collection
Leena Miettinen's avatar
Leena Miettinen committed
68
    takes time, and therefore, there might be a delay
69
70
71
72
73
74
75
    before the data is displayed.

    Do not use application commands to exit the application, because data is
    sent to the QML Profiler when you select the \gui Stop button.
    The application continues to run for some seconds, after which it is stopped
    automatically. If you exit the application, the data is not sent.

Leena Miettinen's avatar
Leena Miettinen committed
76
    Select the \gui {Disable Profiling} button to disable the automatic
Leena Miettinen's avatar
Leena Miettinen committed
77
    start of the data collection when an
78
79
80
    application is launched. Data collection starts when you select the button
    again.

Leena Miettinen's avatar
Leena Miettinen committed
81
82
83
84
85
    To save all the collected data, right-click any QML Profiler view to open
    the context menu, and then select \gui {Save QML Trace}. To view the saved
    data, select \gui {Load QML Trace}. You can also deliver the saved data to
    other developers for examination or load data saved by them.

86
87
88
    \section1 Attaching to Running Qt Quick Applications

    To profile Qt Quick applications that are not launched by \QC, select
89
    \gui {Analyze > QML Profiler (External)}. You must enable QML debugging for
90
91
92
93
94
95
    the application in the project build settings. For more information, see
    \l{Setting Up QML Debugging}.

    In the \gui {QML Profiler} dialog, \gui Port field, specify the port to
    listen to.

96
97
98
99
100
    \section1 Analyzing Collected Data

    The \gui Timeline view displays graphical representations of:

    \list
101
102
103
104
105
    \if defined(enterprise)
        \li Pixmap loading times and cache sizes

        \li Scene graph events
    \endif
106

107
        \li Painting operations
108

109
        \li Compiling the QML sources
110

111
        \li Creating items using QML types
112

113
        \li Binding evaluations
114

115
        \li Signal handling
116

117
        \li Summary of the recorded period
118
119
120

    \endlist

121
122
123
124
125
126
    \if defined(enterprise)
    Information about the pixmap cache and scene graph events are only available
    from Qt 5.1 onwards.

    \image qtcreator-qml-performance-monitor-enterprise.png "QML Profiler"
    \else
127
    \image qtcreator-qml-performance-monitor.png "QML Profiler"
128
    \endif
129

Leena Miettinen's avatar
Leena Miettinen committed
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
    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
    an event is selected, disable the \gui {View Event Information on Mouseover}
    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
    also move between events by selecting the \gui {Jump to Previous Event} (1)
    and \gui {Jump to Next Event} (2) buttons.

    Select the \gui {Show Zoom Slider} button (3) to open a slider that you can
    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,
    and select \gui {Reset Zoom}.

    \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
    \gui {Select Range} button (4) to activate the selection tool. Then click in
    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
    of the second event. The \gui Duration field displays the delay between the
    events in milliseconds.
159

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

Leena Miettinen's avatar
Leena Miettinen committed
162
    To remove an event range, close the \gui Selection dialog.
163

Leena Miettinen's avatar
Leena Miettinen committed
164
    \section2 Evaluating Bindings
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183

    On the \gui Binding row, you can see when a binding is evaluated and how
    long the evaluation takes. Move the mouse over the binding for details
    about the binding: location in the source code, duration, and source
    code.

    Click the binding to move the cursor in the code editor to the part of the
    code where the binding is called.

    \section1 Viewing Events

    The \gui Events view displays the number of times each binding is called
    and the time the calls take. This allows you to examine which events you
    need to optimize. A high number of calls might indicate that a binding is
    called unnecessarily. Click on a binding to move to it in the source code
    in the code editor.

    \image qtcreator-analyzer-bindings.png "Events view"

Leena Miettinen's avatar
Leena Miettinen committed
184
    The \gui Callers and \gui Callees panes show dependencies between events.
185
    They allow you to examine the internal functions of the application.
Leena Miettinen's avatar
Leena Miettinen committed
186
187
188
    The \gui Callers pane summarizes the QML events that trigger a binding.
    This tells you what caused a change in a binding.
    The \gui Callees pane summarizes the QML events that a binding triggers.
189
190
    This tells you which QML events are affected if you change a binding.

Leena Miettinen's avatar
Leena Miettinen committed
191
    Click on a binding to move to it in the source code in the code editor.
192

Leena Miettinen's avatar
Leena Miettinen committed
193
194
195
196
    When you select an event in the \gui Timeline view, information about it is
    displayed in the \gui Events view. To view an event range in the \gui Events
    view, select \gui {Limit Events Pane to Current Range} in the context menu
    in the \gui Timeline view.
197

Leena Miettinen's avatar
Leena Miettinen committed
198
199
    To copy the contents of one view or row to the clipboard, select
    \gui {Copy Table} or \gui {Copy Row} in the context menu.
200

Leena Miettinen's avatar
Leena Miettinen committed
201
202
203
204
    You can view similar information about JavaScript events in the
    \gui JavaScript view.

    \image qml-profiler-javascript.png "JavaScript view"
205
206
207
208
209
210

    \section2 Viewing More Data

    The QML JavaScript engine optimizes trivial bindings. The QML Profiler
    does not receive information about optimized bindings, and
    therefore, it displays the text \gui {<bytecode>} and the message
Leena Miettinen's avatar
Leena Miettinen committed
211
212
    \gui {Source code not available} in the \gui Callers and \gui {Callees}
    panes.
213
214
215
216
217
218
219

    To inspect the optimized bindings, turn off the QML optimizer by setting the
    environment variable QML_DISABLE_OPTIMIZER to 1. To set the environment
    variable for the current project in the project settings:

    \list 1

220
        \li Select \gui {Projects > Run}.
221

222
        \li In \gui {Run Environment}, click \gui Add.
223

224
        \li Add the QML_DISABLE_OPTIMIZER variable and set its value to 1.
225
226
227
228

    \endlist

*/