# Footprint data script details

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.

## Variables
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 $PAYLOAD_RUNTIME_ARGS --rm --runtime=$CONTAINERD_RUNTIME $PAYLOAD $NAME sh -c $PAYLOAD_ARGS`

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
| `PAYLOAD_RUNTIME_ARGS` | Any extra arguments passed into the ctr `run` command
| `PAYLOAD_SLEEP` | Seconds to sleep between launch and measurement, to allow settling
| `MAX_NUM_CONTAINERS` | The maximum number of containers to run before terminating
| `MAX_MEMORY_CONSUMED` | The maximum amount of memory to be consumed before terminating
| `MIN_MEMORY_FREE` | 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

## Output files
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`

## Measurements
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`

## Example script
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.

```
#!/bin/bash

set -e
set -x

export MAX_NUM_CONTAINERS=10
export MAX_MEMORY_CONSUMED=6*1024*1024*1024

function run() {
	###
	# Define what we will be running (app under test)
	#  Default is we run busybox, as a 'small' workload
	export PAYLOAD="quay.io/prometheus/busybox:latest"
	export PAYLOAD_ARGS="tail -f /dev/null"
	export PAYLOAD_SLEEP=10
	export PAYLOAD_RUNTIME_ARGS="5120"
	sudo -E bash $(pwd)/density/footprint_data.sh
}

export CONTAINERD_RUNTIME=io.containerd.kata.v2
run
```