Getting Started with Observatory
- Get Observatory
- Start Observatory
- Observatory UI
- VM screen
- What next?
Observatory is one of the tools in the Dart SDK. To get it, you only have to download the SDK.
You can use Dart to create two kinds of applications: standalone applications (including servers), and web applications (which run in a browser). For standalone apps, Observatory can be enabled at the command line. For browser-based apps, Observatory can be opened in any browser using information obtained when launching your app in Dartium from the command line. So you can use Observatory to profile and debug any Dart application.
How you enable Observatory depends on whether you are writing a standalone app or a web app, and how you prefer to work. No matter how you launch Observatory, its UI is exactly the same.
Standalone apps from the command line
To enable Observatory from the command line, specify one or more Observatory options when launching the dart VM. See the dart reference page for a complete list.
$ dart --observe <script>.dart
Open a browser to
http://localhost:8181 to see the Observatory UI.
By default, the VM service binds to localhost—it only accepts connections coming from the same machine. To access a VM running on another machine, you need to forward the port the VM service is bound to. If the target machine is Linux or Mac running ssdh, you can forward the port over ssh like so:
ssh -L8181:127.0.0.1:8181 user@targetmachine
You can also retroactively enable the VM service for a running
process on Linux or Mac by sending the process
(perhaps you have a long-running server that started misbehaving
and you want to investigate why). The process then displays the
port that the VM service is bound to on its stdout.
$ ps ax | grep dart <pid> pts/61 Sl+ 0:01 dart example.dart $ kill -s SIGQUIT <pid> Observatory listening on http://127.0.0.1:<port>
Launch your app in Dartium. You can do this in WebStorm, for example,
index.html and selecting
Run ‘index.html’ from the pop-up menu.
Observatory listening on http://127.0.0.1:56246
Clicking the URL opens Observatory in a new tab.
You can also launch your web app in Dartium from the command line. The following example launches Dartium with the sunflower sample and specifies several flags that are useful for Observatory. For more information, see the dart reference page.
cd <path-to-demo>/sunflower/web <path-to-Dartium>/Chromium.app/Contents/MacOS/Chromium --DART_FLAGS="--steal_breakpoints --pause-isolates-on-start" sunflower.html
cd <path-to-demo>\sunflower\web <path-to-Dartium>\Chromium\Application\chromium.exe --DART_FLAGS="--steal_breakpoints --pause-isolates-on-start" sunflower.html
cd <path-to-demo>/sunflower/web <path-to-Dartium>/chromium-browser --DART_FLAGS="--steal_breakpoints --pause-isolates-on-start" sunflower.html
The command-line output includes a line similar to the following:
Observatory listening on http://127.0.0.1:49621
Open this URL in any browser to bring up Observatory.
Observatory uses a browser-based UI—the UI is the same no matter how it is launched.
A solid blue bar appears at the top of most screens. The word Observatory is on the left. In some screens, a Refresh button is on the right. You can resample the information at any time using the Refresh button. There may also be other buttons on the right that are specific to a particular screen, such as the Clear button in the CPU Profile screen.
A breadcrumb trail, inside the blue bar, shows where you are in the Observatory UI. You can click items in the breadcrumb trail to navigate to other parts of the UI.
If you hover over the items in the breadcrumb bar, drop-down menus
provide additional functionality for each screens. As shown in the
following screenshot, hovering over the root isolate,
in this example, brings up a menu that includes
debugger, cpu profile, allocation profile, and heap map.
You can return to the VM screen at any time by clicking Observatory in the breadcrumb bar.
The next section describes the VM screen, Observatory’s landing page. For a comprehensive list of all screens, see Screens in Observatory.
When you first connect to Observatory, it opens the VM screen, which reflects information available at the moment the app was sampled. For example:
To update the information, click the Refresh button in the upper right corner.
The displayed information includes:
- When the VM was built and for which architecture.
- started at
- The time stamp when the VM was started.
- How long the VM has been running.
- refreshed at
- When the data was last sampled.
- type checks enabled
- True if the VM is checking for type errors.
- asserts enabled
- True if assertion statements are evaluated by the VM.
- The process ID.
Below the VM information is a list of isolates.
Every app has an initial isolate named
For each isolate, a pie chart shows the breakdown of the activities of the VM. For more information on the meaning of these activities, see User and VM Tags.
A list of links take you to various Observatory screens. For more information, see Screens in Observatory.
Clicking the isolate’s name brings up an isolate screen, with detailed information about that isolate. For more information, see Isolate.
Where you should go next depends on what questions you’d like to answer.
- Unfamiliar with the terminology?
- Glossary of VM Terms
- Want to find screens and features in the UI?
- Screens in Observatory
- Want to see where your app is spending its time?
- CPU Profile
- And dive into “power” profiling?
- User and VM Tags
- Want to set breakpoints?
- Or collect metrics about your app?
- Curious about memory allocation?
- Allocation Profile
- And possible memory fragmentation?
- Heap Map
- Want to query (or modify) Dart code?
- Evaluating Expressions
- Want to see if your code has executed?
- Code Coverage
- Want a stack trace?
- Want to know the state of the root isolate or another isolate?