FlowingDev

Arquivos HAR, explicados: a caixa-preta do seu navegador

Aprenda o que são arquivos HAR (HTTP Archive), como eles capturam cada requisição de rede que seu navegador faz e por que são essenciais para debugar a performance da web.

Testar a ferramenta: Visualizador HAR

Em uma frase

Um arquivo HAR é um log em formato JSON da interação de um navegador com um site, capturando cada requisição e resposta de rede em detalhes minuciosos para análise posterior.

O problema que ele resolve

Imagine a cena: um usuário do outro lado do mundo te manda uma DM, "Seu app está lento demais, impossível de usar." Você testa. Está voando. Ele diz que está quebrado. Você diz que na sua máquina funciona. Impasse.

Esse é o clássico disse me disse do desenvolvimento web. Antes das ferramentas de navegador modernas, debugar problemas de rede remotamente era um pesadelo de adivinhação, garimpo em logs de servidor e ter que pedir para usuários não-técnicos descreverem mensagens de erro esotéricas. Mesmo com o advento do DevTools dos navegadores e sua gloriosa aba Network, o problema permanecia: os dados eram efêmeros. Você não conseguia simplesmente "engarrafar" tudo aquilo e mandar para um colega. Um screenshot de um gráfico de cascata (waterfall) não conta a história toda.

É aí que entra o formato HTTP Archive, ou HAR. Concebido pelo Web Performance Working Group do W3C, ele foi projetado para ser um formato padrão e compartilhável para, bem, arquivar transações HTTP. É o equivalente digital de colocar uma caixa-preta no navegador de um usuário.

Um arquivo HAR resolve o problema do "na minha máquina funciona" ao capturar a conversa inteira da rede entre um navegador e um servidor durante o carregamento de uma página. Ele registra cada requisição para uma imagem, um script, uma fonte ou uma chamada de API. Ele anota os headers exatos enviados, os cookies trocados, os redirects seguidos e, o mais importante, os tempos precisos de cada estágio da requisição.

Isso permite que um desenvolvedor em São Francisco veja exatamente o que um usuário em Singapura experienciou, milissegundo por milissegundo, sem precisar adivinhar. Torna bugs de rede transitórios e difíceis de reproduzir em algo analisável e transforma reclamações vagas de "lentidão" em dados acionáveis.

Como funciona por debaixo dos panos

No fundo, um arquivo HAR não é mágica. É só um arquivo JSON grandão e estruturado. Você pode abrir um em um editor de texto e ver tudo, embora um visualizador dedicado torne a análise infinitamente mais fácil. Vamos dar uma espiada.

A Estrutura Geral: É Só JSON

Um arquivo HAR contém um único objeto JSON de nível superior com uma chave: log. Todo o resto vive dentro desse objeto log.

{
  "log": {
    "version": "1.2",
    "creator": { "name": "Chrome", "version": "118.0.0.0" },
    "browser": { "name": "Chrome", "version": "118.0.0.0" },
    "pages": [ /* ... um ou mais objetos de página ... */ ],
    "entries": [ /* ... um ou mais objetos de requisição/resposta ... */ ]
  }
}
  • version: A versão da especificação HAR, geralmente "1.2".
  • creator / browser: Metadados sobre qual ferramenta e navegador geraram o arquivo. Útil para dar contexto.
  • pages: Um array descrevendo a página principal ou páginas que foram carregadas. Inclui o título da página e tempos para eventos de alto nível como onLoad e onContentLoad.
  • entries: Essa é a estrela do show. É um array longo onde cada objeto representa uma única requisição de rede e sua respectiva resposta.

A Estrela do Show: O Array entries

Quando você analisa um arquivo HAR, você passa 99% do seu tempo nos entries. Cada entrada é um dossiê completo sobre um recurso.

Aqui está uma visão simplificada de uma única entrada:

{
  "startedDateTime": "2023-10-27T10:30:05.123Z",
  "time": 258.45,
  "request": { /* ... detalhes da requisição ... */ },
  "response": { /* ... detalhes da resposta ... */ },
  "timings": { /* ... os detalhes suculentos da performance ... */ },
  "pageref": "page_1"
}
  • startedDateTime: O timestamp UTC exato de quando a requisição começou.
  • time: O tempo total decorrido para a requisição em milissegundos, do início ao fim.
  • request: Um objeto contendo tudo o que o navegador enviou ao servidor.
  • response: Um objeto contendo tudo o que o servidor enviou de volta.
  • timings: A mina de ouro para debugar performance. Vamos dissecar isso a seguir.
  • pageref: Um ID que vincula esta requisição a uma das pages no array de páginas.

