Skip to main content

Agent config.yaml

Introduction​

This document describes the required and possible auxiliary configuration parameters for the LabScale Agent. These options should be set or modified in the config.yaml file found in the labscale-agent folder.

Required configuration items​

The following list of configuration options are generally set automatically at the time the agent is installed. It is best that the values for these options not be modified manually.

agent_id: <AGENT_ID>
broker_url: wss://broker.labscale.com:443/mqtt
loki_push_url: https://broker.labscale.com/loki/v1/push
team_id: <TEAM_ID>

agent_id​

The agent_id configuration option is the ID of the agent recorded in the LabScale service. It is automatically set at the time the agent is installed.

broker_url​

The broker_url configuration option is the URL required by the agent to communicate with the MQTT broker. This value will be automatically set at the time the agent is installed.

loki_push_url​

The loki_push_url configuration option is the URL to the Loki log collection service where log items are uploaded. This option will be automatically set at the time the agent is installed.

team_id​

The team_id configuration option is the ID of the team to which the agent belongs. This option will be set automatically at the time the agent is installed.

Optional configuration options​

Optional configuration options and their default values can be found in the labscale-agent/config/default_config.yaml file. It is best not to modify these, instead to add the desired change to the main configuration file at labscale-agent/config.yaml, any options in this file will override the default options. Below is a list of the configuration options and their default values:

adapter_cache: $HOME/.labscale_agent/adapters
agent_metric_interval: 30
agent_status_interval: 90
agent_sync_interval: 60
agent_update_drain_timeout: 21600
available_adapters:
  pytest_stdout_adapter: https://files.labscale.com/adapter/pytest_stdout_adapter.tgz
config_version: 0
connect_timeout: 60
dialer_timeout: 60
dip_cache: $HOME/.labscale_agent/dips
download_cache: /tmp/labscale_agent/downloads
download_cache_max_age: 0
download_cache_max_size: 10g
download_max_duration: 0
download_stall_timeout: 90
early_device_release: true
job_artifact_upload_grace_period: 0
job_dir: /tmp/labscale_agent/jobs
job_dir_max_age: 30
job_dir_max_backups: 100
job_output_stall_timeout: 300
job_poll_interval: 2
job_results_timeout: 0
job_runtime_signal: SIGTERM
job_shutdown_grace_period: 60
job_teardown_timeout: 0
log_compression: true
log_max_age: 30
log_max_backups: 10
log_max_size: 5
loki_level: info
loki_max_age: 15
loki_max_size: 1000
max_concurrent_agent_messages: 32
mqtt_keep_alive: 30
mqtt_max_reconnect_interval: 120
mqtt_write_timeout: 15
pub_loop_sleep_time: 1
restart_kill_threshold: 1.5
restart_kill_count: 5
s3_presigned_push_url: ""
upload_stall_timeout: 90

An explanation of the configuration options is below:

adapter_cache​

The adapter_cache configuration option is the location where the agent stores results adapters it has downloaded. On subsequent jobs that use the same adapter, the cached copy is reused instead of downloading it again.

agent_metric_interval​

The agent_metric_interval configuration option is the number of seconds between polling devices for their current metrics.

agent_status_interval​

The agent_status_interval configuration option is the number of seconds between agent status updates.

agent_sync_interval​

The agent_sync_interval configuration option is the number of seconds between polling the devices for their current online/offline state.

agent_update_drain_timeout​

The agent_update_drain_timeout configuration option is the maximum number of seconds the agent will wait for its in-flight jobs to finish before an agent update is installed. The agent stays fully online and subscribed for the duration of the wait, so jobs continue to run normally. If jobs are still running when this budget is exhausted, the update install is abandoned and retried later. A value of zero or less selects the built-in default of 21600 seconds (6 hours).

available_adapters​

The available_adapters configuration option is a map of adapter names to the URLs they are downloaded from. It is what allows a job package to select a results adapter by name alone rather than having to supply a full URL. An adapter named by a job package but absent from this map cannot be resolved, and the job's results will not be processed.

config_version​

The config_version configuration option is the revision number of the agent's own configuration. The agent reports it to the LabScale service as part of its host status so the service can tell which revision of the configuration the agent is currently running.

connect_timeout​

The connect_timeout configuration option is the number of seconds the agent waits on connecting to the MQTT broker.

dialer_timeout​

The dialer_timeout configuration option is the number of seconds the agent waits on looking up the broker address.

dip_cache​

The dip_cache configuration option is the location where the agent looks for DIPs that have already been downloaded and are ready to use.

download_cache​

The download_cache configuration option is the intermediate location where the agent will download and store files. On subsequent downloads of the same file, the agent will first check if an identical copy already exists in cache before downloading it again.

download_cache_max_age​

The download_cache_max_age configuration option is the number of seconds to store cached files after download. The current default of 0 indicates this feature is disabled.

download_cache_max_size​

The download_cache_max_size configuration option is the combined total size in bytes of files to store in the download cache before which files will be automatically removed, oldest files first. This option allows shorthand suffix g, m, k that represent gigabytes, megabytes, and kilobytes.

download_max_duration​

The download_max_duration configuration option is an optional absolute ceiling, in seconds, on a single download attempt regardless of how many bytes are transferring. The default of 0 means there is no ceiling. Because a fixed wall-clock limit cannot suit files of arbitrary size, download_stall_timeout is the preferred protection against hung transfers; this option exists for sites that want a hard cap as well.

download_stall_timeout​

The download_stall_timeout configuration option is the maximum number of seconds a download may go without transferring any bytes before the attempt is canceled and retried. The retry resumes from the partial file already on disk, so no progress is lost. A value of 0 disables stall detection.

