github.com/dmaizel/tests@v0.0.0-20210728163746-cae6a2d9cee8/metrics/density/footprint_data.md (about)

     1  # Footprint data script details
     2  
     3  The `footprint_data.sh` script runs a number of identical containers sequentially
     4  via ctr and takes a number of memory related measurements after each
     5  launch. The script is generally not used in a CI type environment, but is intended
     6  to be run and analyzed manually.
     7  
     8  You can configure the script by setting a number of environment variables.
     9  
    10  The following sections list details of the configurable variables, along with a
    11  small example invocation script.
    12  
    13  ## Variables
    14  Environment variables can take effect in two ways.
    15  
    16  Some variables affect how the payload is executed. The `RUNTIME` and `PAYLOAD`
    17  arguments directly affect the payload execution with the following line in
    18  the script:
    19  
    20  `$ ctr run --memory-limit $PAYLOAD_RUNTIME_ARGS --rm --runtime=$CONTAINERD_RUNTIME $PAYLOAD $NAME sh -c $PAYLOAD_ARGS`
    21  
    22  Other settings affect how memory footprint is measured and the test termination
    23  conditions.
    24  
    25  | Variable | Function
    26  | -------- | --------
    27  | `PAYLOAD` | The ctr image to run
    28  | `PAYLOAD_ARGS` | Any arguments passed into the ctr image
    29  | `PAYLOAD_RUNTIME_ARGS` | Any extra arguments passed into the ctr `run` command
    30  | `PAYLOAD_SLEEP` | Seconds to sleep between launch and measurement, to allow settling
    31  | `MAX_NUM_CONTAINERS` | The maximum number of containers to run before terminating
    32  | `MAX_MEMORY_CONSUMED` | The maximum amount of memory to be consumed before terminating
    33  | `MIN_MEMORY_FREE` | The minimum amount of memory allowed to be free before terminating
    34  | `DUMP_CACHES` | A flag to note if the system caches should be dumped before capturing stats
    35  | `DATAFILE` | Can be set to over-ride the default JSON results filename
    36  
    37  ## Output files
    38  The names of the JSON files generated by the test are dictated by some of the parameters
    39  the test is utilising. The default filename is generated in the form of:
    40  `footprint-${PAYLOAD}[-ksm].json`
    41  
    42  ## Measurements
    43  The test measures, calculates, and stores a number of data items:
    44  
    45  | Item | Description
    46  | ---- | -----------
    47  | `uss` | USS for all the VM runtime components
    48  | `pss` | PSS for all the VM runtime components
    49  | `all_pss` | PSS of all of userspace - to monitor if we had other impact on the system
    50  | `user_smem` | `smem` "userspace" consumption value
    51  | `avail` | "available" memory from `free`
    52  | `avail_decr` | "available" memory decrease since start of test
    53  | `cached` | "Cached" memory from `/proc/meminfo`
    54  | `smem_free` | Free memory as reported by `smem`
    55  | `free_decr` | Decrease in Free memory reported by `smem` since start of test
    56  | `anon` | `AnonPages` as reported from `/proc/meminfo`
    57  | `mapped` | Mapped pages as reported from `/proc/meminfo`
    58  | `cached` | Cached pages as reported from `/proc/meminfo`
    59  | `slab` | Slab as reported from `/proc/meminfo`
    60  
    61  ## Example script
    62  The following script is an example of how to configure the environment variables and
    63  invoke the test script to run a number of different container tests.
    64  
    65  ```
    66  #!/bin/bash
    67  
    68  set -e
    69  set -x
    70  
    71  export MAX_NUM_CONTAINERS=10
    72  export MAX_MEMORY_CONSUMED=6*1024*1024*1024
    73  
    74  function run() {
    75  	###
    76  	# Define what we will be running (app under test)
    77  	#  Default is we run busybox, as a 'small' workload
    78  	export PAYLOAD="quay.io/prometheus/busybox:latest"
    79  	export PAYLOAD_ARGS="tail -f /dev/null"
    80  	export PAYLOAD_SLEEP=10
    81  	export PAYLOAD_RUNTIME_ARGS="5120"
    82  	sudo -E bash $(pwd)/density/footprint_data.sh
    83  }
    84  
    85  export CONTAINERD_RUNTIME=io.containerd.kata.v2
    86  run
    87  ```