Fichiers HAR — Le journal de débogage HTTP que vous ne saviez pas que vous aviez besoin

Votre appel à l'API échoue en production. Il fonctionne parfaitement avec curl et localement. Le support ouvre un ticket et vous demande de « partager un fichier HAR ». Vous acquiescez avec confiance et recherchez sur Google « qu'est-ce qu'un fichier HAR » dans une autre onglet.

C'est cet onglet. Voici ce qu'est un fichier HAR, ce qu'il contient et comment l'utiliser pour trouver effectivement le problème.

Qu'est-ce qu'un fichier HAR ?

HAR signifie HTTP Archive. C'est un fichier JSON qui enregistre chaque requête HTTP faite par votre navigateur pendant une session — les URLs, les méthodes, les codes de statut, les en-têtes de requête et de réponse, les corps de requête et de réponse, les cookies, ainsi que les détails de timing. Tout cela, pour chaque requête sur la page.

Ce format a été standardisé par le groupe de travail sur les performances web (version 1.2 du spécification) et est pris en charge par Chrome, Firefox, Safari et Edge. Pensez-y comme à une exportation structurée de la page Réseau de votre navigateur — le genre de chose que vous pourriez donner à quelqu'un qui débogue un problème sans lui donner accès SSH à votre machine.

Les fichiers HAR sont particulièrement utiles lorsque l'échec est intermittent, lorsqu'il se produit uniquement dans un navigateur spécifique, ou lorsque vous devez montrer à un fournisseur que oui, leur API retourne un 500 et ce n'est pas un problème de PEBKAC.

Comment capturer un fichier HAR ?

Chrome et Edge

1. Ouvrir DevTools (F12 ou Cmd+Option+I sur Mac)
2. Allez sur le Réseau onglet
3. Activer Préserve le journal si l'échec se produit après un redirige ou une rechargement de page
4. Reproduire le problème
5. Clic droit n'importe où dans la liste des requêtes → Enregistrer tout en tant que HAR avec contenu

Firefox

1. Ouvrir DevTools → Réseau onglet
2. Reproduire la requête
3. Clic sur l'icône à molette → Enregistrer tout en tant que HAR

Safari

1. Activer le menu Développement : Safari → Paramètres → Avancé → Afficher le menu Développement
2. Développement → Afficher l'inspecteur web → Réseau
3. Reproduire le problème
4. Cliquez sur le Exporter bouton (icône de flèche dans la barre de navigation du réseau)

Une chose à noter concernant Préserve le journal: sans cela, le HAR ne capte que les requêtes faites après le chargement actuel de la page. Si l'échec se produit pendant l'authentification ou au sein d'une chaîne de redirection, vous obtenez un fichier vide ou trompeur et passez 20 minutes dans la confusion. Activez-le avant de reproduire le problème.

Ce qu'il contient dans un fichier HAR

Chaque fichier HAR partage la même structure au niveau supérieur :

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

Le entries un tableau est là où se trouvent toutes les données utiles. Chaque entrée correspond à une paire requête/réponse complète. Une page chargée typiquement produit entre 50 et 200 entrées ; une application progressive complexe chargant un tableau de bord peut dépasser ce chiffre.

Entrée annotée : Les champs qui importent

Voici une analyse des champs clés dans une entrée HAR individuelle :

Champ	Emplacement	Ce que cela vous dit
startedDateTime	Entrée	L'heure à laquelle la requête a été lancée, au format ISO 8601 UTC. Corrélez cela avec les journaux serveur pour trouver la ligne exacte du journal.
time	Entrée	Durée totale en millisecondes depuis le début de la requête jusqu'à la fin de la réponse. Le chiffre à trier lorsqu'on cherche des requêtes lentes.
serverIPAddress	Entrée	L'IP qui a effectivement traité cette requête. Critique derrière les chargeurs — vous indiquez laquelle des instances vous avez touché.
request.method	Demande	GET, POST, PUT, DELETE, etc.
request.url	Demande	URL complète incluant la chaîne de requête. Regardez attentivement les paramètres mal encodés ici.
request.headers	Demande	Tous les en-têtes de requête. Inclut l'authentification — les tokens d'authentification sont là. C'est la préoccupation de confidentialité.
request.postData.text	Demande	Corps brut de la requête. Pour les API JSON, c'est votre charge utile. Si l'API rejette l'entrée, vérifiez d'abord cela.
response.status	Réponse	Code de statut HTTP. 0 signifie généralement que la requête a été bloquée avant de pouvoir être complétée.
response.headers	Réponse	En-têtes de réponse, incluant Content-Type, Cache-Control, Set-Cookie. Utile pour le débogage CORS.
response.content.text	Réponse	Corps de réponse. Pour les API JSON, c'est le JSON brut. Peut être encodé en base64 pour les réponses binaires.
timings.blocked	Temps	Temps d'attente pour un slot de connexion TCP. Des valeurs élevées suggèrent une épuisement du pool de connexions.
timings.dns	Temps	Temps de résolution DNS. Au-dessus de 50 ms, il vaut la peine d'analyser ; au-dessus de 200 ms, c'est un problème.
timings.connect	Temps	Temps de connexion TCP. Des valeurs élevées = latence réseau ou surcharge TLS, pas une lenteur du serveur.
timings.wait	Temps	Temps entre l'envoi de la requête et la réception du premier octet (TTFB). C'est là où les API lentes apparaissent. Un TTFB élevé signifie que votre serveur répond lentement.
timings.receive	Temps	Temps de téléchargement du corps de réponse. Élevé uniquement si le corps de réponse est volumineux.

