page-timing

⏱ Collect and measure browser performance metrics

All metrics are converted to snake_case

import { navigation, paint } from 'page-timing';

(async () => {
    const results = await Promise.all([
        paint(),
        navigation()
    ]);

    const metrics = Object.assign(...results);

    fetch('/browser-performance-metrics', {
        method: 'POST',
        body: JSON.stringify({
            page_name: 'my page',
            metrics
        }),
    });
})();

API endpoints

• navigation: Navigation Timing Illustration 🎨
• paint: Paint Timing
• assets: Information about page resources when this function is called
• connection: Network Information
• memory: Memory API information
• display: Screen and document information
• dom: Calculated metrics from the document object
• elapsed: Time when the measurements were taken
• all: A compound object containing all of the above
• measure: A helper function: Add measure entries to navigation timing API

Metrics

More functions

fps

Measure page frame rate at a certain point in time

import { fps } from 'page-timing';

const frames_per_second = await fps();
console.log({ frames_per_second });

Increase sample rate by checking more than one second. (Result is still in frames per second)

const frames_per_second = await fps({ sample: 5 });
console.log({ frames_per_second });

measure

Wrap a function and measure it's execution time in milliseconds into a performance measure entry.

import { measure } from 'page-timing';

async function myFunction(
    await wait(50);
    doSomethingElse();
}

await measure(myFunction, 'my-function');

// Example: Convert entries to a named array
Object.assign(
    ...performance.getEntriesByType('measure').map(
        ({ name, duration }) => ({[name]: duration})
    )
);
// {my-function: 53.35999990347773}

// Example: Retrieve a specific entry
const { duration } = performance.getEntriesByName('my-function');
// 53.35999990347773

Illustration of navigation events

Bonus

A simple example to add web vitals and TTI

npm i page-timing web-vitals tti-polyfill

import { all, connection } from 'page-timing';
import { getLCP, getFID, getCLS } from 'web-vitals';
import TTI from 'tti-polyfill';

(async () => {
    const connectionInfo = await connection();

    // Send metrics from browser performance API
    send(await all());

    // Send web vitals to the same endpoint
    [
        [getLCP, 'largest_contentful_paint'],
        [getFID, 'first_input_delay'],
        [getCLS, 'cumulative_layout_shift'],
    ].forEach(
        ([ fn, name ]) => fn(
            ({ value }) => send({
                [name]: value,
                ...connectionInfo // Some connection info
            })
        )
    );

    TTI.getFirstConsistentlyInteractive().then(
        (time_to_interactive) => send({
            time_to_interactive,
            ...connectionInfo // Some connection info
        })
    ).catch(() => null)
})();

const send = metrics => fetch('/browser-performance-metrics', {
  method: 'POST',
  body: JSON.stringify({ page_name: 'my page', metrics }),
});

3.1.5

Fixes

Prevent breakage in older browsers that do not support 'navigation' entry type

3.1.4

Fixes

Return an empty object when 'paint' entries are not supported

3.1.3

Fixes

Fix failure to execute 'observe' on 'PerformanceObserver' and entryType in not accepted by browser.

3.1.1

Fixes

Add some backwards compatibility for older browsers

3.1.0

Feature

Add redirect_count to navigation metrics

3.0.1

Fixes

Null check for requestAnimationFrame

Escape execution for "fps" after requestAnimationFrame null check has failed

3.0.0

Breaking changes

Move to async interface

All functions have transformed to async functions.

By utilising PerformanceObserver, async interface allows to decouple from waiting for onload event. User can include an async file and not worry about loading time.

Here are migration examples:

Before

const metrics = navigation();

After

const metrics = await navigation();

Before

send(all());

After

No need to wait for window load

all().then(send).catch(console.error);

Before

const metrics = { ...paint(), ...navigation() };

After

const metrics = Object.assign.apply(null, await Promise.all([ paint(), navigation() ]));

2.2.1

Fixes

Verify page_time_elapsed

Should not send null value. The rest of the library sends undefined when no value is available so it gets dropped in JSON stringification.

2.2.0

New features

Add navigation metrics

• duration: Difference between responseEnd and startTime
• worker_start: Time until service worker ran

Add connection type

• navigation_type: navigate, reload, back_forward, prerender

2.1.1

Fixes

Verify numbers are safe

Use max safe integer if result is higher

2.1.0

New features

Add time elapsed

Time elapsed allows us to have a relative point of comparison between the different measuring.

• page_time_elapsed: milliseconds elapsed since the time origin

2.0.1

Fixes

Support for internet explorer Number functions (fallback from Number object to global functions)

2.0.0

Breaking changes

New interface

Completely new interface. Instead of a callback, expose functions that return structured data. It's different