[vm] Document clock compatibility between Timeline.now and Dart_TimelineGetMicros.

Change-Id: Ife4b5360b9c42221b9dac84014d072f60cd8f11c
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/106720
Commit-Queue: Ryan Macnak <[email protected]>
Reviewed-by: Ben Konyi <[email protected]>
Reviewed-by: Siva Annamalai <[email protected]>

Author: rmacnak-google

runtime/include/dart_tools_api.h

@@ -301,7 +301,8 @@ DART_EXPORT bool Dart_IsReloading();
 
 /**
  * Returns a timestamp in microseconds. This timestamp is suitable for
- * passing into the timeline system.
+ * passing into the timeline system, and uses the same monotonic clock
+ * as dart:developer's Timeline.now.
  *
  * \return A timestamp that can be passed to the timeline system.
  */

runtime/vm/service/service.md

@@ -797,7 +797,8 @@ The _getVMTimeline_ RPC is used to retrieve an object which contains VM timeline
 events.
 
 The _timeOriginMicros_ parameter is the beginning of the time range used to filter
-timeline events.
+timeline events. It uses the same monotonic clock as dart:developer's `Timeline.now`
+and the VM embedding API's `Dart_TimelineGetMicros`.
 
 The _timeExtentMicros_ parameter specifies how large the time range used to filter
 timeline events should be.

runtime/vm/service/service_dev.md

@@ -797,7 +797,8 @@ The _getVMTimeline_ RPC is used to retrieve an object which contains VM timeline
 events.
 
 The _timeOriginMicros_ parameter is the beginning of the time range used to filter
-timeline events.
+timeline events. It uses the same monotonic clock as dart:developer's `Timeline.now`
+and the VM embedding API's `Dart_TimelineGetMicros`.
 
 The _timeExtentMicros_ parameter specifies how large the time range used to filter
 timeline events should be.

sdk/lib/developer/timeline.dart

@@ -166,6 +166,9 @@ class Timeline {
 
   /// The current time stamp from the clock used by the timeline. Units are
   /// microseconds.
+  ///
+  /// When run on the Dart VM, uses the same monotonic clock as the embedding
+  /// API's `Dart_TimelineGetMicros`.
   static int get now => _getTraceClock();
   static final List<_SyncBlock> _stack = new List<_SyncBlock>();
 }