web_winrunner

Introducing Tivoli Application Performance Management Dinesh Kumar, Mohamed Dawood, Vasfi Gucer, Kai Lueke International Technical Support Organization www.redbooks.ibm.com SG24-5508-00 SG24-5508-00 International Technical Support Organization Introducing Tivoli Application Performance Management December 1999 Take Note! Before using this information and the product it supports, be sure to read the general information in Appendix D, “Special notices” on page 211. First Edition (December 1999) This edition applies to Tivoli Application Performance Management Version 1 , Release Number 1 Note This book is based on a pre-GA version of a product and may not apply when the product becomes generally available. We recommend that you consult the product documentation or follow-on versions of this redbook for more current information. Comments may be addressed to: IBM Corporation, International Technical Support Organization Dept. 0SJB Building 003 Internal Zip 2834 11400 Burnet Road Austin, Texas 78758-3493 When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you. © Copyright International Business Machines Corporation 1999. All rights reserved. Note to U.S Government Users – Documentation related to restricted rights – Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp. Contents Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .ix Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv The team that wrote this redbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv Comments welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii Part 1. TAPM concepts and environment setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Chapter 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 1.1 Why application performance management? . . . . . 1.1.1 Measuring service levels . . . . . . . . . . . . . . . . 1.2 Techniques for measuring application performance 1.2.1 Application instrumentation. . . . . . . . . . . . . . . 1.2.2 Transaction simulation . . . . . . . . . . . . . . . . . . 1.2.3 Client capture . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.4 Network X-ray. . . . . . . . . . . . . . . . . . . . . . . . . 1.3 Tivoli’s solution for application performance . . . . . . 1.3.1 An integrated system management solution . . 1.3.2 TAPM overview . . . . . . . . . . . . . . . . . . . . . . . 1.3.3 Response time measurement . . . . . . . . . . . . . 1.3.4 Performance analysis and reporting . . . . . . . . 1.4 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 . .3 . .4 . .5 . .6 . .7 . .7 . .7 . .8 . .9 . 10 . 12 . 12 . 13 . 15 . 15 . 16 . 16 . 17 . 24 . 29 . 30 . 31 . 31 . 32 . 34 . 36 . 38 . 38 Chapter 2. The planning and instrumenting process . . . . 2.1 Plan what to instrument . . . . . . . . . . . . . . . . . . . . . . . . . 2.2 The instrumentation process . . . . . . . . . . . . . . . . . . . . . 2.2.1 Application response time measurement . . . . . . . . 2.2.2 Application instrumentation. . . . . . . . . . . . . . . . . . . 2.2.3 Transaction simulation . . . . . . . . . . . . . . . . . . . . . . 2.2.4 Overview ARM, WinRunner, and VuGen functions . 2.3 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 3. Installing and setting up TAPM . . . . . . . . . . . . 3.1 TAPM prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 Creating the Tivoli environment . . . . . . . . . . . . . . . . . . . 3.3 TAPM database setup . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4 Configuration of the TAPM environment . . . . . . . . . . . . . 3.5 TAPM installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.1 Installing on the TMR server and endpoint gateway © Copyright IBM Corp. 1999 iii 3.5.2 Installing on the endpoint . . . . . . . . . . . . . . . . . . 3.6 Uninstalling TAPM . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1 Running the uninstall script. . . . . . . . . . . . . . . . . 3.6.2 Manually uninstalling TAPM files and directories 3.7 TAPM configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.1 Updating managed resources . . . . . . . . . . . . . . . 3.7.2 Notice group modification . . . . . . . . . . . . . . . . . . 3.7.3 Creating the RIM object . . . . . . . . . . . . . . . . . . . 3.7.4 Installing the TAPM database . . . . . . . . . . . . . . . 3.8 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 . 49 . 49 . 50 . 51 . 51 . 52 . 54 . 56 . 57 . 59 . 59 . 60 . 61 . 62 . 63 . 63 . 63 . 64 . 64 . 69 . 70 . 73 . 73 . 73 . 75 . 77 . 77 . 78 . 78 . 80 . 82 . 85 . 86 . 86 . 88 . 89 . 92 . 94 Chapter 4. Sample application instrumentation . . . . . . . . . . . 4.1 The Software Developer's Kit (SDK) . . . . . . . . . . . . . . . . . . . 4.2 ARM function calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2.1 The ARM API call syntax . . . . . . . . . . . . . . . . . . . . . . . 4.2.2 Return codes from ARM API calls. . . . . . . . . . . . . . . . . 4.2.3 Good handles and return codes . . . . . . . . . . . . . . . . . . 4.2.4 Bad handles and return codes . . . . . . . . . . . . . . . . . . . 4.2.5 Case sensitivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3 Create an ARM-instrumented C application . . . . . . . . . . . . . 4.3.1 Adding ARM function calls . . . . . . . . . . . . . . . . . . . . . . 4.3.2 Compile and link the instrumented application . . . . . . . 4.3.3 Testing the application . . . . . . . . . . . . . . . . . . . . . . . . . 4.4 Using other languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.5 Implementing ARM calls using languages other than C . . . . 4.5.1 Making ARM API calls from PowerBuilder applications . 4.6 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 5. Sample script creation using WinRunner . 5.1 WinRunner installation . . . . . . . . . . . . . . . . . . . . . . . 5.1.1 System requirements . . . . . . . . . . . . . . . . . . . . 5.1.2 Installation process. . . . . . . . . . . . . . . . . . . . . . 5.2 GUI map creation . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3 Recording a script . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3.1 GUI map consolidation . . . . . . . . . . . . . . . . . . . 5.4 Verify script execution . . . . . . . . . . . . . . . . . . . . . . . 5.4.1 Loading GUI map . . . . . . . . . . . . . . . . . . . . . . . 5.4.2 Script execution . . . . . . . . . . . . . . . . . . . . . . . . 5.5 Preparing script for TAPM . . . . . . . . . . . . . . . . . . . . 5.5.1 Script execution with implemented ARM calls . . 5.6 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 6. Sample script creation for LoadRunner . . . . . . . . . . . . . . . 95 6.1 LoadRunner installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 iv Introducing Tivoli Application Performance Management 6.1.1 System requirements . . . . . 6.1.2 VuGen installation . . . . . . . 6.1.3 Robotic Client installation . . 6.2 Recording a business process . . 6.3 Passing parameters to script . . . 6.4 Script execution and verification . 6.4.1 Run-time settings . . . . . . . . 6.4.2 Vuser script execution . . . . 6.5 Preparing a script for TAPM . . . . 6.6 Summary . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 . . 96 . . 97 . . 98 . 101 . 105 . 105 . 110 . 112 . 114 . 115 . 115 . 116 . 116 . 116 . 117 . 120 . 122 . 125 . 128 Chapter 7. Sample script creation using QuickTest for R/3 . 7.1 Installing WinRunner QuickTest for R/3 . . . . . . . . . . . . . . . 7.1.1 System requirements . . . . . . . . . . . . . . . . . . . . . . . . . 7.1.2 QuickTest installation . . . . . . . . . . . . . . . . . . . . . . . . . 7.1.3 Robotic Client installation . . . . . . . . . . . . . . . . . . . . . . 7.2 Recording a business process . . . . . . . . . . . . . . . . . . . . . . 7.3 Verify script execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.4 Preparing a script for TAPM . . . . . . . . . . . . . . . . . . . . . . . . 7.4.1 Script execution with implemented ARM calls . . . . . . . 7.5 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Part 2. TAPM configuration and monitoring applications . . . . . . . . . . . . . . . . . . . . . 129 Chapter 8. Registration, profile creation, and distribution . . . . . 8.1 Registering applications and virtual user scripts . . . . . . . . . . . . . 8.1.1 Registration of virtual user scripts. . . . . . . . . . . . . . . . . . . . 8.1.2 Registration of an ARM-instrumented application . . . . . . . . 8.2 Profile creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.2.1 Modifying the managed resources . . . . . . . . . . . . . . . . . . . 8.2.2 Creating a profile manager . . . . . . . . . . . . . . . . . . . . . . . . . 8.2.3 Creating a TAPM profile . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.3 Simulated transaction settings . . . . . . . . . . . . . . . . . . . . . . . . . . 8.4 ARMed application settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.5 Profile distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.6 Verifying the distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.6.1 Using wmar commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.7 Log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.8 Performance data collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.8.1 Data collection process . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.8.2 The aggregation and uploading process . . . . . . . . . . . . . . . 8.8.3 Using the trace log files to confirm aggregation and upload 8.8.4 Forcing the upload process manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 . 131 . 131 . 133 . 133 . 134 . 134 . 135 . 136 . 141 . 142 . 144 . 145 . 146 . 147 . 148 . 149 . 150 . 153 v 8.9 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 Chapter 9. Reporting performance data . . . . . . . . . . . 9.1 Installing the TDS guide . . . . . . . . . . . . . . . . . . . . . . 9.2 Set up TDS for TAPM . . . . . . . . . . . . . . . . . . . . . . . . 9.3 TDS cubes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.4 Building the cube . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.5 Using the guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.5.1 Topics and views . . . . . . . . . . . . . . . . . . . . . . . 9.5.2 View the data with the TDS Discovery Interface 9.5.3 Sample views . . . . . . . . . . . . . . . . . . . . . . . . . . 9.6 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 10. Alerting on response time problems . . 10.1 Installing TAPM monitors . . . . . . . . . . . . . . . . . . 10.2 Creating a distributed monitoring profile . . . . . . . 10.3 Setting subscribers to the profile . . . . . . . . . . . . 10.4 Editing the profile . . . . . . . . . . . . . . . . . . . . . . . . 10.5 Distributing the profile . . . . . . . . . . . . . . . . . . . . 10.6 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 . 157 . 157 . 162 . 164 . 165 . 165 . 168 . 169 . 178 . 179 . 179 . 179 . 181 . 182 . 185 . 186 . . . . . . . . . 187 187 187 188 189 190 191 192 193 Appendix A. Developer’s Kit for application instrumentation . . . . . A.1 SDK installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.2 The ARM API call syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.2.1 arm_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.2.2 arm_getid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.2.3 arm_start. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.2.4 arm_update. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.2.5 arm_stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A.2.6 arm_end . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Appendix B. wmar commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Appendix C. Source file listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 C.1 Sample2.c. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 C.2 Armtest1.exe. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 Appendix D. Special notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 Appendix E. Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 E.1 IBM Redbooks publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 E.2 IBM Redbooks collections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 E.3 Other resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 vi Introducing Tivoli Application Performance Management How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 IBM Redbook Fax Order Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 List of abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 IBM Redbooks evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 vii viii Introducing Tivoli Application Performance Management Figures 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. 39. 40. End user having trouble in a complex IT environment. . . . . . . . . . . . . . . . . 4 Response time measurement techniques . . . . . . . . . . . . . . . . . . . . . . . . . . 6 TAPM approach to performance management . . . . . . . . . . . . . . . . . . . . . . 9 Overview TAPM in the Tivoli environment . . . . . . . . . . . . . . . . . . . . . . . . . 10 TAPM overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 ARM API agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Placement of ARM calls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Transaction correlation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Transaction simulation (SAP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 VuGen trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Tivoli environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Database client installed on gateway. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 TAPM RIM host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 TAPM environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Installing a product. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Setting the installation media . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Selecting the product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 TAPM installation message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Installation complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Selecting the target for the monitor component . . . . . . . . . . . . . . . . . . . . . 44 Installation using Software Installation Service . . . . . . . . . . . . . . . . . . . . . 45 SIS initial menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 SIS Install details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Selecting the products from SIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Selection of machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Confirming products and targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Set Managed Resources window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Add notice group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Read notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Instrument an application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 arm_update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 init_metric_function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Forward buffer to ARM agent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Compiling process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Example logagent log file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 ARM API calls in a PowerBuilder script . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Declaring the external functions to PowerBuilder . . . . . . . . . . . . . . . . . . . 74 Resolving the ARM calls as PowerBuilder external functions . . . . . . . . . . 74 Winrunner welcome screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Selecting the window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 © Copyright IBM Corp. 1999 ix 41. 42. 43. 44. 45. 46. 47. 48. 49. 50. 51. 52. 53. 54. 55. 56. 57. 58. 59. 60. 61. 62. 63. 64. 65. 66. 67. 68. 69. 70. 71. 72. 73. 74. 75. 76. 77. 78. 79. 80. 81. 82. 83. Selecting tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Recording a script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Capturing the Status bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Document status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Merging GUI files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 GUI map editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Status window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 WinRunner function generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 WinRunner function generator Args. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 WinRunner script page 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 WinRunner script page 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Virtual User Generator window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 New virtual user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Program to record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Toolbar. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Recorded Web script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Parameterize script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 New parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Parameter list. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 File structure VuGen script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 Run-time settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Timing settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Automatic transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Iterations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Think time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 General settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Run toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Run and debug VuGen script. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Web VuGen script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 R/3 logon screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Logon process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Issuing a command in SAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Inserting/removing a break point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Execution Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 Inserting lr functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Inserting the application name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 Enable the sub-transaction option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Sample QuickTest script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 TAPM repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 Directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Updating the managed resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 Creating a profile manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 x Introducing Tivoli Application Performance Management 84. Profile Manager configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 85. Creating a MARProfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 86. Adding a simulation entry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 87. Scheduling information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 88. Simulation settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 89. Database settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 90. Table showing the level of detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 91. TAPM simulation profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 92. Adding an instrumented application entry . . . . . . . . . . . . . . . . . . . . . . . . 142 93. TAPM profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 94. Distributing a profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 95. wmargetdata display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 96. wmargetappreg display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 97. Data log collection on an endpoint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 98. The aggregation and uploading process . . . . . . . . . . . . . . . . . . . . . . . . . 150 99. TAPM gateway mar_trace.log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 100.ODBC setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 101.Selecting application performance management . . . . . . . . . . . . . . . . . . 159 102.Imported TAPM Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 103.Add data source 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 104.Add data source 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 105.Assign data source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 106.Date range. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 107.Cube transformation status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 108.Tivoli Discovery Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 109.Topics and views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 110.Average response time for all transactions-line view . . . . . . . . . . . . . . . 170 111.Average response time for all transactions-clustered bar view . . . . . . . . 171 112.Average response time for main_trans on 08/30/1999. . . . . . . . . . . . . . 172 113.Pie chart graph of average response time . . . . . . . . . . . . . . . . . . . . . . . 173 114.Average response times for the host dreden . . . . . . . . . . . . . . . . . . . . . 174 115.Average response times for each transaction for the host dreden . . . . . 175 116.Execution load by all users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 117.Execution load by user nicola . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 118.Execution load by user nicola for each transaction . . . . . . . . . . . . . . . . . 177 119.Creating a profile manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 120.DM_Profile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 121.Distributed monitoring profile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 122.Subscribing endpoint dresden.5 to the DM_TAPM profile. . . . . . . . . . . . 181 123.DM_TAPM profile with dresden.5 endpoint as its subscriber . . . . . . . . . 182 124.Selecting the average transaction response time monitor . . . . . . . . . . . 183 125.Edit monitor view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 126.Monitoring schedule screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 xi 127.Pop-up window from the monitor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 xii Introducing Tivoli Application Performance Management Tables 1. 2. 3. 4. 5. 6. 7. Functions . . . . . . . . . . . . . . . . TAPM components . . . . . . . . Supported RDBMS . . . . . . . . Hardware configuration . . . . . Software configuration . . . . . . Log file location . . . . . . . . . . . Trace components . . . . . . . . . ...... ...... ...... ...... ...... ...... ...... ....... ....... ....... ....... ....... ....... ....... ...... ...... ...... ...... ...... ...... ...... ....... ....... ....... ....... ....... ....... ....... ...... ...... ...... ...... ...... ...... ...... . . 29 . . 32 . . 35 . . 37 . . 38 . 147 . 154 © Copyright IBM Corp. 1999 xiii xiv Introducing Tivoli Application Performance Management Preface Application performance is quickly becoming the critical measure of service provided by IT departments to their users. To address this market and provide an end-to-end system management solution for its customers, Tivoli has introduced a new product called Tivoli Application Performance Management (TAPM). In this redbook, we introduce this exciting new offering. This redbook will help you understand the intricacies associated with application performance and the approach taken by Tivoli to overcome them with the TAPM product. Guidance and step-by-step directions plus hints and tips are provided to explain the complete functionality and features of TAPM. Actual examples are used throughout to illustrate how to interface with TAPM and utilize the features that it provides. These examples will assist you in performing similar application performance activities through TAPM in your environment. We provide the installation process for TAPM and Mercury Interactive’s WinRunner and LoadRunner products and then perform real-life scenarios managing transaction performance for applications. Since TAPM is shipped with out-of-the box measurement scripts for major ERP systems, we performed the performance measurement of an SAP application system. We also developed an approach for planning and implementing application performance management in production environments. Another exciting feature we investigated is the integration of TAPM with other Tivoli applications, such as Distributed Monitoring (DM), Tivoli Enterprise Console (TEC), and Tivoli Decision Support (TDS). TAPM provides a dedicated TDS Guide that allows reporting on performance and service levels as well as performance correlation between systems. A working knowledge of the Tivoli Management Framework and the Tivoli Managed Environment is assumed. The team that wrote this redbook This Redbook was produced by a team of specialists from around the world working at the International Technical Support Organization, Austin Center. Dinesh Kumar is a Senior ITSO representative working as a project leader in the ITSO Tivoli Group, Austin, Texas. He applies his extensive field experience as an I/T architect and project leader to his work at the ITSO where he writes extensively. Before joining the ITSO, Dinesh worked in IBM © Copyright IBM Corp. 1999 xv Global Services India as Senior Technical Manager of the Network Services team. In a role demanding both management and technical functions, he architected the network and its management for the largest domestic airlines of India. Mohamed Dawood is an Advisory IT specialist in IBM Global Services, South Africa. He has three years of experience with Tivoli and works in a Technical Infrastructure department. He holds a Bachelors degree in Computer Science. Mohamed is also a qualified MCSE and is certified in Tivoli Framework. His areas of expertise include deploying Tivoli across Windows NT, AIX, and SP2 platforms and SAP/R3 systems. Vasfi Gucer is a Senior ITSO Representative working as a project leader in the ITSO Tivoli Group, Austin Center. He has worked in IBM Turkey for 10 years and has been with the ITSO for 10 months. He has more than six years of experience in the areas of systems management and networking of the distributed platforms. Vasfi Gucer is a Certified Tivoli Consultant. Kai Lueke is a junior programmer who has worked for dvg Hannover, a computing center for the savings bank organization, for four years. He started his vocational trainee program in 1995 and completed it in 1998. Since then, he has been working in the department for systems management. He participates in a project that is implementing a Tivoli infrastructure in the dvg environment. His areas of expertise include developing data-based installation and configuration processes and C-programming. The team would like to express special thanks to Fergus Stewart, Tivoli Principal Consultant, for his major contribution to this book. Thanks also go to the following people for their invaluable contributions to this project: Milos Radosavljevic, John Owczarzak Editing Team, International Technical Support Organization, Austin Center Temi Rose Graphics Support, International Technical Support Organization, Austin Center Yoichiro Ishii, Edson Manoel Tivoli Team, International Technical Support Organization, Austin Center Stefan Uelpenich, Mark Johnson, Marco Sebastiani, Antonio Romeo Tivoli Systems, Austin xvi Introducing Tivoli Application Performance Management Comments welcome Your comments are important to us! We want our Redbooks to be as helpful as possible. Send us your comments about this or other Redbooks in one of the following ways: • Fax the evaluation form found in “IBM Redbooks evaluation” on page 231 to the fax number shown on the form. • Use the online evaluation form found at http://www.redbooks.ibm.com/ • Send your comments in an Internet note to redbook@us.ibm.com xvii xviii Introducing Tivoli Application Performance Management Part 1. TAPM concepts and environment setup © Copyright IBM Corp. 1999 1 2 Introducing Tivoli Application Performance Management Chapter 1. Introduction The widespread introduction of computer systems in the 1960s and 1970s had a dramatic impact on many businesses. The deployment of personal computers in the 1980s had a similar impact providing benefits to small organizations that had benefited only indirectly from the earlier computing technology. In the 1990s, the greatest advantages are being realized by organizations that exploit network computing. Network computing combines PCs and workstations, powerful shared computers, and large databases and the networks that connect them to provide a platform for new applications that were not imagined even a few years ago. These applications and the networking and computing systems on which they run are critical to the success of organizations. These applications are fundamentally different than their predecessors. They have more dependencies on more systems spread over an ever wider geographical area. They partition function throughout the network, and they exploit many different technologies. 1.1 Why application performance management? In recent years, the most common model for these distributed applications is the client/server model where the application is split into two parts. One part is the server, which provides functions and data. The server can reside on one system or can be spread over multiple systems. The second part, represented by the client, uses these functions and data. While the application on the client processes information, it is not visible for the user from whom the application gets the necessary information and functions; it seems to be hidden behind a big cloud. One application can use the services of different servers spread over the network. Users are accustomed to being online and moving large amounts of data around with the click of a button, often without being aware of how much data is involved. The user will only recognize that there is something wrong if a transaction takes a long time to process or does not complete at all. This is shown in Figure 1 on page 4. © Copyright IBM Corp. 1999 3 Network End-user Figure 1. End user having trouble in a complex IT environment In order to have an efficient business system, it is essential to be able to troubleshoot and investigate the processes that caused the delay in completion of an application transaction from a user perspective. Determining whether business applications are functioning properly from the end-user's perspective is the single most important challenge faced by IT for delivering acceptable service for business-critical applications. Many enterprise applications often earn a bad reputation for poor performance, which results in user frustration because their work is not being done quickly, reliably, or efficiently. It is necessary to diagnose and fix problems using Application Performance tools before they impact the bottom line. 1.1.1 Measuring service levels Because companies increasingly rely on IT to meet key business objectives, effective delivery of high-quality IT services has become the main goal for most successful IT organizations. Few IT organizations have the ability to measure, much less consistently deliver, predictable service levels. An end-user orientation will focus on the specific services required to ensure that end-users receive targeted service levels. This means that IT will focus 4 Introducing Tivoli Application Performance Management on the end user’s definition of service. The critical elements of service that the end user perceives include the following: • Availability (defined by users as access on demand) - Application availability is a measure of whether business transactions complete successfully. To a typical IT administrator, availability means server or network device availability, but, to a user, availability means access to the system and data within the system on demand; so, to a user, availability includes access rights (Security to IT), the timely execution of batch jobs to update data stores (Scheduling to IT), and the proper software configuration (Desktop Management to IT), thus, user satisfaction in terms of availability depends on delivering several services together in an integrated fashion. • Application response time - Response time is the measure of how long each business transaction takes to complete. • Application throughput - Throughput is a measure of how many transactions complete in a given time period. For batch applications, it is the most important service-level measurement. • Time to resolution - This is the time taken to resolve a problem. The most noticeable service metric with which end users evaluate IT is the measurement of response times. The traditional resource and functional focus means that simply measuring response time is almost impossible for IT departments because such a measurement spans multiple teams, each using domain-specific tools, which are poorly integrated if at all. In addition, it is not even measurement of response time that end users want; it is delivery of consistent response times. More than that, they want fast problem resolution when something goes wrong (time-to-resolution); so, in order for an IT organization to deliver a high level of service, it must not only measure end-user response times but use that capability as part of its overall service level management process. 1.2 Techniques for measuring application performance There are several different techniques for measuring the performance of distributed applications. All these approaches have their advantages and disadvantages. However, they all seek to do the same thing: Measure transaction availability and response time, generally, from the context of a business process. In this section, we will explain four major approaches available in the application performance management marketplace for measuring response Introduction 5 time. We also describe their advantages and disadvantages and when one should use a specific approach. Figure 2 shows different approaches with respect to their value to business and the effort required to perform the activity. Application instrumentation provides the most benefits for measuring response times; however, it requires a significant amount of effort. Application instrumentation Value to business Transaction simulation Client capture Network sniffing Effort to do Figure 2. Response time measurement techniques 1.2.1 Application instrumentation The Application Instrumentation approach for measuring application performance focuses on instrumentation of the application source code by modifying it to include calls to the Application Response Measurement (ARM) API. The ARM API is a set of standard API calls agreed upon by a number of prominent IT companies that allow an application-centric focus on performance. The API is designed to allow you to monitor the performance of any application. A major advantage of this approach is that you can put these calls wherever you want, and control of the instrumentation is in the hands of the application 6 Introducing Tivoli Application Performance Management developers. The disadvantage of this approach is that, in most cases, you need the source code of the application needing to be instrumented. 1.2.2 Transaction simulation This approach records typical end-user transactions of an application and saves them as a script. This script acts as a proxy for the real application. You can edit this script to instrument with ARM API calls just like in the application instrumentation. This instrumented script is executed periodically from a dedicated client on the network simulating the user transactions you recorded. The script accurately represents actions that real users perform, and the resulting measurements can be good approximations of real end-user experience. The advantage of this approach is that it does not depend on access to the source code of the application to carry out performance measurements. It can be used to carry out the response time trend analysis of an application from a user environment perspective. The disadvantage of this approach is that it creates artificial loads in the environment. Also, if the transaction simulation is being used for updates in a production environment database, these dummy updates need to be rolled back to maintain the integrity of the production environment. 1.2.3 Client capture This approach also does not require any changes to the application. The focus is to deploy sensors for observing all activities within that system at key interfaces on the end user’s desktops. The events related to the application being monitored are analyzed to determine which type of application was executed, and response time is measured. The advantage of this approach is that it does not depend on access to the source code of the application for carrying out performance measurements. The disadvantage is that there could be performance overhead on the end-user desktop because it needs to capture and process all the events. Also, the event patterns used to recognize a transaction can change since the new release of an application, and, thus, the exercise may need to be performed again. 1.2.4 Network X-ray This approach uses probes to capture network packet data and determine application response time. The probes look inside the data streams to find clues indicating which type of transaction is executing. The approach focuses Introduction 7 on the network impact of application performance and is designed to facilitate network bandwidth capacity planning. Tivoli Application Performance Management (TAPM) does not incorporate the network X-ray approach as a part of its solution because there are currently a number of limitations associated with the network X-ray approach for the purpose of measuring application response times. This approach requires the placement of probes throughout the network, which could be costly and cumbersome, especially in switched networks. These probes provide limited or no business process perspective and do not scale well since a single probe may be called on to measure every transaction from many hundreds of client desktops. If encryption is used, probes are unable to measure any transaction. 1.3 Tivoli’s solution for application performance The earlier Tivoli solution for response time measurement was based entirely on the use of the ARM API (actually based on ARM V 1.0) together with Tivoli Distributed Monitoring (DM). This approach provides very accurate measurements but requires that the target application be instrumented with the ARM API. This approach was not useful for customers having no access to the source code of their applications. As a result, Tivoli's solution for the application performance market required an expanded approach and capabilities. The new product, Tivoli Application Performance Management (TAPM) provides the solution for managing application performance and overcomes earlier limitations by offering alternatives. With the goal being to identify and resolve end-user problems, Tivoli's TAPM focuses on a combination of three approaches: Capturing response time measurements at the desktop using client capture, transaction simulation, and ARM instrumentation. The availability of three different approaches allows an organization to choose the approach relevant to their environment. TAPM is currently undergoing testing through the Early Support Program (ESP) in which a few customers are using the beta code. Sensor-based instrumentation through Client Capture is to be supported in a future release of TAPM. The two approaches currently supported are shown in Figure 3 on page 9. 8 Introducing Tivoli Application Performance Management Application Using ARM TAPM Performance Measurement Transactions Simulating Script Figure 3. TAPM approach to performance management In this book, we will explore the functionalities of this exciting new product. 1.3.1 An integrated system management solution TAPM is integrated with a number of other Tivoli Enterprise products to provide a complete service-level management solution to customers. The integration addresses the areas of transaction availability and response times experienced by end users, detects service degradation based on business policies, accelerates problem diagnosis and resolution, and enables capacity planning and resource allocation based on business impact. With Tivoli Decision Support (TDS), Tivoli adds an important element to the solution because historical data can be correlated and analyzed to pinpoint offending resources and, thereby, improve availability even further. An overview of the implementation of TAPM in the Tivoli environment is given in Figure 4 on page 10. Note that the dotted lines show the future functionality of TAPM. Introduction 9 TAPM inTivoli Environment Global Enterprise Manager ARMed Appications Status Tivoli Enterprise Console Events Virtual User Applications TAPM Agent Status/Exceptions Tivoli Distributed Monitoring TMA RDBMS Sensors L0G Profile Distribution Tivoli Decision Support Tivoli Endpoint Summaries RDBMS 90 80 70 60 50 40 30 20 10 0 Figure 4. Overview TAPM in the Tivoli environment In this way, the capability delivered with TAPM becomes an integral part of a more comprehensive Tivoli solution that differentiates Tivoli from traditional availability and desktop management tools. 1.3.2 TAPM overview The first step one would take when monitoring an application, is to decide what to monitor. This includes which transactions within an application, the method to be used, and, perhaps, at what time of day these applications will be run. Once the planning is complete, you will decide which tools will best fit your needs, that is, simulation tools, ARM API tools, and so on. You may then proceed with creating simulation scripts or adding API calls to your applications. TAPM requires that all simulation scripts and instrumented applications be registered within the Tivoli environment and added to TAPM profiles before they can be distributed to specific endpoints. 10 Introducing Tivoli Application Performance Management The profile distribution will cause the simulation scripts or instrumented applications to generate data. This will be stored in an external database, and, with the use of TDS, we will be able to report on the data received. TAPM is also shipped with a Distributed Monitoring agent, which will enable you to act upon any exceptions as they appear. As other Distributed Monitoring components, events can be fowarded to the Tivoli Enterprise Console. The monitoring process with TAPM is briefly represented in Figure 5. ??? Planning Tools (Installation) stpircS noitalumiS ARM Application Instrumentation Registration Profile Creation/ Distribution Data Collection Data Monitoring (Distributed Monitoring) Alert (TEC) Reporting (TDS) Figure 5. TAPM overview Introduction 11 1.3.3 Response time measurement The first release of TAPM will support the Application Instrumentation and Transaction Simulation approaches. Both these approaches use a common technique for making the measurement: ARM API calls to the TAPM agent running on a Tivoli Endpoint. 1.3.3.1 Application instrumentation The application code makes an ARM API call when the user transaction starts and another call when the transaction ends. The first of these calls starts a timer in the TAPM agent, and the second one stops the timer. The time difference between the two calls is the end-user's response time. This technique requires that the ARM API calls are inserted into the application code at the appropriate points. Applications can be instrumented at a user's desktop and on the servers to which their application connects. In this case, the measurements can be correlated to isolate the cause of extended response time. 1.3.3.2 Transaction simulation Tivoli has worked with Mercury Interactive to integrate their WinRunner and LoadRunner technologies into TAPM leveraging Mercury's experience with and understanding of end-user applications. TAPM provides the capability of setting up a synthetic user workstation (for Windows platforms) that will run typical end-user transactions by executing Mercury scripts. The scripts will make ARM API calls when the transaction is started and when it completes; so, the TAPM agent will measure the response time for these transactions. TAPM provides pre-written scripts for typical end-user transactions in SAP, Oracle NCA, Baan, PeopleSoft, and http. This will enable TAPM users to very quickly begin measuring typical end-user experience with these applications. These scripts can also be tailored for other applications. TAPM includes a toolkit to create scripts by recording window interactions or using a point-and-click GUI. 1.3.4 Performance analysis and reporting Analysis of the data gathered by TAPM enables you to measure the service level of any application and, thus, allows you to tune application and network management more efficiently. With Tivoli Decision Support (TDS), TAPM adds an important element to the solution, as historical data can be correlated and analyzed to pinpoint offending resources and thereby improve availability even further. In addition, by analyzing both the sources and duration of problems with TDS, the opportunity exists for organizations to fine-tune processes they may use to 12 Introducing Tivoli Application Performance Management resolve problems, thereby, improving on the time-to-resolution metric demanded by users. 1.4 Summary We have seen that there are four approaches for measuring application performance: Application instrumentation, transaction simulation, client capture, and network X-ray. Tivoli Application Performance Management (TAPM) will include all of the approaches above (except network X-ray technique) to deliver a robust solution. The product is currently being tested by ESP customers. Introduction 13 14 Introducing Tivoli Application Performance Management Chapter 2. The planning and instrumenting process In this chapter, we want to give an overview of how to approach the planning and instrumenting process. We will explain what you should keep in mind when you are going to measure response time of transactions. The planning process is very important to a successful implementation of application performance measurement and, as a result, analyzing and keeping service levels. Planning what to instrument will take up most of the time in this process, but it is the most important step. 2.1 Plan what to instrument Whether you use application instrumentation or transaction simulation, you have to decide which transactions you want to measure and monitor. Therefore, you have to define the key business transactions that are performance-sensitive, which is the most important step. Define who needs what kind of data and what the data will be used for. This can be done by the application developer using the application instrumentation when developing the applications. This provides detailed and meaningful information about measured transactions. It is common and useful for both processes to be a joint collaboration between the users and developers of an application and system and network administrators. There are two kinds of transactions that will generally provide the greatest benefit if they are instrumented: • Transactions that are visible to users or that represent major business operations. These are the building blocks for service level agreements, workload monitoring, and early problem detection. • Transactions that are dependent on external services, such as a database operation, a Remote Procedure Call (RPC), or a remote queue operation. These are generally components of a user/business transaction. Knowing how these types of transactions are performing can be invaluable when analyzing problems, tuning applications, and reconfiguring systems and networks. To help in the analysis, you should answer the following questions to help you decide which transactions to measure: • What unit of work does this transaction define? • Are the transaction counts and/or response times important? • Who will use this information? © Copyright IBM Corp. 1999 15 • If the performance of this transaction is too slow, is there some corrective action that can take place (for example, off load work from the machine, add memory, or relocate remote files)? Do not try to measure every transaction; this will only cause unnecessary network load. For example, you measure time un-critical transactions. Note It is important to understand the difference between an application and a transaction. An application is, in a general sense, a computer program that has been purpose-written. A transaction, on the other hand, can be called a specific set of input data that trigger the execution of a specific process or job inside an application. An application can have several independent transactions. 2.2 The instrumentation process The first basic question of the instrumentation process is whether you have access to the application code and the resources to insert ARM API calls into that code. If this is the case, you should consider building up ARMed API applications. If you do not have programmer’s access to the application, you should use WinRunner and VuGen (Load Runner) to build a simulation of the application or a selected part of the application. If you are more concerned with investigating a network problem, VuGen can be used to study the network load. According to the decision made in the previous step and after you have finished planning what to measure, you can go on with the instrumentation process. Tivoli Application Performance Management (TAPM) provides two approaches for measuring transactions; both of them are based on the ARM API calls. While application instrumentation forces you to modify the source code with ARM API calls, in transaction simulation, these calls are placed in a virtual user script, which can be created by WinRunner or VuGen. 2.2.1 Application response time measurement The Application Response Measurement (ARM) API is a set of standard API calls agreed upon by a number of prominent IT companies that allow an application-centric focus on performance. The API is designed to allow you to monitor the performance of any application. The most likely use of the application monitoring capability will be to measure response time, but it can 16 Introducing Tivoli Application Performance Management also be used to record application availability and account for application usage. Response time collection is performed by the ARM agent. The ARM agent receives ARM API calls from the user application or virtual user script and calculates response times. You can see this in Figure 6. Instrumented Applications START ARM AGENT STOP Business Application 11 12 10 9 8 7 6 1 2 3 4 5 11 12 10 9 8 7 11 12 1 2 3 4 7 6 5 6 5 1 2 3 4 Network START STOP Business Application 10 9 8 TAPM ARM AGENT ARM AGENT START STOP Transaction Simulation Figure 6. ARM API agent 2.2.2 Application instrumentation The ARM API is a simple API that applications can use to pass vital information about a transaction to an agent. To simplify this slightly, all the application has to do is call the ARM API just before a transaction (or a subtransaction) starts and again just after it ends. The API is supported by an The planning and instrumenting process 17 agent that measures and monitors the transactions and makes the information available to management applications. The ARM API calls identify the application, the transaction, and (optionally) the user and provide the status of each transaction when it completes. The API is designed to be extendable while still being fully backwards-compatible. This means that anyone who instruments their application to call the ARM API can be reassured that rework of their application will not be needed just to maintain the existing management capability even if the API is enhanced. Exploiting the newest features will be optional. Any implementation using Version 1 of the API is fully supported by Version 2 implementations. 2.2.2.1 ARM API function calls The ARM API is made up of a set of function calls that are contained in a location called shared library. All the performance measurement agents that support the ARM API provide their own implementation of the shared library. When you insert the ARM API function calls in your application, it can be monitored by the agents that implement the shared library. The placement of ARM calls within an application is shown in Figure 7 on page 19. 18 Introducing Tivoli Application Performance Management . Application arm_init arm_getid Transaction arm_start do user's work arm_update do user's work arm_stop arm_end T T1 response time 2 Figure 7. Placement of ARM calls The following list describes the function of each call: • arm_init - During the initialization of your application, call arm_init, which names your application and, optionally, the users and initializes the ARM environment for your application. A unique identifier is returned that must be passed to arm_getid. • arm_getid - Use arm_getid to name each transaction you use in your application. This is often done during the initialization of your application. There can be any number of transaction names defined for each application. The transaction name and details are specified as character strings. A transaction name needs to be unique within an application. The combination of application name and transaction name uniquely identify a transaction class. In each program, each transaction may be executed once or many times. The arm_getid function returns a unique identifier that must be passed to arm_start. The planning and instrumenting process 19 • arm_start - The arm_start function indicates that an instance of a transaction has begun execution. Contrast this with arm_getid, which defines the name of the transaction class during initialization but does not actually indicate that a transaction is executing. The identifier returned on the arm_getid call is passed on as a parameter of arm_start; so, an agent knows which type of transaction is starting. There can be any number of instances of the same transaction class executing simultaneously on the same system. To identify each one, the return code from arm_start is a unique handle generated by the agent. This handle is unique within a system across all instances of all transactions of all applications. The transaction instance is the fundamental entity that the ARM API measures. • arm_update - This is an optional function call that can be made any number of times after arm_start and before arm_stop. The arm_update function gives information about the transaction instance, such as a heartbeat after a group of records has been processed. It would typically be used for a transaction that takes many minutes or hours to complete. An update might be sent at a fixed time interval (for example, every minute) or after a fixed amount of work (for example, after every 1000 records are processed). The identifier returned on the arm_start call is passed on as a parameter to indicate which transaction instance is being updated. • arm_stop - The arm_stop function signals the end of the transaction instance. Which instance of transaction is going to be stopped is indicated by the returned handle of the arm_start call, which is passed as a parameter. Also, one of the three possible statuses is passed: Good means the transaction completed normally, Error means that the transaction completed with an error, and Abort indicates an incomplete transaction. • arm_end - When you are not making any more ARM API calls, you will use this function. The call arm_end cleans up the ARM environment for your application. There should be no problem if this call is not made, but memory may be wasted because it is allocated by the agent even though it is no longer needed. 2.2.2.2 New features in ARM Version 2 The new functionality of ARM API allows you to have more options in managing your Applications. For example, you can have one transaction as a component of another, and transaction correlation can be done on one system or across several systems. This will provide a better understanding of the entire transaction. 20 Introducing Tivoli Application Performance Management You can provide additional information about the transaction, such as the number of bytes or records being processed, or about the state of the application at the moment that the transaction is being processed, such as the length of a work queue. This information (called application-defined metrics) is useful to better understand response times and how the application can be tuned to perform better. You can use the new logging agent to perform a simple verification of your instrumentation. It allows you to determine whether the correct parameters are being passed on each call, but it does not function as a measurement agent. Note that Version 2.0 of the ARM API is backward-compatible with Version 1.0. Applications instrumented to the ARM 1.0 API can continue to function correctly with agents that implement the additional features of the 2.0 API. ARM 2.0 instrumented applications will function correctly with agents that implement the features of the 1.0 API. Previously, in Version 1, we could see what was happening but had no answers as to why these problems were occurring. In Version 2, we could see why things went wrong; For example, we could ask: Where is the transaction being delayed? Is one transaction causing another to hang? How is an application resource being used? and What is the size of the transactions being carried out? In essence, the diagnostic information can point to where the problems occur. All Version 1 API calls have three reserved parameters: A pointer to a data buffer, the length of this buffer, and a word of flags. Version 2 uses the buffer pointer and buffer length parameters to pass the following additional information. See the ARM API Guide for details about how to use the parameters. The parent/child relationship between transactions is represented by correctors passed on an arm_start call. Application and transaction metrics and diagnostic information can be passed on arm_start, arm_update, and arm_stop calls. If these two parameters are set to zero, which they must be in Version 1, the API functions identically to Version 1. This means that the extensions are completely backwards-compatible, and applications using Version 1 of the API do not need to be recompiled to work with an agent supporting Version 2 of the API. 2.2.2.3 Using ARM to correlate transactions and subtransactions Using a client server model, Version 2 can correlate transactions. In this model, the server provides a service to the client through an interface. The client obtains a service from the server by issuing requests. The server may, in turn, be a client to another server in order to obtain further information that it does not have. The planning and instrumenting process 21 Figure 8 briefly explains the correlation process. T r a n s a c t io n C o r r e la tio n a r m _ s ta rt d a ta b a s e s e r v e r T1 a r m _ s ta r t a r m _ s ta r t T2 T3 a r m _ s to p a r m _ s to p a r m _ s to p C o r re la tio n w ith in o n e m a c h in e C o rre la tio n b e tw e e n m a c h in e s Figure 8. Transaction correlation Collecting correlators with ARM ARM Version 2 enables you to measure which subtransaction is causing a parent transaction to perform slowly. This is possible since Version 2 of the API allows you to distinguish which subtransaction belongs to which parent transaction. The collection of the correlation information can be done in two ways: • When an application uses the arm_start call that requests a correlator, the ARM agent assigns a correlator for that transaction. The ARM agent can decide whether to provide the correlator or not. This will either occur if the functionality is not supported, as with Version 1 agent, or if this information is not requested. • Using the same arm_start, the application can provide a correlator for the parent transaction. This allows TAPM to know the parent/child relationship. Using correlation in practice To start monitoring the application, the transactions need to be monitored first. This will be done as in Version 1 of the ARM API. The data that was 22 Introducing Tivoli Application Performance Management generated will be used for comparison and trend analysis. Correlation analysis will only be done if there are unsatisfactory response times obtained. If slow response times are being generated, the correlation application will cause the trace flag to be activated for all transactions. This will occur at the client where the slow response times are being generated. Once the trace flag has been turned on, the correlation information will be captured. If the ARM agents on the slow systems routinely generate correlators but do not make available an online control for the trace flag, the agents can exploit the fact that the agent (system) ID is included in the correlator.The correlation application can provide the ARM agent servers with a list of client systems that are experiencing slow response times. The servers might be selected by the correlation application after consulting an inventory database showing application connectivity. The agents at the servers use the Agent ID field in the correlator to compare with the list of systems and capture all the correlation information for transactions from those systems. It does not capture correlation data from other systems. Also, when the parent transaction is from one of the systems being traced, it can turn on the trace flag for correlators it generates. 2.2.2.4 Collecting application and transaction metrics using ARM ARM API Version 2 can be used to determine why an application is not performing well and also to report on its availability. It is possible to pass the information regarding the number of bytes that are transferred to ARM Version 2 API. This information can be used in a graph to display the length of different sizes of transactions. By correlating response times with the resources allocated, the administrator can get a much better idea of how to configure applications and their environment.The application can determine if there are any transactions that are being processed or waiting to be processed. This will help to alleviate any bottlenecks that may exist. Collecting diagnostic information using ARM When a problem or an exception occurs within the transaction, the application is usually aware of this. This information can be logged by the application, but it will not be as easy to trace the problematic transaction. Version 2 defines a way for an application to provide diagnostic information linked to transaction measurement data. The data must first be passed using the Inter Program Communication (IPC) then written to a trace file, sent across the network, or processed in some other way. The planning and instrumenting process 23 2.2.3 Transaction simulation A different way of measuring application performance is the transaction simulation. You dedicate a machine in your production or test environment to be a simulation machine. To reflect these machines, identical software and configuration should be on that machine. The simulated script with the implemented ARM functions is run on that machine, and the response times are recorded as shown in Figure 9. Transaction Simulation SAP Client TAPM ARM Agent Call generator Vuser script SAP Server arm_start lr_start_transaction arm_stop lr_stop_transaction simulation scheduling engine TAPM Tivoli Management Agent W inRunner LoadRunner Figure 9. Transaction simulation (SAP) This solution only reflects transactions simulated by the script and does not give you the end user’s real application response times. Measured response times can be taken as a reference when the simulation is run in a production environment; therefore, you must be careful because the simulated transactions will have an effect on your production system. When you run these scripts, all processed transactions influence your network performance, and test data can be written in databases or files. You must be aware of what you simulate and how. Transaction Simulation is one of the approaches for measuring application performance. The TAPM product CD contains Mercury’s WinRunner, LoadRunner, Virtual User Generator, and Quick Test for R/3 Toolkit. 24 Introducing Tivoli Application Performance Management 2.2.3.1 Virtual User Generator (VuGen) Virtual User Generator (VuGen) is a component of LoadRunner and is used to develop and create virtual user scripts. These scripts emulate the transactions of human users by performing the same business processes that real end users perform. VuGen works on the protocol level and communicates directly with the server. Figure 10 illustrates a VuGen trace. How VuGen works application protocol level Application Server VuGen tracing the requests Client running an application Figure 10. VuGen trace VuGen supports a variety of protocols for which you can create user scripts. It is especially useful for load testing on client/server systems. The following is a list of VuGen protocols/users and what they emulate. • Database - A database (CtLib, DbLib, Informix, Oracle, and ODBC) application accesses a server. Vusers directly access servers using API calls. • TUXEDO - A TUXEDO client communicates with a TUXEDO application server. TUXEDO users use API calls to directly access a server. • Web - A Web browsing session. • Windows Sockets - A client application communicates with a server using the Windows Sockets protocol. Windows Sockets Vusers use API calls to directly access servers. • APPC - A client application communicating with a server using the Advanced Program to Program Communication (APPC) protocol. APPC Vusers use API calls to directly access servers. • RTE (Windows) - A Windows-based terminal emulator application. The planning and instrumenting process 25 • Java - A user operating a Java applet or application together with its graphical user interface. • Baan - A Baan session together with its graphical user interface. • Oracle NCA • Jolt (including PeopleSoft) - A Jolt client application communicating with a TUXEDO application server. The Vuser type is responsible for the structure and content of Vuser scripts. For example, Database Vuser scripts always have three sections, are written in a code that resembles C, and include SQL calls to a database server. In contrast, GUI Vuser scripts have only one section and are written in TSL (test script language). A VuGen-generated script always has three sections and two different types of functions. The sections are subdivided into the vuser_init, actions, and vuser_end sections. One type is the general Vuser functions, and the other is the protocol-specific functions. The general functions are called LR functions and give you run-time information about the Vuser and its host while the others are specific for the Vuser. For example, APPC Vuser functions are used in APPC Vuser scripts. Each APPC Vuser function begins with an lra prefix. Web Vuser functions begin with the Web prefix. Besides the generated functions, you can modify a script with any C-function or general VuGen function. You can also call external functions from your script that can be recognized and executed by the interpreter. When you have created a script, check its functionality, and run it from VuGen. The script will be processed by an interpreter; so, no compilation is needed. Any syntax errors will be noted by the interpreter. 2.2.3.2 WinRunner WinRunner enables you to create scripts to monitor the performance of your distributed applications by emulating typical business processes and transactions. You can create reusable virtual scripts that emulate the functions of your business applications. Running these scripts allows you to monitor the end-user’s experience. Because you are able to record the actions an end-user will run on his machine, it is possible for you to simulate a real-life example. We will now briefly explain what WinRunner does and how it works. This will only be a short introduction to the WinRunner tool, and, to learn more about it, you should refer to the WinRunner User’s Guide, which is product documentation. 26 Introducing Tivoli Application Performance Management WinRunner offers you an easy way of creating virtual user scripts by recording all the work you do on your application. It generates this script, which is written in the C-like Test Script Language (TSL), while you click on the GUI objects. WinRunner also gives you the ability to edit the scripts and modify, add, or delete functions, which are provided by an included Visual Programming tool, or add only C-language functions. A virtual user script consists of two components: The GUI map and the script itself. To understand this method of working, we have to explain the three stages of developing and creating a virtual user script: 1. Creating the GUI map The GUI map is necessary for WinRunner to recognize the GUI objects of your business application. Without a GUI map you cannot replay your recorded virtual user script. This means you have to create this GUI map either using the RapidTest Script Wizard before recording a script or manually adding object descriptions during the recording of the script. You can easily do this by simply clicking the wanted object; WinRunner then adds it to the GUI map. This GUI map has to be saved and must be loaded before the script is executed. 2. Creating the virtual user script After the GUI map creation, you can take the next step and create the virtual user script. Run your application, and WinRunner will record all the actions that take place within your application. A Test Script Language statement will be generated for every operation or transaction you perform. That statement describes the GUI object and the executed transaction. During the recording, checkpoints confirming the response of the transaction should be inserted. Then, WinRunner saves the expected result, and, later, while running the script, it will be compared with the result of the replayed script. These checkpoints are necessary to ensure correct replay. There are two modes for recording a script: The analog mode, which exactly records mouse clicks, keyboard input, and the x-and y-coordinates traveled by the mouse, and the context-sensitive mode, which does not. After recording, you can modify the script by adding or replacing TSL or C functions. 3. Debug the virtual user script The last step is to run and debug the recorded script to ensure that the script is executed correctly. The results of the debugging will be saved to the debug folder and can be analyzed. Check for defects that can occur, for example, a missing GUI object. The planning and instrumenting process 27 After you have created a running WinRunner script, you can continue by inserting the WinRunner ARM functions in the places you consider reasonable. 2.2.3.3 The WinRunner and LoadRunner functions This chapter explains the WinRunner and LoadRunner functions, which perform differently than the ARM API functions and are not exactly the same. These ARM functions begin with an lr and can be manually inserted using the Function Generator for WinRunner, whereas, for LoadRunner, they need to be typed in manually with the exception of the lr_start_transaction and the lr_stop_transaction. • lr_set_subtransactions - This is only valid for WinRunner. Use this function to define whether correlation between ARM transactions is enabled or disabled. To enable correlation, the parameter is 1, disable 0. • lr_set_application_name - This obligatory function defines the ARM application name and must be placed prior to the first transaction definition. • lr_set_user_name - This optional function defines the ARM user and must also be placed prior to the first transaction definition. • lr_set_transaction_metrics - To use a set of metrics, call this function for a specific transaction. • lr_set_start_transactions - Whatever you decide to measure, insert this function to start an ARM transaction instance. It calculates the response times and forwards the additional metrics, if defined, to the ARM agent. • lr_start_sub_transaction - Start a subtransaction by using this function when you enable the subtransaction feature. It will pass the correlator to the ARM agent to identify this transaction as a child transaction. • lr_set_transaction_status - Set the status of the last transaction still being processed. • lr_update_transaction - To update the metrics of a specific transaction, call this function. It can also be used to tell the ARM agent how much time has passed since a transaction started. • lr_end_transaction - This updates the metrics and stops the transaction instance. • lr_end_application - This is only valid for WinRunner. This mandatory function closes the application and is inserted at the end of the simulation script. 28 Introducing Tivoli Application Performance Management 2.2.3.4 Quick test for R/3 QuickTest for R/3 is a simulation tool designed for SAP R/3 systems. QuickTest launches the SAP R/3 GUI (front end) and records the users’ interaction with the SAP/R3 server. All scripts that are recorded can be played back with different sets of data. QuickTest uses context-sensitive recordings to create scripts. Context sensitive recordings record the commands and actions you perform. They identify the screen objects being used without recording their exact location. The script recordings are created in C programming language. The execution of these scripts is a simple playback. To watch the scripts execute, run them from QuickTest itself. The script will provide input data to the required fields. The logon information can be recorded within the script and, thus, during the playback, the virtual user will log on and execute the recorded steps. QuickTest records the results of each action during playback. This information and the duration of each action is recorded in the execution log. Additional functionality can be programmed into the QuickTest script to improve the capabilities of this script. These virtual user scripts will be integrated into TAPM, which enables the monitoring of end user tasks. 2.2.4 Overview ARM, WinRunner, and VuGen functions The next table displays an overview of which functions TAPM provides to implement either in the application source code or the simulation script. In the left column, you can see the ARM API functions; in the second column, you can see the WinRunner; and, in the third column, you can see the Virtual User Generator scripts. The functions shown in the same row are more or less equal. This means that the WinRunner and Loadrunner functions are not exactly the same as the ARM API functions. For example, the arm_init function is split into two WinRunner functions to set the application name and user. Table 1. Functions ARM API arm_init arm_getid WinRunner lr_set_application_name lr_set_user_name lr_start_transaction lr_set_transaction_metrics Virtual User Generator lr_set_application_name lr_set_user_name lr_start_transaction lr_set_transaction_metrics The planning and instrumenting process 29 ARM API arm_start WinRunner lr_start_transaction lr_start_sub_transaction lr_set_sub_transaction start_transaction 1 lr_update_transaction lr_set_transaction_status lr_end_transaction end_transaction1 lr_end_application Virtual User Generator lr_start_transaction lr_start_sub_transaction arm_update arm_stop arm_end 1 lr_update_transaction lr_set_transaction_status lr_end_transaction Provided for backward compatibility The ARM functions are described further in Section 2.2.2.1, “ARM API function calls” on page 18 and Section 2.2.2.2, “New features in ARM Version 2” on page 20. You can find more about the WinRunner and LoadRunner in Section 2.2.3.3, “The WinRunner and LoadRunner functions” on page 28. 2.3 Summary In this chapter, we have covered the planning and instrumenting steps of TAPM. One important step in the planning stage is to determine which transactions are most critical for the success of the business since these will likely be good candidates to monitor. Trying to monitor every transaction is just a waste of time and resources. 30 Introducing Tivoli Application Performance Management Chapter 3. Installing and setting up TAPM In this chapter, we will explain the TAPM installation and its environment setup process. The Tivoli environment setup process for installation of Framework, TEC, and Distributed Monitoring will be briefly described. We will then explain the necessary steps for creating your TAPM environment. This will be the installation of different components that are shipped in TAPM. In this chapter, we assume that you are familiar with the Tivoli Framework and Tivoli core applications. 3.1 TAPM prerequisites The Tivoli Application Performance Management (TAPM), Version 1.0, consists of several components as shown in Table 2 on page 32. All these components are on the TAPM CD. The Tivoli Decision Support (TDS) Guide for TAPM is not a part of this product CD and was supplied to us separately. This guide will also be a part of the TAPM CD when the product is finally available. Note The TAPM product had been undergoing testing through the Early Support Program (ESP) process in which a few customers use the beta code. We used this TAPM beta code to carry out the project. The TAPM product components and their prerequisites, installation process, and usage may be different when the product is released. The experiences shared in this book are based on the beta code provided to us. The components from serial numbers 3 to 11 in Table 2 on page 32 are for the creation of virtual user scripts, and their prerequisites will be explained later in the book when we create the virtual user scripts. Of the above components for virtual script creation, we did not use the WinRunner add-ons at serial numbers 4, 5, and 6 in Table 2 on page 32. The TAPM software is compatible with the Framework Version 3.6 or higher and associated Versions of Distributed Monitoring (DM), Tivoli Enterprise Console (TEC), and Tivoli Decision Support (TDS). To record the performance data, a database that can reside on any server in or out of the Tivoli environment is required. All Tivoli RIM supported databases are supported by TAPM. © Copyright IBM Corp. 1999 31 Supported hardware platforms for the TAPM engine installation are Solaris, AIX, HP, and WinNT. The endpoints are restricted to Windows NT or Windows 98 platforms. We suggest that the TAPM release notes be reviewed prior to proceeding with its installation. Release notes were not available at the time of this writing since the product was a beta code. Table 2 displays the components of TAPM. Table 2. TAPM components Sl. 1 2 3 4 5 6 7 8 9 10 11 Product Tivoli Application Performance Management 1.0 TAPM 1.0 Monitors for Distributed Monitoring WinRunner WR_Delphi WR_Java WR_Oracle SAP Quick Test VuGen Robotic Client canned_scripts Tool Kits Final Setup TAPM engine Explanation TAPM Monitors for DM WinRunner toolkit WinRunner add-on for Delphi WinRunner add-on for Java WinRunner add-on for Oracle Toolkit for creating SAP virtual user LoadRunner - Virtual user generator toolkit TAPM runtime for VuGen and QT/SAP scripts Ready-made sample scripts Use this automatic installation to complete the installation of toolkits. In the future, this stage will not be necessary. 3.2 Creating the Tivoli environment We created our Tivoli managed environment based on Tivoli Framework 3.6. The single TMR environment is comprised of four different machines as shown in Figure 11 on page 33. The host name of these four machines is mentioned below each system in the figure. One machine was configured as both TMR and TEC server, and the other machines were configured as managed nodes and the endpoint. The managed node frankfurt is configured as an endpoint gateway supporting the endpoint dresden. 32 Introducing Tivoli Application Performance Management Tivoli Environm ent T M R S erver/ T E C S erver S tuttgart G ateway M anaged Node Frank furt A usres 24 E ndpoint D resden Figure 11. Tivoli environment The following lists the installation steps we performed to create our Tivoli environment: 1. Installed and configured Windows NT Server 4.0 Service Pack 5 on all four systems. We chose the Windows NT platform because the first TAPM beta code made available to us at the start of the project supported only this platform. The second beta code supports other platforms as mentioned in Section 3.1, “TAPM prerequisites” on page 31. 2. Installed Oracle database server Version 7.3.2 on the stuttgart system. 3. Installed Framework 3.6 to make the stuttgart system the TMR server. 4. Installed Framework 3.6 to make ausres24 and frankfurt systems managed nodes. 5. Configured the frankfurt system as an Endpoint Gateway. 6. Configured the dresden system as an endpoint connected to the frankfurt gateway. 7. Installed Distributed Monitoring 3.6 on the stuttgart and frankfurt systems. 8. Installed TEC Server 3.6 on the stuttgart system. 9. Installed TEC Console 3.6 on the stuttgart system. 10.Configured the stuttgart system as the TEC RIM host. Installing and setting up TAPM 33 11.Installed Tivoli Decision Support (TDS) 2.0 on the snapper machine as a stand-alone installation. All components of TDS, that is, the Discovery Interface, Discovery Client, Discovery Administrator, Cognos Powerplay, and the File Server were installed on this single machine. The snapper system is not a managed resource in our Tivoli managed environment. 12.Installed Oracle database client on snapper and set up the ODBC connection with the Oracle database server on the stuttgart system for TDS communication requirements. To understand the process of performing the above tasks, refer to the Tivoli documentation on the subject. 3.3 TAPM database setup The application performance data created through TAPM gets collected in a log file on the endpoints. To consolidate the performance information collected on several endpoints in the managed environment, this data needs to be stored in a central accessible database in such a way that it is easily retrievable in a convenient and varied format. The performance data is firstly aggregated on the endpoints and then sent to the endpoint gateway. The endpoint gateway transfers it to the TAPM RDBMS Interface module (RIM) host from where it is loaded into a database using its RIM interface. The data uploading from the RIM host to the database happens through database-specific commands and not through any Tivoli processes. The usage of RIM prevents the application from being dependant on one particular RDBMS server. Thus, you may have the Database server installed on any machine that is totally unrelated to the Tivoli managed environment. The relational database management system (RDBMS) client software must be installed on the same host that will be defined as the TAPM RIM host. This is shown in Figure 12 on page 35. 34 Introducing Tivoli Application Performance Management Tivoli Environment Endpoint RIM Host Gateway Uploading collected data Endpoint Database Operations Database Database Client Database Server Figure 12. Database client installed on gateway TAPM supports the RDBMS from different vendors. Specific versions are listed in Table 3. There may be some restrictions with specific versions. Table 3. Supported RDBMS Client Server Operating System System 390 HP-UX AIX SunOS Solaris Microsoft NT Oracle N/A 7.1.x, 7.2, 7.3 7.1.x, 7.2, 7.3 7.1.x, 7.2, 7.3 7.1.x, 7.2, 7.3 7.1.x, 7.2, 7.3 Sybase N/A 11.0.1, 10.x, 11.x 11.0.1, 10.x, 11.x 11.0.1, 10.x, 11.x 11.0.1, 10.x, 11.x 11.0.1, 10.x, * DB/2 2.1.2 (5.0 for S390) 2.1.2, 2.1.2.5.0 2.1.2, 2.1.2.5.0** 2.1.2, 2.1.2.5.0** 2.1.2, 2.1.2.5.0** 2.1.2, 2.1.2.5.0** We installed ORACLE 7.3.2 server on stuttgart, our TMR server. Although there are no restrictions for using the TMR server as a database server, it is generally not recommended to have both functions on one machine. We used one machine for our convenience. This database server was also used for TEC requirements. During the ORACLE installation, we created the default instance ORCL and used the default settings. Installing and setting up TAPM 35 The Oracle database client was installed on the frankfurt system. The database client and the database server communicate with each other using the TCP/IP protocol. For details on database server and client installation, refer to the Oracle documentation. The TAPM database environment is shown in Figure 13. Tivoli Environment Oracle Database Client TAPM RIM Host Endpoint Gateway TCP/IP Uploading Data TAPM Oracle Database Server TMR Server dresden frankfurt stuttgart Figure 13. TAPM RIM host 3.4 Configuration of the TAPM environment The environment we created for TAPM installation is shown in Figure 14 on page 37. The role being played by each system in our TAPM environment is also mentioned in this figure. 36 Introducing Tivoli Application Performance Management TAPM Environm ent TM R Server/ TEC Server O racle Database Stuttgart OD BC TDS Ausres25 Create Virtual User Scripts Frankfurt Ausres24 Create & Replay Script Endpoin t kdsfnsnns sfndsnd s l l l l l fnn dsn ndsl kd l l Dresden Replay Virtual User Scripts Run ARM Instrumented Applications Figure 14. TAPM environment All of the machines in our environment were IBM PC 300PL except ausres24 and ausres25, which were IBM PC 300GL. Table 4 lists the hardware configuration of these machines. Table 4. Hardware configuration Model IBM PC 300GL IBM PC 300PL Processor Pentium II 350 Mhz Pentium II 400 Mhz RAM 164 132 The software configuration and the products installed on these machines are listed in Table 5 on page 38. k dsfn nns sfndsnd s l s l l l l f nnds n nds kd l l l pi cS t r tp cS ir k dsfnsn n sfndsnd s l l s l l l fn nd n nd skd s l l l tpicS r Report Gateway M anaged Node Snapper Building Reports Diskspace 4 GB 6 GB Installing and setting up TAPM 37 Table 5. Software configuration Product Name Windows NT 4.0 with Service Pack 5 Framework 3.6 TMA (Endpoint) DM 3.6 TEC 3.6 sever & console Oracle Server 7.3.2 Oracle Client 7.3.2 TDS components stuttgart X X frankfurt X X dresden X ausres24 X X snapper X X X X X X X X X The network is token ring, and we are using TCP/IP as the transport protocol. 3.5 TAPM installation Once we had the basic Tivoli managed environment ready, we started the TAPM installation. In this section, we will describe the installation of TAPM engine component (TAPM 1.0) and the TAPM monitor component (TAPM 1.0 Monitors for DM). 3.5.1 Installing on the TMR server and endpoint gateway The TAPM engine component must be installed on the TMR server and all the endpoint gateways in the managed environment. If an endpoint gateway in the environment does not have any endpoint on which you wish to perform application management, the TAPM engine need not be installed on it. The TAPM monitor component will only be installed on the TMR server. Before proceeding with the installation, ensure that your Tivoli database is healthy by running the wchkdb -u command. As per general Tivoli recommendations, you should back up your Tivoli environment prior to performing a product installation. A backup is required in order to restore your previous environment if any errors occur during the installation exercise or if you wish to revert to the old status for any reason. For further information regarding backups, consult the Tivoli Framework User’s Guide, GC31-8433. 38 Introducing Tivoli Application Performance Management After we backed up our Tivoli environment, we inserted the TAPM product CD-ROM in the CD-ROM drive of stuttgart, the TMR server. TAPM installation can be performed through any of the following three methods: • Desktop GUI • Command Line Interface • Software Installation Service We will describe all three installation methods in the following section. 3.5.1.1 Installation using desktop GUI TAPM is installed from the Tivoli desktop in the same way as any other Tivoli application. The installation steps are as follows: 1. Select Desktop -> Install -> Install Product from the Tivoli desktop as shown in Figure 15. Figure 15. Installing a product Installing and setting up TAPM 39 2. If the install path could not find the CONTENTS.LST file, you will get the next screen with an error message. This happens when the install path is set to a value other than the CD-ROM drive where the TAPM CD resides. Select the correct path of z:, which is the CD-ROM drive in stuttgart. Click the Set Media & Close button shown in Figure 16. Figure 16. Setting the installation media 3. The Install Product window will appear as shown in Figure 18 on page 42. We now have to choose the product we want to install. Select Tivoli Application Performance Management 1.0 to be installed on stuttgart (the TMR server), frankfurt (the Endpoint gateway) and ausres24 (the Managed Node). The target machines should appear in the Clients to Install on window. To install the product, click the Install and Close button shown in Figure 18 on page 42. 40 Introducing Tivoli Application Performance Management Note The TAPM engine component must be installed on the TMR server and all endpoint gateways that have endpoints from where you need to perform application management in the managed environment. Figure 17. Selecting the product 4. The message shown in Figure 18 on page 42 appears describing which components will be installed and their installation directories. Review the messages carefully since there could be errors; for example, there may not be enough free disk space available on the destination drive, and the installation will fail. To continue the installation, click the Continue Install button. Installing and setting up TAPM 41 Figure 18. TAPM installation message 5. This will start the actual installation and may take some time. Check the bottom of the window for the message scrolling to stop, and look for a message prompt to continue or a warning of any problem that occurred during installation. Once the product has been installed successfully, you will see the Finished product installation message as shown in Figure 19 on page 43. Select Close to finish the installation. 42 Introducing Tivoli Application Performance Management Figure 19. Installation complete 6. You will get back to the Install Product window as shown in Figure 17 on page 41. Thereafter, we installed the Tivoli Application Performance Management 1.0 Monitor for DM component, but only on the TMR server stuttgart. The target machine should appear in the Clients to Install on window as shown in Figure 20 on page 44. Click on Install and Close to start the installation. The rest of the installation continues as described for the TAPM engine component. 7. The TAPM installation is now complete. Installing and setting up TAPM 43 Figure 20. Selecting the target for the monitor component 3.5.1.2 Installation using Software Installation Service (SIS) The Tivoli Software Installation Service (SIS) is an application designed for the easier installation of Tivoli products in a Tivoli Management Region (TMR). SIS creates an install repository that contains the installation images of the product and pushes them down to the target machine. Software Installation Service should already be installed and configured in the Tivoli Environment. For more information on installing Software Installation Service, refer to Software Installation Service 3.6 User's Guide, GC31-5121. 1. From the Tivoli desktop, select Desktop -> Install -> Software Installation Service as shown in Figure 21 on page 45. 44 Introducing Tivoli Application Performance Management Figure 21. Installation using Software Installation Service 2. Enter the password that you gave when you installed Software Installation Service and click OK. 3. The SIS initial menu shown in Figure 22 will appear. Synchronize the TMR by clicking on the Synchronize with TMR button. Figure 22. SIS initial menu Installing and setting up TAPM 45 4. The SIS initial menu will again appear. Click on Install. 5. The SIS Install details windows shown in Figure 23 will appear. Click on Select Products to choose the products to be installed. Figure 23. SIS Install details 6. A list of products available for installation appears. We selected Tivoli Manager for Application Performance Server component and Tivoli Manager for Application Performance Monitor component from the Select Product window shown in Figure 24. The monitor component works in conjunction with Distributed Monitoring. Click OK to accept the selection. Figure 24. Selecting the products from SIS 46 Introducing Tivoli Application Performance Management 7. The selected products will now be shown in the SIS Install details window. Click Select Machine to identify the systems where you want to install the products. 8. Select stuttgart and frankfurt from the Select Machine window as shown in Figure 25 and click OK. Figure 25. Selection of machines 9. Figure 26 shows the products to be installed. In this example, we installed the TAPM engine on stuttgart (the TMR server) and frankfurt (the Endpoint gateway). The TAPM monitor was only installed on stuttgart. Click on Install, then OK. Figure 26. Confirming products and targets 10.Once the installation has been completed, click Close and quit the Software Installation Service. Installing and setting up TAPM 47 3.5.1.3 Installation using Command Line Interface TAPM components can also be installed from the DOS command line interface. We performed the following steps to install it: 1. Set up the Tivoli environment for executing Tivoli commands from the DOS window with the following command: %systemroot%\system32\drivers\etc\tivoli\setup_env.cmd 2. Type bash to open a bash shell to run UNIX/Tivoli commands and press Enter. 3. Install the TAPM engine component on stuttgart (TMR server) with the following command: winstall -c z:/ -i TAPM -n stuttgart where: • c is the path of the source code, which is the z drive for the CD-ROM. • i is the product to be installed; the product name should be a *.ind file. • n refers to the nodes on which the product will be installed. 4. Similarly, install the TAPM engine component on frankfurt (the Endpoint gateway) with the following command: winstall -c z:/ -i TAPM -n frankfurt 5. Install the monitor component on stuttgart (the TMR server) with the following command: winstall -c z:/tapmmon -i TAPMMON -n stuttgart where: • c is the path of the source code, which is the z drive for the CD-ROM. • i is the product to be installed; the product name should be a *.ind file. • n refers to the nodes on which the product will be installed. 3.5.2 Installing on the endpoint There is no component of Tivoli Application Performance Management 1.0 that needs to be installed on the endpoint. The TAPM engine and back end modules are automatically sent to the endpoint during the TAPM Profile distribution process. If you plan to use transaction simulation using either the LoadRunner or WinRunner, their runtime components will need to be installed on the desired endpoint. Its installation process will be covered in later chapters along with 48 Introducing Tivoli Application Performance Management their script creation process. The application instrumentation does not need any additional installation on the endpoints. 3.6 Uninstalling TAPM If, for any reason, you wish to uninstall the TAPM from your Tivoli environment, there are two ways to do it: • Run an uninstall script or • Manually uninstall TAPM files and directories In this section, we describe both processes. Prior to starting an uninstallation of TAPM, ensure that you have a consistent backup since this may be necessary if you face any problems. 3.6.1 Running the uninstall script We ran the uninstall script on stuttgart, the TMR sever, where it completed successfully. However, when we ran the uninstall script on the endpoint gateway, it did not complete successfully. Therefore, we used the manual uninstall process on the gateway. Perform the following steps: 1. Open a DOS window and configure the Tivoli Environment by entering: %systemroot%\system32\drivers\etc\tivoli\setup_env.cmd 2. Since the uninstall script is a shell script, we use the bash shell. Type bash and press Enter 3. Change to the following directory where the uninstall script resides: /Tivoli/bin/w32-ix86/TME/MAR 4. Execute the uninstall script for the TAPM engine by entering: uninstall.sh 5. Execute the uninstall script for TAPM monitor by entering: uninstallmon.sh 6. After uninstalling a product from the Tivoli environment, it is necessary to check the database for any inconsistencies. Run the following command: wchkdb -u The -u flag will fix any inconsistencies found in the Tivoli database. Installing and setting up TAPM 49 3.6.2 Manually uninstalling TAPM files and directories While performing the manual uninstall of TAPM, be very careful not to delete any other Tivoli directories since other Tivoli code also resides in the same directory. The Tivoli database backup without TAPM installation should be available prior to starting this manual uninstall process. In our environment, the TAPM files were located in the following directories: • c:\Tivoli\bin\lcf_bundle\bin\w32-ix86\TME\MAR • c:\Tivoli\bin\lcf_bundle\bin\win95\TME\MAR • c:\Tivoli\bin\lcf_bundle\MAR\w32-ix86 • c:\Tivoli\bin\w32-ix86\bin • c:\Tivoli\bin\w32-ix86\TME\MAR Perform the following steps to uninstall TAPM manually: 1. From the Windows menu, right click on Start and click Find 2. In the Named field, type *mar*. 3. In the Look in field, select the drive where TAPM was installed. Click Find Now. 4. First, delete the MAR directories; then, refresh by clicking Find Now. 5. Delete the remaining MAR files. 6. Repeat steps 2 through 6, but replace *mar* with *TAPM* 7. After deleting TAPM, restore the Tivoli database by performing the following steps: 1. Open a DOS window and configure the Tivoli Environment by typing: %systemroot%\system32\drivers\etc\tivoli\setup_env.cmd 2. Change to the directory containing the Tivoli database backup without TAPM installation. Our backup was in the following directory: C:\Tivoli\db\backups 3. To restore the database, type: wbkupdb -r -d filename where filename is the backup file that you want to restore. 4. You may be required to restart the oserv daemon on the TMR. 8. After uninstalling a product from the Tivoli environment, it is necessary to check the database for any inconsistencies. Run the wchkdb -u command. 50 Introducing Tivoli Application Performance Management The -u flag will fix any inconsistencies found in the Tivoli database. 3.7 TAPM configuration After completing the TAPM installation, we next configure the environment for appropriate usage. In this section, we will explain the process for adding MarProfile to the managed resources of our Policy Region, adding the TAPM notice group, creating an RIM object, and creating database tables. 3.7.1 Updating managed resources First, we have to add MarProfile and other required Tivoli resources to the managed resources of our Policy Region. You may do so by performing the following steps: 1. Double click the PolicyRegion stutgart-region to open it on the TME desktop. 2. Select Properties->Managed Resources to open the Set Managed Resources window and carry the following resources from Available Resources to Current Resources as shown in Figure 27 on page 52: • ManagedNode • MarProfile • Endpoint • ProfileManager • SentryProfile • TaskLibrary Installing and setting up TAPM 51 Figure 27. Set Managed Resources window 3.7.2 Notice group modification We need to add the TAPM Notice Group to the Administrator user account. This must be done to receive and view any notices containing information about configuring and running TAPM. Perform the following steps to modify the notice group: 1. Open the Administrators window by double clicking on the Administrators icon on the TME desktop. 2. Right mouse click on the administrator icon in the Administrators window and select Edit Notice Group Subscription from the pop-up menu. The Set Notice Group window will appear as shown in Figure 28 on page 53. 52 Introducing Tivoli Application Performance Management Figure 28. Add notice group 3. Select Tivoli Application Performance Management from Available Notice Groups and add it to the Current Notice Groups. Click on Change and Close, and all messages concerning TAPM will appear on the notice board. The notice board should look similar to Figure 29. Figure 29. Read notices Installing and setting up TAPM 53 3.7.3 Creating the RIM object After the installation of the TAPM components and database setup, you need to create the RIM object. To help you better understand why the RIM object is needed here, an explanation of the necessity of RIM and how to use it within TAPM follows. As with other Tivoli applications, such as TEC, the TAPM application uses RIM to access databases. It creates an RIM identifier, also called a TAPM RIM object, to be used in any database operation. This object must be unique within the whole TMR and must be created using a script that TAPM provides. Because the object is unique, this script must be run only once. You can run the script on any Gateway or Managed Node in the TMR or even at the TMR server. After the script is executed, the TAPM RIM object is available to the entire TMR and, specifically, can be accessed from any Gateway. The RIM host where the RIM object is created can either be the host where the database server is installed or a machine that has a database client installed, which, in our case, is frankfurt. Any Managed Node (including the Gateways) or the TMR server can be configured as the RIM host. You need the following information to create an RIM object: • vendor - RDBMS vendor's name (Sybase | Oracle | DB2 | MS_SQL) • host_name - This is a managed node that has the database client software installed on it. • rdbms_home - This is the directory where the DB client software is installed. If the host is NT, you need to put a drive letter at the front of this path. A file named either interfaces (for UNIX) or sql.ini (for WinNT) exists in this directory. This file and directory must be readable by users nobody and tmersrvd, if they exist. • server_id - This is the name of the server on which the dba server is installed; it can also be an alias that is defined in ORACLE, for example, in the tnsnames.ora file. • database id - This is the name of the instance of the RDBMS. • database user - This is the owner of the database (Sybase is case sensitive). 54 Introducing Tivoli Application Performance Management Note We have to create the RIM object before the table creation for TAPM because the values defined in the RIM object will be used by the cr_tapm_db.sh script, which creates the tablespace, tables, and users in our ORACLE database (tapm database creation). TAPM provides the cr_tapm_rim.sh in the $BINDIR/TME/MAR/SQL directory to create the RIM object. We created the RIM on frankfurt (gateway), which means we ran the script on this machine, and you can do so by performing the following steps: 1. To get the rights to create the RIM object on frankfurt, we added the Administrator login to the root administrator. Open the Administrators Icon from the Tivoli desktop. 2. Right mouse click on Root_stuttgart-region -> edit logins. 3. Add the login name Administrator and press Enter; then, click on Change and Close. 4. After adding the administrator, open a DOS prompt and run C:\winnt\system32\drivers\etc\tivoli\setup_env.cmd to set the Tivoli environment. 5. Start a bash shell by typing bash. 6. Change to the $BINDIR/TME/MAR/SQL directory. 7. Type ./cr_tapm_rim.sh to start the script. 8. The script will look for an existing RIM object, and, if none exists, you will be asked to enter the required information to create one. 9. Make the following entries: • vendor=Oracle. • host_name=frankfurt. • rdbms_home=c://orant - This is the home directory of the database client (frankfurt). • database id=ORCL. • database user id=tapm@stuttgart. • Note that the database user is tapm@stuttgart because the RIM host is not the database server but the database client. To look up the RIM objects attributes, use the wgetrim command: Installing and setting up TAPM 55 wgetrim tapm You can check the RIM connection by using the wrimtest -l tapm command, and a session will be opened if the RIM settings are correct. Close the session by typing x and press Enter. 3.7.4 Installing the TAPM database Now that the RIM object is created, the next step is to create the TAPM database. you will find the cr_tapm_db.sh script in the same directory where the RIM creation script is located (in our environment, it was in c:/usr/local/tivoli/bin/w32-ix86/TME/MAR/SQL). This script will use the attributes of the RIM object and the DBA client access method for database creation. Run the script from the bash by: ./cr_tapm_db.sh TAPM database creation will be started, and the script connects to the database using a sqlplus session. The script asks for the password of the user sys, and we typed change_on_install (default access password). It creates the tapm user identified by the password tapmtapm and the following tables: • APPLICATIONS • DATA32 • DATA64 • DATABUCKETS • HOSTS • ID_INFO • METRICDATA • TAPM_ID • TRANSACTIONS • USERS 56 Introducing Tivoli Application Performance Management Note If you ever need to uninstall the database components, change to the $BINDIR/TME/MAR/SQL directory and run the uninstall script rm_tapm_db.sh. This script will delete the tables, user, and tablespace. Before you can execute this script, delete the physical database files of your operating RDBMS. For example, if you are using ORACLE, connect as internal to the ORCALE Server, shut down the database, delete the tapm_DATA and tapm_TEMP files, and restart the database. 3.8 Summary In this chapter we have covered the TAPM installation. We have seen that TAPM monitor is installed on the TMR Server, whereas TAPM engine is installed on the TMR Server and Gateways. There is no component that needs to be installed on the endpoint. TAPM uses RIM object to log its data to an RDBMS system. Installing and setting up TAPM 57 58 Introducing Tivoli Application Performance Management Chapter 4. Sample application instrumentation In this chapter, we will describe the instrumentation of a simple C-program with ARM API calls to measure the response times of an application by TAPM. We will use the ARM Software Developer’s Kit (SDK), which provides header and library files to compile C or C++ source code. We modified the example code to show you the features of ARM API 1.0 and the additions to the ARM API Version 2.0. The additional functions in ARM API Version 2.0 are the transaction correlation within one system and additional information about the transaction (called application-defined metrics). 4.1 The Software Developer's Kit (SDK) The ARM SDK contains everything you need to prepare your application for transaction monitoring. The process by which you obtain the SDK and its installation are covered in detail in Appendix A, “Developer’s Kit for application instrumentation” on page 187. This development kit contains the following four components: • ARM Shared Library (libarm) The ARM Shared Library is a NULL shared library provided to resolve externals, such as functions, in the code. The NULL library is a default no-operation (NULL) shared library that contains all the function calls you will need. It allows you to instrument and run your applications without having an ARM agent, such as TAPM, running on your development machine. This way, the application developer is able to perform the initial testing of the intermitted application. Once the application has been successfully tested, it can be used in the production environment with TAPM. In the production environment, the ARM agent-specific library provided by TAPM may return errors whereas the development NULL library will always return a non-error condition (0). This means that even if the ARM call fails and an error code is returned in the production environment, the same call will return a 0, meaning processed successfully, while testing it with the NULL library. For the Windows NT platform being used by us for development purposes, this shared library is in the form of a file called libarm32.dll. Additionally, the source used to create the NULL library is part of the SDK. This is provided so that a shared library can be created for applications that exist on platforms not currently supported by the measurement © Copyright IBM Corp. 1999 59 technologies. The SDK contains NULL libraries compiled for UNIX systems and PC-based systems, such as the following: • HP-UX • IBM AIX • NCR MP-RAS • Sun Solaris • OS/2 • Windows NT • Windows 95 • Logging agent The source code and header file for a logging agent are supplied for use in testing your instrumentation. The logging agent captures the calls being made from the application and writes them into a file. It will not provide the functions of an ARM agent but gives you some information about the ARM calls being made by your application. The source code for a logging agent, logagent.c, has been included for use in testing your application. Unlike the NULL libraries, it is only in source format; so, it needs to be compiled. • Sample C programs Sample programs for C/C++ are provided as examples of how to instrument applications. • Header file A C language header file, arm.h, is supplied for applications written in either C or C++. The header file contains the declaration of the arm functions, prototypes, and metric structures. If you are using a language other than C or C++, the data structures and external references need to be translated into the language you are using. 4.2 ARM function calls Before instrumenting the application, we take a quick look at the ARM API 2.0 functions. The usage of these functions and their parameters have been explained in Appendix A, “Developer’s Kit for application instrumentation” on page 187. For a more detailed description of the ARM API 2.0 functions, refer to the SDK documentation. 60 Introducing Tivoli Application Performance Management 4.2.1 The ARM API call syntax The following is a list of syntax and usage examples for the six ARM API calls available for instrumenting an application: • arm_init Use arm_init to define the application or a unique instance of the application and user. Syntax: appl_id=arm_init(appl_name,appl_user_id,flags,data,data_size) Example: client_appl_id=arm_init("Client_Application", "*", 0,0,0); • arm_getid The arm_getid function call is used to assign a unique identifier to a transaction class and, optionally, to describe the format of additional data passed on arm_start, arm_update, and arm_stop calls. Syntax: tran_id=arm_getid(appl_id,tran_name,tran_detail,flags,data,data_size) Example: client_tran_id = arm_getid(client_appl_id, "Client_transaction", "First transaction in Client application", 0, 0,0); • arm_start Use arm_start to mark the beginning of a transaction execution. Syntax: start_handle=arm_start(tran_id,flags,data,data_size) Example: metric_tran_handle = arm_start(metric_tran_id, 0, (char *)buf_ptr, buf_sz); • arm_update Use this call for additional information about and the progress of a transaction; this is an optional call. Syntax: error_status=arm_update(start_handle,flags,data,data_size) Example: status=arm_update(metric_tran_handle,0, (char *)buf_ptr,buf_sz); Sample application instrumentation 61 • arm_stop Use arm_stop to mark the end of a transaction instance that was started with arm_start. Syntax: error_status=arm_stop(start_handle,tran_status,flags,data,data_size) Example: status=arm_stop(metric_tran_handle,ARM_GOOD,0,(char *)buf_ptr, buf_sz); • arm_end Use arm_end when you are finished initiating new activity using the ARM API. Syntax: error_status=arm_end(appl_id,flags,data,data_size) Example: status=arm_end(metric_appl_id, 0,0,0); Note Version 2.0 of the ARM API is backward compatible with Version 1.0. Applications instrumented using the ARM 1.0 API can continue to function correctly with agents that implement the additional features of the 2.0 API. 4.2.2 Return codes from ARM API calls Each of the ARM API calls produces a return code for analysis. In every case, this is 32-bits in size and is signed. The nature of the return code differs according to the call being made. The following ARM API calls return handles that are used in subsequent calls: • arm_init • arm_getid • arm_start The following ARM API calls return integer return codes: • arm_update • arm_stop • arm_end 62 Introducing Tivoli Application Performance Management You must declare integer variables in your program to hold the handles and return codes from the ARM API calls, but the handles cannot be treated as integer variables. The difference between handles and integers is that an integer is a numeric value on which numeric operations may be performed whereas a handle is a system-assigned shortcut to reference something that the system has created. The handle only has meaning to the ARM agent, and it cannot be modified in any way. 4.2.3 Good handles and return codes When your application makes successful ARM API calls, you can expect to receive the following returns: • arm_init positive integer • arm_getid positive integer • arm_start positive integer • arm_update zero • arm_stop zero • arm_end zero 4.2.4 Bad handles and return codes Any of the API calls can produce the following return codes: -1 An invalid argument was specified. Usually, this means that you made a mistake in the syntax of the call. For example, you may have coded too many or too few arguments on the call. If you are programming in C or C++, such errors will be caught by the linker when it attempts to resolve the external references in the shared library that is shipped with the agent. If you are calling the ARM API as external functions from another language, such as PowerBuilder, there is no link step, and, so, it is possible for such a mistake to slip by, and you will only be aware of it when the ARM API call is actually made. -2 The ARM agent is not running. This error usually occurs because the ARM engine has not been started on the machine where you are making ARM API calls. 4.2.5 Case sensitivity The ARM API calls are C functions, and are, therefore, case-sensitive. All the ARM API functions use lowercase throughout. If you code any part of the API calls in uppercase, you can get the following errors: Sample application instrumentation 63 • If you are programming in C or C++, the linker will fail to resolve the external functions. • If you are using a language other than C, the call will fail with a return code of -1. 4.3 Create an ARM-instrumented C application We will now explain the process of adding ARM API calls to an application. For our convenience, we used the sample C application (Sample2.c) supplied with SDK to create an ARM-instrumented application. The Sample2.c application simulates a client-server application. For simplicity, both the client and server components are implemented in one file. The main function will call the client and the metric function. The metric function prints some data to the screen whereas the client function calls the server function that will create a file and then returns to the client function. There is no data passed by the functions, and the transactions being processed are very simple. 4.3.1 Adding ARM function calls In general, the application can be separated into different sections. The initialization section, the processing section, and the end section. An application should be instrumented with ARM functions as shown in Figure 30 on page 65. 64 Introducing Tivoli Application Performance Management Application arm_init arm_getid transaction 1 arm_getid transaction 2 arm_getid transaction 3 11 12 1 2 3 Transaction 1 arm_start 10 9 8 7 6 5 4 response time processing 11 10 12 1 2 3 arm_stop . . . . . . 9 8 7 5 6 4 Transaction 2 Transaction 3 arm_end Figure 30. Instrument an application The following steps describe the process of creating an ARM-instrumented application: 1. Include the header file (arm.h) in the source code. 2. Identify the start and end of the application. Place the arm_init call at the top of the source code and the arm_end call at the bottom of the application. 3. Identify the transactions that need to be instrumented and the names associated with them. Sample application instrumentation 65 4. Place the arm_getid calls for every identified transaction at the top of your source code. We suggest using a function in which all the arm_getid calls are made to provide a good overview of all transactions. 5. Insert the arm_start calls prior to starting the execution of a transaction and the arm_stop calls after the transaction completes. Perform this activity for all the identified transactions. 6. Insert the arm_update call for long transactions. The usage of this call is optional and we have not used it in our application. You may want to use it for the following purposes: • It can provide a heartbeat to indicate that a transaction is still running. • It can inform you of the progress of a transaction so that you can see how much of the transaction’s work has been completed. • If a transaction hangs, it can be used to indicate the point at which the hang occurred. This is shown in Figure 31 on page 67. 66 Introducing Tivoli Application Performance Management Transaction 2 11 10 12 1 2 3 arm_start 9 8 7 6 5 4 processing Information like heabeat arm_update processing response time arm_update Information like transaction progress processing 12 11 1 2 3 8 7 6 5 4 arm_end 10 9 Figure 31. arm_update 7. Use the metric_data for arm_start, arm_update, and arm_stop to forward more information about the transaction to the ARM agent. To understand how to use the metrics, we will now provide a brief description. For more information, consult the SDK documentation. The buffers that you can use are declared in the arm.h header. We defined the buffer used in this program in the init_metric_application function. We used format 1, arm_user_data101_t structure, where you can store the following kinds of additional information: • counter • IDs • strings Sample application instrumentation 67 • gauges You do not have to use all the metrics provided. To define which metrics you want to use, switch the metric flags to the appropriate values. This is shown in Figure 32. init_metric_application */ /*****************************************************************************/ void init_metric_application() { type of buffer used flag to use all metrics arm_user_data101_t *buf_ptr, buf = { 101, {0, ARM_AllMetrics_f | ARM_String1_f, 0, 0}, {{1, "Metric #1 - Type 1 is a COUNTER32 "}, {4, "Metric #2 - Type 4 is a GAUGE32 "}, {2, "Metric #3 - Type 2 is a COUNTER64 "}, {9, "Metric #4 - Type 9 is a STRING8 "}, {3, "Metric #5 - Type 3 is a COUNTER32/DIVISOR32"}, {8, "Metric #6 - Type 8 is a NUMERICID64 "}, {10, "The last field is always a STRING32 "} }}; int32 buf_sz; buf_ptr = &buf; buf_sz = sizeof(buf); metric_appl_id=arm_init("Metric_Application", "*", 0,0,0); metric_tran_id = arm_getid(metric_appl_id, "Metric_transaction", "First transaction in 0, (char *)buf_ptr, buf_sz); /* application name */ /* use default user */ /* reserved */ /* appl_id from arm_init */ /* transaction name */ Metric application", /* reserved */ /* buffer */ /* buffer size */ return; Figure 32. init_metric_function You can fill the metrics with data that will be associated with the measured transactions to enable a more precise analysis of the transaction. For example, use the counter to summarize all transactions executed. The metric buffer is passed with the arm_start, arm_update, and arm_stop calls, and this data will be picked up by the ARM agent. We used this 68 Introducing Tivoli Application Performance Management buffer with the arm_update and arm_stop calls to collect some additional data; this can be seen in Figure 33. arm_update(metric_tran_handle, 0, (char *)buf_ptr, buf_sz); /* transaction handle from arm_start */ /* reserved for future use */ /* user metrics buffer pointer */ /* user metric buffer size */ buffer forwarded to ARM agent Figure 33. Forward buffer to ARM agent The above steps need not be followed in the above sequence, and some steps, such as the usage of metrics and arm_update, are not mandatory. 4.3.2 Compile and link the instrumented application After programming the application and instrumenting it with the ARM API calls, we need to compile the source code. You can find our instrumented ArmSample2.c source code in Appendix C, “Source file listing” on page 201. We also used the armtest.c source code, which is taken from the redbook Using Tivoli’s ARM Response Time Agents, SG24-2124. This was already instrumented with ARM calls, and we compiled it to use a simpler application (using only ARM API 1 functions). The application is shown in Appendix 8.1.2, “Registration of an ARM-instrumented application” on page 133. While compiling, you will need to specify the path of the arm.h header file and the library file libarm32.lib to the compiler. The prototypes for the arm_functions and the arm metric structures reside in the header file and will be resolved during the linkage step. The compile and link process for this application is shown in Figure 34 on page 70. We used the header and library files of the SDK, but they will also be available on the TAPM product CD. Sample application instrumentation 69 ArmSample2.c #include arm.h arm_init arm_getid source file arm_start shipped with SDK or TAPM arm_stop arm_end arm.h prototypes arm_functions data_buffer COMPILE ArmSample2.o object file libarm32.lib LINK arm_functions reside in libarm32.lib executable file ArmSample2.exe Figure 34. Compiling process 4.3.3 Testing the application To verify the instrumentation performed in the application, it is recommended that you perform the following tasks: 1. Link to the NULL library that is part of the ARM SDK. If the link fails, it means that you are not linking to the correct library or you are using incorrect names or parameters in at least one of the ARM API calls. Check the path names to the link libraries and the syntax of the arm calls. 2. Once you can link successfully, run your application, including the calls, to the API and verify that your application performs correctly. No testing of the API calls is done except for the linking parameters because the NULL library simply returns zero every time it is called. This means that even if the call is invalid, it returns a 0. Running the application is useful to ensure that you did not inadvertently alter the program in a way that affects its basic function. 3. Compile the logging agent source into a library object, and statically link it or include it within the application, and compile the code. We found the logagent.c in: e:\arm sdk\lib\logagent 70 Introducing Tivoli Application Performance Management 4. Link to the logging agent generated in the previous step. Run your application, including the calls, to the ARM API, and verify that your application performs correctly. The logging agent is provided for use in testing your instrumentation. It provides more information than the NULL library that only returns zeros, but it does not function as a measurement agent. Program calls to the ARM API by the application result in the creation of a text file log (logfile by default) that contains a time-stamped history of the calls and the parameter values associated with those calls. The logfile is created in the same directory where you run the application. 5. Manually review the log created by the logging agent to verify that the correct parameters are passed on each call. These parameters include transaction IDs to connect start calls to the correct transaction class, start handles to connect stop calls to the correct start calls, and any of the optional parameters. Optional advanced parameters include correlators that indicate the parent/child relationship between transactions and components and metrics about the transaction or application state. Search the log for error messages (identified by ERROR in the text) and informative messages (identified by INFO in the text). You can find information about the following: • Generated transaction IDs, handles, or correlators • Metric values This can be seen in the example log file in Figure 35 on page 72. 6. Once the application has been successfully compiled and verified, it can be used in the production environment with TAPM. Sample application instrumentation 71 16:15:32.sss: arm_init: Application User <*> = Appl_id <1> 16:15:32.sss: arm_getid: Application User <*> Transaction Detail 16:15:32.sss: arm_getid: Application User <*> Transaction = Tran_id <1> 16:15:32.sss: arm_init: Application User <*> = Appl_id <2> 16:15:32.sss: arm_getid: Application User <*> Transaction Detail . . . 16:15:32.sss: arm_start: Application User <*> Transaction = Start_handle <1> 16:15:32.sss: arm_start: Application User <*> Transaction Start_handle <1> Generated correlator: Length <40> Format <1> Flags <0> Address Format <1> Vendor_id <29999> Agent_version <201> Agent Instance <42> Start_handle <1> Tran_id <1> Address <426173696c2773204261722c205461626c652033> 16:15:32.sss: arm_init: Application User <*> = Appl_id <3> 16:15:32.sss: arm_getid: Application User <*> Transaction Detail 16:15:32.sss: arm_getid: Application User <*> Transaction = Tran_id <3> 16:15:32.sss: arm_start: Application User <*> Transaction = Start_handle <2> 16:15:32.sss: arm_stop: Application User <*> Transaction Start_handle <2> Status <0> 16:15:32.sss: arm_end: Application User <*> appl_id <3> 16:15:32.sss: arm_stop: Application User <*> Transaction Start_handle <1>Status <0> 16:15:32.sss: arm_start: Application User <*> Transaction = Start_handle <3> . . . 16:15:37.sss: arm_update: Application User <*> Transaction Start_handle <3> Metric < Metric #1 - Type 1 is a COUNTER32 > : <30988> 16:15:37.sss: arm_update: Application User <*> Transaction Start_handle <3> Metric < Metric #2 - Type 4 is a GAUGE32 > : <19012> 16:15:37.sss: arm_update: Application User <*> Transaction Start_handle <3> Metric < Metric #3 - Type 2 is a COUNTER64 > : <81985528891978256.000000> 16:15:37.sss: arm_update: Application User <*> Transaction Start_handle <3> Metric < Metric #4 - Type 9 is a STRING8 > : 16:15:37.sss: arm_update: Application User <*> Transaction Start_handle <3> Metric < Metric #5 - Type 3 is a COUNTER32/DIVISOR32> : 30988 / 2 = <15494.0000> 16:15:37.sss: arm_update: Application User <*> Transaction Start_handle <3> Metric < Metric #6 - Type 8 is a NUMERICID64 > : <0> < 0> 16:15:37.sss: arm_update: Metric < The last field is always a STRING32 > : . . . . . . 16:15:43.sss: arm_end: Application User <*> appl_id <1> 16:15:43.sss: arm_end: Application User <*> appl_id <2> A B Figure 35. Example logagent log file 72 Introducing Tivoli Application Performance Management 4.4 Using other languages The following section will give you an example of implementing ARM calls in other programming languages. 4.5 Implementing ARM calls using languages other than C The ARM API can be called from any language, but, today, the agents ship with header and library files for the C and C++ languages. If you are using a language other than C or C++, we can think of two ways to make calls to the ARM API: • Call the ARM API as an external C function from your programming language. • Convert the header and library files into a format suitable for your language. 4.5.1 Making ARM API calls from PowerBuilder applications We used a PowerBuilder application as an example of how to call the ARM API using a language other than C or C++. PowerBuilder provides its own development language called PowerScript. By following its syntax rules, you can make all the ARM APIs in PowerScript. Here is an example, from a PowerBuilder script, of how the ARM API calls can be made. After each call, this script pops up a window (as shown in Figure 36) to display the handle, which can be very useful during initial development and testing. arm_application = arm_init("new_account", "*",0,0,0) messagebox("arm_init" , string(arm_application)) arm_transaction = arm_getid(arm_application, "open", " " 0,0,0) messagebox("arm_getid" , string(arm_transaction)) arm_start_val = arm_start(arm_transaction, 0,0,0) t = getapplication() messagebox("arm_start" , string(arm_start_val)) t.af_opencustomer(s) arm_stop = arm_stop(arm_start_val, 0,0,0,0) messagebox("arm_stop" , string(arm_stop)) arm_end_val = arm_end(arm_transaction,0,0,0) messagebox("arm_transaction" , string(arm_end_val)) Figure 36. ARM API calls in a PowerBuilder script The script calls the ARM API functions. In order for these function calls to be Sample application instrumentation 73 resolved, you will need to declare the ARM API functions to PowerBuilder as Global External Functions. To do this, in a PowerBuilder window, click Declare on the toolbar and open the Global External Function editor. Now, you can fill in the ARM function prototypes exactly as shown in Figure 37. Note that these declarations are case-sensitive; everything must be in lowercase. If you are accessing this book in softcopy, for example, on the Internet or from a CD, we suggest that you copy and paste the definitions to avoid the possibility of typing errors. function long arm_init(string name,string user_id,long flag,long data,long size) library "libarm32.dll" function long arm_getid(long id,string name,string detail,long flag,long data, long size) "libarm32.dll" function long arm_start(long id,long flag,long data,long size) library "libarm32.dll" function long arm_update(long handle,long flag,long data,long size) library "libarm32.dll function long arm_stop(long handle,long status,long flag,long data,long size) library "li function long arm_end(long id,long flag,long data,long size) library "libarm32.dll" Figure 37. Declaring the external functions to PowerBuilder Now, when the PowerBuilder application runs, the ARM calls that it makes will be resolved in the external function definitions and will result in ARM API calls being made to the ARM Client agent, as shown in Figure 38. PowerBuilder script arm_init arm_getid arm_start External Function Definitions function long arm_inlt(string.. function long arm_getid(ong.. function long arm_start(long.. function long arm_update(long... function long arm_stop(long... function long_end(long.. ARM Client Agent ARM API Calls T1 arm_stop arm_end T2 PowerBuilder Application Figure 38. Resolving the ARM calls as PowerBuilder external functions 74 Introducing Tivoli Application Performance Management 4.6 Summary In this chapter, we have described the instrumentation of a simple C-program with ARM API calls to measure the response times of an application by TAPM using the ARM Software Developer’s Kit (SDK). We explained the ARM function calls with examples. Sample application instrumentation 75 76 Introducing Tivoli Application Performance Management Chapter 5. Sample script creation using WinRunner This chapter provides information about how to create virtual user simulation scripts using Mercury’s WinRunner product for usage by TAPM. We created a sample script simulating an end-user accessing the Internet using Netscape Navigator 4.5 to describe the script-creation process. The script starts Netscape Navigator, loads the defined home page, goes to the IBM Web site, searches for the word product in all the IBM Web sites, and, finally, closes Netscape Navigator. The different transactions performed during this process are then instrumented using ARM API calls for monitoring by TAPM. The script we created is very simple, the idea being to show the script creation process. No error handling routines were added to this script for their unattended execution in a production environment. You may customize it for your requirements. The script creation process using WinRunner is explained in detail in the WinRunner User’s Guide, which is shipped along with TAPM and should be used for creating scripts for your organizational requirements. The WinRunner script creation process is broken up into the following five basic steps, which will be described later in this chapter: • WinRunner installation • GUI Map creation • Recording a script • Script execution and verification • Preparing the script for TAPM We created our sample virtual user WinRunner script on a stand-alone NT workstation. This machine was not a Tivoli managed resource. 5.1 WinRunner installation The WinRunner tool is both for development and replaying of WinRunner scripts; therefore, we will install WinRunner on the machines on which we want to record our scripts as well as on endpoints where they will be played back. The development machine for recording the scripts can even be a stand-alone machine not connected to the network. We installed WinRunner on the dresden, ausres24, and ausres25 systems. The dresden system was configured as an endpoint in our Tivoli environment and was used to play © Copyright IBM Corp. 1999 77 back the recorded scripts when used through TAPM, and the ausres24 and ausres25 systems were used to create our sample scripts. 5.1.1 System requirements WinRunner needs an IBM-PC or compatible with a Pentium/100MHz or higher microprocessor, 32 MB of RAM memory, and 63 MB of free disk space for a compact installation or 115 MB for a typical/complete installation. During installation, you will need an additional 5 MB of free disk space. The supported operating systems are Windows 95, Windows 98, and Windows NT 4.0. 5.1.2 Installation process The WinRunner toolkit is located on the TAPM product CD-ROM in the VirtualUsers\WinRunner folder. We installed it on the three systems, dresden, ausres24, and ausres25, using the default parameters as follows: 1. Start the Windows explorer and click on VirtualUsers and then on the WinRunner folder. 2. Double click on setup.exe file to execute it. 3. Click Yes to accept the Software License Agreement. 4. Provide your name, the name of your company, and your maintenance number in the Registration window. We used the maintenance number 1712667 with the early code that we had. Check for the current number in the TAPM product Release Notes. After providing this information, click Next. 5. Click Yes to confirm the settings. 6. Select Standalone Installation and click Next on the next window. 7. Choose Typical Installation and click Next. 8. Specify the destination folder (we used the default location settings), and click Yes. 9. Specify the location of the temporary files, and click Next. 10.Confirm the settings, and click Next. 11.The WinRunner install process starts. We replaced the ODBC Manager and driver with a newer version (ODBC 3.51) and went on with the installation by clicking on the Install ODBC button. 12.Select the Program Folder for WinRunner and click Next to proceed. 78 Introducing Tivoli Application Performance Management 13.On the next two information windows, click on Yes and finish the installation, but do not restart the computer because you should run another utility before concluding the installation. 14.Select Start -> Run from the windows, and type z:\ToolKitsFinalSetup\instutil.exe to run this utility program. . Note If you do not run instutil utility, you will get an error while trying to run the WinRunner application. WinRunner will be unable to locate some specific dll files. You will be able to run WinRunner and create scripts, but, while using the WinRunner ARM functions within the script, it will cause a load_dll Error and RPC_ERRO while executing. 15.After you run this program, a DOS window will open, and screen text output will be shown as follows: Z:\ToolKitsFinalSetup\books\books.pdf ==> C:\Program Files\Mercury Interactive\W inRunner\doc\books\books.pdf Succeeded Z:\ToolKitsFinalSetup\addtoWR\lrlibscript ==> C:\Program Files\Mercury Interacti ve\WinRunner\lib/lrlib/script Succeeded Z:\ToolKitsFinalSetup\addtoWR\slminitscript ==> C:\Program Files\Mercury Interac tive\WinRunner\lib/slminit/script Succeeded Z:\ToolKitsFinalSetup\addtoWR\winarm.dll ==> C:\Program Files\Mercury Interactiv e\WinRunner\arch/winarm.dll Succeeded Z:\ToolKitsFinalSetup\addtoWR\libarm32.dll ==> C:\Program Files\Mercury Interact ive\WinRunner\arch/libarm32.dll Succeeded Z:\ToolKitsFinalSetup\slmutils.dll ==> C:\Program Files\Mercury Interactive\WinR unner\bin mercury.ini.[SLM].SAVE_AS_AMS=1 mercury.ini.[SLM].SLMUTILS=C:\Program Files\Mercury Interactive\WinRunner\bin\sl mutils.dll mercury.ini.[SLM].TOOLKIT_CHANGES=1 Z:\ToolKitsFinalSetup\AmsFormatFile.txt ==> C:\Program Files\Mercury Interactive \WinRunner\dat Installation completed success fully Please hit to finish> 16.Press Enter to close the process. Restart the computer to finish the WinRunner installation. Sample script creation using WinRunner 79 5.2 GUI map creation The first activity is to create the GUI map so that WinRunner can recognize the GUI objects and learn about their properties in your application. The GUI map can be created using the following automatic process, which we employed, or can be manually created by adding descriptions of individual GUI objects while creating the script. 1. To start WinRunner, select Start -> Programs -> Winrunner -> Winrunner. The Welcome to Winrunner window appears as shown in Figure 39. Figure 39. Winrunner welcome screen 2. Select Rapid Test Script Wizard in the WinRunner Welcome screen when you start WinRunner. Alternatively, select Create -> RapidTest Script Wizard if you are within WinRunner. Rapid Test Script Wizard enables WinRunner to learn all windows and objects in your application at once. It systematically opens every window in the application and learns the GUI objects. 3. Click Next on the RapidTest Script Wizard Welcome window. You will be asked to identify the application for creation of the GUI map. 4. It is suggested that you close or minimize all your windows prior to identifying your application. Open your application. In our case, we started Netscape Navigator and clicked on the hand icon in the RapidTest Script Wizard window. Figure 40 on page 81 shows the RapidTest Script Wizard window after it has learned the application name. The Austin ITSO Center indicated in the window is the default Web page loaded after starting Netscape Navigator. 80 Introducing Tivoli Application Performance Management Figure 40. Selecting the window 5. Click Next. From the Select Tests window, select the following tests as shown in Figure 41: • A GUI Regression Test • A User Interface Test • A Test Template Figure 41. Selecting tests where: • A GUI Regression Test enables you to compare the state of GUI objects in different versions of your application. When you run the test on your application, WinRunner compares the captured state of GUI objects to their current state and reports on all discrepancies. Sample script creation using WinRunner 81 • A Bitmap Regression Test enables you to compare bitmap images of your application in different versions of the application. When you run the test, WinRunner compares the captured window images to the current windows and reports any mismatches. We did not use this test. • A User Interface Test checks whether your application complies with Microsoft Windows standards. When you run this test, WinRunner searches the user interface of your application and reports each case that does not adhere to Microsoft Windows standards. • A Test Template provides the basic framework of an automated test that navigates your application. It opens and closes each window leaving space for you to add code (through recording or programming) that checks the window. 6. Click Next in the Select Test window. You can provide the characters or symbols used in your application’s user interface to open new windows. We left it in default values. Click Next, select express, and click Learn. 7. Click on your Web browser, and observe as WinRunner goes through each button and menu on the Web browser window. This process will take several minutes. When it has completed, select No (do not load at startup) and click Next on the Start Application window. 8. Accept the default locations to store the GUI maps and click Next and then OK. Note We saved our GUI map file as server.gui in the default location where we installed WinRunner, that is, C:\Program Files\Mercury Interactive\Winrunner\dat. 5.3 Recording a script Now, we can create our virtual user scripts through the WinRunner recording and programming process. Since the virtual user script is supposed to be running in unattended operational mode, it is suggested that you include all the thinking processes in the creation of the script. We performed the following steps: 1. From Winrunner, click File -> New. Select Create -> Record-Context Sensitive as shown in Figure 42 on page 83. The Context Sensitive mode of recording records the operations you perform on your application by identifying Graphical User Interface (GUI) 82 Introducing Tivoli Application Performance Management objects. There is another mode of recording tests called Analog mode, which records keyboard input, mouse clicks, and the precise x and y coordinates traveled by the mouse pointer across the screen. Figure 42. Recording a script 2. Now, we can perform our actions for recording in the script. We first start our Netscape Navigator by selecting Start -> Programs -> Netscape Communicator -> Netscape Navigator from the Windows panel. Notice that Winrunner starts recording the actions being performed. When Netscape starts, it will either start with a default home page or a blank page. This configuration can be set from Netscape. Note The script once recorded on the development machine will get executed on different machines in the network in unattended mode. In order for the script to be successfully executed, ensure that the file names, folders, default home page, and so on are the same in the end devices as those in the development machine. For example, if the default start page changes in Netscape, the script will be unable to run; therefore, it is important to ensure that Netscape (on your recording environment) and your execution environment be set up uniformly. 3. If a default start page exists, it must have completed loading before we proceed. To confirm that the page has been loaded, we capture the status bar at the bottom of the Netscape window. From the WinRunner menu bar, Sample script creation using WinRunner 83 select Create -> GUI Checkpoint -> For Object/Window as seen in Figure 43. The addition of this checkpoint in the script is to ensure that the initial loading is completed prior to executing the next step for proper measurement of response time in this transaction. You can add GUI, bitmap, text, and database checkpoints as well as synchronization points to your test script. Figure 43. Capturing the Status bar 4. Click on the window you want to capture. We selected the Document Done: window at the bottom of the main Netscape Window. Figure 44. Document status 5. Enter the desired URL in the location field of the Web browser. We typed http://www.ibm.com. Again, to confirm that the page has been loaded successfully, run Step 3. 6. While WinRunner records your steps in the background, browse through your desired Web site as you would usually do. Repeat Step 3 after each new page has been loaded. Once finished, it is suggested that you close 84 Introducing Tivoli Application Performance Management your application as part of the recording process. From the Netscape menu bar, click File -> Exit. This will allow you to run the script several times without having multiple windows opened. 7. To stop recording the script, select Create -> Stop Recording from the WinRunner menu bar. 8. Save the script with the desired name by selecting File -> Save from the WinRunner menu bar. The information saved is in the form of a directory with the specified name. 5.3.1 GUI map consolidation Although a GUI map was created in Section 5.2, “GUI map creation” on page 80 (in our case, server.gui) WinRunner will learn more about the application (Netscape) as the script is being created. This is due to certain menu functions being unavailable at the time the GUI map was created. The new GUI information is stored in a temporary GUI file. To have a final consolidated GUI map file, we need to merge this temporary GUI created during the script creation process with the GUI map server.gui created earlier. The steps we used are as follows: 1. From the WinRunner menu, select Tools -> GUI Map Editor to open the GUI Map Editor window. 2. Click View -> GUI Files from the menu bar. 3. If only one panel is visible, click on the expand button. If both panels are visible, in the left panel, select Temporary as the GUI file. Highlight the objects in the Window/Objects window that you want to merge. In the right panel, select the GUI file that you want merged. We selected server.gui. Click move and then OK. This is shown in Figure 45 on page 86. Sample script creation using WinRunner 85 Figure 45. Merging GUI files 4. Select File -> Save from the GUI Map Editor window to save the GUI map. 5.4 Verify script execution Now that we have the script ready, we need to test it to verify its correctness. Before the script can be executed for testing, we need to load the GUI map created earlier for the application. The GUI map will allow WinRunner to understand the application window. By default, the last GUI map file is loaded. 5.4.1 Loading GUI map Loading the GUI map can be done in one of the following three ways: • Insert the GUI load command in the script • Use the GUI map editor • Edit the myinit file 5.4.1.1 GUI load command The following entry can be added at the beginning of the script to load the GUI map: GUI_load("D:\\TI\\Ti4521\\WinRunnerTest\\Server.gui") 86 Introducing Tivoli Application Performance Management where Server.gui is the name of the GUI map D:\\TI\\Ti4521\\WinRunnerTest is the path for the GUI Map file. Note WinRunner uses double slashes to specify the path for the script. 5.4.1.2 GUI Map Editor The GUI map can be loaded manually from the WinRunner menu bar as follows: Select Tools -> Gui Map Editor from the WinRunner menu bar. We selected File -> Open from the GUI Map Editor window and clicked on server.gui. Figure 46 shows the GUI map editor after server.gui has been added. Figure 46. GUI map editor To delete a GUI map, select the GUI file that you want deleted and click File -> Close from the GUI Map Editor window. The Temporary GUI cannot be removed, but its contents can be deleted. To delete the contents of a GUI map, select the GUI map, and, in the Windows/Objects window, select the unwanted files and click Delete. Sample script creation using WinRunner 87 5.4.1.3 Editing the myinit file The myinit file is loaded when WinRunner starts up. The file is located in C:\Program Files\Mercury Interactive\Winrunner\dat\myinit\. This is the default drive on which we chose to install the product. From the WinRunnner menu, select File -> Open to open myinit.ams. Add the following entry to this file: GUI_load("C:\\Program\\Files\\Mercury Interactive\\WinRunner\\dat\\ server.GUI") where server.gui is the GUI map that we used. Note Multiple GUI maps can be added in the myinit file. The myinit file is loaded every time WinRunner starts and sets your environment. If you have two different GUI maps with the same object name, it can cause problems when you try to load the second GUI map. WinRunner will tell you that this object is already loaded and does not load the second GUI map. The same GUI map can only be added once. 5.4.2 Script execution From the Winrunner menu, select Run -> Run from Top. The script can also be run from wherever the arrow is located, or it can be run in steps (for trouble shooting). Open windows of the same application can cause the error message Object not found. This can be solved by closing the running application and restarting the script again. To verify that all components of the script have run successfully, a WinRunner Test Results window can be viewed. Select Tools -> Test Results. Successful steps are shown in green, and those that failed will be displayed in red. By double clicking on these steps, more information can be obtained. The response times that appear here are not TAPM times but the times measured by WinRunner during the execution of the scripts. Figure 47 on page 89 shows the test results after a script was executed. 88 Introducing Tivoli Application Performance Management Figure 47. Status window 5.5 Preparing script for TAPM In order to use the WinRunner virtual user script in the TAPM environment, we need to add function calls to the script that work in conjunction with TAPM. After the developing and testing process described in the previous sections, we started to instrument the script with special lr_functions that define the name of the application, the name of the user, and the transaction information. The lr_functions are needed to make the ARM API calls for a WinRunner script and are generated by WinRunner. We need to identify the transactions in the virtual user script for each business process whose response time you want to measure. We decided to measure response time for the following transactions: • Execution of the entire script • Loading of the home page • Loading of IBM Web site • Search time on IBM Web site Once a script is instrumented, that is, once it is ready for use with TAPM, it can be integrated into a TAPM profile for distribution to end-user devices. The process will be covered in later chapters. Sample script creation using WinRunner 89 You can easily insert the lr_functions in the script, and we did so by performing the following steps: 1. Select Create -> Insert Function -> From Function Generator from the WinRunner menu bar. The Function Generator window, as shown in Figure 48, will pop up. Figure 48. WinRunner function generator 2. From the Category drop down menu, select the ARM category, and only the WinRunner ARM functions will be shown. Choose the lr_set_sub_transaction function. 3. Click on the Args button and modify the Sub-Transaction argument to 1. This enables the correlation of transactions; click on Paste to insert the function in the script. This is shown in Figure 49. Figure 49. WinRunner function generator Args 90 Introducing Tivoli Application Performance Management 4. Repeat the above step of choosing Function Name and clicking on Paste to insert all lr_functions in our script. Optionally, when you think you are familiar with the syntax, you can type them in the script manually. 5. Insert the lr_set_application_name statement to define the ARM application name. The call must be made after the lr_set_sub_transaction statement but before any start transaction function is called; so, put them in the beginning of the script. The ARM application name is the name used to register the application to TAPM. We called our application Netscape_app. 6. Insert the lr_set_user_name statement after lr_set_application_name. We set this parameter to *. 7. Insert the lr_start_transaction and lr_end_transaction statements to define the business processes, or transactions, whose response time you want to measure. Place the lr_start_transaction statement immediately before the action you want to measure. Place the lr_end_transaction statement after the last statement of the transaction. Add these statements according to the defined transactions. We named the transaction for measuring the execution time of the script main_trans. The first parameter passed is the name of the transaction, and the second is the status of the stopped transaction. We inserted the lr_end_transaction function after closing the netscape application (as well as the lr_end_application function) to clear the environment. Insert lr_start_sub_transaction statements within a parent transaction to define subtransactions whose response times you want to measure. We decided to measure a subtransaction, which is the loading of the IBM site; so, we used the lr_start_sub_transaction function with the parameters sub transaction name and child transaction name. lr_start_sub_transaction("ibm_web_trans","main_trans"); Like a transaction, the sub transaction is also stopped by a lr_end_transaction call; so, we inserted it after the correct loading of the IBM Web site. 8. Insert lr_set_transaction_status statements within transactions if you want to set the status (pass or fail) of the transaction. We did not use it. 9. Insert lr_set_transaction_metrics statements to define metrics for a specified ARM transaction. Use a separate lr_set_transaction_metrics statement for each set of metrics you want to define. We used the next transaction in our script to show this enhanced function of ARM API 2.0. We set the metrics with the lr_set_transaction_metrics function to get more information about the word being searched. Sample script creation using WinRunner 91 lr_set_transaction_metrics("search_prod_trans","page",ARM_METRIC_LONG_S TRING,"products",7); 10.Save the script with the desired name. We named our script Nets_Bkup. The WinRunner script that we created and distributed to the endpoint is shown in Figure 50 on this page and Figure 51 on page 93. 5.5.1 Script execution with implemented ARM calls Once the script is instrumented with ARM API calls for usage by TAPM, it can be executed from the test environment to verify its correctness. To run the script in the test environment, follow the steps described in Section 5.4, “Verify script execution” on page 86. This test run will ensure that you did not inadvertently corrupt the script while inserting the lr_functions. The execution of the script will not measure any transaction time of the ARM API calls because the calls are run against the ARM null library. Note When using this script at the end user location through TAPM, the ARM null library, libarm32.dll in the \Program Files\Mercury Interactive\WinRunner \arch directory, needs to be renamed so that actual TAPM agents start collecting the data. #Loads GUI Map GUI_load("D:\\TI\\Ti4521\\WinRunnerTest\\Server.gui"); # ARM API defining section lr_set_sub_transactions(1);# Allow sub-transactions for ARM API value=1 lr_set_application_name("netscape_app");# Defining the ARM application name lr_set_user_name("*"); Defining the ARM user # lr_start_transaction("main_trans");# Starting to measure the main transaction set_window ("Shell_TrayWnd", 4); #Starting Netscape button_press ("Start"); menu_select_item ("Programs;Netscape Communicator(Common section);Netscape Navigator"); set_window("Austin ITSO Center - Netscape", 9); obj_check_gui("Status Bar", "list1.ckl", "gui1", 1); if (E_OK!=0){exit(E_GENERAL_ERROR);} Figure 50. WinRunner script page 1 92 Introducing Tivoli Application Performance Management set_window ("Austin ITSO Center - Netscape", 14); obj_mouse_click ("Status Bar", 84, 6, LEFT); #Opening the IBM website lr_start_sub_transaction("ibm_web_trans","main_trans"); # Starting the subtransaction edit_set ("Location:_1", "www.ibm.com"); obj_type ("Location:_1",""); set_window("IBM Corporation - Netscape", 8); #Waits for window to be loaded and return if fails obj_check_gui("Status Bar", "list2.ckl", "gui2", 1); if (E_OK!=0){ lr_end_transaction("ibm_web_trans",LR_FAIL); exit(E_GENERAL_ERROR); } lr_end_transaction("ibm_web_trans",LR_PASS); End of subtransaction # obj_mouse_click ("Status Bar", 110, 5, LEFT); set_window ("IBM Corporation - Netscape", 21); edit_set ("Edit", "products"); #Serach for "products" lr_set_transaction_metrics("search_prod_trans","page",ARM_METRIC_LONG_STRING,"products",7 lr_start_transaction("search_prod_trans"); Start transaction # obj_mouse_click ("Afx:400000:3028", 403, 83, LEFT); set_window("IBM Search Results: products - Netscape", 20); #Waits for window to be loaded and return if fails obj_check_gui("Status Bar", "list3.ckl", "gui3", 1); if (E_OK!=0){ lr_end_transaction("search_prod_trans",LR_FAIL); exit(E_GENERAL_ERROR); } set_window ("IBM Search Results: products - Netscape", 20); obj_mouse_click ("Status Bar", 257, 11, LEFT); obj_mouse_click ("Afx:400000:3028", 210, 186, LEFT); lr_end_transaction("search_prod_trans",LR_PASS); Stop transaction # # End Netscape win_close ("IBM Search Results: products - Netscape"); #win_close ("IBM Products - Netscape"); lr_end_transaction("main_trans",LR_PASS); Stopping main transaction # # Closing the ARM application lr_end_application(); Figure 51. WinRunner script page 2 Sample script creation using WinRunner 93 5.6 Summary In this chapter, we have described the steps for creating virtual user simulation scripts using Mercury’s WinRunner product for usage by TAPM. Taking our script as a base, you may further customize the script for your own needs. 94 Introducing Tivoli Application Performance Management Chapter 6. Sample script creation for LoadRunner In this chapter, we will describe how to create a sample virtual user simulation script by using the Virtual User Generator (VuGen), which is a component of LoadRunner, for usage by TAPM. VuGen has the capability of recording scripts of different application types. In our exercise, we have confined ourselves to recording a Web application script. We created a sample script simulating an end user accessing the Internet using Internet Explorer 3.0 to describe the script creation process. The script initiates the Web browser, loads the defined home page, goes to the IBM Web site, searches for the word product in all the IBM Web sites, and, finally, closes the Web browser. After recording the script, we instrument the script using ARM API calls for monitoring by TAPM. The created script is very simple, the idea being to indicate the script creation process. No error handling routines were added to this script for their unattended execution in a production environment. The LoadRunner script creation process is broken up into the following five basic steps, which will be described later in this chapter: 1. LoadRunner installation 2. Recording a Business Process 3. Passing parameters to script 4. Script execution and verification 5. Preparing script for TAPM 6.1 LoadRunner installation The LoadRunner product has two components: The development tool called VuGen, which also has the ability to play back scripts, and the run-time only component called Robotic Client. This is contrary to WinRunner product wherein both the development and execution components were merged into a single product. This has an advantage in that you need not install the development component on the systems where you simply need to execute the scripts. To record Loadrunner scripts, you can install VuGen on any machine and also play them back for testing purposes whereas the Robotic Client must reside on a machine that only plays back the VuGen and QuickTest/SAP scripts. © Copyright IBM Corp. 1999 95 We installed VuGen on ausres24 and ausres25 machines where we created our development environment to create the scripts. The Robotic Client was installed on the Tivoli endpoint, the end-user machine dresden, where we wanted to measure the application performance through TAPM. Before proceeding with the installation of LoadRunner 5.02 components, uninstall any previous versions of LoadRunner to avoid any conflicts. 6.1.1 System requirements VuGen takes about 120 MB of disk space, but, without samples, it takes about 80 MB. The Robotic Client (run-time) takes about 40 MB of disk space. The minimal memory requirement is 32 MB. The operating system must be Windows 95, Windows 98, or Windows NT. 6.1.2 VuGen installation The VuGen toolkit is located on the TAPM product CD-ROM in the VirtualUsers\VuGen folder. Before starting your installation, make sure you read the Readme file that, on our CD, is located in the VirtualUsers\VuGen\slm_lr\readme.nt\dat directory. We installed it on the two systems ausres24 and ausres25 using the default parameters as follows: 1. Start the Windows explorer; click on VirtualUsers and then on the VuGen folder. 2. Double click on setup.exe file to execute it. 3. Select Typical and click Next in the Setup Type window. 4. Specify the destination folder settings and click Next; we used the default settings. 5. Click Next to confirm the settings. 6. The product copy process will now start. After the installation process, two information windows are shown; click OK to continue. 7. Select the default Program Folder, which should be created for VuGen, and click Next to proceed. 8. The following DOS window will appear; press any key to continue. 96 Introducing Tivoli Application Performance Management CFG_TAB_DLL=saprts_tab.dll TemplateDir=sap 32BitRecord=FALSE 16BitRecord=FALSE WINNT=mdrv.exe -drv_pt_coinit ole WIN95=mdrv.exe -drv_pt_coinit ole WINNT_EXT_LIBS=SapMtdExt.dll WIN95_EXT_LIBS=SapMtdExt.dll WINNT_DLLS=SapReplayApi.dll WIN95_DLLS=SapReplayApi.dll EnableThreads=1 LibCfgFunc=sap_configure the following part attached to C:\Program Files\Mercury Interactive\Virtual User Generation\dat\vugen.dat [ExtraExtension] vugdbg_ext=vugen_dbg,ArmExtDll the following part attached to mercury.ini [SLM] TOOLKIT_CHANGES=1 SLMSETUP: Added lr_arm.h to lrun.h successfully Slm Variables setup finished. Press any key to confirm 9. On the last window, we elected not to restart our computer and finished the installation by clicking the Finish button. 10.Select Start -> Run from the windows and type z:\ToolKitsFinalSetup\instutil.exe to run this utility program. This process was also carried out while installing WinRunner. 11.After you run this program, a DOS window will open; press any key to complete the process. Restart the computer to finish the VuGen installation. 6.1.3 Robotic Client installation The Robotic Client toolkit is located on the TAPM product CD-ROM in the VirtualUsers\RoboticClient folder. Because we wanted to play back the scripts on dresden, we only installed the Robotic Client on this system. The following are the installation steps: 1. Start the Windows explorer and click on VirtualUsers, RoboticClient, and then the Setup folder. 2. Double click on the setup.exe file to execute it. 3. Click Next on the Welcome to TAPM Run-Time installation window. 4. Choose the destination folder and click Next; We chose the default location. Sample script creation for LoadRunner 97 5. The product copy process will now start. After the installation process, click Finish to complete the process. 6. The following DOS window will appear; press any key to continue. TAPM Runtime Installation CFG_TAB_DLL=saprts_tab.dll TemplateDir=sap 32BitRecord=FALSE 16BitRecord=FALSE WINNT=mdrv.exe -drv_pt_coinit ole WIN95=mdrv.exe -drv_pt_coinit ole WINNT_EXT_LIBS=SapMtdExt.dll WIN95_EXT_LIBS=SapMtdExt.dll WINNT_DLLS=SapReplayApi.dll WIN95_DLLS=SapReplayApi.dll EnableThreads=1 LibCfgFunc=sap_configure the following part attached to C:\Program Files\Mercury Interactive\tapm_runtime \dat\vugen.dat [ExtraExtension] vugdbg_ext=vugen_dbg,ArmExtDll the following part attached to mercury.ini [SLM] TOOLKIT_CHANGES=1 SLMSETUP: Added lr_arm.h to lrun.h successfully Slm Variables setup finished. Press any key to confirm 7. Manually update the windows path to %INST_DIR%\bin, which, in our case, was c:\Program Files\Mercury. 8. Select Start -> Run from the windows and type z:\ToolKitsFinalSetup\instutil.exe to run this utility program. 9. After you run this program, a DOS window will open; press any key to complete the process. Restart the computer to finish the Robotic Client installation. 6.2 Recording a business process We recorded the same business processes as were recorded with WinRunner to provide a comparative view of the two methods of creating virtual user scripts. We recorded our script on ausres24, a Windows NT machine, where VuGen was installed. The following are the script creation steps we performed: 98 Introducing Tivoli Application Performance Management 1. To start the Virtual User Generator, select Start -> Programs -> Virtual User Generator -> Virtual User Generator. The Virtual User Generator window will appear as shown in Figure 52. Figure 52. Virtual User Generator window Note When recording a Netscape script, make sure that you have closed all Netscape windows before starting; otherwise, you will get an error message. We were unable to record a Netscape script using socks server settings. The Netscape script could be created only after changing the Netscape preference settings to use an HTTP proxy. 2. Select File -> New to start the recording process. 3. Select Web user from the New Virtual User window, and click OK. The window is shown in Figure 53 on page 100. Sample script creation for LoadRunner 99 Figure 53. New virtual user Note It is not possible to record into an existing script for Web Vusers; this can only be done for Baan, Java, or RTE Vusers scripts. 4. Type "C:\Program Files\Plus!\Microsoft Internet\Iexplore.exe" (The file name is to be written in quotes) to use the Internet Explorer, and click OK in the Start Recording window. This will now become the default Web browser when you start recording a Web script through VuGen. The Internet Explorer window will pop up; now, you can start recording your transactions. Figure 54. Program to record 5. Enter the desired URL in the location field of the Web browser. We typed http://www.ibm.com, and, after the loading of that site, we searched for products. Notice that all the actions being performed in Web browsing are being recorded in VuGen in the background. Once you are finished with the transactions to be simulated, close the Internet Explorer. 100 Introducing Tivoli Application Performance Management 6. As soon as you start recording the transactions, a toolbar window pops up. Now that we are finished with our recording, stop the recording by clicking the stop button on the far right of this toolbar as shown in Figure 55. stop recording start recording Figure 55. Toolbar 7. On the main VuGen window, you can now see all your recorded actions in the Action section. Virtual user starts and stops of the Internet Explorer application are recorded in the vuser_init and vuser_end sections as shown in Figure 56. Figure 56. Recorded Web script 6.3 Passing parameters to script In the scripts created so far, you may notice that the Web sites we accessed are hard coded into the script meaning that, whenever the script is executed, Sample script creation for LoadRunner 101 it will only access the defined sites. In order to avoid this, you can pass the Web site names as parameters to the script. In this section, we will show the process of replacing the recorded values with a parameter. TAPM provides the convenience of accepting such parameters while distributing the script in the form of a profile to an endpoint. When registering the script, TAPM determines the defined custom parameters. We parameterized the start Web page, which gets loaded when we execute the script to demonstrate the process. The following are the steps we took: 1. Mark the desired value you want to replace and click the right mouse button. A pull-down menu appears; select Replace with a new Parameter. This is shown in Figure 57. Figure 57. Parameterize script 2. The New Parameter window will appear. From the pull-down menu, select Custom. Click on Properties as shown in Figure 58 on page 103. 102 Introducing Tivoli Application Performance Management Figure 58. New parameter 3. In the upcoming Parameter List window, define the Default Value, which is usually the original value of the parameterized argument. 4. Specify a prompt string in the Prompt box. TAPM will use this string to describe the parameter when you set simulation settings. This will make it easier for you to identify later on. 5. Select the Is it Mandatory? check box to indicate that the parameter should never be left empty, and click on OK. The result of the previous three steps can be seen in Figure 59 on page 104. Sample script creation for LoadRunner 103 Figure 59. Parameter list 6. Select File->Save, and save the script. We saved our LoadRunner script as LR_iexplorer. When you save the script, VuGen actually creates a directory with the specified name containing several files. A sample of the file structure is shown in Figure 60 on page 105. Note Do not name the script init, run, or end because these are reserved file names. In the directory created after saving the script, VuGen creates files named init, run, and end, and, for that reason, you cannot use these names for a VuGen script. 104 Introducing Tivoli Application Performance Management Figure 60. File structure VuGen script The different filename suffixes in the directory structure are as follows: • *.usr for recorded VuGen scripts • *.c for different script sections (C-Code) • *.cfg for run-time settings • *.ams for ARM transaction informations • *.prm for parameters • *.log for ams-file creation log 6.4 Script execution and verification Now that we have the script ready, we need to test it to verify its correctness. Before running the script, we need to modify the run-time settings for its execution and execute it. 6.4.1 Run-time settings The run-time settings options available are different for different types of virtual scripts. Since we have created a Web script, we have more options than other types of Vusers. We modified the default run time settings by performing the following steps: 1. Select Vuser->Run-Time-Settings from the VuGen menu bar. The Run-Time-Settings window is shown in Figure 61 on page 106. Sample script creation for LoadRunner 105 Figure 61. Run-time settings 2. Do not modify the Proxy settings. 3. In Network settings, enable the Search for images and load them check box. Now, when executing the script, VuGen loads graphics associated with the Web page. 4. In HTTP settings, we used the default values. 5. In Timing settings, click on Enable automatic think time check box and change the timings according to your requirements. Our settings can be seen in Figure 62 on page 107. While recording the script, VuGen does not record the time it took for us to think of and type the transactions. As a result, when the script is executed, it is completed very quickly. If you need to have a script that completely simulates an end user, you need to insert the thinking time between each transaction being performed. Receive timeout specifies the maximum amount of time a Web Vuser waits between several transfers of data after a connection has been made. We modified this settings to 60 meaning the request will be skipped after 60 seconds even if the transfer is still in progress, thus, indicating that either the server is down or the network is overloaded. Another way to simulate think time is to insert an lr_think_time function, but we did not use this. 106 Introducing Tivoli Application Performance Management Figure 62. Timing settings 6. In Performance settings, disable the Enable automatic transactions check box as shown in Figure 63. When automatic transactions is enabled, the Web Vuser regards every GET and POST command as a transaction. As a result, in spite of our having not specified the transactions for response measurement, it will take all such GET and POST commands as transactions and return the response time when the script is executed. We did not want this feature because we wanted to define our own transactions through the ARM instrumentation process by inserting the lr_functions in the script. The process for inserting the lr_functions in a script will be described later in this chapter. This will enable us to have transactions and subtransactions similar to the WinRunner script we created earlier, which would not have been possible otherwise. If we enable the automatic transactions, VuGen will execute lr_start_transaction and lr_end_transaction with the URL as the transaction name at run time, although it will not insert the lr_functions explicitly in the script. Sample script creation for LoadRunner 107 Figure 63. Automatic transactions 7. In the Iterations settings screen, we specified four iterations of the Vuser script, and each iteration will start as soon as possible as shown in Figure 64. The iteration number should be increased only when the initial testing of the script is finished and the script is ready for use with TAPM. Figure 64. Iterations 8. In Log settings, click on Extended log and select the first two options in Extended log options as shown in Figure 65 on page 109.The log messages will be very helpful for diagnosis during the Vuser script development process. The settings we made will show us warnings and Vusers messages. To get more information about VuGen log events, refer to the VuGen Users Guide. Once a script works without errors, you can turn off the log messages since unnecessary resources are used by additional logging. 108 Introducing Tivoli Application Performance Management Figure 65. Logging 9. In the Think Time settings screen, we used the default values since VuGen does not record the think time for Web Vusers. This is shown in Figure 66. Figure 66. Think time 10.In the General settings screen, we enabled the subtransactions as shown in Figure 67 on page 110. This is done to prepare the script for subtransactions that we will insert later. Sample script creation for LoadRunner 109 Figure 67. General settings 11.Click OK to save the Run-Time settings. 6.4.2 Vuser script execution Now, we are ready to check the functionality of the script we created by executing it from VuGen in a stand-alone mode. Because it is executed by an Interpreter, you will see any errors occurring during the execution. There are four different ways to run the script: • Running it in VuGen • Running it from a command prompt • Running it from a UNIX command line • Integrating it into a profile We executed our script from the VuGen environment by performing the following steps: 1. Select View->Animated Run from the menu bar to observe the Vuser in animated mode. VuGen will highlight the code line being processed during the execution of the script. 2. Select View->Output from the menu bar to view the execution log. You will see the output of the processed transactions in the bottom window. 3. If the run toolbar is not displayed, select View->Run Toolbar from the menu bar to display it. 4. Click the start button from the VuGen toolbar as shown in Figure 68 on page 111, or select Vusers->Run to run the Vuser script. You can stop the 110 Introducing Tivoli Application Performance Management execution process by clicking the stop button on the toolbar. You can also run the script in step-by-step mode through the menu bar options. To trace a Vuser script, use the step-by-step execution. start button Figure 68. Run toolbar stop button 5. In the Execution Log window, you can read all the trace messages, such as the parameter substitution or the completion of a transaction. The processed transaction is highlighted in blue in the Action section; so, you can follow which transaction is now being processed. A screen similar to Figure 69 should be seen when running the Vuser script in your environment. Figure 69. Run and debug VuGen script 6. Verify that the script executed properly, or else, make modifications and test the script again. Sample script creation for LoadRunner 111 6.5 Preparing a script for TAPM In order to use the LoadRunner virtual user script in the TAPM environment, we need to add to the script function calls that work in conjunction with Tivoli Application Response Measurement (ARM) agents. After the development and testing process described in the previous sections, we started to instrument the script with special lr_functions. The lr_functions are the ARM API calls for a LoadRunner script. We need to identify the transactions in the virtual user script for each business process whose response time you want to measure. In order to provide a comparative view between WinRunner and LoadRunner, we identified the same transactions as used in WinRunner script for response time measurement. The transactions identified are: • Execution of the entire script • Loading of the home page • Loading of IBM Web site • Search time on IBM Web site Once a script is ARMed, that is, ready for use with TAPM, it can be integrated into a TAPM profile for distribution to the end user devices. This process will be covered in later chapters. Note In WinRunner, you can add the lr_start_transaction and lr_stop_transaction functions by using the clock icons on the toolbar; see Figure 55 on page 101. VuGen provides no function generator, and you need to manually insert the lr functions into a script. While preparing your script for TAPM, you will need to know the lr_functions and their parameters. The syntax of the lr_functions is similar in WinRunner & LoadRunner. You can use the online help for a quick reference to all the functions in the following way: 1. Select Help->Function Reference from the menu bar. 2. Click General Vuser Functions. 3. Click Alphabetical Listing to get a list of all defined functions. 4. Choose the desired function to get an explanation and its syntax. 112 Introducing Tivoli Application Performance Management You can easily insert the lr_functions manually in the script, and we did so by performing the following steps: 1. Insert the lr_set_application_name statement to define the ARM application name. Insert it before any start transaction function is called. The application name is the name used to register the application to TAPM. We called our application LR_iexplorer_app. 2. Insert the lr_set_user_name statement after lr_set_application_name. We set this parameter to *. 3. Insert lr_start_transaction and lr_end_transaction statements to define the business processes, or transactions, whose response time you want to measure. Place the lr_start_transaction statement immediately before the action you want to measure. Place the lr_end_transaction statement after the last statement of the transaction. Insert lr_start_sub_transaction statements within a parent transaction to define subtransactions whose response time you want to measure. We decided to measure a subtransaction that is the loading of the IBM site; so, we used the lr_start_sub_transaction function with the parameters subtransaction name and child transaction name. lr_start_sub_transaction("ibm_web_trans","main_trans"); Like a transaction, the sub transaction is also stopped by an lr_end_transaction call; so, we inserted it after the correct loading of the IBM Web site. 4. We inserted the same lr_functions used in WinRunner into our script (except the lr_set_subtransaction and the lr_end_application since VuGen does not need them). 5. Verify the execution of the script by performing the steps described in Section 6.4, “Script execution and verification” on page 105. Specifically, look for error messages in the Execution log section that are created by the lr_functions. Once the script executes without any error, it is ready to be used in the TAPM environment. 6. Save the script with the desired name. The LoadRunner script that we created and distributed to the endpoint is shown in Figure 70 on page 114. Sample script creation for LoadRunner 113 Figure 70. Web VuGen script Note When you develop VuGen scripts and insert lr_functions, these ARM calls run against the ARM null library. The result is that you can run this script for testing. When you want to measure the response times on the same machine on which you are developing, you have to rename the libarm32.dll in the Program Files\Mercury Interactive\Virtual user generation\bin. 6.6 Summary In this chapter, we have made use of LoadRunner in order to create a sample virtual user simulation script. After recording the script, we instrumented it using ARM API calls. We have seen that LoadRunner has two components: VuGen and Robotic Client, VUGen being the development tool, and Robotic Client being the run-time component. 114 Introducing Tivoli Application Performance Management Chapter 7. Sample script creation using QuickTest for R/3 This chapter describes how to create simulated SAP R/3 applications for use with TAPM using the WinRunner QuickTest for R/3 toolkit supplied with TAPM. Using the QuickTest for R/3 toolkit, we created a sample virtual user script simulating an end user performing real SAP R/3 transactions and business processes. When used in conjunction with TAPM, these scripts will enable us to monitor the performance of our SAP R/3 transactions. QuickTest for R/3 launches the SAP R/3 front end. All user processes are recorded and can be played back. We created a simple script and instrumented it for use by TAPM. No error handling routines were added to this script for their unattended execution in the production environment. The script creation process using WinRunner QuickTest for R/3 has been explained in detail in its user’s guide and should be used for creating scripts according to your organizational requirements. The QuickTest for R/3 script creation process is broken up into the following four basic steps, which are described later in this chapter: • Install QuickTest for R/3 • Record a Business Process • Script execution and verification • Prepare scripts for TAPM We created our sample virtual user script on a stand-alone NT workstation with access to an SAP R/3 environment. This machine was not a Tivoli managed resource. 7.1 Installing WinRunner QuickTest for R/3 The QiuckTest for R/3 tool is used to record and simulate end-user transactions in an SAP/R3 environment; therefore, this product should be installed wherever the scripts are created. To run the scripts on an endpoint, the Robotic Client, which is a part of LoadRunner, should be installed there. We installed QuickTest for R/3 on the ausres24 and ausres25 machines where we created our development environment to create the scripts. The Robotic Client was installed on the Tivoli endpoint (the end user machine dresden) where we wanted to measure application performance through TAPM. © Copyright IBM Corp. 1999 115 7.1.1 System requirements QuickTest for R/3 Version 5.5 requires any of the following platforms: • Windows 95, Windows 98, or Windows NT 4.0 • R/3 Server Version 3.x or 4.0 • R/3 Client 4.0a or higher The following hardware is necessary to run QuickTest for R/3: • Pentium 100 CPU or better • Minimum 32 MB of memory • Minimum 20 MB of hard disk space 7.1.2 QuickTest installation The QuickTest for R/3 toolkit is located on the TAPM product CD-ROM in the VirtualUsers\SAPQuickTest folder. We installed it on the two systems, ausres24 and ausres25, using the default parameters as follows: 1. Start the Windows explorer and change to the following path: \VirtualUsers\SAPQuickTest\0057 2. Double click on the setup.exe file to execute it. 3. Click Next on the Welcome screen. 4. After reading the Software License Agreement, select Yes to continue with the installation or No if you disagree, and the installation will abort. 5. Select a target folder from the Choose Destination Location screen, and then click Next. 6. After the QuickTest for R/3 files have been copied to your computer, you are prompted to install LoadRunner support. Click No, and continue. 7. Click Finish to end the installation. 8. After installing QuickTest for R/3, we needed to add the Step Generator for TAPM. To do this, we installed instutil.exe from the ToolkitsFinalSetup directory on the TAPM CD-ROM. From the above directory, run instutil.exe. After the files have been extracted to your computer, press Enter. This will end the installation process. 7.1.3 Robotic Client installation The Robotic Client toolkit is located on the TAPM product CD-ROM in the VirtualUsers\RoboticClient folder. Because we wanted to play back the scripts on the dresden system, we only installed the Robotic Client on this system. 116 Introducing Tivoli Application Performance Management For information about installing the product, refer to Section 6.1.3, “Robotic Client installation” on page 97. 7.2 Recording a business process We recorded business transactions that enabled us to get processing done on the SAP R/3 server. Since we worked with a live SAP R/3 environment, we were cautious not to perform transactions that would adversely affect the production environment. Before you start recording, ensure that you have the SAP front end installed on your computer. This is also required on the computer where the script will be executed. Try to connect to the SAP/R3 server to ensure that the SAP front end is configured correctly. The first step in the recording process is to identify the business processes to be automated and what user actions to record. We recorded the script for the following three business processes: • Logon process • SAP business process • Logoff process Note The names given to these processes are defined by the user and can be anything. Perform the following steps to create the script: 1. To start QuickTest for SAP/R3, select Start -> Programs -> WinRunner-QuickTest for R/3 ->WinRunner-QuickTest for R/3 from your Windows desktop. 2. Select Insert -> Record from the QuickTest menu bar to start recording. 3. On the R3 Logon screen, select SAP@POK as the logon server. Ensure that the Auto Logon box is unchecked as shown in Figure 71 on page 118. Do not enter the user and password information. Click Logon to continue. Sample script creation using QuickTest for R/3 117 Figure 71. R/3 logon screen 4. This launches the SAP front-end application. Enter the logon information in the SAP R/3 window and press Enter. 5. Once you are successfully logged on, stop the recording process by selecting Insert -> Stop Recording. By default, the recorded process is called New Business Process. Change this to make your script more readable by right-clicking New Business Process and choosing Rename. Change the process name to Logon. 6. A close inspection of the above logon process will reveal that the actual user ID and password have been recorded. To hide this information, expand the SAP /R3 tree, right click the user field, and choose Properties. In the Input section in the Properties window, click the Parameter radio button, and then click OK. 7. Repeat the above procedure for the password field. The logon process script can be seen in Figure 72 on page 119. 118 Introducing Tivoli Application Performance Management Figure 72. Logon process 8. Now, start recording the body of the script. Collapse the Logon process tree by clicking the - sign. 9. Right click the Logon process, and select New -> Business Process. Rename the new process SAP Business Process. 10.Select Insert -> Record from the QuickTest menu bar to continue recording the script. 11.On the command line, type /nsm37 and press Enter as shown in Figure 73. This request gave us the status of jobs that were running in the background. Figure 73. Issuing a command in SAP 12.In the Select Background Jobs window, enter * in the Job Name and User name fields. A start and stop time is also required. Enter a random start and stop time. The result is displayed after you press Enter. 13.The next command to issue is /nsm51. This will provide you with a list of active servers. 14.After performing the above two transactions within an SAP environment, stop the recording by selecting Insert -> Stop Recording from the QuickTest menu bar. 15.The logoff process was recorded as a new business process. Right click the Logon process and click New -> Business Process. Rename the new process Logoff. 16.Highlight the Logoff process and start recording the logoff cycle. Select Insert -> Record from the QuickTest menu bar. In the SAP R/3 command Sample script creation using QuickTest for R/3 119 line, type /nend to log off. Once you have logged off the SAP server, the QuickTest recording will stop automatically. 17.Click File -> Save to save the script. 7.3 Verify script execution After the script has been created, it should be executed in the development environment to ensure that it runs properly. From the QuickTest menu bar, select Execution ->Run. The script can be run in the following ways: • Run from start to finish as explained above • Run to cursor • Run from cursor • Step Into (only executes certain commands) • Step Over (ignores certain commands) All of these options are available under the Execution menu on the QuickTest menu bar. To use the Step Into and Step Over options, specific entries within the script must be highlighted. To highlight a certain line, right click on an entry and select Insert/Remove Breakpoint as shown in Figure 74 on page 121. A red dot will appear on the left of the entry indicating that a breakpoint has been added. To remove the breakpoint, repeat the process. Figure 74 also shows a few entries that have breakpoints added to them. 120 Introducing Tivoli Application Performance Management Figure 74. Inserting/removing a break point After the script has executed, the Execution Log window appears, which shows whether a command was successfully executed. The Execution Log also shows the start and stop times of the transactions and the duration of the transaction as shown in Figure 75 on page 122. Sample script creation using QuickTest for R/3 121 Figure 75. Execution Log 7.4 Preparing a script for TAPM In order to use the QuickTest for R/3 virtual user script (created earlier in this chapter) in the TAPM environment, we need to add function calls that work in conjunction with TAPM agents to the script. To ARM a virtual user script, add the lr functions for TAPM after recording the script. We will explain the process of inserting these special lr functions into our script. We need to identify the transactions in the virtual user script for each business process whose response time we want to measure. We decided to measure response times for the following transactions: • Logon • Process sm37 (Checks current jobs) • Process sm51 (Lists active SAP servers) • Logoff Once a script is ARMed, that is, once it is ready for use with TAPM, it can be integrated into a TAPM profile for distribution to end-user devices. The process of using the script with TAPM will be explained in later chapters of this book. You can easily insert the lr functions into the script, and we did so by performing the following steps: 122 Introducing Tivoli Application Performance Management 1. Right click the Logon entry in the script to add the lr function for application name. Select New -> Step as shown in Figure 76. Figure 76. Inserting lr functions 2. In the Step Generator window, expand the TAPM tree. By clicking on the Advanced button, you can see the parameters of all lr functions available from TAPM. You can also insert these lr functions into the script manually, although we preferred to do it through menu options as described here. 3. Select TAPM Set Application Name. In the scripts panel, add the application name SAP_Application and click OK. This can be seen in Figure 77 on page 124. Note that the lr_set_application_name function statement needs to be done at the initiation of the script. Sample script creation using QuickTest for R/3 123 Figure 77. Inserting the application name 4. To insert the user name function, repeat the aforementioned steps. Select TAPM Set User Name from the Steps window. In the script panel, insert the user name *. Click OK. 5. Insert the lr function to enable the sub transactions in the script. We did not use subtransactions in our script. Note The lr_user_name function must be placed below the first transaction definition. We did not add any subtransaction functions, but, if they were added, they should appear before the first transaction definition as in the following example. Example lr_set_sub_transaction(1); lr_set_application_name("SAP_Application"); lr_set_user_name("*"); 6. Insert lr function statements for starting and ending business processes or transactions whose response times you want to measure. Place the lr_start_transaction statement immediately before the action you want to measure. Place the lr_end_transaction statement after the last statement of the transaction. Ensure that you give the same transaction name for both lr start and end functions. 124 Introducing Tivoli Application Performance Management We inserted these functions through the menu-driven process for our transactions. Several start and stop transactions can be added depending on how many transactions you want to measure for response time. Note When an lr start or stop function is created, a clock icon appears on the script instead of the lr function itself. 7. Insert lr functions to start a subtransaction; set transaction metrics; update transaction, and set transaction status in accordance with your requirements. For simplicity, we did not use these functions. 8. Save the script with the desired name. The saving process creates a complete directory structure for the script. The SAP_Trans script created by us is shown in Figure 79 on page 127. The script is now ready for distribution and monitoring on end-user devices through TAPM. 7.4.1 Script execution with implemented ARM calls Once the script is instrumented with ARM API calls for use by TAPM, it can be executed from the test environment to verify its correctness. You can run it by following the steps described in Section 7.3, “Verify script execution” on page 120. If you have enabled subtransactions within the script, you will need to enable them from the Run Time settings as follows: 1. Select Testcase -> View Manager from the QuickTest menu. 2. Select Properties and then Run-Time Settings on the View Manager window. 3. Check the Enable option in the Sub-Transaction section of the General panel in the Run-Time Settings window. Click OK as shown in Figure 78 on page 126. Sample script creation using QuickTest for R/3 125 Figure 78. Enable the sub-transaction option 126 Introducing Tivoli Application Performance Management Figure 79. Sample QuickTest script Sample script creation using QuickTest for R/3 127 7.5 Summary In this chapter, we have described how to create simulated SAP R/3 applications for use with TAPM using the WinRunner QuickTest for R/3 toolkit. Using the QuickTest for R/3 toolkit, we created a sample virtual user script simulating an end user performing real SAP R/3 transactions. QuickTest for R/3 is used to launch the SAP R/3 front end and to record all user processes. 128 Introducing Tivoli Application Performance Management Part 2. TAPM configuration and monitoring applications © Copyright IBM Corp. 1999 129 130 Introducing Tivoli Application Performance Management Chapter 8. Registration, profile creation, and distribution This chapter describes the registration of applications, process to create and distribute MAR profiles, and the process of uploading to the database. We also explain the different wmar* commands and their functions. 8.1 Registering applications and virtual user scripts Before you can distribute any profile containing a virtual user script (WinRunner, LoadRunner, or QuickTest scripts) or an ARM-instrumented application, you must register it at the TAPM repository. The application names will be stored in the Tivoli ODB. After a virtual user script is registered, a directory structure is created on the machine where the application registration command wmarreg was run. This is shown in Figure 80. TMR REGISTRATION COMPRESSION wmarreg command Tivoli ODB specific file system virtual user scripts Figure 80. TAPM repository 8.1.1 Registration of virtual user scripts Prior to registering the scripts, you must copy the scripts to the TMR server. Since we were working with an early TAPM code, and the registration of the scripts did not work on the TMR server, we copied the scripts to our Gateway. The scripts must be copied to the same drive on which Tivoli was installed. You can now continue with the registration of the scripts. The wmarreg command is used to register virtual user scripts. This command should be run from the TMR server, but, as explained previously, the code we used required the command to be run from the Gateway. The command adds the application information to the TAPM application registry and also does the © Copyright IBM Corp. 1999 131 packaging of the virtual user script into a tar file for downloading to the endpoint. The command has the following syntax: wmarreg -r -a application_name -b base_path -v script_name where: • application_name value is used by the TAPM software to register the application simulated by the script with the specified name; that is, when the script runs, it will make an arm_init call passing the application_name value to the TAPM engine. This is the same name passed in the lr_set_application_name call within your script. If the application already exists in the repository, and the -r flag has not been specified, the command returns an error. • base_path is the path where the script resides. • script_name is the name of the script. The script_name can be a relative path to avoid name clashes. • Use -r to replace an entry that already exists. Note Although the syntax is the same, there are slight differences in the registration procedures for the WinRunner, LoadRunner, and QuickTest scripts. For example, when registering a WinRunner application, the file name must not be specified in the -v option. Only give the last directory name where the script resides. The -b and -v flags are combined to form the absolute path to the virtual user script. The value of the -v argument is used to create the name of the script in the TAPM application registry. If -v is specified without a -b, the script name is the name of the .usr file (or, in the case of WinRunner, the name of the last directory in the -v argument). If -b is specified, the script name is the entire -v argument. The point behind these two parameters is to allow you to register two different scripts that have the same .usr name (or, in the case of WinRunner, the same directory name). Figure 81 shows the directory in which our scripts were installed. Figure 81. Directory structure 132 Introducing Tivoli Application Performance Management In the above directory structure, our LoadRunner script is in the Nets_BKUP subdirectory, and the WinRunner script is in the iexpl subdirectory. We registered our scripts using the following command: wmarreg.sh -a netscape_app -b "d:\Mercury Interactive" -v "scripts\Nets_BKUP" for WinRunner scripts and wmarreg.sh -a LR_iexplorer_app -b "d:\Mercury Interactive" -v "scripts\iexpl\iexpl.usr" for LoadRunner scripts. Once a script is registered, *.tar files are created in the following directories: Tivoli\bin\lcf_bundle\Mar\w32-ix86\vus\wr for WinRunner scripts and Tivoli\bin\lcf_bundle\Mar\w32-ix86\vus\lr for LoadRunner and QuickTest scripts. 8.1.2 Registration of an ARM-instrumented application The registration of an ARM-instrumented application differs slightly from the registration of a simulation script. The instrumented application is a normal application that is installed on the endpoint. The syntax for registering an ARM-instrumented application is: sh wmarreg.sh -a application_name where application_name is the name of the application that is defined in the arm_init call within the application. An example of registering an instrumented application is as follows: sh wmarreg.sh -a armtest1 8.2 Profile creation A TAPM profile is just like any other Tivoli profile. Profiles are stored centrally and distributed to endpoints and managed nodes. The TAPM profile contains information and is configuration-specific to the TAPM application. The Tivoli desktop refers to the TAPM profile as a MAR profile. Registration, profile creation, and distribution 133 8.2.1 Modifying the managed resources Before a TAPM profile can be created, the MarProfile managed resource needs to be added to the required policy region. We decided to use the main policy region in our TMR. Right click the Stuttgart-Region policy region and select Managed Resources. In the Managed Resources window, select MAR Profile from the available resources panel, and click the left arrow shown in Figure 82. . Figure 82. Updating the managed resources 8.2.2 Creating a profile manager Double click on your chosen policy region. From the Policy Region window, click Create ->Profile Manager as shown in Figure 83 on page 134. Figure 83. Creating a profile manager 134 Introducing Tivoli Application Performance Management The Create Profile Manager window appears; we entered TAPM_Profiles as the name of the Profile Manager and checked the Dataless Endpoint Mode box. Click Create & Close. This can be seen in Figure 84. Note The reason for creating a Dataless Profile Manager is to be able to subscribe endpoints, in addition to the managed nodes, to the profile manager. Figure 84. Profile Manager configuration 8.2.3 Creating a TAPM profile Double click on the Profile Manager TAPM_Profiles; in the resulting window, select Create -> Profile. We selected a MARProfile and typed LR for the name of the Profile. This can be seen in Figure 85. Click Create & Close. Registration, profile creation, and distribution 135 Figure 85. Creating a MARProfile Note To make our troubleshooting easier, we created separate profiles for each type of script. This is not necessary in your environment. 8.3 Simulated transaction settings We will now discuss how to add a simulated transaction entry within a MAR profile. The process for all simulated transactions will be the same. We chose to describe the process using a LoadRunner script. 1. Open the MAR profile that you just created by double clicking on the icon. Click the Add Entry button at the bottom of the window. The Add Entry to the Profile window will appear; it is similar to the one shown in Figure 86 on page 137. 136 Introducing Tivoli Application Performance Management Figure 86. Adding a simulation entry 2. In the Application part of the window, we selected LR_iexplorer_app as shown in Figure 86. This is the application we registered in Section 8.1.2, “Registration of an ARM-instrumented application” on page 133. 3. The Transaction Filter box is used to monitor specific transactions. The name of the transaction should be entered here. We used * to indicate that all transactions will be monitored. 4. Bucket limits are used to group the length of each transaction. Predefined values exist, but these can be changed by typing in the values that you require. We did not change the default settings. 5. Click the Schedule button, and Figure 87 on page 138 appears. This is used to specify the start date and stop date for data collection on the endpoint. A rule can be created to define the days and times of day on which these collections will occur. Registration, profile creation, and distribution 137 Figure 87. Scheduling information 6. To create a new rule, click the New Rule button. In the Rule Name box, we entered Daily as the name of the rule. We then selected all seven days of the week and clicked the All Day check box. This rule will run seven days a week, twenty four hours a day, for the duration specified by the start and stop dates at the top of the window. 7. The time selected for the collection interval will define how often data is copied from memory to the log files on the endpoint. We chose our collection interval to be every 10 minutes. Click Add & Close when you have finished. 8. This returned us to the Edit Entry in the Profile window; we then selected Simulation Settings. The Add VUS Parameter Values window appears as shown in Figure 88 on page 139. 138 Introducing Tivoli Application Performance Management Figure 88. Simulation settings 9. These settings define how often the simulation script will be run on the endpoint. We chose to have the script run every 10 minutes. The start date and stop date defined in the Schedule option will be used to determine when the script will run. After the time interval has been entered, click Add & Close. Note In the Settings panel at the bottom of Figure 88, the Comment for TAPM initial web page box appears with a certain URL. This is only available for a LoadRunner script after a parameter is defined within the script. This is discussed in Section 6.3, “Passing parameters to script” on page 101. 10.We clicked the Database Setting button in the Edit Entry on the Profile window. We chose Yes to save information to the database and selected Minimum for the level of detail as shown in Figure 89 on page 140. Click Add & Close. The level of detail defines the amount of information that will be written to the database. Figure 90 on page 140 describes what each level will consist of. Selecting the medium option will allow you to use Bucket Limits, and the maximum option will allow you to collect metric data. Registration, profile creation, and distribution 139 Figure 89. Database settings Record Format on the Endpoint Average response time Maximum response time Minimum response time # transactions GOOD collection interval minimum medium # transactions FAILED # transactions ABORTED # # # # # # # in bucket 1 in bucket 2 in bucket 3 in bucket 4 in bucket 5 in bucket 6 in bucket 7 maximum ARM V2 "application metric" 1 ARM V2 "application metric" 2 ARM V2 "application metric" 3 ARM V2 "application metric" 4 ARM V2 "application metric" 5 ARM V2 "application metric" 6 ARM V2 "application metric" 7 Figure 90. Table showing the level of detail 11.We selected Change & Close in the Edit Entry in the Profile box. The entry will then be added to the profile as shown in Figure 91 on page 141. 140 Introducing Tivoli Application Performance Management Figure 91. TAPM simulation profile Disabling an entry To disable an entry within a TAPM profile, click on the desired entry in the Application Availability Profile window, and then click Disable. This should only be done if you want to distribute an inactive entry to an endpoint. 8.4 ARMed application settings ARMed instrumented profiles are configured similarly to the simulated profiles discussed in Section 8.3, “Simulated transaction settings” on page 136. The main difference is that the application cannot be scheduled as in a simulation script. Data will only be collected when a user runs a particular application on the endpoint. To add an entry to a profile, click the Add Entry button at the bottom of the window of MAR profile. The Add Entry to the Profile window will appear. We selected armtest1, the application we registered in Section 8.1.2, “Registration of an ARM-instrumented application” on page 133. This can be seen in Figure 92 on page 142. Registration, profile creation, and distribution 141 Figure 92. Adding an instrumented application entry The rest of the process completes as described in Section 8.3, “Simulated transaction settings” on page 136. 8.5 Profile distribution The TAPM profile contains information about the following measurement settings as shown in Figure 93 on page 143: • Which applications? • Which transactions? • When should data be measured? • Where should data be stored? • Simulation parameters for virtual user scripts. When a profile is distributed to an endpoint, a copy of the profile is sent to that endpoint. To distribute a profile, double click the profile manager that houses the TAPM profile. In our case, we double clicked the TAPM_Profiles profile manager. We distributed the LR profile to the endpoint dresden, single clicked the profile, and then dragged and dropped it to the required endpoint (in our case, dresden). This can be seen in Figure 94 on page 143. 142 Introducing Tivoli Application Performance Management Figure 93. TAPM profile Figure 94. Distributing a profile Registration, profile creation, and distribution 143 Upon distributing a profile When a TAPM profile is distributed to an endpoint, the following will occur: 1. The *.tar file that was created when the script was registered in Section 8.1.1, “Registration of virtual user scripts” on page 131 is expanded, and the following directories and files are created (we installed the endpoint code on C:\Program Files\Tivoli): • C:\Program Files\Tivoli\dat\1\mar\jre\ • C:\Program Files\Tivoli\dat\1\mar\vus\ • C:\Program Files\Tivoli\dat\1\mar\w32-ix86\ • C:\Program Files\Tivoli\dat\1\mar\mar_trace.log • C:\Program Files\Tivoli\dat\1\mar\mar_trace_engine.log • C:\Program Files\Tivoli\dat\1\mar\mardataYYYYMMDD.log • C:\Program Files\Tivoli\dat\1\mar.log 2. The TAPM engine starts 3. The TAPM collection starts Distributing a disabled profile If a disabled profile is distributed to the endpoint, the collection will stop, but the engine will still be running. To disable a profile entry, see “Disabling an entry” on page 141. 8.6 Verifying the distribution The distribution of the profiles can be verified by issuing the following command: wmargetdata -a LR_netscape_app dresden This will retrieve the current performance data for this application. An example is shown in Figure 95. 144 Introducing Tivoli Application Performance Management Method successfully executed Reported applications: 1 -- APPLICATION: LR_iexplorer_app USER: * Transaction: ibm_web_trans () Record 0 Timestamp: Thu Sep 02 15:47:20 1999 Average response time: 3515 Minimum response time: 3515 Maximum response time: 3515 Completed transactions: 1 Aborted transactions: 0 Failed transactions: 0 Transaction: search_prod_trans () Record 0 Timestamp: Thu Sep 02 15:47:20 1999 Average response time: 5298 Minimum response time: 5298 Maximum response time: 5298 Completed transactions: 1 Aborted transactions: 0 Failed transactions: 0 Transaction: main_trans () Record 0 Timestamp: Thu Sep 02 15:47:20 1999 Average response time: 9073 Minimum response time: 9073 Maximum response time: 9073 Completed transactions: 1 Aborted transactions: 0 Failed transactions: 0 Figure 95. wmargetdata display Note If you do not end your application or virtual user script with an arm_stop or lr_end_transaction call, the wmargetdata command will not display any data. 8.6.1 Using wmar commands To check the applications or scripts that have been registered, use the wmargetappreg.exe command. The output of the wmargetappreg command is shown in Figure 96. Application Type : 'LR_iexplorer_app' : 'MAR_VUS' Figure 96. wmargetappreg display Registration, profile creation, and distribution 145 Note The LR_iexplorer_app is the LoadRunner Script If the TAPM engine on the endpoint is not working properly and the wrong collections are running, try to clear the engine with the wmarcleareng hostname command. This will delete all collections on the specified endpoint but will not stop the engine. To restart the collection, use the wmarstartcoll command or distribute the profiles to the endpoint again. If this procedure does not work, you must stop and restart the engine by performing the following steps: 1. Stop the collections on the endpoint with the wmarstopcoll command. 2. Stop the TAPM engine with the wmarstopeng command. 3. Distribute the profiles again (this will start the engine and the collections), or start the engine with the wmarstarteng command, and start the collections with the wmarstartcoll command. For more information about wmar commands, refer to Appendix B, “wmar commands” on page 195. 8.7 Log files TAPM creates several log files on different machines that can be analyzed for troubleshooting purposes. • The mar.log file is created on endpoint and TAPM gateways. Endpoint log: The mar.log file contains information about CLI commands and the time they were executed as well as information about the data aggregation and uploading process on an endpoint. Gateway log: Information about the data upload from the gateway to database. • The mar_trace.log file is created on endpoint and TAPM gateways. This log file contains trace informations about the CLI commands and profile distribution commands executed on the TMR server or TAPM gateway where the log file resides and the intended endpoint which the command was sent to. For example if you execute the wmarlseng dresden command on frankfurt, detailed trace informations about Tivoli function calls and their return code will be written to the log files on dresden and frankfurt. 146 Introducing Tivoli Application Performance Management • mar_trace_engine.log This log file is only created on an endpoint and contains information about the engine processes on the endpoint, such as arm function calls, and their data, such as metric data, application name, application ID, or correlator requests. The following log files contain no trace data. They are the data log files: • marinfoYYYYMMDD.log This log file contains the strings, such as application name and transaction name, for the collected data and is a binary file. • mardataYYYYMMDD.log This log file contains numbers, such as response time and the number of transactions, for the collected data and is a binary file. • mar_aggregated.log This log file contains the aggregated data of the marinfo and mardata log files and is a binary file. Table 6 shows the location of the logfiles. Table 6. Log file location Log file name mar.log mar_trace.log mar_trace_engine.log mardataYYYYMMDD.log marinfoYYYYMMDD.log mar_aggregated.log Endpoint directory Tivoli\lcf\dat\1 Tivoli\lcf\dat\1\Mar Tivoli\lcf\dat\1\Mar Tivoli\lcf\dat\1\Mar Tivoli\lcf\dat\1\Mar Tivoli\lcf\dat\1\Mar TAPM Gateway directory Tivoli\db\$hostname.db\tmp\Mar Tivoli\db\$hostname.db\tmp\Mar N/A N/A N/A N/A 8.8 Performance data collection After you have created and distributed the TAPM profiles, start the TAPM engine and the collection of each application. We will now explain how TAPM stores collected data and how you can retrieve it. We will also describe the process of forwarding the data to the database. Registration, profile creation, and distribution 147 8.8.1 Data collection process The TAPM agent collects the performance data created by the ARM-instrumented applications or Virtual User Scripts. This collection data is stored in memory, and, after a specified time (the collection interval), TAPM writes the performance data to two binary log files on the endpoint. They are created in the Tivoli\lcf\dat\1\Mar directory. These two log files are: • marinfoYYYYMMDD.log This log file contains information about the application name, transaction name, or user ID of the data that is collected and written in the second file. It is like an index for the actual data file. • mardataYYYYMMDD.log This log file contains numbers, such as response time and the number of transactions, for the collected data. The reason for splitting the collected data into two files is performance. The collection process is shown in Figure 97 on page 148. Tivoli Management Agent ARM Application / arm_start 11 10 9 8 7 12 1 2 3 4 5 6 TAPM Agent ResponseTime Additional Data arm_update Vuser Script arm_stop 12 11 10 9 8 7 6 5 4 1 2 3 Collection Record Collection Interval 11 12 1 10 2 3 9 8 4 7 6 5 marinfo.log mardata.log Figure 97. Data log collection on an endpoint 148 Introducing Tivoli Application Performance Management 8.8.2 The aggregation and uploading process Once a day, marinfoYYYYMMDD.log and mardataYYYYMMDD.log are aggregated and initialized by the TAPM agent on the endpoint. Only the data of those collections that should save their collected data to the database is merged to the binary file mar_aggregated.log. The aggregation interval is one hour for all transactions in this file. This means that transaction collections are gathered into one hour batches within the log file. It is saved in the Tivoli\lcf\dat\1\Mar directory on the endpoint. In our environment, this aggregation process was executed every night at approximately 00:30. We could not determine whether it is possible to change this setting. The mar_aggregated.log binary file is then uploaded to the TAPM gateway. After the gateway has collected all data from the endpoints, it will transfer the data to the database using the RIM interface. The RIM object communicates with the Database server. This can be seen in Figure 98 on page 150. Registration, profile creation, and distribution 149 Database Server TAPM TAPM RIM Upload to Database Gateway TAPM Gateway Upcall Collector Upcall Endpoint TAPM Agent marinfo.log mardata.log Aggregator Process mar_aggregated.log Figure 98. The aggregation and uploading process 8.8.3 Using the trace log files to confirm aggregation and upload When troubleshooting a corrupt process, it is good to investigate the log files’ mar_trace.log on the endpoint and the gateway. The successful aggregation and upload process should look like the following log files: 150 Introducing Tivoli Application Performance Management 1. Endpoint mar_trace.log: *------------------------------------------------------------* Aug 27 00:31:22 performAggregation(): Starting aggregator Data file: mardata19990826.log Info file: marinfo19990826.log *------------------------------------------------------------* Aug 27 00:31:22 performAggregation(): Closing aggregator. Function completed successfully. *------------------------------------------------------------* Aug 27 00:31:33 t_imp_MarBackend_Endpoint_uploaddata(): start *------------------------------------------------------------* Aug 27 00:31:33 t_imp_MarBackend_Endpoint_uploaddata: completed 2. TAPM gateway mar_trace.log: *------------------------------------------------------------* Aug 28 00:34:43 downcall_driver(): running Number of EndPoints: 1 *------------------------------------------------------------* Aug 28 00:34:43 downcall_driver(): running EndPoint Label: dresden.5, 1288818247.5.508+#TMF_Endpoint::Endpoint# *------------------------------------------------------------* Aug 28 00:34:43 open_connection(): running Opening IOM channel with key: 151239573I1790I423a50423a50 frankfurt *------------------------------------------------------------* Aug 28 00:34:44 downcall_driver(): running Aggregated file received: DATA length = 36830 bytes *------------------------------------------------------------* Aug 28 00:34:44 data_decode(): Closing method Current position: 76, length: 36830 *------------------------------------------------------------* A successful upload to the database, including the lookup for the RIM interface, should look like the sample mar_trace.log file of our gateway frankfurt. The start and end section of the entries concerning the upload process can be seen in Figure 99 on page 152. Registration, profile creation, and distribution 151 *------------------------------------------------------------* Aug 28 00:34:44 get_info(): RIM info TapmRIM_OID: 1288818247.2.28#RIM::RDBMS_Interface# conn_id: 9999 RIM Host: frankfurt RDBMS User: tapm@stuttgart RDBMS Vendor: Oracle -> Oracle Database ID: ORCL Database Home: c:/orant Server ID: stuttgart Instance Home: (null) *------------------------------------------------------------* Aug 28 00:34:45 TapmDB_Fill(): running ---- Begin TRANSACTION for INSERT --HostName = dresden.itsc.austin.ibm.com HostID from DB = 1 *------------------------------------------------------------* Aug 28 00:34:45 TapmDB_Fill(): running appNum =5 *------------------------------------------------------------* Aug 28 00:34:45 TapmDB_Fill(): running ApplName = LR_iexplorer_app ApplID from DB = 1 *------------------------------------------------------------* Aug 28 00:34:45 TapmDB_Fill(): running usrNum =1 *------------------------------------------------------------* Aug 28 00:34:45 TapmDB_Fill(): running UserName = Administrator UserID from DB= 1 -----------------------------------------------------------* ... ... ... *------------------------------------------------------------* Aug 28 00:34:50 TapmDB_Fill(): running ---- End TRANSACTION for INSERT --*------------------------------------------------------------* Aug 28 00:34:50 TapmDB_Fill(): running DB Transaction unit COMMITTED. *------------------------------------------------------------* Aug 28 12:34:50 downcall_driver(): running Aggregated data successfully loaded on Database. *------------------------------------------------------------* Figure 99. TAPM gateway mar_trace.log 152 Introducing Tivoli Application Performance Management 8.8.4 Forcing the upload process manually There is a way to force the aggregation process to execute. You can manually start the execution of the upload process, but be aware of the fact that you manipulate the database when you do this. This should only be done in a test environment to check whether the upload process works. The following steps must be performed: 1. Look for an existing mar_aggregated.log on the endpoint. If no log exists, you cannot force the process to be executed. 2. Open a cmd shell, and run the Tivoli lcf environment configuration command, lcf_env.cmd, which is located in c:\WINNT\Tivoli\lcf\1. 3. Go to the lcf bin directory, c:\Program Files\Tivoli\lcf\dat\1\Mar, and run mar_up endpoint_name. For example: mar_up dresden The command itself will provide no feedback as to whether it executed successfully; therefore, you have to check the log files on the endpoint. As you can see in the mar_trace.log on the endpoint, the upload process is forced to execute during daytime: *------------------------------------------------------------* Sep 02 15:06:48 t_imp_MarBackend_Endpoint_uploaddata(): start *------------------------------------------------------------* Sep 02 15:06:48 t_imp_MarBackend_Endpoint_uploaddata: completed This means that the upload process to the TAPM gateway has completed successfully. Next, to confirm the upload to the database, check the mar_trace.log on the TAPM gateway for messages explained in Section 8.8.3, “Using the trace log files to confirm aggregation and upload” on page 150. After the Gateway has collected all data from the endpoints, it will transfer the data to the database using the RIM interface. The RIM object communicates with the Database server. For the TAPM engine activities, you can increase the trace level in the marproperties.ser file to get a more detailed log file. There are three different TraceLevels: • MAR_TRACE_NONE • MAR_TRACE_MIN Registration, profile creation, and distribution 153 • MAR_TRACE_MAX You also can specify which components should be traced. This is done by setting the TraceComponent. Table 7 gives you an overview of the available settings. Table 7. Trace components Value What is traced MAR_COMPONENT_WILDCARD MAR_COMPONENT_NONE MAR_COMPONENT_API_ID MAR_COMPONENT_COMMAND_ID MAR_COMPONENT_COLLECTION_ID MAR_COMPONENT_SIMUL_ID All activities Exceptional conditions All ARM APIs calls All CLI commands and profile pushes Collections activity Simulations activity A maximum detailed log file should only be used if you are facing problems on the endpoint because these logfiles use a large amount of disk space. Do not forget to return to a less detailed log file after the problem has been detected and solved. We changed the trace level for our endpoint dresden by performing the following steps: 1. Stop the TAPM engine with the wmarstopeng command: wmarstopeng dresden 2. Go to the TAPM lcf directory (on our machine, it is at c:\Program Files\Tivoli\lcf\dat\1\Mar), and edit the marproperties.ser file. 3. Modify the TraceComponent and the TraceLevel. TraceComponent=MAR_COMPONENT_WILDCARD TraceLevel=MAR_TRACE_MAX 4. Start the TAPM engine using the wmarstarteng command. wmarstart dresden 154 Introducing Tivoli Application Performance Management Note When you edit the marproperties.ser file, it is only visible when the TAPM engine is not running; therefore, you have to stop the engine. You can use the wmarlsappl command to retrieve information about the application name, the transactions, and the user ID that executes it. You can use wildcards in the application name. For example, wmarlsappl -a LR_* dresden will produce the following output: The following applications match the specified criteria: Application name: LR_iexplorer_app UserId: Administrator Transaction name(s): search_prod_trans ibm_web_trans main_trans When you issue the wmarlseng command, TAPM will list all active collections running on the specified endpoint. All the profile-defined values for this collection will be listed. Executing wmarlseng dresden will produce the following output: ------------------------------------------Collection active on application: LR_iexplorer_app transaction filter : * bucket limits (msec) : 100 500 1000 2000 5000 10000 collection interval : 600 sec collection active on : Daily=EveryDay start date : Sep 01 1999 stop date : Sep 02 1999 data-base storage : active, detail level: Minimum The application is a simulation: name : lr\iexpl\iexpl.usr execution interval : 600 parameter(s) : {Comment for TAPM initial web page}Param1=http://itsorus.austin.ibm.com/ ------------------------------------------- Registration, profile creation, and distribution 155 8.9 Summary In this chapter, we have covered how to register our applications in order to store the names of the applications in the Tivoli ODB. This step is necessary for Tivoli to recognize the applications. The next step after registering the applications is to create the TAPM profiles to distribute to subscribers. We have seen that one TAPM profile is just like another and is handled in the same way as other Tivoli objects. 156 Introducing Tivoli Application Performance Management Chapter 9. Reporting performance data Tivoli Decision Support provides a powerful mechanism for viewing and exploring complex database structures at different levels of detail and from different perspectives. It also allows its users to relate data in multiple dimensions. The TDS Discovery Guide for Application Performance Management allows you to view the application performance of the past. The Tivoli Discovery Interface presents information in a graphical format utilizing several multidimensional cubes built with data from the TAPM database. Use the Tivoli Discovery Administrator tool to customize these multidimensional cubes. 9.1 Installing the TDS guide Decision Support comes with a bundle of Service Desk Guides that are available when installing the product; others are delivered with the Tivoli product itself. The installation process we describe in this chapter will have changed due to the fact that the guide was not available on the TAPM product CD we used. This will be changed with the official release of TAPM. We had to copy it from the network drive where it was provided. To start the TDS Guide installation, we started the setup.exe in the TDS Guide\tds\Tivoli Decision Support for Application Performance Measurement\NT-Image. The installation process completed successfully, but we had to copy the *.ppr files into the c:\ProgramFiles\tds\cubes and the *.mdb files into the c:\ProgramFiles\tds\data directory to work with TDS. 9.2 Set up TDS for TAPM To use TDS for TAPM, we have to set up the ODBC driver. Make sure that the proper ODBC drivers and the database client are installed on the machine. Since we are using Oracle, we installed the Microsoft Oracle ODBC drivers from the TDS CD. Perform the following steps to set up the drivers: 1. Choose the 32-bit ODBC icon from the Windows Control Panel. 2. Select the System DSN and choose Add. 3. From the Create new Data Source dialog box, choose Microsoft ODBC Driver for Oracle, and click on Finish. In the ODBC setup window, we typed the values shown in Figure 100. © Copyright IBM Corp. 1999 157 Figure 100. ODBC setup Try an SQL-Plus connection to the database server to ensure that all settings are correct. After the ODBC setup, we can start working with TDS. To start the Discovery Administrator, perform the following steps: 1. Select Start->Programs->Tivoli Decision Support->Tivoli Discovery Administrator. If you start the Discovery Administrator for the first time, the Welcome box appears; otherwise, perform the remaining steps to import the Discovery Guide. 2. Enter OK . The Import Discovery Guide box will appear. 3. Enter No. The Add Data Source box will appear. 4. Enter No. Our intention is to show how to add the Discovery Guide and Data Source through Tivoli Discovery Administrator. Perform the following steps to import the Discovery Guide: 1. From the menu bar, select Decision Support Guides->Import . 2. In the upcoming window, click on Application Performance Management , and then click OK as shown in Figure 101 on page 159. 158 Introducing Tivoli Application Performance Management Figure 101. Selecting application performance management The result is that the Application Performance Manager Guide is imported, and the available cubes should be visible as shown in Figure 102. Figure 102. Imported TAPM Guide Perform the following steps to add the Data Source: 1. From the menu bar, select Data Sources->Add. Reporting performance data 159 The first Add Data Source Wizard box will appear as shown in Figure 103. Note If you turn off the Toggle Wizard, the Wizard windows will not appear. 2. Select tapm from the pull-down menu, and click Next . 3. The second box will show up. Type tapm and tapmtapm as shown in Figure 103, and click Next . Figure 103. Add data source 2 4. In the third box, you must give the qualifier used by TDS to fully qualify the tables in the database. Choose Next . 160 Introducing Tivoli Application Performance Management Figure 104. Add data source 3 5. In the next box, click Finish to save your data source. 6. Test the connection by selecting Data Source->Test Connectivity from the menu bar. A box will appear displaying the status of the test. If the test fails, repeat the steps, and make sure you use the correct qualifier, user, and password. 7. After adding the data source, select Data Sources->Assign Data Source from the menu bar. As a result, the Assign Data Source box will appear and ask to assign the new Data Source to each query used for the Application Performance cubes. Click on Select All ; choose tapm as your Data Source, and click OK . This is shown in Figure 105 on page 162. Reporting performance data 161 Figure 105. Assign data source As a result, the selected data source is assigned to the selected queries, and the Tivoli Discovery Administrator window appears again. 9.3 TDS cubes There are seven cubes provided by TDS, which you can use to display the collected data: • Application Performance (1) MIN RT - This cube is used to gather Response Time data from Tivoli Application Performance Management set on minimum configuration. Parameters: • Date range - Set this date range to, at most, the last 30 days because the Visual Basic function called in the query will use the data structures for, at most, 30 days. • Metric label - This gives a terminology mapping table. Usually, you do not need to change it. • Response time threshold - This table contains the names of the ARM-instrumented application’s transactions whose performance you want to measure. In this table, for a given transaction name, you can set a threshold of response time after which the value becomes critical. • Application Performance (2) MIN Tx Status - This cube is used to gather Completion Status data from Tivoli Application Performance Management set on minimum configuration. Parameters: 162 Introducing Tivoli Application Performance Management • Date range • Metric Label • Application Performance (3) MIN RT Service Level - This cube is used as a model for service-level target views for Response Time data gathered from Tivoli Application Performance Management set on minimum configuration. Parameters: • Date range • Metric Label • Application Performance (4) MIN Forecast - This cube gets Response Time and Completion Status data from Tivoli Application Performance Management set on minimum configuration in order to produce views regarding trends and forecasts. Parameters: • Date range • Metric Label • Forecast day - This table contain two entries: Back and Forward. They are the number of days to be represented in the views of type forecast computed with respect to the last day of data available at cube-building time. • Application Performance (5) MIN Tx Forecast - This cube is used as a model for Completion Status data gathered from Tivoli Application Performance Management set on minimum configuration in order to produce views regarding trends and forecasts. • Application Performance (6) MED Buckets - This cube gets Buckets measurements from Tivoli Application Performance Management set on medium configuration in order to produce views regarding Response Time distribution. Parameters: • Date range • Metric Label • Application Performance (7) MAX - This cube gets the ARM v2 additional data (defined by the user) from Tivoli Application Performance Management set on maximum configuration in order to produce the relative views. Parameters: Reporting performance data 163 • Date range • Metric Label 9.4 Building the cube Now that we have finished the prerequisites for using TDS, we will build the cubes; therefore, we use the Tivoli Administrator interface in the following way: 1. In the Administrator window of the Tivoli Discovery Administrator, click on the Cubes folder, and double click on the cube you want to build; the cube properties will appear. Double click on Parameters. 2. Set the Date Range parameters to the appropriate value by double clicking on Date Range. The Date Range window will appear as shown in Figure 106. Figure 106. Date range 3. Set the date to the date range from which you want to retrieve the data, but do not use a time period longer than 30 days. Click on OK. 4. Right mouse click on the cube you want to build, and, from the pop-up menu, select Build. 5. If you want to build the cube with the specified parameters, in the Confirm Build Cube window, press Yes. The Cube Transformation Status window will appear as shown in Figure 107. 164 Introducing Tivoli Application Performance Management Figure 107. Cube transformation status 6. Finish the cube build by clicking on the Close button. Repeat these steps for every cube, and exit the Tivoli Discovery Administrator. 9.5 Using the guide In this section, we will show how to use the TAPM Discovery Guide. 9.5.1 Topics and views These are the topics with their related views and short explanations: • Are my applications meeting the service-level target? This topic provides the following service-level reports: • Threshold on response time - This graph shows you whether an application transaction meets the service-level target. By default, you will see the current day; drilling down, you will see the threshold for Reporting performance data 165 each transaction type. The response time and service-level threshold units of measure are milliseconds. • How is my application performing? The following graphs display typical views of response time: • Response time by application - This view shows how response time changes during the day for individual applications. Application response time is the average of the response times for all transactions defined within that application. The response time unit of measure is the millisecond. • Response time by hostname - These are response times for individual IP hosts. The complete name is used in the format hostname.domain. Each host may be a single user machine or a multiuser server. The response time unit of measure is the millisecond. • Response time by subnet - This is the response time, during the day, for individual IP subnets. The response time unit of measure is the millisecond. • Response time by transaction - This is the response time, during the day, for individual transactions. A transaction is a unit of work defined within an application. The response time unit of measure is the millisecond. • Response time by user - This is the response time experienced by individual users for all applications they are using. The user's name is their logon to the operating system. In a Windows environment, the user ID Administrator might represent many users if they each log on to their machines as Administrator. The response time unit of measure is the millisecond. • Response time distribution - This is the percentage of transactions for which the response time is in the range of each bucket. The ranges of the buckets are set, by default, to: 0-1 seconds, 1-3 seconds, 3-5 seconds, and so on. Their actual values are shown in milliseconds (ms) in the legend. • How is my ARM additional data? The following graph displays typical views of counter values collected from the Additional Data fields on the arm_start, arm_update, and arm_stop calls: • ARM V2 additional data - The use of these additional data fields on the call is optional; so, they might not be used by the transaction. If they have not been used, no data will be displayed. The nature of this 166 Introducing Tivoli Application Performance Management display depends on the implementation of the additional data metrics in the transaction being monitored. • What are my application performance forecasts? The following graphs present projected performance data: • Response time forecast - This view lets you look at a history of hourly, low, and high forecast values for the average, minimum, and maximum Response Time metric. The response time unit of measure is the millisecond. • Response time trend - This view shows you the growth trend for response time over the last four weeks. It looks at the average value on a day-by-day basis (that is, it compares Mondays of each week). The response time unit of measure is the millisecond. • Transactions forecast - This view lets you look at a history of hourly, low, and high forecast values for the number of transactions that succeeded, failed, and aborted. • What is my application availability? The following graphs show the completion status of transactions. Transactions can complete in three ways: Good, failed, and aborted. The real meaning of each of these depends on how the application has been programmed: • Transaction completion status - This graph shows the completion status for transactions. Transactions should, ideally, complete with a Succeeded status. Look for failed or aborted transactions; this can indicate that transactions did not work as the user would expect or may not have worked at all. • What is my application throughput? The following graphs provide views of the amount of work being done by the application: • Execution load by application - The number of times the application was executed in the time interval. This shows which applications are being used the most. If an application has an unusually low value, it may have been unavailable during the interval. • Execution load by transaction - The number of times a transaction was executed in the time interval. This shows which transactions are being used the most. If a transaction has an unusually low value, it may have been unavailable during the interval. • Execution load by user - The number of times the user executed an application or transaction in the time interval. This shows who is using Reporting performance data 167 the applications and how much. Such information can be used to charge for application usage. The user's name is their logon to the operating system. In a Windows environment, the user ID Administrator might represent many users if they log on to their machines as Administrator. 9.5.2 View the data with the TDS Discovery Interface To view the collected data, start the Tivoli Discovery Interface by performing the following steps: 1. Select Start->Programs->Tivoli Decision Support->Tivoli Discovery Interface. 2. Click on Guides, and select Application Performance from the list of installed guides as shown in Figure 108. Figure 108. Tivoli Discovery Interface 168 Introducing Tivoli Application Performance Management 3. Turn to the Topic Map, and double click on the Application Performance Management icon. If you open all topics, you will see views similar to those shown in Figure 109. Figure 109. Topics and views 9.5.3 Sample views We will go through some of the views in this section. 9.5.3.1 Response time by transaction Perform the following steps to get a response time by transaction report: 1. Double click on the Response time by transaction view, and the graph for this view will appear in the display pane. The graph in Figure 110 on page 170 will show you the average response times in milliseconds for all the transactions. Reporting performance data 169 Figure 110. Average response time for all transactions-line view 2. Select View->Change Display->Clustered Bar (depth) , and switch to the Clustered Bar view for better visibility. The result is shown in Figure 111 on page 171. 170 Introducing Tivoli Application Performance Management . Figure 111. Average response time for all transactions-clustered bar view 3. Double click on the main_trans for the date 08/30/1999. The result is shown in Figure 112 on page 172 where average response times for transaction main_trans are seen by the time of day on 08/30/1999. Note This operation is called drill-down in TDS terms and is used to access more detailed data, such as YEAR->MONTH->DAY. The drill-down paths depend on the models of the cubes. Drill-up is the opposite of drill-down: You access a more aggregated view from a detailed view. Reporting performance data 171 Figure 112. Average response time for main_trans on 08/30/1999. 4. Select View->Change Display->Pie, and switch to the Pie Chart view to get a better picture of the hourly average response times. The result is shown in Figure 113 on page 173. 172 Introducing Tivoli Application Performance Management . Figure 113. Pie chart graph of average response time 9.5.3.2 Response time by hostname Perform the following steps to get a response time by hostname report: 1. Double click on the Response time by hostname view, and the graph for this view will appear in the display pane. The graph shows you the average response times in milliseconds for all transactions from the host dresden. Reporting performance data 173 Figure 114. Average response times for the host dreden 2. Drag and drop the All Transactions dimension onto the Legend area to get the average response times for each transaction. The result is shown in Figure 115 on page 175. Note This operation is called slice and dice in TDS terms. It is done by applying different dimensions to the data. It is one of the most robust techniques for analyzing data. 174 Introducing Tivoli Application Performance Management Figure 115. Average response times for each transaction for the host dreden 9.5.3.3 Execution load by user Perform the following steps to get the execution load by user report: 1. Double click on the view Execution load by user, and the graph for this view will appear in the display pane. The graph in Figure 116 on page 176 shows you the number of times the user executed an application or transaction in the time interval. This will give an indication of who is using the applications and how much they are using them. Reporting performance data 175 Figure 116. Execution load by all users 2. We only want to see the transactions performed by Nicola; so, we double click on the name nicola in the legend. Figure 117 on page 177 shows the result of this operation. Note This operation is called filtering in TDS terms and is used to analyze a subset of the data that is shown on the graph. 176 Introducing Tivoli Application Performance Management Figure 117. Execution load by user nicola 3. Drag and drop the All Transactions dimension on the Legend (or directly on the graph) for details of each transaction Nicola has submitted. The graph in Figure 118 shows you this data. Figure 118. Execution load by user nicola for each transaction Reporting performance data 177 9.6 Summary We have seen that using TDS with the TAPM Guide gives us a powerful option to analyze the data created by TAPM. We included sample reports and some TDS techniques to analyze the data in this chapter. It is recommended that the reader refer to the TDS documentation, such as the redbook Using Tivoli Decision Support Guides, SG24-5506, for more information about Tivoli Decision Support products and data-analysis techniques. 178 Introducing Tivoli Application Performance Management Chapter 10. Alerting on response time problems TAPM is shipped with a Distributed Monitoring component. The monitor reports on average, minimum, and maximum transaction response times as well as failed or aborted transactions and metric data. 10.1 Installing TAPM monitors To install the monitoring component, refer to Chapter 3.5, “TAPM installation” on page 38. 10.2 Creating a distributed monitoring profile To create a Distributed Monitoring Profile, a Profile Manager must first be created. The process to be followed is as follows: 1. From the Policy Region window, select Create -> Profile Manager as shown in Figure 119 on page 179. Figure 119. Creating a profile manager 2. The Create Profile Manager window appears; we entered DM_Profile as the name of the Profile and clicked the Dataless Endpoint Mode check box. 3. This can be seen in Figure 120 on page 180. Click Create & Close. © Copyright IBM Corp. 1999 179 Figure 120. DM_Profile 4. Double click on the newly-created profile manager, DM_profile. 5. From the Profile Manager window, click Create -> Profile. The Create Profile window appears; select Sentry Profile, and enter the profile name as DM_TAPM as shown in Figure 121. Figure 121. Distributed monitoring profile 180 Introducing Tivoli Application Performance Management 10.3 Setting subscribers to the profile The next step after creating the profile DM_TAPM is to subscribe endpoint(s) to it. Select the dresden.5 endpoint in order to subscribe to the profile as follows: Figure 122. Subscribing endpoint dresden.5 to the DM_TAPM profile. After selecting Set Subscriptions & Close you may see that the dresden.5 endpoint is subscribed to the DM_TAPM profile as shown in Figure 123 on page 182. Alerting on response time problems 181 Figure 123. DM_TAPM profile with dresden.5 endpoint as its subscriber 10.4 Editing the profile Now, you need to edit the profile to add a monitor. Double click the DM_TAPM profile icon and select Add Monitors. You can see the available monitors for the TAPM monitoring collection in Figure 124 on page 183. 182 Introducing Tivoli Application Performance Management Figure 124. Selecting the average transaction response time monitor You may use Average Transaction Response Time monitor as an example to monitor the response time of the main_transaction of LR_iexporer application. Set the required values for the application name, application user ID, and transaction name fields, and select Add Empty. If the average response time for the main_transaction of LR_iexporer application exceeds 15 seconds, the monitor should notify us by way of a pop-up and send a Fatal event to TEC at the same time. Set the required values on the Edit Monitor screen according to this requirement as shown in Figure 125 on page 184. Alerting on response time problems 183 Figure 125. Edit monitor view Next, select Set Monitoring Schedule and set the monitoring schedule to check the monitor every minute as shown in Figure 126 on page 185. 184 Introducing Tivoli Application Performance Management Figure 126. Monitoring schedule screen Select Change & Close to close the window. Then, select Profile->Save on the next screen to save the profile. 10.5 Distributing the profile Now, you may distribute the DM_TAPM profile by dragging and dropping the profile onto the dresden.5 endpoint icon. If the average response time for the main_transaction of LR_iexporer application exceeds 15 seconds, you should receive the pop-up message shown in Figure 127 from your desktop as well as a FATAL TEC event from the TEC console. Figure 127. Pop-up window from the monitor Alerting on response time problems 185 We can verify that the actual response time is more than 15 seconds by running the wmargetdata command as follows: D:\Tivoli\bin\w32-ix86\bin>wmargetdata -a LR_iexplorer_app -t main_trans -u Admi nistrator dresden.5 Method successfully executed Reported applications: 1 -- APPLICATION: LR_iexplorer_app USER: Administrator Transaction: main_trans () Record 0 Timestamp: Fri Sep 10 12:05:15 1999 Average response time: 26769 Minimum response time: Maximum response time: Completed transactions: Aborted transactions: Failed transactions: 26769 26769 1 0 0 10.6 Summary Apart from getting reports through TDS, which was covered in the previous chapter, TAPM can also be used to monitor for average, minimum, and maximum transaction response times as well as failed or aborted transactions and metric data. TAPM is shipped with a monitoring collection that is integrated with Tivoli Distributed Monitoring. It is also possible to send TAPM events to Tivoli Enterprise Console through Tivoli Distributed Monitoring. 186 Introducing Tivoli Application Performance Management Appendix A. Developer’s Kit for application instrumentation The ARM Software Developer’s kit (SDK) contains everything you need to prepare your application for transaction monitoring. The process followed by us to obtain the SDK and its installation is covered in detail in this appendix. In this appendix, we also describe the different ARM API calls and their syntax and parameters for easy reference. A.1 SDK installation To begin instrumenting your application, you need to create the development environment. In our case, since we planned to instrument a C application, we installed a C compiler (Microsoft Developer Studio 97, but any other standard C compiler can be used) and the ARM SDK files. The SDK installation process installs the appropriate NULL shared library, the header file, the shared library source code, the logging agent source, documentation files and sample program files to your system. The installation consists of the following steps: 1. Tivoli provides the SDK on their Website. You can get the ARM 2.0 SDK from www.tivoli.com/products/index/module_designer/body_arm_index.html (If the URL has changed, search for SDK at www.tivoli.com/products/. Download the self-expanding zip format file armsdk.exe for the Windows NT platform to your local disk. 2. Open a DOS window; switch to the directory containing the file armsdk.exe, and type the armsdk.exe -d command. This will expand the file into the current directory and create several subdirectories for the extracted files. 3. Read the 'readme.pc' and 'license.pc' files, and copy the LIBARM*.DLL to the standard location for the platform as shown below. Do not copy the library if the library already exists in the destination directory since you may be overwriting an ARM agent-specific library with a NULL library. Windows95/Windows NT: copy \ARM_SDK\LIB\WIN95_NT\LIBARM32.DLL %windir%\SYSTEM32\ A.2 The ARM API call syntax The ARM API is made up of a set of function calls that are contained in a shared library. Here, we provide a brief description of the six different function calls supported in ARM Version 2.0 and a detailed description of their © Copyright IBM Corp. 1999 187 parameters and returns. For a detailed description of these function calls, refer to the SDK documentation. A.2.1 arm_init Use arm_init to define the application or a unique instance of the application and user. Syntax: appl_id=arm_init(appl_name,appl_user_id,flags,data,data_size) Parameters: appl_name (char*) appl_user_id (char*) This is the name used to identify the application. This is the name of the application user. On UNIX and Windows NT, you can set this value to “*” to indicate the login user ID of the person running the application. This is reserved for future use. It must be set to zero. This is reserved for future use. A NULL value (0) must be used. This is reserved for future use. It must be set to zero. flags (int32)=0 data (char*)=0 data_size (int32)=0 Return code: appl_id (int32) A unique value to reference an application/user identifier. This ID must be passed to the arm_getid call. Example: client_appl_id=arm_init("Client_Application", "*", 0,0,0); Error handling: If the value returned in appl_id is less than zero, an error occurred in communicating with the measurement agent. The value returned on an error can be passed to arm_getid, which will cause arm_getid to function as a NULL operation. The error should be logged; so, corrective action can be taken. 188 Introducing Tivoli Application Performance Management A.2.2 arm_getid The arm_getid function call is used to assign a unique identifier to a transaction class and, optionally, to describe the format of additional data passed on arm_start, arm_update, and arm_stop calls. Syntax: tran_id=arm_getid(appl_id,tran_name,tran_detail,flags,data,data_size) Parameters: appl_id (int32) This is the unique reference to an application/user identifier returned from the arm_init call. If the appl_id is less than zero, this arm_getid call will be treated as a NULL operation, and a negative tran_id will be returned. This is the unique name of the transaction class. It is defined for each transaction class by the application developer. It must be unique within the application (for each arm_init call). Transaction detail allows a developer to provide additional information about a transaction class. It is a free-form text area that is set once for each appl_id/tran_name pair. If the contents of the field change on later calls using the same appl_id/tran_name pair, the new contents will be ignored. This is reserved for future use. It must be set to zero. This is a pointer to a buffer that describes the format of additional data that can be passed on arm_start, arm_update, and arm_stop calls. If no additional data is passed on these calls, this parameter must be set to zero (0). The length in bytes of the buffer pointed to by data. If data is set to zero (0), data_size must also be set to zero. tran_name (char*) tran_detail (char*) flags (int32)=0 data (char*) data_size (int32) Return code: tran_id (int32) The unique identifier assigned for this transaction class. This ID needs to be passed on arm_start calls. Developer’s Kit for application instrumentation 189 Example: client_tran_id = arm_getid(client_appl_id, "Client_transaction", "First transaction in Client application", 0, 0,0); Error handling: If the value returned in tran_id is less than zero, an error occurred in communicating with the measurement agent. It can be passed to arm_start, which will cause arm_start to function as a NULL operation. A.2.3 arm_start Use arm_start to mark the beginning of the execution of a transaction. Syntax: start_handle=arm_start(tran_id,flags,data,data_size) Parameters: tran_id (int32) The unique identifier assigned to the transaction class. This is the ID generated by arm_getid. If the tran_id is less than zero, this arm_start call will be treated as a NULL operation, and a negative start_handle will be returned. Reserved for future use. It must be set to zero. A pointer to a buffer with additional data that can be passed optionally. If no additional data is passed, this parameter must be set to zero (0). The length in bytes of the buffer pointed to by the data parameter. If data is set to zero (0), data_size must also be set to zero. flags (int32)=0 data (char*) data_size(int32) Return code: start_handle (int32) The unique transaction handle assigned to this instance of a transaction. This handle must be passed on arm_stop and any arm_update calls. Example: metric_tran_handle = arm_start(metric_tran_id, 0, (char *)buf_ptr, buf_sz); Error handling: 190 Introducing Tivoli Application Performance Management If the value returned in start_handle is less than zero, an error occurred in communicating with the measurement agent. The most likely cause is passing an invalid value for tran_id. The value returned on an error can be passed to arm_update and arm_stop calls, which will cause these calls to function as NULL operations. A.2.4 arm_update Use this call for additional information about and the progress of a transaction. This is an optional call. error_status=arm_update(start_handle,flags,data,data_size) Parameters: start_handle (int32) This is the unique handle from the arm_start call that marked the start of this transaction instance. The start_handle must be passed in each arm_update call. Many transaction instances may be executing at the same time from this and other applications; so, this handle is essential to identify which transaction instance is being updated. If start_handle is less than zero, this arm_update call will be treated as a NULL operation, and a negative error_status returned. This is reserved for future use. It must be set to zero. This is a pointer to a buffer with additional data that can be passed optionally. If no additional data is passed, this parameter should be set to zero (0). •If the Format field contains the value 1, application-defined metrics as defined in arm_getid can be passed. The correlator field is not used in the arm_update call. •If the Format field contains the value 2, a status message up to 1020 bytes in length may be passed in. data_size (int32) This is the length in bytes of the buffer pointed to by data. If data is set to zero (0), data_size should also be set to zero. flags (int32)=0 data (char*) Return code: Developer’s Kit for application instrumentation 191 error_status (int32) Contains a zero if successful and a negative value if an error occurred. Example: arm_update(metric_tran_handle,0, (char *)buf_ptr,buf_sz); Error handling: If the value returned in error_status is less than zero, an error occurred in communicating with the measurement agent. The most likely cause is passing an invalid value for start_handle. A.2.5 arm_stop Use arm_stop to mark the end of a transaction instance that was started with arm_start. Syntax: error_status=arm_stop(start_handle,tran_status,flags,data,data_size) Parameters: start_handle (int32) The unique handle from the arm_start call that marked the start of this transaction instance. start_handle must be passed in each arm_stop call. Many transaction instances may be executing at the same time from this and other applications; so, this handle is essential for the measurement agent to use to identify which transaction instance is stopping. If start_handle is less than zero, this arm_stop call will be treated as a NULL operation, and a negative error_status will be returned. This is the completion code of the transaction, as determined by the application. 0 = Transaction successful (defined as ARM_GOOD in arm.h). Use this value when the operation completed normally and as expected.1 = Transaction aborted (defined as ARM_ABORT in arm.h). Use this value when there was a fundamental failure in the system. 2 = Transaction failed (defined as ARM_FAILED in arm.h). Use this value in applications where the transaction worked properly, but no result was generated. tran_status (int32) 192 Introducing Tivoli Application Performance Management flags (int32)=0 data (char*) Reserved for future use. It must be set to zero. This is a pointer to a buffer with additional data that can be passed optionally. If no additional data is passed, this parameter should be set to zero (0). The format is identical to the arm_start call, except the Correlator field is not used in the arm_stop call. The length in bytes of the buffer pointed to by the data parameter. If data is set to zero (0), data_size should also be set to zero. data_size (int32) Return code: error_status (int32) Contains a zero if successful and a negative value if an error occurred. Example: status=arm_stop(metric_tran_handle,ARM_GOOD,0,(char *)buf_ptr, buf_sz); Error handling: If the value returned in error_status is less than zero, an error occurred in communicating with the measurement agent. The most likely cause is passing an invalid value for start_handle. A.2.6 arm_end Use arm_end when you are finished initiating new activity using the ARM API. error_status=arm_end(appl_id,flags,data,data_size) Parameters: appl_id (int32) This is a unique reference to an application/user identifier returned from the arm_init call. If appl_id is less than zero, this arm_end call will be treated as a NULL operation, and a negative error_status will be returned. This is reserved for future use. It must be set to zero. This is reserved for future use. A NULL pointer (0) must be used. flags (int32)=0 data (char*)=0 Developer’s Kit for application instrumentation 193 data_size (int32)=0 This is reserved for future use. It must be set to zero. Return code: error_status This contains a zero if successful and a negative value if an error has occurred. Example: status=arm_end(metric_appl_id, 0,0,0); Error handling: If the value returned in error_status is less than zero, an error occurred in communicating with the measurement agent. The most likely cause is passing an invalid value for appl_id. 194 Introducing Tivoli Application Performance Management Appendix B. wmar commands Here is a list of the available wmar commands, their usage, and examples. •wmarcleareng.exe This command is for clearing the engine on the endpoint. The syntax is wmarcleareng host_name. • wmargetappreg.exe This command is for listing all the applications registered on the endpoint. The syntax is wmargetappreg. This command takes no parameters. Sample output: Application Type Application Type VUS Name Application Type VUS Name Application Type Application Type Application Type VUS Name : : : : : : : : : : : : : : : 'Client_Application' 'MAR_ARM' 'LR_iexplorer_app' 'MAR_VUS' 'lr\iexpl\iexpl.usr' 'LR_test_app' 'MAR_VUS' 'lr\LR_test\LR_test.usr' 'Metric_Application' 'MAR_ARM' 'Server_Application' 'MAR_ARM' 'netscape_app' 'MAR_VUS' 'wr\Nets_BKUP' where: • LR_iexplorer_app is the LoadRunner application. • netscape_app is the WinRunner application. • Metric_Application, Server_Application, and Client_Application are the ARM-instrumented applications. • wmargetdata.exe This is for checking the data collected on the endpoint. The syntax is as follows: wmargetdata -a app_name [-t tx_name] [-u user_id] [-i interval | -s [-]start_time [-e [-]end_time]] [-m monitor_name] host_name Sample Output: © Copyright IBM Corp. 1999 195 This is from a WinRunner Application: ############## Method successfully executed Reported applications: 1 -- APPLICATION: netscape_app USER: * Transaction: ibm_web_trans () Record 0 Timestamp: Thu Aug 26 15:48:28 1999 Average response time: 20 Minimum response time: 20 Maximum response time: 20 Completed transactions: 1 Aborted transactions: 0 Failed transactions: 0 Transaction: search_prod_trans () Record 0 Timestamp: Thu Aug 26 15:48:28 1999 Average response time: 40 Minimum response time: 40 Maximum response time: 40 Completed transactions: 1 Aborted transactions: 0 Failed transactions: 0 Transaction: main_trans () Record 0 Timestamp: Thu Aug 26 15:48:28 1999 Average response time: 130 Minimum response time: 130 Maximum response time: 130 Completed transactions: 1 Aborted transactions: 0 Failed transactions: 0 • wmargetstatus.exe This is for checking the status of the engine on the endpoint. The syntax is as follows: wmargetstatus host_name. Sample output of this command is: The engine is running Log file name: C:\Program Files\Tivoli\lcf\dat\1\mar.log Default Values: Global Collection Flag: Inactive Aggregation Start Time: 600 Correlator Flag: Inactive Agent Trace Flag: Inactive • wmargwinst.exe 196 Introducing Tivoli Application Performance Management This command is used internally by wmarreg.sh script for distributing the files to the Endpoint Gateway. The syntax is as follows: wmargwinst -f file_name • wmarlsappl.exe This command is to list the details of an application registered on the endpoint. The syntax is: wmarlsappl [-a app_name] [-t tx_name] [-u user_id] host_name Sample output of the command is as follows: The following applications match the specified criteria: Application name: LR_iexplorer_app UserId: Administrator Transaction name(s): search_prod_trans ibm_web_trans main_trans • wmarlseng.exe This is to list all the applications registered on an endpoint. You do not need to remember the application names as is the case with the wmarlsappl command. wmar commands 197 Collection active on application: LR_iexplorer_app transaction filter : * bucket limits (msec) : 100 500 1000 2000 5000 10000 collection interval : 300 sec collection active on : Daily=EveryDay start date : Aug 20 1999 stop date : Aug 31 1999 data-base storage : active, detail level: Maximum The application is a simulation: name : lr\iexpl\iexpl.usr execution interval : 300 parameter(s) : None -------------------------------------------------------------Collection active on application: Metric_Application transaction filter : * bucket limits (msec) : 100 500 1000 2000 5000 10000 collection interval : 300 sec collection active on : Alldaylong=EveryDay start date : Aug 24 1999 stop date : Aug 30 1999 data-base storage : active, detail level: Maximum ------------------------------------------Collection active on application: Client_Application transaction filter : * bucket limits (msec) : 100 500 1000 2000 5000 10000 collection interval : 300 sec collection active on : Alldaylong=EveryDay start date : Aug 24 1999 stop date : Aug 30 1999 data-base storage : active, detail level: Maximum ------------------------------------------Collection active on application: Server_Application transaction filter : * bucket limits (msec) : 100 500 1000 2000 5000 10000 collection interval : 300 sec collection active on : Alldaylong=EveryDay start date : Aug 24 1999 stop date : Aug 30 1999 data-base storage : active, detail level: Maximum • wmarreg.sh This script is to register applications within TAPM. The syntax is as follows: wmarreg [-r] -a app_name [-b base_path -v script_name] 198 Introducing Tivoli Application Performance Management • wmarstartcoll.exe This is to start the collection of data on the endpoint. This does not need to be executed since the collection gets started after distributing a profile. The syntax is: wmarstartcoll [-a app_name] [-t tx_filter] [-b bucket_limits] [-s start_time] [-e end_time] [-c scheduling_cycle] [-i collection_interval] [-d detail_level] [-r run_interval] [-p parms_list] host_name. • wmarstarteng.exe This is to start the TAPM engine on the endpoint. This also is not required since it gets started after the profile is distributed to the endpoint. The syntax is: wmarstarteng host_name • wmarstopcoll.exe This is to stop the collection of data. The syntax is: wmarstopcoll [-a app_name] host_name • wmarstopeng.exe This is to stop the engine on an endpoint. The syntax is: wmarstopeng host_name wmar commands 199 200 Introducing Tivoli Application Performance Management Appendix C. Source file listing This appendix contains the source file listing of our instrumented C application. This will assist you in understanding the process of inclusion of ARM API calls to your applications. C.1 Sample2.c The ARM SDK provides sample C applications, and we used one of the samples and instrumented it with ARM API calls. The application has been created and tested successfully on a Windows NT 4.0 machine. /*****************************************************************************/ /* Sample2.c */ /* */ /* This program provides examples of how to use two of the new features */ /* provided by version 2.0 of the ARM API, user defined metrics and */ /* correlation. For simplicity, this sample program does not perform any */ /* error checking. */ /*****************************************************************************/ #include #include #include "arm.h" int32 int32 int32 int32 client_appl_id = -1; client_tran_id = -1; metric_appl_id = -1; metric_tran_id = -1; /* application id */ /* transaction id */ /* application id */ /* transaction id */ /*****************************************************************************/ /* server_application */ /* */ /* This routine is included here to simplify this example. In a real life */ /* situation, this piece of code would likely be running on a separate */ /* system. */ /*****************************************************************************/ void server_application(arm_app_correlator_t client_correlator) { FILE *stream; int32 server_appl_id = -1; /* unique application id */ int32 server_tran_id = -1; /* unique transacation id */ int32 server_tran_handle = -1; /* transaction instance */ arm_user_data1_t *buf_ptr, buf = { 1, /* header */ {ARM_CorrPar_f, 0, 0, 0}, /* flags */ }; © Copyright IBM Corp. 1999 201 int32 int buf_sz; i, data_len, x; /* application name */ /* use default user */ /* reserved */ /* appl_id from arm_init */ /* transaction name */ Server program", /* data buffer */ /* buffer pointer & size */ server_appl_id=arm_init("Server_Application", "*", 0,0,0); server_tran_id = arm_getid(server_appl_id, "Server_transaction", "First Transaction in 0, 0,0); /* Pass the parent correlator received from the client application to /* the ARM agent using the arm_start call. buf_ptr = &buf; buf_ptr->flags[0] = ARM_CorrPar_f; */ */ buf_ptr->correlator.length = client_correlator.length; data_len = (client_correlator.length - sizeof(client_correlator.length)); for (i = 0; i < data_len; i++) buf_ptr->correlator.agent_data[i] = client_correlator.agent_data[i]; buf_sz = (sizeof(buf)-sizeof(client_correlator) + client_correlator.length); server_tran_handle = arm_start(server_tran_id, /* tran_id from arm_getid */ 0, /* reserved */ (char *)buf_ptr, buf_sz); /**********************************************/ /* Perform actual transaction processing here */ /**********************************************/ for(x=0;x<1000;x++){ if((stream=fopen("test_data","w+"))==NULL) printf("error opening test_data\n"); else{ fprintf(stream,"This is only to have some processing\n"); fclose(stream); } } arm_stop(server_tran_handle, ARM_GOOD, 0, 0,0); arm_end(server_appl_id, 0,0,0); return; } /* server_application() */ /* /* /* /* transaction handle from arm_start */ successful completion define = 0 */ reserved for future use */ buffer pointer & buffer size */ /* application id from arm_init */ /* reserved for future use */ /*****************************************************************************/ /* client_transaction */ 202 Introducing Tivoli Application Performance Management /*****************************************************************************/ void client_transaction() { int32 client_tran_handle = -1; transaction start handle */ /* *buf_ptr, buf = { /* Header */ arm_user_data1_t 1, }; int32 buf_sz; arm_app_correlator_t correlator = { 0, /* correlator length */ 0, /* agent data */ }; int i, data_len; buf_ptr = &buf; buf_sz = sizeof(buf); /* The client application requests a correlator from the ARM Agent */ buf_ptr->flags[0] = ARM_CorrReq_f; client_tran_handle = arm_start(client_tran_id, /* tran_id from arm_getid */ 0, /* reserved for future use */ (char *)buf_ptr, /* metrics buf ptr */ buf_sz); /* user metric buffer size */ /* If the ARM Agent returns a correlator, determine the size of the /* agent specific data in the correlator and pass the data, along with /* the correlator length, to the server application. if ((buf_ptr->flags[0] & ARM_CorrGen_f) == ARM_CorrGen_f) { correlator.length = buf_ptr->correlator.length; data_len = (correlator.length - sizeof(buf_ptr->correlator.length)); for (i = 0; i < data_len; i++) correlator.agent_data[i] = buf_ptr->correlator.agent_data[i]; } server_application(correlator); arm_stop(client_tran_handle, ARM_GOOD, 0, 0,0); return; } /* client_transaction() */ /* /* /* /* transaction handle from arm_start */ successful completion define = 0 */ reserved for future use */ buffer pointer & buffer size */ */ */ */ /*****************************************************************************/ /* init_client_application */ /*****************************************************************************/ Source file listing 203 void init_client_application() { client_appl_id=arm_init("Client_Application", /* application name */ "*", /* use default user */ 0,0,0); /* reserved for future use */ client_tran_id = arm_getid(client_appl_id, "Client_transaction", "First transaction in 0, 0,0); return; } /* init_client_application */ /* appl_id from arm_init */ /* transaction name */ Client application", /* reserved */ /* buffer pointer & size */ /*****************************************************************************/ /* metric_transaction */ /*****************************************************************************/ void metric_transaction() { int i,k; int32 metric_tran_handle = -1; transaction start handle */ /* arm_user_data1_t *buf_ptr, buf = { 1, {0, ARM_AllMetrics_f | ARM_String1_f, 0, 0}, }; int32 buf_sz; /* Header */ /* Flags */ buf_ptr = &buf; buf_sz = sizeof(buf); buf_ptr->metric[0].counter32 = 0x0; /* Overall transaction counter */ buf_ptr->metric[1].gauge32 = 0x0;/* Value of the randomized i variable */ buf_ptr->metric[2].counter64.upper = 0x01234567; buf_ptr->metric[2].counter64.lower = 0x76543210; strcpy(buf_ptr->metric[3].string8, "Initial8"); buf_ptr->metric[4].cntrdivr32.count = 0x0; /* Overall transaction counter (average) */ buf_ptr->metric[4].cntrdivr32.divisor = 0x2; /* transactions average per loop */ buf_ptr->metric[5].numericid64.upper = 0x0; Error id 1 = no loop processed */ /* buf_ptr->metric[5].numericid64.lower = 0x0; strcpy(buf_ptr->string32,"This is a 32 character string "); /* Additional string info */ metric_tran_handle = arm_start(metric_tran_id, /* tran_id from arm_getid */ 0, /* reserved */ (char *)buf_ptr, /* metrics buf ptr */ 204 Introducing Tivoli Application Performance Management buf_sz); /********************************/ /* Perform some processing here */ /********************************/ printf("This is the first metric processing.\n"); /* user metric buffer size */ srand((unsigned)time(NULL)); seed random-number generator with time */ /* i=rand(); /* Fill the metrics with information */ if(i>=50000) { memcpy(buf_ptr->string32,"First i is to high, no process!",31); buf_ptr->metric[5].numericid64.upper = 0x1; } else { memcpy(buf_ptr->string32,"First for loop was processed! ",31); buf_ptr->metric[5].numericid64.upper = 0x0; } buf_ptr->metric[1].gauge32 = i; /* transaction loop */ for(;i<50000;i++) { buf_ptr->metric[4].cntrdivr32.count++; /* increase counter */ buf_ptr->metric[0].counter32++; increase counter for average calculation */ /* printf(":-)) :-} \n"); } arm_update(metric_tran_handle, 0, (char *)buf_ptr, buf_sz); /* /* /* /* transaction handle from arm_start */ reserved for future use */ user metrics buffer pointer */ user metric buffer size */ /*************************************/ /* Perform some more processing here */ /*************************************/ printf("This is the second metric process\n"); srand((unsigned)time(NULL)); seed random-number generator with time */ /* i=rand(); /* Fill metrics */ if(i>=20000) memcpy(buf_ptr->string32,"2'nd i is to high, no process! ",31); else memcpy(buf_ptr->string32,"2'nd for loop was processed! ",31); buf_ptr->metric[1].gauge32 = i; for(;i<20000;i++) { buf_ptr->metric[4].cntrdivr32.count++; buf_ptr->metric[0].counter32++; printf("Second loop"); } arm_stop(metric_tran_handle, /* transaction handle from arm_start */ Source file listing 205 ARM_GOOD, 0, (char *)buf_ptr, buf_sz); return; } /* metric_transaction() */ /* /* /* /* successful completion define = 0 */ reserved for future use */ user metrics buffer pointer */ user metric buffer size */ /*****************************************************************************/ /* init_metric_application */ /*****************************************************************************/ void init_metric_application() { arm_user_data101_t *buf_ptr, buf = { 101, {0, ARM_AllMetrics_f | ARM_String1_f, 0, 0}, {{1, "Metric #1 - Type 1 is a COUNTER32 "}, {4, "Metric #2 - Type 4 is a GAUGE32 "}, {2, "Metric #3 - Type 2 is a COUNTER64 "}, {9, "Metric #4 - Type 9 is a STRING8 "}, {3, "Metric #5 - Type 3 is a COUNTER32/DIVISOR32"}, {8, "Metric #6 - Type 8 is a NUMERICID64 "}, {10, "The last field is always a STRING32 "} }}; int32 buf_sz; buf_ptr = &buf; buf_sz = sizeof(buf); metric_appl_id=arm_init("Metric_Application", "*", 0,0,0); metric_tran_id = arm_getid(metric_appl_id, "Metric_transaction", "First transaction in 0, (char *)buf_ptr, buf_sz); /* application name */ /* use default user */ /* reserved */ /* appl_id from arm_init */ /* transaction name */ Metric application", /* reserved */ /* buffer */ /* buffer size */ return; } /* init_metric_application */ /*****************************************************************************/ /* Main */ /*****************************************************************************/ ain() { int continue_processing = 1; 206 Introducing Tivoli Application Performance Management init_client_application(); init_metric_application(); while (continue_processing) { client_transaction(); metric_transaction(); continue_processing = 0; } arm_end(client_appl_id, 0,0,0); arm_end(metric_appl_id, 0,0,0); return(0); } /* application id from arm_init */ /* reserved for future use */ /* application id from arm_init */ /* reserved for future use */ C.2 Armtest1.exe This is the armtest1.exe source code we also used to register and run on the same machine on which the previous application ran. The source code is taken from the redbook Using Tivoli’s ARM Response Time Agents , SG24-2124, and is slightly modified. /***************************************************************/ /* This is a simple interactive demonstration program. */ /* It tests the ARM Agents for NT Workstation. */ /* The agents are part of Distributed Monitoring. */ /***************************************************************/ void showError(char* func); #define W32 #include #include #include #include "arm.h" /* Global variable */ /* Prototype for showError function */ int arm_rc; void main() /**********************************************************/ /* Define the local variables */ /**********************************************************/ { char transaction[20]; int appl_handle; int getid_handle; Source file listing 207 char int char int int startcmd[20]; start_handle; endcmd[20]; stoprc; endrc; printf("\nThis program generates transactions for the ARM Agents of\n"); printf("Distributed Monitoring, on NT workstation.\n\n"); printf("This Tests TAPM\n"); /**********************************************************/ /* make arm_init call */ /**********************************************************/ appl_handle = arm_init("armtest","*",0,0,0); arm_rc=appl_handle; showError("arm_init"); /* Call the showError function */ /**********************************************************/ /* Ask for transaction name and make arm_getid call */ /**********************************************************/ printf("Please enter the name of your transaction:\n"); scanf("%s",&transaction); getid_handle = arm_getid(appl_handle,transaction,"NTwks",0,0,0); arm_rc=getid_handle; showError("arm_getid"); /* Call the showError function */ /**********************************************************/ /* Prompt user to start the transaction */ /**********************************************************/ do { printf("Type \"start\" to start the transaction\n"); scanf("%s",&startcmd); /**********************************************************/ /* Test whether user typed start */ /**********************************************************/ } while (strcmp(startcmd,"start")); /**********************************************************/ /* Loop to repeat transactions */ /**********************************************************/ do { /**********************************************************/ /* Make arm_start call at transaction start */ 208 Introducing Tivoli Application Performance Management /**********************************************************/ start_handle = arm_start(getid_handle,0,0,0); printf("\nTransaction started...\n"); arm_rc=start_handle; showError("arm_start"); /* Call the showError function */ printf("Type a few characters and press ENTER.\n"); printf("Or type \"end\" and press ENTER, to end the program.\n\n"); scanf("%s",&endcmd); /**********************************************************/ /* Make arm_stop call at transaction end */ /**********************************************************/ stoprc = arm_stop(start_handle,ARM_GOOD,0,0,0); printf("\nTransaction stopped.\n"); arm_rc=stoprc; showError("arm_stop"); /* Call the showError function */ } while (strcmp(endcmd,"end")); /**********************************************************/ /* Make arm_end call at application end */ /**********************************************************/ endrc = arm_end(appl_handle,0,0,0); arm_rc=endrc; showError("arm_end"); } /* Call the showError function */ /*********************************************/ /* Function for reporting return codes */ /*********************************************/ void showError(char* func) { if (arm_rc > -1) { printf("The return from your %s call is: %d \t[Good!]\n\n",func,arm_rc); } else { printf("The return from your %s call is: %d",func,arm_rc); switch (arm_rc) { case -1 : printf("\n[ERROR: An invalid argument was used in the call]\n\n"); break; Source file listing 209 case -2 : printf("\n[ERROR: The ARM agent is not running]\n\n"); break; case -3 : printf("\n[ERROR: Communication with the agent cannot be established]\n\n"); break; case -4 : printf("\n[ERROR: An error was found in the agent; look in the log file]\n\n"); break; default : printf("\n[ERROR: Unknown error code]\n\n"); break; } } } /**********************************************************/ /* End of program */ /**********************************************************/ 210 Introducing Tivoli Application Performance Management Appendix D. Special notices This publication is intended to help the reader understand and use the Tivoli Application Performance Manager in their environment. The information in this publication is not intended as the specification of any programming interfaces that are provided by Tivoli Application Performance Manager or the Tivoli Management Framework. See the Publications section of the IBM Programming Announcement for Tivoli Application Performance Manager for more information about what publications are considered to be product documentation. References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only the IBM product, program, or service may be used. Any functionally-equivalent program that does not infringe any IBM intellectual property rights may be used instead of the IBM product, program, or service. Information in this book was developed in conjunction with the use of the equipment specified and is limited in application to those specific hardware and software products and levels. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact IBM Corporation, Dept. 600A, Mail Drop 1329, Somers, NY 10589 USA. Such information may be available, subject to appropriate terms and conditions including, in some cases, payment of a fee. The information contained in this document has not been submitted to any formal IBM test and is distributed AS IS. The information about non-IBM ("vendor") products in this manual has been supplied by the vendor and IBM assumes no responsibility for its accuracy or completeness. The use of this information or the implementation of any of these techniques is a customer responsibility and depends on the customer's ability to evaluate and integrate © Copyright IBM Corp. 1999 211 them into the customer's operational environment. While each item may have been reviewed by IBM for accuracy in a specific situation, there is no guarantee that the same or similar results will be obtained elsewhere. Customers attempting to adapt these techniques to their own environments do so at their own risk. Any pointers in this publication to external Web sites are provided for convenience only and do not in any manner serve as an endorsement of these Web sites. Any performance data contained in this document was determined in a controlled environment, and therefore, the results that may be obtained in other operating environments may vary significantly. Users of this document should verify the applicable data for their specific environment. This document contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples contain the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. Reference to PTF numbers that have not been released through the normal distribution process does not imply general availability. The purpose of including these reference numbers is to alert IBM customers to specific information relative to the implementation of the PTF when it becomes available to each customer according to the normal IBM PTF distribution process. The following terms are trademarks of the International Business Machines Corporation in the United States and/or other countries: AIX AT DB2 Netfinity PC 300 SP System 390 AS/400 CT IBM  OS/2 RS/6000 SP2 400 The following terms are trademarks of other companies: Tivoli, Manage. Anything. Anywhere.,The Power To Manage., Anything. Anywhere.,TME, NetView, Cross-Site, Tivoli Ready, Tivoli Certified, Planet Tivoli, and Tivoli Enterprise are trademarks or registered trademarks of Tivoli Systems Inc., an IBM company, in the United States, other countries, or both. In Denmark, Tivoli is a trademark licensed from Kjøbenhavns Sommer - Tivoli 212 Introducing Tivoli Application Performance Management A/S. C-bus is a trademark of Corollary, Inc. in the United States and/or other countries. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and/or other countries. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States and/or other countries. PC Direct is a trademark of Ziff Communications Company in the United States and/or other countries and is used by IBM Corporation under license. ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel Corporation in the United States and/or other countries. (For a complete list of Intel trademarks see www.intel.com/tradmarx.htm) UNIX is a registered trademark in the United States and/or other countries licensed exclusively through X/Open Company Limited. SET and the SET logo are trademarks owned by SET Secure Electronic Transaction LLC. Other company, product, and service names may be trademarks or service marks of others. Special notices 213 214 Introducing Tivoli Application Performance Management Appendix E. Related publications The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this redbook. E.1 IBM Redbooks publications For information on ordering these publications, see “How to get IBM Redbooks” on page 219. • Deploying a Tivoli Infrastructure in Large-Scale Environments, SG24-5210 • New Features in Tivoli Software Distribution 3.6, SG24-2045 • Managing SAP R/3 with Tivoli , SG24-5298 • Managing RDBMS Servers with Tivoli , SG24-5240 • An Introduction to Tivoli Enterprise, SG24-5494 • An Industry Around the Tivoli Framework: Examples from 10/Plus Association, SG24-2122 • Tivoli Enterprise Internals and Problem Determination, SG24-2034-01 • Using Tivoli Software Installation Service for Mass Installation, SG24-5109 • All about Tivoli Management Agents, SG24-5134 • A Project Guide for Deploying Tivoli Solutions, SG24-5310 • Designing Tivoli Solutions for End-to-End Systems and Service Management, SG24-5104 • Implementing TME 10 in High Availability Environments, SG24-2032 • Instrumenting Enterprise Applications Using Tivoli GEM, SG24-5399 • Using Tivoli’s ARM Response Time Agents, SG24-2124 • Measuring Lotus Notes Response Times with Tivoli’s ARM Agents , SG24-4787 • Using the Applications Management Specification in a TMA Environment , SG24-4809 • TEC Implementation Examples, SG24-5216 • Problem Management Using Tivoli Service Desk and TEC, SG24-5301 • A Design and Implementation Guide for Tivoli Decision Support , SG24-5499 © Copyright IBM Corp. 1999 215 E.2 IBM Redbooks collections Redbooks are also available on the following CD-ROMs. Click the CD-ROMs button at http://www.redbooks.ibm.com/ for information about all the CD-ROMs offered, updates, and formats. CD-ROM Title Collection Kit Number IBM S/390 Redbooks Collection SK2T-2177 IBM Networking and Systems Management Redbooks Collection SK2T-6022 IBM Transaction Processing and Data Management Redbooks Collection SK2T-8038 IBM Lotus Redbooks Collection SK2T-8039 Tivoli Redbooks Collection SK2T-8044 IBM AS/400 Redbooks Collection Kit SK2T-2849 IBM Netfinity Hardware and Software Redbooks Collection SK2T-8046 IBM RS/6000 Redbooks Collection Kit (BkMgr Format) SK2T-8040 IBM RS/6000 Redbooks Collection (PDF Format) SK2T-8043 IBM Application Development Redbooks Collection Kit SK2T-8037 IBM Enterprise Storage and Systems Management Solutions SK3T-3694 E.3 Other resources These publications are also relevant as further information sources. The following Tivoli publications are Product Documentation, which can only be obtained by purchasing the associated Tivoli product: • TME10 Framework 3.6 Planning & Installation Guide, SC31-8432 • Framework 3.6 User’s Guide, GC31-8433 • TME10 Framework 3.6 Reference Manual , SC31-8434 • TME10 Framework Release Notes Version 3.6, GI10-3028 • Software Installation Service 3.6 User’s Guide, GC31-5121 • Software Installation Service Release Notes, GI10-0512 • Tivoli Distributed Monitoring User’s Guide 3.6, GC31-8382 • TME10 Software Distribution 3.6 User’s Guide, GC31-8330 • Tivoli Decision Support User’s Guide, GC31-5202 • Tivoli Decision Support Administrator’s Guide, GC31-5201 • TME10 Enterprise Console User’s Guide Version 3.6 , GC31-8506 • Tivoli Global Enterprise Manager User’s Guide, GC31-5152 216 Introducing Tivoli Application Performance Management • Tivoli Manager for SAP R/3 User’s Guide, GC31-8411 The following Mercury Interactive publications are product documentation supplied with the Tivoli Application Performance Manager product: • Virtual User Generator User’s Guide • WinRunner User’s Guide • WinRunner QuickTest for R/3 User’s Guide Related publications 217 218 Introducing Tivoli Application Performance Management How to get IBM Redbooks This section explains how both customers and IBM employees can find out about ITSO redbooks, redpieces, and CD-ROMs. A form for ordering books and CD-ROMs by fax or e-mail is also provided. • Redbooks Web Site http://www.redbooks.ibm.com/ Search for, view, download, or order hardcopy/CD-ROM redbooks from the redbooks Web site. Also read redpieces and download additional materials (code samples or diskette/CD-ROM images) from this redbooks site. Redpieces are redbooks in progress; not all redbooks become redpieces and sometimes just a few chapters will be published this way. The intent is to get the information out much quicker than the formal publishing process allows. • E-mail Orders Send orders by e-mail including information from the redbooks fax order form to: In United States Outside North America • Telephone Orders United States (toll free) Canada (toll free) Outside North America 1-800-879-2755 1-800-IBM-4YOU Country coordinator phone number is in the “How to Order” section at this site: http://www.elink.ibmlink.ibm.com/pbl/pbl e-mail address usib6fpl@ibmmail.com Contact information is in the “How to Order” section at this site: http://www.elink.ibmlink.ibm.com/pbl/pbl • Fax Orders United States (toll free) Canada Outside North America 1-800-445-9269 1-403-267-4455 Fax phone number is in the “How to Order” section at this site: http://www.elink.ibmlink.ibm.com/pbl/pbl This information was current at the time of publication, but is continually subject to change. The latest information may be found at the redbooks Web site. IBM Intranet for Employees IBM employees may register for information on workshops, residencies, and redbooks by accessing the IBM Intranet Web site at http://w3.itso.ibm.com/ and clicking the ITSO Mailing List button. Look in the Materials repository for workshops, presentations, papers, and Web pages developed and written by the ITSO technical professionals; click the Additional Materials button. Employees may access MyNews at http://w3.ibm.com/ for redbook, residency, and workshop announcements. © Copyright IBM Corp. 1999 219 IBM Redbook Fax Order Form Please send me the following: Title Order Number Quantity First name Last name Company Address City Postal code Telefax number Country VAT number Telephone number Invoice to customer number Credit card number Credit card expiration date Card issued to Signature We accept American Express, Diners, Eurocard, Master Card, and Visa. Payment by credit card not available in all countries. Signature mandatory for credit card payment. 220 Introducing Tivoli Application Performance Management List of abbreviations AIX APPC Advanced Interactive Executive Advance Program to Program Communication Command Line Interface Dynamic Link Library Early Support Program Global Enterprise Manager Graphical User Interface International Business Machines Corporation Inter Program Communication International Technical Support Organization Local Area Network Lightweight Client Framework Load Runner Object Database Personal Computer Software Developer’s Kit Software Installation Service Structured Query Language Tivoli Application Performance Manager Transmission Control Protocol / Internet Protocol Tivoli Decision Support TEC TMA TME TMR TRAA TRIP TSL VuGen Vuser Tivoli Enterprise Console Tivoli Management Agent Tivoli Management Environment Tivoli Management Region Tivoli Remote Access Account Tivoli Remote Execution Service Test Script Language Virtual User Generator Virtual User CLI DLL ESP GEM GUI IBM IPC ITSO LAN LCF LR ODB PC SDK SIS SQL TAPM TCP/IP TDS © Copyright IBM Corp. 1999 221 222 Introducing Tivoli Application Performance Management Index A access on demand 5 Advanced Program to Program Communication (APPC) 25, 26 agent 12, 148, 149 agent ID 23 aggregation confirmation 150 process 149, 153 ams-file log 105 analog recording mode 27, 83 Application availability 5 defined metrics 21, 59 initialization 19 Instrumentation 6, 17 performance forecasts 167 response time measurement 16 throughput 5, 167 tuning 21 application performance management techniques application instrumentation 6 client capture 7 network X-ray 7 transaction simulation 7 ARM agent 17, 23, 28, 59, 60, 63 ARM API 21, 22, 29 buffer length 21 buffer pointer 21 call syntax 60, 61, 187 arm_end 20, 62, 193 arm_getid 19, 61, 66 , 189 arm_init 19, 61, 188 arm_start 20, 21, 61, 66, 67, 68, 166, 190 arm_stop 20, 21, 62, 66, 67, 68, 145, 166, 192 arm_update 20, 21, 61, 66, 67, 68, 166, 191 calls 6, 10, 12, 16, 20, 21, 23, 28, 29, 59, 70, 73, 89, 95, 112, 187 collecting correlators 22 collecting diagnostic information 23 collecting transaction metrics 23 correctors 21 New features 20 reserved parameter 21 Return codes 62 ARM application creation 64 data collection 148 registration 133 testing 70 using other languages 73 ARM application settings 141 ARM implemented script execution 92, 125 ARM Shared Library 59 ARM transaction informations 105 automatic transactions 107 B Baan 12, 26, 100 batch applications 5 Bitmap Regression Test 82 Bucket limits 137, 139 buffers 67 business process recording LoadRunner 98 QuickTest 117 C C application Adding ARM function calls 64 ARM instrumentation 64 compile process 69 link process 69 Testing instrumentation 70 canned_scripts 32 Case sensitivity 63 C-Code filename suffix 105 CLI commands 146 Client capture 7 Cognos Powerplay 34 Collecting correlators 22 collection interval 138, 148 Command Line Interface 48 compile process 69 , 71 Configuration 36 context sensitive recording mode 27, 29, 82 correlation analysis 23 in practice 22 response time 23 © Copyright IBM Corp. 1999 223 transaction 21, 28 correlator 22, 23, 28, 71, 147 collecting 22 cube 157, 162 cube building 164 Endpoint Gateway 33, 34 , 38, 41, 49, 197 Execution load by user 175 Extended log 108 D data aggregation 146 collection process 148 log files 147 metrics 167 source 161 database id 54 inconsistencies 49 installation 55, 56 operation 15 qualifier 160 setup 34 simulation 25 supported 35 uninstall script 57 user 54 Vuser scripts 26 dataless endpoint 179 Profile Manager 135 Date range 162, 164 Desktop Management 5 diagnostic information 23 disabled profile 141 disabled profile distribution 144 Discovery Administrator 34 , 157, 158 Client 34 Interface 34 Distributed Monitoring 33, 46 distribution verification 144 DOS 48 drill-down 171 drill-up 171 F filename suffixes 105 filtering 176 Forecast day 163 function calls 112 function comparisons ARM, WinRunner, LoadRunner 29 Function Generator 28 G GET command 107 GUI load command 86 map 27, 77, 88 consolidation 85 creation 27, 80 editor 87 loading 86 objects 27, 80, 82 Regression Test 81 Vuser scripts 26 H handle 20, 63, 71, 73 bad 63 good 63 hardware configuration 37 header file 60, 65, 69, 73, 187 heartbeat 20 historical data 12 host_name parameter 54 HP-UX 60 http 12 proxy 99 settings 106 I E Early Support Program (ESP) 31 Endpoint log 146 TAPM installation 48 IBM AIX 60 Informix 25 init_metric_application function 67 install repository 44 instrument what 15 224 Introducing Tivoli Application Performance Management instrumentation process 16 using other languages 73 verification 21 instutil utility 79, 116 integer variables 63 Inter Program Communication (IPC) 23 Interpreter 110 Iterations 108 lr_think_time 106 lr_update_transaction 28 lr_user_name 124 M Managed Node 51 managed resources modification 134 managed resources updation 51 management applications 18 manual upload process 153 mar directory 50 log 146 profile 51, 131, 133, 136, 141 mar_aggregated log 147, 149, 153 mar_trace log 146, 150, 151, 153 mar_trace_engine log 147 MAR_TRACE_MAX 154 MAR_TRACE_MIN 154 MAR_TRACE_NONE 153 mardataYYYYMMDD log 147, 148 marinfoYYYYMMDD log 147, 148 marproperties.ser file 153, 154 Mercury 24 metric 91 data 139, 179 function 64 label 162 structures 60 values 71 metric_data 67 modification of notice group 52 monitor 179 monitor installation 179 myinit file 88 editing 88 J Java 26, 100 Jolt 26 K key business transactions 15 L length - work queue 21 level of detail 139 library files 73 link process 69, 70, 71 load testing 25 LoadRunner 12, 16, 24, 95, 131 ARM functions 28 Installation 95 Sample script creation 95 script execution 105 script preparation 112 System Requirements 96 Log files 138, 146 logging agent 21, 60, 70, 71, 187 Logoff process 122 Logon process 122 lr functions 26, 122 lr_end_application 28, 113 lr_end_transaction 28, 91, 107, 113, 124, 145 lr_functions 89, 91, 107, 112 lr_set_application_name 28, 91, 113, 123, 132 lr_set_start_transactions 28 lr_set_subtransaction 28, 91, 113 lr_set_transaction_metrics 28, 91 lr_set_transaction_status 28 lr_set_user_name 28, 91, 113 lr_start_sub_transaction 28, 91, 113 lr_start_transaction 91, 107, 112, 113, 124 lr_stop_transaction 112 N NCR MP-RAS 60 Netscape Navigator 77 Netscape script 99 network bandwidth capacity planning 8 computing 3 load 16 management 12 packet data 7 X-ray 7, 8 225 Notice group 52 NULL library 59, 60, 70, 71, 92, 114, 187 R Rapid Test Script Wizard 27, 80 RDBMS server 34 rdbms_home parameter 54 Receive timeout 106 record application availability 17 recording a script 27 registration ARM application 133 virtual user script 131 Remote Procedure Call 15 remote queue operation 15 repository 131 response time 5, 7 by hostname 173 by transaction 169 collection 17 forecast 167 measurement 12, 16 Application instrumentation 12 Transaction simulation 12 threshold 162 trend 167 RIM 31, 34, 51 creation script 56 host 33, 54 interface 149, 151 object 55, 149 object creation 54 objects attributes 55 Robotic Client 32, 95, 96, 115 installation 116 RTE 25 RTE Vusers scripts 100 Rule 138 Run-time settings 105 filename suffix 105 O ODBC 25, 78, 158 connection 34 driver 157 Oracle 12, 25 database client 34, 36 database server 33 NCA 26 OS/2 60 P parameter - filename suffix 105 parameter substitution 111 parent transaction 22 passing parameters to script 101 PeopleSoft 12, 26 performance data 148 aggregation 34 collection 147 planning process 15 Policy Region 51 POST command 107 PowerBuilder 63, 73, 74 PowerBuilder application 73 PowerScript 73 prerequisites 31 probe 7 problem resolution 5 problematic transaction 23 profile 102, 110 creation 131, 135 distribution 11, 142, 146 distribution verification 144 Profile Manager 51 creation 134 S Sample application instrumentation 59 Sample C program 60 Armtest1.exe 207 Sample2.c 201 Sample script creation LoadRunner 95 QuickTest for R/3 115 WinRunner 77 SAP 12, 115 Q QuickTest 24, 29, 95, 115 installation 116 Sample script creation 115 script preparation 122 scripts 131 System requirements 116 226 Introducing Tivoli Application Performance Management SAP Quick Test 32 Scheduling 5 script 7 execution 88, 125 parameter passing 101 preparation 89, 112, 122 verification 105 verify execution 120 SDK 59, 64, 69, 75, 187 SDK installation 187 Security 5 sensor 7 SentryProfile 51 server_id parameter 54 Service Desk Guides 157 service level 12, 165 service level measurement 4 shared library 18, 187 simulated script 24 simulated transaction settings 136 simulation 16 parameters 142 tools 10 slice and dice 174 socks server settings 99 software configuration 37 Software Installation Service 44 source code 7 SQL-Plus connection 158 Step Generator 116 subtransaction 17, 21, 109, 124 Sun Solaris 60 Synchronization 45 synthetic user workstation 12 System DSN 157 T TAPM 8, 12, 16 agent 12, 148, 149 database installation 55, 56 database setup 34 desktop GUI installation 39 endpoint installation 48 engine component 38, 41 files and directories 50 Gateway 146, 149, 153 Gateway log 146 Installation 36 LoadRunner script preparation 112 manual uninstallation 50 monitor 47 monitor component 38 monitor installation 179 notice group 51 prerequisites 31 Profile distribution process 48 QuickTest script preparation 122 repository 131 RIM object 54 supported databases 35 table creation 55 TDS setup 157 un-installation 49 using uninstall script 49 WinRunner script preparation 89 TAPM Installation from command line 48 from SIS 44 from the desktop 38 TAPM Profile 10, 112, 133, 142, 144, 147 creating 179 distributing 185 editing 182 subscribing 181 tapm_DATA files 57 tapm_TEMP files 57 TaskLibrary 51 TDS 9, 12, 34, 157 cube building 164 Discovery Guide 157 Discovery Interface 168 Guide 31 Guide installation 157 guide usage 165 import guide 158 setup 157 test connection 161 Test Script Language 26, 27 Test Template 82 thinking time 106 Threshold 165 Time to Resolution 5 timer 12 Timing 106 Tivoli database 38 inconsistencies 50 restoration 50 227 Tivoli Discovery Interface 168 Tivoli Distributed Monitoring 8 Tivoli endpoint 12 Tivoli Enterprise Console 11, 33 Tivoli environment configuration 49 creation 32 setup 48 Tivoli framework 31 Tivoli Management Region 44 Tivoli Software Installation Service 44 TME desktop 51, 52 TMR server 38, 41 Toggle Wizard 160 trace flag 23 trace log files usage 150 TraceComponent 154 TraceLevel 154 transaction 3, 7, 15 class 19, 71 correlation 20, 21, 59 Filter 137 forecast 167 IDs 71 instance 20 measurement data 23 metrics 21, 23 monitoring 18, 59 Transaction completion status 167 Transaction Simulation 7, 24 , 48 TSL 26 See Test Script Language 27 tuning applications 15 TUXEDO 25, 26 virtual user script 16, 17 , 26, 27, 29, 148 creation 27, 31, 77 debugging 27 recording 82 recording business process 98 registration 131 Visual Basic 162 Visual Programming tool 27 VuGen 25, 32 file creation 104 filename suffix 105 functions 26, 29 installation 96 instrumentation process 16 recording business process 98 script creation 95 Vuser 26, 108 script 111 script execution 110 scripts 26 vuser_end function 26, 101 vuser_init function 26, 101 W Web 25 Web script 95, 105 Web Vuser 100, 106 Windows 95 60, 96 Windows 98 96 Windows NT 96 Windows Sockets 25 WinRunner 12, 16, 24, 26, 32, 77, 78, 82, 131 ARM functions 28 functions 29 installation 77 Sample script creation 77 script preparation 89 System requirements 78 toolkit 78 wmar commands 145, 195 wmarcleareng 146, 195 wmargetappreg 145, 195 wmargetdata 186, 195 wmargetstatus 196 wmargwinst 196 wmarlsappl 155, 197 wmarlseng 146, 155, 197 wmarreg 131, 198 U Un-installing TAPM 49 manual uninstallation 50 through uninstall script 49 upload confirmation 150 upload process 149, 153 upload process manual 153 User Interface Test 81, 82 user scripts 25 V verify script execution 120 virtual user 26, 29, 108 228 Introducing Tivoli Application Performance Management wmarstartcoll 146, 199 wmarstarteng 146, 154, 199 wmarstopcoll 146, 199 wmarstopeng 146, 154, 199 workload monitoring 15 WR_Delphi 32 WR_Java 32 WR_Oracle 32 229 230 Introducing Tivoli Application Performance Management IBM Redbooks evaluation Introducing Tivoli Application Performance Management SG24-5508-00 Your feedback is very important to help us maintain the quality of IBM Redbooks. Please complete this questionnaire and return it using one of the following methods: • Use the online evaluation form found at http://www.redbooks.ibm.com/ • Fax this form to: USA International Access Code + 1 914 432 8264 • Send your comments in an Internet note to redbook@us.ibm.com Which of the following best describes you? _ Customer _ Business Partner _ Solution Developer _ None of the above _ IBM employee Please rate your overall satisfaction with this book using the scale: (1 = very good, 2 = good, 3 = average, 4 = poor, 5 = very poor) Overall Satisfaction Please answer the following questions: __________ Was this redbook published in time for your needs? If no, please explain: Yes___ No___ What other redbooks would you like to see published? Comments/Suggestions: (THANK YOU FOR YOUR FEEDBACK!) © Copyright IBM Corp. 1999 231 Introducing Tivoli Application Performance Management SG24-5508-00 SG24-5508-00 Printed in the U.S.A.