Qu'est-ce que l'API User Timing ?

Qu'est-ce que l'API User Timing ?

L'API User Timing fait partie de la Web Performance API. Elle permet à votre propre JavaScript de poser des horodatages nommés (marks) et la durée entre eux (measures) sur la chronologie de performance haute résolution du navigateur, pour chronométrer des étapes que seule votre application connaît, comme « résultats de recherche affichés » ou « formulaire de paiement prêt ».

Comment ça marche

• performance.mark(name) crée un PerformanceMark (type d'entrée mark) à l'instant courant. Options : startTime et detail.
• performance.measure(name, startMark, endMark) crée un PerformanceMeasure (type measure). Sa duration est la fin moins le début. Vous pouvez aussi passer un objet d'options avec start, end, duration et detail. Sans fin, la mesure se termine maintenant.
• On lit les entrées avec un PerformanceObserver, la méthode préférée selon MDN, ou avec performance.getEntriesByType('measure'). On les supprime avec clearMarks() et clearMeasures().

Dans le panneau Performance de Chrome DevTools, une mark dont le detail contient un objet devtools avec dataType: 'marker' apparaît dans la piste Timings, et les measures avec dataType: 'track-entry' dessinent des pistes personnalisées (activez « Show custom tracks » dans les paramètres de capture). La prise en charge de cette extension varie selon le navigateur. Détails : MDN.

Exemple

Mesurez le temps d'une recherche, de la requête à l'affichage des résultats :

performance.mark('search-start');
const data = await fetch('/api/search?q=shoes').then(r => r.json());
renderResults(data);
performance.mark('search-rendered');
performance.measure('search-total', 'search-start', 'search-rendered');
const [m] = performance.getEntriesByName('search-total');
console.log(m.duration);

Le résultat est une entrée search-total avec une durée en millisecondes, visible dans le code et dans les outils de développement.

User Timing et ses voisines

Navigation Timing couvre les étapes intégrées du chargement de page, et l'en-tête Server-Timing transporte les durées du backend. User Timing sert aux étapes intermédiaires que seul votre code peut nommer. Envoyez les mesures à votre outil d'analyse et vous obtenez du suivi des utilisateurs réels pour vos propres parcours. Pour le chargement de page et les Core Web Vitals depuis des lieux fixes, voir la surveillance de la vitesse de page LoadFocus. Une vue plus large dans le guide des tests de performance front-end.

Erreurs fréquentes

• Mesurer avant que la mark de fin existe. Une mark nommée introuvable lève une SyntaxError.
• Mélanger les formes d'options. duration n'est valide qu'avec exactement un de start ou end, sinon TypeError.
• Réutiliser un nom pour des étapes différentes. getEntriesByName() renvoie alors plusieurs entrées : nommez chaque étape clairement.
• Ne jamais nettoyer les entrées dans une application monopage durable. Supprimez les marks et measures déjà envoyées.
• Poser des marks dans des boucles serrées. Cela inonde la chronologie et masque les étapes utiles.

Questions fréquentes : API User Timing

Quelle différence entre mark et measure ?

Une mark est un instant nommé. Une measure est la durée entre deux points, qui peuvent être deux marks, des horodatages ou un de chaque.

Faut-il un PerformanceObserver ?

Non, mais c'est le meilleur choix car il vous prévient à la création des entrées. Les méthodes get ne renvoient que celles qui existent déjà.

Comment voir marks et measures dans les DevTools ?

Enregistrez un profil dans le panneau Performance. Avec un objet devtools dans detail, les marqueurs vont dans la piste Timings et les measures dans des pistes personnalisées.

Est-ce la même chose que performance.now() ?

Non. performance.now() renvoie un horodatage. User Timing enregistre des entrées nommées sur la chronologie de performance, lisibles par les outils et les observateurs.

Cela fonctionne-t-il dans les Web Workers ?

Oui, MDN indique que performance.measure() est disponible dans les workers.