How do you turn on Flutter's PerformanceOverlay on a running app, and what do its two graphs tell you?

## What the overlay is **`PerformanceOverlay`** is a `LeafRenderObjectWidget` whose render object asks the engine to draw frame statistics over your app. The engine paints it, not your widget tree, so it costs very little and does not distort the numbers it shows. The Flutter docs describe each graph as showing the last 300 frames for its thread. ## Three ways to turn it on 1. **In code.** `MaterialApp(showPerformanceOverlay: true, ...)`. The same flag exists on `WidgetsApp` and `CupertinoApp`, and it defaults to `false`. Use it for a build you hand to a tester. 2. **From the terminal.** Press **P** in the terminal session running `flutter run` to toggle it on the attached app. 3. **From DevTools.** Click **Performance Overlay** in the performance view. You can also place `PerformanceOverlay.allEnabled()` in the tree yourself, or `PerformanceOverlay(optionsMask: ...)` built from `PerformanceOverlayOption` values, to choose which statistics appear. `allEnabled()` is not a `const` constructor, because it computes the mask. ## Reading the two graphs | Graph | Thread | Red bar means | |---|---|---| | top (marked GPU in the docs) | raster: turns the layer tree into GPU commands | the scene was too expensive to draw in time | | bottom | UI: your Dart code and the framework's build, layout and paint | Dart work for that frame took too long | - The **horizontal axis** is frames. The graph only advances when the app paints, so an idle app shows a still graph. - The **vertical axis** is time. White lines mark 16 ms steps; a bar above the first line ran slower than 60 Hz. - **Green** vertical bars mark the current frame when things are fine. **Red** bars appear in the graph of the thread that missed its budget. - When **both** graphs show red, the docs advise diagnosing the UI thread first. ## Choosing statistics with optionsMask `PerformanceOverlay(optionsMask: ...)` takes a bit mask built by shifting 1 by the index of each **`PerformanceOverlayOption`** you want: - `displayRasterizerStatistics`: raster frame time and FPS as text; - `visualizeRasterizerStatistics`: the raster graph; - `displayEngineStatistics`: UI frame time and FPS as text; - `visualizeEngineStatistics`: the UI graph. `PerformanceOverlay.allEnabled()` sets all four. For example, `1 << PerformanceOverlayOption.visualizeRasterizerStatistics.index` shows only the raster graph, which is handy when you are tuning a raster-heavy screen and want less clutter. ## Why profile mode matters here The docs say the overlay should always be viewed in **profile mode**. Debug builds run JIT-compiled code with assertions and extra checks, so the UI graph shows red bars that release builds would never have. Profile builds are compiled like release builds but keep enough tracing to measure. Run on a physical device too, because an emulator's GPU has nothing in common with a phone's. ## When to reach for it and when not to - **Good for:** watching a scroll or an animation live on a device, showing a tester where jank happens, and seeing at a glance which thread is struggling. - **Not enough for:** finding which widget or render object is responsible. For that, record the same interaction in the DevTools performance view, select the red frame and read its timeline events. - **Not for users:** leave `showPerformanceOverlay` off in shipped builds. To measure real users, collect `FrameTiming` data with `SchedulerBinding.instance.addTimingsCallback` instead. ## A typical first session Turn on the overlay, open the slow screen and repeat the interaction a few times. If only the bottom graph spikes, look at build and layout work. If only the top graph spikes, look at what the screen draws: translucency, clips, shadows and large images. Then move to DevTools for the detail.