The frame meter

The frame meter is a small panel over the app with the frames a second it really draws, the average time of their build and raster, the worst frame, and a bar per frame: within the budget, up to twice it, or over. The times are Flutter's own (FrameTiming), on every platform the web included, so it shows on a phone what a desktop browser cannot.

Why

An app that scrolls smoothly on a developer's laptop may drop frames on a mid-range phone, or in a phone's browser. Flutter's DevTools need a connected computer. The meter shows the truth on the device itself, in any build, and is turned on by a property: in a profile you test with, not for your users.

Example

# lib/resources/application-profile.yml: in profile builds only
spring:
  flutter:
    frame-meter:
      enabled: true
      position: bottom-right
      target-rate: 120      # a 120 Hz phone

What it shows

Frames drawn without Flutter

A 3D scene on a canvas of its own under the page has frames that are no frames of Flutter. Without a line of their own the meter would say idle while the scene moves at 60 a second. Each source has a line: its name, how many frames a second it drew in the last second, and what one cost the page's thread on average. A page at rest with a scene moving on it:

idle
3D 60 fps · 0.9 ms

The line's color is the budget's, as for Flutter's frames: good within 1 / target-rate, warning up to twice that. A scene held to 30 frames a second shows warning against a target-rate of 60: the color says how often it draws, not that it is late. A source that drew fewer than two frames in the last second has no line.

The scenes of spring_boot_starter_flutter_scene report as 3D: their frames on spring.flutter.scene.canvas: layer or engine in a browser, and those its slow condition measures behind the placeholders. With canvas: page, and outside a browser, Flutter draws the scenes, and their frames are in Flutter's own line.

A late frame, and a frame nobody waited for

A frame is late only when the app was waiting for it. The meter knows which: as each frame ends it notes whether the next one was asked for already.

What draws What the meter measures What it shows
Something that moves at every frame: a scroll, a ticker, a transition The time between the frames. Each was asked for as the one before ended The rate in good, warning or bad; 20 a second here is bad
Something that asks for a frame now and then: a slow drift of the background drawn 15 times a second, a clock What each frame cost to build and raster. Few frames are drawn because few are wanted The rate in the plain text color, small bars
Nothing Nothing idle

So a page whose theme drifts its background shows 15 fps at rest and 60 fps while it scrolls, and neither is a fault. Flutter draws only what changes, so a pause with nothing to draw is never a slow frame; a frame the app waited long for is late however long the wait.

The panel is drawn again at most four times a second. A frame drawn for the meter alone is not the app's: it is not counted, and it does not make the app's frames look closer to each other. Until the app shows, the meter neither shows nor counts, so it takes nothing from the splash.

In a release

In a release build the meter can be shipped alone, with the debug module spring.flutter.debug.frame-meter.enabled, without the rest of the debug panel. It is shown and hidden with ⌘⇧X (Ctrl+Shift+X), or by five quick taps and a sixth held two seconds. See the debug panel.

The properties

Key Type Default Meaning
spring.flutter.frame-meter.enabled bool false Shows the meter over the app (FrameMeter, put there by SpringApp)
spring.flutter.frame-meter.position top-left, top-right, bottom-left, bottom-right top-right The corner of the screen it shows in, inside the safe area
spring.flutter.frame-meter.target-rate number 60 The frames a second the screen is meant to show: a frame within 1 / target-rate is good, up to twice that a warning, more a drop

The debug panel turns the meter on and off, and moves it, in a running app without a new build (its Frames tab).

Its look

The look is the theme's frame-meter. A value left out comes from the theme's colors and typography:

spring:
  flutter:
    theme:
      frame-meter:
        background: { color: $colors.surface, alpha: 85% }
        foreground: $colors.on-surface
        good: $colors.primary
        warning: $colors.tertiary
        bad: $colors.error
        text-style: label-small
Key Type Default Meaning
frame-meter.background color the surface at 85 % The panel's fill
frame-meter.foreground color on-surface The text
frame-meter.good color primary Frames within the budget
frame-meter.warning color tertiary Frames up to twice the budget
frame-meter.bad color error Dropped frames
frame-meter.text-style a text style of the typography, or code label-small The text's style

Colors take every color form of the theme: names, hex, $ references and color objects.

In code

With the debug feature (spring.flutter.debug.frame-meter.enabled) the meter is a debug overlay: it shares its corner with the timeline, one under the other or as pages, and can be dragged with the drag feature. FrameMeterGauge is the panel alone. FrameMeter(position:, targetRate:, stages:, child:) is a widget; put one over any part of the app by hand when you build your own app widget.

Code that draws frames without Flutter reports each one to OutsideFrames, and the meter shows the source:

final OutsideFrames _frames = OutsideFrames.of('video');

void _drew(Duration cost) => _frames.frame(cost);

OutsideFrames.of(name) is the source of that name, made the first time it is asked for; frame(cost) is a frame drawn now, with what it cost the page's thread; recent is the rate and the average cost of the last second, null when it drew fewer than two frames.

See also