Puppeteer Debugging mit Cloudflare: Erst prüfen, dann neu starten

Cloudflare hat den Ablauf beim Puppeteer Debugging fehlgeschlagener Browser-Jobs am 18. September 2026 geändert. Eine abgeschlossene Browser-Run-Aufzeichnung zeigt nun Konsolenprotokolle, Netzwerkanfragen und die finale Seitenstruktur. So lässt sich das bereits bezahlte Beweismaterial auswerten, bevor ein weiterer Browser gestartet wird.

Puppeteer Debugging beginnt mit den Spuren des letzten Laufs

Bislang blieben nach einem Browser-Job dessen Ausgabe, die Fehlerbehandlung und – sofern Session Recording aktiviert war – eine Wiedergabe. Erklärte sich ein Fehler damit nicht von selbst, wurden meist zusätzliche Protokolle ergänzt und der Job erneut ausgeführt.

Das neue Inspect-Panel stellt neben einer abgeschlossenen Aufzeichnung drei Ansichten bereit:

• Logs durchsucht die erfasste Konsolenausgabe und filtert sie nach Stufe.
• Network zeigt für jede Anfrage Methode, Status, Header, Payload, Antwort und Timing. Die Aktivität lässt sich als HAR-Datei exportieren – dem Standardarchiv für die Anfragehistorie eines Browsers.
• DOM bildet die Seitenstruktur am Ende der Aufzeichnung ab und ermöglicht es, das rekonstruierte HTML zu kopieren. DOM bezeichnet den Elementbaum, den der Browser aus der Seite aufgebaut hat.

Dabei handelt es sich um Beweismaterial nach dem Lauf, nicht um eine weitere Oberfläche für Live-Debugging. Cloudflares Session Recording speichert strukturierte rrweb-Ereignisdaten statt eines Videos. Erfasst werden DOM-Änderungen, Maus- und Tastaturereignisse sowie die Navigation. Nach Ende der Sitzung ergänzt das Inspect-Panel die Wiedergabe um durchsuchbare Hinweise.

Damit unterscheidet sich das Release von Cloudflares vorheriger Änderung an Browser Run. Session-Grenzen und die schreibgeschützte Live View steuern, welche Ziele ein aktiver Job aufrufen darf und welche Eingriffe einem Kunden beim Zuschauen erlaubt sind. Inspect hilft dem eigenen Team dagegen zu verstehen, warum ein bereits abgeschlossener Job gescheitert ist.

Welche Fehler die Aufzeichnung sichtbar macht

Das Panel hilft immer dann, wenn der Fehler im Browser verwertbare Spuren hinterlassen hat.

Ein Solo-SaaS-Gründer findet die abgewiesene Anfrage

Angenommen, ein regelmäßig laufender Extraktionsjob erreicht die Seite, liefert aber keine Daten zurück. Die Network-Ansicht zeigt, ob eine API mit 401 geantwortet hat, ein Rate-Limit den Status 429 auslöste, eine Weiterleitung den Browser an ein unerwartetes Ziel schickte oder eine einzelne Abhängigkeit den größten Teil der Laufzeit beanspruchte.

Anfrage- und Antwortdetails lassen sich prüfen, bevor vorübergehendes Logging eingebaut wird. Das grenzt die erste Diagnose ein: Korrigiert werden gezielt die Zugangsdaten, die Backoff-Strategie, die Weiterleitung oder die langsame Abhängigkeit, die bereits im vorhandenen Lauf erkennbar war.

Eine Agentur trennt Seitenänderung und Skriptfehler

Ein Kunden-Workflow kann scheitern, weil sich ein Selektor geändert hat, statt der erwarteten Ansicht eine Anmeldeseite erschien oder eine Asset-Anfrage einen Fehler zurückgab. Der finale DOM und das kopierte HTML zeigen, auf welcher Seite der Browser tatsächlich gelandet ist. Die Anfragehistorie erklärt den Weg dorthin.

So erhält das Umsetzungsteam eine konkrete Übergabe. Statt der Meldung „Die Automatisierung ist kaputt“ bekommt es den finalen Elementbaum und eine HAR-Datei mit den verfügbaren Headern, Payloads, Statuswerten und Timings.

Ein Plattformtechniker verfolgt den richtigen Tab

Die Aufzeichnung ordnet ihre Ereignis-Arrays Chrome-DevTools-Protocol-Zielen wie target-1 zu; jedes Ziel steht üblicherweise für einen Browser-Tab. Bei einer Aufzeichnung mit mehreren Tabs werden diese Ziele getrennt ausgewiesen, und das Inspect-Panel im Dashboard folgt dem ausgewählten Tab.

Das ist bei Authentifizierungsübergaben und Agenten-Workflows entscheidend. Der Login-Tab kann erfolgreich sein, während der Arbeitstab scheitert. Zielspezifische Spuren verhindern, dass beide Abläufe miteinander vermischt werden.