Anatomia de uma Requisição e Resposta

Os objetos request e response são espelhos do que você veria no DevTools.

O objeto request detalha:

  • method: GET, POST, PUT, etc.
  • url: A URL completa do recurso.
  • headers: Um array com todos os headers da requisição, como User-Agent, Accept e Cookie.
  • queryString: Um array com quaisquer parâmetros de query na URL.
  • postData: Para requisições POST, isso contém o payload, como dados de formulário ou um corpo JSON.

O objeto response detalha:

  • status: O código de status HTTP (ex: 200, 404, 500).
  • statusText: A frase de motivo (ex: OK, Not Found).
  • headers: Um array com todos os headers da resposta, como Content-Type, Cache-Control e Set-Cookie.
  • content: Um objeto descrevendo o corpo da resposta, incluindo seu size, mimeType e, muitas vezes, o próprio corpo na propriedade text (embora isso possa ser omitido para economizar espaço ou por segurança).

A Análise Detalhada dos Timings (Waterfall)

O objeto timings é o que alimenta o colorido gráfico de cascata (waterfall) em um visualizador de HAR. Ele quebra o time total da requisição em suas fases constituintes. Entender isso é a chave para diagnosticar "por que" uma requisição foi lenta.

Timing O que significa
blocked Tempo que a requisição passou esperando na fila do navegador antes mesmo de poder começar. Geralmente devido a limites de conexão.
dns Tempo gasto na busca de DNS. Um valor alto pode indicar um provedor de DNS lento.
connect Tempo necessário para estabelecer uma conexão TCP com o servidor. Inclui o tempo de ssl.
ssl (Parte do connect) Tempo para o handshake SSL/TLS. Valores altos podem apontar para problemas de configuração do servidor ou de rede.
send Tempo gasto enviando a requisição HTTP para o servidor. Geralmente muito curto.
wait Time To First Byte (TTFB). O mais crítico de todos. Tempo gasto esperando o servidor processar a requisição e enviar o primeiro byte da resposta. Um tempo de wait longo é quase sempre um problema no backend.
receive Tempo gasto baixando o corpo da resposta do servidor. Um tempo de receive longo em um arquivo pequeno pode indicar uma rede lenta; em um arquivo grande, é esperado.

O time total para uma entrada é a soma desses tempos individuais (não negativos). Quando um visualizador de HAR mostra uma barra para uma requisição, ele está visualmente empilhando esses valores de timings ponta a ponta.

Histórias do mundo real

O Caso da Lentidão Misteriosa

Um PM frenético manda mensagem pro time: "A nova página de checkout está super lenta para o nosso maior cliente! Eles estão ameaçando cancelar o contrato!" O time de desenvolvimento testa o fluxo de checkout. Está voando. O cliente insiste que leva 20 segundos para confirmar um pedido. Em vez de uma discussão infrutífera, o dev líder orienta o cliente sobre como exportar um arquivo HAR.

Ao abrir o arquivo, o problema fica instantaneamente óbvio. Nos entries, a requisição POST para /api/v1/finalize_order tem um time total de 20.145ms. Olhando para o objeto timings, o wait (TTFB) é de mais de 20.000ms. O servidor de backend está levando 20 segundos para responder. Acontece que este cliente específico tinha um histórico de pedidos massivo, e uma query de banco de dados não otimizada estava dando timeout, mas apenas para a conta dele. O arquivo HAR foi a prova cabal que apontava diretamente para um processo específico do backend.

A Lição: Um arquivo HAR captura condições específicas do usuário (como dados da conta) que você não consegue replicar, transformando um mistério em um relatório de bug direcionado.

O Culpado: O Bundle Inchado

Um site de marketing vai ao ar e a taxa de rejeição (bounce rate) está nas alturas. Ele simplesmente parece pesado. Um dev front-end acessa o site, abre o DevTools, grava uma sessão e exporta o HAR.

