Skip to main content

Job Package config.yaml

Introduction​

This document describes the required and possible auxillary 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
artifacts:
  location: ${DIR}/artifact/dir/
  frequency: 15
  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.

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.

  • 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