Skip to content

Special Features

Automator supports a few special options and features.

Additional Browser Extensions

If you want to load additional browser extensions with the browser start, you first have to download the extension from the Chrome Web Store.

Use the download_crx.sh script, which is bundled with Automator, to download additional extensions. For instance, to download the uBlock Origin ad blocker:

./download_crx.sh cjpalhdlnbpafiamejdnhcphjbkeiagm \
    $HOME/surfmeter/extensions/ublockOrigin

You can then load this extension along with the Automator:

./surfmeter-automator-headless startStudy \
    --studyId STUDY_YOUTUBE \
    --additionalExtensions $HOME/surfmeter/extensions/ublockOrigin

Specify multiple extensions by repeating the --additionalExtensions flag.

Note that we cannot guarantee that all extensions will work properly with Automator. Please report any issues you encounter and we will try to fix them.

Environment Variables

When running the Surfmeter Automator executables, you can pass the following additional environment variables:

Variable Description
TMPDIR Override the path for temporary lockfiles
SURFMETER_AUTOMATOR_EXEC Set the path to the surfmeter-automator executable when using a different directory
HEADLESS_RESOLUTION Specify the X window resolution in the format <width>x<height>x<bitDepth>, defaults to 1920x1080x24. Note that this will not work if the X window daemon is running or if you are using the GUI version.
CONFIG_DIR Set the path to an alternative configuration directory
LOG_LEVEL Set the log level, e.g. LOG_LEVEL=debug to print additional messages. Available log levels are: error, warning, info (default), debug, trace, extreme
SURFMETER_CHROME_BINARY Set the default path to the Chrome (or Chromium) binary. Can be overridden with the --chromeBinary command-line option. Chrome-based studies only.
SURFMETER_CHROMEDRIVER_BINARY Set the default path to the ChromeDriver binary. Can be overridden with the --chromeDriverBinary command-line option. Chrome-based studies only.
CHROME_PATH Path to the Chrome binary used by Google Lighthouse's launcher for the Lighthouse web study. Set to the same binary as SURFMETER_CHROME_BINARY.
SURFMETER_DISPLAY Set the X display number that will be used for Simulated Headless mode, defaults to :123. This also applies to the Docker container and will change the internal Xvfb server display number.
SURFMETER_DISABLE_PULSEAUDIO Set to 1 to disable PulseAudio. This only works for the Docker version.
SURFMETER_AUTO_LOAD_SCHEDULE Set to 1 to automatically load the schedule when starting the Automator inside Docker. Has no effect for native deployments.
SURFMETER_AUTO_REGISTER Set to 1 to automatically register the Docker container with the server. Has no effect for native deployments.
SURFMETER_DEFAULT_REGISTRATION_KEY Set the default registration key to use when automatically registering with the server.
SURFMETER_ENABLE_VNC Set to 1 to enable VNC server automatically. Has no effect for native deployments.
SURFMETER_CRON_LOG Path to the named pipe (FIFO) used to forward cron output to container stdout in Docker. Set to empty to disable. See Logging. (default: /tmp/surfmeter-cron.log)
SURFMETER_DEEPLINK_LOAD_TIMEOUT Wait for how many seconds to detect Surfmeter Lab startup (default: 60)
SURFMETER_DEEPLINK_WAIT_TIMEOUT Wait for how many seconds to get deep link status (default: 60)

These are mainly useful for Docker deployments, but can also be used for native deployments.

The Chrome binary variables are usually set for you

On a native amd64 installation, the setup.sh script installs Chrome for Testing and writes SURFMETER_CHROME_BINARY, SURFMETER_CHROMEDRIVER_BINARY, and CHROME_PATH to your ~/.profile, so you normally do not set these by hand. Set them yourself only when you install the browser manually or keep it in a non-standard location. Automator resolves the browser in this order: the --chromeBinary / --chromeDriverBinary option, then the SURFMETER_CHROME_BINARY / SURFMETER_CHROMEDRIVER_BINARY environment variable, then the browser found on your PATH.

Overriding Options via Environment Variables

Any command-line option can also be set through an environment variable named SURFMETER_OPTIONS__<OPTION_NAME>, where <OPTION_NAME> is the option's name written in SCREAMING_SNAKE_CASE. This is useful when you want to force a setting per machine or per deployment without editing the (often synced) config file. For example, you can enable the GPU only on the probes that actually have a working one.

The environment variable is the highest-priority source: it wins over both command-line flags and any flags baked into a scheduled (cron) job. So an operator can override whatever the config or a typed flag would otherwise produce.

The option name is simply the camelCase CLI option converted to upper case with underscores between words:

  • --enableGpu becomes SURFMETER_OPTIONS__ENABLE_GPU
  • --studyTimeout becomes SURFMETER_OPTIONS__STUDY_TIMEOUT
  • --noLogNetworkRequests becomes SURFMETER_OPTIONS__NO_LOG_NETWORK_REQUESTS
  • --webRtcDumpDir becomes SURFMETER_OPTIONS__WEB_RTC_DUMP_DIR

Some examples:

# Turn the GPU on
SURFMETER_OPTIONS__ENABLE_GPU=1 ./surfmeter-automator-headless startStudy --studyId STUDY_YOUTUBE

# Raise the per-study timeout to 600 seconds
SURFMETER_OPTIONS__STUDY_TIMEOUT=600 ./surfmeter-automator-headless startStudy --studyId STUDY_YOUTUBE

# Do not log network requests
SURFMETER_OPTIONS__NO_LOG_NETWORK_REQUESTS=1 ./surfmeter-automator-headless startStudy --studyId STUDY_YOUTUBE

