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

| Name | Meaning | Group | Type | - | - | - | - | navigation_start | Termination of previous document upon navigating | navigation | number | unload_event_start | Previous document unload | navigation | number | unload_event_end | | navigation | number | redirect_count | Numbers of redirects while requesting this page | navigation | number | redirect_start | Redirect from previous document | navigation | number | redirect_end | | navigation | number | fetch_start | Ready to fetch the document | navigation | number | domain_lookup_start | | navigation | number | domain_lookup_end | | navigation | number | duration | Difference between responseEnd and startTime | navigation | number | connect_start | Sent request to open a connection | navigation | number | connect_end | | navigation | number | secure_connection_start | Secure connection handshake | navigation | number | request_start | Request the document | navigation | number | response_start | Received the first byte of the response | navigation | number | response_end | Received the last byte of the response | navigation | number | dom_loading | Parser started work | navigation | number | dom_interactive | Parser finished work on main document. Changed document readyState to "interactive" | navigation | number | dom_content_loaded_event_start | Executed required scripts after parsing the document | navigation | number | dom_content_loaded_event_end | | navigation | number | dom_complete | Changed document readyState to "complete" | navigation | number | load_event_start | All assets are loaded. Document fires "load" event | navigation | number | load_event_end | Document finished executing "load" event listeners | navigation | number | transfer_size | Size (octets) of response headers and payload body | navigation | number | encoded_body_size | Size (octets) of payload body | navigation | number | decoded_body_size | Size (octets) of message body | navigation | number | worker_start | Time until service worker ran | navigation | number | first_paint | User agent first rendered after navigation | paint | number | first_contentful_paint | Document contains at least one element that is paintable and contentful † | paint | number | first_image_paint | TBD | paint | number | final_asset_javascript_count | Total number of Javascript resources | assets | number | final_asset_javascript_load | Loading time spent on Javascript resources | assets | number | final_asset_javascript_size | Total size of Javascript resources | assets | number | final_asset_stylesheets_count | Total number of CSS resources | assets | number | final_asset_stylesheets_load | Loading time spent on CSS resources | assets | number | final_asset_stylesheets_size | Total size of CSS resources | assets | number | final_asset_images_count | Total number of image resources | assets | number | final_asset_images_load | Loading time spent on image resources | assets | number | final_asset_images_size | Total size of image resources | assets | number | final_asset_other_count | Total number of other resources | assets | number | final_asset_other_load | Loading time spent on other resources | assets | number | final_asset_other_size | Total size of other resources | assets | number | connection_type | bluetooth, cellular, ethernet, none, wifi, wimax, other, unknown | connection | string | effective_bandwidth | Mbps | connection | number | effective_connection_type | slow-2g, 2g, 3g, 4g | connection | string | effective_max_bandwidth | Mbps | connection | number | reduced_data_usage | Vendor's "Data Saver" feature enables | connection | boolean | round_trip_time | Estimated effective round-trip in ms | connection | number | navigation_type | navigate, reload, back_forward, prerender | connection | string | js_heap_size_limit | Maximum bytes available for JS heap | memory | number | total_js_heap_size | Total allocated bytes for JS heap | memory | number | used_js_heap_size | Currently active bytes of JS heap | memory | number | window_inner_height | Height of the window's layout viewport | display | number | window_inner_width | Width of the window's layout viewport | display | number | screen_color_depth | Color depth of the screen | display | number | screen_pixel_depth | Bit depth of the screen | display | number | screen_orientation_type | landscape-primary, landscape-secondary, portrait-primary, portrait-secondary | display | string | final_dom_node_count | Total number of nodes under the document object | dom | number | final_dom_nest_depth | Highest nesting depth of DOM element under the document | dom | number | final_html_size | Character count of the HTML document | dom | number | page_time_elapsed | milliseconds elapsed since the time origin | elapsed | number

† contentful element: A visible element which contains non empty text, media content or input.

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