flutter: improve app start and frames tracking docs (#11891)

* update

* update

* update frames tracking docs

* update wording

* Apply suggestions from code review

Co-authored-by: Karl Heinz Struggl <[email protected]>

* remove usages of 'we'

---------

Co-authored-by: Karl Heinz Struggl <[email protected]>

Author: buenaflor

docs/platforms/flutter/integrations/app-start-instrumentation.mdx

@@ -10,13 +10,28 @@ categories:
 
 Sentry's app start instrumentation provides insight into how long your application takes to launch.
 
+<Note>
+
+App start instrumentation is available on **iOS** and **Android**.
+
+</Note>
+
 ## Instrumentation Behaviour
 
 Before diving into the configuration, it's important to understand how app start instrumentation behaves:
 
-- The SDK attaches the app start metrics to the **first run transaction**.
-- It tracks the length of time from the **earliest native process initialization** until the very first [PostFrameCallback](https://api.flutter.dev/flutter/scheduler/SchedulerBinding/addPostFrameCallback.html) is triggered.
-- The SDK differentiates between a cold and a warm start, but doesn't track hot starts/resumes.
+App start instrumentation tracks the duration between the earliest native process initialization and the first frame rendered (as reported by [addTimingsCallback](https://api.flutter.dev/flutter/scheduler/SchedulerBinding/addTimingsCallback.html)). Once the app start is processed, the callback is removed to avoid additional overhead.
+
+When the SDK receives the start and end times of the app launch, the SDK:
+- Creates a transaction named `ui.load`
+- Attaches a span with either `app.start.cold` or `app.start.warm` operation
+- Adds app start metrics to the transaction
+
+<Note>
+
+While the SDK differentiates between cold and warm starts, it doesn't track hot starts/resumes.
+
+</Note>
 
 ## Prerequisites
 
@@ -27,49 +42,18 @@ Before starting, ensure:
 
 ## Configure
 
-This type of instrumentation is automatically enabled. There is no need for further configuration.
+This instrumentation is automatically enabled. There is no need for further configuration.
 
 ## Verify
 
-### 1. Execute the Transaction:
-
-Initiate a transaction immediately after the app launches.
+### 1. Launch Your App:
 
-```dart
-import 'package:sentry/sentry.dart';
-
-final transaction = Sentry.startTransaction("test test", "my operation");
-await Future.delayed(const Duration(milliseconds: 1000));
-transaction.finish();
-```
+Launch your Sentry configured app.
 
 ### 2. Locate Your Transaction:
 
-Open the [sentry.io](https://sentry.io/) performance dashboard, find, and select the transaction you executed.
+Open the [sentry.io performance page](https://sentry.io/performance), find, and select the 'root /' transaction and navigate to the trace view of a sampled event.
 
 ### 3. View App Start Metrics:
 
-Select the event within your transaction. Sentry.io displays the app start metrics on the right side of the screen.
-
-## Additional Configuration
-
-### Change App Start Tracking End
-
-1. Set `autoAppStart` to `false` in the Sentry options.
-2. Call `SentryFlutter.setAppStartEnd`.
-
-```dart
-import 'package:sentry_flutter/sentry_flutter.dart';
-
-// Run my App and do my things first
-
-// Initialize the Flutter SDK
-Future<void> main() async {
-  await SentryFlutter.init(
-    (options) => options.autoAppStart = false,
-  );
-}
-
-// End the App Start metric
-SentryFlutter.setAppStartEnd(DateTime.now().toUtc());
-```
+Select the event within your transaction. Sentry displays the app start metrics on the right side of the screen in the **Mobile Vitals** section.

docs/platforms/flutter/integrations/slow-and-frozen-frames-instrumentation.mdx

@@ -12,10 +12,17 @@ Unresponsive UI and animation hitches annoy users and degrade the user experienc
 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](https://develop.sentry.dev/sdk/performance/frames-delay/).
 
+<Note>
+
+Frames tracking instrumentation is available on **iOS**, **macOS** and **Android**.
+
+</Note>
+
 ## Instrumentation Behaviour
 
-Frame metrics are manually calculated using the [addPersistentFrameCallback](https://api.flutter.dev/flutter/scheduler/SchedulerBinding/addPersistentFrameCallback.html) API from the Flutter SDK.
-Frame duration tracking in Sentry's Flutter SDK begins automatically when a span starts. It continuously measures each frame's render time until the span finishes, then calculates and attaches frame metrics to the completed span.
+The frames tracking instrumentation measures frame metrics (slow frames, frozen frames, and frame delay) for each span. To calculate these metrics, the SDK uses a custom `WidgetsFlutterBinding` that measures the duration between [handleBeginFrame](https://api.flutter.dev/flutter/scheduler/SchedulerBinding/handleBeginFrame.html) and [handleDrawFrame](https://api.flutter.dev/flutter/scheduler/SchedulerBinding/handleDrawFrame.html) 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
 
@@ -26,22 +33,34 @@ Before starting, ensure:
 
 ## Configure
 
-This type of instrumentation is automatically enabled. There is no need for further configuration.
+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:
+```dart {2}
+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.
 
-```dart
-import 'package:flutter/widgets.dart';
-import 'package:sentry_flutter/sentry_flutter.dart';
-
-Future<void> main() async {
-  await SentryFlutter.init(
-    (options) => options.enableFramesTracking = false,
-    appRunner: () => runApp(MyApp()),
-  );
-}
+```dart {3}
+await SentryFlutter.init(
+  (options) {
+    options.enableFramesTracking = false
+  },
+);
 ```