PerformanceObserverEntryList — Schnittstelle · JavaScript-Referenz

Signatur

interface PerformanceObserverEntryList

Beschreibung

PerformanceObserverEntryList ist das Objekt, das der Callback eines PerformanceObserver als ersten Parameter bekommt. Es enthält die Performance-Einträge (z. B. mark, measure, resource, paint, largest-contentful-paint, longtask), die seit dem letzten Callback-Aufruf aufgezeichnet wurden und zu den mit observe() angemeldeten Typen passen.

Einen eigenen Konstruktor gibt es nicht. Instanzen erzeugt ausschließlich der Browser bzw. die Laufzeitumgebung. Zum Auslesen gibt es drei Methoden:

getEntries() gibt alle Einträge der Liste zurück, chronologisch nach startTime sortiert.
getEntriesByType(type) gibt nur die Einträge eines bestimmten entryType zurück.
getEntriesByName(name, type?) gibt die Einträge mit einem bestimmten name zurück, auf Wunsch zusätzlich nach Typ gefiltert.

Alle drei Methoden liefern ein normales Array von PerformanceEntry-Objekten (bzw. von Unterklassen wie PerformanceResourceTiming). Anders als die globalen Methoden auf performance enthält die Liste nur den aktuellen Stapel an neuen Einträgen, nicht die gesamte Zeitleiste. Deshalb eignet sie sich für fortlaufendes Monitoring, etwa für Web Vitals oder Real User Monitoring (RUM).

Parameter

Name	Typ	Default	Beschreibung
$type	string		Bei `getEntriesByType(type)` (dort Pflicht) und `getEntriesByName(name, type)` (dort optional): der `entryType`, nach dem gefiltert wird, z. B. `"resource"`, `"mark"` oder `"measure"`.
$name	string		Nur bei `getEntriesByName(name, type?)`, dort Pflicht: der exakte `name` des Eintrags, z. B. der Name einer Markierung oder die URL einer Ressource.

Rückgabewert

Typ

PerformanceEntry[]

Beschreibung

Alle drei Methoden geben ein Array von PerformanceEntry-Objekten zurück, sortiert nach startTime. Passt kein Eintrag, ist das Array leer.

Beispiele

Eigene Messungen mit getEntries() erfassen

const observer = new PerformanceObserver((list) => {
  // list ist eine PerformanceObserverEntryList
  for (const entry of list.getEntries()) {
    console.log(`${entry.name}: ${entry.duration.toFixed(1)} ms`);
  }
});
observer.observe({ entryTypes: ['measure'] });

performance.mark('start');
for (let i = 0; i < 1e6; i++); // simulierte Arbeit
performance.mark('ende');
performance.measure('schleife', 'start', 'ende');

schleife: 3.2 ms

Langsame Ressourcen mit getEntriesByType() finden

const observer = new PerformanceObserver((list) => {
  const langsam = list
    .getEntriesByType('resource')
    .filter((e) => e.duration > 500);

  langsam.forEach((e) =>
    console.warn(`Langsam: ${e.name} (${Math.round(e.duration)} ms, ${e.initiatorType})`)
  );
});

// buffered: true liefert auch Einträge, die vor dem Aufruf entstanden sind
observer.observe({ type: 'resource', buffered: true });

Langsam: https://example.com/hero.jpg (812 ms, img)

Largest Contentful Paint mit getEntriesByName() und der Liste auswerten

new PerformanceObserver((list) => {
  const entries = list.getEntries();
  const lcp = entries.at(-1); // der jüngste Kandidat zählt
  console.log('LCP:', Math.round(lcp.startTime), 'ms', lcp.element);
}).observe({ type: 'largest-contentful-paint', buffered: true });

// Gezielt nach dem Namen einer Markierung filtern
new PerformanceObserver((list) => {
  const [ready] = list.getEntriesByName('app-bereit', 'mark');
  if (ready) console.log('App bereit nach', Math.round(ready.startTime), 'ms');
}).observe({ type: 'mark', buffered: true });

performance.mark('app-bereit');

App bereit nach 431 ms LCP: 1180 ms <img class="hero">

// Wichtig · Fallstricke

Kein Konstruktor: new PerformanceObserverEntryList() wirft einen TypeError. Instanzen gibt es nur im Callback eines PerformanceObserver.
Nur der aktuelle Stapel: Die Liste enthält ausschließlich die seit dem letzten Callback neu hinzugekommenen Einträge. Wer die gesamte Historie braucht, nimmt performance.getEntries() oder buffered: true in observe().
buffered nur mit type: buffered: true wirkt nur zusammen mit der Option type, nicht mit entryTypes.
Browser-Unterstützung: Das Interface selbst wird überall unterstützt. Welche Typen es gibt (longtask, largest-contentful-paint, layout-shift, event), ist aber je nach Browser verschieden. Safari und Firefox kennen einige davon nicht. Prüfe das vorher mit PerformanceObserver.supportedEntryTypes.
Datenschutz und CORS: Bei Ressourcen von fremden Origins sind die detaillierten Zeitwerte (z. B. domainLookupStart, transferSize) 0, solange der Server keinen Header Timing-Allow-Origin sendet.
Performance: Im Callback keine aufwendige Verarbeitung ausführen. Daten lieber sammeln und gebündelt senden, z. B. per navigator.sendBeacon() bei visibilitychange.

Siehe auch

Performance.mark() Performance.measure() PerformanceObserver PerformanceServerTiming PerformanceElementTiming