Как настроить данные об эффективности с помощью API расширяемости

Andrés Olivares

Sofia Emelianova

Обзор

Хотите получать более подробную статистику эффективности приложения, чем та, которая доступна в браузере? Теперь на панели Производительность можно добавлять собственные данные о производительности прямо на временную шкалу. Независимо от того, являетесь ли вы автором фреймворка, которому необходимо визуализировать внутренние процессы, разработчиком библиотеки, отслеживающим влияние вашего кода, или создаете сложное приложение с настраиваемыми инструментами, API расширяемости производительности предоставляет инструменты для получения по-настоящему всестороннего понимания того, что происходит под капотом.

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

API предлагает два подхода:

1. API console.timeStamp (расширенная версия для инструментов разработчика)

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

2. User Timings API (с помощью performance.mark и performance.measure).

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

Основные преимущества

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

• Собственные треки. Добавляйте отдельные треки и группы треков, чтобы отслеживать уникальные аспекты производительности кода.
• Записи. Добавляйте в дорожки записи, которые четко обозначают важные события или продолжительность определенных операций.
• Настройка цвета. Используйте цветовое кодирование, чтобы визуально различать разные типы событий или измерений.

Как выбрать API, который вам подходит

• console.timeStamp API:

  • Влияние инструментирования на производительность является основной проблемой, особенно в производственных сборках.
  • Вам нужен быстрый и эффективный способ отмечать временные отрезки или события без необходимости добавлять дополнительные метаданные.
  • Вам нужно только визуализировать данные на панели "Производительность".

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

  • Используйте, если вам нужно хранить дополнительные данные с каждой записью и вы уже используете API Пользовательского времени.
  • Вам нужно связать наглядные данные (подсказки, подробные свойства) с записями о производительности.
  • Вы хотите добавить визуальные маркеры, чтобы выделить определенные моменты.
  • Вам нужно, чтобы данные были доступны не только в инструментах разработчика, но и во внутренней временной шкале производительности браузера для более широкого анализа или других инструментов.
  • Вы уже знакомы с User Timings API или используете его.

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

API console.timeStamp расширен и позволяет создавать пользовательские записи времени на панели Производительность с минимальными затратами, особенно когда DevTools не записывает трассировку.

console.timeStamp(label: string, start?: string|number, end?: string|number, trackName?: string, trackGroup?: string, color?: DevToolsColor);

• label:

  Ярлык для записи о времени.

• start (необязательно):

  • Если задано как строка, то это название ранее записанной временной метки (с помощью console.timeStamp(timeStampName)).

  • Если задано как число: временная метка в миллисекундах относительно Performance.timeOrigin (например, полученная с помощью performance.now()), которая представляет время начала записи.

  • Если не указано, в качестве времени начала используется текущее время.

• end:

  • Если задано как строка: название ранее записанной временной метки.

  • Если задано как число: временная метка в миллисекундах относительно Performance.timeOrigin (например, полученная с помощью performance.now()), которая представляет время окончания записи.

  • Если значение не задано, в качестве времени окончания используется текущее время.

• trackName:

  Название пользовательской версии.

• trackGroup:

  Название группы дорожек.

• color:

  Цвет записи.

Как передавать данные с помощью User Timings API

Чтобы добавить специальные данные, включите объект 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
}

Как посмотреть данные в хронологии

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

Попробуйте сделать это на демонстрационной странице. Начните запись производительности, нажмите Add new Corgi (Добавить нового корги) на странице демоверсии, а затем остановите запись. В трассировке появится специальная дорожка с событиями, для которых заданы специальные подсказки, подробная информация на вкладке Сводка и сводки групп специальных дорожек в сводке трассировки.

Примеры кода

Ниже приведены примеры того, как с помощью API добавить собственные данные на панель Производительность, используя каждый из доступных механизмов.

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

// Take a start timestamp
const start = performance.now();

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

// Take an end timestamp
const end = performance.now();

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

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

Примеры использования User Timings API

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

• Специальные дорожки и записи на временной шкале
• Маркеры на дорожке временных меток

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

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

// Mark used to represent the start of the image processing task
// The start time is defaulted to now
const imageProcessinTimeStart = performance.now();

// ... 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: imageProcessinTimeStart,
  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"
    }
  }
});

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