docs/development/devtools/apex-s3p.rst

   1 .. This work is licensed under a
   2 .. Creative Commons Attribution 4.0 International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4
   5 .. _apex-s3p-label:
   6
   7 .. toctree::
   8    :maxdepth: 2
   9
  10 Policy APEX PDP component
  11 ~~~~~~~~~~~~~~~~~~~~~~~~~
  12
  13 Setting up Stability Tests in APEX
  14 ++++++++++++++++++++++++++++++++++
  15
  16 Introduction
  17 ------------
  18
  19 The 72 hour Stability Test for apex-pdp has the goal of introducing a steady flow of transactions initiated from a test client server running JMeter. The pdp is configured to start a rest server inside it and take input from rest clients (JMeter) and send back output to the rest clients (JMeter).
  20
  21 The input events will be submitted through rest interface of apex-pdp and the results are verified using the rest responses coming out from apex-pdp.
  22
  23 The test will be performed in a multi-threaded environment where 20 threads running in JMeter will keep sending events to apex-pdp in every 500 milliseconds for the duration of 72 hours.
  24
  25 Setup details
  26 -------------
  27
  28 The stability test is performed on VM's running in OpenStack cloud environment. There are 2 seperate VM's, one for running apex pdp & other one for running JMeter to simulate steady flow of transactions.
  29
  30 **OpenStack environment details**
  31
  32 Version: Mitaka
  33
  34 **apex-pdp VM details**
  35
  36 OS:Ubuntu 16.04.5 LTS
  37
  38 CPU: 4 core
  39
  40 RAM: 4 GB
  41
  42 HardDisk: 40 GB
  43
  44 Docker Version: 18.06.1-ce, build e68fc7a
  45
  46 Java: openjdk version "1.8.0_181"
  47
  48 **JMeter VM details**
  49
  50 OS: Ubuntu 16.04.3 LTS
  51
  52 CPU: 4 core
  53
  54 RAM: 4 GB
  55
  56 HardDisk: 40 GB
  57
  58 Java: openjdk version "1.8.0_181"
  59
  60 JMeter: 5.1.1
  61
  62 Install JMeter in virtual machine
  63 ---------------------------------
  64
  65 Make the etc/hosts entries
  66
  67 .. code-block:: bash
  68
  69     echo $(hostname -I | cut -d\  -f1) $(hostname) | sudo tee -a /etc/hosts
  70
  71 Make the DNS entries
  72
  73 .. code-block:: bash
  74
  75     echo "nameserver <PrimaryDNSIPIP>" >> sudo /etc/resolvconf/resolv.conf.d/head
  76
  77     echo "nameserver <SecondaryDNSIP>" >> sudo /etc/resolvconf/resolv.conf.d/head
  78
  79     resolvconf -u
  80
  81 Update the ubuntu software installer
  82
  83 .. code-block:: bash
  84
  85     apt-get update
  86
  87 Check & Install Java
  88
  89 .. code-block:: bash
  90
  91     apt-get install -y openjdk-8-jdk
  92
  93     java -version
  94
  95 Download & install JMeter
  96
  97 .. code-block:: bash
  98
  99     mkdir jMeter
 100
 101
 102     cd jMeter
 103
 104
 105     wget http://mirrors.whoishostingthis.com/apache//jmeter/binaries/apache-jmeter-5.1.1.zip
 106
 107
 108     unzip apache-jmeter-5.1.1.zip
 109
 110 Install apex-pdp in virtual machine
 111 -----------------------------------
 112
 113 We will be running apex-pdp as docker container. So we need to first install docker and then create the container hosting apex-pdp by pulling the image from ONAP repository.
 114
 115 **Docker Installation**
 116
 117 1. Make the etc/hosts entries
 118
 119 .. code-block:: bash
 120
 121     echo $(hostname -I | cut -d\  -f1) $(hostname) | sudo tee -a /etc/hosts
 122
 123 2. Make the DNS entries
 124
 125 .. code-block:: bash
 126
 127     echo "nameserver <PrimaryDNSIPIP>" >> sudo /etc/resolvconf/resolv.conf.d/head
 128     echo "nameserver <SecondaryDNSIP>" >> sudo /etc/resolvconf/resolv.conf.d/head
 129     resolvconf -u
 130
 131 3. Update the ubuntu software installer
 132
 133 .. code-block:: bash
 134
 135     apt-get update
 136
 137 4. Check and Install Java
 138
 139 .. code-block:: bash
 140
 141     apt-get install -y openjdk-8-jdk
 142     java -version
 143
 144 Ensure that the Java version that is executing is OpenJDK version 8
 145
 146 5. Check and install docker
 147
 148 .. code-block:: bash
 149
 150     curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
 151     add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
 152     apt-get update
 153     apt-cache policy docker-ce
 154     apt-get install -y docker-ce
 155     systemctl status docker
 156     docker ps
 157
 158 6. Change the permissions of the Docker socket file
 159
 160 .. code-block:: bash
 161
 162     chmod 777 /var/run/docker.sock
 163
 164 7. Check the status of the Docker service and ensure it is running correctly
 165
 166 .. code-block:: bash
 167
 168     service docker status
 169     docker ps
 170
 171 **Install apex-pdp**
 172
 173 Run the below command to create the container hosting apex-pdp by pulling the image from ONAP repository.
 174
 175 .. code-block:: bash
 176
 177     docker run -d --name apex -p 12561:12561 -p 23324:23324 -it nexus3.onap.org:10001/onap/policy-apex-pdp:2.1.0-latest /bin/bash -c "/opt/app/policy/apex-pdp/bin/apexApps.sh jmx-test -c /opt/app/policy/apex-pdp/examples/config/SampleDomain/RESTServerJsonEvent.json"
 178     docker ps
 179
 180 Note: If you observe that requests from JMeter client is failing due to timeout, then modify the "RESTServerJsonEvent.json" mentioned in the above command and increase the "synchronousTimeout" property as per needed.
 181
 182 Install & Configure VisualVM
 183 ----------------------------
 184
 185 VisualVM needs to be installed in the virtual machine having apex-pdp. It will be used to monitor CPU, Memory, GC for apex-pdp while stability test is running.
 186
 187 Install visualVM
 188
 189 .. code-block:: bash
 190
 191     sudo apt-get install visualvm
 192
 193 Login to docker container (using root)
 194
 195 .. code-block:: bash
 196
 197     docker exec -u 0 -it apex /bin/bash
 198
 199 Run few commands to configure permissions
 200
 201 .. code-block:: bash
 202
 203     cd /usr/lib/jvm/java-1.8-openjdk/bin/
 204
 205     touch visualvm.policy
 206
 207     vi visualvm.policy
 208
 209     Add the following in visualvm.policy
 210
 211
 212     grant codebase "file:/usr/lib/jvm/java-1.8-openjdk/lib/tools.jar" {
 213        permission java.security.AllPermission;
 214     };
 215
 216
 217     chmod 777 visualvm.policy
 218
 219
 220     exit
 221
 222 Login to docker container (using normal user)
 223
 224 .. code-block:: bash
 225
 226     docker exec -it apex /bin/bash
 227
 228 Run following commands to start jstatd using port 1111
 229
 230 .. code-block:: bash
 231
 232     cd /usr/lib/jvm/java-1.8-openjdk/bin/
 233
 234
 235     ./jstatd -p 1111 -J-Djava.security.policy=visualvm.policy  &
 236
 237
 238     exit
 239
 240 Login to VM using graphical interface in separate terminal window.
 241
 242 .. code-block:: bash
 243
 244     ssh -X <user>@<VM-IP-ADDRESS>
 245
 246 Open visualVM
 247
 248 .. code-block:: bash
 249
 250     visualvm &
 251
 252 Connect to jstatd & remote apex-pdp JVM
 253
 254 1. Right click on "Remote" in the left panel of the screen and select "Add Remote Host..."
 255
 256 2. Enter the IP address of apex-pdp docker container.
 257
 258 .. code-block:: bash
 259
 260     docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' container_name_or_id
 261
 262 3. Right click on IP address, select "Add jstatd Connection..."
 263 4. In "jstatd Connections" tab, enter port 1111 and click OK.
 264 5. Right click on IP address, select "Add JMX Connection..."
 265 6. Enter the apex-pdp docker container IP Address (from step 2) <IP address>:9911 ( for example - 172.17.0.2:9911) and click OK.
 266 7. Double click on the newly added nodes under "Remote" to start monitoring CPU, Memory & GC.
 267
 268 Sample Screenshot of visualVM
 269
 270 .. image:: images/apex-s3p-vvm-sample.jpg
 271
 272 Test Plan
 273 ---------
 274
 275 The 72 hours stability test will run the following steps in 20 threaded loop.
 276
 277 - **Send Input Event** - sends an input message to rest interface of apex-pdp.
 278 - **Assert Response Code** - assert the response code coming from apex-pdp.
 279 - **Assert Response Message** - assert the response message coming from apex-pdp.
 280
 281 The following steps can be used to configure the parameters of test plan.
 282
 283 - **HTTP Header Manager** - used to store headers which will be used for making HTTP requests.
 284 - **HTTP Request Defaults** -  used to store HTTP request details like Server Name or IP, Port, Protocol etc.
 285 - **User Defined Variables** -  used to store following user defined parameters.
 286
 287 ==================  ============================================================================  ============================
 288 **Name**            **Description**                                                               **Default Value**
 289 ==================  ============================================================================  ============================
 290 wait                Wait time after each request (in milliseconds)                                500
 291 threads             Number of threads to run test cases in parallel.                              20
 292 threadsTimeOutInMs  Synchronization timer for threads running in parallel (in milliseconds).      5000
 293 ==================  ============================================================================  ============================
 294
 295
 296 Download and update the jmx file presented in the apex-pdp git repository - `jmx file path <https://gerrit.onap.org/r/gitweb?p=policy/apex-pdp.git;a=tree;f=testsuites/apex-pdp-stability/src/main/resources;h=99d373033a190a690d4e05012bc3a656cae7bc3f;hb=refs/heads/master>`_.
 297
 298 - HTTPSampler.domain - The ip address of VM which the apex container is running
 299 - HTTPSampler.port - The  listening port, here is 23324
 300 - ThreadGroup.druation - Set the duration to 72 hours (in seconds)
 301
 302 Use the CLI mode to start the test
 303
 304 .. code-block:: bash
 305
 306     ./jmeter.sh -n -t ~/apexPdpStabilityTestPlan.jmx -Jusers=1 -l ~/stability.log
 307
 308 Stability Test Result
 309 ---------------------
 310
 311 **Summary**
 312
 313 Stability test plan was triggered for 72 hours injecting input events to apex-pdp from 20 client threads running in JMeter.
 314
 315 After the test stop, we can generate a HTML test report via command
 316
 317 .. code-block:: bash
 318
 319     ~/jMeter/apache-jmeter-5.1.1/bin/jmeter -g stability.log -o ./result/
 320
 321 ==============================================  ===================================================  ================================  =============  ============
 322 **Number of Client Threads running in JMeter**  **Number of Server Threads running in Apex engine**  **Total number of input events**  **Success %**  **Error %**
 323 ==============================================  ===================================================  ================================  =============  ============
 324 20                                              4                                                    6394602                           99.999971%     0.0029%
 325 ==============================================  ===================================================  ================================  =============  ============
 326
 327 :download:`result.zip <zip/result.zip>`
 328 :download:`onap.zip <zip/onap.zip>`
 329
 330
 331 Setting up Performance Tests in APEX
 332 ++++++++++++++++++++++++++++++++++++
 333
 334 The apex-pdp has built in support for performance testing. A special performance testing REST server is available in the code base for performance testing.
 335 It is in the module `performance-benchmark-test <https://github.com/onap/policy-apex-pdp/tree/master/testsuites/performance/performance-benchmark-test>`_.
 336 To execute a benchmark test, you start the REST server, and then configure and run APEX against the server.
 337 There are example configurations for running tests in the `resources of this module <https://github.com/onap/policy-apex-pdp/tree/master/testsuites/performance/performance-benchmark-test/src/main/resources/examples/benchmark>`_.
 338
 339 In order to run the test for 72 hours, set the batch count in the `EventGeneratorConfig.json <https://github.com/onap/policy-apex-pdp/blob/master/testsuites/performance/performance-benchmark-test/src/main/resources/examples/benchmark/EventGeneratorConfig.json>`_ file to zero, which causes the REST server to generate batches forever.
 340
 341 Here is an example of how to do this:
 342
 343 1. Clone and build the apex-pdp git repo
 344
 345 2. Go into the performance-benchmark-test module and run the REST server
 346
 347 .. code-block:: bash
 348
 349     cd testsuites/performance/performance-benchmark-test
 350     mvn exec:java -Dexec.mainClass="org.onap.policy.apex.testsuites.performance.benchmark.eventgenerator.EventGenerator" -Dexec.args="-c  src/main/resources/examples/benchmark/EventGeneratorConfig.json"
 351
 352 3. Separately, create a local directory and unzip the APEX tarball
 353
 354 .. code-block:: bash
 355
 356     mkdir apex
 357     cd apex
 358     tar zxvf ~/git/onap/policy/apex-pdp/packages/apex-pdp-package-full/target/*gz
 359
 360 4. Run APEX with a configuration that runs against the benchmark REST server, select the configuration that is appropriate for the number of threads for the number of cores on the host on which APEX is running. For example on a 32 core machine, select the "32" configuration, on an 8 core machine, select the "08" configuration.
 361
 362 .. code-block:: bash
 363
 364     bin/apexApps.sh engine -c ~/git/onap/policy/apex-pdp/testsuites/performance/performance-benchmark-test/src/main/resources/examples/benchmark/Javascript64.json
 365
 366 5. To get the test results, Issue the following command using CURL or from a browser(also can store the result into a file by setting outfile in the `EventGeneratorConfig.json <https://github.com/onap/policy-apex-pdp/blob/master/testsuites/performance/performance-benchmark-test/src/main/resources/examples/benchmark/EventGeneratorConfig.json>`_ file, statistics would be written into this file after event generator terminated)
 367
 368 .. code-block:: bash
 369
 370     curl http://localhost:32801/EventGenerator/Stats
 371
 372 The results are similar to those below:
 373
 374 :download:`Example APEX performance metrics <json/example-apex-perf.json>`
 375
 376 Performance Test Result
 377 -----------------------
 378
 379 **Summary**
 380
 381 Performance test was triggered for 2 hours on a 4 core, 4GB RAM virtual machine.
 382
 383 **Test Statistics**
 384
 385 :download:`Attached result log <json/result.json>`
 386
 387 ===============  =============  =================  ==============  =====================  ==================  =============  ===========
 388 **batchNumber**  **batchSize**  **eventsNotSent**  **eventsSent**  **eventsNotReceived**  **eventsReceived**  **Success %**  **Error %**
 389 ===============  =============  =================  ==============  =====================  ==================  =============  ===========
 390 3650             182500         0                  182500          0                      182500              100 %          0 %
 391 ===============  =============  =================  ==============  =====================  ==================  =============  ===========
 392
 393 ========================  =========================  ========================
 394 **averageRoundTripNano**  **shortestRoundTripNano**  **longestRoundTripNano**
 395 ========================  =========================  ========================
 396 40024623                  7439158                    5161374486
 397 ========================  =========================  ========================
 398
 399 ============================  =============================  ============================
 400 **averageApexExecutionNano**  **shortestApexExecutionNano**  **longestApexExecutionNano**
 401 ============================  =============================  ============================
 402 1335622                       513650                         5104326434
 403 ============================  =============================  ============================