Passen Sie Ihre Leistungsdaten mit der Extensible API an.

Andrés Olivares

Sofia Emelianova

Übersicht

Möchten Sie detailliertere Einblicke in die Leistung Ihrer Anwendung erhalten, die über die integrierten Messwerte des Browsers hinausgehen? Mit dem Bereich Leistung können Sie jetzt Ihre eigenen Leistungsdaten direkt in die Zeitachse einfügen. Ob Sie als Framework-Autor interne Prozesse visualisieren, als Bibliotheksentwickler die Auswirkungen Ihres Codes verfolgen oder eine komplexe Anwendung mit benutzerdefinierter Instrumentierung erstellen möchten – die Performance Extensibility API bietet die Tools, mit denen Sie ein umfassendes Verständnis dafür erhalten, was im Hintergrund passiert.

Durch das Einfügen benutzerdefinierter Messungen und Ereignisse können Sie im bekannten Bereich Leistung maßgeschneiderte Visualisierungen erstellen. Stellen Sie sich vor, Sie sehen die Lifecycle-Events der Komponenten Ihres Frameworks neben den Standard-Leistungsmesswerten zur Browserleistung oder verfolgen den Ausführungsablauf Ihrer benutzerdefinierten Rendering-Engine in perfekter Synchronisierung mit der Rendering-Pipeline des Browsers.

Diese API bietet zwei Ansätze, um dies zu erreichen:

1. Die console.timeStamp API (erweitert für die Entwicklertools)

Diese API bietet eine leistungsstarke Methode zum Instrumentieren von Anwendungen und zum Bereitstellen von Zeitmessungsdaten ausschließlich für den Bereich Leistung in den Entwicklertools. Sie ist für einen minimalen Laufzeit-Overhead konzipiert und eignet sich daher für die Instrumentierung von Hot Paths und Produktions-Builds. Es werden keine Einträge zur internen Leistungszeitachse des Browsers hinzugefügt.

2. Die Nutzertiming API (mit performance.mark und performance.measure)

Diese API nutzt die vorhandene User Timings API. Außerdem werden Einträge zur internen Leistungszeitachse des Browsers hinzugefügt, die eine weitere Analyse und Integration mit anderen Leistungstools ermöglichen.

Hauptvorteile

Beide APIs bieten folgende Vorteile:

• Benutzerdefinierte Tracks:Fügen Sie spezielle Tracks und Trackgruppen hinzu, um die einzigartigen Leistungsaspekte Ihres Codes darzustellen.
• Einträge:Füllen Sie diese Tracks mit Einträgen, die wichtige Ereignisse oder die Dauer bestimmter Vorgänge deutlich kennzeichnen.
• Farbliche Anpassung:Verwenden Sie Farben, um verschiedene Arten von Ereignissen oder Messungen auf einen Blick visuell zu unterscheiden.

Die richtige API für Ihre Anforderungen auswählen :

• console.timeStamp API :

  • Die Auswirkungen der Instrumentierung auf die Leistung sind ein Hauptanliegen, insbesondere bei Produktions-Builds.
  • Sie benötigen eine schnelle und effiziente Möglichkeit, Dauern oder Ereignisse zu markieren, ohne dass zusätzliche Metadaten erforderlich sind.
  • Die Daten müssen nur im Bereich „Leistung“ visualisiert werden.

• Nutzertiming-API (performance.mark, performance.measure) :

  • Verwenden Sie diese API, wenn Sie zusätzliche Daten mit jedem Eintrag speichern müssen und die Nutzertiming API bereits verwenden.
  • Sie müssen umfangreiche Daten (Tooltips, detaillierte Eigenschaften) mit Ihren Leistungseinträgen verknüpfen.
  • Sie möchten visuelle Markierungen hinzufügen, um bestimmte Momente hervorzuheben.
  • Die Daten müssen nicht nur in den Entwicklertools, sondern auch in der internen Leistungszeitachse des Browsers für eine umfassendere Analyse oder andere Tools verfügbar sein.
  • Sie sind bereits mit der Nutzertiming API vertraut oder verwenden sie.

Daten mit console.timeStamp einfügen

Die console.timeStamp API wurde erweitert, um die Erstellung benutzerdefinierter Zeitmessungseinträge im Bereich Leistung mit minimalem Overhead zu ermöglichen, insbesondere wenn die Entwicklertools keine Aufzeichnung durchführen.

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

• label:

  Die Bezeichnung für den Zeitmessungseintrag.

