Understand performance during a session

Investigate Flutter rendering performance and resource use with frame timings, supported native metrics, and your own app measurements.

Frame timings help you see whether Flutter spends time building or rasterizing frames. Compare these measurements and supported resource metrics with the surrounding session activity when investigating performance.

The native runtime samples supported iOS and Android memory, FPS, and battery channels. Flutter instrumentation adds the following channels on every supported Flutter target. On macOS, native FPS samples are derived from Flutter frame timings and retained on channel 3.

ChannelIdUnit
Flutter frame build40ms
Flutter frame raster41ms
Flutter frame total42ms
Flutter frame count43count

Register app metrics as needed:

await Ansight.instance.registerMetricChannel(
  const AnsightChannel(id: 50, name: 'Queue depth', unit: 'items'),
);
await Ansight.instance.metric(42, channel: 50);

Native runtime resource channels are opt-in:

final options = createOptionsBuilder()
    .withOpenFileHandleTracking()
    .withJniReferenceCountTracking()
    .build();

Open file handles use reserved channel 7 on supported native targets. JNI references use reserved channel 6 on Android only. Native ids 0-7 and 255 are reserved, and Flutter instrumentation uses 40-43; choose a different id for app channels.

Set captureFrames: false when installing Flutter instrumentation if frame timing is unnecessary. Use enableFramesPerSecond(), disableFramesPerSecond(), and captureBuiltInTelemetrySample() for native sampling control.