Special Features

Additional Browser Extensions

To load additional browser extensions, first download the extension from the Chrome Web Store, using the download_crx.sh script that comes with Automator. For instance, to download the uBlock Origin ad blocker:

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

You can then load this extension in a study. Repeat the flag to load multiple extensions.

surfmeter study start --studyId STUDY_YOUTUBE \
    --additionalExtensions $HOME/.surfmeter/extensions/ublockOrigin

We cannot guarantee that all extensions will work properly with Automator. Please report any issues you encounter.

Environment Variables

• SURFMETER_STORAGE_DIR: The directory for the registration, configuration, and data (default: ~/.surfmeter)
• SURFMETER_DISPLAY: The number of the virtual display (default: :123). See Display Modes.
• SURFMETER_DISPLAY_RESOLUTION: The resolution of a virtual display, in the format <width>x<height>x<bitDepth> (default: 1920x1080x24)
• SURFMETER_DISABLE_CONFIG_UPDATE: Set to 1 to stop the daemon from downloading the configuration
• SURFMETER_DISABLE_SYSTEM_STATUS: Set to 1 to disable the collection and reporting of CPU, memory, filesystem, and connection status
• SURFMETER_CHROME_BINARY: The path to a different browser binary. This can be overridden with --chromeBinary.
• SURFMETER_LOG_MODE: The output mode
• LOG_LEVEL: The log level

The Docker container takes additional environment variables.

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 name of the option in SCREAMING_SNAKE_CASE. Use this to override a setting on one machine without changing its configuration files. The environment variable takes priority over command-line flags and schedule config options.

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

The value is interpreted according to the type of the option:

• Boolean options accept true, 1, yes, or on, and false, 0, no, or off. To turn off a behavior that is on by default, set its no* option.
• Number options accept any number. String options are taken as they are.
• Array options accept a single value or a JSON array, such as SURFMETER_OPTIONS__CHROME_ARGS='["ozone-platform=headless","use-gl=angle"]'. A single value is not split at commas.
• --metadata and --extraHeaders accept JSON, such as SURFMETER_OPTIONS__METADATA='{"site":"probe-042"}'.

The output mode cannot be set this way. Use SURFMETER_LOG_MODE instead.

For scheduled studies, the variable must be available to the daemon. You can set it with systemctl --user edit surfmeter-daemon.service, in the environment of the Docker container, or in the env section of the schedule config.

Custom Chrome Arguments

Use --chromeArgs to pass extra command-line arguments to the browser. Pass each argument without the leading --, and repeat the flag to pass more than one:

surfmeter study start --studyId STUDY_YOUTUBE \
    --chromeArgs ozone-platform=headless \
    --chromeArgs use-gl=angle

You can also set them for all scheduled studies, in the schedule config:

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

Values passed with enable-features=... or disable-features=... are merged with the flags that Automator sets itself. Any other argument is added as it is. A feature flag may contain commas. Keep it as one value.

Network Throttling in Chrome

For studies that use the browser, you can emulate a slow network:

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

With extreme values, videos may run into timeouts. Sending the measurement data is not 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, which also applies to studies that do not use the browser. Note that this also affects the sending of the measurement data. For Docker, run the container with the NET_ADMIN capability, which our Compose file already does. So far, only latency throttling appears to work with Docker.

Cache Clearing

Each time it starts the browser, Automator attempts to clear the following data:

1. The system DNS cache
2. Browser cookies
3. The browser cache

You can disable these steps with the flags --noClearSystemDns, --noClearCookies, and --noClearCache.

To clear the system DNS cache, the user must be able to run resolvectl with sudo without entering a password. To allow this, add the following line with visudo, replacing <username> with the name of the user:

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

Browser Profiles

Each browser starts with a temporary profile, which is deleted after the run. Use --profileDir to keep browser state between runs, for example to inspect a completed run or log in to a service manually. To remove caches and other temporary data from a saved profile, run surfmeter profile cleanup --profileDir <path>.