Skip to content

Commit 4f089c1

Browse files
antfitchantfitch
authored
Update performance profiling docs. (#11688)
_Description of what this PR is changing or adding, and why:_ This is part of one of our goals to make it easier for iOS developers to work with our docs. iOS devs are having a particularly difficult time with debugging and performance. This guide is full of great information, but it's been added to over the years by many contributors and looks like it has started to lose its original form. I've taken a shot at condensing all of the materials that have been added over the years and making this doc easier to parse in a linear fashion. I worked on it a bit more than intended, so if the changes are too much in one PR, no worries at all. I can always split this up. Changes: - Created an overview and moved the various notes and conceptual details into this overview. - The overview now has a list of performance analysis tools that the developer can browse with links to the documentation elsewhere. - Tried to make it more clear that this page is specifically about the Performance Overlay tool, but more might be needed. - A few sections in the doc weren't about the Performance Overlay tool, so I moved them into the bulleted list in the overview with links to their documentation (the sections were very small, so this was pretty easy). - Changed some headings, and moved some sections around. - Moved all of the links to the bottom of the topic and alphabetically sorted them (to match the pattern i've seen elsewhere the most often.) _Issues fixed by this PR (if any):_ _PRs or commits this PR depends on (if any):_ ## Presubmit checklist - [x] This PR is marked as draft with an explanation if not meant to land until a future stable release. - [x] This PR doesn’t contain automatically generated corrections (Grammarly or similar). - [x] This PR follows the [Google Developer Documentation Style Guidelines](https://developers.google.com/style) — for example, it doesn’t use _i.e._ or _e.g._, and it avoids _I_ and _we_ (first person). - [x] This PR uses [semantic line breaks](https://github.com/dart-lang/site-shared/blob/main/doc/writing-for-dart-and-flutter-websites.md#semantic-line-breaks) of 80 characters or fewer.
1 parent ef96f99 commit 4f089c1

File tree

1 file changed

+87
-128
lines changed

1 file changed

+87
-128
lines changed

‎src/content/perf/ui-performance.md

+87-128
Original file line numberDiff line numberDiff line change
@@ -4,50 +4,52 @@ subtitle: Where to look when your Flutter app drops frames in the UI.
44
description: Diagnosing UI performance issues in Flutter.
55
---
66

7-
{% render docs/performance.md %}
8-
9-
:::secondary What you'll learn
10-
* Flutter aims to provide 60 frames per second (fps) performance,
11-
or 120 fps performance on devices capable of 120Hz updates.
12-
* For 60fps, frames need to render approximately every 16ms.
13-
* Jank occurs when the UI doesn't render smoothly. For example,
14-
every so often, a frame takes 10 times longer to render,
15-
so it gets dropped, and the animation visibly jerks.
16-
:::
17-
18-
It's been said that "a _fast_ app is great,
19-
but a _smooth_ app is even better."
20-
If your app isn't rendering smoothly,
21-
how do you fix it? Where do you begin?
22-
This guide shows you where to start,
23-
steps to take, and tools that can help.
24-
25-
:::note
26-
* An app's performance is determined by more than one measure.
27-
Performance sometimes refers to raw speed, but also to the UI's
28-
smoothness and lack of stutter. Other examples of performance
29-
include I/O or network speed. This page primarily focuses on the
30-
second type of performance (UI smoothness), but you can use most
31-
of the same tools to diagnose other performance problems.
32-
* To perform tracing inside your Dart code, see [Tracing Dart code][]
33-
in the [Debugging][] page.
34-
:::
35-
36-
[Debugging]: /testing/debugging
7+
## Overview
8+
9+
App performance encompasses various aspects, from raw speed and I/O throughput
10+
to the smoothness of the user interface. While this page primarily focuses on UI
11+
smoothness (lack of stutter or jank), the tools described here can often be used
12+
to diagnose other performance issues as well.
13+
14+
Flutter offers several tools for performance analysis. Here are a few of them:
15+
16+
* **The Performance Overlay**: Displays a simplified set of metrics directly
17+
within your running app. To learn more, see the sections in this topic.
18+
19+
* **The Performance View**: A web-based interface that connects to your app and
20+
displays detailed performance metrics. Part of the DevTools utility. To learn
21+
more, see [Use the Performance View][].
22+
23+
* **Performance tracing within Dart**: Add tracing directly into your app's
24+
Dart code, using the `dart:developer package`, and then track your app's
25+
performance in the DevTools utility. To learn more, see [Tracing Dart code][].
26+
27+
* **Benchmarking**: You can measure and track your app's performance by writing
28+
benchmark tests. The Flutter Driver library provides support
29+
for benchmarking. Using this integration test framework,
30+
you can generate metrics that track jank, download size, battery efficiency,
31+
and startup time. For more information, check out [Integration testing][].
32+
33+
* **Widget rebuild profiler (IntelliJ for Android Studio)**: Jank often arises
34+
from unnecessary UI rebuilds. If you are using IntelliJ for Android Studio,
35+
the Widget Rebuild Profiler helps pinpoint and fix these issues by showing
36+
widget rebuild counts for the current screen and frame. For more information,
37+
see [Show performance data][].
38+
39+
Flutter aims to provide 60 frames per second (fps) performance,
40+
or 120 fps on devices that support it. To achieve the 60fps, each frame must
41+
render approximately every 16ms to avoid jank. Jank occurs when frames take
42+
significantly longer to render and are dropped, resulting in a visible stutter
43+
in animations. For example, if a frame occasionally takes 10 times longer than
44+
usual to render, it will likely be dropped, causing the animation to appear
45+
jerky.
46+
47+
[Use the Performance View]: /tools/devtools/performance
3748
[Tracing Dart code]: /testing/code-debugging#trace-dart-code-performance
49+
[Show performance data]: /tools/android-studio#show-performance-data
50+
[Integration testing]: /testing/integration-tests
3851