Einen Job aufzeichnen und seine Netzwerkspur abrufen

Die Aufzeichnung ist optional. Sie muss beim ersten Start der Browser-Sitzung aktiviert werden; beim erneuten Verbinden mit einer vorhandenen Sitzung lässt sie sich nicht nachträglich einschalten.

Als kleinster sinnvoller Einstieg eignet sich eine regelmäßig laufende Browser Session, deren Fehler derzeit noch manuell nachgestellt werden.

1. 1

   Aufzeichnung beim Start aktivieren

   Cloudflares Puppeteer-Beispiel übergibt beim ersten Start recording: true. Vor dem Schließen des Browsers muss die Sitzungs-ID gespeichert werden:

   import puppeteer from "@cloudflare/puppeteer";
   
   interface Env {
   	MYBROWSER: Fetcher;
   }
   
   export default {
   	async fetch(request: Request, env: Env): Promise<Response> {
   		const browser = await puppeteer.launch(env.MYBROWSER, { recording: true });
   		const page = await browser.newPage();
   
   		await page.goto("https://example.com");
   		// ... your automation steps ...
   
   		const sessionId = browser.sessionId();
   		await browser.close();
   
   		return new Response(`Session recorded: ${sessionId}`);
   	},
   };

   Playwright verwendet dieselbe Startoption. Bei einer CDP-Verbindung steht recording=true in der WebSocket-URL.

2. 2

   Abgeschlossene Aufzeichnung anfordern

   Nach dem Schließen der Sitzung wird die Aufzeichnung über ihre Sitzungs-ID abgerufen:

   curl https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/browser-rendering/recording/<SESSION_ID> \
     -H "Authorization: Bearer <API_TOKEN>"

   Die Antwort legt die Ereignis-Arrays unter result.events ab. Deren Schlüssel, etwa target-1, sind die Ziel-IDs für die Netzwerkanfrage. Eine neue Aufzeichnung kann kurzzeitig 404 zurückgeben, während Cloudflare sie fertigstellt. In diesem Fall sollte der Abruf wiederholt werden, statt den ersten 404 als fehlenden Lauf zu werten.

3. 3

   Unverarbeitete Anfragen des Ziels abrufen

   Aus der Aufzeichnungsantwort wird ein Ziel ausgewählt. Der Parameter target ist erforderlich:

   curl 'https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/browser-rendering/recording/<SESSION_ID>/network?target=<TARGET_ID>' \
     -H "Authorization: Bearer <API_TOKEN>"

   Die Antwort enthält die erfassten Anfragen als JSON einschließlich der verfügbaren Anfrage- und Antwortdetails.

4. 4

   HAR-Datei exportieren

   Benötigt ein Entwickler die Spur in einem Browser-Netzwerkviewer oder einem anderen Analysetool, wird format=har ergänzt:

   curl 'https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/browser-rendering/recording/<SESSION_ID>/network?target=<TARGET_ID>&format=har' \
     -H "Authorization: Bearer <API_TOKEN>"

   Die Datei ist wie ein Debug-Artefakt mit eng begrenztem Zugriff zu behandeln. Laut dokumentierter Antwort kann sie verfügbare Header und Payloads enthalten und verdient deshalb dieselbe Sorgfalt wie die Jobdaten selbst.

Der naheliegende Fehler besteht darin, die Aufzeichnung erst nach dem ersten Fehlschlag einzuschalten. Rückwirkend gibt es dann keine Spuren mehr zu prüfen. Sinnvoll ist der Start mit einem wiederkehrenden Job, bei dem schon der nächste Fehler relevant wäre.

Die Browser-Kosten sind nicht der größte Posten

Cloudflares aktuelle Preise für Browser Run weisen keine separate Gebühr für die Aufzeichnung oder deren Speicherung aus. Eine aufgezeichnete Browser Session wird weiterhin nach den üblichen Browserstunden und der Parallelität abgerechnet. Session Recording befindet sich in der Betaphase; der veröffentlichte Preis beschreibt daher den heutigen Stand und ist kein dauerhaftes Versprechen.

Workers Free umfasst 10 Browser-Minuten pro Tag und drei gleichzeitig laufende Browser. Für Workers Paid gilt eine monatliche Mindestgebühr von $5 pro Konto. Enthalten sind 10 Browserstunden und 10 parallele Browser; anschließend kosten jede weitere Browserstunde $0.09 und jeder zusätzliche parallele Browser $2, berechnet nach dem Monatsdurchschnitt der täglichen Spitzenwerte.

Der direkte Preis eines einzelnen Diagnoseneustarts ist gering. Der Arbeitsaufwand rundherum ist es nicht. Das folgende Planungsmodell ist kein Cloudflare-Benchmark:

