Performance.getEntriesByName() — Methode · JavaScript-Referenz

Signatur

Performance.prototype.getEntriesByName(name, type)

Beschreibung

performance.getEntriesByName() durchsucht den Performance-Puffer des aktuellen Dokuments bzw. Workers nach Einträgen mit genau dem angegebenen name. Optional lässt sich das Ergebnis über type auf einen bestimmten entryType wie "mark", "measure" oder "resource" einschränken. Die Einträge im Ergebnis-Array sind chronologisch nach startTime sortiert.

Typische Anwendungsfälle sind das Auslesen eigener Messungen, die mit performance.mark() und performance.measure() angelegt wurden. Außerdem kann man damit die Ladezeiten einer bestimmten Ressource prüfen. Bei Ressourcen-Einträgen (PerformanceResourceTiming) ist der Name die vollständige, aufgelöste URL der Ressource.

Die Methode liefert nur eine Momentaufnahme des Puffers. Wenn du fortlaufend auf neue Einträge reagieren willst, ist ein PerformanceObserver die bessere Wahl. Er erfasst außerdem Eintragstypen wie "largest-contentful-paint" oder "layout-shift", die über getEntriesByName() gar nicht verfügbar sind.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name der gesuchten Einträge, z. B. der Name einer Markierung oder Messung oder die vollständige URL einer Ressource. Der Vergleich ist exakt und unterscheidet Groß- und Kleinschreibung.
$type	string	undefined (alle Typen)	Optionaler `entryType` als Filter, z. B. `"mark"`, `"measure"`, `"resource"`, `"navigation"` oder `"paint"`.

Rückgabewert

Typ

PerformanceEntry[]

Beschreibung

Ein Array mit allen passenden PerformanceEntry-Objekten (bzw. Unterklassen wie PerformanceMark, PerformanceMeasure oder PerformanceResourceTiming), sortiert nach startTime. Gibt es keinen Treffer, ist das Array leer.

Beispiele

Eigene Messung auslesen

performance.mark('daten-start');

const daten = Array.from({ length: 100_000 }, (_, i) => i * 2);
const summe = daten.reduce((a, b) => a + b, 0);

performance.mark('daten-ende');
performance.measure('datenverarbeitung', 'daten-start', 'daten-ende');

const [messung] = performance.getEntriesByName('datenverarbeitung', 'measure');
console.log(`${messung.name}: ${messung.duration.toFixed(2)} ms`);

datenverarbeitung: 4.37 ms (Wert variiert)

Mehrere Messungen mit gleichem Namen auswerten

const ladeBenutzer = async (id) => {
  performance.mark(`start-${id}`);
  await fetch(`https://jsonplaceholder.typicode.com/users/${id}`);
  performance.measure('api-aufruf', `start-${id}`);
};

for (const id of [1, 2, 3]) {
  await ladeBenutzer(id);
}

const aufrufe = performance.getEntriesByName('api-aufruf', 'measure');
const schnitt = aufrufe.reduce((s, e) => s + e.duration, 0) / aufrufe.length;
console.log(`${aufrufe.length} Aufrufe, Ø ${schnitt.toFixed(1)} ms`);

// Aufräumen, damit der Puffer nicht wächst
performance.clearMeasures('api-aufruf');

3 Aufrufe, Ø 112.4 ms (Wert variiert)

Ladezeit einer Ressource über ihre URL prüfen

// Der Name eines Ressourcen-Eintrags ist die absolute URL
const url = new URL('/css/style.css', location.href).href;
const [eintrag] = performance.getEntriesByName(url, 'resource');

if (eintrag) {
  console.log(`Dauer: ${eintrag.duration.toFixed(1)} ms`);
  console.log(`Übertragen: ${eintrag.transferSize} Bytes`);
} else {
  console.log('Ressource nicht im Puffer gefunden');
}

Dauer: 23.8 ms Übertragen: 4812 Bytes

// Wichtig · Fallstricke

Absolute URLs: Ressourcen-Einträge werden nur mit der vollständig aufgelösten URL gefunden, also mit Protokoll, Host und Query-String. Relative Pfade wie "/app.js" liefern ein leeres Array. Verwende deshalb new URL(pfad, location.href).href.
Begrenzter Puffer: Der Puffer für Ressourcen-Einträge fasst standardmäßig nur etwa 250 Einträge. Ist er voll, werden neue Einträge verworfen. Mit performance.setResourceTimingBufferSize() lässt sich die Größe ändern, das Ereignis resourcetimingbufferfull meldet einen vollen Puffer.
Speicher: Eigene Marks und Measures bleiben erhalten, bis sie gelöscht werden. Räume sie bei häufigen Messungen mit clearMarks() bzw. clearMeasures() auf.
Nicht alle Typen verfügbar: Typen wie "largest-contentful-paint", "layout-shift" oder "longtask" erscheinen hier nicht. Sie lassen sich nur über einen PerformanceObserver erfassen.
Cross-Origin-Ressourcen: Bei fremden Ursprüngen ohne Timing-Allow-Origin-Header sind Detailwerte wie transferSize oder die DNS- und Verbindungszeiten 0.
Genauigkeit: Die Zeitwerte werden zum Schutz vor Timing-Angriffen gerundet. Die Genauigkeit hängt vom Browser und von der Cross-Origin-Isolation ab.
Kompatibilität: Die Methode wird von allen modernen Browsern und in Workern unterstützt. In Node.js steht sie über perf_hooks bzw. das globale performance zur Verfügung.

Siehe auch

Performance.getEntries() Performance.getEntriesByType() Performance.mark() Performance.measure() Performance.clearMarks() PerformanceEntry PerformanceObserver PerformanceResourceTiming