39-
## Diagnosing performance problems
40-
41-
To diagnose an app with performance problems, you'll enable
42-
the performance overlay to look at the UI and raster threads.
43-
Before you begin, make sure that you're running in
44-
[profile mode][], and that you're not using an emulator.
45-
For best results, you might choose the slowest device that
46-
your users might use.
47-
48-
[profile mode]: /testing/build-modes#profile
49-
50-
### Connect to a physical device
52+
## Connect to a physical device
5153

5254
Almost all performance debugging for Flutter applications
5355
should be conducted on a physical Android or iOS device,
@@ -72,7 +74,7 @@ on the slowest device that your users might reasonably use._
7274
compilation, which itself can cause jank.
7375
:::
7476

75-
### Run in profile mode
77+
## Run in profile mode
7678

7779
Flutter's profile mode compiles and launches your application
7880
almost identically to release mode, but with just enough additional
@@ -87,9 +89,6 @@ Use Chrome DevTools to
8789
[generate timeline events][] for a web app.
8890
:::
8991

90-
[generate timeline events]: {{site.developers}}/web/tools/chrome-devtools/evaluate-performance/performance-reference
91-
92-
9392
Launch the app in profile mode as follows:
9493

9594
* In VS Code, open your `launch.json` file, and set the
@@ -121,6 +120,7 @@ You'll begin by opening DevTools and viewing
121120
the performance overlay, as discussed in the next section.
122121

