Skip to main content

Job Package config.yaml

Introduction​

This document describes the required and possible auxiliary configuration parameters for the Job Packages created by users for packaging their code for execution by the LabScale agent. These parameters reside in the config.yaml file found in the package's root folder.

Required configuration items​

The following configuration items define the minimalest set of options required for a functional Job Package.

name: the-package-name
version: 1.0.0
cmd: ${DIR}/main_script

name​

This name configuration item is the given name of the Job Package.

version​

The version configuration item is the version of the Job Package and is used to determine if the new job package has been updated and requires replacement within the download cache.

cmd​

This is the path to the script called by the agent when executing the Job. Environment variables are available and can be used for substitutions. However, the variable DIR is only available within this context and represents the path to the unpacked job package.

Optional configuration options​

ignore_rc: true/false
ignore_timeout: true/false
ignore_runtime_rc: true/false
setup_cmd: ${DIR}/setup.sh
cleanup_cmd: ${DIR}/cleanup.sh
early_device_release: true/false
teardown_timeout: 0
results_timeout: 0
adapter:
  name: pytest_stdout_adapter
  URI: https://files.labscale.com/adapter/pytest_stdout_adapter.tgz
artifacts:
  location: ${DIR}/artifact/dir/
  frequency: 15
  type: jfile
  call_hook: ${DIR}/script

ignore_timeout​

The ignore_timeout configuration option accepts a simple true or false boolean value and tells the agent to show the job as completed instead of timed out if the task is terminated due to a timeout.

ignore_rc​

The ignore_rc configuration option accepts a simple true of false boolean value and tells the agent to ingnore the return code from the job and to display a complete instead of error should an error code be returned.

ignore_runtime_rc​

The ignore_runtime_rc configuration option accepts a simple true or false boolean value and applies only when a job exceeds its configured runtime limit. When the limit is reached, the agent signals the job's script to shut down. A script that does not handle that signal is terminated by it and reports a failing return code, even though nothing actually went wrong. Setting this option to true tells the agent not to treat termination by that specific signal as a failure.

This is narrower than ignore_rc in two ways. It only forgives that one signal, so genuine failures are still reported as errors, and it does not apply to a script that is forcibly killed after refusing to shut down, nor to a script that handles the signal and then chooses its own exit code. Like ignore_rc and ignore_timeout, it is off unless the package opts in.

setup_cmd​

The setup_cmd configuration will execute whatever string is provided in a command shell. This will be called prior to execution of the job package's main script.

cleanup_cmd​

The cleanup_cmd configuration will execute whatever string is provided in a command shell. This will be called after execution of the job package's main script.

early_device_release​

The early_device_release configuration option accepts a simple true or false boolean value and determines whether the job's target device is released back to the pool as soon as the main script exits, rather than being held through the cleanup phase. The cleanup phase covers the cleanup script, artifact upload, and removal of the job's working directory. Releasing the device early lets the scheduler dispatch the next job sooner, while cleanup continues in the background.

Unlike the other boolean options on this page, this one has three states rather than two. If the option is omitted entirely, the agent-wide early_device_release setting decides. Setting it explicitly to true or false overrides the agent-wide setting in either direction.

Set it explicitly to false for packages whose cleanup phase still needs the device — for example an artifacts call_hook script that pulls files off the device. Releasing such a device early would allow the scheduler to hand it to the next job while that cleanup is still using it.

teardown_timeout​

The teardown_timeout configuration option is the maximum number of seconds allowed for this package's teardown phase after the main script exits, overriding the agent-wide job_teardown_timeout. A value of 0, or omitting the option, uses the agent-wide setting.

results_timeout​

The results_timeout configuration option is the maximum number of seconds allowed for processing this package's results, overriding the agent-wide job_results_timeout. A value of 0, or omitting the option, uses the agent-wide setting.

adapter stanza (deprecated)​

The adapter stanza selects the results adapter used to parse the job's output into test results. It is a legacy option retained for backwards compatibility — the adapter is normally supplied by the LabScale service as part of the job itself, and a job that supplies one takes precedence over anything declared here.

The stanza accepts two options, at least one of which must be given:

  • name selects an adapter by name from the agent's available_adapters list. If the name is not present in that list, the adapter cannot be resolved and the job's results will not be processed.
  • URI is the full URL the adapter is downloaded from, for adapters that are not in the agent's available_adapters list. When a URI is given without a name, the name is derived from the URI.
note

Adapter declaration is now done within the web application but we will continue to support the legacy method for the foreseeable future.

artifacts stanza​

  • location​

    The location configuration option is the path to a folder containing generated artifacts that should be uploaded to the LabScale service during or at the end of execution. If it is not present, no artifacts will be processed or uploaded. The path can contain the same environment and DIR variables allowed by the cmd configuration item.

  • frequency​

    The frequency configuration option tells the agent the number of seconds between processing and uploading artifacts. If the value is 0 then artifacts will only be uploaded at the end of the Job's execution.

  • type​

    The type configuration option tells the agent how the uploaded artifacts should be classified by the LabScale service. The default is jfile, which attaches the artifacts to the Job that produced them. The alternative is misc, which uploads them as miscellaneous files not associated with a specific Job. No other values are accepted.

  • call_hook​

    The call_hook configuration option is the path to an auxiliary script that will be called just prior to processing and uploading artifacts. The script may accept a single argument that is passed on final execution that signals the last call to the script.

    An example of such a script may look like the following bash script for Android devices that pulls the Logcat file on every call, but will pull Bluetooth and Android Tombstone crash log files only on the last call to the script, just before the Job completes and exits. The latter will be split into chunks if they are greater 128Mb in size.

    #!/bin/bash -x
    EXEC_DIR="$(dirname "${0}")"

    RESULTS_ROOT="${EXEC_DIR}/artifacts/folder"
    [[ -z "${RESULTS_ROOT}" ]] && {
        echo "unable to find current log folder"
        exit 0
    }

    export ANDROID_SERIAL=${ANDROID_SERIAL:-${LS_DIP_android_serial}}

    # Get tombstone files.
    get_tombstones() {
        echo "Getting tombstones"
        adb root
        adb pull -a "/data/anr/" "."
        # Chunk tombstones to the upload folder.
        echo "Chunking tombstones"
        labscale-toolbelt chunkdir "./anr" "${RESULTS_ROOT}/anr"
        rm -rf "./anr"
        sync
    }

    # Get the BT snoop files
    get_btsnoop_logs() {
        echo "Pulling bt snoop logs"
        adb pull -a "/data/misc/bluetooth/" "."
        echo "Chunking bt snoop logs"
        labscale-toolbelt chunkdir "./bluetooth" "${RESULTS_ROOT}/bluetooth"
        rm -rf "./bluetooth"
        sync
    }

    # Get logcat
    get_logcat() {
        echo "Getting logcat"
        mkdir -p "${RESULTS_ROOT}/logcat"
        adb shell -x "logcat -d '*:W' && logcat -c" >>"${RESULTS_ROOT}/logcat/logcat.log"
        sync
    }

    # Pull logcat files on every call...
    get_logcat

    # Pull tombstones and bluetooth snoop logs only at the end of the job.
    if [[ "${1}" == "final" ]]; then
        get_tombstones
        get_btsnoop_logs
    fi