Ce que vous devez chercher réellement

Lorsque vous ouvrez un HAR, vous cherchez généralement l'un des trois éléments suivants :

La requête qui échoue

Trier ou filtrer par response.status. Dans Chrome DevTools, vous pouvez filtrer en temps réel avec status-code:4xx ou status-code:5xx. Une fois que vous avez la requête échouée, lisez la totalité de response.content.text — le message d'erreur du serveur est généralement plus utile que le code de statut.

La requête qui est lente

Trier les entrées par timings.wait (TTFB) en ordre décroissant. Un wait = votre serveur est lent. Un timings.connect avec un wait = le goulot d'étranglement est la couche réseau ou le handshake TLS, pas votre application. Ces éléments pointent vers des solutions complètement différentes, donc obtenir cela correctement économise beaucoup de temps en attribuant le problème à la mauvaise couche.

La requête qui est manquante

Parfois, le bug est une requête manquante — une webhook qui n'a pas été déclenchée, une requête préliminaire OPTIONS bloquée par CORS, une requête d'analyse qui a été mangée par un bloqueur publicitaire. Comparez ce qui devrait être dans le HAR avec ce qui est présent. L'absence d'une requête est une donnée.

Le problème de confidentialité que vous devez connaître

Les fichiers HAR contiennent tout. Cela inclut :

• Authorization en-têtes — tokens Bearer, identifiants de base authentification
• Cookie en-têtes — tokens de session, JWT, tout ce qui se trouve dans un cookie
• Corps de requête et de réponse — qui peuvent contenir des mots de passe, des données sensibles (PII) ou des clés API

Chrome ne supprime aucun de ces éléments lors de l'exportation. Avant de partager un fichier HAR avec le support, un fournisseur ou un collègue en dehors de votre entreprise, supprimez ou masquez les champs sensibles.

La méthode la plus rapide pour inspecter et nettoyer un HAR avant de le partager est l'outil HAR File Formatter — collez votre fichier, parcourrez les entrées et masquez-les avant de l'envoyer. Alternativement, si vous êtes à l'aise avec jq:

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

Pas la plus jolie ligne unique, mais elle fonctionne.

Lecture d'un fichier HAR brut

Les fichiers HAR sont au format JSON, donc en théorie lisibles dans n'importe quel éditeur de texte. En pratique, ils sont énormes — une page chargée produit un fichier de plusieurs centaines de kilo-octets d'en-têtes et de corps, tous profondément ancrés dans des clés imbriquées. Quelques moyens de les naviguer :

• Importer dans DevTools — Chrome et Firefox prennent en charge l'importation de fichiers HAR dans l'onglet Réseau via l'icône à molette. Cela vous donne l'interface de tri et de filtre comme dans une capture en direct.
• HAR File Formatter — Basé sur le navigateur, sans installation requise. Idéal lorsque vous envoyez le fichier à quelqu'un qui ne utilise pas DevTools.
• jq — Pour le filtrage en ligne de commande. jq '.log.entries[] | select(.response.status >= 400) | {url: .request.url, status: .response.status}' extraire toutes les requêtes échouées avec leurs URLs en secondes.

Pour une analyse rapide et un filtrage, jq est la plus rapide. Pour le partage et l'inspection visuelle, l'importation dans le navigateur ou un formatateur en ligne signifie que la personne reçue n'a pas besoin de connaître ce que jq est.

Vous aimerez peut-être aussi