Настройте свои данные о производительности с помощью расширяемого API

Андрес Оливарес
Andrés Olivares
София Емельянова
Sofia Emelianova

Обзор

Панель «Производительность» поддерживает API расширения производительности, позволяющий добавлять пользовательские данные на временную шкалу производительности. Это позволяет вам вводить измерения и события непосредственно на временную шкалу производительности в виде пользовательской дорожки или дорожки времени . Это может быть полезно разработчикам платформ, библиотек и сложных приложений со специальными инструментами, чтобы получить более полное представление о производительности.

Этот API предлагает два различных механизма:

1. API пользовательского времени (с использованием performance.mark и performance.measure ).

Этот API использует существующий API User Timings . Он также добавляет записи во внутреннюю шкалу производительности браузера, что позволяет проводить дальнейший анализ и интеграцию с другими инструментами производительности.

2. API console.timeStamp (расширенный для DevTools)

Этот API предоставляет высокопроизводительный метод инструментирования приложений и отображения данных синхронизации исключительно на панели «Производительность» в DevTools. Он разработан с минимальными накладными расходами во время выполнения, что делает его пригодным для инструментирования «горячих» путей и производственных сборок. Он не добавляет записи во внутреннюю шкалу производительности браузера.

Ключевые особенности

Оба API предлагают:

  • Пользовательские треки: добавляйте записи в пользовательские треки и группы треков.
  • Записи : заполнение треков записями, представляющими события или измерения.
  • Настройка цвета: записи цветового кода для визуальной дифференциации.

Ключевые различия и когда использовать каждый API:

  • API пользовательского времени ( performance.mark , performance.measure ):
    • Добавляет записи как на панель «Производительность» , так и на внутреннюю временную шкалу производительности браузера.
    • Позволяет использовать обширные данные, включая всплывающие подсказки и подробные свойства.
    • Позволяет добавлять маркеры . Выделяйте определенные моменты на временной шкале с помощью визуальных маркеров.
    • Подходит для детального анализа производительности и в случаях, когда требуется интеграция с другими инструментами производительности.
    • Используйте, когда вам нужно хранить дополнительные данные с каждой записью и когда вы уже используете API User Timings.
  • API console.timeStamp :
    • Добавляет записи только на панель «Производительность» .
    • Обеспечивает значительно более высокую производительность, особенно в производственных средах.
    • Идеально подходит для инструментирования горячих путей и кода, критичного к производительности.
    • Никакие дополнительные данные, такие как всплывающие подсказки или свойства, добавить нельзя.
    • Используйте, когда накладные расходы на производительность являются основной проблемой и вам необходимо быстро инструментировать код.

Внедряйте свои данные с помощью API User Timings.

Чтобы внедрить пользовательские данные, включите объект devtools в свойство detail методов performance.mark и performance.measure . Структура этого объекта devtools определяет, как ваши данные отображаются на панели «Производительность» .

  • Используйте performance.mark для записи мгновенного события или отметки времени на временной шкале. Вы можете отметить начало или конец определенной операции или любой достопримечательности, не имеющей продолжительности. Когда вы включаете объект devtools в свойство detail , на панели «Производительность» отображается настраиваемый маркер на дорожке «Тайминги» .

  • Используйте performance.measure для измерения продолжительности задачи или процесса. Когда вы включаете объект devtools в свойство detail , на панели «Производительность» отображаются записи пользовательских измерений на временной шкале в пользовательской дорожке. Если вы используете performance.mark в качестве ориентира для создания performance.measure , вам не нужно включать объект devtools в вызовы performance.mark .

объект devtools

Эти типы определяют структуру объекта devtools для различных функций расширения:

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
}

Вставьте свои данные с помощью console.timeStamp

API console.timeStamp расширен и теперь позволяет создавать собственные записи времени на панели «Производительность» с минимальными накладными расходами.

console.timeStamp(label: string, start?: string, end?: string, trackName?: string, trackGroup?: string, color?: DevToolsColor);
  • label : Метка для записи времени.
  • start : имя ранее записанной метки времени (с использованием console.timeStamp(timeStampName) ). Если не определено, используется текущее время.
  • end : имя ранее записанной временной метки. Если не определено, используется текущее время.
  • trackName : имя пользовательского трека.
  • trackGroup : название группы треков.
  • color : цвет записи.

Просматривайте свои данные на временной шкале

Чтобы увидеть свои пользовательские данные на временной шкале, на панели «Производительность» включите «Настройки захвата» > «Данные расширения» .

Флажок «Расширение данных» в разделе «Настройки захвата» на панели «Производительность».

Попробуйте это на этой демонстрационной странице . Включите данные расширения , начните запись выступления, нажмите «Добавить нового корги» на демонстрационной странице, затем остановите запись. В трассировке вы увидите настраиваемую дорожку, содержащую события с настраиваемыми подсказками и подробностями на вкладке «Сводка» .

Примеры кода

Вот несколько примеров использования API для добавления собственных данных на панель «Производительность» с использованием каждого доступного механизма.

Примеры API пользовательского времени:

В следующих разделах приведены примеры кода, демонстрирующие, как добавить на временную шкалу производительности следующее:

Пользовательские треки и записи

Создавайте собственные треки и заполняйте их записями, чтобы визуализировать данные о своей производительности в пользовательском треке. Например:

// Mark used to represent the start of the image processing task
// The start time is defaulted to now
performance.mark("Image Processing Start");

// ... later in your code

// Track entry representing the completion of image processing
// with additional details and a tooltip
// The start time is a marker from earlier
// The end time is defaulted to now
performance.measure("Image Processing Complete", {
  start: "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"
    }
  }
});

В результате на временной шкале производительности появится следующая пользовательская запись трека вместе с текстом и свойствами всплывающей подсказки:

Пользовательский трек на временной шкале производительности.

Маркеры

Визуально выделяйте определенные точки интереса на временной шкале с помощью настраиваемых маркеров, охватывающих все дорожки. Например:

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

В результате на дорожке «Тайминги» появится следующий маркер вместе с текстом и свойствами его всплывающей подсказки:

Пользовательский маркер на дорожке времени.

Примеры API console.timeStamp :

// Record a start timestamp
console.timeStamp("start");

// Measure duration from start to now
console.timeStamp("measure 1", "start", undefined, "My Track", "My Group", "primary-light");

// Record an end timestamp
console.timeStamp("end");

// Measure duration from start to end
console.timeStamp("measure 2", "start", "end", "My Track", "My Group", "secondary-dark");

В результате на временной шкале производительности появится следующая пользовательская запись трека:

Пользовательский трек с пользовательскими записями, добавленными с помощью API console.timeStamp.