Automação de navegador: como investigar falhas no Cloudflare Browser Run

Em 18 de setembro de 2026, a Cloudflare mudou o fluxo de investigação de falhas na automação de navegador. Agora, a gravação concluída de uma execução no Browser Run reúne logs do console, requisições de rede e a estrutura final da página. Assim, você examina as evidências que já pagou para produzir antes de iniciar outro navegador.

A automação de navegador agora gera um pacote de evidências

Antes, uma execução no navegador deixava a saída, o tratamento de erros e um replay — caso o Session Recording estivesse ativado. Quando a própria falha não explicava a causa, o caminho habitual era adicionar mais logs e executar a tarefa novamente.

O novo painel Inspect coloca três visualizações ao lado de uma gravação concluída:

• Logs permite pesquisar a saída capturada do console e filtrá-la por nível.
• Network mostra método, status, headers, payload, resposta e duração de cada requisição. Também permite exportar a atividade como arquivo HAR, o formato padrão para arquivar o histórico de requisições de um navegador.
• DOM exibe a estrutura da página no fim da gravação e permite copiar o HTML reconstruído. DOM é a árvore de elementos que o navegador montou a partir da página.

Essas são evidências pós-execução, não mais uma ferramenta de depuração em tempo real. O Session Recording da Cloudflare armazena dados estruturados de eventos do rrweb, e não um vídeo. Ele registra mudanças no DOM, eventos de mouse e teclado e a navegação. Depois que a sessão termina, o painel Inspect acrescenta pistas pesquisáveis ao replay.

É isso que diferencia este lançamento da mudança anterior no Browser Run. As proteções de sessão e o Live View somente leitura controlam aonde uma tarefa ativa pode ir e o que um cliente pode fazer enquanto a acompanha. Já o Inspect ajuda sua própria equipe a entender por que uma tarefa concluída falhou.

Que tipos de falha esse registro consegue revelar

O painel é útil quando a falha deixa rastros no navegador.

Quem toca um SaaS sozinho consegue localizar a requisição rejeitada

Imagine que uma tarefa recorrente de extração chegue à página, mas não retorne nenhum dado. A visualização Network pode revelar se uma API respondeu com 401, se um limite de requisições devolveu 429, se um redirecionamento levou o navegador a um destino inesperado ou se uma dependência consumiu a maior parte da execução.

Antes de adicionar logs temporários, você consegue examinar os detalhes da requisição e da resposta. O primeiro diagnóstico fica mais preciso: corrija a credencial, o backoff, o redirecionamento ou a dependência lenta que a execução existente já expôs.

Quem lidera uma agência separa uma mudança na página de um bug no script

O fluxo de um cliente pode falhar porque um seletor mudou, uma página de login substituiu a tela esperada ou a requisição de um recurso retornou erro. O DOM final e o HTML copiado mostram onde o navegador realmente terminou. O histórico de requisições mostra como ele chegou até ali.

Isso dá à equipe de implementação um material concreto para o repasse. Em vez de receber apenas “a automação quebrou”, ela recebe a árvore final de elementos e um HAR com os headers, payloads, status e tempos disponíveis.

A equipe de engenharia de plataforma acompanha a aba certa

A gravação organiza seus arrays de eventos por targets do Chrome DevTools Protocol, como target-1; em geral, cada target representa uma aba do navegador. Em uma gravação com várias abas, esses targets aparecem separadamente, e o painel Inspect do dashboard acompanha a aba selecionada.

Isso faz diferença nos fluxos de autenticação e de agentes. A aba de login pode funcionar enquanto a aba de trabalho falha. Evidências separadas por target impedem que essas duas histórias se misturem.

Grave uma execução e recupere seu tráfego de rede

A gravação é opcional. Você precisa ativá-la quando a sessão do navegador é aberta pela primeira vez; não é possível ligá-la depois, ao se reconectar a uma sessão existente.

O menor ponto de partida útil é uma única Browser Session recorrente cujas falhas hoje exigem reprodução manual.

