Slow and Frozen Frames and Frames Delay Instrumentation

Unresponsive UI and animation hitches annoy users and degrade the user experience. This integration can help. Set it up and identify these problems in your app by tracking and showing slow frames, frozen frames, and frame delay metrics for spans. Learn more about frame delay here.

Instrumentation Behaviour

The frames tracking instrumentation measures frame metrics (slow frames, frozen frames, and frame delay) for each span. To calculate these metrics, we use a custom WidgetsFlutterBinding that measures the duration between handleBeginFrame and handleDrawFrame to determine each frame's render time.

Frame duration tracking begins automatically when a span starts. The integration continuously measures frame durations until the span finishes, then calculates and attaches the frame metrics to the completed span.

Prerequisite

Before starting, ensure:

1. The Sentry Flutter SDK is initialized. Learn more here.
2. Tracing is set up. Learn more here.

Configure

This instrumentation is automatically enabled through two integrations:

• The WidgetsFlutterBindingIntegration which provides the custom binding for frame tracking
• The FramesTrackingIntegration which processes and attaches the frame metrics to spans

In most cases, no additional configuration is required.

Early Widgets Binding Initialization

If you need to initialize the widgets binding earlier than SentryFlutter.init(), you must call SentryWidgetsFlutterBinding.ensureInitialized() manually. Note that using a different custom binding will prevent this instrumentation from working properly.

Example:

void main() {
  SentryWidgetsFlutterBinding.ensureInitialized();
  // ... rest of your initialization code
}

Additional Configuration

Disabling the Instrumentation

Set enableFramesTracking to false in the options to disable the instrumentation.

await SentryFlutter.init(
  (options) {
    options.enableFramesTracking = false
  },
);