Scheduling Studies

The scheduling daemon runs studies defined in a schedule config. Create schedules in the dashboard or in a local automatorConfig.json. See the Automator Config V2 reference for all fields.

Example

automatorConfig.json

{
  "$schema": "https://aveq.info/jsonschema/AutomatorConfigV2.json",
  "version": 2,
  "globalScheduleSettings": {
    "timeZone": "Europe/Vienna",
    "randomOffset": 5
  },
  "studySchedules": [
    {
      "id": "youtube-hourly",
      "studyId": "STUDY_YOUTUBE",
      "schedule": "0 * * * *"
    },
    {
      "id": "peak",
      "studyId": ["STUDY_YOUTUBE", "STUDY_FASTCOM"],
      "schedule": "0 20 * * *"
    },
    {
      "id": "chain",
      "studyId": ["STUDY_DNS", "STUDY_YOUTUBE"],
      "interval": "30m",
      "options": { "sequential": true }
    },
    {
      "id": "campaign",
      "studyId": "STUDY_FASTCOM",
      "interval": "1h",
      "validFrom": "2026-12-01T00:00:00Z",
      "validUntil": "2026-12-31T23:59:59Z"
    }
  ]
}

Timing

Each entry has either a schedule or an interval.

Fixed Times

A schedule is a cron expression:

• Five fields (minute hour day month weekday), for example 0 * * * * for every hour. If you are unsure, check crontab.guru.
• Six fields, with a leading field for the second, for example 30 0 * * * *.
• Macros: @yearly, @annually, @monthly, @weekly, @daily, @midnight, and @hourly. @reboot is not supported.

If a run is due while the previous run of the same entry is still active, it is skipped, and reported to the server as an aborted measurement with the reason previousRunStillActive. Different entries can run at the same time. Make sure that your probe can handle that.

Intervals

An interval is the time between the end of one run and the start of the next, regardless of whether the run succeeded. It is a whole number followed by s, m, h, or d, for example 30s, 15m, 2h, or 1d. An entry with an interval never overlaps with itself.

The first run starts when the daemon starts, or when the entry first appears in the configuration.

Time Zone

Cron schedules use the time zone of the host. To set a different one for all entries, use globalScheduleSettings.timeZone with an IANA name such as UTC or Europe/Vienna. Intervals do not depend on a time zone.

Random Offset

globalScheduleSettings.randomOffset keeps multiple probes from starting at the same moment. The value is a maximum in minutes (at least 1/60, and less than 60). Each probe gets a stable offset per entry and keeps its time slot across restarts. For an interval, the offset only delays the first run.

Start and End Dates

validFrom and validUntil limit an entry to a time period, for example for a campaign. Both are ISO 8601 times, and both are inclusive.

Missed Runs

The daemon skips runs missed while it or the probe was stopped. A probe that reboots at a fixed time every day therefore never runs a study scheduled within that window.

Multiple Studies

studyId can be a list of studies. These run in parallel, or one after the other with "options": { "sequential": true }. See Running Studies for the limits of parallel studies.

Study Options and Environment Variables

options sets the options of surfmeter study start, and env sets environment variables. Set defaults in globalScheduleSettings and overrides in each entry. Automator merges them, with entry values taking priority.

Unknown keys and options are errors in version 2 of the format.

Timeouts

Set globalTimeout in options to limit the duration of a run, in seconds. Without it, the default is 600 seconds. If the run is still active after this time, plus the grace period and 30 more seconds, the daemon kills it. See timeouts.

Checking the Schedule

Use these commands to check the active schedule or run an entry immediately. See Scheduling Daemon for details.

surfmeter daemon status             # Show the jobs, schedule issues and runs
surfmeter daemon run <entryId>      # Run an entry now