dart-sdk/runtime/docs/timeline.md

Timeline

The timeline, also called tracing, provides a way to see when manually annotated events are running and how much time they are taking.

Recorders

Name	Description
none	All events are dropped.
ring	Fixed-size buffer. Once full, new events overwrite the oldest events.
startup	Fixed-size buffer. Once full, new events are dropped.
endless	Infinite buffer. Eventually the process may die from hitting out of memory.
file	Writes events to a file in Chrome Trace Format. This format can be visualized with chrome://tracing.
systrace (Linux/Android)	Writes events to Systrace.
systrace (Fuchsia)	Writes events to Fuchsia tracing.
systrace (Mac/iOS)	Writes events to Signposts.

The recorder can be selected with the timeline_recorder flag. E.g., --timeline_recorder=startup or --timeline_recorder=file=mytrace.json.

If the recorder uses a VM-internal buffer (ring, startup, endless), then the timeline can be retrieved using the getVMTimeline method of the VM service.

Streams

Streams, also called categories, are sets of events whose recordering can be enabled or disabled.

Name	Description
API	Calls to the Dart_* embedding API functions.
Compiler	Time spent compiling Dart / RegExp to machine code.
CompilerVerbose	Events for detailed compiler phases.
Dart	Events created by dart:developer's Timeline etc.
Debugger
Embedder	Events created by Dart_TimelineEvent.
GC	Events related to garbage collection or heap iteration.
Isolate	Isolate or isolate group lifecycle events such as startup or shutdown.
VM	VM lifecycle events such a startup or shutdown.

The set of enabled streams can be selected with the timeline_streams flag. E.g., --timeline_stream=VM,Isolate,GC,Dart or --timeline_streams=All.

The set of enabled streams can also be changed at runtime using the setVMTimelineFlags method of the VM service.

Usage

There are also some convenience flags:

Flag	Expansion
--timeline_streams=All	--timeline_streams=API,Compiler,CompilerVerbose,Dart,Debugger,Embedder,GC,Isolate,VM
--complete_timeline	--timeline_recorder=endless --timeline_streams=All
--startup_timeline	--timeline_recorder=startup --timeline_streams=All

Example

$ dart --observe --complete-timeline hello.dart
The Dart VM service is listening on http://127.0.0.1:8181/U9AvIH-PxG8=/
# Navigate to the URL, and select "view timeline".

Example

$ dart --timeline_recorder=file:mytimeline.json --timeline_streams=VM,Isolate,GC,Dart hello.dart
# Navigate to chrome://tracing and load mytimeline.json.