No visualizador de HAR, ele ordena as entradas por tamanho. No topo está main.acb123.js com impressionantes 5.2 MB. O waterfall mostra que é um recurso que bloqueia a renderização; nada aparece na página até que esse monstro termine de baixar. O tempo de receive sozinho leva vários segundos, mesmo em uma conexão rápida. Pior, olhando os headers da response para esta entrada, ele vê que o servidor não está enviando um header Content-Encoding: gzip, apesar de o navegador enviar Accept-Encoding: gzip nos headers da request. O bundle de JavaScript não estava sendo comprimido.

A Lição: Arquivos HAR tornam trivialmente fácil identificar assassinos de performance como assets superdimensionados e configurações incorretas do servidor que estão matando seu tempo de carregamento de página.

O Loop de Redirect Infinito

Um usuário reclama que não consegue fazer login. Ele insere suas credenciais, clica em "Log In" e é imediatamente jogado de volta para a página de login sem nenhum erro. É um loop clássico. O suporte pede ao usuário um arquivo HAR da tentativa de login.

A lista de entries no HAR conta uma história clara:

  1. POST /login tem sucesso e recebe um 302 Redirect para /dashboard. A resposta inclui um header Set-Cookie com o token de sessão.
  2. O navegador segue o redirect e faz uma requisição GET /dashboard.
  3. O servidor responde ao GET /dashboard com um 302 Redirect de volta para /login.

Por quê? O dev inspeciona a entrada da requisição GET /dashboard. O header Cookie está sem o token de sessão. Então ele verifica a resposta do POST /login inicial. O header Set-Cookie era session_id=...; Secure; HttpOnly. O flag Secure significa que o navegador só enviará o cookie por HTTPS. O usuário estava em um ambiente http://staging.example.com. O navegador estava corretamente se recusando a enviar o cookie seguro por uma conexão insegura, então o servidor nunca o viu como logado.

A Lição: Arquivos HAR te dão um replay perfeito, quadro a quadro, de redirects HTTP e trocas de headers, tornando possível debugar fluxos de autenticação complexos que falham silenciosamente.

Erros e armadilhas comuns

  • Esquecer de marcar a opção "Preserve log". Se o seu bug envolve navegar da página A para a página B, você deve habilitar a opção "Preserve log" (ou equivalente) no DevTools. Caso contrário, o log é limpo na navegação, e seu arquivo HAR conterá apenas as requisições da página B.
  • Compartilhar dados sensíveis. Arquivos HAR são gravadores indiscriminados. Eles capturarão chaves de API, tokens de sessão em cookies e informações de identificação pessoal em corpos de POST. Sempre sanitize os arquivos HAR antes de compartilhá-los em bug trackers públicos ou fóruns.
  • Interpretar mal o tempo de blocked. Um tempo de blocked alto nem sempre significa que a rede está congestionada. Os navegadores têm um limite de quantas conexões paralelas eles abrem para um único domínio (geralmente 6). Se você disparar 20 requisições de imagem de uma vez, 14 delas ficarão em estado de blocked, esperando uma das 6 primeiras terminar.
  • Ignorar o estado do cache. Se você está testando a performance do primeiro carregamento, precisa gravar com o cache do navegador desabilitado. Caso contrário, você verá muitas respostas 304 Not Modified ou requisições que completam em menos de um milissegundo, o que não reflete a experiência de um novo usuário.

Por que isso deve estar no seu radar

Você deve pensar em usar um arquivo HAR sempre que a comunicação de rede for uma suspeita em potencial.

  • Quando um usuário relata um problema de performance que você não consegue reproduzir.
  • Quando você precisa otimizar uma página que carrega lentamente e quer identificar os maiores gargalos.
  • Quando você está debugando um fluxo de API de várias etapas, como um login OAuth ou um processo de pagamento, e precisa ver a sequência exata de eventos.
  • Quando você precisa abrir um bug report com um serviço de terceiros (como um CDN ou provedor de API) e quer fornecer a eles uma prova irrefutável do problema. Um arquivo HAR é a linguagem universal dos problemas de rede.

Para ir além

Teoria feita. Hora de pôr a mão na massa — 100% no seu navegador.

Testar a ferramenta: Visualizador HAR