PerformanceMark — Schnittstelle · JavaScript-Referenz

Signatur

interface PerformanceMark extends PerformanceEntry

Beschreibung

PerformanceMark gehört zur User Timing API. Damit setzt du eigene, benannte Zeitmarken in die Performance-Timeline des Browsers, etwa „Daten geladen“ oder „Komponente gerendert“. Jede Marke ist ein PerformanceEntry mit entryType "mark", einem frei wählbaren name, einem hochauflösenden startTime (in Millisekunden relativ zu performance.timeOrigin) und immer duration = 0.

Marken erstellst du meist über performance.mark(name, options). Sie wird dabei in den Performance-Puffer eingetragen und ist über performance.getEntriesByType("mark") oder einen PerformanceObserver abrufbar. Seit User Timing Level 3 gibt es auch den Konstruktor new PerformanceMark(name, options). Eine so erzeugte Marke landet aber nicht automatisch in der Timeline.

Für Laufzeitmessungen kombinierst du zwei Marken mit performance.measure(). Das ergibt einen PerformanceMeasure mit echter Dauer. Über die Eigenschaft detail kannst du beliebige, strukturiert klonbare Zusatzdaten an eine Marke hängen, etwa eine Komponenten-ID oder Parameter. Die Entwicklerwerkzeuge (Performance-Panel) zeigen Marken ebenfalls an, das hilft beim Profiling.

name: Name der Marke
entryType: immer "mark"
startTime: Zeitpunkt in ms (DOMHighResTimeStamp)
duration: immer 0
detail: optionale Zusatzdaten (Standardwert null)

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name der Marke (Konstruktor bzw. `performance.mark()`). Darf nicht mit einem Attributnamen von `PerformanceTiming` übereinstimmen, z. B. `"navigationStart"`, sonst wird ein `SyntaxError` geworfen.
$options	object	{}	Optionales Objekt mit den Einstellungen für die Marke.
$options.startTime	DOMHighResTimeStamp	performance.now()	Eigener Zeitstempel für die Marke. Ein negativer Wert löst einen `TypeError` aus.
$options.detail	any	null	Beliebige Zusatzdaten. Sie werden strukturiert geklont, Funktionen oder DOM-Knoten führen also zu einem `DataCloneError`.

Rückgabewert

Typ

PerformanceMark

Beschreibung

performance.mark() und new PerformanceMark() liefern das erzeugte PerformanceMark-Objekt. Nur bei performance.mark() wird es auch in die Timeline eingetragen.

Beispiele

Marke setzen und Eigenschaften lesen

const mark = performance.mark('app-start', {
  detail: { version: '2.1.0' }
});

console.log(mark instanceof PerformanceMark);
console.log(mark.entryType, mark.name, mark.duration);
console.log(mark.detail.version);

true mark app-start 0 2.1.0

Ladezeit eines API-Aufrufs mit zwei Marken messen

const ladeBenutzer = async () => {
  performance.mark('fetch-start');
  const res = await fetch('https://jsonplaceholder.typicode.com/users');
  const daten = await res.json();
  performance.mark('fetch-end', { detail: { anzahl: daten.length } });

  const messung = performance.measure('benutzer-laden', 'fetch-start', 'fetch-end');
  console.log(`Dauer: ${messung.duration.toFixed(1)} ms`);

  // Aufräumen, damit der Puffer nicht volläuft
  performance.clearMarks('fetch-start');
  performance.clearMarks('fetch-end');
  performance.clearMeasures('benutzer-laden');
};

ladeBenutzer();

Dauer: 142.7 ms

Marken mit PerformanceObserver beobachten

const observer = new PerformanceObserver((liste) => {
  for (const eintrag of liste.getEntries()) {
    console.log(`${eintrag.name} @ ${Math.round(eintrag.startTime)} ms`, eintrag.detail);
  }
});
observer.observe({ type: 'mark', buffered: true });

performance.mark('render-done', { detail: { komponente: 'Warenkorb' } });

render-done @ 523 ms { komponente: 'Warenkorb' }

Konstruktor: Marke erzeugen, ohne sie einzutragen

const vorlage = new PerformanceMark('manuell', {
  startTime: 100,
  detail: 'nur lokal'
});

console.log(vorlage.startTime);
console.log(performance.getEntriesByName('manuell').length);

100 0

// Wichtig · Fallstricke

Konstruktor und Timeline: new PerformanceMark() trägt nichts in die Timeline ein. Wenn Observer oder DevTools die Marke sehen sollen, verwende performance.mark().
Reservierte Namen: Namen wie "navigationStart" oder "domComplete" (Attribute von PerformanceTiming) führen im Window-Kontext zu einem SyntaxError.
Doppelte Namen sind erlaubt. performance.measure() nimmt dann die jüngste Marke dieses Namens.
Speicher: Marken bleiben im Puffer, bis du sie entfernst. In langlebigen Single-Page-Anwendungen solltest du regelmäßig performance.clearMarks() aufrufen.
Genauigkeit: Browser runden startTime aus Sicherheitsgründen (Spectre) gröber, ohne Cross-Origin-Isolation auf etwa 100 µs.
Kompatibilität: detail, options und der Konstruktor gehören zu User Timing Level 3 und werden in Chrome 78+, Firefox 101+, Safari 14.1+ und Node.js 16+ unterstützt. Ältere Browser kennen nur performance.mark(name) und liefern dort undefined zurück.

Siehe auch

Performance.prototype.now() Performance PerformanceEntry PerformanceMeasure PerformanceTiming