Perfectum Client

Library for measuring client performance metrics :rocket:

Features

• Using the latest APIs for better performance measurement :dart:
• Measure only user-centric performance metrics :man:
• Minimal impact on application performance :zap:
• Small library size (< 3Kb gzip) :fire:

Built With

• Beacon API
• Performance API
• PerformanceObserver API

Collected Metrics

• First Paint Time
• First Contentful Paint Time
• Largest Contentful Paint Time
• Cumulative Layout Shift
• First Input Delay Duration
• First Input Delay Start Time
• First Input Delay Event Name
• Total Long Tasks
• First Long Task Start Time
• First Long Task Duration
• Domain Lookup Time
• Server Connection Time
• Server Response Time
• Download Document Time
• Network Information
• Device Information
• Custom Metrics

Installation

yarn add @perfectum/client

Usage

import Perfectum from '@perfectum/client';

Perfectum.init({
  sendMetricsUrl: 'http://example.com/metrics',
  sendMetricsData: {
      app: 'example',
      env: 'production'
  },
  sendMetricsCallback: (metrics) => {
    const data = JSON.stringify(metrics);

    window.navigator.sendBeacon('http://example.com/metrics', data);
  },
  maxPaintTime: 15000
});

By default, before the user closes the page (unload event), the Perfectum will send an object with the collected metrics to the address specified in the sendMetricsUrl property.

If you need to add data to the resulting object with collected metrics, for example, the name of the application or the type of environment, you can specify the object with additional data in the sendMetricsData property.

If you want to implement your own logic for sending the collected metrics, you can specify a callback in the sendMetricsCallback property that will be called before the user closes the page (unload event). When calling a callback, an object with collected metrics will be passed as an argument.

If you want to filter paint performance metrics such as First Paint, First Contentful Paint, Largest Contentful Paint, you can set the maxPaintTime property(in milliseconds). By default, it is set to 60 seconds.

Custom Metrics

Custom metrics are the ability to measure the performance of individual elements on a page or the operations performed in your project. These metrics are necessary to provide the most accurate picture of how users perceive the performance of your application. There are two approaches to measuring custom metrics:

Measurement at the initialization stage of the application

At this stage, we may need to measure the time of appearance of the most important page elements on the user's screen, such as a hero image, cta button, lead form etc. For this type of measurement, you need to add the elementtiming attribute to the HTML element whose performance or time of appearance on the page you would like to measure.

<h1 elementtiming="metric-name">Example App</h1>

Measurement at the stage of interaction with the application

At this stage, we may need to measure the performance of the priority task, the time spent on an important request, or the rendering of specific page components. For this type of measurement, you need to use the special interface provided in the form of two static methods, startMeasure and stopMeasure.

import Perfectum from '@perfectum/client';

Perfectum.startMeasure('metric-name');

someKindOfImportantTask();

Perfectum.stopMeasure('metric-name');