Arquivos HAR — O Log de Depuração HTTP que Você Não Sabia que Precisava

Sua chamada à API está falhando no ambiente de produção. Funciona bem no curl e localmente. O suporte abre um ticket e pede que você "compartilhe um arquivo HAR". Você concorda com confiança e pesquisa no Google "o que é um arquivo HAR" em uma aba diferente.

Esta é a aba. Aqui está o que é um arquivo HAR, o que contém e como usá-lo para realmente encontrar o problema.

O que é um arquivo HAR

HAR significa HTTP Archive. É um arquivo JSON que registra todas as requisições HTTP feitas pelo navegador durante uma sessão — URLs, métodos, códigos de status, cabeçalhos de requisição e resposta, corpos de requisição e resposta, cookies e desdobramentos de tempo. Tudo isso, para cada requisição na página.

O formato foi padronizado pelo Web Performance Working Group (versão 1.2 do especificação) e é suportado por Chrome, Firefox, Safari e Edge. Pense nele como uma exportação estruturada da aba Network do navegador — o tipo de coisa que você daria a alguém para debugar seu problema sem dar acesso SSH à sua máquina.

Arquivos HAR são particularmente úteis quando o falha é intermitente, quando só se reproduz em um navegador específico ou quando você precisa mostrar a um fornecedor que sim, sua API está retornando um 500 e não é um problema de PEBKAC.

Como capturar um arquivo HAR

Chrome e Edge

1. Abra as ferramentas de desenvolvimento (F12 ou Cmd+Option+I no Mac)
2. Vá para o Rede aba
3. Ativar Preservar log se o problema ocorrer após um redirecionamento ou recarregamento da página
4. Reproduza o problema
5. Clique com o botão direito em qualquer lugar da lista de requisições → Salvar tudo como HAR com conteúdo

Raposa de fogo

1. Abra as ferramentas de desenvolvimento → Rede aba
2. Reproduza a requisição
3. Clique no ícone de engrenagem → Salve tudo como HAR

Safári

1. Habilite o menu Desenvolver: Safari → Configurações → Avançado → Mostre o menu Desenvolver
2. Desenvolver → Mostre o Inspectador Web → Rede
3. Reproduza o problema
4. Clique no Exportar botão (ícone de seta na barra de rede)

Uma coisa importante a notar sobre Preservar log: sem isso, o HAR apenas captura requisições feitas após o carregamento atual da página. Se o problema ocorrer durante a autenticação ou dentro de uma cadeia de redirecionamento, você capturará um arquivo vazio ou enganoso e passará 20 minutos confuso. Ative-o antes de reproduzir o problema.

O que está dentro de um arquivo HAR

Cada arquivo HAR compartilha a mesma estrutura de nível superior:

{
  "log": {
    "version": "1.2",
    "creator": { "name": "Chrome", "version": "124.0.6367.82" },
    "entries": [ ... ]
  }
}

O entries array é onde todos os dados úteis estão. Cada entrada é um par completo de requisição/resposta. Uma carga típica de página produz entre 50 e 200 entradas; uma SPA complexa carregando um painel pode ultrapassar esse número.

Entrada Anotada: Os Campos que Importam

Aqui está uma divisão dos campos principais em uma única entrada HAR:

