Changing the Configuration¶

Although we're shipping a default configuration, we're certain that you want to change the configuration at some point.

First, let's cover the concepts. There are two types of configuration for Surfmeter:

Public Configuration (publicConfig.json): here, you will define all studies (and, consequently, the measurements created) that can be run by Surfmeter. To find out more about it, please check out the public config reference.¹
Automator Configuration (automatorConfig.json): this defines the Automator configuration, i.e., when and how to run which studies. We'll explain it in more detail in the Automator Config Reference.

In other words, whenever you want to add/edit what is being measured, you will need to change the public configuration. Whenever you want to change how Surfmeter is being run, you will need to change the automator configuration.

Editing the `publicConfig.json`¶

Native ExecutionDocker

Locate the publicConfig.json file in the config directory, next to the surfmeter-lab-automator directory.

If you can't find the publicConfig.json file, you can create it and fill it out yourself. You can also always get a default configuration from us, or turn the one build into the Surfmeter Lab extension into an actual file. Run the following to create it locally:

./surfmeter-lab-automator/surfmeter-automator-headless getPublicConfig --publicConfigFile ./config/publicConfig.json

This will store the currently loaded public config file in the config directory one level above.

If you set up Docker per our setup instructions, you will already have a config folder locally, but it will be empty by default, because the default config is baked into the image.

You can run the getPublicConfig command inside the Docker container to store the public config file in the config folder:

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

Now you should have the publicConfig.json file in the config directory on your local machine mapped to the container.

How does the `publicConfig.json` file look like?¶

If you're using the default configuration, it might look like this:

publicConfig.json

{
  "version": 1,
  "studies": [
    {
      "id": "STUDY_YOUTUBE",
      "type": "VIDEO",
      "subject": "youtube",
      "names": {
        "en_US": {
          "short": "YouTube BBB Test",
          "long": "YouTube BBB Sample Test"
        }
      },
      "params": {
        "duration": 60,
        "timeout": 30,
        "video": {
          "src": "https://www.youtube.com/watch?v=aqz-KE-bpKQ",
          "contentType": "feature"
        },
        "playMode": "normal"
      }
    }
    // ...
  ]
}

Example: Adding a new study¶

Now, you can edit the file with your favorite text editor. For example, if you want to add a new study, you can add it to the studies array:

publicConfig.json

{
  "version": 1,
  "studies": [
    {
      "id": "STUDY_YOUTUBE",
      // ...
    },
    {
      "id": "STUDY_FACEBOOK",
      // ...
    }
  ]
}

To understand how you should format the file, and which studies/params are available, please have a look at the available studies page, and for detailed parameters, check out the public config reference.

Tip

The JSON files read by Automator support the JSON5 format, which means that you can use comments in your JSON files. This is especially useful for the publicConfig.json file, where you might want to add some comments to explain what a study does, or temporarily comment out a study that you don't want to run.

Once you've edited the publicConfig.json file, the next time you run a study, Automator will pick up the changes and store them in the Surfmeter Lab extension.

Editing the `automatorConfig.json`¶

Similarly, if you want to edit/add/remove the schedule of when studies are run, you need to change the automator config file.

Locate the automatorConfig.json file in the config directory, next to the surfmeter-lab-automator directory.

It might look like this:

automatorConfig.json

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

If you can't find the automatorConfig.json file, you can always get a default configuration from us, or simply use an empty template, with at least the following content:

automatorConfig.json

{
    "version": 1,
    "studySchedules": []
}

Now, you can edit the file with your favorite text editor. For example, if you want to add a new schedule for a study, you can add it to the studySchedules array:

automatorConfig.json

{
  "version": 1,
  "registrationKey": "...",
  "updates": {
    // ...
  },
  "studySchedules": [
    {
      "id": "STUDY_YOUTUBE",
      "studyId": "STUDY_YOUTUBE",
      "cronSchedule": "0,10,35 * * * *"
    },
    {
      "id": "STUDY_FACEBOOK",
      "studyId": "STUDY_FACEBOOK",
      "cronSchedule": "5,25,45 * * * *"
    }
  ]
}

