Add information about Chrome DevTools extensibility API (#41372)

tunetheweb · web-flow · commit 5143045a1106 · 2025-11-05T12:46:43.000-08:00
* Add information about Chrome DevTools extensibility API

* Review feedback

* More detail
diff --git a/files/en-us/web/api/console/timestamp_static/index.md b/files/en-us/web/api/console/timestamp_static/index.md
@@ -14,21 +14,94 @@ The **`console.timeStamp()`** static method adds a single marker to the browser'
 
 You can optionally supply an argument to label the timestamp, and this label will then be shown alongside the marker.
 
+Some browsers have further extended this `console.timeStamp()` method to allow additional, optional parameters to be provided as part of its extensibility API that surfaces these in performances traces. See the [Chrome's extensibility API documentation](https://developer.chrome.com/docs/devtools/performance/extension#inject_your_data_with_consoletimestamp) for more information.
+
 ## Syntax
 
 ```js-nolint
-console.timeStamp(label)
+console.timeStamp(label);
+console.timeStamp(label, start, end, trackName, trackGroup, color, data);
 ```
 
 ### Parameters
 
+- `color` {{Optional_Inline}} {{Experimental_Inline}}
+  - : A string for the display colour of the entry. Must be one of `"primary"`, `"primary-light"`, `"primary-dark"`, `"secondary"`, `"secondary-light"`, `"secondary-dark"`, `"tertiary"`, `"tertiary-light"`, `"tertiary-dark"`, `"error"`.
+
+- `data` {{Optional_Inline}} {{Experimental_Inline}}
+  - : An object with additional data to display. URLs may automatically be turned into links by some browsers.
+
+- `end` {{Optional_Inline}} {{Experimental_Inline}}
+  - : A string referencing a previously defined `timeStamp` label or a timestamp ({{domxref("DOMHighResTimeStamp")}}) to be used as the end time.
+
 - `label` {{Optional_Inline}}
   - : Label for the timestamp.
 
+- `start` {{Optional_Inline}} {{Experimental_Inline}}
+  - : A string referencing a previously defined `timeStamp` label or a timestamp ({{domxref("DOMHighResTimeStamp")}}) to be used as the start time.
+
+- `trackName` {{Optional_Inline}} {{Experimental_Inline}}
+  - : The name of the custom track used to display the timestamp data
+
+- `trackGroup` {{Optional_Inline}} {{Experimental_Inline}}
+  - : The group of the custom track used to display the timestamp data
+
 ### Return value
 
 None ({{jsxref("undefined")}}).
 
+## Examples
+
+### Basic usage
+
+```js
+console.timeStamp("marker 1");
+```
+
+### Using the Extensibility API to provide richer details for display
+
+```js
+// 1. Create a duration event with rich data
+const start = performance.now() - 150;
+const end = performance.now() - 20;
+
+const durationData = {
+  processingTime: `${end - start}ms`,
+  info: "Check this URL: https://example.com for more.",
+  metrics: {
+    items: 5,
+    isCached: true,
+  },
+};
+
+console.timeStamp(
+  "My Timed Task", // label
+  start, // startTime
+  end, // endTime
+  "Tasks", // trackName
+  "My Extension", // trackGroup
+  "tertiary", // color
+  durationData, // data (object)
+);
+
+// 2. Create an instant event with a deep link for a DevTools extension
+const linkData = {
+  url: "ext://resource/123",
+  description: "View Resource 123",
+  otherDetail: "This data also appears in the JSON viewer",
+};
+
+console.timeStamp(
+  "Event with Link", // label
+  performance.now(), // startTime (instant)
+  undefined, // endTime (instant)
+  "Tasks", // trackName
+  "My Extension", // trackGroup
+  "primary-light", // color
+  linkData, // data (object)
+);
+```
+
 ## Browser compatibility
 
 {{Compat}}
@@ -41,3 +114,4 @@ None ({{jsxref("undefined")}}).
 - {{domxref("performance/mark", "performance.mark()")}}
 - {{domxref("performance/measure", "performance.measure()")}}
 - [Adding markers with the console API](https://web.archive.org/web/20211207010020/https://firefox-source-docs.mozilla.org/devtools-user/performance/waterfall/index.html#adding-markers-with-the-console-api)
+- [Chrome DevTools extensibility API](https://developer.chrome.com/docs/devtools/performance/extension#inject_your_data_with_consoletimestamp)
diff --git a/files/en-us/web/api/performance/mark/index.md b/files/en-us/web/api/performance/mark/index.md
@@ -21,10 +21,22 @@ mark(name, markOptions)
 
 - `name`
   - : A string representing the name of the mark. Must not be the same name as one of the properties of the deprecated {{domxref("PerformanceTiming")}} interface.
+
 - `markOptions` {{optional_inline}}
   - : An object for specifying a timestamp and additional metadata for the mark.
     - `detail` {{optional_inline}}
       - : Arbitrary metadata to include in the mark. Defaults to `null`. Must be [structured-cloneable](/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm).
+        - `devtools` {{optional_inline}} {{experimental_inline}}
+          - : Some browsers have use a structured `devtools` object within the `detail` object as part of an Extensibility API that surfaces these in custom tracks in performance traces. See the [Chrome's Extensibility API documentation](https://developer.chrome.com/docs/devtools/performance/extension#inject_your_data_with_the_user_timings_api) for more information.
+            - `dataType` {{experimental_inline}}
+              - : A string which must be set to `marker`. Identifies as a marker.
+            - `color` {{optional_inline}} {{experimental_inline}}
+              - : Defaults to `"primary"`. Must be one of `"primary"`, `"primary-light"`, `"primary-dark"`, `"secondary"`, `"secondary-light"`, `"secondary-dark"`, `"tertiary"`, `"tertiary-light"`, `"tertiary-dark"`, `"error"`.
+            - `properties` {{optional_inline}} {{experimental_inline}}
+              - : Array of key-value pairs. Values can be any JSON-compatible type.
+            - `tooltipText` {{optional_inline}} {{experimental_inline}}
+              - : Short description for tooltip.
+
     - `startTime` {{optional_inline}}
       - : {{domxref("DOMHighResTimeStamp")}} to use as the mark time. Defaults to {{domxref("performance.now()")}}.
 
@@ -80,6 +92,27 @@ performance.mark("login-button-pressed", {
 });
 ```
 
+### DevTools Extensibility API
+
+For browsers that support the [Extensibility API](https://developer.chrome.com/docs/devtools/performance/extension) you can use the `detail` parameter to provide more details in a `devtools` object that will be used to display this in performance profiles:
+
+```js
+// Marker indicating when the processed image was uploaded
+performance.mark("Image Upload", {
+  detail: {
+    devtools: {
+      dataType: "marker",
+      color: "secondary",
+      properties: [
+        ["Image Size", "2.5MB"],
+        ["Upload Destination", "Cloud Storage"],
+      ],
+      tooltipText: "Processed image uploaded",
+    },
+  },
+});
+```
+
 ### Reserved names
 
 Note in order to maintain backwards compatibility, names that are part of the deprecated {{domxref("PerformanceTiming")}} interface can't be used. The following example throws:
diff --git a/files/en-us/web/api/performance/measure/index.md b/files/en-us/web/api/performance/measure/index.md
@@ -39,20 +39,37 @@ To only provide an `endMark`, you need to provide an empty `measureOptions` obje
   - : An object that may contain measure options.
     - `detail` {{optional_inline}}
       - : Arbitrary metadata to be included in the measure. Defaults to `null`. Must be [structured-cloneable](/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm).
+        - `devtools`
+          - : Some browsers have use a structured `devtools` object within the `detail` object as part of an Extensibility API that surfaces these in custom tracks in performance traces. See the [Chrome's Extensibility API documentation](https://developer.chrome.com/docs/devtools/performance/extension#inject_your_data_with_the_user_timings_api) for more information.
+            - `dataType` {{experimental_inline}}
+              - : String with a value of `track-entry` (for defining a new track) or `marker` (for defining an entry in a track).
+            - `color` {{optional_inline}} {{experimental_inline}}
+              - : Defaults to `"primary"`. Must be one of `"primary"`, `"primary-light"`, `"primary-dark"`, `"secondary"`, `"secondary-light"`, `"secondary-dark"`, `"tertiary"`, `"tertiary-light"`, `"tertiary-dark"`, `"error"`.
+            - `track` {{optional_inline}} {{experimental_inline}}
+              - : String of the name of the custom track (required for `track-entry`)
+            - `trackGroup` {{optional_inline}} {{experimental_inline}}
+              - : String of the name of the grouping withing a custom track (required for `track-entry`)
+            - `properties` {{optional_inline}} {{experimental_inline}}
+              - : Array of key-value pairs. Values can be any JSON-compatible type.
+            - `tooltipText` {{optional_inline}} {{experimental_inline}}
+              - : Short description for tooltip.
+
     - `start` {{optional_inline}}
       - : Timestamp ({{domxref("DOMHighResTimeStamp")}}) to be used as the start time, or string that names a {{domxref("PerformanceMark")}} to use for the start time.
 
         If this is a string naming a {{domxref("PerformanceMark")}}, then it is defined in the same way as `startMark`.
 
     - `duration` {{optional_inline}}
       - : Duration (in milliseconds) between the start and end mark times. If omitted, this defaults to {{domxref("performance.now()")}}; the time that has elapsed since the context was created. If provided, you must also specify either `start` or `end` but not both.
+
     - `end` {{optional_inline}}
       - : Timestamp ({{domxref("DOMHighResTimeStamp")}}) to be used as the end time, or string that names a {{domxref("PerformanceMark")}} to use for the end time.
 
         If this is a string naming a {{domxref("PerformanceMark")}}, then it is defined in the same way as `endMark`.
 
 - `startMark` {{optional_inline}}
   - : A string naming a {{domxref("PerformanceMark")}} in the performance timeline. The {{domxref("PerformanceEntry.startTime")}} property of this mark will be used for calculating the measure.
+
 - `endMark` {{optional_inline}}
   - : A string naming a {{domxref("PerformanceMark")}} in the performance timeline. The {{domxref("PerformanceEntry.startTime")}} property of this mark will be used for calculating the measure.
     If you want to pass this argument, you must also pass either `startMark` or an empty `measureOptions` object.
@@ -140,6 +157,44 @@ performance.measure("login-click", {
 });
 ```
 
+### DevTools Extensibility API
+
+For browsers that support the [Extensibility API](https://developer.chrome.com/docs/devtools/performance/extension) you can use the `detail` parameter to provide more details in a `devtools` object that will be used to display this in performance profiles:
+
+```js
+const imageProcessingTimeStart = performance.now();
+
+// ... later in your code
+
+performance.measure("Image Processing Complete", {
+  start: imageProcessingTimeStart,
+  end: performance.now(),
+  detail: {
+    // This data appears in the "Summary"
+    extraInfo: {
+      imageId: "xyz-123",
+      source: "cache",
+      checkUrl: "https://example.com/check/xyz-123",
+    },
+    // The devtools object controls the track visualization
+    devtools: {
+      dataType: "track-entry",
+      track: "Image Processing Tasks",
+      trackGroup: "My Tracks",
+      color: "tertiary-dark",
+      properties: [
+        ["Filter Type", "Gaussian Blur"],
+        // Values can be objects, arrays, or other types
+        ["Resize Dimensions", { w: 500, h: 300 }],
+        // String values that are URLs get linkified
+        ["Image URL", "https://example.com/img.png"],
+      ],
+      tooltipText: "Image processed successfully",
+    },
+  },
+});
+```
+
 ## Specifications
 
 {{Specifications}}
diff --git a/files/en-us/web/api/performancemark/index.md b/files/en-us/web/api/performancemark/index.md
@@ -20,6 +20,9 @@ Entries of this type are typically created by calling {{domxref("Performance.mar
 
 ## Instance properties
 
+- {{domxref("PerformanceMark.detail")}}
+  - : Contains arbitrary metadata about the measure.
+
 This interface extends the following {{domxref("PerformanceEntry")}} properties by qualifying/constraining the properties as follows:
 
 - {{domxref("PerformanceEntry.entryType")}} {{ReadOnlyInline}}
@@ -31,11 +34,6 @@ This interface extends the following {{domxref("PerformanceEntry")}} properties
 - {{domxref("PerformanceEntry.duration")}} {{ReadOnlyInline}}
   - : Returns `0`. (A mark has no _duration_.)
 
-This interface also supports the following properties:
-
-- {{domxref("PerformanceMark.detail")}} {{ReadOnlyInline}}
-  - : Returns arbitrary metadata that has been included in the mark upon construction.
-
 ## Instance methods
 
 This interface has no methods.
@@ -44,6 +42,8 @@ This interface has no methods.
 
 See the example in [Using the User Timing API](/en-US/docs/Web/API/Performance_API/User_timing).
 
+Chrome DevTools uses `performance.mark()` and in particular a structured `detail` property as part of its extensibility API that surfaces these in custom tracks in performance traces. See the example in [Performance: mark() method](/en-US/docs/Web/API/Performance/mark) page and the [Chrome's extensibility API documentation](https://developer.chrome.com/docs/devtools/performance/extension#inject_your_data_with_the_user_timings_api) for more information and examples.
+
 ## Specifications
 
 {{Specifications}}
diff --git a/files/en-us/web/api/performancemark/performancemark/index.md b/files/en-us/web/api/performancemark/performancemark/index.md
@@ -27,6 +27,16 @@ new PerformanceMark(name, markOptions)
   - : An object for specifying a timestamp and additional metadata for the mark.
     - `detail` {{optional_inline}}
       - : Arbitrary metadata to include in the mark. Defaults to `null`.
+        - `devtools` {{optional_inline}} {{experimental_inline}}
+          - : Some browsers have use a structured `devtools` object within the `detail` object as part of an Extensibility API that surfaces these in custom tracks in performance traces. See the [Chrome's Extensibility API documentation](https://developer.chrome.com/docs/devtools/performance/extension#inject_your_data_with_the_user_timings_api) for more information.
+            - `dataType` {{experimental_inline}}
+              - : A string which must be set to `marker`. Identifies as a marker.
+            - `color` {{optional_inline}} {{experimental_inline}}
+              - : Defaults to `"primary"`. Must be one of `"primary"`, `"primary-light"`, `"primary-dark"`, `"secondary"`, `"secondary-light"`, `"secondary-dark"`, `"tertiary"`, `"tertiary-light"`, `"tertiary-dark"`, `"error"`.
+            - `properties` {{optional_inline}} {{experimental_inline}}
+              - : Array of key-value pairs. Values can be any JSON-compatible type.
+            - `tooltipText` {{optional_inline}} {{experimental_inline}}
+              - : Short description for tooltip.
     - `startTime` {{optional_inline}}
       - : {{domxref("DOMHighResTimeStamp")}} to use as the mark time. Defaults to {{domxref("performance.now()")}}.
 
@@ -41,6 +51,8 @@ A {{domxref("PerformanceMark")}} object.
 
 ## Examples
 
+### Creating named markers
+
 The following example shows how {{domxref("PerformanceMark")}} entries are constructed and then aren't part of the browser's performance timeline.
 
 ```js
@@ -53,6 +65,27 @@ console.log(allEntries.length);
 // 0
 ```
 
+### DevTools Extensibility API
+
+For browsers that support the [Extensibility API](https://developer.chrome.com/docs/devtools/performance/extension) you can use the `detail` parameter to provide more details in a `devtools` object that will be used to display this in performance profiles:
+
+```js
+// Marker indicating when the processed image was uploaded
+performance.mark("Image Upload", {
+  detail: {
+    devtools: {
+      dataType: "marker",
+      color: "secondary",
+      properties: [
+        ["Image Size", "2.5MB"],
+        ["Upload Destination", "Cloud Storage"],
+      ],
+      tooltipText: "Processed image uploaded",
+    },
+  },
+});
+```
+
 ## Specifications
 
 {{Specifications}}
diff --git a/files/en-us/web/api/performancemeasure/index.md b/files/en-us/web/api/performancemeasure/index.md
@@ -13,12 +13,10 @@ browser-compat: api.PerformanceMeasure
 
 ## Instance properties
 
-This interface defines:
-
 - {{domxref("PerformanceMeasure.detail")}}
   - : Contains arbitrary metadata about the measure.
 
-In addition, it extends the following {{domxref("PerformanceEntry")}} properties by qualifying/constraining the properties as follows:
+This interface extends the following {{domxref("PerformanceEntry")}} properties by qualifying/constraining the properties as follows:
 
 - {{domxref("PerformanceEntry.entryType")}}
   - : Returns `"measure"`.
@@ -37,6 +35,8 @@ This interface has no methods.
 
 See the example in [Using the User Timing API](/en-US/docs/Web/API/Performance_API/User_timing).
 
+Chrome DevTools uses `performance.measure()` and in particular a structured `detail` property as part of its extensibility API that surfaces these in custom tracks in performance traces. See the example in [Performance: measure() method](/en-US/docs/Web/API/Performance/measure) page and the [Chrome's extensibility API documentation](https://developer.chrome.com/docs/devtools/performance/extension#inject_your_data_with_the_user_timings_api) for more information and examples.
+
 ## Specifications
 
 {{Specifications}}
