Project: Kata Containers (Runtime / Container Runtime)
File: footprint_data.md

The `footprint_data.sh` script runs a number of identical containers sequentially via ctr and takes a number of memory related measurements after each launch. The script is generally not used in a CI type environment, but is intended to be run and analyzed manually. You can configure the script by setting a number of environment variables. The following sections list details of the configurable variables, along with a small example invocation script. Environment variables can take effect in two ways. Some variables affect how the payload is executed. The `RUNTIME` and `PAYLOAD` arguments directly affect the payload execution with the following line in the script: `$ ctr run --memory-limit $PAYLOADRUNTIMEARGS --rm --runtime=$CONTAINERDRUNTIME $PAYLOAD $NAME sh -c $PAYLOADARGS` Other settings affect how memory footprint is measured and the test termination conditions. | Variable | Function | -- | -- | `PAYLOAD` | The ctr image to run | `PAYLOAD_ARGS` | Any arguments passed into the ctr image | `PAYLOADRUNTIMEARGS` | Any extra arguments passed into the ctr `run` command | `PAYLOAD_SLEEP` | Seconds to sleep between launch and measurement, to allow settling | `MAXNUMCONTAINERS` | The maximum number of containers to run before terminating | `MAXMEMORYCONSUMED` | The maximum amount of memory to be consumed before terminating | `MINMEMORYFREE` | The minimum amount of memory allowed to be free before terminating | `DUMP_CACHES` | A flag to note if the system caches should be dumped before capturing stats | `DATAFILE` | Can be set to over-ride the default JSON results filename The names of the JSON files generated by the test are dictated by some of the parameters the test is utilising. The default filename is generated in the form of: `footprint-${PAYLOAD}[-ksm].json` The test measures, calculates, and stores a number of data items: | Item | Description | - | -- | `uss` | USS for all the VM runtime components | `pss` | PSS for all the VM runtime components | `all_pss` | PSS of all of userspace - to monitor if we had other impact on the system | `user_smem` | `smem` "userspace" consumption value | `avail` | "available" memory from `free` | `avail_decr` | "available" memory decrease since start of test | `cached` | "Cached" memory from `/proc/meminfo` | `smem_free` | Free memory as reported by `smem` | `free_decr` | Decrease in Free memory reported by `smem` since start of test | `anon` | `AnonPages` as reported from `/proc/meminfo` | `mapped` | Mapped pages as reported from `/proc/meminfo` | `cached` | Cached pages as reported from `/proc/meminfo` | `slab` | Slab as reported from `/proc/meminfo` The following script is an example of how to configure the environment variables and invoke the test script to run a number of different container tests. ``` set -e set -x export MAXNUMCONTAINERS=10 export MAXMEMORYCONSUMED=610241024*1024 function run() { export PAYLOAD="quay.io/prometheus/busybox:latest" export PAYLOAD_ARGS="tail -f /dev/null" export PAYLOAD_SLEEP=10 export PAYLOADRUNTIMEARGS="5120" sudo -E bash $(pwd)/density/footprint_data.sh } export CONTAINERD_RUNTIME=io.containerd.kata.v2 run ```