To understand how you should format the file, please check out the Automator config reference.

Tip

The Automator config also supports the JSON5 format, like the public config.

Local Configuration Overrides¶

Sometimes, you want to configure machines differently. For example, you might want to run a study on one machine, but not on another. Or you might want to run a study more often on one machine, but not on another. This is where local configuration overrides come in. You can still define a general configuration in the publicConfig.json and automatorConfig.json files, but you can also override specific values for specific machines.

Local Public Config — `publicConfig.local.json`¶

If you want to override the parameters for some studies on a specific machine, you can create a publicConfig.local.json file in the config directory. This file will be loaded on top of the publicConfig.json file, and will override any values that are present in both files.

For instance, your config folder might look like this:

├── automatorConfig.json
├── publicConfig.json
└── publicConfig.local.json

The definitions of each study in the default public config will be recursively merged with entries in the local public config. The studies will be matched via their ID. Any property present in the local public config will override a property with the same name in the default public config. So if you have a study with STUDY_YOUTUBE in your regular config, and you add a new study with STUDY_YOUTUBE to the local public config, the new study will override the old one.

If you add a new study ID to the local public config (i.e. one that previously did not exist), it will be added to the default public config.

Examples

Overriding a video URLSetting global credentials

For example, if your default public config contains a study for YouTube:

publicConfig.json

{
    "version": 1,
    "studies": [
        {
            "id": "STUDY_YOUTUBE",
            "subject": "youtube",
            "names": {
                "de_DE": {
                    "short": "YouTube BBB Test",
                    "long": "YouTube BBB Sample Test"
                },
                "en_US": {
                    "short": "YouTube BBB Test",
                    "long": "YouTube BBB Sample Test"
                }
            },
            "params": {
                "duration": 60,
                "timeout": 30,
                "video": {
                    "src": "https://www.youtube.com/watch?v=aqz-KE-bpKQ",
                    "contentType": "feature"
                },
                "playMode": "normal"
            }
            // ...
        }
    ]
}

You may override this with a local public config containing a different video source:

publicConfig.local.json

{
    "studies": [
        {
            "id": "STUDY_YOUTUBE",
            "params": {
                "video": {
                    "src": "https://www.youtube.com/watch?v=9bZkp7q19f0"
                }
            }
        }
    ]
}

Note that you don't need to specify all properties of the study. You can just specify the ones you want to override.

You can also set a general override for all studies of a particular type:

publicConfig.local.json

{
    "credentials": {
        "netflix": {
            "username": "foo@example.com",
            "password": "bar"
        }
    }
}

This will apply the credentials to any Netflix studies.

Local Automator Config — `automatorConfig.local.json`¶

Similarly, you can override the schedule of when studies are run on a specific machine by creating a automatorConfig.local.json file in the config directory. This file will be loaded on top of the automatorConfig.json file.

In contrast to the local public config, the local automator config will not merge the array of schedules by their ID. Instead, it will replace the schedules entirely. So if you have existing schedules in your regular config, and you use a local automator config, the schedules in the local config will completely override all schedules in the regular config.

You may want to check how to set the public config or how to configure the Automator in more detail.

But for now, we can explore other features of Automator. Click Next below.

This is called “public” because there is also a “private” configuration hidden inside Surfmeter Lab. No need to worry about this one though. ↩

Changing the Configuration¶

Editing the publicConfig.json¶

How does the publicConfig.json file look like?¶

Example: Adding a new study¶

Editing the automatorConfig.json¶

Local Configuration Overrides¶

Local Public Config — publicConfig.local.json¶

Local Automator Config — automatorConfig.local.json¶

Editing the `publicConfig.json`¶

How does the `publicConfig.json` file look like?¶

Editing the `automatorConfig.json`¶

Local Public Config — `publicConfig.local.json`¶

Local Automator Config — `automatorConfig.local.json`¶