early_device_release​

The early_device_release configuration option is a simple true/false value that determines whether a job's devices are released back to the pool as soon as the job's script finishes, rather than being held through the job's teardown and results processing. Releasing early makes devices available to queued jobs sooner. This setting is the agent-wide default; an individual job package can override it with its own early_device_release setting in the job package config.yaml.

job_artifact_upload_grace_period​

The job_artifact_upload_grace_period configuration option is the number of seconds the final artifact upload at the end of a job will wait for a still-running periodic upload to finish on its own before canceling it and starting a fresh, blocking final upload pass. The default of 0 means a straggling periodic upload is canceled immediately. This option only governs that handoff — the final upload pass itself is deliberately not subject to a timeout, since artifact directories can be arbitrarily large.

job_dir​

The job_dir configuration option is the location in the filesystem where workspace folders are created when executing a job.

job_dir_max_age​

The job_dir_max_age configuration option is the maximum age in days before a job workspace folder is deleted.

job_dir_max_backups​

The job_dir_max_backups configuration option is the maximum number of job workspaces to be create before the agent cleans them up, the oldest getting cleaned up first.

job_output_stall_timeout​

The job_output_stall_timeout configuration option is the maximum number of seconds a job's script may run without producing any output before a warning about a possible stall is logged. The warning repeats at each interval while the stall continues and clears as soon as output resumes. This option only produces a warning; it does not terminate the job. A value of zero or less selects the built-in default of 300 seconds.

job_poll_interval​

The job_poll_interval configuration option is the number of seconds the agent waits until it checks with the backend scheduler for new jobs.

job_results_timeout​

The job_results_timeout configuration option is the maximum number of seconds allowed for a single results processing pass, which covers downloading the results adapter and parsing the job's output. This is budgeted separately from job_teardown_timeout so that an expired teardown budget can never truncate a results file. The default of 0 disables the timeout.

job_runtime_signal​

The job_runtime_signal configuration option is the signal sent to a job's script process when the job's configured runtime limit is reached. Valid values are SIGTERM (the default) and SIGINT. Use SIGINT for scripts, such as many Python test runners, that produce a cleaner shutdown and better output on an interrupt.

job_shutdown_grace_period​

The job_shutdown_grace_period configuration option is the number of seconds a canceled or timed-out job is given, after it is first asked to stop, to complete its wind-down before it is forcibly killed. The wind-down covers stopping the job script, running the teardown script, processing results, and removing the job workspace. Setting this value too low kills the job mid-cleanup and leaves job workspace folders behind. A value of zero or less selects the built-in default of 300 seconds. There is no added delay when a job winds down sooner — the agent waits only as long as the job actually takes.

job_teardown_timeout​

The job_teardown_timeout configuration option is the maximum number of seconds allowed for the teardown phase after a job's script exits. The budget starts when the script exits and covers everything that follows: in-flight and final artifact uploads, the teardown script, and workspace cleanup. Results processing is deliberately excluded and governed by job_results_timeout instead. The default of 0 disables the timeout.

log_compression​

The log_compression configuration option is a simple true/false value that tells the agent to compress the agent's rotated log files.

log_max_age​

The log_max_age configuration option is the number of seconds to retain an agent's rotated log file.

log_max_backups​

The log_max_backups configuration option is the number of total rotated logs files to retain on the host before they are removed, oldest removed first.

log_max_size​

The log_max_size configuration option is the total size in megabytes a log file can grow before it is automatically rotated.

loki_level​

The loki_level configuration option determines what level of agent log items are sent to the Loki log collection service.

loki_max_age​

The loki_max_age configuration option is the maximum number of seconds to wait before buffered log items are pushed to the Loki collection service.

loki_max_size​

The loki_max_size configuration option is the maximum number log lines to buffer before they are automatically pushed to the Loki log collection service.

max_concurrent_agent_messages​

The max_concurrent_agent_messages configuration option is the maximum number of incoming commands from the LabScale service — configure device, run job, delete device, and so on — that the agent will process at the same time. Additional commands are queued; if the queue is also full, the command is dropped and a warning is logged rather than stalling the agent's message handling. A value of zero or unset selects the built-in default.

mqtt_keep_alive​

The mqtt_keep_alive configuration option is the number of seconds between MQTT keep-alive packets sent to the broker. Lowering it detects a dead connection sooner at the cost of slightly more network traffic.

mqtt_max_reconnect_interval​

The mqtt_max_reconnect_interval configuration option is the maximum number of seconds to wait between MQTT reconnection attempts. The agent backs off progressively after a disconnect, and this value caps how long that back-off is allowed to grow.

mqtt_write_timeout​

The mqtt_write_timeout configuration option is the number of seconds the agent waits for a single MQTT publish to complete before giving up on it.

pub_loop_sleep_time​

The pub_loop_sleep_time configuration option is the number of seconds to wait before publishing messages.

restart_kill_threshold​

The restart_kill_threshold configuration option is the number of seconds between kill/restarts of the agent before the agent is considered to be malfunctioning.

restart_kill_count​

THe restart_kill_count configuration option is the number of times the agent is allowed to automatically restart before it is considered to be malfunctioning and killed.

s3_presigned_push_url​

The s3_presigned_push_url configuration option is the location to upload artifact files. This may be configured automatically when installed and should not be set manually.

upload_stall_timeout​

The upload_stall_timeout configuration option is the upload counterpart to download_stall_timeout: the maximum number of seconds an upload may go without transferring any bytes before the attempt is canceled and retried. Unlike downloads, uploads cannot resume, so a canceled attempt restarts from the beginning. A value of 0 disables stall detection.