¿Qué es la API User Timing?

¿Qué es la API User Timing?

La API User Timing forma parte de la Web Performance API. Permite que su propio JavaScript ponga marcas de tiempo con nombre (marks) y el tiempo entre ellas (measures) en la línea de tiempo de rendimiento de alta resolución del navegador, para medir pasos que solo su app conoce, como "resultados de búsqueda renderizados" o "formulario de pago listo".

Cómo funciona

• performance.mark(name) crea un PerformanceMark (tipo de entrada mark) en el momento actual. Opciones: startTime y detail.
• performance.measure(name, startMark, endMark) crea un PerformanceMeasure (tipo measure). Su duration es el final menos el inicio. También acepta un objeto de opciones con start, end, duration y detail. Sin final, termina ahora.
• Las entradas se leen con un PerformanceObserver, la vía preferida según MDN, o con performance.getEntriesByType('measure'). Se eliminan con clearMarks() y clearMeasures().

En el panel Performance de Chrome DevTools, una marca cuyo detail lleva un objeto devtools con dataType: 'marker' aparece en la pista Timings, y los measures con dataType: 'track-entry' dibujan pistas propias (active "Show custom tracks" en los ajustes de captura). La compatibilidad con esta extensión varía según el navegador. Detalles: MDN.

Ejemplo

Mida cuánto tarda una búsqueda desde la petición hasta los resultados renderizados:

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

El resultado es una entrada search-total con una duración en milisegundos, visible en el código y en las herramientas de desarrollo.

User Timing junto a sus APIs vecinas

Navigation Timing cubre las fases integradas de la carga de página y la cabecera Server-Timing aporta tiempos del backend. User Timing es para los pasos intermedios que solo su código puede nombrar. Si envía las mediciones a su analítica, tiene monitorización de usuarios reales de sus propios flujos. Para la carga de página y las Core Web Vitals desde ubicaciones fijas, consulte la monitorización de velocidad de LoadFocus. Una visión más amplia está en la guía de pruebas de rendimiento frontend.

Errores comunes

• Medir antes de que exista la marca final. Una marca con nombre inexistente lanza un SyntaxError.
• Mezclar las formas de opciones. duration solo vale con exactamente uno de start o end; si no, TypeError.
• Reutilizar un nombre para pasos distintos. getEntriesByName() devuelve entonces varias entradas, así que nombre cada paso con claridad.
• No limpiar nunca las entradas en una SPA de larga vida. Elimine las marcas y mediciones ya enviadas.
• Marcar dentro de bucles ajustados. Inunda la línea de tiempo y oculta los pasos importantes.

Preguntas frecuentes: API User Timing

¿Qué diferencia hay entre mark y measure?

Un mark es un punto en el tiempo con nombre. Un measure es la duración entre dos puntos, que pueden ser dos marks, marcas de tiempo o uno de cada.

¿Necesito un PerformanceObserver?

No, pero es mejor opción porque avisa cuando se crean entradas. Los métodos get solo devuelven las que ya existen.

¿Cómo veo marks y measures en DevTools?

Grabe un perfil en el panel Performance. Con un objeto devtools en detail, los marcadores van a la pista Timings y los measures a pistas propias.

¿Es lo mismo que performance.now()?

No. performance.now() devuelve una marca de tiempo. User Timing registra entradas con nombre en la línea de tiempo que herramientas y observadores pueden leer.

¿Funciona en Web Workers?

Sí, MDN indica que performance.measure() está disponible en workers.