flutter-devtools-perf

name	flutter-devtools-perf
description	Use Flutter DevTools Performance, CPU, Memory, and Network views to find UI-thread and raster-thread bottlenecks.

Flutter DevTools Performance

Instructions

Flutter DevTools is the canonical profiler for Flutter apps on iOS, Android, desktop, and web. Run it against a profile-mode build for real numbers; debug mode is up to 10× slower and obscures real bottlenecks.

1. Launch

flutter pub global activate devtools
flutter run --profile
# DevTools URL printed in the run output; open in Chrome

Or from VS Code: Command Palette → Dart: Open DevTools.

2. Performance View — Frames and Timelines

• Frames chart at the top: bars per frame, colored red when over budget.
• Click a red frame — the Timeline panel shows two flame charts:
  • UI (Dart thread) — widget build, layout, paint.
  • Raster (GPU thread) — Skia/Impeller rasterization.
• Enhance Tracing:
  • Track Widget Builds — each build event appears as a slice.
  • Track Layouts — render-object layout slices.
  • Track Paints — paint slices.
  • Track Platform Channels — latency of method calls to native.

Reading pattern:

• If UI flame is wide → optimize Dart: reduce rebuilds, move work off UI isolate.
• If Raster flame is wide → overdraw, blurs, or shader compile.
• Gap between UI end and Raster start → platform / vsync issue.

3. CPU Profiler

Tab: CPU Profiler. Click Record, perform the action, stop.

• Call Tree → top-down.
• Bottom Up → hot leaves aggregated.
• Flame Chart → visual hierarchy.

Filter to the UI isolate. Use VM Tags (e.g., CompileUnoptimized, Runtime) to find compile jank versus steady state.

4. Memory View

• Chart: Used / Capacity / External memory over time.
• GC events plotted as dots.
• Heap Snapshot: click "Snapshot" → see class-by-class instance counts.
• Diff Snapshots: take before + after navigation round-trip; non-zero retained counts reveal leaks.

Filter by type to check your State and controller classes.

For CI, use the leak_tracker package:

void main() {
  LeakTracking.start();
  runApp(const MyApp());
}

5. Widget Inspector — Rebuild Stats

DevTools → Widget Inspector → More → Rebuild Stats.

• Counts rebuilds per widget type on every frame.
• Sort descending. The first five are your targets.
• Common offenders:
  • A top-level Consumer/BlocBuilder wrapping the whole screen.
  • Forgotten const constructors.
  • New lambdas passed down each rebuild (use stable references / useCallback via hooks).

6. Network View

Shows Dio / http client requests:

• Bytes in/out, duration, HTTP status.
• Timing breakdown: DNS, TLS, waiting, receive.

Use to confirm caching (302 from cache) and to spot request storms.

7. Provider View

Riverpod and Provider expose their state here. Useful to see when state changes and which widgets listen.

8. Shader Compilation Jank

A unique Flutter problem on Android: the first animation after install compiles shaders, causing visible jank.

Fix:

• Use Impeller (default on iOS, enabled on Android by default in recent stable). Impeller pre-compiles shader variants.

• For legacy Skia: generate SkSL warm-up:

  flutter run --profile --cache-sksl --purge-persistent-cache
  # reproduce animations you care about
  # quit; the SkSL is saved. Build:
  flutter build apk --bundle-sksl-path flutter_01.sksl.json
  

9. Impeller Diagnostics

If using Impeller, enable:

flutter run --profile --dart-define=IMPELLER_ENABLE_VALIDATION=1

Validation logs mis-uses that cause unexpected GPU work.

10. Production Metrics

Use dart:developer's Timeline in your code:

Timeline.startSync('loadFeed');
final feed = await api.fetchFeed();
Timeline.finishSync();

Ship a production profiler like SentryPerformance or Firebase Performance for field data.

11. Common Flutter Wins

• const constructors everywhere possible.
• Extract widgets so only the leaf rebuilds.
• ListView.builder + itemExtent for uniform rows.
• RepaintBoundary around an animated subtree inside a larger static screen.
• Move JSON parsing to isolates with compute() or Isolate.run.
• Precache images with precacheImage before the frame that needs them.

Checklist

• Profiling done in --profile mode, not --debug.
• Enhanced Tracing used to label builds, layouts, paints.
• Rebuild Stats show no widget rebuilding more than expected.
• Heap snapshot diff confirms no retained state classes after navigation.
• Network View confirms cache hits on revisited screens.
• Impeller enabled or SkSL warm-up bundle shipped.
• Production perf SDK wired and ingesting frame, startup, and network metrics.