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

Andrés Olivares

Sofia Emelianova

Omówienie

Panel Wydajność obsługuje interfejs API do rozszerzania skuteczności, co umożliwia dodawanie danych niestandardowych do osi czasu skuteczności. Dzięki temu możesz dodawać pomiary i zdarzenia bezpośrednio na osi czasu skuteczności jako ścieżkę niestandardową lub ścieżkę Czasy. Może to być przydatne dla deweloperów frameworków, bibliotek i kompleksowych aplikacji z niestandardowymi narzędziami pomiarowymi, którzy chcą uzyskać bardziej kompleksowe informacje o wydajności.

Ten interfejs API udostępnia 2 różne mechanizmy:

1. Interfejs User Timings API (z użyciem interfejsów performance.mark i performance.measure)

Ten interfejs API korzysta z dotychczasowego interfejsu User Timings API. Dodaje też wpisy do wewnętrznej osi czasu wydajności przeglądarki, co umożliwia dalszą analizę i integrację z innymi narzędziami do pomiaru wydajności.

2. console.timeStampAPI (rozszerzone o DevTools)

Ten interfejs API zapewnia wydajną metodę instrumentowania aplikacji i wyświetlania danych o czasie wyłącznie w panelu Skuteczność w DevTools. Jest on zaprojektowany tak, aby generował minimalne obciążenie podczas działania, co czyni go odpowiednim do instrumentowania często używanych ścieżek i kompilacji produkcyjnych. Nie dodaje wpisów do wewnętrznego harmonogramu wydajności przeglądarki.

Najważniejsze funkcje

Oba interfejsy API oferują:

• Ścieżki niestandardowe: dodawaj wpisy do niestandardowych ścieżek i grup ścieżek.
• Wpisy: wypełniają ścieżki wpisami reprezentującymi zdarzenia lub pomiary.
• Dostosowanie kolorów: wpisy z oznaczeniem kolorem w celu wizualnego rozróżnienia.

Najważniejsze różnice i sytuacje, w których należy używać poszczególnych interfejsów API:

• User Timings API (performance.mark, performance.measure):
  • Dodaje wpisy do panelu Wydajność oraz do wewnętrznej osi czasu wydajności przeglądarki.
  • Umożliwia wyświetlanie bogatych danych, w tym opisu okna zasobów i szczegółowych właściwości.
  • Umożliwia dodawanie znaczników: możesz wyróżnić konkretne momenty na osi czasu za pomocą wizualnych znaczników.
  • Nadaje się do szczegółowej analizy skuteczności i w przypadku, gdy wymagana jest integracja z innymi narzędziami do analizy skuteczności.
  • Używaj, gdy chcesz przechowywać dodatkowe dane z każdą pozycją i gdy używasz już interfejsu User Timings API.
• console.timeStamp Interfejs API:
  • Dodaje wpisy tylko do panelu Wydajność.
  • Zapewnia znacznie większą wydajność, zwłaszcza w środowiskach produkcyjnych.
  • Idealne do instrumentowania często używanych ścieżek i kodu o kluczowym znaczeniu dla wydajności.
  • Nie można dodawać dodatkowych danych, takich jak tooltipy czy właściwości.
  • Używaj tej opcji, gdy głównym problemem jest wydajność, a Ty musisz szybko zaimplementować kod.

Wstrzykiwanie danych za pomocą interfejsu API Czasy użytkownika

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

• Aby zarejestrować natychmiastowe zdarzenie lub sygnaturę czasową na osi czasu, użyj performance.mark. Możesz zaznaczyć początek lub koniec konkretnej operacji lub dowolny punkt zainteresowania, który nie ma czasu trwania. Gdy w ramach właściwości detail uwzględnisz obiekt devtools, w panelu Wydajność pojawi się znacznik niestandardowy na ścieżce Czasy.

• Użyj performance.measure, aby zmierzyć czas trwania zadania lub procesu. Gdy w ramach właściwości detail uwzględnisz obiekt devtools, w panelu Skuteczność pojawią się wpisy niestandardowych pomiarów na osi czasu w niestandardowym śladzie. Jeśli do utworzenia elementu performance.measure używasz elementu performance.mark jako punktu odniesienia, nie musisz uwzględniać obiektu devtools w wywołaniach performance.mark.

devtools obiekt

Te typy określają strukturę obiektu devtools w przypadku 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
}

Wstrzyknij dane za pomocą console.timeStamp

Interfejs API console.timeStamp został rozszerzony, aby umożliwić tworzenie niestandardowych wpisów o czasie w panelu Skuteczność z minimalnym obciążeniem.

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

• label: etykieta wpisu dotyczącego czasu.
• start: nazwa wcześniej zarejestrowanej sygnatury czasowej (za pomocą console.timeStamp(timeStampName)). Jeśli nie jest zdefiniowana, używana jest bieżąca godzina.
• end: nazwa wcześniej zarejestrowanej sygnatury czasowej. Jeśli nie jest zdefiniowany, używana jest aktualna godzina.
• trackName: nazwa ścieżki niestandardowej.
• trackGroup: nazwa grupy ścieżek.
• color: kolor wpisu.

Wyświetlanie danych na osi czasu

Aby wyświetlić dane niestandardowe na osi czasu, w panelu Wydajność włącz ustawienia Ustawienia rejestrowania > pole wyboru Dane rozszerzenia.

Wypróbuj to na stronie demonstracyjnej. Włącz Dane rozszerzenia, rozpocznij nagrywanie wydajności, na stronie demonstracyjnej kliknij Dodaj nowe Corgi, a potem zatrzymaj nagrywanie. Na karcie Podsumowanie zobaczysz ścieżkę niestandardową, która zawiera zdarzenia z niestandardowymi etykietami i szczegółami.

Przykłady kodu

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

Przykłady interfejsu User Timings API:

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

• Niestandardowe ścieżki i wpisy na osi czasu
• Oznaczenia na ścieżce Czasy

Ścieżki i wpisy niestandardowe

Tworzenie ścieżek niestandardowych i wypełnianie ich wpisami w celu wizualizacji danych o skuteczności na ścieżce niestandardowej. Na przykład:

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

W związku z tym na osi czasu skuteczności pojawi się wpis dotyczący niestandardowego śledzenia wraz z tekstem i właściwościami etykietki:

Znaczniki

Podświetlaj wizualnie konkretne punkty na osi czasu za pomocą niestandardowych znaczników, 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"
    }
  }
});

W efekcie na ścieżce Harmonogram pojawi się ten znacznik wraz z tekstem i właściwościami wtyczki:

console.timeStamp Przykłady wywołań interfejsu API:

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

W związku z tym na osi czasu skuteczności pojawi się taki wpis dotyczący ścieżki niestandardowej: