Was ist die Web Performance API?

Was ist die Web Performance API?

Die Web Performance API, meist einfach Performance API genannt, ist eine Sammlung von Browserstandards, um die Leistung einer Webseite zu messen. Sie erfasst Zeiten für Navigation, Ressourcen, Rendering und lange Tasks auf einer hochgenauen Zeitleiste, erlaubt eigene Marken und Messungen und funktioniert in Seiten und Workern. So lassen sich Messwerte echter Nutzer an die eigene Analytics senden.

So funktioniert sie

Jede Metrik ist ein PerformanceEntry mit name, startTime, duration und entryType. Die meisten Einträge zeichnet der Browser automatisch auf. Du kannst sie mit performance.getEntries() lesen, besser ist aber ein PerformanceObserver, der dich benachrichtigt, sobald neue Einträge entstehen. Dieselben Daten zeigt auch die Performance Timeline in den Entwicklertools des Browsers.

Die wichtigsten Eintragstypen

• Navigation Timing: ein Eintrag für das aktuelle Dokument mit redirectCount, domInteractive, domComplete, loadEventEnd und einem type von navigate, reload oder back_forward.
• Resource Timing: Netzwerkzeiten für jedes Bild, Skript, Stylesheet und jeden Fetch-Aufruf, einschließlich initiatorType, transferSize, responseStatus und nextHopProtocol.
• Paint, LCP und Layoutverschiebungen: Einträge für Paint Timing, Largest Contentful Paint und Layout Shifts, die Rohdaten für die Core Web Vitals.
• Event Timing und lange Tasks: Ereignislatenz (die Grundlage von Interaction to Next Paint) und Tasks, die den Hauptthread blockieren.
• Marks und Measures: eigene Markierungen und die Zeit dazwischen, etwa von "Checkout gestartet" bis "Checkout gerendert".

Beispiel

Dieses Snippet protokolliert jede Ressource beim Laden, liest den Navigationseintrag und misst einen eigenen Schritt:

const po = new PerformanceObserver((list) => {
  for (const e of list.getEntries()) console.log(e.name, e.duration);
});
po.observe({ type: "resource", buffered: true });

const [nav] = performance.getEntriesByType("navigation");
console.log(nav.type, nav.domInteractive, nav.loadEventEnd);

performance.mark("checkout-start");
// ... work ...
performance.mark("checkout-end");
performance.measure("checkout", "checkout-start", "checkout-end");

Beachte: buffered: true funktioniert mit type (ein Eintragstyp pro Aufruf), nicht mit entryTypes. Es liefert auch Einträge, die vor dem Aufruf von observe() entstanden sind.

Häufige Fehler

• Cross-Origin-Zeiten lesen und nur Nullen erhalten. Bei Ressourcen von einer anderen Origin liefern Felder wie domainLookupStart, connectStart und requestStart den Wert 0, solange der Server keinen Timing-Allow-Origin-Header sendet.
• entryTypes mit buffered mischen. Nutze type, wenn du gepufferte Einträge brauchst, mit einem Observer pro Typ.
• Zu spät beobachten. Observer, die erst nach dem Laden der Seite registriert werden, verpassen frühere Einträge, wenn du keine gepufferten anforderst.
• Einem einzelnen Besuch trauen. Die API misst einen Nutzer mit einem Gerät in einem Netz. Aggregiere viele Besuche und betrachte Perzentile statt eines einzelnen Werts.
• Einen transferSize von 0 für einen Fehler halten. Er deutet auf einen lokalen Cache-Treffer hin.

Performance API, Real User Monitoring und synthetische Tests

Die Performance API liefert die Daten für Real User Monitoring: Sie läuft im Browser deiner Besucher und zeigt, was sie tatsächlich erlebt haben. Synthetic Monitoring ist das Gegenstück: Ein Skript lädt die Seite nach Zeitplan von einem bekannten Standort, sodass Ergebnisse von Lauf zu Lauf vergleichbar bleiben. Du brauchst beides. Das Page-Speed-Monitoring von LoadFocus führt geplante Lighthouse-Audits aus Cloud-Regionen aus und speichert den Verlauf, und der kostenlose Core-Web-Vitals-Checker liefert schnell einen Wert für jede URL. Eine Schritt-für-Schritt-Anleitung findest du im Beitrag Core Web Vitals mit Alarmen und Berichten überwachen (auf Englisch). Die API steht auch in einem Web Worker bereit, sodass sich auch Arbeit außerhalb des Hauptthreads messen lässt.

Häufige Fragen

Was ist der Unterschied zwischen Performance API und Performance Timeline?

Die Performance API ist die Menge der Schnittstellen und Methoden, die du per JavaScript aufrufst. Die Performance Timeline ist die geordnete Aufzeichnung der Einträge, die der Browser führt, die die API ausliest und die Entwicklertools anzeigen.

Sollte ich getEntries() oder PerformanceObserver nutzen?

Bevorzuge PerformanceObserver. Er meldet sich, sobald Einträge entstehen, du musst also nicht abfragen, und mit der Option type und buffered auf true liefert er auch frühere Einträge.

Warum sind manche Zeitwerte bei Drittanbieter-Ressourcen 0?

Bei Cross-Origin-Ressourcen blendet der Browser detaillierte Zeiten wie DNS-Auflösung und Verbindungsaufbau aus. Der Server, der die Ressource ausliefert, muss einen Timing-Allow-Origin-Header senden, um sie freizugeben.

Ersetzt die Performance API ein Monitoring-Tool?

Nein. Sie sammelt Messwerte im Browser, aber du brauchst weiterhin einen Ort, um sie zu speichern, zu aggregieren und Alarme darauf zu setzen. Kombiniere sie mit geplanten synthetischen Checks, damit du Probleme auch bemerkst, wenn niemand die Seite besucht.