Skip to main content
Version: 2.0 (Preview)

How it Works

Components​

A probe runs three components:

  • The surfmeter program, which starts studies and provides all commands.
  • The scheduling daemon, a background service that is part of the same program. It starts a separate surfmeter study start process for each scheduled run. A study that hangs or crashes does not affect the schedule.
  • A browser managed by Automator, used for browser-based studies.

Where the Configuration Comes From​

Automator uses two configuration files. In the dashboard, they are called:

  • Measurement config (publicConfig.json): what to measure, as a list of studies
  • Schedule config (automatorConfig.json): when to measure, and with which options

You edit and publish these in the Surfmeter Dashboard and assign them to clients. The daemon asks the server for updates every 15 minutes, installs a new configuration, and applies it without a restart. If a new configuration is invalid, the probe keeps the last one that worked.

You can also maintain the configuration on the probe, for example for a test setup.

Where Measurements Run​

Most measurements run in a browser, which Automator installs during setup.

Native measurements run without a browser, for example with ping, or with the Lighthouse version built into Automator. Automator starts the tool, waits for it to finish, and collects the results.

Multiple measurements can run in parallel, for example a video study together with a speed test.

For more details on the underlying concepts, see the concepts page.

What Happens with the Results​

Automator sends the results of every measurement to the Surfmeter server. There, you can view them in the dashboard or export them using the API. If a result cannot be sent, for example because the network is down, Automator stores it in ~/.surfmeter/data/, and the daemon sends it later. You can also store each result as a JSON report on the probe.

See Measurement Data for the result fields, Statistic Values for KPIs, and Client Reports for debug data.

Where Files Are Stored​

Automator is installed in ~/surfmeter, and the command surfmeter is available for all users. All of its data is in ~/.surfmeter:

  • .auth.json, .api-auth.json: the registration of the client
  • config/: the configuration files
  • lastGoodConfig/: a copy of the last configuration that worked
  • data/: results that have not reached the server yet
  • logs/: log files of commands that you run by hand
  • logs/scheduled/: log files of scheduled runs, if configured
  • recordings/, pcaps/, har-files/, network-requests/, reports/: files created by the optional features
Keep the client registration and unsent results

Do not delete ~/.surfmeter. It contains the client's registration and unsent results. Set SURFMETER_STORAGE_DIR to use a different storage location.