PerformanceMeasure — Schnittstelle · JavaScript-Referenz

Signatur

interface PerformanceMeasure extends PerformanceEntry

Beschreibung

PerformanceMeasure gehört zur User Timing API und steht für eine benannte Zeitspanne auf der Performance-Zeitleiste des Browsers. Solche Einträge entstehen fast immer durch performance.measure(). Die Methode berechnet die Dauer zwischen zwei Markierungen (PerformanceMark), zwischen festen Zeitstempeln oder zwischen dem Start der Navigation und dem aktuellen Zeitpunkt.

Die Schnittstelle erbt von PerformanceEntry alle wichtigen Eigenschaften: name (der vergebene Name), entryType (immer "measure"), startTime (Startzeitpunkt in Millisekunden relativ zu performance.timeOrigin) und duration (Dauer in Millisekunden). Neu hinzu kommt nur detail: Darin stehen beliebige Metadaten, die du beim Anlegen mitgegeben hast.

Typische Einsatzfälle sind Messungen eigener Abläufe, etwa wie lange eine API-Anfrage dauert, bis eine Komponente gerendert ist oder wie viel Zeit eine rechenintensive Funktion braucht. Die Messwerte erscheinen in den Entwicklerwerkzeugen im Performance-Panel. Du kannst sie mit performance.getEntriesByType("measure") abfragen oder mit einem PerformanceObserver laufend beobachten, zum Beispiel um sie an ein Monitoring-System zu senden.

Einen eigenen Konstruktor hat die Schnittstelle nicht. new PerformanceMeasure() wirft einen TypeError. Instanzen bekommst du ausschließlich über performance.measure().

Parameter

Name	Typ	Default	Beschreibung
$detail	any	null	Eigenschaft (schreibgeschützt): Metadaten, die beim Aufruf von `performance.measure(name, { detail })` übergeben wurden. Der Wert wird per structured clone kopiert.
$name Pflicht	string		Geerbte Eigenschaft: Name der Messung, also das erste Argument von `performance.measure()`.
$entryType Pflicht	string	"measure"	Geerbte Eigenschaft: bei dieser Schnittstelle immer `"measure"`.
$startTime Pflicht	DOMHighResTimeStamp		Geerbte Eigenschaft: Startzeitpunkt der Messung in Millisekunden.
$duration Pflicht	DOMHighResTimeStamp		Geerbte Eigenschaft: gemessene Dauer in Millisekunden.

Rückgabewert

Typ

PerformanceMeasure

Beschreibung

Wird von performance.measure() zurückgegeben (seit User Timing Level 3; ältere Browser liefern undefined) und über getEntriesByType("measure") oder einen PerformanceObserver bereitgestellt.

Beispiele

Messung zwischen zwei Markierungen erzeugen

performance.mark('daten-start');

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 instanceof PerformanceMeasure);
console.log(messung.entryType, messung.name);
console.log(`Dauer: ${messung.duration.toFixed(2)} ms`);

true measure daten-verarbeitung Dauer: 42.17 ms

API-Anfrage mit Metadaten in 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();

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

  console.log(messung.detail, `${Math.round(messung.duration)} ms`);
  return daten;
};

await ladeBenutzer(1);

{ id: 1, status: 200 } 135 ms

Messungen mit PerformanceObserver sammeln und melden

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

performance.mark('render-start');
setTimeout(() => {
  performance.measure('render', 'render-start');
}, 100);

[Messung] render: 100.4 ms

Alle Messungen auslesen und aufräumen

performance.measure('seit-navigation'); // von timeOrigin bis jetzt

const messungen = performance.getEntriesByType('measure');
console.table(messungen.map(({ name, startTime, duration }) => ({ name, startTime, duration })));

// Puffer leeren, damit er nicht voll läuft
performance.clearMeasures();
console.log(performance.getEntriesByType('measure').length);

(Tabelle mit name, startTime, duration) 0

// Wichtig · Fallstricke

Kein Konstruktor: new PerformanceMeasure() wirft einen TypeError. Lege Messungen immer mit performance.measure() an.
Rückgabewert in alten Browsern: Vor User Timing Level 3 gab performance.measure() undefined zurück. Auch das Optionsobjekt (start, end, duration, detail) fehlte dort. Für ältere Umgebungen liest du den Eintrag besser mit getEntriesByName() aus.
Fehlende Markierung: Gibt es einen angegebenen Markierungsnamen nicht, wirft der Aufruf eine SyntaxError-DOMException.
Speicher: Messungen bleiben im Performance-Puffer, bis du sie löschst. Bei häufigen Messungen, etwa in Schleifen oder Single-Page-Apps, solltest du regelmäßig performance.clearMeasures() und clearMarks() aufrufen.
Genauigkeit: Browser vergröbern Zeitstempel zum Schutz vor Timing-Angriffen wie Spectre. Ohne Cross-Origin-Isolation sind sie oft nur auf 0,1 ms oder 1 ms genau, in Firefox teils noch gröber.
detail: Der Wert wird per structured clone kopiert. Funktionen und DOM-Knoten lassen sich nicht übergeben und lösen eine DataCloneError aus.
In Node.js stehen die Schnittstelle und performance global zur Verfügung, außerdem über perf_hooks.

Siehe auch

Performance.measure() Performance.now() PerformanceMark PerformanceEntry PerformanceObserver