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

NameDescription
noneAll events are dropped.
ringFixed-size buffer. Once full, new events overwrite the oldest events.
startupFixed-size buffer. Once full, new events are dropped.
endlessInfinite buffer. Eventually the process may die from hitting out of memory.
fileWrites 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.

NameDescription
APICalls to the Dart_* embedding API functions.
CompilerTime spent compiling Dart / RegExp to machine code.
CompilerVerboseEvents for detailed compiler phases.
DartEvents created by dart:developer's Timeline etc.
Debugger
EmbedderEvents created by Dart_RecordTimelineEvent.
GCEvents related to garbage collection or heap iteration.
IsolateIsolate or isolate group lifecycle events such as startup or shutdown.
VMVM 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:

FlagExpansion
--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".

Visualization of complete timeline

Example

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

Visualization of file with select streams enabled