• Das Konto hat seine 10 enthaltenen Browserstunden bereits überschritten.
• Ein wiederkehrender Job dauert 10 Minuten und scheitert 12-mal im Monat.
• Das Nachstellen und Diagnostizieren jedes Fehlers beansprucht 20 Arbeitsminuten.
• Die Prüfung der vorhandenen Aufzeichnung dauert 5 Arbeitsminuten.
• Für die Arbeitszeit werden $75 pro Stunde angesetzt.
• Die Prüfung vermeidet einen Diagnoseneustart; ein späterer Lauf zur Verifizierung der Korrektur kann dennoch nötig sein.

Nur 18 Cent dieser Differenz entfallen auf die reine Browserzeit. Die übrigen $225 sind Arbeitszeit. Außerdem rundet Cloudflare die Browsernutzung auf Kontoebene, nachdem der gesamte Abrechnungszeitraum summiert wurde. Die 1.5 Cent für einen 10-minütigen Lauf sollten deshalb nicht als eigener Rechnungsposten verstanden werden.

Genau darin liegt die wirtschaftliche Folge. Mit dem Inspect-Panel wird Browser-Rechenzeit nicht plötzlich zum großen Sparhebel. Es kann aber in einem Vorfall die Schleife aus Instrumentieren, Nachstellen und Warten einmal einsparen.

Was die Aufzeichnung nicht zeigen kann

Erfasst werden der Zustand des Dokuments und seine Ereignisse, nicht jedes gerenderte Pixel.

Diese Grenzen bestimmen, welche Fehler weiterhin eine andere Diagnosemethode benötigen. Ein in Canvas gezeichnetes Diagramm, ein Checkout-Formular in einem Drittanbieter-iFrame, ein Videostatus, eine WebGL-Szene oder ein Wert in einem maskierten Feld kann falsch sein, obwohl die umgebende Aufzeichnung unauffällig wirkt.

Die DOM-Ansicht bildet außerdem nur die Struktur am Ende der Aufzeichnung ab. Sie kann erklären, auf welcher Seite der Job endete, ist aber kein pixelgenauer Screenshot jedes früheren Zustands.

Hinzu kommen betriebliche Grenzen. Aufzeichnungen bleiben 30 Tage verfügbar, dauern mindestens 1 Sekunde und höchstens 2 Stunden und funktionieren mit Browser Sessions über launch() oder CDP. Quick Actions können keine Aufzeichnungen erzeugen. Eine sehr aktive Seite kann einen großen Ereignisstrom verursachen, weil jede häufige DOM-Änderung zu Aufzeichnungsdaten wird.

Wer den Ablauf jetzt umstellen sollte

Eine Umstellung lohnt sich noch in dieser Woche, wenn regelmäßig Puppeteer-, Playwright- oder CDP-Jobs laufen und nach einem Fehler üblicherweise zuerst jemand den Ablauf nachstellt. Die Aufzeichnung sollte zunächst bei einem Job statt bei allen Jobs aktiviert werden. Anschließend lässt sich messen, ob sie die erste Diagnosefrage beantwortet.

Abwarten ist sinnvoll, wenn der entscheidende Zustand überwiegend in Canvas, WebGL, Medien, einem Cross-Origin-iFrame oder maskierten Formularfeldern steckt. Screenshots, Anwendungsprotokolle und gezielte Instrumentierung bleiben dort nötig, weil die Aufzeichnung sie nicht ersetzen kann.

Wer ausschließlich mit Quick Actions arbeitet, ist von der Änderung nicht betroffen. Nur für die Aufzeichnung auf Browser Sessions umzusteigen, verändert die Implementierung und nimmt Parallelität in das Preismodell auf. Dieser Schritt lohnt sich nur, wenn der Diagnosevorteil das rechtfertigt.

Der nächste Schritt am Montag

Ausgewählt wird eine regelmäßig laufende Browser Session, die bereits mehr als einmal gescheitert ist. Beim ersten Start kommt recording: true hinzu, die Sitzungs-ID wird neben der eigenen Job-ID gespeichert und der nächste geplante Lauf darf regulär schließen.

Danach wird die Aufzeichnung abgerufen, ihr die erste relevante Ziel-ID entnommen und die rohe Netzwerkspur oder die HAR-Datei angefordert. Gemessen wird, wie lange es dauert, die fehlerhafte Anfrage oder den finalen Seitenzustand zu benennen. Erspart dieses Material einen Diagnoseneustart, bleibt die Aufzeichnung für diesen Job aktiv und die Spur wird Teil des Vorfallprotokolls. Andernfalls wird sie wieder abgeschaltet und das fehlende Signal dort ergänzt, wo der blinde Fleck tatsächlich liegt.

Wer weitere praxisnahe Einordnungen zu Plattformänderungen erhalten möchte, kann den Newsletter abonnieren.