Performance.measure() — Methode · JavaScript-Referenz

Signatur

Performance.prototype.measure(measureName, startOrMeasureOptions, endMark)

Beschreibung

performance.measure() gehört zur User Timing API. Damit messen Sie die Zeit zwischen zwei Punkten, meist zwischen zwei vorher mit performance.mark() gesetzten Marken. Das Ergebnis ist ein PerformanceMeasure-Eintrag vom Typ "measure". Er landet in der Leistungszeitleiste, ist über performance.getEntriesByName() oder einen PerformanceObserver abrufbar und erscheint in den Browser-DevTools im Performance-Panel.

Die Methode lässt sich auf mehrere Arten aufrufen:

measure(name): misst vom Zeitursprung (performance.timeOrigin) bis jetzt.
measure(name, startMark): misst von der Marke startMark bis jetzt.
measure(name, startMark, endMark): misst zwischen zwei Marken.
measure(name, { start, end, duration, detail }): Options-Objekt mit Markennamen oder Zeitstempeln (DOMHighResTimeStamp) und optionalen Zusatzdaten.

Die Methode eignet sich, um eigene Messwerte zu erfassen, etwa die Renderzeit einer Komponente, die Dauer eines API-Aufrufs oder die Zeit bis zur Interaktivität. Anders als bei einer manuellen Differenz aus performance.now() sind die Messungen für Werkzeuge sichtbar und lassen sich zentral auswerten.

Als Markennamen sind auch die Eigenschaftsnamen von PerformanceTiming erlaubt, z. B. "navigationStart" oder "domContentLoadedEventEnd". Moderne Anwendungen sollten stattdessen eigene Marken oder Zeitstempel verwenden.

Parameter

Name	Typ	Beschreibung
$measureName Pflicht	string	Name der Messung. Muss nicht eindeutig sein: Mehrere Messungen mit demselben Namen werden alle gespeichert.
$startOrMeasureOptions	string \| { start?: string \| number, end?: string \| number, duration?: number, detail?: any }	Entweder der Name der Startmarke oder ein Options-Objekt. `start`/`end` sind Markennamen oder Zeitstempel. `duration` ist eine Dauer in Millisekunden und darf nur mit genau einem der beiden Werte `start` oder `end` kombiniert werden. `detail` enthält beliebige, strukturiert klonbare Zusatzdaten. Fehlt der Parameter, gilt der Zeitursprung als Start.
$endMark	string	Name der Endmarke. Fehlt er, gilt `performance.now()` als Ende. Darf nicht zusammen mit einem Options-Objekt angegeben werden.

Rückgabewert

Typ

PerformanceMeasure

Beschreibung

Der erzeugte Eintrag mit name, entryType ("measure"), startTime, duration und detail. Ältere Browser, die nur User Timing Level 2 umsetzen, geben undefined zurück.

Beispiele

Dauer zwischen zwei Marken messen

performance.mark('daten-start');

// Aufwendige Arbeit simulieren
const summe = Array.from({ length: 1_000_000 }, (_, i) => i)
  .reduce((a, b) => a + b, 0);

performance.mark('daten-ende');

const messung = performance.measure('daten-verarbeitung', 'daten-start', 'daten-ende');
console.log(`${messung.name}: ${messung.duration.toFixed(2)} ms`);

daten-verarbeitung: 42.37 ms

API-Aufruf mit Options-Objekt und detail messen

const ladeBenutzer = async (id) => {
  const start = performance.now();
  const res = await fetch(`https://jsonplaceholder.typicode.com/users/${id}`);
  const daten = await res.json();

  performance.measure('api:benutzer', {
    start,
    end: performance.now(),
    detail: { id, status: res.status }
  });
  return daten;
};

await ladeBenutzer(1);
const [eintrag] = performance.getEntriesByName('api:benutzer');
console.log(eintrag.duration > 0, eintrag.detail);

true { id: 1, status: 200 }

Messungen zentral mit PerformanceObserver erfassen

const observer = new PerformanceObserver((liste) => {
  for (const eintrag of liste.getEntries()) {
    console.log(`[Messung] ${eintrag.name}: ${Math.round(eintrag.duration)} ms`);
  }
});
observer.observe({ type: 'measure', buffered: true });

// Zeit seit Seitenstart bis jetzt
performance.measure('bis-app-bereit');

// Feste Dauer ab einer Marke
performance.mark('animation-start');
performance.measure('animation', { start: 'animation-start', duration: 300 });

[Messung] bis-app-bereit: 1234 ms [Messung] animation: 300 ms

Aufräumen nach der Auswertung

performance.mark('a');
performance.mark('b');
performance.measure('a-bis-b', 'a', 'b');

console.log(performance.getEntriesByType('measure').length);

performance.clearMeasures('a-bis-b');
performance.clearMarks();

console.log(performance.getEntriesByType('measure').length);

1 0

// Wichtig · Fallstricke

Nicht existierende Marke: Ist eine angegebene Marke nicht vorhanden, wirft die Methode einen SyntaxError (DOMException). Tippfehler bei Markennamen fallen deshalb sofort auf.
Ungültige Kombinationen: Ein Options-Objekt zusammen mit endMark oder ein Options-Objekt mit start, end und duration führt zu einem TypeError. Ein leeres Options-Objekt {} mit nur detail ist dagegen erlaubt.
Negative Dauer: Liegt die Endmarke vor der Startmarke, entsteht eine Messung mit negativer duration. Es wird kein Fehler ausgelöst.
Speicher: Messungen sammeln sich in der Zeitleiste an. Bei häufigen Messungen, etwa in Render-Schleifen, sollten Sie regelmäßig performance.clearMeasures() und clearMarks() aufrufen.
Genauigkeit: Zum Schutz vor Timing-Angriffen (Spectre) runden Browser die Zeitstempel ab, ohne Cross-Origin-Isolation teilweise auf 100 µs bis 1 ms. Für sehr kurze Abschnitte sind die Werte deshalb ungenau.
Kompatibilität: Die Grundform mit Markennamen funktioniert in allen Browsern. Options-Objekt, detail und der Rückgabewert (Level 3) gibt es ab Chrome 78, Firefox 103 und Safari 14.1. In Node.js steht die Methode über perf_hooks bzw. das globale performance-Objekt zur Verfügung (ab Node.js 16 mit Level 3).

Siehe auch

Performance.mark() Performance.now() new ManagedMediaSource() Performance.clearMeasures() Performance.toJSON()