• start (optional):

  • Als String definiert: der Name eines zuvor aufgezeichneten Zeitstempels (mit console.timeStamp(timeStampName)).

  • Als Zahl definiert: ein Zeitstempel in Millisekunden relativ zu Performance.timeOrigin (z. B. mit performance.now() erfasst), der die Startzeit des Zeitmessungseintrags darstellt.

  • Wenn nicht definiert, wird die aktuelle Zeit als Startzeit verwendet.

• end:

  • Als String definiert: der Name eines zuvor aufgezeichneten Zeitstempels.

  • Als Zahl definiert: ein Zeitstempel in Millisekunden relativ zu Performance.timeOrigin (z. B. mit performance.now() erfasst), der die Endzeit des Zeitmessungseintrags darstellt.

  • Wenn nicht definiert, wird die aktuelle Zeit als Endzeit verwendet.

• trackName:

  Der Name des benutzerdefinierten Tracks.

• trackGroup:

  Der Name der Trackgruppe.

• color:

  Die Farbe des Eintrags.

Daten mit der Nutzertiming API einfügen

Wenn Sie benutzerdefinierte Daten einfügen möchten, fügen Sie ein devtools Objekt in die detail Eigenschaft der performance.mark und performance.measure Methoden ein. Die Struktur dieses devtools-Objekts bestimmt, wie Ihre Daten im Bereich Leistung angezeigt werden.

• Verwenden Sie performance.mark, um ein sofortiges Ereignis oder einen Zeitstempel in der Zeitachse aufzuzeichnen. Sie können den Beginn oder das Ende eines bestimmten Vorgangs oder einen beliebigen Punkt markieren, der keine Dauer hat. Wenn Sie ein devtools-Objekt in die detail-Eigenschaft einfügen, wird im Bereich Leistung eine benutzerdefinierte Markierung im Track Timings angezeigt.

• Verwenden Sie performance.measure, um die Dauer einer Aufgabe oder eines Prozesses zu messen. Wenn Sie ein devtools-Objekt in die detail-Eigenschaft einfügen, werden im Bereich Leistung benutzerdefinierte Messungseinträge in der Zeitachse in einem benutzerdefinierten Track angezeigt. Wenn Sie performance.mark als Referenzpunkt verwenden, um eine performance.measure zu erstellen, müssen Sie das devtools-Objekt nicht in performance.mark-Aufrufe einfügen.

devtools-Objekt

Diese Typen definieren die Struktur des devtools-Objekts für verschiedene Erweiterungsfunktionen:

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
}

Daten in der Zeitachse ansehen

Wenn Sie Ihre benutzerdefinierten Daten in der Zeitachse sehen möchten, muss im Bereich Leistung die folgende Einstellung aktiviert sein: settings Aufzeichnungseinstellungen > check_box Benutzerdefinierte Tracks anzeigen.

Probieren Sie es auf dieser Demoseite aus. Starten Sie eine Leistungsaufzeichnung, klicken Sie auf der Demoseite auf Neuen Corgi hinzufügen und beenden Sie dann die Aufzeichnung. In der Aufzeichnung sehen Sie einen benutzerdefinierten Track mit Ereignissen mit benutzerdefinierten Tooltips, Details auf dem Tab Zusammenfassung und benutzerdefinierten Zusammenfassungen der Trackgruppen in der Aufzeichnungszusammenfassung.

Codebeispiele

Hier sind einige Beispiele für die Verwendung der API, um dem Bereich Leistung mit den verfügbaren Mechanismen eigene Daten hinzuzufügen.

console.timeStamp API-Beispiele:

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

Dadurch wird der folgende benutzerdefinierte Trackeintrag in der Leistungszeitachse erstellt:

Nutzertiming API-Beispiele:

In den nächsten Abschnitten finden Sie Codebeispiele, die zeigen, wie Sie der Leistungszeitachse Folgendes hinzufügen:

• Benutzerdefinierte Tracks und Einträge
• Markierungen zum Track „Timings“

Benutzerdefinierte Tracks und Einträge

Erstellen Sie benutzerdefinierte Tracks und füllen Sie sie mit Einträgen, um Ihre Leistungsdaten in einem benutzerdefinierten Track zu visualisieren. Beispiel:

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

Dadurch wird der folgende benutzerdefinierte Trackeintrag in der Leistungszeitachse erstellt, zusammen mit dem Kurzinfo-Text und den Eigenschaften:

Markierungen

Heben Sie bestimmte Punkte in der Zeitachse mit benutzerdefinierten Markierungen hervor, die sich über alle Tracks erstrecken. Beispiel:

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

Dadurch wird die folgende Markierung im Track Timings erstellt, zusammen mit dem Tooltip-Text und den Eigenschaften: