Customize your performance data with extensibility API

Andrés Olivares

Sofia Emelianova

Overview

The Performance panel supports the performance extensibility API that lets you add your own custom data to the performance timeline.

This API leverages the existing User Timings API and lets you inject your measurements and events directly into the performance timeline as a custom track or in the Timings track. This may be useful for developers of frameworks, libraries, and complex applications with custom instrumentation to gain a more comprehensive understanding of performance.

Key features

• Custom tracks: Create dedicated tracks to visualize your own time-based data.
• Entries: Populate tracks with entries representing events or measurements.
• Tooltips and details: Provide rich context for entries with customizable tooltips and detailed views.
• Markers: Highlight specific moments in the timeline with visual markers.

Inject your data with the User Timings API

To inject custom data, include a devtools object within the detail property of performance.mark and performance.measure methods. The structure of this devtools object determines how your data is displayed in the Performance panel.

• Use performance.mark to record an instant event or timestamp in the timeline. You can mark the start or end of a specific operation or any point of interest that doesn't have a duration. When you include a devtools object within the detail property, the Performance panel shows a custom marker in the timeline.

• Use performance.measure to measure the duration of a task or process. When you include a devtools object within the detail property, the Performance panel shows custom measurement entries in the timeline. If you're using performance.mark as a reference point to create a performance.measure, you don't need to include the devtools object in performance.mark calls.

devtools object

These types define the structure of the devtools object for different extension features:

type DevToolsColor =
  "primary" | "primary-light" | "primary-dark" |
  "secondary" | "secondary-light" | "secondary-dark" |
  "tertiary" | "tertiary-light" | "tertiary-dark" |
  "error";

interface ExtensionTrackEntryPayload {
  dataType?: "track-entry"; // Defaults to "track-entry"
  color?: DevToolsColor;    // Defaults to "primary"
  track: string;            // Required: Name of the custom track
  trackGroup?: string;      // Optional: Group for organizing tracks
  properties?: [string, string][]; // Key-value pairs for detailed view
  tooltipText?: string;     // Short description for tooltip
}

interface ExtensionMarkerPayload {
  dataType: "marker";       // Required: Identifies as a marker
  color?: DevToolsColor;    // Defaults to "primary"
  properties?: [string, string][]; // Key-value pairs for detailed view
  tooltipText?: string;     // Short description for tooltip
}

View your data in the timeline

To see your custom data in the timeline, in the Performance panel, turn on settings Capture settings > check_box Extension data.

Try it on this demo page. Turn on Extension data, start a performance recording, click Add new Corgi on the demo page, then stop the recording. You'll see a custom track in the trace that contains events with custom tooltips and details in the Summary tab.

Code examples

In the next sections, see the examples of code that showcase how to add the following to the performance timeline:

• Custom tracks and entries to the timeline
• Markers to the Timings track

Custom tracks and entries

Create custom tracks and populate them with entries to visualize your performance data in a custom track. For example:

// Mark used to represent the start of an image processing task
performance.mark("Image Processing Start");

// ... later in your code

// Track entry representing the completion of image processing
// with additional details and a tooltip
performance.measure("Image Processing Complete", "Image Processing Start", {
  detail: {
    devtools: {
      dataType: "track-entry",
      track: "Image Processing Tasks",
      trackGroup: "My Tracks", // Group related tracks together
      color: "tertiary-dark",
      properties: [
        ["Filter Type", "Gaussian Blur"],
        ["Resize Dimensions", "500x300"]
      ],
      tooltipText: "Image processed successfully"
    }
  }
});

This results in the following custom track entry in the performance timeline, along with its tooltip text and properties:

Markers

Visually highlight specific points of interest in the timeline with custom markers that span across all tracks. For example:

// 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"
    }
  }
});

This results in the following marker in the Timings track, along with its tooltip text and properties: