Skip to main content
Version: 2.0 (Preview)

Running Studies

Run studies manually to test a configuration or take a one-off measurement. For Docker, see how to run commands in the container.

Supported Study Types

Automator can measure video streaming services, website performance, speed tests, network diagnostics, and conferencing platforms. For complete examples and configuration details, see Available Studies.

Measuring a URL​

Use surfmeter measure to measure a URL without configuring a study first:

surfmeter measure https://www.wikipedia.org
surfmeter measure "https://www.youtube.com/watch?v=aqz-KE-bpKQ"
surfmeter measure traceroute://8.8.8.8

Automator infers the type of study from the URL:

  • Website: a normal URL without a path, such as https://example.com
  • Video: a URL with a path from a known video service, such as https://www.youtube.com/watch?v=<id>. This runs for 30 seconds by default.
  • Speed test: speedtest://<service>, with fast.com, speedtest.net, or nperf.com as the service. Use ooklaspeedtest:// for the Ookla command-line tool.
  • Network test: traceroute://<host>, icmpping://<host>, or dns://<host>

You can pass multiple URLs with surfmeter study start --url <url1> --url <url2>. The generated study is stored in publicConfig.local.json. To change its duration or other details, configure a study.

Running Configured Studies​

List the studies in your configuration:

surfmeter study list

If a study that you are looking for is not listed, you need to add it to the measurement config.

Run a study by its ID:

surfmeter study start --studyId STUDY_YOUTUBE

For a browser-based study, this opens a browser in the background, runs the measurement, and sends the results to the server. Results appear in the dashboard about 30 seconds later and are also available through the API.

To run an entry of the schedule now, with its options, use surfmeter daemon run <entryId>.

Storing Measurement Results (Reports)​

To write the results to a JSON file, use --reportFile or --reportDir:

surfmeter study start --studyId STUDY_YOUTUBE --reportFile output.json
surfmeter study start --studyId STUDY_YOUTUBE --reportDir ~/.surfmeter/reports/

With --reportDir, the file is named according to the date and time, the client UUID, and the study ID.

Report Format​

{
    "started_at": "2023-09-04T18:36:05.736Z",
    "ended_at": "2023-09-04T18:36:20.975Z",
    "measurement_reports": [
        [
            {
                "type": "VideoMeasurement",
                "id": 2033,
                "video_measurement_id": 1331
                // ...
            }
        ]
    ],
    "study_summary": [
        {
            "study_id": "STUDY_YOUTUBE",
            "finish_status": "aborted",
            "aborted_reason": "videoLoadError"
        }
    ],
    "diagnostics": {
        // ...
    }
}
  • measurement_reports contains the measurements of each study. The format is described in the measurement data reference. The results also contain the statistic values and the Client Reports.
  • started_at and ended_at contain the start and end time of all studies, in ISO 8601 format.
  • study_summary contains the study ID, the finish status, and the reason for aborting the study, if applicable.
  • diagnostics contains information about the run, such as the command-line arguments, the versions of Automator and Surfmeter Lab, the display mode, and any errors.

Starting Parallel Studies​

You can run multiple studies in parallel by repeating --studyId, for example a speed test while loading a video:

surfmeter study start --studyId STUDY_FASTCOM --studyId STUDY_YOUTUBE

The results are stored in separate measurements on the server.

To run them one after the other, add --sequential. Use --startOffset to delay the start of a study by a number of seconds.

Timeouts​

Study Timeout​

  • --studyTimeout: The maximum duration of one study, in seconds (default: 300). A study that is still running after this time is aborted with the reason studyTimeout. If the nominal duration of a study is longer, the timeout is increased, and a warning is printed.
  • --sendTimeout: The maximum time for sending the results to the server, in seconds (default: 15). Results that could not be sent are kept, and are sent later.
  • --globalTimeout: The maximum duration of the whole run, in seconds (default: 600). It is raised automatically if it is too short for the studies of the run. After this time, Automator aborts the studies. Within a grace period (--globalTimeoutGracePeriod), it still tries to report to the server that the study was aborted.

If you schedule studies back-to-back, ensure that the global timeout leaves enough time for the browser to close before the next study starts. Alternatively, use an interval, which is measured from the end of the previous run.

Sending Unsent Results​

Results that could not be sent are stored in ~/.surfmeter/data/, and the daemon sends them every 15 minutes. To do this by hand, or to see what is stored, run:

surfmeter database list
surfmeter database flush

To send earlier results after a study, add --flushDb to the study. You can set a timeout in seconds with --flushDbTimeout (default: 10).

Additional Data​

See the reference for all options.