¿Qué es la Web Performance API?

¿Qué es la Web Performance API?

La Web Performance API, normalmente llamada Performance API, es un conjunto de estándares del navegador para medir el rendimiento de una página web. Registra tiempos de navegación, recursos, renderizado y tareas largas en una línea de tiempo de alta precisión, permite añadir marcas y mediciones propias y funciona en páginas y en workers, así que puedes enviar a tu analítica datos de usuarios reales.

Cómo funciona

Cada métrica es un PerformanceEntry con name, startTime, duration y entryType. El navegador registra la mayoría de las entradas automáticamente. Puedes leerlas con performance.getEntries(), pero lo mejor es un PerformanceObserver, que te avisa cuando se registran entradas nuevas. Estos mismos datos alimentan la Performance Timeline que muestran las herramientas para desarrolladores.

Los tipos de entrada más usados

• Navigation timing: una entrada para el documento actual, con redirectCount, domInteractive, domComplete, loadEventEnd y un type de navigate, reload o back_forward.
• Resource timing: tiempos de red de cada imagen, script, hoja de estilos y llamada fetch, con initiatorType, transferSize, responseStatus y nextHopProtocol.
• Paint, LCP y cambios de diseño: entradas de paint timing, Largest Contentful Paint y layout shift, la materia prima de las Core Web Vitals.
• Event timing y tareas largas: latencia de eventos (la base de Interaction to Next Paint) y tareas que bloquean el hilo principal.
• Marks y measures: tus propias marcas y el tiempo entre ellas, útiles para pasos como "inicio del pago" hasta "pago renderizado".

Ejemplo

Este fragmento registra cada recurso al cargarse, lee la entrada de navegación y mide un paso propio:

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

Ten en cuenta que buffered: true funciona con type (un tipo de entrada por llamada), no con entryTypes. También entrega las entradas registradas antes de llamar a observe().

Errores comunes

• Leer tiempos de otro origen y obtener ceros. En recursos de otro origen, campos como domainLookupStart, connectStart y requestStart devuelven 0 salvo que ese servidor envíe la cabecera Timing-Allow-Origin.
• Mezclar entryTypes con buffered. Usa type cuando necesites entradas en búfer, con un observer por tipo.
• Observar demasiado tarde. Los observers registrados después de la carga pierden las entradas anteriores si no pides las almacenadas en búfer.
• Fiarse de una sola visita. La API mide a un usuario, con un dispositivo y una red. Agrega muchas visitas y mira percentiles, no un único valor.
• Pensar que un transferSize de 0 es un error. Indica un acierto de caché local.

Performance API, monitorización de usuarios reales y pruebas sintéticas

La Performance API es de donde la monitorización de usuarios reales obtiene sus datos: se ejecuta en el navegador de tus visitantes y muestra lo que vivieron de verdad. La monitorización sintética hace lo contrario: una prueba con script carga la página de forma programada desde una ubicación conocida, de modo que los resultados son comparables entre ejecuciones. Conviene tener ambas. La monitorización de velocidad de página de LoadFocus ejecuta auditorías Lighthouse programadas desde regiones en la nube y guarda el historial, y el verificador gratuito de Core Web Vitals da una lectura rápida de cualquier URL. Para una configuración paso a paso, consulta la guía monitorizar Core Web Vitals con alertas e informes (en inglés). La API también está disponible en un web worker, así que se puede medir el trabajo fuera del hilo principal.

Preguntas frecuentes

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

La Performance API es el conjunto de interfaces y métodos que llamas desde JavaScript. La performance timeline es el registro ordenado de entradas que guarda el navegador, que la API lee y que muestran las herramientas para desarrolladores.

¿Debo usar getEntries() o PerformanceObserver?

Mejor PerformanceObserver. Te avisa cuando se registran entradas, así que no tienes que consultar de forma repetida, y con la opción type y buffered en true también devuelve entradas anteriores.

¿Por qué algunos tiempos valen 0 en recursos de terceros?

En recursos de otro origen, el navegador oculta tiempos detallados como la resolución DNS y el inicio de la conexión. El servidor que aloja el recurso debe enviar una cabecera Timing-Allow-Origin para exponerlos.

¿Sustituye la Performance API a una herramienta de monitorización?

No. Recoge mediciones en el navegador, pero sigues necesitando un lugar donde almacenarlas, agregarlas y crear alertas. Combínala con comprobaciones sintéticas programadas para detectar problemas también cuando nadie visita la página.