Measuring performance with


In this tutorial, I will introduce you to an amazing performance tool I have come across:

The official website describes the tool as “the complete toolbox to test the web performance of your website.” What makes the tool even greater? Yep, you’ve guessed it; it is also open source. gathers some popular performance tools in one place to get a clear picture of the state of your site in a matter of seconds! This tutorial will help you get your environment up and running using Docker.

Downloading docker image

For this tutorial, we will be using docker to set everything up. If you do not have docker installed yet, you can do so from here.

As soon as you have docker up and running, we need to download the official image. To do this, you must execute the following in your terminal:

docker pull sitespeedio/

Once this is done, we can double check that everything installed successfully by executing the following command:

docker images

If the image is listed, then the docker image was downloaded successfully.

Our first performance test

With the image successfully downloaded we can run our first basic performance test.

In the terminal, execute the following command:

docker run --shm-size=1g --rm -v "$(pwd)":/ sitespeedio/ -b chrome https://<website>

Don’t forget to replace <website> to any site of your choice (it can also be localhost), and in a matter of seconds, will generate a report on your site’s performance against google chrome.

The report is stored in a directory which is created in the same place you executed your command from. Find the index.html file and load it into your favourite browser.

Voila, this is just a summary of your score. Let us navigate throughout the report in a little more detail, shall we?

As you may have noticed, sitespeedio accepts some different options depending on your preferences. These are probably the most popular:

  1. Browser: -b [chrome,firefox] (default: chrome)
  2. Iterations: -n (how many times you want to test each page, default: 3)
  3. Connectivity: -c [“3g”, “3gfast”, “3gslow”, “3gem”, “2g”, “cable”, “native”, “custom”] (default: native)
  4. Crawler: -d (How deep to crawl (1=only one page, 2=include links from the first page, etc.) default: 1)
  5. Mobile agent: –mobile (Set UA and width/height. For Chrome it will use device Apple iPhone 6.)

So let’s say you want to run your test on a chrome browser, using a mobile agent, with the crawler going through the links of the first page, one iteration and a 3g connectivity you would execute the following command:

docker run --shm-size=1g --rm -v "$(pwd)":/ sitespeedio/ -b chrome --mobile -d 2 -n 1 -c 3g https://<website>

Integrating more tools

As mentioned before, sitespeedio also integrates with other services to give you a clearer picture of your site’s performance.


Let’s start off with WebPageTest. This comes out of the box, so it is fairly simple to integrate. Before you try this out, you would need a WebPageTest API key.

Once you have that in hand, execute the following command:

docker run --shm-size=1g --rm -v "$(pwd)":/ sitespeedio/ -b chrome --mobile -d 1 -n 1 -c 3g --webpagetest.key <API> --webpagetest.runs 1 https://<website>


Next up is google page insight. This is a bit more tricky to integrate, but the step by step guide below should make it a simple process.

  1. Like WebPageTest you also need an API key to use GPSI
  2. In the same directory we have been working on till now need to install the plugin by cloning the following repo:
  3. Now we need to execute the following command within the plugin-gpsi directory:
    npm install
  4. Once that is done we need to make some changes to our sitespeedio command, so we need to add the following options:
    1. –plugins.add “/”
    2. –gpsi.key “<yourKey>”

The resulting command is the following:

docker run --shm-size=1g --rm -v "$(pwd)":/ sitespeedio/ -b chrome --mobile -d 1 -n 1 -c 3g --webpagetest.key --webpagetest.runs 1 --plugins.add "/" --gpsi.key "<yourKey>" https://<website>

Organising your command using a config file

With more options you add, the more your command is going to grow(and get super untidy), to keep everything tidy we can use a JSON config file.

Moreover, the command will now look like the following:

docker run --shm-size=1g --rm -v "$(pwd)":/ sitespeedio/ --config config.json http://<website>

Continuous monitoring using Grafana & Graphite

Why go through all this trouble to check your site’s performance once? Why not continuously monitor the performance so you could compare how your site is performing over time? The guys at sitespeedio made this super easy using Grafana and Graphite. To set this up, we will be using docker compose.

Next, we need to build our new docker-compose file with the following command:

docker-compose up -d

This command should install all images in the docker-compose file, and also boot them up.

We now need to edit our config.json and add the graphite host:

We can now run our test:

docker-compose run --rm --config config.json http://<website>

Go to:, and you can see your results 🙂

You can also set this up with Jenkins, and run the test on a scheduled basis. Amazing right?

Github Repo.

That’s it for today, as usual, if you have any questions or comments, you can use the comment section below.

P.S. We are looking for guest authors, interested? Contact us.

7 thoughts on “Measuring performance with”

  1. The docker-compose.yml file gives error:

    ERROR: yaml.scanner.ScannerError: while scanning a simple key
    in “.\docker-compose.yml”, line 37, column 1
    could not find expected ‘:’
    in “.\docker-compose.yml”, line 38, column 9

    Could you please look into it?

  2. Hi,

    I’m unable to run the test with the GPSI as after configuring with your steps I’m getting this error
    Couldn’t load plugin / Error: Cannot find module ‘/usr/src/app/lib/plugins/’
    Require stack:
    – /usr/src/app/lib/core/pluginLoader.js
    – /usr/src/app/lib/sitespeed.js
    – /usr/src/app/bin/sitespeed.js
    and I’m not sure how to solve it, would really appreaciate any help on this matter


    1. Hi Bart,

      The problem is that you are running the command within the gpsi repo that you cloned 🙂

      Just “cd ..” and run the command again, and it should work.


  3. When I run your latest addition with docker-compose I’m getting an error saying
    “Invalid JSON config file: config.json”

    Any ideas here?

    docker-compose version 1.25.4, build 8d51620a

      1. Hi Eugene,

        The problem has been solved by adding an extra line in the docker-compose.yml file 🙂

        Please try again

Leave a Reply

Your email address will not be published. Required fields are marked *

one × 1 =