Skip to content

Scheduling Studies

Surfmeter Automator can run studies on a schedule. It uses cron for doing so. This means that you can schedule studies to run at a specific time, or at a specific interval.

The automatorConfig.json file is used for scheduling the studies and updates. To accomplish this, it may contain a set of cron schedules. These schedules specify when the studies/updates are run.

Example automatorConfig.json

Here is an example automatorConfig.json file that schedules a study to run every 15 minutes:

automatorConfig.json
{
  "version": 1,
  "studySchedules": [
    {
      "id": "STUDY_YOUTUBE",
      "studyId": "STUDY_YOUTUBE",
      "cronSchedule": "*/15 * * * *"
    }
  ]
}

For the specific syntax, see the configuration documentation.

Want to persist the logs?

Normally, cron logs and Surfmeter's output is not shown or persisted. To log it to a file, modify automatorConfig.json and set the following property:

"globalScheduleSettings": {
    "cronLogFile": "$HOME/logs/surfmeter-automator.log",
}

This will log the cron output to the logs/surfmeter-automator.log file. If the path does not exist yet, please make sure to create it before. In a Docker environment, this folder should already be present.

Loading the Schedule

To load these schedules, use the loadSchedule command:

./surfmeter-lab-automator/surfmeter-automator-headless loadSchedule

docker exec --user surfmeter -it surfmeter surfmeter-lab-automator/surfmeter-automator-headless \
    loadSchedule

Note that we have an option to automatically load the schedule when the container starts. This is useful for running Automator in a containerized environment where restarts may happen. Set the SURFMETER_AUTO_LOAD_SCHEDULE environment variable to 1 to enable this behavior. You can do this in the .env file that is used for running the Docker container:

SURFMETER_AUTO_LOAD_SCHEDULE=1

Or use the environment property in the docker-compose.yml file:

# (other options)
services:
    surfmeter:
        # (other options)
        environment:
            SURFMETER_AUTO_LOAD_SCHEDULE: 1
        # (other options)

Important

By default, Automator will not run any studies or updates automatically, even if they are scheduled in the config file. You must first actively load this schedule into the user's crontab.

After loading the schedule, you can check the contents of the crontab (i.e. cron's current setup) with:

crontab -l

docker exec --user surfmeter -it surfmeter crontab -l

All entries for Automator have a comment added at the end of the line to identify them.

Clearing the Schedule

To clear the schedule, use the clearSchedule command:

./surfmeter-lab-automator/surfmeter-automator-headless clearSchedule

docker exec --user surfmeter -it surfmeter surfmeter-lab-automator/surfmeter-automator-headless \
    clearSchedule

Clearing the schedule will remove all Automator-defined entries in the crontab, but keep others (e.g., in case you have defined other recurring tasks).

Now you know how to set the schedule, we invite you to check out the screen recording, logging network requests or Automator's other special features.