Profiler: samplebufferfull — Ereignis · JavaScript-Referenz

Signatur

profiler.addEventListener("samplebufferfull", handler)

Beschreibung

Das Ereignis samplebufferfull gehört zur JS Self-Profiling API. Ein Profiler nimmt in regelmäßigen Abständen (sampleInterval) Stichproben des JavaScript-Aufrufstapels und legt sie in einem Puffer ab. Die Größe dieses Puffers legt man beim Anlegen mit new Profiler({ sampleInterval, maxBufferSize }) fest. Wenn der Puffer voll ist, löst der Profiler samplebufferfull aus und nimmt ab dann keine weiteren Stichproben mehr auf.

Mit dem Ereignis erfährt man also, dass die Aufzeichnung abgeschnitten wurde. Normalerweise ruft man im Handler profiler.stop() auf, holt den bis dahin gesammelten ProfilerTrace ab und schickt ihn z. B. an einen Analyse-Endpunkt. Bei Bedarf startet man danach einen neuen Profiler, damit die Messung weiterläuft.

Einen Handler kann man auf zwei Wegen registrieren: mit profiler.addEventListener("samplebufferfull", handler) oder über die Eigenschaft profiler.onsamplebufferfull = handler. Das Ereignisobjekt ist ein einfaches Event ohne zusätzliche Eigenschaften. Es blubbert nicht auf und lässt sich nicht abbrechen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, immer `"samplebufferfull"`.
$handler Pflicht	(event: Event) => void		Callback, der aufgerufen wird, sobald der Stichprobenpuffer voll ist. Er bekommt ein einfaches `Event`, dessen `target` der betroffene `Profiler` ist.
$options	boolean \| AddEventListenerOptions	false	Die üblichen Optionen von `addEventListener`, z. B. `{ once: true }` oder `{ signal }`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Den Trace erhält man über profiler.stop(), das ein Promise<ProfilerTrace> zurückgibt.

Beispiele

Volle Puffer erkennen und den Trace sichern

// Voraussetzung: HTTP-Header "Document-Policy: js-profiling"
const profiler = new Profiler({ sampleInterval: 10, maxBufferSize: 1000 });

profiler.addEventListener("samplebufferfull", async () => {
  console.warn("Puffer voll – Aufzeichnung wird beendet");
  const trace = await profiler.stop();
  console.log(`Stichproben: ${trace.samples.length}`);
  navigator.sendBeacon("/api/profile", JSON.stringify(trace));
}, { once: true });

Puffer voll – Aufzeichnung wird beendet Stichproben: 1000

Handler über die Eigenschaft onsamplebufferfull

const profiler = new Profiler({ sampleInterval: 10, maxBufferSize: 500 });

profiler.onsamplebufferfull = async (event) => {
  console.log(event.type, event.target === profiler);
  const { samples, frames } = await profiler.stop();
  console.log(`${samples.length} Stichproben, ${frames.length} Frames`);
};

// Handler wieder entfernen
// profiler.onsamplebufferfull = null;

samplebufferfull true 500 Stichproben, 42 Frames

Fortlaufend messen: bei vollem Puffer neuen Profiler starten

const traces = [];

const startProfiling = () => {
  const profiler = new Profiler({ sampleInterval: 10, maxBufferSize: 2000 });

  const onFull = async () => {
    profiler.removeEventListener("samplebufferfull", onFull);
    traces.push(await profiler.stop());
    console.log(`Trace-Block ${traces.length} gespeichert`);
    if (traces.length < 3) startProfiling(); // höchstens 3 Blöcke
  };

  profiler.addEventListener("samplebufferfull", onFull);
};

if ("Profiler" in window) {
  startProfiling();
} else {
  console.info("JS Self-Profiling API wird nicht unterstützt");
}

Trace-Block 1 gespeichert Trace-Block 2 gespeichert Trace-Block 3 gespeichert

// Wichtig · Fallstricke

Nur experimentell und nur in Chromium verfügbar (ab Chrome 94). Vor der Nutzung mit "Profiler" in window prüfen.
Ohne den Antwort-Header Document-Policy: js-profiling wirft new Profiler() einen NotAllowedError. In diesem Fall wird das Ereignis nie ausgelöst.
Ist der Puffer voll, endet die Aufzeichnung, aber der Profiler ist damit nicht automatisch beendet. Den Trace bekommt man erst durch profiler.stop(). Ein zweiter Aufruf von stop() führt zu einem abgelehnten Promise.
Das tatsächliche sampleInterval kann größer sein als verlangt, weil der Browser rundet (in Chrome meist auf 10 ms, unter Windows teils 16 ms). Wann der Puffer voll ist, lässt sich deshalb nur ungefähr voraussagen.
Profiling kostet Rechenzeit. Deshalb in Produktion nur für einen Teil der Sitzungen aktivieren und den Puffer klein halten.
In Trace-Daten können Skript-URLs und Funktionsnamen stecken. Ressourcen aus anderen Ursprüngen erscheinen nur, wenn sie per CORS freigegeben sind.

Siehe auch

Profiler Profiler.prototype.stop() Performance.prototype.now() IDBRequest: error MediaSource: sourceopen