CrashReportContext — Schnittstelle · JavaScript-Referenz

Signatur

interface CrashReportContext

Beschreibung

Das Interface CrashReportContext gehört zur Reporting API. Es ist über window.crashReport erreichbar und legt einen kleinen Datenspeicher an, der an den aktuellen Top-Level-Browsing-Kontext gebunden ist. Stürzt der Renderer-Prozess ab, zum Beispiel wegen Speichermangel (OOM) oder eines Fehlers in der Engine, kann die Seite selbst keinen Code mehr ausführen. Der Browser hängt die gespeicherten Daten dann selbst an den Crash-Report an und sendet ihn an den konfigurierten Reporting-Endpunkt.

Typische Einsatzfälle sind Diagnosedaten, die erklären sollen, was die Anwendung kurz vor dem Absturz gemacht hat. Dazu gehören etwa die aktuelle Route, der Schritt in einem Assistenten, eine Build-Version, aktive Feature-Flags oder die Größe eines gerade geladenen Datensatzes. Die Daten werden fortlaufend mit set() aktualisiert und mit delete() wieder entfernt.

Das Interface stellt folgende Methoden bereit:

initialize(length): Reserviert Speicher mit der angegebenen Größe in Bytes und gibt ein Promise zurück. Die Methode muss vor den anderen Methoden aufgerufen werden.
set(key, value): Speichert einen Zeichenketten-Wert unter einem Schlüssel oder überschreibt ihn.
delete(key): Entfernt einen Schlüssel.

Damit Reports ankommen, muss der Server einen Endpunkt über den HTTP-Header Reporting-Endpoints festlegen. Die gespeicherten Schlüssel-Wert-Paare erscheinen dann im body des Crash-Reports (Typ "crash").

Parameter

Name	Typ	Beschreibung
$length Pflicht	number	Bei `initialize(length)`: Größe des reservierten Speichers in Bytes. Der Browser legt dafür eine Obergrenze fest.
$key Pflicht	string	Bei `set()` und `delete()`: Name des Eintrags.
$value Pflicht	string	Bei `set()`: der zu speichernde Wert. Andere Typen werden in Zeichenketten umgewandelt. Objekte sollten Sie deshalb vorher mit `JSON.stringify()` umwandeln.

Rückgabewert

Typ

CrashReportContext

Beschreibung

Instanz über window.crashReport. initialize() gibt Promise<undefined> zurück, set() und delete() geben undefined zurück.

Beispiele

Initialisieren mit Feature-Erkennung

const initCrashContext = async () => {
  if (!('crashReport' in window)) {
    console.log('CrashReportContext wird nicht unterstützt');
    return false;
  }
  try {
    // 4 KiB für Diagnosedaten reservieren
    await window.crashReport.initialize(4096);
    window.crashReport.set('build', '2.14.3');
    window.crashReport.set('locale', navigator.language);
    return true;
  } catch (err) {
    console.warn('Initialisierung fehlgeschlagen:', err.name);
    return false;
  }
};

initCrashContext().then((ok) => console.log('Crash-Kontext aktiv:', ok));

Crash-Kontext aktiv: true

Aktuelle Route und Arbeitsschritt mitschreiben

const trackRoute = (path) => {
  window.crashReport?.set('route', path);
};

const startHeavyImport = async (file) => {
  window.crashReport?.set('task', JSON.stringify({ name: 'csv-import', bytes: file.size }));
  try {
    const text = await file.text();
    return text.split('\n').length;
  } finally {
    // Nach Abschluss ist der Hinweis nicht mehr relevant
    window.crashReport?.delete('task');
  }
};

window.addEventListener('popstate', () => trackRoute(location.pathname));
trackRoute(location.pathname);

Server-Seite: Endpunkt für Crash-Reports festlegen (Node.js)

import http from 'node:http';

http.createServer((req, res) => {
  if (req.method === 'POST' && req.url === '/reports') {
    let body = '';
    req.on('data', (chunk) => (body += chunk));
    req.on('end', () => {
      const reports = JSON.parse(body);
      for (const r of reports.filter((r) => r.type === 'crash')) {
        console.log('Absturz:', r.url, r.body);
      }
      res.writeHead(204).end();
    });
    return;
  }
  // Crash-Reports landen am Endpunkt "default"
  res.setHeader('Reporting-Endpoints', 'default="https://example.com/reports"');
  res.setHeader('Content-Type', 'text/html');
  res.end('<!doctype html><title>App</title>');
}).listen(8080);

Absturz: https://example.com/editor { reason: 'oom', ..., route: '/editor', build: '2.14.3' }

// Wichtig · Fallstricke

Kompatibilität: Die Schnittstelle ist experimentell und bisher nur in Chromium-basierten Browsern verfügbar, und das auch nur in einem sicheren Kontext. Prüfen Sie die Unterstützung immer mit 'crashReport' in window und nutzen Sie optionale Verkettung (?.). Firefox und Safari unterstützen die Schnittstelle nicht.
Reihenfolge: set() und delete() funktionieren erst, wenn das Promise von initialize() erfüllt ist. Werden sie vorher aufgerufen, wird ein DOMException ausgelöst (z. B. NotAllowedError). Auch wenn initialize() mehrfach aufgerufen wird oder eine zu große length angegeben ist, kann die Methode fehlschlagen.
Speichergrenze: Der reservierte Speicher ist fest begrenzt. Speichern Sie deshalb nur kurze, aussagekräftige Werte und keine vollständigen Zustandsobjekte. Überschreitet ein set()-Aufruf den Speicher, wird ein Fehler ausgelöst.
Datenschutz: Die Werte werden an Ihren Reporting-Endpunkt übertragen. Speichern Sie deshalb keine personenbezogenen Daten, Tokens oder Passwörter.
Ohne einen Endpunkt im Header Reporting-Endpoints werden die Daten nie gesendet. Die Reports werden außerdem mit Verzögerung zugestellt, oft erst beim nächsten Start des Browsers.
Die API hilft nur bei echten Abstürzen des Renderers. Normale JavaScript-Fehler fangen Sie mit window.onerror bzw. dem Event unhandledrejection ab.

Siehe auch

CrashReport AudioContext BaseAudioContext EditContext CSSImportRule