docs/testing/user/configguide/tools.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. (c) OPNFV, Intel Corporation, Spirent, AT&T and others.
   4
   5 .. _additional-tools-configuration:
   6
   7 =============================================
   8 'vsperf' Additional Tools Configuration Guide
   9 =============================================
  10
  11 Overview
  12 --------
  13
  14 VSPERF supports the following categories additional tools:
  15
  16   * `Infrastructure Metrics Collectors`_
  17   * `Load Generators`_
  18   * `L3 Cache Management`_
  19
  20 Under each category, there are one or more tools supported by VSPERF.
  21 This guide provides the details of how to install (if required)
  22 and configure the above mentioned tools.
  23
  24 .. _`Infrastructure Metrics Collectors`:
  25
  26 Infrastructure Metrics Collection
  27 ---------------------------------
  28
  29 VSPERF supports following two tools for collecting and reporting the metrics:
  30
  31 * pidstat
  32 * collectd
  33
  34 *pidstat* is a command in linux systems, which is used for monitoring individual
  35 tasks currently being managed by Linux kernel.  In VSPERF this command is used to
  36 monitor *ovs-vswitchd*, *ovsdb-server* and *kvm* processes.
  37
  38 *collectd* is linux application that collects, stores and transfers various system
  39 metrics. For every category of metrics, there is a separate plugin in collectd. For
  40 example, CPU plugin and Interface plugin provides all the cpu metrics and interface
  41 metrics, respectively. CPU metrics may include user-time, system-time, etc., whereas
  42 interface metrics may include received-packets, dropped-packets, etc.
  43
  44 Installation
  45 ^^^^^^^^^^^^
  46
  47 No installation is required for *pidstat*, whereas, collectd has to be installed
  48 separately. For installation of collectd, we recommend to follow the process described
  49 in *OPNFV-Barometer* project, which can be found here `Barometer-Euphrates <http://docs.opnfv.org/en/stable-euphrates/submodules/barometer/docs/release/userguide/feature.userguide.html#building-all-barometer-upstreamed-plugins-from-scratch>`_ or the most
  50 recent release.
  51
  52 VSPERF assumes that collectd is installed and configured to send metrics over localhost.
  53 The metrics sent should be for the following categories: CPU, Processes, Interface,
  54 OVS, DPDK, Intel-RDT.
  55
  56 For multicmd, apart from collectd, installation of PROX is also necessary.
  57 Installation steps for PROX can be found here - `DPPD-PROX <https://github.com/opnfv/samplevnf/tree/master/VNFs/DPPD-PROX>`_
  58
  59 Configuration
  60 ^^^^^^^^^^^^^
  61
  62 The configuration file for the collectors can be found in **conf/05_collector.conf**.
  63 *pidstat* specific configuration includes:
  64
  65 * ``PIDSTAT_MONITOR`` - processes to be monitored by pidstat
  66 * ``PIDSTAT_OPTIONS`` - options which will be passed to pidstat command
  67 * ``PIDSTAT_SAMPLE_INTERVAL`` - sampling interval used by pidstat to collect statistics
  68 * ``LOG_FILE_PIDSTAT`` - prefix of pidstat's log file
  69
  70 The *collectd* configuration option includes:
  71
  72 * ``COLLECTD_IP``  - IP address where collectd is running
  73 * ``COLLECTD_PORT``  - Port number over which collectd is sending the metrics
  74 * ``COLLECTD_SECURITY_LEVEL``  - Security level for receiving metrics
  75 * ``COLLECTD_AUTH_FILE`` - Authentication file for receiving metrics
  76 * ``LOG_FILE_COLLECTD`` - Prefix for collectd's log file.
  77 * ``COLLECTD_CPU_KEYS`` - Interesting metrics from CPU
  78 * ``COLLECTD_PROCESSES_KEYS`` - Interesting metrics from processes
  79 * ``COLLECTD_INTERFACE_KEYS`` - Interesting metrics from interface
  80 * ``COLLECTD_OVSSTAT_KEYS`` - Interesting metrics from OVS
  81 * ``COLLECTD_DPDKSTAT_KEYS`` - Interesting metrics from DPDK.
  82 * ``COLLECTD_INTELRDT_KEYS`` - Interesting metrics from Intel-RDT
  83 * ``COLLECTD_INTERFACE_XKEYS`` - Metrics to exclude from Interface
  84 * ``COLLECTD_INTELRDT_XKEYS`` - Metrics to exclude from Intel-RDT
  85 * ``MC_COLLECTD_CSV`` - Path where collectd writes its metrics as CSV.
  86 * ``MC_COLLECTD_CMD`` - Path where Collectd is installed
  87 * ``MC_PROX_HOME`` - Path where PROX-IRQ is installed.
  88 * ``MC_PROX_CMD`` - Command to run PROX-IRQ
  89 * ``MC_PROX_OUT`` - Output file generated by PROX-IRQ stats collector.
  90 * ``MC_CRON_OUT`` - Output file path of the command run through CROND
  91 * ``MC_BEAT_CFILE`` - Filebeat configuration file path.
  92
  93
  94 .. _`Load Generators`:
  95
  96
  97 Load Generation
  98 ---------------
  99
 100 In VSPERF, load generation refers to creating background cpu and memory loads to
 101 study the impact of these loads on system under test. There are two options to
 102 create loads in VSPERF. These options are used for different use-cases. The options are:
 103
 104 * stress or stress-ng
 105 * Stressor-VMs
 106
 107 *stress and stress-ng* are linux tools to stress the system in various ways.
 108 It can stress different subsystems such as CPU and memory. *stress-ng* is the
 109 improvised version of *stress*. StressorVMs are custom build virtual-machines
 110 for the noisy-neighbor use-cases.
 111
 112 Installation
 113 ^^^^^^^^^^^^
 114
 115 stress and stress-ng can be installed through standard linux installation process.
 116 Information about stress-ng, including the steps for installing can be found
 117 here: `stress-ng <https://github.com/ColinIanKing/stress-ng>`_
 118
 119 There are two options for StressorVMs - one is VMs based on stress-ng and second
 120 is VM based on Spirent's cloudstress. VMs based on stress-ng can be found in this
 121 `link <https://github.com/opensource-tnbt/stressng-images>`_ . Spirent's cloudstress
 122 based VM can be downloaded from this `site <https://github.com/spirent/cloudstress>`_
 123
 124 These stressorVMs are of OSV based VMs, which are very small in size. Download
 125 these VMs and place it in appropriate location, and this location will used in
 126 the configuration - as mentioned below.
 127
 128 Configuration
 129 ^^^^^^^^^^^^^
 130
 131 The configuration file for loadgens can be found in **conf/07_loadgen.conf**.
 132 There are no specific configurations for stress and stress-ng commands based
 133 load-generation. However, for StressorVMs, following configurations apply:
 134
 135 * ``NN_COUNT``  - Number of stressor VMs required.
 136 * ``NN_MEMORY``  - Comma separated memory configuration for each VM
 137 * ``NN_SMP``  -  Comma separated configuration for each VM
 138 * ``NN_IMAGE``  -  Comma separated list of Paths for each VM image
 139 * ``NN_SHARED_DRIVE_TYPE``  - Comma separated list of shaed drive type for each VM
 140 * ``NN_BOOT_DRIVE_TYPE``  - Comma separated list of boot drive type for each VM
 141 * ``NN_CORE_BINDING``  -  Comma separated lists of list specifying the cores associated with each VM.
 142 * ``NN_NICS_NR``  -  Comma seprated list of number of NICS for each VM
 143 * ``NN_BASE_VNC_PORT``  -  Base VNC port Index.
 144 * ``NN_LOG_FILE``  - Name of the log file
 145
 146 .. _`L3 Cache Management`:
 147
 148 Last Level Cache Management
 149 ---------------------------
 150
 151 VSPERF support last-level cache management using Intel's RDT tool(s) - the
 152 relavant ones are `Intel CAT-CMT <https://github.com/intel/intel-cmt-cat>`_ and
 153 `Intel RMD <https://github.com/intel/rmd>`_. RMD is a linux daemon that runs on
 154 individual hosts, and provides a REST API for control/orchestration layer to
 155 request LLC for the VMs/Containers/Applications. RDT receives resource policy
 156 form orchestration layer - in this case, from VSPERF - and enforce it on the host.
 157 It achieves this enforcement via kernel interfaces such as resctrlfs and libpqos.
 158 The resource here refer to the last-level cache. User can configure policies to
 159 define how much of cache a CPU can get. The policy configuration is described below.
 160
 161 Installation
 162 ^^^^^^^^^^^^
 163
 164 For installation of RMD tool, please install CAT-CMT first and then install RMD.
 165 The details of installation can be found here: `Intel CAT-CMT <https://github.com/intel/intel-cmt-cat>`_
 166 and `Intel RMD <https://github.com/intel/rmd>`_
 167
 168 Configuration
 169 ^^^^^^^^^^^^^
 170
 171 The configuration file for cache management can be found in **conf/08_llcmanagement.conf**.
 172
 173 VSPERF provides following configuration options, for user to define and enforce policies via RMD.
 174
 175 * ``LLC_ALLOCATION`` - Enable or Disable LLC management.
 176 * ``RMD_PORT`` - RMD port (port number on which API server is listening)
 177 * ``RMD_SERVER_IP`` - IP address where RMD is running. Currently only localhost.
 178 * ``RMD_API_VERSION`` - RMD version. Currently it is 'v1'
 179 * ``POLICY_TYPE`` - Specify how the policy is defined - either COS or CUSTOM
 180 * ``VSWITCH_COS`` - Class of service (CoS for Vswitch. CoS can be gold, silver-bf or bronze-shared.
 181 * ``VNF_COS``  - Class of service for VNF
 182 * ``PMD_COS`` - Class of service for PMD
 183 * ``NOISEVM_COS`` - Class of service of Noisy VM.
 184 * ``VSWITCH_CA`` - [min-cache-value, maxi-cache-value] for vswitch
 185 * ``VNF_CA`` - [min-cache-value, max-cache-value] for VNF
 186 * ``PMD_CA`` - [min-cache-value, max-cache-value] for PMD
 187 * ``NOISEVM_CA`` - [min-cache-value, max-cache-value] for Noisy VM
 188
 189 VSPERF Containers
 190 -----------------
 191
 192 VSPERF containers are found in tools/docker folder.
 193
 194 RESULTS CONTAINER
 195 ^^^^^^^^^^^^^^^^^
 196
 197 The results container includes multiple services - ELK Stack, Barometer-Grafana, OPNFV-TestAPI & Jupyter.
 198
 199 Pre-Deployment Configuration
 200 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 201
 202 1. Set the limit on mmap counts equal to 262144 or more.
 203    You can do this by the command - ``sysctl -w vm.max_map_count = 262144``.
 204    Or to set it permanently, update the ``vm.max_map_count`` field in ``/etc/sysctl.conf``.
 205
 206 2. You may want to modify the IP address from 0.0.0.0 to appropriate host-ip in ``docker-compose.yml``
 207
 208 3. Please add dashboards folder from OPNFV-Barometer-Grafana into the grafana folder. It can be found in `Barometer Grafana <https://github.com/opnfv/barometer/tree/master/docker/barometer-grafana`
 209
 210 Build
 211 ~~~~~
 212
 213 Run ``docker-compose build`` command to build the container.
 214
 215 Run
 216 ~~~
 217
 218 Run the container with ``docker-compose up`` command.
 219
 220 Post-Deployment Configuration
 221 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 222
 223 The directory ``resultsdb`` contains the source from Dovetail/Dovetail-webportal project.
 224 Once the results container is deployed, please run the python script as follows, to ensure that results can be
 225 pushed and queried correctly - ``python init_db.py host_ip_address testapi_port``.
 226 For example, if the host on which the container is running is 10.10.120.22, and container is exposing 8000 as the port,
 227 the command should be: ``python init_db.py 10.10.120.22 8000``