Campo	Localização	O que ele告诉你
startedDateTime	Entrada	Quando a requisição foi enviada, no formato ISO 8601 UTC. Correlacione isso com logs do lado do servidor para encontrar a linha exata do log.
time	Entrada	Milissegundos totais desde o início da requisição até o final da resposta. O número a ser usado para ordenar quando busca requisições lentas.
serverIPAddress	Entrada	O IP que realmente tratou essa requisição. Crítico atrás de balanceadores de carga — diz qual instância você atingiu.
request.method	Solicitação	GET, POST, PUT, DELETE, etc.
request.url	Solicitação	URL completa incluindo a string de consulta. Observe por parâmetros duplicadamente codificados aqui.
request.headers	Solicitação	Todos os cabeçalhos de requisição. Inclui Autorização — tokens de autenticação estão aqui. Este é o problema de privacidade.
request.postData.text	Solicitação	Corpo bruto da requisição. Para APIs JSON, este é seu payload. Se a API está rejeitando entrada, verifique isso primeiro.
response.status	Resposta	Código de status HTTP. 0 geralmente significa que a requisição foi bloqueada antes de completar.
response.headers	Resposta	Cabeçalhos de resposta, incluindo Content-Type, Cache-Control, Set-Cookie. Útil para depuração de CORS.
response.content.text	Resposta	Corpo da resposta. Para APIs JSON, este é o JSON bruto. Pode estar codificado em base64 para respostas binárias.
timings.blocked	Tempo de execução	Tempo esperando por um slot de conexão TCP. Valores altos sugerem esgotamento do pool de conexões.
timings.dns	Tempo de execução	Tempo de resolução DNS. Acima de ~50ms merece atenção; acima de 200ms é um problema.
timings.connect	Tempo de execução	Tempo de conexão TCP. Valores altos = latência de rede ou sobrecarga TLS, não lentidão do servidor.
timings.wait	Tempo de execução	Tempo desde o envio da requisição até a recepção do primeiro byte (TTFB). É aqui que APIs lentas aparecem. TTFB alto = seu servidor está lento para responder.
timings.receive	Tempo de execução	Tempo para baixar o corpo da resposta. Apenas alto se o corpo da resposta for grande.

O que procurar realmente

Quando você abre um HAR, geralmente está procurando uma das três coisas:

A requisição que está falhando

Ordene ou filtre por response.status. No Chrome DevTools você pode filtrar diretamente com status-code:4xx ou status-code:5xx. Uma vez que tenha a requisição falhando, leia a entrada completa response.content.text — a mensagem de erro do servidor é geralmente mais útil do que o código de status.

A requisição que está lenta

Ordene entradas por timings.wait (TTFB) em ordem decrescente. TTFB alto wait = seu servidor está lento. TTFB alto timings.connect com valores normais wait = o gargalo é a rede ou o handshake TLS, não sua aplicação. Essas indicações apontam para soluções completamente diferentes, então obter isso certo poupa muito tempo de atribuição errada a uma camada incorreta.

A requisição que está faltando

Às vezes o erro é uma requisição ausente — um webhook que não foi disparado, um prévio OPTIONS bloqueado por CORS, uma chamada de análise que foi consumida por um bloqueador de anúncios. Compare o que deveria estar no HAR com o que está. A ausência de uma requisição é dado.

O problema de privacidade que você deve conhecer

Arquivos HAR contêm tudo. Isso inclui:

• Authorization cabeçalhos — tokens Bearer, credenciais de autenticação básica
• Cookie cabeçalhos — tokens de sessão, JWTs, qualquer coisa em um cookie
• Corpos de requisição e resposta — que podem conter senhas, dados pessoais ou chaves de API

O Chrome não remove nenhum desses ao exportar. Antes de compartilhar um arquivo HAR com suporte, fornecedor ou colega fora da sua empresa, remova ou redacte os campos sensíveis.

A forma mais rápida de inspecionar e limpar um HAR antes de compartilhar é o Formatador de Arquivo HAR — cole seu arquivo, navegue pelas entradas e redacte antes de enviar. Alternativamente, se você estiver confortável com jq:

# Strip Authorization headers from all entries
jq '.log.entries[].request.headers |= map(select(.name | ascii_downcase != "authorization"))' file.har

Não é a mais bonita linha única, mas funciona.

Ler um arquivo HAR bruto

Arquivos HAR são JSON, então tecnicamente podem ser lidos em qualquer editor de texto. Na prática, são enormes — uma carga típica de página produz um arquivo com centenas de kilobytes de cabeçalhos e corpos, todos em chaves profundamente aninhadas. Algumas formas de navegar neles:

• Importar no DevTools — Chrome e Firefox suportam importar arquivos HAR na aba de Rede via o ícone de engrenagem. Isso dá a você a mesma interface de filtragem e ordenação de uma captura em tempo real.
• Formatador de Arquivo HAR — Baseado no navegador, sem instalação necessária. Útil quando você está enviando o arquivo para alguém que não usa DevTools.
• jq — Para filtragem no terminal. jq '.log.entries[] | select(.response.status >= 400) | {url: .request.url, status: .response.status}' extrai todas as requisições falhas com suas URLs em segundos.

Para análise rápida e filtragem, jq é a mais rápida. Para compartilhamento e inspeção visual, a importação no navegador ou um formatação online significa que a outra pessoa não precisa saber o que jq é.

Você também pode gostar