From 7f32cbe5351ad073eeb0e1e0f60a9a5e2035c23b Mon Sep 17 00:00:00 2001 From: littleGnAl Date: Mon, 21 Oct 2024 19:00:06 +0800 Subject: [PATCH 1/6] ++ --- lib/src/glance.dart | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/lib/src/glance.dart b/lib/src/glance.dart index d210c42..dde7c14 100644 --- a/lib/src/glance.dart +++ b/lib/src/glance.dart @@ -88,6 +88,18 @@ class GlanceConfiguration { /// After obtaining the [JankReport.stackTrace], you can symbolize it using the `flutter symbolize` command. /// For more details, see https://docs.flutter.dev/deployment/obfuscate#read-an-obfuscated-stack-trace. /// You can save the stack traces to files or upload them to your server and symbolize them later. +/// +/// ## How it works +/// `glance` starts a dedicated [Isolate] internally to capture Dart UI thread stack traces using native stack unwinding. +/// Refer to [Sampler] for more details. +/// +/// To detect UI jank, `glance` extends `WidgetsFlutterBinding`, monitoring the build phase execution time, +/// along with callbacks such as `WidgetBindingObserver`, touch events, and method channel callbacks. +/// Jank is detected when the execution time exceeds the [GlanceConfiguration.jankThreshold]. +/// For further information, refer to [GlanceWidgetBinding]. +/// +/// Upon detecting jank, `glance` fetches stack traces from the [Sampler] during the jank period and reconstructs them into Dart stack traces. +/// These are then reported to the [GlanceReporter], specified via [GlanceConfiguration.reporters]. abstract class Glance { Glance._(); From 34d43c33344a76fb28ae14a5236f8e8c6d41ff34 Mon Sep 17 00:00:00 2001 From: littleGnAl Date: Tue, 22 Oct 2024 11:39:55 +0800 Subject: [PATCH 2/6] ++ --- README.md | 2 +- lib/src/glance.dart | 8 ++++---- lib/src/glance_impl.dart | 6 +++--- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index e331656..205e9b3 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ An APM library for detecting UI jank in Flutter for mobile (Android/iOS). Building smooth APPs with Flutter is easy, but as your APP grows in complexity and faces a variety of user environments and devices, ensuring smooth performance in production can be challenging. Even if your app runs smoothly locally, it doesn't guarantee the same for all users. `glance` helps collect stack traces during UI jank, allowing you to pinpoint the exact function causing the performance issue, so you can resolve it effectively. -`glance` detects UI jank during the build phase as well as through various callbacks, such as, `WidgetBindingObserver` callbacks, touch events, and method channel callbacks. These cover most cases that cause UI jank. It works only in release or profile builds when your application is built with the [`--split-debug-info` option](https://docs.flutter.dev/deployment/obfuscate#obfuscate-your-app). +`glance` detects UI jank during the rendering as well as through various callbacks, such as, `WidgetBindingObserver` callbacks, touch events, and method channel callbacks. These cover most cases that cause UI jank. It works only in release or profile builds when your application is built with the [`--split-debug-info` option](https://docs.flutter.dev/deployment/obfuscate#obfuscate-your-app). ## Getting Started diff --git a/lib/src/glance.dart b/lib/src/glance.dart index dde7c14..02be094 100644 --- a/lib/src/glance.dart +++ b/lib/src/glance.dart @@ -6,7 +6,7 @@ import 'package:glance/src/glance_impl.dart'; import 'package:flutter/widgets.dart' show WidgetsFlutterBinding; /// A custom binding that connects [WidgetsFlutterBinding] and [Glance] to detect -/// UI jank during the build phase and from "external sources" such as callbacks from +/// UI jank during the rendering phase and from "external sources" such as callbacks from /// [WidgetsBindingObserver], touch events, and channel messages from the platform. class GlanceWidgetBinding extends WidgetsFlutterBinding with GlanceWidgetBindingMixin { @@ -93,10 +93,10 @@ class GlanceConfiguration { /// `glance` starts a dedicated [Isolate] internally to capture Dart UI thread stack traces using native stack unwinding. /// Refer to [Sampler] for more details. /// -/// To detect UI jank, `glance` extends `WidgetsFlutterBinding`, monitoring the build phase execution time, -/// along with callbacks such as `WidgetBindingObserver`, touch events, and method channel callbacks. +/// To detect UI jank, `glance` extends [WidgetsFlutterBinding] and monitors execution time between [WidgetsFlutterBinding.handleBeginFrame] +/// and [WidgetsFlutterBinding.handleDrawFrame]. It also tracks various callbacks such as `WidgetBindingObserver`, touch events, +/// and method channel callbacks' invocations, checking each against its execution time. /// Jank is detected when the execution time exceeds the [GlanceConfiguration.jankThreshold]. -/// For further information, refer to [GlanceWidgetBinding]. /// /// Upon detecting jank, `glance` fetches stack traces from the [Sampler] during the jank period and reconstructs them into Dart stack traces. /// These are then reported to the [GlanceReporter], specified via [GlanceConfiguration.reporters]. diff --git a/lib/src/glance_impl.dart b/lib/src/glance_impl.dart index 3633e4e..1632f5e 100644 --- a/lib/src/glance_impl.dart +++ b/lib/src/glance_impl.dart @@ -289,7 +289,7 @@ typedef HandleDrawFrameEndCallback = void Function( typedef CheckJankCallback = void Function(int start, int end); -/// Besides the build phase check ([handleBeginFrame] to [handleDrawFrame]), we only +/// Besides the rendering phase check ([handleBeginFrame] to [handleDrawFrame]), we only /// override the functions that handle callbacks from the [PlatformDispatcher]. /// Other callbacks are handled by the channel called ([_DefaultBinaryMessengerProxy]). mixin GlanceWidgetBindingMixin on WidgetsFlutterBinding { @@ -307,8 +307,8 @@ mixin GlanceWidgetBindingMixin on WidgetsFlutterBinding { T traceFunctionCall(T Function() func) { int start = Timeline.now; final ret = func(); - // Only check jank if not in build phase, because if it is in buid phase, - // the jank has been checked by the build phase jank check + // Only check jank if not in rendering phase, because if it is in buid phase, + // the jank has been checked by the rendering phase jank check if (schedulerPhase == SchedulerPhase.idle) { _onCheckJank?.call(start, Timeline.now); } From 92b8f225693c10712af5399f669668d7ea369eaa Mon Sep 17 00:00:00 2001 From: littleGnAl Date: Tue, 22 Oct 2024 14:46:38 +0800 Subject: [PATCH 3/6] ++ --- README.md | 2 +- lib/src/glance.dart | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 205e9b3..39ed369 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ An APM library for detecting UI jank in Flutter for mobile (Android/iOS). Building smooth APPs with Flutter is easy, but as your APP grows in complexity and faces a variety of user environments and devices, ensuring smooth performance in production can be challenging. Even if your app runs smoothly locally, it doesn't guarantee the same for all users. `glance` helps collect stack traces during UI jank, allowing you to pinpoint the exact function causing the performance issue, so you can resolve it effectively. -`glance` detects UI jank during the rendering as well as through various callbacks, such as, `WidgetBindingObserver` callbacks, touch events, and method channel callbacks. These cover most cases that cause UI jank. It works only in release or profile builds when your application is built with the [`--split-debug-info` option](https://docs.flutter.dev/deployment/obfuscate#obfuscate-your-app). +`glance` detects UI jank during the rendering phase as well as through various callbacks, such as, `WidgetBindingObserver` callbacks, touch events, and method channel callbacks. These cover most cases that cause UI jank. It works only in release or profile builds when your application is built with the [`--split-debug-info` option](https://docs.flutter.dev/deployment/obfuscate#obfuscate-your-app). ## Getting Started diff --git a/lib/src/glance.dart b/lib/src/glance.dart index 02be094..00ce066 100644 --- a/lib/src/glance.dart +++ b/lib/src/glance.dart @@ -94,8 +94,8 @@ class GlanceConfiguration { /// Refer to [Sampler] for more details. /// /// To detect UI jank, `glance` extends [WidgetsFlutterBinding] and monitors execution time between [WidgetsFlutterBinding.handleBeginFrame] -/// and [WidgetsFlutterBinding.handleDrawFrame]. It also tracks various callbacks such as `WidgetBindingObserver`, touch events, -/// and method channel callbacks' invocations, checking each against its execution time. +/// and [WidgetsFlutterBinding.handleDrawFrame] during the rendering phase. It also tracks various callbacks such as `WidgetBindingObserver`, +/// touch events, and method channel callbacks' invocations, checking each against its execution time. /// Jank is detected when the execution time exceeds the [GlanceConfiguration.jankThreshold]. /// /// Upon detecting jank, `glance` fetches stack traces from the [Sampler] during the jank period and reconstructs them into Dart stack traces. From c1f5084f37543db3692859a6e442d9c224cd5df3 Mon Sep 17 00:00:00 2001 From: littleGnAl Date: Tue, 22 Oct 2024 16:02:02 +0800 Subject: [PATCH 4/6] ++ --- lib/src/glance.dart | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/lib/src/glance.dart b/lib/src/glance.dart index 00ce066..2ba0f8c 100644 --- a/lib/src/glance.dart +++ b/lib/src/glance.dart @@ -89,12 +89,34 @@ class GlanceConfiguration { /// For more details, see https://docs.flutter.dev/deployment/obfuscate#read-an-obfuscated-stack-trace. /// You can save the stack traces to files or upload them to your server and symbolize them later. /// +/// For example: +/// ```dart +/// // Implement your `JankDetectedReporter` +/// class MyJankDetectedReporter extends JankDetectedReporter { +/// @override +/// void report(JankReport info) { +/// final stackTrace = info.stackTrace.toString(); +/// // Save the stack traces to a file, or upload them to your server, +/// // symbolize them using the `flutter symbolize` command. +/// } +/// } +/// +/// void main() { +/// // Call `GlanceWidgetBinding.ensureInitialized()` first +/// GlanceWidgetBinding.ensureInitialized(); +/// // Start UI Jank Detection +/// Glance.instance.start(config: GlanceConfiguration(reporters: [MyJankDetectedReporter()])); +/// +/// runApp(const MyApp()); +/// } +/// ``` +/// /// ## How it works /// `glance` starts a dedicated [Isolate] internally to capture Dart UI thread stack traces using native stack unwinding. /// Refer to [Sampler] for more details. /// /// To detect UI jank, `glance` extends [WidgetsFlutterBinding] and monitors execution time between [WidgetsFlutterBinding.handleBeginFrame] -/// and [WidgetsFlutterBinding.handleDrawFrame] during the rendering phase. It also tracks various callbacks such as `WidgetBindingObserver`, +/// and [WidgetsFlutterBinding.handleDrawFrame] during the rendering phase. It also tracks various callbacks such as [WidgetBindingObserver], /// touch events, and method channel callbacks' invocations, checking each against its execution time. /// Jank is detected when the execution time exceeds the [GlanceConfiguration.jankThreshold]. /// From 0903c582f4687dd4ca59100c2183c88bc9861f03 Mon Sep 17 00:00:00 2001 From: littleGnAl Date: Tue, 22 Oct 2024 16:24:40 +0800 Subject: [PATCH 5/6] ++ --- lib/src/glance_impl.dart | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/src/glance_impl.dart b/lib/src/glance_impl.dart index 1632f5e..cdf2281 100644 --- a/lib/src/glance_impl.dart +++ b/lib/src/glance_impl.dart @@ -307,7 +307,7 @@ mixin GlanceWidgetBindingMixin on WidgetsFlutterBinding { T traceFunctionCall(T Function() func) { int start = Timeline.now; final ret = func(); - // Only check jank if not in rendering phase, because if it is in buid phase, + // Only check jank if not in rendering phase, because if it is in rendering phase, // the jank has been checked by the rendering phase jank check if (schedulerPhase == SchedulerPhase.idle) { _onCheckJank?.call(start, Timeline.now); From 2096416f85ee32d88ba0375a0daa2a0f1aa97b7f Mon Sep 17 00:00:00 2001 From: littleGnAl Date: Tue, 22 Oct 2024 16:36:14 +0800 Subject: [PATCH 6/6] ++ --- lib/src/glance.dart | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/lib/src/glance.dart b/lib/src/glance.dart index 2ba0f8c..01f2702 100644 --- a/lib/src/glance.dart +++ b/lib/src/glance.dart @@ -88,7 +88,7 @@ class GlanceConfiguration { /// After obtaining the [JankReport.stackTrace], you can symbolize it using the `flutter symbolize` command. /// For more details, see https://docs.flutter.dev/deployment/obfuscate#read-an-obfuscated-stack-trace. /// You can save the stack traces to files or upload them to your server and symbolize them later. -/// +/// /// For example: /// ```dart /// // Implement your `JankDetectedReporter` @@ -110,17 +110,17 @@ class GlanceConfiguration { /// runApp(const MyApp()); /// } /// ``` -/// +/// /// ## How it works -/// `glance` starts a dedicated [Isolate] internally to capture Dart UI thread stack traces using native stack unwinding. +/// `glance` starts a dedicated [Isolate] internally to capture Dart UI thread stack traces using native stack unwinding. /// Refer to [Sampler] for more details. -/// -/// To detect UI jank, `glance` extends [WidgetsFlutterBinding] and monitors execution time between [WidgetsFlutterBinding.handleBeginFrame] -/// and [WidgetsFlutterBinding.handleDrawFrame] during the rendering phase. It also tracks various callbacks such as [WidgetBindingObserver], -/// touch events, and method channel callbacks' invocations, checking each against its execution time. +/// +/// To detect UI jank, `glance` extends [WidgetsFlutterBinding] and monitors execution time between [WidgetsFlutterBinding.handleBeginFrame] +/// and [WidgetsFlutterBinding.handleDrawFrame] during the rendering phase. It also tracks various callbacks such as [WidgetBindingObserver], +/// touch events, and method channel callbacks' invocations, checking each against its execution time. /// Jank is detected when the execution time exceeds the [GlanceConfiguration.jankThreshold]. -/// -/// Upon detecting jank, `glance` fetches stack traces from the [Sampler] during the jank period and reconstructs them into Dart stack traces. +/// +/// Upon detecting jank, `glance` fetches stack traces from the [Sampler] during the jank period and reconstructs them into Dart stack traces. /// These are then reported to the [GlanceReporter], specified via [GlanceConfiguration.reporters]. abstract class Glance { Glance._();