Observatory Docs Home | Edit these docs

User and VM Tags

Observatory uses tags to identify categories of execution. Most of the predefined (default) tags identify VM activities that you don’t have direct control over, such as garbage collection. An exception is the Dart tag, which identifies the execution of Dart code, including your Dart code and the Dart code in libraries that you use. The predefined tags are explained in VM tags.

If you’d like to add custom tags, you can define user tags, which appear only when using the CPU Profile screen.

User tags

Observatory samples a running application and, when Dart code is executing, labels those samples with the Dart tag. When you view the resulting data in the profile tree, the Dart percentage tells you how your code has performed compared to other VM tasks.

This information is somewhat useful, but it does not tell you about the performance of the code inside your app.

For example, are there any bottlenecks? Does initialization take too long? What are the slowest activities? Maybe those can be deferred, or moved to another isolate. Is there a more efficient sorting algorithm for your data? Would caching calculated values improve performance enough to make the effort worthwhile?

This sort of performance tuning requires more finely grained reporting. You can achieve this when you label your code with custom tags, called user tags, using the dart:developer library.

Defining user tags

You can bracket any piece of code with a user tag. Only one tag can be currently active—when you install a new current tag, you must stash the previous tag, and restore it when your code has completed.

The following snippet shows how to mark a piece of code with a tag named MyTag:

import 'dart:developer';

var customTag = new UserTag('MyTag');

// Save the previous tag when installing the custom tag.
var previousTag = customTag.makeCurrent();

// your code here

// Restore the previous tag.

When you now run your app, the MyTag label appears in the CPU profile for the corresponding isolate. The following example shows an InitCircle tag added to code that initializes a circle stress demo and a MainApp tag added in the main() method:

example showing user defined tags

VM tags

Observatory defines the following, default VM tags, which are used throughout the UI:

CompileOptimized, CompileScanner, CompileTopLevel, CompileUnoptimized

Compiling Dart code.


Garbage collecting new generation.


Garbage collecting old generation.


Not a VM tag, per se, the Idle label often appears alongside the VM tags (on the VM and isolate screens, for example) to indicate the percentage of samples where the isolate was not scheduled. (Perhaps it was waiting for asynchronous I/O or maybe it had finished executing but was idling until released.)


Executing native (platform specific) code—for example, the C++ code used by the dart:io library.


Executing runtime code.


Executing your Dart code.


Starting an isolate. This category also includes VM activity not covered by the other tags.

Privacy Policy