new PerformanceMark() — Methode · JavaScript-Referenz

Signatur

new PerformanceMark(name, markOptions)

Beschreibung

Der Konstruktor PerformanceMark() erzeugt einen benannten Zeitstempel vom Typ PerformanceMark (entryType ist "mark", duration ist immer 0). Den Zeitpunkt können Sie über startTime selbst festlegen, beliebige Zusatzdaten übergeben Sie über detail.

Der wichtigste Unterschied zu performance.mark(): Ein mit new PerformanceMark() erzeugtes Objekt wird nicht in die Performance-Zeitleiste eingetragen. Es taucht also weder in performance.getEntriesByType("mark") noch bei einem PerformanceObserver auf. Wenn die Markierung global sichtbar sein soll, etwa für DevTools, performance.measure() mit Mark-Namen oder RUM-Werkzeuge (Real User Monitoring), verwenden Sie performance.mark(). Diese Methode nimmt dieselben Argumente entgegen und gibt ebenfalls einen PerformanceMark zurück.

Der Konstruktor ist nützlich, wenn Sie Messpunkte nur lokal brauchen: zum Beispiel für eine eigene Messlogik, für Tests oder um Einträge zu sammeln und später gebündelt an einen Analyse-Server zu schicken. Er ist in Fenstern, in Web Workern und in Node.js (als globales PerformanceMark bzw. über perf_hooks) verfügbar.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name der Markierung. Wird in `entry.name` gespeichert. Im Fenster-Kontext darf er nicht einem veralteten `PerformanceTiming`-Attribut entsprechen (z. B. `"navigationStart"`).
$markOptions	object	{}	Optionales Objekt mit Zusatzoptionen.
$markOptions.detail	any	null	Beliebige Zusatzdaten (Metadaten). Werden per structured clone kopiert und stehen danach in `entry.detail`.
$markOptions.startTime	DOMHighResTimeStamp (number)	performance.now()	Eigener Zeitstempel in Millisekunden relativ zu `performance.timeOrigin`. Darf nicht negativ sein.

Beispiele

Einfache Markierung erzeugen

const mark = new PerformanceMark("app-start");

console.log(mark.name);        // "app-start"
console.log(mark.entryType);   // "mark"
console.log(mark.duration);    // 0
console.log(typeof mark.startTime); // "number"

app-start mark 0 number

Eigener Zeitstempel und Zusatzdaten

const clickTime = performance.now();

const mark = new PerformanceMark("checkout-click", {
  startTime: clickTime,
  detail: { userId: 42, cartSize: 3 }
});

console.log(mark.startTime === clickTime); // true
console.log(mark.detail);                  // { userId: 42, cartSize: 3 }

true { userId: 42, cartSize: 3 }

Unterschied zu performance.mark(): kein Eintrag in der Zeitleiste

new PerformanceMark("lokal");
performance.mark("global");

const names = performance.getEntriesByType("mark").map((e) => e.name);
console.log(names.includes("lokal"));  // false
console.log(names.includes("global")); // true

false true

Lokale Messpunkte sammeln und gebündelt senden

const marks = [];

const track = (name, detail = null) => {
  marks.push(new PerformanceMark(name, { detail }));
};

const loadData = async () => {
  track("fetch-start");
  const res = await fetch("/api/items");
  const items = await res.json();
  track("fetch-end", { count: items.length });
  return items;
};

loadData().then(() => {
  const [start, end] = marks;
  console.log(`Ladezeit: ${(end.startTime - start.startTime).toFixed(1)} ms`);
  navigator.sendBeacon("/metrics", JSON.stringify(marks.map((m) => m.toJSON())));
});

Ladezeit: 123.4 ms

// Wichtig · Fallstricke

Nicht in der Zeitleiste: Die Markierung wird nicht gepuffert. performance.measure("x", "meinMark") findet sie deshalb nicht über ihren Namen. Übergeben Sie stattdessen { start: mark.startTime } oder verwenden Sie performance.mark().
TypeError, wenn startTime negativ ist oder kein Name übergeben wurde.
SyntaxError im Fenster-Kontext, wenn name einem Attribut von PerformanceTiming entspricht (z. B. "navigationStart" oder "loadEventEnd"). In Workern gilt diese Einschränkung nicht.
detail wird per structured clone kopiert. Funktionen oder DOM-Knoten lösen einen DataCloneError aus. Spätere Änderungen am Originalobjekt wirken sich nicht auf die Kopie aus.
Kompatibilität: Den Konstruktor und die Optionen detail/startTime gibt es erst seit User Timing Level 3, in Firefox erst ab Version 101. Für ältere Umgebungen prüfen Sie mit typeof PerformanceMark === "function" und weichen notfalls auf performance.mark() aus.
Die Zeitstempel können aus Datenschutzgründen (Schutz vor Timing-Angriffen) gerundet sein. Ohne Cross-Origin-Isolation ist die Auflösung deshalb geringer.

Siehe auch

Performance.prototype.mark() Performance.prototype.measure() Performance.prototype.now() new PerformanceObserver() new PeriodicWave()