Was ist die Performance-Timeline-API?

Was ist die Performance-Timeline-API?

Die Performance Timeline ist das geordnete Protokoll der Performance-Einträge einer Seite im Browser: Navigation, Ressourcen, Paint, Layout-Verschiebungen, eigene Marker und mehr. Die W3C-Spezifikation legt fest, wie Einträge gespeichert, gelesen und beobachtet werden, über getEntries(), getEntriesByType(), getEntriesByName() und PerformanceObserver. Andere Timing-APIs schreiben ihre Einträge hinein.

So funktioniert es

Jedes globale Objekt, also jede Seite und jeder Worker, hält pro Eintragstyp einen Puffer. Jeder Eintrag ist ein PerformanceEntry mit name, entryType, startTime und duration. Es gibt zwei Wege zum Lesen:

• Momentaufnahme: getEntries() liefert, was jetzt in der Timeline steht, nach startTime sortiert; getEntriesByType() und getEntriesByName() filtern. Neue Einträge meldet es nie, und ein zweiter Aufruf liefert dieselben Einträge erneut. Manche Typen, etwa Layout-Verschiebung, Largest Contentful Paint, Event und Long Task, gibt es damit nie zurück.
• Observer: Ein PerformanceObserver ruft Sie auf, sobald Einträge aufgezeichnet werden. MDN nennt das den bevorzugten Weg. Mit type und buffered: true erhalten Sie auch Einträge, die vor dem Start der Beobachtung entstanden sind.

Die Timeline ist die gemeinsame Schicht. Die Web-Performance-API ist die größere Familie von Schnittstellen, die sie füllen, etwa Navigation Timing und User Timing. Für Zeiten auf der Serverseite siehe die Server-Timing-API.

Eintragstypen und Puffergrenzen

MDN nennt diese Eintragstypen: element, event, first-input, largest-contentful-paint, layout-shift, longtask, mark, measure, navigation, paint, resource und visibility-state. Die Unterstützung hängt vom Browser ab; prüfen Sie daher PerformanceObserver.supportedEntryTypes, bevor Sie beobachten. In Workern ist die Liste meist kürzer.

Die Puffer sind begrenzt. MDN nennt je globalem Objekt: 250 für resource (einstellbar), 200 für longtask, je 150 für element, event, layout-shift und largest-contentful-paint, 50 für visibility-state, 2 für paint, 1 für first-input und keine Grenze für mark, measure und navigation. Ist ein Puffer voll, werden neue Einträge nicht gespeichert und ein Zähler für verworfene Einträge steigt; ein Observer erhält ihn als droppedEntriesCount.

Beispiel

// which entry types does this browser support?
console.log(PerformanceObserver.supportedEntryTypes);

// resource entries, including those recorded before this line
const po = new PerformanceObserver((list, obs, opts) => {
  for (const e of list.getEntries()) console.log(e.entryType, e.name, e.startTime);
  if (opts && opts.droppedEntriesCount) console.warn("dropped:", opts.droppedEntriesCount);
});
po.observe({ type: "resource", buffered: true });

// snapshot of what is in the timeline right now, ordered by startTime
const marks = performance.getEntriesByType("mark");

Eine Seite mit vielen Bildern und Skripten kann mehr als 250 Resource-Einträge erzeugen. Erhöhen Sie das Limit mit performance.setResourceTimingBufferSize() oder sichern und leeren Sie die Einträge mit clearResourceTimings(), wenn das Ereignis resourcetimingbufferfull auftritt.

Häufige Fehler

• getEntries() abfragen (Polling). Sie lesen alte Einträge erneut und verpassen trotzdem Typen. Nutzen Sie einen Observer.
• Optionen mischen. entryTypes lässt sich nicht mit type oder buffered kombinieren, und buffered funktioniert nur mit type. Für mehrere gepufferte Typen legen Sie je Typ einen Observer an.
• Puffergrenzen ignorieren. Auf einer ausgelasteten Seite können späte Resource-Einträge unbemerkt fehlen.
• Einen Besuch für die Wahrheit halten. Die Timeline beschreibt einen Nutzer, ein Gerät, ein Netz. Aggregieren Sie viele Besuche.
• Annehmen, dass sie Ihr Monitoring von selbst speist. Der Browser zeichnet nur auf. Senden, Speichern und Alarmieren müssen Sie selbst lösen.

Performance Timeline, Test und Monitoring

Aus der Timeline bezieht Real User Monitoring seine Rohdaten, auch die Signale hinter den Core Web Vitals. Sie zeigt, was Besucher erlebt haben, nicht aber, was passiert, wenn niemand die Seite besucht. Das Page-Speed-Monitoring von LoadFocus ergänzt sie mit geplanten Lighthouse-Audits aus Cloud-Regionen, Verlauf und Alarmen. Eine Schritt-für-Schritt-Anleitung finden Sie in Core Web Vitals mit Alarmen und Berichten überwachen.

Häufige Fragen

Was ist der Unterschied zwischen Performance Timeline und Performance API?

Die Timeline ist das geordnete Protokoll der Einträge samt den Regeln zum Lesen und Beobachten. Die Performance API ist die breitere Menge an Schnittstellen, die Einträge erzeugen, etwa Navigation, Ressourcen und User Timing.

Sollte ich getEntries() oder PerformanceObserver verwenden?

Bevorzugen Sie PerformanceObserver. Er meldet Einträge, sobald sie entstehen, und liefert mit type und buffered auch frühere. getEntries() ist eine Momentaufnahme und kann manche Typen gar nicht zurückgeben.

Warum fehlen auf einer ausgelasteten Seite Einträge?

Die Puffer sind begrenzt, bei Resource-Einträgen zum Beispiel auf 250. Ist der Puffer voll, werden neue Einträge verworfen. Erhöhen Sie das Limit oder leeren Sie den Puffer, nachdem Sie gesichert haben, was Sie brauchen.

Funktioniert die Performance Timeline in Web Workern?

Ja. Die Schnittstellen stehen auch in Workern bereit, die Liste unterstützter Eintragstypen ist dort aber meist kürzer.