Qu'est-ce que la Web Performance API ?

Qu'est-ce que la Web Performance API ?

La Web Performance API, souvent appelée Performance API, est un ensemble de standards du navigateur pour mesurer les performances d'une page web. Elle enregistre les temps de navigation, de ressources, d'affichage et de tâches longues sur une chronologie haute précision, permet d'ajouter vos propres repères et mesures, et fonctionne dans les pages comme dans les workers : vous pouvez ainsi envoyer à votre outil d'analyse des mesures d'utilisateurs réels.

Comment ça marche

Chaque métrique est un PerformanceEntry avec un name, un startTime, une duration et un entryType. Le navigateur enregistre la plupart des entrées automatiquement. Vous pouvez les lire avec performance.getEntries(), mais mieux vaut un PerformanceObserver, qui vous prévient quand de nouvelles entrées sont enregistrées. Ces mêmes données alimentent la Performance Timeline affichée dans les outils de développement.

Les types d'entrées les plus utilisés

• Navigation timing : une entrée pour le document courant, avec redirectCount, domInteractive, domComplete, loadEventEnd et un type navigate, reload ou back_forward.
• Resource timing : les temps réseau de chaque image, script, feuille de style et appel fetch, avec initiatorType, transferSize, responseStatus et nextHopProtocol.
• Paint, LCP et décalages de mise en page : entrées de paint timing, de Largest Contentful Paint et de layout shift, la matière première des Core Web Vitals.
• Event timing et tâches longues : la latence des événements (la base d'Interaction to Next Paint) et les tâches qui bloquent le thread principal.
• Marks et measures : vos propres repères et le temps qui les sépare, utiles pour des étapes comme « paiement démarré » jusqu'à « paiement affiché ».

Exemple

Cet extrait journalise chaque ressource au chargement, lit l'entrée de navigation et mesure une étape personnalisée :

const po = new PerformanceObserver((list) => {
  for (const e of list.getEntries()) console.log(e.name, e.duration);
});
po.observe({ type: "resource", buffered: true });

const [nav] = performance.getEntriesByType("navigation");
console.log(nav.type, nav.domInteractive, nav.loadEventEnd);

performance.mark("checkout-start");
// ... work ...
performance.mark("checkout-end");
performance.measure("checkout", "checkout-start", "checkout-end");

Notez que buffered: true fonctionne avec type (un type d'entrée par appel), pas avec entryTypes. Il renvoie aussi les entrées enregistrées avant l'appel à observe().

Erreurs courantes

• Lire des temps cross-origin et obtenir des zéros. Pour les ressources d'une autre origine, des champs comme domainLookupStart, connectStart et requestStart renvoient 0 tant que ce serveur n'envoie pas l'en-tête Timing-Allow-Origin.
• Mélanger entryTypes et buffered. Utilisez type quand il vous faut des entrées en tampon, avec un observer par type.
• Observer trop tard. Les observers enregistrés après le chargement de la page manquent les entrées antérieures si vous ne demandez pas les entrées en tampon.
• Se fier à une seule visite. L'API mesure un utilisateur, sur un appareil et un réseau donnés. Agrégez de nombreuses visites et regardez les percentiles, pas une valeur isolée.
• Prendre un transferSize à 0 pour une erreur. Il indique une réponse servie par le cache local.

Performance API, supervision des utilisateurs réels et tests synthétiques

La Performance API fournit les données de la supervision des utilisateurs réels (RUM) : elle s'exécute dans le navigateur de vos visiteurs et montre ce qu'ils ont réellement vécu. La supervision synthétique fait l'inverse : un test scripté charge la page à intervalle régulier depuis un lieu connu, ce qui rend les résultats comparables d'une exécution à l'autre. Il faut les deux. Le suivi de la vitesse des pages de LoadFocus lance des audits Lighthouse planifiés depuis des régions cloud et conserve l'historique, et le vérificateur gratuit de Core Web Vitals donne une lecture rapide pour n'importe quelle URL. Pour une mise en place pas à pas, voir le guide surveiller les Core Web Vitals avec alertes et rapports (en anglais). L'API est aussi disponible dans un web worker : on peut donc mesurer le travail déporté hors du thread principal.

Questions fréquentes

Quelle différence entre la Performance API et la Performance Timeline ?

La Performance API est l'ensemble des interfaces et méthodes que vous appelez en JavaScript. La performance timeline est l'enregistrement ordonné des entrées que tient le navigateur, que l'API lit et que les outils de développement affichent.

Faut-il utiliser getEntries() ou PerformanceObserver ?

Préférez PerformanceObserver. Il vous prévient à l'enregistrement des entrées, sans interrogation répétée, et avec l'option type et buffered à true il renvoie aussi les entrées antérieures.

Pourquoi certains temps valent 0 pour les ressources tierces ?

Pour les ressources d'une autre origine, le navigateur masque les temps détaillés comme la résolution DNS et le début de la connexion. Le serveur qui héberge la ressource doit envoyer un en-tête Timing-Allow-Origin pour les exposer.

La Performance API remplace-t-elle un outil de supervision ?

Non. Elle collecte des mesures dans le navigateur, mais il faut encore un endroit pour les stocker, les agréger et déclencher des alertes. Associez-la à des vérifications synthétiques planifiées pour repérer aussi les problèmes quand personne ne visite la page.