The value is interpreted according to the option's type:

  • Boolean options accept true, 1, yes, or on for on, and false, 0, no, or off for off (case-insensitive). An unrecognized value is ignored with a warning.
  • Number options accept any number, including negatives and decimals. An invalid value is ignored with a warning.
  • String options are taken as-is.

If the option name does not match any known option (for example due to a typo), the variable is ignored and a warning is logged.

Turning off a default-on behavior

Some behaviors are on by default and are turned off with an explicit no* option. For those, use the no* variant. For instance, network request logging is on by default; to turn it off, set SURFMETER_OPTIONS__NO_LOG_NETWORK_REQUESTS=1. The intuitive SURFMETER_OPTIONS__LOG_NETWORK_REQUESTS maps to the --logNetworkRequests option, which is deprecated and does nothing.

Array and Object Options

For array options such as --chromeArgs, a single value is taken as one array element, even if it contains commas. This is important because a Chrome feature flag may itself contain commas:

# A single Chrome argument, kept intact (commas are not split)
SURFMETER_OPTIONS__CHROME_ARGS='enable-features=NetworkService,NetworkServiceInProcess'

To pass more than one array element, use a JSON array:

SURFMETER_OPTIONS__CHROME_ARGS='["enable-features=NetworkService,NetworkServiceInProcess","disable-gpu"]'

For object options such as --metadata and --extraHeaders, pass a JSON string:

SURFMETER_OPTIONS__METADATA='{"site":"probe-042","lab":"vienna"}'

Using Overrides with Scheduled Jobs

For a scheduled (cron) job, the environment variable must be present in the environment where the job actually runs. You can achieve this in several ways:

  • Add an environment line to the top of the crontab.
  • Set the variable in the Docker container environment.
  • Set it in the schedule config via globalScheduleSettings.env or a per-entry env block. Automator writes these as a KEY=value prefix in front of the scheduled command, so the override applies to that job. See Scheduling Studies.

Custom Chrome Arguments

You can pass extra command-line arguments to the browser with the --chromeArgs option. This is mainly useful for enabling Chrome feature flags — for example the GPU rendering flags (see GPU Rendering).

Pass each argument without the leading --, and repeat the flag to pass more than one:

./surfmeter-automator-headless startStudy \
    --studyId STUDY_YOUTUBE \
    --chromeArgs ozone-platform=headless \
    --chromeArgs use-gl=angle

You can also set them once for all scheduled studies in automatorConfig.json:

automatorConfig.json
{
  "globalScheduleSettings": {
    "options": {
      "chromeArgs": ["ozone-platform=headless", "use-gl=angle"]
    }
  }
}

Automator already sets a number of Chrome feature flags itself. When you pass an enable-features=... or disable-features=... argument, its comma-separated values are merged with Automator's own flags rather than replacing them; any other argument is appended as-is.

Commas inside a single flag

A single feature flag may itself contain commas (e.g. enable-features=NetworkService,NetworkServiceInProcess). Keep it as one --chromeArgs value; do not split it into several. When you set the override through an environment variable instead, see Array and Object Options.

Network Throttling Chrome

For studies that use the browser (i.e., non-Lighthouse web measurements using the website subject, video measurements, and non-native speed tests), Chrome's capabilities to emulate a slow network can be used.

  • --latency: Sets the latency in milliseconds
  • --uploadThroughput: Sets the upload throughput in kBit/s. Set to -1 to disable throttling (default).
  • --downloadThroughput: Sets the download throughput in kBit/s. Set to -1 to disable throttling (default)

Note that with extreme settings of the above values, functionality of the Automator software may not be guaranteed, and videos may run into timeouts. The sending of the measurement data will not be affected by the throttling.

Network Throttling on the System Level

You can use a tool like comcast to throttle the network on the system level. This is useful for studies that do not use the browser, such as the DNS measurement. Note, however, that this will also affect the sending of the measurement data.

Under the hood, it uses tc, which requires root privileges. To install it on Ubuntu, run:

sudo apt update -qq && sudo apt install golang-go iproute2 iptables

As root, run:

go get github.com/tylertreat/comcast

Then add this to your /root/.bashrc:

export PATH=$PATH:/root/go/bin/

Now you can run it, as root, like this:

comcast --stop
comcast --latency=250

Check out the GitHub repository for more information.

Docker usage

For Docker, so far, it appears that only latency throttling works with Docker.

To run the above commands you need to make sure you run the container with the --cap-add=NET_ADMIN flag, and drop into a root shell to perform the above commands:

docker exec --user root -it surfmeter bash

Cache Clearing

Automator attempts to create a clean environment for running measurements, by performing the following steps every time the browser is started:

  1. Clearing the system DNS cache
  2. Clearing browser cookies
  3. Clearing the browser cache

These steps can be disabled via the respective command-line flags:

  • --noClearSystemDns
  • --noClearCookies
  • --noClearCache

Note

To clear the system DNS cache, the user must be able to run a specific binary with sudo without having to enter the password interactively. The command depends on the operating system. For Linux, it is resolvectl; for macOS it is dscacheutil. Please refer to the man sudoers manual on how to allow the user to execute these commands noninteractively.

For instance, to allow a user to run Linux resolvectl without a password, add the following line to the /etc/sudoers file:

<username> ALL=(ALL) NOPASSWD: /usr/bin/resolvectl

Please replace <username> with your user's name, and edit this file with visudo to avoid syntax errors.

On older systems, the binary might be located at /usr/bin/systemd-resolve.