Dostosuj dane o skuteczności za pomocą interfejsu API Extensibility API

Andrés Olivares

Sofia Emelianova

Przegląd

Chcesz uzyskać bardziej szczegółowe informacje o skuteczności aplikacji niż te, które są dostępne w ramach wbudowanych w przeglądarkę danych? Panel Skuteczność umożliwia teraz bezpośrednie dodawanie własnych danych o skuteczności do osi czasu. Niezależnie od tego, czy jesteś autorem frameworka, który chce wizualizować procesy wewnętrzne, deweloperem biblioteki, który śledzi wpływ swojego kodu, czy też tworzysz złożoną aplikację z niestandardową instrumentacją, interfejs API rozszerzalności skuteczności zapewnia narzędzia do uzyskania naprawdę kompleksowego wglądu w to, co dzieje się w tle.

Wstawiając własne pomiary i zdarzenia, możesz tworzyć dostosowane wizualizacje w znanym panelu Skuteczność. Wyobraź sobie, że widzisz zdarzenia cyklu życia komponentu platformy obok standardowych wskaźników skuteczności przeglądarki lub śledzisz przepływ wykonywania własnego silnika renderowania niestandardowego w doskonałej synchronizacji z potokiem renderowania przeglądarki.

Ten interfejs API oferuje 2 sposoby na osiągnięcie tego:

1. Interfejs console.timeStamp API (rozszerzony o Narzędzia deweloperskie)

Ten interfejs API zapewnia wydajną metodę instrumentowania aplikacji i wyświetlania danych o czasie wyłącznie w panelu Skuteczność w Narzędziach deweloperskich. Został zaprojektowany tak, aby minimalizować obciążenie środowiska wykonawczego, dzięki czemu nadaje się do instrumentowania ścieżek krytycznych i kompilacji produkcyjnych. Nie dodaje wpisów do wewnętrznej osi czasu przeglądarki.

2. Interfejs Czas działań użytkownika API (z użyciem performance.mark i performance.measure)

Ten interfejs API korzysta z istniejącego interfejsu Czas działań użytkownika API. Dodaje też wpisy do wewnętrznej osi czasu przeglądarki, co umożliwia dalszą analizę i integrację z innymi narzędziami do analizy skuteczności.

Główne zalety

Oba interfejsy API oferują:

• Ścieżki niestandardowe: dodawaj dedykowane ścieżki i grupy ścieżek, aby przedstawiać unikalne aspekty skuteczności kodu.
• Wpisy: wypełniaj te ścieżki wpisami, które wyraźnie oznaczają ważne zdarzenia lub czas trwania określonej operacji.
• Dostosowywanie kolorów: używaj kodowania kolorami, aby na pierwszy rzut oka wizualnie odróżniać różne typy zdarzeń lub pomiarów.

Wybór odpowiedniego interfejsu API:

• Interfejs console.timeStamp API:

  • Wpływ instrumentacji na skuteczność jest najważniejszy, zwłaszcza w przypadku kompilacji produkcyjnych.
  • Potrzebujesz szybkiego i wydajnego sposobu oznaczania czasu trwania lub zdarzeń bez konieczności dodawania dodatkowych metadanych.
  • Dane muszą być wizualizowane tylko w panelu Skuteczność.

• Interfejs Czas działań użytkownika API (performance.mark, performance.measure):

  • Używaj, gdy musisz przechowywać dodatkowe dane z każdym wpisem i gdy używasz już interfejsu API Czasu działań użytkownika.
  • Musisz powiązać dane rozszerzone (etykietki, szczegółowe właściwości) z wpisami dotyczącymi skuteczności.
  • Chcesz dodać znaczniki wizualne, aby wyróżnić określone momenty.
  • Dane muszą być dostępne nie tylko w Narzędziach deweloperskich, ale też w wewnętrznej osi czasu przeglądarki, aby można było przeprowadzić szerszą analizę lub użyć innych narzędzi.
  • Znasz już interfejs API Czasu działań użytkownika lub go używasz.

Wstawianie danych za pomocą console.timeStamp

Interfejs console.timeStamp API został rozszerzony, aby umożliwić tworzenie niestandardowych wpisów dotyczących czasu w panelu Skuteczność przy minimalnym obciążeniu, zwłaszcza gdy Narzędzia deweloperskie nie rejestrują śladu.

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

• label:

  Etykieta wpisu dotyczącego wstępu o wyznaczonej godzinie.

