Skip to content

sumup-oss/signal

Repository files navigation

Signal

Stars Coverage License Contributor Covenant

Collect and send page performance metrics with ease

Table of contents

What is it

Signal is a script that collects specific page performance events and sends them to a configurable service url.

Installation

At the moment Signal is distributed as a script. Meaning you have to build your own version and embed it in your web page. In order to build your version of it, follow these steps:

Clone the repo using SSH

git clone git@github.com:sumup-oss/signal.git

Or using https

git clone https://github.com/sumup-oss/signal.git

Run

yarn

Copy the .env.example to .env:

cp .env.example .env

The .env file contains the following values:

SERVICE_URL=""
APPLICATION_NAME=""
PERFORMANCE_OBSERVER_METRICS=""

Service url (mandatory)

The url where events will be send to

Application name (optional)

This is app's identifier and is useful when you have more than one application which is sending events

Performance observer metrics (optional)

You can configure which metrics supported by PerformanceObserver you want to track by specifying them in comma-separated list.

Please keep in mind that these 6 metrics are included by default:

  • first-paint
  • first-contentful-paint
  • largest-contentful-paint
  • first-input-delay
  • cumulative-layout-shift
  • time-to-first-byte

In the example below custom user metrics are enabled additionally to the default FCP and FID metrics -

PERFORMANCE_OBSERVER_METRICS="first-paint,first-contentful-paint,first-input-delay,user-timing"

Usage

Now you are ready to build the script. If you want to customize the events, please refer to Customization.

In order to generate the script, run

yarn build

Copy the output from build/perf.js

pbcopy < build/perf.js

Add the script to the <head> tag of your html file. This is required due to how you collect the time-to-interactive metric.

Events

Here's the full list of events that this script supports out of the box.

The events are provided by both the PerformanceObserver and PerformanceTiming APIs.

Via PerformanceObserver

Via PerformanceTiming

More detailed documentation about each metric, how they relate to each other and how they should be used can be found in Confluence - https://sumupteam.atlassian.net/wiki/spaces/DEV/pages/1431569763/Tracking+Performance.

Keep in mind each API has a different browser support. Please refer to Browser compatibility section for more info on it.

Event dispatch

All events are transported using the Navigator.sendBeacon api.

The events from the PerformanceObserver API (first-paint, first-contentful-paint and time-to-interactive) are dispatched individually and as soon as they are available, to avoid losing the data.

The events from the PerformanceTiming API (dom-interactive, dom-content-loaded, dom-loading, dom-complete) are batched into a single request and are dispatched after the onload event. This is due since we have to wait for some properties after the onload event anyways.

Event enhancing

By default each event is enhanced with the following metadata:

{
  event_name,
    user_agent,
    google_analytics_client_id,
    connection_type,
    effective_connection_type,
    url,
    timestamp,
    application;
}

Please refer to Customization for more information on how to add/remove properties and events

Customization

You can customize both Events and Metadata fields.

Customizing Events

You can edit both PerformanceObserver and PerformanceTiming handlers. All you have to do is edit the perf.ts file.

Customizing Metadata fields

You'll have to edit two files:

Browser compatibility

The script is powered by three APIs:

If sendBeacon isn't available, the script won't be executed. There isn't a fallback with XHR due to the blocking nature of it.

Since each type of event has a different browser support, please refer to the table to understand which events you can support. The majority of the PerformanceObserver APIs that are required to get metric values, are only available in Chromium-based browsers (e.g. Google Chrome, Microsoft Edge, Opera, Brave, Samsung Internet, etc.).:

Event Browser
first-paint Chromium
first-contentful-paint Chromium
largest-contentful-paint Chromium
first-input-delay Chromium
cumulative-layout-shift Chromium
time-to-first-byte Chromium, Firefox
time-to-interactive Chromium
user-timing Chromium, Firefox
element-timing Chromium
resource-timing Chromium, Firefox
navigation-timing Chromium, Firefox
dom-interactive Every major browser
dom-content-loaded Every major browser
dom-loading Every major browser
dom-complete Every major browser

Code of conduct

We want to foster an inclusive and friendly community around our Open Source efforts. Like all SumUp Open Source projects, this project follows the Contributor Covenant Code of Conduct. Please, read it and follow it.

If you feel another member of the community violated our CoC or you are experiencing problems participating in our community because of another individual's behavior, please get in touch with our maintainers. We will enforce the CoC.

Maintainers

About SumUp

SumUp logo

SumUp is a mobile-point of sale provider. It is our mission to make easy and fast card payments a reality across the entire world. You can pay with SumUp in more than 30 countries, already. Our engineers work in Berlin, Cologne, Sofia, and Sāo Paulo. They write code in JavaScript, Swift, Ruby, Go, Java, Erlang, Elixir, and more.

Want to come work with us? Head to our careers page to find out more.

About

Collect and send page performance metrics with ease

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published