new Profiler() — Methode · JavaScript-Referenz

Signatur

new Profiler(options)

Beschreibung

Der Konstruktor Profiler() gehört zur JS Self-Profiling API. Mit ihr kann eine Webanwendung ihre eigene JavaScript-Ausführung im Browser echter Nutzer messen, statt nur lokal in den DevTools. Sobald das Objekt erzeugt ist, beginnt der Browser, in regelmäßigen Abständen den aktuellen Aufrufstapel aufzuzeichnen. Einen eigenen start()-Aufruf gibt es nicht.

Beendet wird die Aufzeichnung mit profiler.stop(). Die Methode gibt ein Promise zurück, das mit einem ProfilerTrace-Objekt erfüllt wird. Es enthält die Felder resources (Skript-URLs), frames (Funktionsname, Zeile, Spalte), stacks (verkettete Stapelrahmen) und samples (Zeitstempel mit Verweis auf einen Stapel). Diese Daten schickt man meist an einen eigenen Server und wertet sie dort aus, etwa um langsame Funktionen bei der Interaktion echter Nutzer zu finden.

Die API funktioniert nur, wenn das Dokument mit dem HTTP-Antwortkopf Document-Policy: js-profiling ausgeliefert wurde. Fehlt dieser Kopf, wirft der Konstruktor einen Fehler. Das tatsächlich genutzte Abtastintervall kann vom gewünschten abweichen. Es lässt sich über profiler.sampleInterval auslesen. Ist der Puffer voll, löst der Profiler das Ereignis samplebufferfull aus.

Parameter

Name	Typ	Beschreibung
$options Pflicht	Object	Konfigurationsobjekt (`ProfilerInitOptions`) mit den folgenden Pflichtfeldern.
$options.sampleInterval Pflicht	number	Gewünschter Abstand zwischen zwei Stichproben in Millisekunden (`DOMHighResTimeStamp`). Der Browser darf auf ein unterstütztes Intervall runden, in Chromium derzeit meist 10 ms (unter Windows 16 ms). Negative Werte führen zu einem `RangeError`.
$options.maxBufferSize Pflicht	number	Höchstzahl der Stichproben, die gespeichert werden. Wird sie erreicht, endet die Aufzeichnung und das Ereignis `samplebufferfull` wird ausgelöst.

Rückgabewert

Typ

Profiler

Beschreibung

Ein neues Profiler-Objekt (erbt von EventTarget), das sofort aufzeichnet. Es hat die Eigenschaften sampleInterval und stopped sowie die Methode stop().

Beispiele

Einen Codeabschnitt profilieren

// Voraussetzung: Server sendet 'Document-Policy: js-profiling'
const profiler = new Profiler({ sampleInterval: 10, maxBufferSize: 10_000 });

// Rechenintensive Arbeit
const fib = (n) => (n < 2 ? n : fib(n - 1) + fib(n - 2));
fib(30);

const trace = await profiler.stop();
console.log('Intervall:', profiler.sampleInterval, 'ms');
console.log('Stichproben:', trace.samples.length);
console.log('Frames:', trace.frames.map((f) => f.name));

Intervall: 10 ms Stichproben: 42 Frames: ["fib", ...]

Feature-Erkennung und Fehlerbehandlung

const startProfiler = () => {
  if (!('Profiler' in globalThis)) {
    console.warn('JS Self-Profiling wird nicht unterstützt');
    return null;
  }
  try {
    return new Profiler({ sampleInterval: 10, maxBufferSize: 5000 });
  } catch (err) {
    // z. B. NotAllowedError, wenn der Document-Policy-Header fehlt
    console.warn('Profiler nicht erlaubt:', err.name);
    return null;
  }
};

const profiler = startProfiler();

Profiler nicht erlaubt: NotAllowedError

Eine Nutzerinteraktion profilieren und Trace hochladen

const button = document.querySelector('#export');

button.addEventListener('click', async () => {
  const profiler = new Profiler({ sampleInterval: 10, maxBufferSize: 2000 });

  profiler.addEventListener('samplebufferfull', () => {
    console.warn('Puffer voll – Aufzeichnung beendet');
  });

  await exportData(); // eigene Anwendungsfunktion

  const trace = await profiler.stop();
  navigator.sendBeacon('/api/profiles', JSON.stringify(trace));
});

// Wichtig · Fallstricke

Experimentell: Die API ist nur in Chromium-Browsern (ab Version 94) verfügbar. Firefox und Safari unterstützen sie nicht. Vorher immer mit 'Profiler' in globalThis prüfen.
Document Policy nötig: Ohne den Antwortkopf Document-Policy: js-profiling wirft der Konstruktor einen DOMException vom Typ NotAllowedError.
Beide Optionen sind Pflicht. Fehlt eine, wird ein TypeError geworfen. Ein negatives sampleInterval führt zu einem RangeError.
Das gewünschte Intervall wird nicht garantiert. Den tatsächlichen Wert liefert profiler.sampleInterval.
Leistung: Das Profiling kostet selbst Rechenzeit. Deshalb besser nur bei einem kleinen Teil der Nutzer aktivieren (Sampling) und maxBufferSize knapp wählen.
Datenschutz/Sicherheit: Frames aus Cross-Origin-Skripten erscheinen nur, wenn diese per CORS geladen werden (crossorigin-Attribut plus passender Access-Control-Allow-Origin-Kopf). Traces können Funktionsnamen und URLs enthalten und sollten deshalb vertraulich behandelt werden.
Nach stop() kann ein Profiler nicht erneut gestartet werden. Für eine neue Messung ist eine neue Instanz nötig.

Siehe auch

Profiler Profiler.prototype.stop() Performance.prototype.now() PerformanceObserver new CaptureController()