mirror of
https://github.com/flutter/flutter
synced 2024-10-13 03:32:55 +00:00
Add comments to flutter_driver for timeline class (#58823)
* Add comments to flutter_driver for timeline class Mostly about explanation for the json items from timeline.dart and timeline_summary.dart.
This commit is contained in:
parent
42e02d60d3
commit
9c3f0faa6d
|
@ -20,6 +20,9 @@ class Timeline {
|
|||
final Map<String, dynamic> json;
|
||||
|
||||
/// List of all timeline events.
|
||||
///
|
||||
/// This is parsed from "traceEvents" data within [json] and sorted by
|
||||
/// timestamp. Anything without a valid timestamp is put in the beginning.
|
||||
final List<TimelineEvent> events;
|
||||
}
|
||||
|
||||
|
|
|
@ -62,7 +62,7 @@ class TimelineSummary {
|
|||
.where((Duration duration) => duration > kBuildBudget)
|
||||
.length;
|
||||
|
||||
/// Average amount of time spent per frame in the GPU rasterizer.
|
||||
/// Average amount of time spent per frame in the engine rasterizer.
|
||||
///
|
||||
/// Returns null if no frames were recorded.
|
||||
double computeAverageFrameRasterizerTimeMillis() {
|
||||
|
@ -96,6 +96,61 @@ class TimelineSummary {
|
|||
int countRasterizations() => _extractGpuRasterizerDrawDurations().length;
|
||||
|
||||
/// Encodes this summary as JSON.
|
||||
///
|
||||
/// Data ends with "_time_millis" means time in milliseconds and numbers in
|
||||
/// the "frame_build_times", "frame_rasterizer_times", "frame_begin_times" and
|
||||
/// "frame_rasterizer_begin_times" lists are in microseconds.
|
||||
///
|
||||
/// * "average_frame_build_time_millis": Average amount of time spent per
|
||||
/// frame in the framework building widgets, updating layout, painting and
|
||||
/// compositing.
|
||||
/// See [computeAverageFrameBuildTimeMillis].
|
||||
/// * "90th_percentile_frame_build_time_millis" and
|
||||
/// "99th_percentile_frame_build_time_millis": The p-th percentile frame
|
||||
/// rasterization time in milliseconds. 90 and 99-th percentile number is
|
||||
/// usually a better metric to estimate worse cases. See discussion in
|
||||
/// https://github.com/flutter/flutter/pull/19121#issuecomment-419520765
|
||||
/// See [computePercentileFrameBuildTimeMillis].
|
||||
/// * "worst_frame_build_time_millis": The longest frame build time.
|
||||
/// See [computeWorstFrameBuildTimeMillis].
|
||||
/// * "missed_frame_build_budget_count': The number of frames that missed
|
||||
/// the [kBuildBudget] and therefore are in the danger of missing frames.
|
||||
/// See [computeMissedFrameBuildBudgetCount].
|
||||
/// * "average_frame_rasterizer_time_millis": Average amount of time spent
|
||||
/// per frame in the engine rasterizer.
|
||||
/// See [computeAverageFrameRasterizerTimeMillis].
|
||||
/// * "90th_percentile_frame_rasterizer_time_millis" and
|
||||
/// "99th_percentile_frame_rasterizer_time_millis": The 90/99-th percentile
|
||||
/// frame rasterization time in milliseconds.
|
||||
/// See [computePercentileFrameRasterizerTimeMillis].
|
||||
/// * "worst_frame_rasterizer_time_millis": The longest frame rasterization
|
||||
/// time.
|
||||
/// See [computeWorstFrameRasterizerTimeMillis].
|
||||
/// * "missed_frame_rasterizer_budget_count": The number of frames that missed
|
||||
/// the [kBuildBudget] on the raster thread and therefore are in the danger
|
||||
/// of missing frames.
|
||||
/// See [computeMissedFrameRasterizerBudgetCount].
|
||||
/// * "frame_count": The total number of frames recorded in the timeline. This
|
||||
/// is also the length of the "frame_build_times" and the "frame_begin_times"
|
||||
/// lists.
|
||||
/// See [countFrames].
|
||||
/// * "frame_rasterizer_count": The total number of rasterizer cycles recorded
|
||||
/// in the timeline. This is also the length of the "frame_rasterizer_times"
|
||||
/// and the "frame_rasterizer_begin_times" lists.
|
||||
/// See [countRasterizations].
|
||||
/// * "frame_build_times": The build time of each frame, by tracking the
|
||||
/// [TimelineEvent] with name [kBuildFrameEventName].
|
||||
/// * "frame_rasterizer_times": The rasterize time of each frame, by tracking
|
||||
/// the [TimelineEvent] with name [kRasterizeFrameEventName]
|
||||
/// * "frame_begin_times": The build begin timestamp of each frame.
|
||||
/// * "frame_rasterizer_begin_times": The rasterize begin time of each frame.
|
||||
/// * "average_vsync_transitions_missed": Computes the average of the
|
||||
/// `vsync_transitions_missed` over the lag events.
|
||||
/// See [sceneDisplayLagSummarizer.computeAverageVsyncTransitionsMissed].
|
||||
/// * "90th_percentile_vsync_transitions_missed" and
|
||||
/// "99th_percentile_vsync_transitions_missed": The 90/99-th percentile
|
||||
/// `vsync_transitions_missed` over the lag events.
|
||||
/// See [sceneDisplayLagSummarizer.computePercentileVsyncTransitionsMissed].
|
||||
Map<String, dynamic> get summaryJson {
|
||||
final SceneDisplayLagSummarizer sceneDisplayLagSummarizer = _sceneDisplayLagSummarizer();
|
||||
final Map<String, dynamic> profilingSummary = _profilingSummarizer().summarize();
|
||||
|
@ -135,6 +190,10 @@ class TimelineSummary {
|
|||
}
|
||||
|
||||
/// Writes all of the recorded timeline data to a file.
|
||||
///
|
||||
/// See also:
|
||||
///
|
||||
/// * [Timeline.fromJson], which explains detail about the timeline data.
|
||||
Future<void> writeTimelineToFile(
|
||||
String traceName, {
|
||||
String destinationDirectory,
|
||||
|
@ -202,6 +261,12 @@ class TimelineSummary {
|
|||
|
||||
/// Extracts Duration list that are reported as a pair of begin/end events.
|
||||
///
|
||||
/// Extracts Duration of events by looking for events with the name and phase
|
||||
/// begin ("ph": "B"). This routine assumes that the next event with the same
|
||||
/// name is phase end ("ph": "E"), but it's not examined.
|
||||
/// "SceneDisplayLag" event is an exception, with phase ("ph") labeled
|
||||
/// 'b' and 'e', meaning begin and end phase for an async event.
|
||||
/// See [SceneDisplayLagSummarizer].
|
||||
/// See: https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU
|
||||
List<Duration> _extractBeginEndEvents(String name) {
|
||||
return _extractDurations(
|
||||
|
|
Loading…
Reference in a new issue