¿Qué es la API de Performance Timeline?

¿Qué es la API de Performance Timeline?

La Performance Timeline es el registro ordenado de entradas de rendimiento de una página en el navegador: navegación, recursos, pintado, cambios de diseño, sus propias marcas y más. La especificación del W3C define cómo se almacenan, leen y observan las entradas mediante getEntries(), getEntriesByType(), getEntriesByName() y PerformanceObserver. Otras API de tiempos escriben sus entradas en ella.

Cómo funciona

Cada objeto global, es decir, cada página o worker, mantiene un búfer de entradas por tipo. Cada entrada es un PerformanceEntry con name, entryType, startTime y duration. Hay dos formas de leerlas:

• Instantánea: getEntries() devuelve lo que hay ahora en la línea de tiempo, ordenado por startTime, y getEntriesByType() y getEntriesByName() lo filtran. Nunca avisa de entradas nuevas y, si lo llama dos veces, devuelve las mismas entradas otra vez. Algunos tipos, como layout shift, largest contentful paint, event y long task, nunca los devuelve.
• Observador: un PerformanceObserver le avisa a medida que se registran entradas. MDN lo considera la forma preferida. Con type y buffered: true también recibe las entradas registradas antes de empezar a observar.

La línea de tiempo es la capa común. La API de rendimiento web es la familia más amplia de interfaces que la llenan, como Navigation Timing y User Timing. Para los tiempos del servidor, vea la API Server-Timing.

Tipos de entrada y límites de los búferes

MDN lista estos tipos: element, event, first-input, largest-contentful-paint, layout-shift, longtask, mark, measure, navigation, paint, resource y visibility-state. El soporte varía según el navegador, así que consulte PerformanceObserver.supportedEntryTypes antes de observar. En los workers la lista suele ser más corta.

Los búferes son finitos. MDN indica estos límites por objeto global: 250 para resource (ajustable), 200 para longtask, 150 para cada uno de element, event, layout-shift y largest-contentful-paint, 50 para visibility-state, 2 para paint, 1 para first-input y sin límite para mark, measure y navigation. Cuando un búfer se llena, las entradas nuevas no se guardan y sube un contador de entradas descartadas, que el observador recibe como droppedEntriesCount.

Ejemplo

// 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");

Una página con muchas imágenes y scripts puede superar las 250 entradas de recursos. Suba el límite con performance.setResourceTimingBufferSize(), o guarde y vacíe las entradas con clearResourceTimings() cuando se dispare el evento resourcetimingbufferfull.

Errores comunes

• Consultar getEntries() en bucle. Vuelve a leer entradas antiguas y aun así se pierde algunos tipos. Use un observador.
• Mezclar opciones. entryTypes no se puede combinar con type ni con buffered, y buffered solo funciona con type. Para varios tipos con búfer, cree un observador por tipo.
• Ignorar los límites de los búferes. En una página muy cargada pueden faltar, sin aviso, las últimas entradas de recursos.
• Tomar una visita por la verdad. La línea de tiempo describe a un usuario, un dispositivo y una red. Agregue muchas visitas.
• Suponer que alimenta su monitorización por sí sola. El navegador solo registra. Usted debe enviar, almacenar y crear alertas con los datos.

Performance Timeline, pruebas y monitorización

De la línea de tiempo obtiene sus datos en bruto la monitorización de usuarios reales, incluidas las señales de las Core Web Vitals. Muestra lo que vivieron los visitantes, pero no lo que ocurre cuando nadie visita la página. La monitorización de velocidad de página de LoadFocus la complementa con auditorías Lighthouse programadas desde regiones en la nube, historial y alertas. Para una guía paso a paso, lea cómo monitorizar Core Web Vitals con alertas e informes.

Preguntas frecuentes

¿Qué diferencia hay entre la Performance Timeline y la Performance API?

La línea de tiempo es el registro ordenado de entradas y las reglas para leerlo y observarlo. La Performance API es el conjunto más amplio de interfaces que generan entradas, como navegación, recursos y User Timing.

¿Debo usar getEntries() o PerformanceObserver?

Prefiera PerformanceObserver. Avisa cuando llegan las entradas y, con type y buffered, también devuelve las anteriores. getEntries() es una instantánea y no puede devolver algunos tipos.

¿Por qué faltan entradas en una página muy cargada?

Los búferes tienen un tamaño máximo, por ejemplo 250 para las entradas de recursos. Una vez llenos, las entradas nuevas se descartan. Suba el límite o vacíe el búfer después de guardar lo que necesite.

¿Funciona la Performance Timeline en web workers?

Sí. Las interfaces también están disponibles en los workers, aunque la lista de tipos de entrada admitidos suele ser más corta.