Concepts

Here's a list of concepts that you should be familiar with before you start using Surfmeter.

Clients

We call the Surfmeter instances that produce measurements “clients”. Each client is identified by a unique ID. It can additionally be assigned a label and tags.

Measurements vs. Studies

When you use Surfmeter, you will be working with three different types of entities: measurements, studies, and study chains. These are the main concepts that you should be familiar with.

• A measurement is the actual measurement of a service.
• A study can be a collection of measurements.
• A study chain can be a collection of studies.

This diagram visualizes the above concepts:

erDiagram
    StudyChain one--many Study : has
    Study one--many Measurement : has
    StudyChain {
        array study_ids
    }
    Study {
        object description
    }
    Measurement {

    }

In practice, this means that you could define a study to run or produce multiple measurements. For instance, a study might be a study of the top 20 websites, and each measurement would be the loading of one of those websites. And when automating studies, you can run them in a chain that runs multiple studies in parallel (or sequentially).

In other words, when you will later define the configuration, you will always specify the study, and the study will then (sometimes implicitly) define the measurements that are part of it. When you then go to automate those studies, you can choose to run some of them in parallel, like an upload and a download study — that would be a study chain.

Measurement Types

We differentiate between the following major types of measurements:

• Web: Measure the quality of a website through the browser or special tools (like Google Lighthouse)
• Video: Measure the quality of a video service through the browser
• Speedtest: Measure the quality of a network connection through a speedtest website
• Network: Measure the quality of a network connection through various native tools
• Conferencing: Measure the quality of a conferencing service through the browser

For each measurement type, we allow you to define:

1. what it is that you want to measure (e.g., the video URL, a list of hosts), and
2. how to measure it (e.g., using the browser extension, using a native tool, etc.)

The what is defined by certain parameters (params) inside the Study description. The how is defined by the technology (which is also called subject in our configuration) which is also part of the Study description. Just remember, since the Study creates the measurements, you have to make these definitions in the Study description.

For video, the technology is usually always the same: we open a browser and play the video. For web, we can load a site through the browser or use Google Lighthouse to do it for us. For network tests however, we can use different native technologies, such as ping, dig, etc., which are installed on your local host.

To learn more about which types of measurements are possible, the technologies that are available, and how to define them, go through the Automator documentation, which includes a chapter on the configuration.

For the mobile SDKs, these concepts are very similar; the only difference is that the configuration is done programmatically in the app.

Measurement Results

Each measurement produces a result, which is a JSON object that contains the actual data that you can see in the dashboards. The result is stored in the database, and you can also download it from our API.

In particular, the measurement will always contain metadata to identify the measurement, such as the study, the measurement type, the technology, the time when the measurement was started, etc. It will also contain the actual data that was measured, such as the loading time of a website, the download speed of a video, etc. Here, we differentiate between two types of results:

• Statistic Values: These are the actual values that were measured, such as the loading time of a website, the QoE score a video, etc. These values are always stored as a particular type (e.g., a number), and they are always in the same unit (e.g., milliseconds, megabits per second, etc.). More information can be found in our statistic values reference.
• Client Reports: These are complex objects that are specific to the technology that was used to measure the data. For instance, for web measurements, we might use Google Lighthouse, which produces a report that contains a lot of information about the website. For video measurements, we might extract detailed logs from the particular player (e.g., YouTube) that you can later use to analyze the video quality. For network measurements, we store the detailed results of command-line tools such as ping, dig, etc. These Client Reports allow you to analyze the data in more detail. More information can be found in our Client Reports reference.

---

Now we're done with the most important concepts. To understand more about the underlying architecture of our measurement system, read on.