• start (opcjonalnie):

  • Jeśli jest zdefiniowany jako ciąg znaków: nazwa wcześniej zarejestrowanej sygnatury czasowej (za pomocą console.timeStamp(timeStampName)).

  • Jeśli jest zdefiniowany jako liczba: sygnatura czasowa w milisekundach względem Performance.timeOrigin (np. pobrana za pomocą performance.now()), która reprezentuje czas rozpoczęcia wpisu dotyczącego czasu.

  • Jeśli nie jest zdefiniowany, jako czas rozpoczęcia używany jest bieżący czas.

• end:

  • Jeśli jest zdefiniowany jako ciąg znaków: nazwa wcześniej zarejestrowanej sygnatury czasowej.

  • Jeśli jest zdefiniowany jako liczba: sygnatura czasowa w milisekundach względem Performance.timeOrigin (np. pobrana za pomocą performance.now()), która reprezentuje czas zakończenia wpisu dotyczącego czasu.

  • Jeśli nie jest zdefiniowany, jako czas zakończenia używany jest bieżący czas.

• trackName:

  Nazwa ścieżki niestandardowej.

• trackGroup:

  Nazwa grupy ścieżek.

• color:

  Kolor wpisu.

Wstawianie danych za pomocą interfejsu Czas działań użytkownika API

Aby wstawić dane niestandardowe, dodaj obiekt devtools do właściwości detail metod performance.mark i performance.measure. Struktura tego obiektu devtools określa sposób wyświetlania danych w panelu Skuteczność.

• Użyj performance.mark, aby zarejestrować zdarzenie natychmiastowe lub sygnaturę czasową na osi czasu. Możesz oznaczyć początek lub koniec określonej operacji albo dowolny punkt zainteresowania, który nie ma czasu trwania. Gdy dodasz obiekt devtools do właściwości detail, panel Skuteczność wyświetli niestandardowy znacznik na ścieżce Czasy.

• Użyj performance.measure, aby zmierzyć czas trwania zadania lub procesu. Gdy dodasz obiekt devtools do właściwości detail, panel Skuteczność wyświetli na osi czasu wpisy dotyczące pomiarów niestandardowych w ścieżce niestandardowej. Jeśli używasz performance.mark jako punktu odniesienia do utworzenia performance.measure, nie musisz dodawać obiektu devtools do wywołań performance.mark.

Obiekt devtools

Te typy określają strukturę obiektu devtools dla różnych funkcji rozszerzenia:

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
}

Wyświetlanie danych na osi czasu

Aby zobaczyć dane niestandardowe na osi czasu, w panelu Skuteczność włącz to ustawienie: settings Ustawienia rejestrowania > check_box Pokaż ścieżki niestandardowe.

Wypróbuj na tej stronie demonstracyjnej. Rozpocznij rejestrowanie skuteczności, na stronie demonstracyjnej kliknij Dodaj nowego Corgi, a następnie zatrzymaj rejestrowanie. W śladzie zobaczysz ścieżkę niestandardową, która zawiera zdarzenia z niestandardowymi etykietkami, szczegóły na karcie Podsumowanie oraz podsumowania grup ścieżek niestandardowych w podsumowaniu śladu.

Przykłady kodu

Oto kilka przykładów użycia interfejsu API do dodawania własnych danych do panelu Skuteczność za pomocą każdego dostępnego mechanizmu.

Przykłady interfejsu console.timeStamp API:

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

Spowoduje to utworzenie w osi czasu skuteczności tego wpisu ścieżki niestandardowej:

Przykłady interfejsu Czas działań użytkownika API:

W kolejnych sekcjach znajdziesz przykłady kodu, które pokazują, jak dodać do osi czasu skuteczności:

• ścieżki i wpisy niestandardowe na osi czasu,
• znaczniki na ścieżce Czasy.

Ścieżki i wpisy niestandardowe

Twórz ścieżki niestandardowe i wypełniaj je wpisami, aby wizualizować dane o skuteczności w ścieżce niestandardowej. Na przykład:

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

Spowoduje to utworzenie w osi czasu skuteczności tego wpisu ścieżki niestandardowej wraz z tekstem etykietki i właściwościami:

Znaczniki

Wizualnie wyróżniaj określone punkty zainteresowania na osi czasu za pomocą znaczników niestandardowych, które obejmują wszystkie ścieżki. Na przykład:

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

Spowoduje to utworzenie na ścieżce Czasy tego znacznika wraz z tekstem etykietki i właściwościami: