mirror of
https://github.com/dart-lang/sdk
synced 2024-09-05 08:24:39 +00:00
[vm] Timeline docs.
Change-Id: Ie9415e02adc84a1f01178f16585f2bb6e7436f3f Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/286863 Reviewed-by: Martin Kustermann <kustermann@google.com>
This commit is contained in:
parent
8617cc68fa
commit
203998d021
BIN
runtime/docs/timeline-complete.webp
Normal file
BIN
runtime/docs/timeline-complete.webp
Normal file
Binary file not shown.
After Width: | Height: | Size: 37 KiB |
BIN
runtime/docs/timeline-file.webp
Normal file
BIN
runtime/docs/timeline-file.webp
Normal file
Binary file not shown.
After Width: | Height: | Size: 28 KiB |
67
runtime/docs/timeline.md
Normal file
67
runtime/docs/timeline.md
Normal file
|
@ -0,0 +1,67 @@
|
|||
# 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](https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU). This format can be visualized with `chrome://tracing`. |
|
||||
| `systrace` (Linux/Android) | Writes events to [Systrace](https://source.android.com/docs/core/tests/debug/systrace). |
|
||||
| `systrace` (Fuchsia) | Writes events to [Fuchsia tracing](https://fuchsia.dev/fuchsia-src/development/tracing/). |
|
||||
| `systrace` (Mac/iOS) | Writes events to [Signposts](https://help.apple.com/instruments). |
|
||||
|
||||
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](../vm/service/service.md).
|
||||
|
||||
## 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](../vm/service/service.md).
|
||||
|
||||
## 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".
|
||||
```
|
||||
![Visualization of complete timeline](timeline-complete.webp)
|
||||
|
||||
### 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](timeline-file.webp)
|
Loading…
Reference in a new issue