Qu'est-ce que l'API Performance Timeline ?

Qu'est-ce que l'API Performance Timeline ?

La Performance Timeline est le journal ordonné des entrées de performance d'une page dans le navigateur : navigation, ressources, rendu, décalages de mise en page, vos propres repères et plus encore. La spécification du W3C définit comment les entrées sont stockées, lues et observées, via getEntries(), getEntriesByType(), getEntriesByName() et PerformanceObserver. D'autres API de mesure y écrivent leurs entrées.

Comment ça marche

Chaque objet global, c'est-à-dire chaque page ou worker, conserve un tampon d'entrées par type. Chaque entrée est un PerformanceEntry avec name, entryType, startTime et duration. Deux façons de les lire :

• Instantané : getEntries() renvoie ce qui se trouve dans la chronologie à l'instant, trié par startTime, et getEntriesByType() et getEntriesByName() le filtrent. Il ne signale jamais les nouvelles entrées, et un second appel renvoie les mêmes entrées. Certains types, comme layout shift, largest contentful paint, event et long task, ne sont jamais renvoyés.
• Observateur : un PerformanceObserver vous appelle au fur et à mesure que les entrées sont enregistrées. MDN en fait la méthode à privilégier. Avec type et buffered: true, vous recevez aussi les entrées enregistrées avant le début de l'observation.

La chronologie est la couche commune. L'API Web Performance est la famille plus large d'interfaces qui l'alimentent, comme Navigation Timing et User Timing. Pour les durées côté serveur, voir l'API Server-Timing.

Types d'entrées et limites des tampons

MDN liste ces types : element, event, first-input, largest-contentful-paint, layout-shift, longtask, mark, measure, navigation, paint, resource et visibility-state. La prise en charge varie selon le navigateur : consultez donc PerformanceObserver.supportedEntryTypes avant d'observer. Dans les workers, la liste est généralement plus courte.

Les tampons sont limités. MDN donne ces limites par objet global : 250 pour resource (ajustable), 200 pour longtask, 150 chacun pour element, event, layout-shift et largest-contentful-paint, 50 pour visibility-state, 2 pour paint, 1 pour first-input, et aucune limite pour mark, measure et navigation. Quand un tampon est plein, les nouvelles entrées ne sont pas stockées et un compteur d'entrées perdues augmente ; un observateur le reçoit sous le nom droppedEntriesCount.

Exemple

// which entry types does this browser support?
console.log(PerformanceObserver.supportedEntryTypes);

// resource entries, including those recorded before this line
const po = new PerformanceObserver((list, obs, opts) => {
  for (const e of list.getEntries()) console.log(e.entryType, e.name, e.startTime);
  if (opts && opts.droppedEntriesCount) console.warn("dropped:", opts.droppedEntriesCount);
});
po.observe({ type: "resource", buffered: true });

// snapshot of what is in the timeline right now, ordered by startTime
const marks = performance.getEntriesByType("mark");

Une page avec beaucoup d'images et de scripts peut dépasser 250 entrées de ressources. Augmentez la limite avec performance.setResourceTimingBufferSize(), ou enregistrez puis videz les entrées avec clearResourceTimings() quand l'événement resourcetimingbufferfull se déclenche.

Erreurs courantes

• Interroger getEntries() en boucle. Vous relisez d'anciennes entrées et manquez malgré tout certains types. Utilisez un observateur.
• Mélanger les options. entryTypes ne se combine ni avec type ni avec buffered, et buffered ne fonctionne qu'avec type. Pour mettre plusieurs types en tampon, créez un observateur par type.
• Ignorer les limites des tampons. Sur une page chargée, les dernières entrées de ressources peuvent manquer sans avertissement.
• Prendre une visite pour la vérité. La chronologie décrit un utilisateur, un appareil, un réseau. Agrégez de nombreuses visites.
• Croire qu'elle alimente seule votre supervision. Le navigateur ne fait qu'enregistrer. Envoyer, stocker et alerter reste à votre charge.

Performance Timeline, tests et surveillance

La chronologie fournit leurs données brutes à la surveillance des utilisateurs réels, y compris les signaux derrière les Core Web Vitals. Elle montre ce que les visiteurs ont vécu, pas ce qui se passe quand personne ne visite le site. La surveillance de la vitesse de page de LoadFocus la complète avec des audits Lighthouse planifiés depuis des régions cloud, un historique et des alertes. Pour une mise en place pas à pas, lisez comment surveiller les Core Web Vitals avec alertes et rapports.

Questions fréquentes

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

La chronologie est le journal ordonné des entrées et les règles pour le lire et l'observer. La Performance API est l'ensemble plus large d'interfaces qui produisent des entrées, comme la navigation, les ressources et User Timing.

Faut-il utiliser getEntries() ou PerformanceObserver ?

Privilégiez PerformanceObserver. Il est notifié à l'arrivée des entrées et, avec type et buffered, renvoie aussi les précédentes. getEntries() est un instantané et ne peut pas renvoyer certains types.

Pourquoi des entrées manquent-elles sur une page chargée ?

Les tampons ont une taille maximale, par exemple 250 pour les entrées de ressources. Une fois pleins, les nouvelles entrées sont abandonnées. Augmentez la limite ou videz le tampon après avoir enregistré ce dont vous avez besoin.

La Performance Timeline fonctionne-t-elle dans les web workers ?

Oui. Les interfaces sont aussi disponibles dans les workers, mais la liste des types d'entrées pris en charge y est généralement plus courte.