O que é um ficheiro HAR? Como gravar um, como o ler e como o partilhar em segurança

Alguém lhe pede um ficheiro HAR. Normalmente é o suporte, ou um programador a olhar para um erro que reportou, e quase sempre o pedido chega com instruções que partem do princípio de que já sabe o que isso é.

Um ficheiro HAR é a gravação de todos os pedidos que o navegador fez enquanto estava a fazer alguma coisa, guardada num único ficheiro. HAR quer dizer HTTP Archive. É um ficheiro JSON simples que lista cada pedido que a página enviou, o que veio de volta, quanto tempo cada um demorou e por que ordem: o separador Rede das ferramentas de programador do seu navegador, posto por escrito e entregue.

O que está lá dentro

Para cada pedido que a página fez enquanto gravava:

• O pedido: método, URL completo, cabeçalhos, query string e o corpo, se existia
• A resposta: código de estado, cabeçalhos, tipo de conteúdo, tamanho e muitas vezes o corpo
• Os tempos: quanto o pedido esperou, demorou a ligar, a enviar e a receber o primeiro byte
• Quando aconteceu, de forma que a ordem e os intervalos entre pedidos se mantêm

É esta última parte que torna um HAR mais útil do que uma captura de ecrã do separador Rede. Uma captura mostra-lhe uma lista; um HAR deixa alguém repetir a sequência e ver que a renovação do token só arrancou depois do pedido que precisava dela.

Quando lho pedem

Quase sempre porque o problema é invisível de fora e acontece só consigo.

• Uma página carrega para si e não para eles, ou ao contrário
• Alguma coisa falha em silêncio, sem que a interface o diga
• Um pedido está lento e ninguém sabe dizer se é a rede, o servidor ou o navegador
• Uma integração devolve um erro só em produção, e só para uma conta

Em todos estes casos a resposta costuma ser uma linha num ficheiro para o qual ninguém olhou: um 403 onde se esperava um 200, um pedido que nunca chegou a sair, um ciclo de redirecionamentos, um erro de CORS que a página engoliu.

Como gravar um

Chrome ou Edge. Abra as ferramentas de programador com F12, ou Cmd + Option + I num Mac. Vá ao separador Rede. Marque Preservar registo para que um redirecionamento não apague o que já gravou. Reproduza o problema. Depois clique com o botão direito em qualquer linha da lista e escolha Guardar tudo como HAR com conteúdo.

Firefox. Ferramentas de programador, separador Rede, reproduza, e depois clique com o botão direito numa linha e escolha Guardar tudo como HAR.

Safari. Ative o menu Programar nas definições, depois Programar, Mostrar Inspetor Web, Rede e Exportar.

Duas coisas que escapam a toda a gente. Comece a gravar antes daquilo que quer demonstrar, porque o separador Rede só guarda o que viu. E reproduza o problema uma vez e pare: um HAR com onze minutos de cliques é um ficheiro que ninguém vai ler.

Ler um sem ferramenta nenhuma

A entrada mais rápida é abrir o ficheiro no próprio separador Rede de um navegador: arraste o HAR para cima do painel Rede e ele carrega como se o tivesse gravado, com ordenação e filtros.

O que olhar, mais ou menos por esta ordem:

Isto não primeiro

Percorrer a lista inteira à procura de alguma coisa que pareça errada

Isto primeiro

Filtrar por estado 400 para cima, depois pelos poucos pedidos mais lentos, e depois ver o que aconteceu mesmo antes da falha

Um HAR é JSON, por isso o jq também funciona com ele: jq '.log.entries[] | select(.response.status >= 400) | {url: .request.url, status: .response.status}' capture.har dá-lhe as falhas numa linha.

Um HAR só guarda pedidos que o navegador fez. Para inspecionar um que o seu próprio código envia, aponte-o ao endpoint de teste de webhooks, que lhe dá um URL e mostra o método, os cabeçalhos, a query string e o corpo do que lá chegar.

A parte de que ninguém o avisa

Um ficheiro HAR contém quase sempre credenciais. É a coisa mais importante a saber sobre ele, e as instruções que lhe mandam raramente a mencionam.

Guardado com conteúdo, um HAR leva todos os cabeçalhos de pedido, ou seja cookies de sessão e tokens de autorização, e todos os corpos de resposta, que podem incluir dados pessoais de quem estava autenticado. Quem tiver o ficheiro consegue muitas vezes agir como esse utilizador até esses tokens expirarem.

Por isso:

• Trate um HAR como uma palavra-passe. Não o cole num gestor de erros público, num canal partilhado ou numa cadeia de email que vai ser reencaminhada.
• Limpe-o antes de o partilhar, se conseguir. Algumas ferramentas retiram os cookies e os cabeçalhos de autorização; senão, abra o JSON e retire-os à mão.
• Grave numa janela privada com uma conta de teste quando o problema o permitir, o que mantém dados reais de clientes inteiramente fora do ficheiro.
• Apague-o depois. É prova de uma investigação, não um documento.

Se for você a pedir um HAR, diga tudo isto no pedido. A maior parte das pessoas que lhe manda um com o token de sessão ativo nunca ouviu ninguém dizer-lhe que não o fizesse.

Conseguir um sem as instruções

Tudo o que está acima são quatro parágrafos de instruções para alguém que só quer avisar que uma página está partida, e é por isso que os ficheiros HAR tantas vezes não chegam sequer a aparecer.

O registo de rede que captura inclui um ficheiro HAR que pode transferir e abrir nas ferramentas de programador, por isso quem pega no relatório fica com o mesmo ficheiro que teria pedido, sem ter tido de o pedir. O que não faz é decidir por si o que há a ocultar: o aviso acima continua a valer para tudo o que partilhar.

Para tudo o que rodeia o ficheiro - o que esperava, o que aconteceu e de que build se tratava - o guia do relatório de erro tem o modelo.