1. 1

   Ative a gravação na inicialização

   No exemplo com Puppeteer da Cloudflare, a chamada inicial passa recording: true. Guarde o ID da sessão antes de fechar o navegador:

   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}`);
   	},
   };

   O Playwright usa a mesma opção de inicialização. Em uma conexão CDP, use recording=true na URL do WebSocket.

2. 2

   Solicite a gravação concluída

   Depois que a sessão terminar, solicite a gravação com o ID da sessão:

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

   A resposta coloca os arrays de eventos em result.events. As chaves, como target-1, são os IDs de target necessários para a requisição de rede. Uma gravação nova pode retornar 404 por alguns instantes enquanto a Cloudflare termina de processá-la; nesse caso, repita a consulta em vez de tratar o primeiro 404 como sinal de uma execução inexistente.

3. 3

   Recupere as requisições brutas do target

   Escolha um target retornado pela resposta da gravação. O parâmetro target é obrigatório:

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

   O retorno traz as requisições capturadas em JSON, incluindo os detalhes disponíveis de cada requisição e resposta.

4. 4

   Exporte o HAR

   Adicione format=har quando alguém da equipe de desenvolvimento precisar abrir o histórico em um visualizador de rede do navegador ou em outra ferramenta de análise:

   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>"

   Trate esse arquivo como um artefato de depuração com acesso restrito e temporário. A resposta documentada pode conter headers e payloads disponíveis, por isso merece o mesmo cuidado aplicado aos dados da tarefa.

O erro mais fácil de cometer é ativar a gravação somente depois da primeira falha. Não há como inspecionar retroativamente uma evidência que não foi registrada. Comece por uma tarefa recorrente cuja próxima falha seja relevante.

O custo do navegador não é o maior gasto

A página atual de preços do Browser Run da Cloudflare não lista uma cobrança separada por gravação ou armazenamento das gravações. Uma Browser Session gravada continua entrando na conta normal de horas de navegador e concorrência. Como o Session Recording está em beta, trate esses valores como os preços publicados hoje, não como uma promessa permanente.

O Workers Free inclui 10 minutos de navegador por dia e três navegadores simultâneos. O Workers Paid tem um mínimo mensal de $5 por conta, inclui 10 horas de navegador e 10 navegadores simultâneos e, depois disso, cobra $0.09 por hora adicional de navegador e $2 por navegador simultâneo extra, com base na média mensal do pico de cada dia.

O preço direto de uma única repetição para diagnóstico é pequeno. O trabalho ao redor dela não é. Este é um modelo de planejamento, não um benchmark da Cloudflare:

• A conta já ultrapassou as 10 horas de navegador incluídas.
• Uma tarefa recorrente leva 10 minutos e falha 12 vezes em um mês.
• Reproduzir e diagnosticar cada falha consome 20 minutos de trabalho do operador.
• Inspecionar o registro existente leva 5 minutos de trabalho do operador.
• O custo-hora total do operador é estimado em $75.
• A inspeção evita uma repetição para diagnóstico, embora outra execução ainda possa ser necessária depois para verificar a correção.

Apenas 18 centavos dessa diferença correspondem ao tempo bruto de navegador. Os outros $225 são tempo do operador. A Cloudflare também arredonda o uso do navegador no nível da conta após somar todo o ciclo de cobrança; portanto, não espere ver 1.5 centavos referentes a uma execução de 10 minutos como item separado na fatura.

Essa é a consequência para o negócio. O painel Inspect não transforma a computação do navegador em uma grande economia. Ele pode eliminar de um incidente o ciclo de instrumentar, reproduzir e esperar.

O que o registro não consegue mostrar

A gravação captura o estado do documento e os eventos, não cada pixel renderizado.

Esses limites definem quais falhas ainda precisam de outro método de diagnóstico. Um gráfico desenhado em canvas, um formulário de checkout dentro de um iframe de terceiros, o estado de um vídeo, uma cena WebGL ou um valor digitado em um campo mascarado podem estar errados mesmo quando o restante do registro parece normal.

A visualização DOM também mostra a estrutura no fim da gravação. Ela pode explicar em qual página a tarefa terminou, mas não funciona como uma captura de tela pixel a pixel de cada estado anterior.

Também há limites operacionais. As gravações ficam disponíveis por 30 dias, duram no mínimo 1 segundo e no máximo 2 horas e funcionam com Browser Sessions por launch() ou CDP. Não é possível criá-las com Quick Actions. Uma página muito movimentada pode gerar um fluxo grande de eventos, porque cada mudança frequente no DOM vira dado de gravação.

Quem deve mudar o fluxo agora

Tome uma medida ainda esta semana se você executa tarefas recorrentes com Puppeteer, Playwright ou CDP e uma falha costuma começar com alguém tentando reproduzi-la. Adicione gravação a uma tarefa, não a todas, e então meça se o registro responde à primeira pergunta do diagnóstico.

Espere se o estado importante estiver principalmente em canvas, WebGL, mídia, iframe de outra origem ou campos de formulário mascarados. Mantenha capturas de tela, logs da aplicação e instrumentação direcionada nesse fluxo, porque a gravação não consegue substituí-los.

Nada muda se o seu trabalho se limita a Quick Actions. Migrar para Browser Sessions apenas para gravar altera a implementação e adiciona concorrência ao modelo de preços; o benefício de depuração precisa justificar essa mudança.

O que fazer na segunda-feira

Escolha uma Browser Session recorrente que já tenha falhado mais de uma vez. Adicione recording: true à inicialização, armazene o ID da sessão junto ao ID da sua própria tarefa e deixe a próxima execução agendada terminar normalmente.

Depois, recupere a gravação, escolha o primeiro ID de target relevante e solicite o tráfego bruto de rede ou o HAR. Cronometre quanto tempo você leva para identificar a requisição com falha ou o estado final da página. Se a evidência eliminar uma repetição para diagnóstico, mantenha a gravação nessa tarefa e incorpore o histórico ao registro do incidente. Caso contrário, desative-a novamente e acrescente o sinal que falta exatamente onde está o ponto cego.

Para receber mais análises operacionais sobre mudanças em plataformas, assine a newsletter.