The task manager

The task manager lists what runs in the app and how busy each is: the app's own isolate, the engine's threads that draw and decode for it, and every isolate the app starts for heavy work. A small table over the app shows the essentials; the debug panel has every number.

Why

"The app stutters" has four different causes in a Flutter app, and each has its own fix:

Flutter's DevTools shows this on a developer's machine. The task manager shows it in the running app, on any device and in a release build, where there is no VM service to ask.

Example

spring:
  flutter:
    debug:
      isolates:
        enabled: true          # in every build; not set: debug and profile only
        position: bottom-right

Run the app and press ⌘⇧I (Ctrl+Shift+I), or on a phone tap seven times quickly and hold the eighth. The table shows in its corner, a line per row: the name, how busy, how late.

main      ▂  3%   0.4 ms
raster    ▅ 31%
platform         1.2 ms
io               0.8 ms
task-1    █ 96%

The rows

Row What it is What is measured
main The app's isolate: your Dart code and Flutter's build and layout. The engine's UI thread How late its event loop runs (lag) and from that how busy it is; the frames' build times (average and worst); the memory of the process
raster The engine's thread that draws the frames The share of the time spent drawing (busy), the frames' raster times, the sizes of the layer and picture caches
platform The platform's main thread: plugins, the keyboard, the system's views The round trip of a harmless call of an engine channel, every two seconds
io The engine's threads that decode pictures The round trip of decoding a picture of one pixel, every two seconds
task-1, … The isolates of the task executor, while they exist The share of the time spent in tasks, the tasks done, those waiting
a name of yours An isolate the app starts itself, shown with IsolateLoads.track That it runs

A row has only the numbers its source can measure. main is one row from two sources: the framework's sampler gives the lag, the engine's frame times are added to it.

In a browser there are no platform and IO threads: the rows are main and raster. The memory is the JavaScript heap, where the browser tells it (Chromium).

Where the engine runs Dart on the platform's thread (the macOS desktop embedder does by default), platform waits as long as main does: they are one thread there.

An isolate the app starts with Isolate.run or compute is not found by itself: a compiled app cannot list its isolates. Start the work through the task executor, or show it with one call:

final report = await isolateLoads.track('report', Isolate.run(buildReport));

It measures only while you look

Nothing is measured while the table is hidden and the panel's tab is closed. The first look starts the timers (the first second has no numbers yet); half a minute after the last look they stop by themselves. So a release build with the feature in it pays for it only when someone opens it.

The table reads every interval (a second). The lag of main is how late a timer due every 100 ms fires: work that ends between two timers does not show, so a busy of 3 % says the isolate keeps up, not that it used 3 % of a processor.

The debug panel

The debug panel has an Isolates tab with the full table: every row with its kind, busy share, lag, longest lag, what it is working on, memory and details (the frame times, the cache sizes, the tasks done). Copy JSON puts the rows on the clipboard, for a bug report.

The table lives in the dock of the debug overlays with the frame meter and the timeline: in one corner they stack on a laptop and become pages to swipe on a phone.

In the build or not

Like the other debug features, the task manager is a module of its own, decided by spring.flutter.debug.isolates.enabled:

Value The app
true Has it in every build, a release too
false Has no code of it
not set Has it in debug and profile builds; a release compiles it away

Without it the app has no code that measures the engine's threads. The isolateLoads bean is still there, with the rows that cost nothing to have (main, the task executor's isolates): a screen of your own can read it.

A row of your own

A bean that implements IsolateLoadSource adds rows: the task manager asks every source.

@Component()
class SyncLoad implements IsolateLoadSource {
  SyncLoad(this.sync);
  final SyncService sync;

  @override
  List<IsolateLoad> loads() => [
    IsolateLoad(
      name: 'sync',
      kind: 'own',
      active: sync.pending,
      details: {'uploaded': sync.uploaded},
    ),
  ];
}

See Isolates and their load.

The properties

Key Type Default Meaning
spring.flutter.debug.isolates.enabled bool not set Whether the build has the task manager (see above)
spring.flutter.debug.isolates.position corner bottom-right The corner of its table
spring.flutter.debug.isolates.interval duration 1s How often the table and the tab read the rows

The action is debug.isolates; change its keys with spring.flutter.shortcuts.debug.isolates (see Keyboard shortcuts and taps). On the web Ctrl+Shift+I is also the browser's own shortcut for its developer tools on Windows and Linux: give the action other keys there, or use the taps.

See also