Logging

Automator writes logs to a file, the systemd journal, or the container output, depending on how it runs.

Commands You Run by Hand

In a terminal, Automator shows a progress summary and any errors. It writes the full log to ~/.surfmeter/logs/. The file name contains the time, command, and process ID, for example 2026-09-08T10-12-31_study-start_48211.log.

Automator deletes the oldest files once there are more than 100 or they take up more than 256 MiB.

Send the full log when contacting support

A failed run prints its log file path. Send that file to support; it contains more detail than the terminal summary.

To see the full log in your terminal, add --verbose.

The --logMode option, or the SURFMETER_LOG_MODE environment variable, sets the output mode:

• user: a progress summary, with the full log in a file. This is the default in a terminal.
• pretty: the full, readable log on standard output. --verbose is a shorthand for this mode.
• ldjson: the full log as JSON lines on standard output. This is the default outside of a terminal, such as in a script.

Scheduled Studies

The output of scheduled runs is part of the log of the daemon, which you can read with:

journalctl --user -u surfmeter-daemon -f

Every line of a run contains its runId and jobId (the ID of the schedule entry). You can use this to filter the log of one run:

journalctl --user -u surfmeter-daemon -o cat | jq 'select(.runId == "<runId>")'

To additionally write the output to a file, set logFile, either for all studies under globalScheduleSettings, or for a single entry:

{
  "globalScheduleSettings": {
    "logFile": "$HOME/.surfmeter/logs/scheduled/studies.log"
  }
}

You can use the variables $HOME, $TMP, $USER, and $UID in the path.

Important: Configure rotation for scheduled log files

Automator does not rotate files configured with logFile. Set up log rotation to limit their disk usage.

Docker

All services in the container write JSON lines to the container output. Read them with:

docker compose logs -f surfmeter

Limit the size of these logs with the logging section of the Compose file, as shown in the Docker setup.

Log Levels

The LOG_LEVEL environment variable controls how detailed the log is. These are the levels, from least to most verbose:

• error
• warn
• info: the default
• debug: also shows every request sent to the server. In user mode, the log file uses this level by default.
• trace: also shows the content of these requests
• extreme: also shows all messages exchanged with the browser

Set the variable for a single command, or in the env section of the schedule config:

LOG_LEVEL=debug surfmeter study start --studyId STUDY_YOUTUBE --verbose

{
  "id": "youtube-hourly",
  "studyId": "STUDY_YOUTUBE",
  "schedule": "0 * * * *",
  "env": {
    "LOG_LEVEL": "debug"
  }
}

Secrets such as passwords and tokens are removed from the logs, at all levels.

Log Rotation

To rotate files that you configured with logFile, you can use logrotate. Create a file /etc/logrotate.d/surfmeter, with the correct path for your user:

/home/surfmeter/.surfmeter/logs/scheduled/*.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
    copytruncate
}

Use copytruncate, since the daemon keeps the file open while a run is active.