123122
[Flutter's build modes]: /testing/build-modes
123+
[generate timeline events]: {{site.developers}}/web/tools/chrome-devtools/evaluate-performance/performance-reference
124124

125125
## Launch DevTools
126126

@@ -133,12 +133,32 @@ UI performance of your application on a frame-by-frame basis.
133133
Once your app is running in profile mode,
134134
[launch DevTools][].
135135

136-
[launch DevTools]: /tools/devtools
137136
[Timeline view]: /tools/devtools/performance
137+
[launch DevTools]: /tools/devtools
138+
139+
## Display the performance overlay {:#displaying-the-performance-overlay}
140+
141+
You can toggle the display of the performance overlay as
142+
follows:
143+
144+
* **DevTools Performance view**: The easiest way to enable the
145+
PerformanceOverlay widget is from the [Performance view][] in [DevTools][].
146+
Simply click the **Performance Overlay** button to toggle the overlay on your
147+
running app.
148+
149+
* **command line**: Toggle the performance overlay using the **P** key from
150+
the command line.
151+
152+
* **programmatically**: To enable the overlay programmatically, see
153+
[Performance overlay][], a section in the
154+
[Debugging Flutter apps programmatically][] page.
155+
156+
[Performance overlay]: /testing/code-debugging#add-performance-overlay
157+
[Debugging Flutter apps programmatically]: /testing/code-debugging
138158

139159
<a id="the-performance-overlay" aria-hidden="true"></a>
140160

141-
## The performance overlay {:#performance-overlay}
161+
## Observe the performance overlay {:#performance-overlay}
142162

143163
The performance overlay displays statistics in two graphs
144164
that show where time is being spent in your app. If the UI
@@ -158,7 +178,7 @@ on the Flutter Gallery example:
158178
and UI thread (bottom).<br>The vertical green bars
159179
represent the current frame.
160180

161-
## Interpreting the graphs
181+
### Review the graphs {:#interpreting-the-graphs}
162182

163183
The top graph (marked "GPU") shows the time spent by
164184
the raster thread, the bottom one graph shows the time
@@ -188,9 +208,7 @@ the scene is too complicated to render quickly.
188208
expensive to both render and paint.<br>When both graphs
189209
display red, start by diagnosing the UI thread.
190210

191-
[debug mode]: /testing/build-modes#debug
192-
193-
## Flutter's threads
211+
### Review the threads {:#flutters-threads}
194212

195213
Flutter uses several threads to do its work, though
196214
only two of the threads are shown in the overlay.
@@ -203,7 +221,7 @@ on other threads.
203221
: The platform's main thread. Plugin code runs here.
204222
For more information, see the [UIKit][] documentation for iOS,
205223
or the [MainThread][] documentation for Android.
206-
This thread is not shown in the performance overlay.
224+
_This thread is not shown in the performance overlay._
207225

208226
**UI thread**
209227
: The UI thread executes Dart code in the Dart VM.
@@ -229,58 +247,29 @@ on other threads.
229247
**I/O thread**
230248
: Performs expensive tasks (mostly I/O) that would
231249
otherwise block either the UI or raster threads.
232-
This thread is not shown in the performance overlay.
250+
_This thread is not shown in the performance overlay._
233251

234252
For links to more information and videos,
235253
see [The Framework architecture][] in the
236254
[Flutter wiki][], and the community article,
237255
[The Layer Cake][].
238256

257+
[debug mode]: /testing/build-modes#debug
239258
[Flutter wiki]: {{site.repo.flutter}}/tree/main/docs
240-
[MainThread]: {{site.android-dev}}/reference/android/support/annotation/MainThread
241-
[The Framework architecture]: {{site.repo.flutter}}/blob/main/docs/about/The-Framework-architecture.md
242-
[The Layer Cake]: {{site.medium}}/flutter-community/the-layer-cake-widgets-elements-renderobjects-7644c3142401
243259
[UIKit]: {{site.apple-dev}}/documentation/uikit
260+
[The Layer Cake]: {{site.medium}}/flutter-community/the-layer-cake-widgets-elements-renderobjects-7644c3142401
261+
[The Framework architecture]: {{site.repo.flutter}}/blob/main/docs/about/The-Framework-architecture.md
262+
[MainThread]: {{site.android-dev}}/reference/android/support/annotation/MainThread
244263

245-
### Displaying the performance overlay
246-
247-
You can toggle display of the performance overlay as follows:
248-
249-
* Using the Flutter inspector
250-
* From the command line
251-
* Programmatically
252-
253-
#### Using the Flutter inspector
254-
255-
The easiest way to enable the PerformanceOverlay widget is
256-
from the Flutter inspector, which is available in the
257-
[Inspector view][] in [DevTools][]. Simply click the
258-
**Performance Overlay** button to toggle the overlay
259-
on your running app.
260-
261-
[Inspector view]: /tools/devtools/inspector
262-
263-
#### From the command line
264-
265-
Toggle the performance overlay using the **P** key from
266-
the command line.
267-
268-
#### Programmatically
269-
270-
To enable the overlay programmatically, see
271-
[Performance overlay][], a section in the
272-
[Debugging Flutter apps programmatically][] page.
273-
274-
[Debugging Flutter apps programmatically]: /testing/code-debugging
275-
[Performance overlay]: /testing/code-debugging#add-performance-overlay
264+
## Identify problems
276265

277-
## Identifying problems in the UI graph
266+
### Review the UI graph {:#identifying-problems-in-the-ui-graph}
278267

279268
If the performance overlay shows red in the UI graph,
280269
start by profiling the Dart VM, even if the GPU graph
281270
also shows red.
282271

283-
## Identifying problems in the GPU graph
272+
### Review the GPU graph {:#identifying-problems-in-the-gpu-graph}
284273

285274
Sometimes a scene results in a layer tree that is easy to construct,
286275
but expensive to render on the raster thread. When this happens,
@@ -306,8 +295,6 @@ If it's a static scene that's being faded, rotated, or otherwise
306295
manipulated, a [`RepaintBoundary`][] might help.
307296

308297
[programmatically]: /testing/code-debugging#debug-animation-issues
309-
[`RepaintBoundary`]: {{site.api}}/flutter/widgets/RepaintBoundary-class.html
310-
[`saveLayer`]: {{site.api}}/flutter/dart-ui/Canvas/saveLayer.html
311298

312299
#### Checking for offscreen layers
313300

@@ -361,46 +348,13 @@ _Because raster cache entries are expensive to
361348
construct and take up loads of GPU memory,
362349
cache images only where absolutely necessary._
363350

364-
### Viewing the widget rebuild profiler
365-
366-
The Flutter framework is designed to make it hard to create
367-
applications that are not 60fps and smooth. Often, if you have jank,
368-
it's because there is a simple bug causing more of the UI to be
369-
rebuilt each frame than required. The Widget rebuild profiler
370-
helps you debug and fix performance problems due to these sorts
371-
of bugs.
372-
373-
You can view the widget rebuilt counts for the current screen and
374-
frame in the Flutter plugin for Android Studio and IntelliJ.
375-
For details on how to do this, see [Show performance data][]
376-
377-
[Show performance data]: /tools/android-studio#show-performance-data
378-
379-
## Benchmarking
380-
381-
You can measure and track your app's performance by writing
382-
benchmark tests. The Flutter Driver library provides support
383-
for benchmarking. Using this integration test framework,
384-
you can generate metrics to track the following:
385-
386-
* Jank
387-
* Download size
388-
* Battery efficiency
389-
* Startup time
390-
391-
Tracking these benchmarks allows you to be informed when a
392-
regression is introduced that adversely affects performance.
393-
394-
For more information, check out [Integration testing][].
395-
396-
[Integration testing]: /testing/integration-tests
397-
398351
## Other resources
399352

400353
The following resources provide more information on using
401354
Flutter's tools and debugging in Flutter:
402355

403356
* [Debugging][]
357+
* [Performance view][]
404358
* [Flutter inspector][]
405359
* [Flutter inspector talk][], presented at DartConf 2018
406360
* [Why Flutter Uses Dart][], an article on Hackernoon
@@ -409,11 +363,16 @@ Flutter's tools and debugging in Flutter:
409363
* [Flutter API][] docs, particularly the [`PerformanceOverlay`][] class,
410364
and the [dart:developer][] package
411365

366+
[`PerformanceOverlay`]: {{site.api}}/flutter/widgets/PerformanceOverlay-class.html
367+
[`RepaintBoundary`]: {{site.api}}/flutter/widgets/RepaintBoundary-class.html
368+
[`saveLayer`]: {{site.api}}/flutter/dart-ui/Canvas/saveLayer.html
412369
[dart:developer]: {{site.api}}/flutter/dart-developer/dart-developer-library.html
370+
[Debugging]: /testing/debugging
413371
[devtools]: /tools/devtools
414372
[Flutter API]: {{site.api}}
415-
[Flutter inspector]: /tools/devtools/inspector
416373
[Flutter inspector talk]: {{site.yt.watch}}?v=JIcmJNT9DNI
417-
[`PerformanceOverlay`]: {{site.api}}/flutter/widgets/PerformanceOverlay-class.html
374+
[Flutter inspector]: /tools/devtools/inspector
375+
[Performance view]: /tools/devtools/performance
376+
[profile mode]: /testing/build-modes#profile
418377
[video]: {{site.yt.watch}}?v=5F-6n_2XWR8
419378
[Why Flutter Uses Dart]: https://hackernoon.com/why-flutter-uses-dart-dd635a054ebf

0 commit comments

Comments
 (0)