IBM Tivoli Monitoring Version 5.1.1 Creating Resource Models and Providers Sg246900

Front cover
IBM Tivoli Monitoring Version 5.1.1

Creating Resource Models and Providers
Practical step-by-step development examples Creating cross-platform Java resource models Provider engineering and implementation
Tony Bhe Kiyonobu Inayama Craig Lister Massimiliano Parlione Michael Vesich
ibm.com/redbooks
International Technical Support Organization IBM Tivoli Monitoring Version 5.1.1 Creating Resource Models and Providers August 2003
SG24-6900-00
Note: Before using this information and the product it supports, read the information in Notices on page xvii.
First Edition (August 2003) This edition applies to Version 5, Release 1, Modification 1 of IBM Tivoli Monitoring.
Copyright International Business Machines Corporation 2003. All rights reserved. Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix The team that wrote this redbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi Comments welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi Part 1. ITM fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Chapter 1. IBM Tivoli Monitoring architecture . . . . . . . . . . . . . . . . . . . . . . . 3 1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.2 High level architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.3 Engine features and abilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.4 Endpoint integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.4.1 ITM data flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.4.2 Directory structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.5 ITM Engine architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 1.5.1 Engine input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 1.5.2 Engine output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 1.5.3 Engine components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Chapter 2. Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 2.2 Using Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 2.2.1 The Workbench panes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 2.2.2 Elements in Resource Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 2.2.3 Looking at the PhysicalDiskModel . . . . . . . . . . . . . . . . . . . . . . . . . . 28 2.3 Creating Resource Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 2.3.1 Creating Resource Models using the wizard. . . . . . . . . . . . . . . . . . . 46 2.3.2 Cloning existing Resource Models . . . . . . . . . . . . . . . . . . . . . . . . . . 60 2.3.3 Registering a Resource Model into ITM . . . . . . . . . . . . . . . . . . . . . . 61 2.4 Tools and extra information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 2.4.1 WorkBench command line interface . . . . . . . . . . . . . . . . . . . . . . . . . 62 2.4.2 Microsoft tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Copyright IBM Corp. 2003. All rights reserved.
iii
2.4.3 Saxsoft . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 2.4.4 Rhino . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Chapter 3. Resource Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 3.1 Resource Model overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 3.1.1 Logical components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 3.1.2 Physical components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 3.1.3 Types of Resource Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 3.2 Resource Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 3.2.1 Resource Models for each platform . . . . . . . . . . . . . . . . . . . . . . . . . 77 3.2.2 Windows Resource Models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 3.2.3 UNIX Resource Models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Chapter 4. Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 4.2 Industry technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 4.2.1 Web-Based Enterprise Management (WBEM) . . . . . . . . . . . . . . . . 113 4.2.2 The Common Information Model (CIM). . . . . . . . . . . . . . . . . . . . . . 113 4.2.3 Managed Object Format (MOF) . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 4.2.4 CIM Provider layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 4.2.5 Windows Management Interface (WMI) . . . . . . . . . . . . . . . . . . . . . 115 4.2.6 Java Management Extensions (JMX) . . . . . . . . . . . . . . . . . . . . . . . 117 4.3 Tivoli implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 4.3.1 ITM Engine components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 4.3.2 Legacy support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 4.3.3 Touchpoint Service Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 4.3.4 CIM object definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 4.3.5 Tivoli ILT Provider Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 4.3.6 Tivoli Management Extensions for Java (TMX4J). . . . . . . . . . . . . . 133 Part 2. Practical examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Chapter 5. Engineering a Java ILT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 5.1 Terminology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 5.2 Planning and design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 5.2.1 Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 5.2.2 CIM class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 5.2.3 ILT class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 5.2.4 Provider class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 5.2.5 Component reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 5.3 Implementing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 5.3.1 Managed Object Format (MOF) . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 5.3.2 ILT Java class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 5.3.3 Provider Java class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
iv
IBM Tivoli Monitoring: Creating Resource Models and Providers
5.3.4 Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 5.4 Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 5.4.1 Testing and importing the MOF. . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 5.4.2 Java compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 5.4.3 Making the jar file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 5.4.4 Assembling the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . 173 5.4.5 Building the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 5.5 ITSO_Sample template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 5.5.1 ITSO_Sample.mof. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 5.5.2 ITSO_SampleIlt.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 5.5.3 ITSO_Sample.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 5.5.4 Resource Model JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Chapter 6. Creating an SNMP Resource Model for Windows . . . . . . . . . 201 6.1 Designing the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 6.1.1 Design overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 6.1.2 What part of ITM will we use? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 6.1.3 Detailed design Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . 204 6.2 Creating the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 6.2.1 Installing SNMP and WMI SNMP on the managed machine . . . . . 205 6.2.2 Creating the new SNMP Resource Model . . . . . . . . . . . . . . . . . . . 211 6.2.3 Packaging the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 6.2.4 Testing the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 6.3 ITSO_SNMP_Interface_Bps source code . . . . . . . . . . . . . . . . . . . . . . . . 225 6.3.1 ITSO_SNMP_Interface_Bps.vba . . . . . . . . . . . . . . . . . . . . . . . . . . 225 Chapter 7. Creating an SNMP Resource Model for Java . . . . . . . . . . . . . 231 7.1 Terminology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 7.2 Planning and design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 7.2.1 Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 7.2.2 CIM class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 7.2.3 ILT class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 7.2.4 Provider class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 7.2.5 Component reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 7.3 Implementing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 7.3.1 Managed object format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 7.3.2 ILT Java class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 7.3.3 Provider Java class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 7.3.4 Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 7.4 Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270 7.4.1 Testing and importing the MOF. . . . . . . . . . . . . . . . . . . . . . . . . . . . 270 7.4.2 Java compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 7.4.3 Making the jar file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Contents
7.4.4 Assembling the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . 274 7.4.5 Building the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 7.5 ITSO_SnmpProbe source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 7.5.1 ITSO_SnmpProbe.mof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 7.5.2 ITSO_SnmpProbeILT.Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 7.5.3 ITSO_SnmpProbe.Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 7.5.4 SnmpInterface.Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300 7.5.5 Resource Model JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300 Chapter 8. Creating a log-file Resource Model. . . . . . . . . . . . . . . . . . . . . 305 8.1 Engine component utilization: Overview . . . . . . . . . . . . . . . . . . . . . . . . . 306 8.2 Creating the MOF files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307 8.3 Compiling the MOF file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 8.4 Creating the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316 8.5 Constructing the Resource Model: Events . . . . . . . . . . . . . . . . . . . . . . . 325 8.6 Constructing the Resource Model: Dependencies . . . . . . . . . . . . . . . . . 327 8.7 Constructing the Resource Model: Inserting code . . . . . . . . . . . . . . . . . 328 8.8 The flow of the code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 Chapter 9. Creating a log-file Resource Model and ILT . . . . . . . . . . . . . . 333 9.1 Designing the ITSO_LogfileLite Resource Model and ILT . . . . . . . . . . . 334 9.1.1 Design overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334 9.1.2 What part of ITM will we use? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 9.1.3 The detailed design of the ITSO_LogfileLite Resource Model . . . . 338 9.2 Creating the ITSO_LogfileLite Resource Model and ILT. . . . . . . . . . . . . 341 9.2.1 Setting up the development environment . . . . . . . . . . . . . . . . . . . . 341 9.2.2 Creating the MOF file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 9.2.3 Creating the ITSO_LogfileLite ILT code . . . . . . . . . . . . . . . . . . . . . 345 9.2.4 Creating the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 9.2.5 Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 9.2.6 Testing the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 9.3 ITSO_LogfileLite source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 9.3.1 ITSO_LogfileLite.mof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 9.3.2 ITSO_LogfileLite-wmi.mof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 9.3.3 ITSO_LogfileLiteILT.java. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 9.3.4 ITSO_LogfileLite.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 9.3.5 ITSO_LogfileLite_RM.js . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 Chapter 10. Creating a custom script Resource Model . . . . . . . . . . . . . . 411 10.1 Designing the ITSO_ProcessNum Resource Model . . . . . . . . . . . . . . . 412 10.1.1 Design overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412 10.1.2 What part of ITM will we use? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412 10.1.3 The detailed design of the ITSO_ProcessNum Resource Model . 413 10.2 Creating a custom script Resource Model . . . . . . . . . . . . . . . . . . . . . . 416
vi
10.2.1 Using the wizard to create a custom script Resource Model . . . . 416 10.2.2 Extending the functions of the Resource Model . . . . . . . . . . . . . . 421 10.2.3 Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432 10.2.4 Testing the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434 10.3 ITSO_ProcessNum source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442 10.3.1 ITSO_ProcessNum.js . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442 10.3.2 ITSO_ProcessNum.ksh. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446 Chapter 11. File monitoring Resource Model example . . . . . . . . . . . . . . 447 11.1 Engine component utilization: Overview . . . . . . . . . . . . . . . . . . . . . . . . 448 11.2 Compiling DMXFile MOF into Workbench. . . . . . . . . . . . . . . . . . . . . . . 449 11.2.1 Extraction of MOF from DMXFile resource monitor . . . . . . . . . . . 449 11.2.2 Strip UNIX control characters from the MOF file . . . . . . . . . . . . . . 450 11.2.3 Extraction of dependencies from the DMXFile resource monitor . 450 11.2.4 Compiling the MOF file to the CIM repository . . . . . . . . . . . . . . . . 450 11.3 Constructing the Resource Model: Dynamic Model . . . . . . . . . . . . . . . 459 11.3.1 Constructing the Resource Model: Events . . . . . . . . . . . . . . . . . . 464 11.3.2 Constructing the Resource Model: Parameters . . . . . . . . . . . . . . 467 11.3.3 Constructing the Resource Model: Dependencies . . . . . . . . . . . . 469 11.3.4 Constructing the Resource Model: Inserting code . . . . . . . . . . . . 470 11.3.5 The flow of the code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476 Part 3. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479 Appendix A. Testing a Java Resource Model . . . . . . . . . . . . . . . . . . . . . . 481 ITM Engine tracing and clean-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482 Debugging the Init function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483 Debugging the VisitTree function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486 Simulating data Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487 Verifying the Resource Model logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488 Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490 Appendix B. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495 Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495 Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495 System requirements for downloading the Web material . . . . . . . . . . . . . 496 How to use the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496 Abbreviations and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497 Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499 IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499 Other publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499 Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
Contents
vii
How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
viii
Figures
1-1 1-2 1-3 1-4 1-5 1-6 1-7 1-8 1-9 1-10 2-1 2-2 2-3 2-4 2-5 2-6 2-7 2-8 2-9 2-10 2-11 2-12 2-13 2-14 2-15 2-16 2-17 2-18 2-19 2-20 2-21 2-22 2-23 2-24 2-25 2-26 2-27 2-28 High level architecture view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 ITM data flow diagram: all platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Windows LCFD directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Windows ITM directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 UNIX directory structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Java ITM on UNIX directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . 14 ITM Engine components for Windows . . . . . . . . . . . . . . . . . . . . . . . . . . 16 ITM Engine components for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Engine sub-components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Graph of holes and occurrences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Introduction of the Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Panes in the Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 TMW_PhsyicalDiskModel general settings . . . . . . . . . . . . . . . . . . . . . . 29 Example of descriptive name in a profile . . . . . . . . . . . . . . . . . . . . . . . . 30 PhysicalDiskModel general settings . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Opening the CIM browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 PhysicalDisk resource class definitions . . . . . . . . . . . . . . . . . . . . . . . . . 33 Profile indications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 TMW_SlowPhysicalDrive event element settings . . . . . . . . . . . . . . . . . 36 PhysicalDiskModel thresholds in a profile . . . . . . . . . . . . . . . . . . . . . . . 38 PhysicalDiskModel HighPercentUsage threshold profile display . . . . . . 39 PhysicalDiskModel logging element profile display . . . . . . . . . . . . . . . . 40 PhysicalDiskModel percent disk usage element profile display . . . . . . . 41 Creating a Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Selecting JavaScript or Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Selecting the wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Selecting the data source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Connecting to namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Selecting a CIM class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Selecting properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Specifying the event trigger condition . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Entering the trigger condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Selecting the properties to log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Cycle time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Saving the source file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Building the package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Building the TEC BAROC file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
ix
2-29 3-1 3-2 3-3 4-1 4-2 4-3 4-4 4-5 4-6 4-7 4-8 4-9 4-10 4-11 4-12 5-1 5-2 5-3 5-4 5-5 5-6 5-7 5-8 5-9 5-10 5-11 5-12 5-13 6-1 6-2 6-3 6-4 6-5 6-6 6-7 6-8 6-9 6-10 6-11 6-12 6-13 6-14
Copying the package file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Logical components of the Resource Model . . . . . . . . . . . . . . . . . . . . . 69 Sampling of volatile metric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Physical components in the Resource Model . . . . . . . . . . . . . . . . . . . . 74 IT management methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Management technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 JMX MBean server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Management agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 ITM Engine Logical Components (Java) . . . . . . . . . . . . . . . . . . . . . . . 121 Common logical components for Windows and Java . . . . . . . . . . . . . 122 ITM Engine Logical Components (Windows) . . . . . . . . . . . . . . . . . . . . 124 Logical components for Windows COM support . . . . . . . . . . . . . . . . . 125 Logical components for Windows WMI native support . . . . . . . . . . . . 127 Logical components for Windows and Java custom scripts. . . . . . . . . 128 Logical components for Windows and Java DM Classic . . . . . . . . . . . 128 Logical components for Windows and Java ILTs. . . . . . . . . . . . . . . . . 132 Java ITM Engine logical components . . . . . . . . . . . . . . . . . . . . . . . . . 142 ITM Workbench: about selected class . . . . . . . . . . . . . . . . . . . . . . . . . 144 ITM Workbench: General Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 ITM Workbench: Dynamic Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 ITM Workbench: parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 ITSO_Sample.tar: Resource Model Tar File . . . . . . . . . . . . . . . . . . . . 170 mofcomp output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 javac output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 javac output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 jar output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 ITM Workbench: Tree view pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 ITM Workbench: Build menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 ITM Workbench: Save As . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 Design overview of ITSO_SNMP_Interface_Bps Resource Model . . . 202 ITM Engine logical components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 Installing Optional Networking Components . . . . . . . . . . . . . . . . . . . . 206 Installing the SNMP Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 Enabling SNMP Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 Installing the WMI SNMP Provider. . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 Connect to namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 Browse for Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 Browse for Namespace to localhost . . . . . . . . . . . . . . . . . . . . . . . . . . 213 Selecting a class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 Selecting properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 Collection test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 Filter condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
6-15 6-16 6-17 6-18 6-19 6-20 7-1 7-2 7-3 7-4 7-5 7-6 7-7 7-8 7-9 7-10 7-11 7-12 7-13 7-14 8-1 8-2 8-3 8-4 8-5 8-6 8-7 8-8 8-9 8-10 8-11 8-12 8-13 8-14 8-15 8-16 8-17 8-18 8-19 8-20 8-21 8-22 8-23
Entering the trigger condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 Using the Proc drop down selector . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 Resource Model Tar File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 Step to cursor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 Quick Watch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 Debugging the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 Java: ITM logical components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 ITM Workbench: About selected class. . . . . . . . . . . . . . . . . . . . . . . . . 238 ITM Workbench: General Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 ITM Workbench: Dynamic Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 ITM Workbench: Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 ITSO_SnmpProbe.tar: Resource Model Tar File . . . . . . . . . . . . . . . . . 270 mofcomp output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 SnmpInterface.java: javac output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 ITSO_SnmpProbe.java: javac output. . . . . . . . . . . . . . . . . . . . . . . . . . 272 ITSO_SnmpProbeILT.java: javac output . . . . . . . . . . . . . . . . . . . . . . . 273 jar output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 ITM Workbench: Tree view pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 ITM Workbench: Build menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 ITM Workbench: Save As dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 Resource Model sub-components for Windows . . . . . . . . . . . . . . . . . 306 Resource Model sub-components for Java . . . . . . . . . . . . . . . . . . . . . 307 Workbench new Resource Model window . . . . . . . . . . . . . . . . . . . . . . 309 Select VBA or JavaScript language . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 Workspace selection window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310 Select data source window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 Connect to namespace window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 Username/password selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312 Select a Class window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312 MOF compiler action select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313 MOF file path and namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314 MOF compiler wizard update options window . . . . . . . . . . . . . . . . . . . 315 MOF compile results window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 Resource Model Wizard: Select a Class window. . . . . . . . . . . . . . . . . 316 Resource Model Wizard: Select Properties window . . . . . . . . . . . . . . 317 Resource Model Wizard: Filtering window . . . . . . . . . . . . . . . . . . . . . . 318 Resource Model Wizard: Specify the Event Triggering Conditions . . . 319 Resource Model Wizard: Select the Properties to log window . . . . . . 320 Resource Model cycle time data entry panel . . . . . . . . . . . . . . . . . . . . 320 IBM Tivoli Monitoring Workbench main window . . . . . . . . . . . . . . . . . 321 Dynamic Model data entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322 Dynamic Model data entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323 Dynamic Model data entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Figures
xi
8-24 8-25 8-26 8-27 9-1 9-2 9-3 9-4 9-5 9-6 9-7 9-8 9-9 9-10 9-11 9-12 9-13 9-14 9-15 9-16 9-17 9-18 9-19 9-20 9-21 9-22 9-23 9-24 9-25 9-26 10-1 10-2 10-3 10-4 10-5 10-6 10-7 10-8 10-9 10-10 10-11 10-12 10-13
IBM Tivoli Monitoring Workbench main window . . . . . . . . . . . . . . . . . 325 Event construction window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326 IBM Tivoli Monitoring Workbench main window . . . . . . . . . . . . . . . . . 327 IBM Tivoli Monitoring Workbench main window . . . . . . . . . . . . . . . . . 328 Design overview of ITSO_LogfileLite Resource Model . . . . . . . . . . . . 335 Windows ITM Engine Logical Components . . . . . . . . . . . . . . . . . . . . . 337 UNIX ITM Engine Logical Components . . . . . . . . . . . . . . . . . . . . . . . . 337 Flowchart of ITSO_LogfileLite decision tree script. . . . . . . . . . . . . . . . 340 Setting the CLASSPATH environment variable . . . . . . . . . . . . . . . . . . 342 The relationship of the methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 Creating a new Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 Selecting data source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 Connect to namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 Launching the MOF Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360 Selecting a MOF file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 Completing the compile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 Selecting the class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 Trigger condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 Property of the ITSO_LogfileLite Resource Model . . . . . . . . . . . . . . . 364 Setting the alias name of the CIM class. . . . . . . . . . . . . . . . . . . . . . . . 365 Changing the event setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366 Changing the threshold setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367 Adding the ITSO_LogfileLite_Pattern parameter . . . . . . . . . . . . . . . . . 368 Adding the ITSO_LogfileLite_FileName parameter . . . . . . . . . . . . . . . 368 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 Category and Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 Parameter ITSO_LogfileLite_FileName . . . . . . . . . . . . . . . . . . . . . . . . 378 Parameter ITSO_LogfileLite_Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . 379 Event ITSO_LogfileLite_EventNum_too_high . . . . . . . . . . . . . . . . . . . 380 Design overview of ITSO_ProcessNum Resource Model . . . . . . . . . . 412 ITM Engine Logical Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 Flowchart of ITSO_ProcessNum Resource Model . . . . . . . . . . . . . . . 415 Creating a new ITM Workbench project. . . . . . . . . . . . . . . . . . . . . . . . 417 Selecting data source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418 Importing the custom script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419 Trigger condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420 Saving the Resource Model file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 ITM Workbench thermometer icon. . . . . . . . . . . . . . . . . . . . . . . . . . . . 422 Changing properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 Opening the event setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424 Changing the event setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 Changing the threshold setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
xii
10-14 10-15 10-16 10-17 10-18 11-1 11-2 11-3 11-4 11-5 11-6 11-7 11-8 11-9 11-10 11-11 11-12 11-13 11-14 11-15 11-16 11-17 11-18 11-19 11-20 11-21 11-22 11-23 11-24 11-25 11-26 11-27 11-28 A-1 A-2
Adding the parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428 Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433 Category and Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435 Parameter of the ITSO_ProcessNum . . . . . . . . . . . . . . . . . . . . . . . . . 436 Event I of the ITSO_ProcessNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437 Resource Model sub-components for Windows . . . . . . . . . . . . . . . . . 448 Resource Model sub-components for Java . . . . . . . . . . . . . . . . . . . . . 449 Workbench new Resource Model window . . . . . . . . . . . . . . . . . . . . . . 451 Select VBA or JavaScript language . . . . . . . . . . . . . . . . . . . . . . . . . . . 451 Workspace selection window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452 Select data source window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453 Connect to namespace window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453 Browse For Namespace window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454 Username/password selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454 Select a class window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455 MOF compiler action select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456 MOF file path and namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457 MOF compiler wizard update options window . . . . . . . . . . . . . . . . . . . 458 MOF compile successful results window . . . . . . . . . . . . . . . . . . . . . . . 458 MOF compile error results window . . . . . . . . . . . . . . . . . . . . . . . . . . . 459 Resource Model Wizard: Select a Class window. . . . . . . . . . . . . . . . . 460 Resource Model wizard properties selection window . . . . . . . . . . . . . 461 Resource Model wizard triggering conditions selection window . . . . . 462 Resource Model wizard filtering selection window. . . . . . . . . . . . . . . . 463 Resource Model cycle time data entry panel . . . . . . . . . . . . . . . . . . . . 463 IBM Tivoli Monitoring Workbench main window . . . . . . . . . . . . . . . . . 464 Event construction window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465 Event construction window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466 IBM Tivoli Monitoring Workbench main window . . . . . . . . . . . . . . . . . 467 Parameter data entry window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468 Parameter data entry window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468 IBM Tivoli Monitoring Workbench main window . . . . . . . . . . . . . . . . . 469 IBM Tivoli Monitoring Workbench main window . . . . . . . . . . . . . . . . . 470 The Quadcap Embeddable Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 489 Opening the database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
Figures
xiii
xiv
Tables
2-1 3-1 3-2 3-3 3-4 3-5 3-6 3-7 3-8 3-9 3-10 3-11 3-12 3-13 3-14 3-15 3-16 3-17 3-18 3-19 3-20 3-21 3-22 3-23 3-24 3-25 3-26 5-1 5-2 6-1 6-2 7-1 9-1 9-2 9-3 9-4 9-5 9-6 Supported Resource Model type per operating system . . . . . . . . . . . . . 47 Resource Model types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Windows Resource Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 UNIX Resource Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 OS/400 Resource Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Memory Resource Model dependencies . . . . . . . . . . . . . . . . . . . . . . . . 85 Network Interface Card Resource Model dependencies . . . . . . . . . . . . 87 Parametric event log Resource Model dependencies . . . . . . . . . . . . . . 90 Parametric Services Resource Model dependencies . . . . . . . . . . . . . . 90 Parametric TCP/IP Ports Resource Model dependencies . . . . . . . . . . . 91 Logical Disk Resource Model dependencies . . . . . . . . . . . . . . . . . . . . . 91 Physical Disk Resource Model dependencies . . . . . . . . . . . . . . . . . . . . 92 Printing Resource Model dependencies . . . . . . . . . . . . . . . . . . . . . . . . 93 Process Resource Model dependencies . . . . . . . . . . . . . . . . . . . . . . . . 94 Processor Resource Model dependencies . . . . . . . . . . . . . . . . . . . . . . 95 Services Resource Model dependencies. . . . . . . . . . . . . . . . . . . . . . . . 96 TCP/IP Resource Model dependencies . . . . . . . . . . . . . . . . . . . . . . . . . 97 Table of correlated indications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 CPU Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Memory Resource Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 File Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Process Resource Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Network Interface Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 File system Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Security Resource Model and file monitoring: Part 1 . . . . . . . . . . . . . . 105 Security Resource Model and file monitoring: Part 2 . . . . . . . . . . . . . . 106 Network RPC/NFS Resource Model (Sun Solaris specific) . . . . . . . . . 107 ILT supported classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 CIM class properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 The indication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 List of elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 CIM class properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 The parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 The indication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 A list of elements of the ITSO_LogfileLite Resource Model. . . . . . . . . 338 Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 An example of the values of the properties . . . . . . . . . . . . . . . . . . . . . 344 Operations in the ITSO_LogfileLite ILT . . . . . . . . . . . . . . . . . . . . . . . . 346
xv
9-7 9-8 9-9 9-10 9-11 10-1 10-2 10-3 10-4 10-5 10-6 10-7 10-8 10-9 10-10 A-1 A-2 A-3 A-4 A-5 A-6 A-7 A-8
Operations in the ITSO_LogfileLite Provider . . . . . . . . . . . . . . . . . . . . 353 The event of ITSO_LogfileLite_EventNum_too_high. . . . . . . . . . . . . . 366 The threshold definition for Thr_EventNum_gt . . . . . . . . . . . . . . . . . . 367 Dependency files for each platform . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 Summary of the useful trace and log files . . . . . . . . . . . . . . . . . . . . . . 382 The parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 The indication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 A list of elements of the ITSO_ProcessNum Resource Model . . . . . . 414 The event of Ev_process_num_becomes_very_high . . . . . . . . . . . . . 425 The event of Ev_process_num_becomes_high . . . . . . . . . . . . . . . . . . 426 The event definition for Ev_process_num_becomes_low . . . . . . . . . . 426 The threshold definition for Ev_process_num_becomes_veryhigh . . . 427 The threshold definition for Ev_process_num_becomes_high . . . . . . 428 The threshold definition for Ev_process_num_becomes_low . . . . . . . 428 ITSO_ProcessNum Resource Model scenarios . . . . . . . . . . . . . . . . . 438 Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490 RmProfiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491 Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491 Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491 Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492 Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492 MetricsData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492 CategoriesData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
xvi
Notices
This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described 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: IBM Director of Licensing, IBM Corporation, North Castle Drive Armonk, NY 10504-1785 U.S.A.
The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include 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. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrates programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing, or distributing application programs conforming to IBM's application programming interfaces.
xvii
Trademarks
The following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both: AIX ^ eServer IBM ibm.com NetView Notes OS/400 Perform Redbooks Redbooks (logo) RMF S/390 Tivoli Tivoli Enterprise Tivoli Enterprise Console TME WebSphere
The following terms are trademarks of other companies: Intel, Intel Inside (logos), MMX, and Pentium are trademarks of Intel Corporation in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. SET, SET Secure Electronic Transaction, 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.
xviii
Preface
This IBM Redbook focuses on creating Resource Models (RMs) and Providers for the IBM Tivoli Monitoring Version 5.1.1 infrastructure. The ITM Workbench is used for developing, debugging, and packaging Resource Models for IBM Tivoli Monitoring. You will learn how to use the step-by-step wizards provided by the ITM Workbench to create RMs to monitor any number of your IT resources, including operating systems, databases, hardware resources, and applications. In addition, you will learn how to use the step-by-step instructions to bind groups of Resource Models into deployable PACs using the ITM Toolkit. Upon completion, you will be able to create, test, and deploy monitoring solutions, quickly and efficiently creating an autonomic environment.
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. Tony Bhe is an IT Specialist in the United States. He has eight years of experience in the IT industry with seven years of direct Tivoli Enterprise products experience while working for IBM. He holds a degree in Electrical Engineering from North Carolina State University in Raleigh, North Carolina. His areas of expertise include Tivoli Performance and Availability and Tivoli Configuration and Operations. He has spent the last three years working as a Tivoli Integration Test Lead, and one year prior to that as a Tivoli Services consultant for Tivoli Performance and Availability products. Kiyonobu Inayama is an IT Specialist working at IBM Japan. He has eight years of experience mainly in systems and network management, architecting solutions, and consulting for IBM customers. He also teaches IBM classes in Japan on the areas of systems and network management. His areas of expertise include Tivoli Performance and Availability Management: server monitoring, transaction performance, and network management. Kiyonobu holds a bachelor's degree in Computer Science from Nagoya University, Japan. Craig Lister is a Tivoli Analyst with StGeorge Bank in Australia. He has twenty years of experience in the IT industry. His areas of expertise include ITM, DM, and TEC rule writing, and has a passion for Perl. Massimiliano Parlione is a Software Engineer in the IBM Tivoli Software lab in Rome, Italy. He has been with IBM Tivoli Software since April 2000. He worked
xix
in the teams that developed and designed Tivoli Java Management Extensions (TMX4J), Tivoli Web Component Manager (TWCM), and ported ITM Version 5.1.1 on OS400 and OS2. Currently, he is working on the ITM 5.2 OEM Java engine. Before joining IBM, Mr. Parlione worked as an independent consultant for the Italian Research Council (CNR) and as an employee of the Regione Marche regional government. He received his degree (laurea) in Computer Science from the University of L'Aquila, Italy, in July 1995 and a doctorate in Computer Science from the University "La Sapienza" of Rome in April 2000. He is co-author of the Introducing IBM Tivoli Monitoring for Web Infrastructure, SG24-6618 redbook. Michael Vesich is a member of the Tivoli Services organization in North America. He has over fourteen years experience in the information systems field with nine years in software development. Prior to joining IBM in 1998, Michael worked for Kvaerner Engineering, initially as an Automation Engineer developing real-time industrial process control systems and later becoming the I.T. Director for the Merrillville facility. Since joining IBM, he has focused on the Performance and Availability product set, with a more recent role as an ITM Subject Matter Expert. He has contributed to the Tivoli Certification program, Business Partner enablement, and was the initial developer of the Tivoli Knowledge Toolkit. Thanks to the following people for their contributions to this project: Joanne Luedtke, Edson Manoel, Stephen Hochstetler, Lupe Brown, Wade Wallace, and Chris Blatchley International Technical Support Organization, Austin Center Wade Allen Software Developer, IBM Software Group Kevin P. Ferguson Software Developer, IBM Software Group Steve Gutierrez Software Developer, IBM Software Group Jason Hooper Senior Software Engineer, IBM Software Group Bill Horne Software Developer, IBM Software Group Richard F. Reed Systems Integrator Consultant, IBM Software Group
xx
Theo Winkelmann Technical Evangelist, IBM Software Group
Become a published author

Join us for a two- to six-week residency program! Help write an IBM Redbook dealing with specific products or solutions, while getting hands-on experience with leading-edge technologies. You'll team with IBM technical professionals, Business Partners and/or customers. Your efforts will help increase product acceptance and customer satisfaction. As a bonus, you'll develop a network of contacts in IBM development labs, and increase your productivity and marketability. Find out more about the residency program, browse the residency index, and apply online at:
ibm.com/redbooks/residencies.html
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: Use the online Contact us review redbook form found at:
ibm.com/redbooks
Send your comments in an Internet note to:

redbook@us.ibm.com
Mail your comments to: IBM Corporation, International Technical Support Organization Dept. JN9B Building 003 Internal Zip 2834 11400 Burnet Road Austin, Texas 78758-3493
Preface
xxi
xxii
Part 1
Part
ITM fundamentals
In this part, we introduce the architecture and theory behind the IBM Tivoli Monitoring Version 5.1.1 product, and provide definitions of the intricate pieces of the product, including the different types of Providers. Specifically, we cover the following topics: IBM Tivoli Monitoring Architecture IBM Tivoli Monitoring Workbench Resource Models Providers
Chapter 1.
IBM Tivoli Monitoring architecture

This chapter provides an overview of the IBM Tivoli Monitoring Version 5.1.1 engine architecture, as well as references to the components that support the engine. Subsequent chapters will provide specific details on the components related to the creation of custom IBM Tivoli Monitoring Version 5.1.1 instrumentation.
1.1 Overview
IBM Tivoli Monitoring Version 5.1.1 (ITM) is a Resource Model based monitoring infrastructure that provides Resource Models for best practice monitoring of common resources. ITM also provides System Administrators a means to extend its monitoring capabilities by providing the ability to create and import custom Resource Models and dynamically pluggable instrumentation. The focus of this redbook is on the methods used to extend the monitoring capabilities of the product through the use of IBM Tivoli Monitoring Workbench 5.1.1 (ITMWB), which is supplied with the product, and through the development of custom Java instrumentation. After the development of a custom Resource Model is complete, the package created by the ITMWB can be installed into your Tivoli Enterprise environment from the command line. Once installed into the Tivoli Enterprise environment, the new Resource Model can then be used in the same manner as the ITM provided Resource Models.
1.2 High level architecture

Figure 1-1 on page 5 gives a high level overview of the full data flow of IBM Tivoli Monitoring Version 5.1.1. You will note that the flow commences with either the distribution of a supplied Resource Model or the development of a custom Resource Model from ITMWB, and completes with the measured metrics being supplied to one or all of the following: IBM Tivoli Data Warehouse IBM Tivoli Web Health Console IBM Tivoli Event Console The cycle of instrumenting and reporting will repeat, with the above outputs, until the ITM Engine is stopped.
Trend Analy sis Trend Ana lysis CuCu s t s to om m ize ize/ /D Dis Data Warehouse De Data Warehouse is t r D tri ib fa e bu utRollup ulfau ts lt te e Rollup s y
Profile Profile
TMR TMR TMR TMR Tivoli Event Console In

Resource Model Resource Model
ll s ta
ITM ITM HeartBeat HeartBeat
tall In s
Design Create Design , Create, Deb ug Debug
Di st r ib ut Distribute e
Web Health la Web Health Display Console isp Console D Ge tD ata Get Data Endpoint
Unix/Linux Endpoint Endpoint Windows Windows NT/2000 NT/2000 Endpoint ITM Engine Uni x/Linux ITM Engine
Workbench Workbench
ITM Engine ITM Engine
Figure 1-1 High level architecture view
1.3 Engine features and abilities

ITM eliminates the need to transfer large amounts of diagnostic data back to a central location for evaluation. On each localized endpoint, it has the ability to: Perform root-cause analysis Isolate individual faults Initiate programmed corrective actions The ITM Engine is able to initiate the following functions on the endpoint: Event analysis
Chapter 1. IBM Tivoli Monitoring architecture
Event correlation (Windows only) Event aggregation Event management Data logging The engines ability to perform these functions locally is what frees the system administrators from the analysis of multiple data sources, including large log files, event logs, and performance metrics, to detect resource failures and bottlenecks. A further extension of the local engines capabilities is obtained when the data logging feature is used in conjunction with IBM Tivoli Data Warehouse. This enables system administrators to gain a trend analysis tool for any resource profile from which data logging is enabled. All instrumentation sources for ITM are provided to the engine through a Common Information Model (CIM) interface. In a Windows environment, this is provided by Microsofts implementation of CIM, Windows Management Instrumentation (WMI). The UNIX component of CIM is provided via IBM Tivolis own CIM implementation, which is called Touchpoint.
1.4 Endpoint integration

There are several aspects that make up the ITM integration with the Tivoli Endpoint. It helps to be able to identify these aspects in order to aid in problem diagnosis. First, understanding the flow of information through the endpoint to the ITM components will assist in determining which components may be at fault; is the problem high level (TMR or specifically MDist2), mid-level (the assigned Gateway), or low-level (the Endpoint or ITM Engine itself)? Second, the directory structures of the engine will define which files or paths should be investigated when a problem is believed to be on the endpoint directly.
1.4.1 ITM data flow

It is helpful to understand the flow of configuration information as it relates to the ITM components. Figure 1-2 on page 7 provides a high level view of the ITM Engine upon which later chapters will provide additional granularity.
Data Flow
TME
LCF
ITM Engine
2 3
ITM Engine Analyzer Event Handling
4
TMWService (Java Class)
Platform Specific CIM Implementations Reference s ITM Logical Diagrams: Touchpoint (Java) -orWMI (Windows) Provider Layer Resources (OS & Applications)
Figure 1-2 ITM data flow diagram: all platforms
Figure 1-2 on page 7 contains five boxes numbered one through five. Each of these boxes represents a data flow and is defined in the subsequent numbered lists. Each list number represents the number in the box in Figure 1-2 on page 7. 1. Management Framework & Endpoint Management [M9] information (that is, Reference Model and Parameters) and Manageability [M12] information (that is, Dynamic Model) reach the endpoint through a conduit, currently the Tivoli Endpoint agent, LCFD. 2. ITM Engine The ITM Engine works as a faade between the LCFD and the ITM components. It receives Tmw2k profile distributions and configuration changes from the LCFD and configures the management function, the analyzer component, with the management information, Resource Model and parameters, and the Touchpoint with the manageability information, and Dynamic Model. 3. Dynamic Model The Dynamic Model is loaded in the Touchpoint. The manageability information presented in M12 MOF format will be loaded in the underlying CIMOM. 4. Analyzer The Analyzer component is actually a script engine, which means the configuration that it receives from the faade is presented in script form. In this script, the TMWService object is instantiated and initialized with information about the resource that it needs to collect metrics on. At run time, the code inside the script invokes the collect method of TMWService, which in turn accesses the Touchpoint to collect the resource metrics. 5. TMWService a. Java platform Driven by the script, TMWService Java class accesses the Touchpoint using the Touchpoint service layer (TSL) interface on Java to collect the resource metrics. b. Windows platform Driven by the script, the TMWService COM object accesses the WMI using the WMI APIs to collect the resource metrics. The metrics may be direct WMI Providers or ILT compliant Providers utilizing the Tivoli Touchpoint Java engine. The metric data collected is reported back to the Resource Model script where it is processed according to the best practices coded within the script. An event handling component is then used to allow the analyzer to communicate the result of the best practices appliance to other components.
CIM components and the Provider layer

The Common Information Model (CIM) allows the ITM Engine to handle system resources in an industry standard object oriented fashion, while the Provider layer allows for dynamically pluggable instrumentation within the ITM Engine. The concepts and technologies behind the CIM implementation and the Provider layer are discussed at length in Chapter 4, Providers on page 109.
Resources
Resources refers to the physical resources that the Provider components provide instrumentation for. Instrumentation is handled through either operating system libraries or Application Programming Interfaces (APIs), such as Java or vendor supplied APIs. Such resources include, but are not limited to, the following: System hardware Operating system Applications
1.4.2 Directory structures

When troubleshooting, it is important to know where to find the files you need. This section will give some insight into where log files and other ITM components are located.
Windows platform
Figure 1-3 on page 10 corresponds to the Framework (LCFD) components of the endpoint. The primary log file, lcfd.log, can be found in the lcf\dat\1 directory. This log file can prove to be very useful while diagnosing many problems.
Figure 1-3 Windows LCFD directory structure
It is also important to note that the lcf\bin\w32-ix86\JRE\DMAE directory is where Java is installed by default when you distribute a profile from the command line using the wdmdistrib command and the -J switch.
10
Another directory of interest is lcf\bin\w32-ix86\tools. This is where all the tool type programs (perl, bash, ntprocinfo, and so on) reside. Figure 1-4 corresponds to the ITM components of the endpoint. The main ITM log file resides in the lcf\dat\1\LCFNEW\Tmw2k directory and is named Tmw2k.log. It is in here that you will find most of your ITM debugging information when you run into problems.
Figure 1-4 Windows ITM directory structure
Another useful file is located in lcf\dat\1\LCFNEW\AMG\logs and is named logging.properties. This file is a Java config file that gives you the ability to initiate logging for the various Java modules. This is easily done by looking for lines such as islogging=False and changing them to islogging=true, and then restarting the ITM Engine. You will notice another directory under the preceding directory called log files. This directory relates to the log file adapter Resource Model discussed later in this book. It is in this file that the offsets are stored when reading log files. If the engine is stopped and Java is also stopped, you can remove this file. When the
11
engine restarts, the ITM log file adapter will start reading from the beginning of your log file. In the directory lcf\dat\1\LCFNEW\AMW\logs, you will find three other log files named ILTManagerForJava1.log, trace_ILTManagerForJava.log, and msg_ILTManagerForJava.log. These can be useful when debugging Java ILT issues. If you have enabled logging in your profile, then the directory lcf\dat\1\LCFNEW\Tmw2k\db is where the log information is written on a Windows endpoint and stored in a Microsoft Access database. The lcf\dat\1\LCFNEW\Tmw2k\Dec directory is particularly interesting. This directory is where your code, be it VBA or Java, is stored on the local endpoint. If you stop your ITM Engine by use of the wdmcmd -stop -e <endpointname> command, you are able to make changes to this script on the local endpoint. You will then be able to restart the ITM Engine and validate your changes. This can be a great time saver, as you do not have to go all the way out to the ITMWB and back through the distribution process. In the lcf\dat\1\LCFNEW\Tmw2k\Mof directory, you will find your MOF files that you compiled from the ITMWB. There is also a directory within this tree named compiled. It houses the locally compiled MOF files. So if your MOF file is in the top directory but not in the compiled directory, then you know that you have a problem. Finally, the lcf\dat\1\LCFNEW\Tmw2k\Unix\Classes\WizGenRM directory is the storage area for any dependant jar files that you may have included in your Resource Model.
Java platform on UNIX

Figure 1-5 on page 13 corresponds to the Framework (LCFD) components of the endpoint. The main LCFD log file, lcfd.log, can be found in the lcf\dat\1 directory. This log file can prove to be very useful while diagnosing many problems. It is also important to note that lcf\bin\aix4-r1\JRE\DMAE is where Java is installed by default when you distribute a profile from the command line using the wdmdistrib command and the -J switch.
12
Figure 1-5 UNIX directory structure
It is in the lcf\dat\1\LCFNEW\AMW\logs directory, in Figure 1-6 on page 14, where you will find the trace_dmxengine.log, msg_dmxengine.log, trace_dmxeu.log and trace_dmxntv.log log files. The file that will be most useful
13
is trace_dmxengine.log. This file is the equivalent to the Windows endpoint Tmw2k.log. The best way to view the file, as it is XML formatted, is to open the file in a text editor and set word wrap on.
Figure 1-6 Java ITM on UNIX directory structure
14
Another useful file is located in lcf\dat\1\LCFNEW\AMG\logs and is named logging.properties. This file is a Java config file, which give you the ability to instigate logging for the various Java modules. This is easily done by looking for lines like islogging=False and changing it to islogging=true, and then restarting the ITM Engine. If you have enabled logging in your profile, then the lcf\dat\1\LCFNEW\Tmw2k\Unix\data\ITMLogger\dblogger directory is where the log information is written on a UNIX endpoint. The logging information is stored in an Open Source Database by Quadcap Software. The lcf\dat\1\LCFNEW\Tmw2k\Unix\Dec directory is particularly interesting. It is here that your code, be it VBA or Java, is stored on the local endpoint. If you stop your ITM Engine by use of the wdmcmd -stop -e <endpointname> command, you are able to make changes to this script on the local endpoint. After restarting the ITM Engine, you can then validate your changes. This can be a great time saver, as you do not have to go all the way out to the ITMWB and back through the distribution process. Finally, the lcf\dat\1\LCFNEW\Tmw2k\Unix\Classes\WizGenRM directory is the storage area for any dependant jar files that you may have included in your Resource Model.
1.5 ITM Engine architecture

Figure 1-7 on page 16 highlights the logical components that comprise the Windows platform ITM Engine.
15
Windows, ITM Engine Logical Components

Analyzer Resource Model Resource Model Resource Model Resource Model Resource Model Resource Model Resource Model
TMWService WMI APIs DM Classic Monitor Probes WMI (CIMOM) Custom Scripts ILT Manager for Java (WMI Provider DLL) WMI Provider DLLs Java Virtual Machine (JVM) Launch (Class Loader) ILT Providers Resource Resource Resource Resource Resource ILT Provider JNI Binary Library MBean Server MBean1 JMX ILT
COM Objects
Resources (OS & Applications)
Figure 1-7 ITM Engine components for Windows
Figure 1-8 on page 17 highlights the logical components that comprise the Java platform ITM Engine.
16
Java, ITM Engine Logical Components

Analyzer Resource Model Resource Model Resource Model Service Object Resource Model Resource Model
DM Classic Monitor Probes
Custom Scripts
Launch (Class Loader)
Java Class Loader ILT Providers ILT Provider JNI Native Binaries MBean Server MBean(s) JMX ILT
Resource
Resource
Resource
Figure 1-8 ITM Engine components for Java
1.5.1 Engine input

To get the engine to monitor your endpoint, you need to create a profile that contains at least one Resource Model and distribute it to the endpoint. A Resource Model is a way of monitoring certain properties of the endpoint to which the profile, which contains the Resource Model, is distributed. The data is derived through the Service Object API using WMI or CIM from the endpoints operating system. When the Resource Model is distributed to the endpoint, the following types of files are placed in the directories described in 1.4.2, Directory structures on page 9 and Java platform on UNIX on page 12: Managed Object Format (MOF) Visual Basic or JavaScript
17
Dependent jar files A Resource Model may have the following elements defined depending on the desired functionality: Visual Basic or JavaScript, as contained in the VisitTree function Events Thresholds Parameters Logging Dependencies
The script component

Every Resource Model requires some programatic instructions on how to deal with the metric data supplied. It needs to compare these values against your thresholds and decide when it is appropriate to generate the alerting events. The public function VisitTree contains your monitoring algorithm, which will be called cyclically, as specified in your Resource Model.
Events and thresholds

Each Resource Model can include one or more events which will be checked against its corresponding threshold. Each period cycle, the monitored resource is checked against the specified numeric threshold. If the threshold is exceeded, then an event will be escalated. Events can have many causative indications or only one. If there are many indications, they must be aggregated before they trigger an event. If the indication does not exceed its particular threshold, it is called a hole. Holes are used to reset indications. In other words, if an indication exceeds its threshold for three cycles in a row without any holes, then an event would be generated. If, on the second cycle, the threshold was not exceeded, then the engine would restart the threshold breech count. This examples assumes that you have configured the indications and holes for the Resource Model to be 3 and 0, respectively.
Parameters
While thresholds must be numeric, parameters can be multiple numeric or alpha characters. You are able to customize your Resource Models by coding the parameters in ITM Workbench as defaults or they can be entered at profile definition time.
18
Dependencies
When using ITM Workbench, you can include any scripts, platform dependant binary libraries, such as Dynamic Link Libraries (DLL), or Java classes and packages that may be intrinsic to your Resource Model. Anything that is included this way is automatically installed on your endpoint when the profile is distributed.
1.5.2 Engine output

When you have a successful distribution of your profile, the engine will start running and providing information or output. It will take the form of events, data logging, and engine trace logs for debugging.
Events
The engine will provide two sorts of informational events. The alerting event and, when the metric has gone back within your defined thresholds, a clearing event. It is important to note that if you indicate, in your profile, that you wish to receive clearing events, then only one alerting event will be issued. Without clearing events, an alerting event will be issued each time your thresholds are exceeded.
Logging of metric data

The output data attributes obtained from the operating system on your endpoints by the Resource Model is able to be retained in a database on each endpoint. Windows NT systems must have the Microsoft Access 2000 Jet engine installed to utilize this feature. This Jet engine is available from Microsofts Web site as a download called MDAC. UNIX systems use an open source Java RDBMS. Any metrics that you wish to log for historical purposes must be predefined in your Resource Model by setting the appropriate fields. Logging is enabled in the profile before it is distributed to the endpoint. A maximum of 24 hours aggregated data is retained and is viewable by using the Health Console. If more data that this is needed, then ITM Data Warehouse would need to be installed.
Engine trace logs

As the engine carries out its monitoring work, you are able to set various levels of tracing using the following command:
wdmtrceng -e endpoint logfilelocation/name trace level size
where: endpoint is your endpoint name. logfilelocation/name is in the form of c:\yourdir\tmw2k.log.
19
trace level is from 0 to 3. size is the number of bytes to dedicate to log length. If you use log level 3, make sure that you make this a large number, as output is very verbose and the log may wrap around before you get your details.
1.5.3 Engine components

The ITM Engine is composed of the following: Scheduler Analyzer Event aggregator Event correlator Logger Action manager Provider layer Figure 1-9 demonstrates how the sub-components interact.
Analyzer
ITM5.1.1 Engine Components

Interpreter Decision Tree (VBA or JS)
Service Object (COM orJava)
Scheduler
TEC or TBSM
Event Aggregator
Correlator (Windows Only)
Action Manager
Logger
CIM Implementation
Providers - ILTs
Providers - ILTs
System Resources (CPU, Memory, Disks etc)
BackOffice Applications
Figure 1-9 Engine sub-components
20
Scheduler
Any profile, when distributed to endpoints, can be scheduled to run at specified times. As an example, an Administrator may only want a profile to run from Monday through Friday. Maintaining this would be the schedulers function. Any number and combination of rules can be employed. Note that the time zone utilized is always local to the endpoint. Additionally, the time that the event occurred is always the local time of the endpoint
Analyzer
The Resource Model contains parameters, thresholds, and metrics. It is the job of the analyzer to compare the measurements provided from WMI or CIM and decide what indications are to be referred to the event aggregator. A simple example of this would be the monitoring of disk space on an endpoint and with a set threshold of 80% capacity. The analyzer would compare the reading from the endpoint disk sub-system to your threshold and send this indication to the event aggregator.
Event aggregator
When an indication is received from the analyzer, it does not neccessarily mean that an alert event will be generated. The aggregator must calculate the persistence of the problem. The event aggregator collects all indications coming from all decision trees currently running, and consolidates them based on the aggregation rules that are configured in the profile. The aggregation rules are controlled by the occurrences and holes that are configured in the IBM Tivoli Monitoring profile. An occurrence is the term used to refer to a cycle during which an indication occurs for a given Resource Model (an above threshold cycle). A hole is the term used to refer to a cycle during which an indication does not occur (a below threshold cycle). If the persistence of an indication meets the configured number of occurrences, an event is generated and sent to the event correlator. If the profile is configured to send events to Tivoli Enterprise Console for a particular indication, then the event aggregator is responsible for sending the event to Tivoli Enterprise Console. However, all events generated by the event aggregator are sent to the event correlator, irrespective of whether it is configured to send events to Tivoli Enterprise Console. To better understand the concept of holes and occurrences please refer to Figure 1-10 on page 22. You will note in Figure 1-10 on page 22 that an event will be issued at the point on the graph called Indication #4. The indication count is not cleared by the hole
21
after Indication #1 as it is followed by Indication #2. Only two consecutive holes clears the indication count, and, in this case generates a clearing event.
In dica tion # 4 Indication #3
metric values
In dica tion # 1
Ind ication #2
threshold
.
}
C ycle Time
.
2 consecutive holes
C learing eve nt
tim e
Ma x # o f hole s is 1 and they are not co nse cutive
Figure 1-10 Graph of holes and occurrences
Event correlator
There will usually be more than one Resource Model running on an endpoint. They will produce many events. The correlator uses its set of static rules to perform a correlation between the events. An example of this would be the TMW_ProcessHoggingCPU event. This is composed of the two indications, TMW_ProcessHighCPU from the Process Resource Model and TMW_HighProcesses from the Processor Resource Model.
Logger
The logger is responsible for collecting performance data on the endpoint and storing the data locally. The logger handles multiple Resource Models that are distributed to an endpoint and that have been defined by Workbench to output logging. It also handles the way data is collected, that is, aggregated data (minimum, maximum, or average values) or raw data. The logger is also responsible for clearing the oldest records in the database. Nightly, around midnight, a data purging process is executed, which removes all data over 24 hours old. Though only 24 hours of data can be viewed, there are times when this database has almost 48 hours of data. This situation exists just prior to the midnight purging process. By default, logging is turned off. Windows NT systems must have the Microsoft Access 2000 Jet engine installed to utilize this feature. UNIX systems use an open source Java RDBMS.
22
Action manager
This component is responsible for executing corrective actions (tasks and built-in actions) when a Resource Model detects a problem. It executes the actions that the user has associated to a particular indication. There are a number of ways that the action manager executes the actions. Built-in actions are implemented as methods of Resource Models and they are executed through the WMI. Tivoli tasks are the classic Tivoli tasks that the user can associate with a particular indication through the IBM Tivoli Monitoring profile GUI. The action manager also generates an ActionResult or a TaskResult indication that is received by the Tivoli Enterprise Console adapter and then forwarded to the Tivoli Enterprise Console server.
Provider layer
The Provider layer is not a single component, but an implementation of a services layer that supports dynamically pluggable instrumentation. Such instrumentation is designed to provide performance data and or operable methods to a defined system resource. The Provider technologies are object-oriented in design and therefore represent only a specific resource. That is, a Provider may exist to supply performance statistics on the CPU of a host. In such a real-world example, such a Provider would instantiate each CPU as its own object. Due to the complex nature of the technologies behind the Provider layer, Chapter 4, Providers on page 109 has been written to clarify not only the terminology and technologies, but the physical implementations as well.
23
24
Chapter 2.
Workbench
The Workbench is an Integrated Development Environment (IDE) for developing and modifying Resource Models for Tivoli Monitoring. This chapter details the steps, using elementary examples, used to develop and modify resource modes. A thorough understanding of the IBM Tivoli Monitoring architecture is recommended before reading the following sections. Chapter 1, IBM Tivoli Monitoring architecture on page 3 provides a complete overview of the IBM Tivoli Monitoring architecture. The following topics are discussed in this chapter: Introduction Using Workbench Creating Resource Models Tools and extra information
25
2.1 Introduction
The Workbench is a development environment to create and modify Resource Models. It is a software component of IBM Tivoli Monitoring that can be installed as a stand-alone component on the Windows platform. Figure 2-1 briefly shows how the Workbench works.
Workbench PC
Workbench
TMR Server
Build
Package .tar
Register
copy
Package .tar BAROC .baroc
wdmrm command wrb command
ITM
Edit
Source File .dmws .dmjsws BAROC .baroc TEC
Figure 2-1 Introduction of the Workbench
The Workbench keeps all customizing in a source file: .dmws for VBA-based Resource Models and .dmjsws for JavaScript-based Resource Models. As the most important output the Workbench produces a package in the format of a tar file. This package file includes all information necessary for the registration of the Resource Model, which is copied over to the TMR Server where IBM Tivoli Monitoring is installed. Then you can add it to the environment by using the wrmadd command. The Workbench also generates a few outputs: the BAROC file, the message catalog file, the script file, and so on.
Note: Workbench is available through various methods. You can obtain it from the product CD-ROM or FixPack code. You can also obtain Workbench from the Tivoli Developers domain at the following URL:
http://www-3.ibm.com/software/tivoli/info/pa/monitor/index.jsp
We recommend you use the latest version of Workbench, because sample Resource Models are updated in the latest Workbench. In this redbook, we use the Workbench in the ITM5.1.1-Fixpack2 code, which has the latest sample Resource Models available.
26
2.2 Using Workbench

Before creating the Resource Models, a quick review of the basics of the Workbench might be helpful. We will begin by exploring one of the simpler Resource Models shipped with IBM Tivoli Monitoring: the PhysicalDiskModel.
2.2.1 The Workbench panes

The Workbench is made up of three panes, as shown in Figure 2-2.
Figure 2-2 Panes in the Workbench
The panes are: Pane 1 The first pane contains most of the Resource Model elements that make up a particular model. These elements are ordered in a tree-like hierarchy. The root node of the tree is the name of the Resource Model and describes the models general settings. In this case, it is the TMW_PhysicalDiskModel. In most cases, any element in the tree can be opened by double-clicking on it. Some elements in the tree have multiple options associated with them. A
Chapter 2. Workbench
27
Right-clicking the mouse button on any element in the tree will list the associated options for that element. For example, right-clicking on the TMW_PhysicalDisk element under Dynamic Model/CIM Classes will display three options: Modify, Remove, and Collection Test. We will be illustrating the use of many of these options in Part II. Pane 2 This pane contains the decision tree script, which is based on Java or Visual Basic script code. The functions in this code are used to initialize, set configuration options, and run the decision tree logic. Pane 3 This pane is only used for models that interact with the Windows platforms (that is, CIM/WMI-based). When debugging a Resource Model, you see an aggregated event message generated by your Resource Model here. This pane is useful when debugging a Resource Model and can be used to display the aggregate status of event indications.
2.2.2 Elements in Resource Models

Using Workbench, you can see various elements in Resource Models. All Resource Models are made up of seven basic elements, as described below: The Dynamic Model Events Thresholds Parameters Logging Dependencies Decision tree script In Chapter 3, Resource Models on page 67, we will describe the elements of Resource Models in greater detail.
2.2.3 Looking at the PhysicalDiskModel

In this section, we describe how you can view each elements by using the PhysicalDiskModel.
28
The properties of the PhysicalDiskModel

To view the properties of a Resource Model, double-click on the root node object. In this case, it is the TMW_PhysicalDisk object. You can see the display depicted in Figure 2-3.
Figure 2-3 TMW_PhsyicalDiskModel general settings
The following are descriptions of the properties:

Internal name
This is the internal name of the Resource Model. Changes to this setting will automatically update the SetDefaultConfiguration function Svc.SetModelName method call in the decision tree script. See Figure 2-5 on page 31 for an example of these settings in the SetDefaultConfiguration function. The internal name can be retrieved in the VisitTree function by calling the Svc.GetModelName method. The name is composed of alphabetic characters and must start with a letter. No blanks are allowed. This is the name that appears in the IBM Tivoli Monitoring Version 5.1.1 profile list of Resource Models. See Figure 2-4 on page 30 for an example of the Descriptive Name in the profile.
Descriptive name
29
Figure 2-4 Example of descriptive name in a profile
Description
This is the text that describes the Resource Model. This is used for documenting the Resource Model. These settings can be used to document the decision tree logic, as well as explain the threshold settings. This name is the internal name for grouping Resource Models on the profile category display. All Resource Models that have the same category internal name will be displayed under the same category option, as seen in Figure 2-5 on page 31. This is the name that is displayed in the profile category display. An example of this can be seen in the Category pull-down options in Figure 2-4.
Category internal name
Category descriptive name
30
Cycle time
This is the default cycle time for the Resource Model. This value can be changed in the profile before the profile distribution. This setting will change the Svc.SetCycleTime in the SetDefaultConfiguration function. See Figure 2-5 for the SetDefaultConfiguration function for the PhysicalDiskModel. This setting can also be retrieved in the VisitTree function using the Svc.GetCycleTime method.
' General info section '<<GENERAL_INFO>> Svc.SetModelName "TMW_PhysicalDiskModel" Svc.SetProfileName "411749921" Svc.SetCategory "Windows" Svc.SetCycleTime 120 '<<\GENERAL_INFO>>
Figure 2-5 PhysicalDiskModel general settings
Major and minor version Supported platforms
This is the internal version of the Resource Model. This is a list of the platforms that the Resource Model supports. The supported platforms are defined when the Resource Model is created.
The properties created or modified from the general settings dialog will automatically update the code in the SetDefaultConfiguration function, as seen in Figure 2-5.
The Dynamic Model element of the PhysicalDiskModel

The PhysicalDiskModel Resource Model uses only one resource class, the TMW_PhysicalDisk class. We can look further at this class by opening the CIM browser supplied with the Workbench. See Figure 2-6 on page 32 for an example of opening the CIM browser. To open up the CIM browser, we will select the TMW_PhysicalDisk resource class under the Dynamic Model/CIM classes hierarchy. When opening up the CIM browser from the Workbench, the first pop-up window is used to designate the CIM name space we want to open. For Windows CIM/WMI-based models, always use root/CIMV2. For UNIX/Linux-based Resource Models, you can use both root/CIMV2 and root/default. The next window displayed is a login window. This window always defaults to the signed-on user (just click OK).
31
Figure 2-6 Opening the CIM browser
The CIM browser now displays all of the properties of the PhysicalDisk resource class defined in the PhysicalDiskModel. See Figure 2-7 on page 33.
Note: The Workbench CIM browser does not automatically position the browser to the correct CIM class in the Classes window (the left pane), even though it displays all of the correct properties for the selected class. If another class is selected, all of the properties are erased from the selected properties window. It is important to cancel out of the browser in this scenario. However, if we are creating a new resource class, as will be demonstrated later, a new class will have to be selected.
32
Figure 2-7 PhysicalDisk resource class definitions
The following is an overview of property fields that make up the PhysicalDisk resource class settings:
Class properties
These are the attribute values (in CIM terminology, they are called properties) that are selected for processing. The SetDefaultConfiguration will have a Svc.DefineClass method call with all of the properties selected from this class. See Figure 2-1 on page 34 for the SetDefaultConfiguration function for the PhysicalDiskModel. The IBM Tivoli Monitoring analyzer will collect all of the properties that are in the selected list each cycle time. This is used to optionally set sort options for data that may need to be in sorted order. This is where optional filters can be placed on the collection process before the VisitTree function is called. For example, if we did not want to process any physical disks, where the PercentDiskTime property was less than 25 percent, we could add a WQL filter. The WHERE Clause field is passed to WMI as WQL code by the engine
Collection info Filtering
33
to filter data that is to be returned. For more information on WQL, see 2.4.2, Microsoft tools on page 63. The properties created or modified from the Dynamic Model element will automatically update the code in the SetDefaultConfiguration function, as seen in Example 2-1.
Example 2-1 PhysicalDiskModel Dynamic Model properties
' Dynamic Model section '<<DATA_INFO>> Svc.DefineClass "CIM", "TMW_PhysicalDisk", "ROOT\CIMV2:TMW_PhysicalDisk", "", "AvgDiskSecXfer,PercentDiskWriteTime,AvgDiskBytesXfer,DiskXfersSec,PercentDiskR eadTime,AvgDiskReadQLength,DiskReadBytesSec,DiskReadsSec,DiskBytesSec,CurrentDi skQLength,AvgDiskQLength,PercentDiskTime,AvgDiskWriteQLength,DiskWritesSec,Disk WriteBytesSec", "PhysicalDisk", "None", "", 0, 1 '<<\DATA_INFO>>
The event element of the PhysicalDiskModel

The PhysicalDiskModel has six event elements that are used by the decision tree, VisitTree, to send indications. These elements are defined in the Resource Model and define the event name along with all of the attributes of the event and the aggregation settings. Once the Resource Model is added to the Tivoli environment, the aggregation settings can be updated from a IBM Tivoli Monitoring profile, as seen in Figure 2-8 on page 35.
34
Figure 2-8 Profile indications
We will take a look at one of the event elements in this example. In the PhysicalDiskModel, the TMW_SlowPhysicalDrive indication is generated by the VisitTree function when the following property conditions are true: The CurrentDiskQLength property is greater than the threshold setting. The DiskBytesSec property is greater than the threshold setting. None of this logic can be found in the event element settings. This can only be derived from analyzing the VisitTree code, which we will be doing later in this chapter in Example 2-4 on page 42. The threshold values can be seen in the threshold elements discussed in the next section. The event element defines the properties that make up the event as well as the aggregation settings (holes and occurrences) that are used by the event aggregator. Figure 2-9 on page 36 is an example of the TMW_SlowPhysicalDrive event element in the Workbench.
35
Figure 2-9 TMW_SlowPhysicalDrive event element settings
The following is an overview of the TMW_SlowPhysicalDrive properties:

Internal name
This is the internal name used for this indication. This name will be defined in the SetDefaultConfiguration function with the Svc.DefineEvent method. See Example 2-2 on page 37 for the SetDefaultConfiguration function for the PhysicalDiskModel. The internal name is referenced in the VisitTree function by the SvcSendEvent and Svc.SendEventEx methods. The SendEvent and SendEventEx methods pass indications to the event aggregator to determine what action to take. The internal name is also used as a prefix to variables passed to shell scripts. For example, if a Perl script is invoked as a response from the TMW_SlowPhysicalDrive, one of the variables that would be set in the Perl script at run time would be TMW_SlowPhysicalDrive_PercentDiskTime. These are the attributes of the event. If the event aggregator generates a TEC or TBSM event (based on holes and occurrences), these are the properties that will be passed into the slots of the TEC event and attributes of the TBSM event. These attributes are set in the VisitTree code before the SendEvent or SendEventEx methods are invoked.
Attributes
36
Aggregation settings
This is where the aggregation keys are defined, along with the number of occurrences and holes for this indication.
Notification
These are the definitions for event notification. If the indication becomes an event based on the output of the event aggregator, these settings will be used to set the severity. These settings are used for the attributes of the event to be sent. The descriptive name is the display name. The message is used to set the message slot for TEC events and attributes for TBSM events. In this example the message text is as follows: The physical drive @PhysicalDisk@ is too slow. @PhysicalDisk@ will be replaced with the PhysicalDisk variable set in the VisitTree routine. The Actions button is used to define response actions for the event. CIM Methods and/or shell programs can be defined as response actions to the event element. If a response action is defined, it will run after event aggregation has determined that an event should be generated. For example, if TMW_SlowPhysicalDrive is set to three occurrences and zero holes and has a send_email.pl script defined as an action, then send_email.pl will run locally on the monitored machine after the third consecutive indication has occurred. Unlike compatibility mode scripts and scripts invoked by the Svc.Shell method, response actions do not have a time-out value.
String resources
Actions
The properties created or modified from the event element will automatically update the SetDefaultConfiguration function, as seen in Example 2-2.
Example 2-2 PhysicalDiskModel event element properties
' Event definition section '<<EVENTS_INFO>> Svc.DefineEvent "TMW_SlowPhysicalDrive", "CurrentDiskQLength,PercentDiskTime,AvgQLength,AvgReadQLength,AvgWriteQLength,D iskReadBytesSec,DiskWriteBytesSec", "PhysicalDisk" '<<\EVENTS_INFO>>
37
The threshold element of the PhysicalDiskModel

The PhysicalDiskModel has three threshold elements that are used by the decision tree logic (that is, VisitTree) to determine if an indication should be sent. These elements are defined in the Resource Model and become part of the Resource Model tar file. Once they are added to the Tivoli environment they can be updated from an IBM Tivoli Monitoring profile, as seen in Figure 2-10.
Figure 2-10 PhysicalDiskModel thresholds in a profile
Figure 2-11 on page 39 is an example of the TMW_HighPercentUsage threshold element in the Workbench.
38
Figure 2-11 PhysicalDiskModel HighPercentUsage threshold profile display
The following is an overview of the HighPercentUsage properties:

Internal name
This is the internal name that is used by the VisitTree function to determine if a property has exceeded a threshold value. In the VisitTree function, the Svc.GetThreshold method is invoked to retrieve and compare this value. The threshold is defined in the SetDefaultConfiguration function by the Svc.DefineThreshold method. Remember the SetDefaultConfiguration definitions are updated automatically by the Workbench when we update the element in the elements pane (that is, pane 1). This is the default value associated with the internal name. The HighQLength is 3 by default. This is the name that is used for the IBM Tivoli Monitoring profile display, as seen in Figure 2-10 on page 38. This is used for documentation purposes.
Default value Descriptive name Description
The properties created or modified from the threshold element will automatically update the SetDefaultConfiguration function, as seen in Example 2-3.
Example 2-3 PhysicalDiskModel threshold element properties
' Thresholds section '<<THRESHOLDS_INFO>> Svc.DefineThreshold "HighBytesSec", 1572864.000000 Svc.DefineThreshold "HighQLength", 3.000000 Svc.DefineThreshold "HighPercentUsage", 90.000000 '<<\THRESHOLDS_INFO>>
39
The logging element of the PhysicalDiskModel

The PhysicalDiskModel has three logging elements that are used by the decision tree logic (that is, VisitTree) to determine if an indication should be logged. Once they are added to the Tivoli environment, they can be updated from an IBM Tivoli Monitoring Version 5.1.1 profile, as seen in Figure 2-12.
Figure 2-12 PhysicalDiskModel logging element profile display
Figure 2-13 on page 41 is an example of the percent disk usage logging element in the Workbench.
40
Figure 2-13 PhysicalDiskModel percent disk usage element profile display
The following is an overview of the HighPercentUsage properties:

Context
This is the name that is passed as the first parameter of the Svc.LogInst or Svc.LogInstEx methods. This name is also the display name in the IBM Tivoli Monitoring Web Health Console. This is the name that is used as the second argument of the Svc.LogInst and Svc.LogInstEx methods. This name is also what is displayed in the IBM Tivoli Monitoring Web Health Console historical data. These are the properties that are to be logged under this this context/resource. The PhysicalDiskModel HighPercentUsage logging element has a key of PhysicalDisk. This can be seen in the graph in the Web Health Console.
Resource
Properties
The decision tree script of the PhysicalDiskModel

As we have seen thus far, the PhysicalDiskModel is made up of four key components: Dynamic Model elements, event elements, threshold elements, and logging elements. We have been focusing on three specific elements: The TMW_SlowPhysicalDrive event element The HighQueueLength threshold element
41
The Percent Disk Usage_PhysicalDisk logging element It is the PhysicalDiskModel decision tree script code that ties these three elements together. The PhysicalDiskModel Decision Tree script is a Visual Basic script based model that uses Microsofts WMI to retrieve CIM data. WMI is Microsofts implementation of the CIM architecture on Windows machines. The VisitTree in the PhysicalDiskModel really only does three things: 1. It evaluates thresholds. 2. It generates indications. 3. It logs data. So, let us first look at how the TMW_SlowPhysicalDrive indication gets sent to the event aggregator.
Note: Remember the event aggregator is not in the decision tree code. It is part of the IBM Tivoli Monitoring engine.
The PhysicalDiskModel collects data from the WMI Performance Monitoring Provider (PerfProv). Most of the Windows-based Resource Models collect data from PerfProv as well. In the Dynamic Model element of the PhysicalDiskModel, all of the properties that are defined will be collected each cycle time before the VisitTree function is called. The TMW_SlowPhysicalDrive indication gets generated from the VisitTree function when the CurrentDiskQLength and the DiskBytesSec exceed their threshold values. The Percent Disk Usage_PhysicalDisk logging element gets processed on every cycle regardless of whether the threshold is met or not. We can follow the code for TMW_SlowPysicalDrive and the logging elements in Example 2-4. This code is an example of the PhysicalDiskModel code and has been modified for the purposes of this discussion.
Example 2-4 PhysicalDiskModel example VisitTree
1 2 3 4 5 6 7 8 9 10 11 12 Public Function VisitTree(Svc As Object) As Long Dim numAvgQLength As Long, numCurrentDiskQLength As Long, numAvgReadQLength As Long Dim numAvgWriteQLength As Long, bytDiskReadBytesSec As Long, bytDiskWriteBytesSec As Long Dim numDiskReadsSec As Long, numDiskWritesSec As Long, numDiskXfersSec As Long Dim numDiskBytesSec As Long, numPercentDiskTime As Long, numPercentDiskReadTime As Long Dim numPercentDiskWriteTime As Long, numTotalDisks As Long, flagHighPhysicalQLength As Long Dim flagHighPhysicalXferRate As Long, flagHighPhysicalReadRate As Long, flagHighPhysicalWriteRate As Long Dim flagHighPhysicalPercentTime As Long, i As Long Dim strPhysicalDisk As String i = 0
42
13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 39 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61
numTotalDisks = Svc.GETNUMOFINST(TMW_PhysicalDisk) Do While i < numTotalDisks flagHighPhysicalQLength = 0 flagHighPhysicalXferRate = 0 flagHighPhysicalReadRate = 0 flagHighPhysicalWriteRate = 0 flagHighPhysicalPercentTime = 0 strPhysicalDisk = Svc.GetStrProperty(TMW_PhysicalDisk, i, PhysicalDisk) If strPhysicalDisk <> _Total Then strPhysicalDisk = Mid$(strPhysicalDisk, 1, 1) bytDiskReadBytesSec = Svc.GetNumProperty(TMW_PhysicalDisk, i, DiskReadBytesSec) bytDiskWriteBytesSec = Svc.GetNumProperty(TMW_PhysicalDisk, i, DiskWriteBytesSec) numDiskReadsSec = Svc.GetNumProperty(TMW_PhysicalDisk, i, DiskReadsSec) numDiskWritesSec = Svc.GetNumProperty(TMW_PhysicalDisk, i, DiskWritesSec) numCurrentDiskQLength = Svc.GetNumProperty(TMW_PhysicalDisk, i, CurrentDiskQLength) numAvgQLength = Svc.GetNumProperty(TMW_PhysicalDisk, i, AvgDiskQLength) numAvgReadQLength = Svc.GetNumProperty(TMW_PhysicalDisk, i, AvgDiskReadQLength) numAvgWriteQLength = Svc.GetNumProperty(TMW_PhysicalDisk, i, AvgDiskWriteQLength) numDiskBytesSec = Svc.GetNumProperty(TMW_PhysicalDisk, i, DiskBytesSec) bytDiskReadBytesSec = Svc.GetNumProperty(TMW_PhysicalDisk, i, DiskReadBytesSec) bytDiskWriteBytesSec = Svc.GetNumProperty(TMW_PhysicalDisk, i, DiskWriteBytesSec) numPercentDiskTime = Svc.GetNumProperty(TMW_PhysicalDisk, i, PercentDiskTime) numPercentDiskReadTime = Svc.GetNumProperty(TMW_PhysicalDisk, i, PercentDiskReadTime) numPercentDiskWriteTime = Svc.GetNumProperty(TMW_PhysicalDisk, i, PercentDiskWriteTime) 'Log instance data stuff Svc.LogInst Percent Disk Usage, PhysicalDisk, numPercentDiskReadTime, strPhysicalDisk Svc.LogInst Bytes Transferred, PhysicalDisk, numDiskBytesSec, strPhysicalDisk Svc.LogInst Queue Length, PhysicalDisk, numAvgQLength, strPhysicalDisk If numCurrentDiskQLength > Svc.GetThreshold(HighQLength) Then flagHighPhysicalQLength = 1 End If If numDiskBytesSec > Svc.GetThreshold(HighBytesSec) Then flagHighPhysicalXferRate = 1 End If
43
62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92
If bytDiskReadBytesSec > Svc.GetThreshold(HighBytesSec) Then flagHighPhysicalReadRate = 1 End If If bytDiskWriteBytesSec > Svc.GetThreshold(HighBytesSec) Then flagHighPhysicalWriteRate = 1 End If If numPercentDiskTime > Svc.GetThreshold(HighPercentUsage) Then flagHighPhysicalPercentTime = 1 End If If flagHighPhysicalQLength = 1 Then If flagHighPhysicalXferRate = 1 Then Svc.SENDEVENT TMW_SlowPhysicalDrive, _ numCurrentDiskQLength, _ numPercentDiskTime, _ numAvgQLength, _ numAvgReadQLength, _ numAvgWriteQLength, _ bytDiskReadBytesSec, _ bytDiskWriteBytesSec, _ strPhysicalDisk Else Some code deleted i = i + 1 Loop VisitTree = 0 End Function
Tip: A thread exists for each Resource Model running on the engine. Each thread runs a simplified pseudo code loop:
While (Engine Running) { CollectCIMData(); Call VisitTree(); Sleep(cycle time); }
Let us examine the code in Example 2-4 on page 42: Line 1 This is the VisitTree function definition.
44
Line 210 These lines are the variable definitions. The variables that we are concerned with for TMW_SlowPyhsicalDrive are numCurrentQLength, numDiskBytesSec, and numPercentDiskTime. Line 14 This is the method call that returns the number of instances that have been collected by the IBM Tivoli Monitoring Version 5.1.1 engine. In our environment, there were two physical disks on our W2K machine. However, the Svc.GETNUMOFINST returned three instances (disk0, disk1, and _Total). Some of the Perfmon-provided properties will return a _Total instance where it is appropriate. In line 25, we will skip this instance. Line 23 When the VisitTree function is called, all of the data that was collected by the IBM Tivoli Monitoring Version 5.1.1 analyzer is available to the VisitTree function via method calls. Individual properties can be retrieved using the Svc.GetStrProperty or the Svc.GetNumPropery methods as seen in lines 2645. In this example we are retrieving the physical disk name on each instance (that is, disk0, disk1, and _Total). Line 25 In the shipped PhysicalDiskModel, code _Total instances is discarded. A customized model could make use of this instance. _Total is the total of all instances. Line 27 This is a call to the Svc.GetNumProperty method to retrieve the DiskReadBytesSec property. Line 32 This is a call to the Svc.GetNumProperty method to retrieve the CurrentDiskQLength. Line 42 This is a call to the Svc.GetNumProperty method to retrieve the PercentDiskTime. Line 4852 These lines are unconditional calls to the Svc.LogInst methods for the three logging elements defined in Figure 2-12 on page 40.
45
Line 5456 This code checks the CurrentQLength value retrieved from CIM/WMI against the static threshold definition defined in the SetDefaultConfiguration function and sets a flag. The Svc.GetThreshold method returns values stored by the Svc.DefineThreshold in the SetDefaultConfiguration function. See Example 2-3 on page 39. Line 5860 This code checks the DiskBytesSec value retrieved from CIM/WMI against the static threshold definition defined in the SetDefaultConfiguration function and sets a flag. The Svc.GetThreshold method returns values stored by the Svc.DefineThreshold in the SetDefaultConfiguration function. See Example 2-3 on page 39. Line 7484 If the HighPhysicalQLength and HighPhysicalXfreRate flags are set, then the Svc.SENDEVENT method is invoked, passing all the TMW_PhysicalDisk class properties retrieved in lines 2746. Line 8990 This line increments and loops back to get the next instance. LIne 9192 Return back to the IBM Tivoli Monitoring Version 5.1.1 engine.
2.3 Creating Resource Models

The Workbench provides two methods to create Resource Models: Creating Resource Models using the wizard. Cloning existing Resource Models. We briefly explain how to use these methods in the subsequent sections.
2.3.1 Creating Resource Models using the wizard

Using the wizard, you can create Resource Models in various ways. In this section, we will show you a typical way to create a Resource Model by the Resource Model wizard. Let us begin by clicking on the New icon in the left side of the Workbench toolbar, as shown in Figure 2-14 on page 47.
46
Figure 2-14 Creating a Resource Model
1. Select JavaScript or Visual Basic, as shown in Figure 2-15.
Figure 2-15 Selecting JavaScript or Visual Basic
You can create your Resource Models using either JavaScript or Visual Basic. The difference between JavaScript and Visual basic is described in 3.1.3, Types of Resource Models on page 75. Deciding which scripting language to use depends on the following factors: The Resource Model on UNIX supports only JavaScript, as shown in Table 2-1. If you are going to use the Resource Model on UNIX as well as Windows, the choice is easy: you have to select JavaScript.
Table 2-1 Supported Resource Model type per operating system
Resource Model Windows UNIX
JavaScript Visual Basic
X X
X N/A
47
If you will use the Resource Model only on Windows, the choice depends on your expertise level in both languages. If you are more experienced in Visual Basic, then use that language. On the other hand, if you are only experienced in JavaScript, you can use it. If you will use the Resource Model only on Windows and are experienced in both languages, choose Visual Basic, since it is more tightly integrated with Windows and provides extra capabilities, such as debugging the Resource Model. As a second reason, JavaScript Resource Models on Windows requires additional installation of Microsoft Windows Script Host 5.6.
Note: The Workbench implements the Sax interpreter, which differs slightly from other Visual Basic interpreters. See http://www.saxsoft.com/Basic/Details for more information. On the other hand, JavaScript Workbench uses Rhino. Rhino is an open-source implementation of JavaScript written entirely in Java.
2. Selecting the wizard (see Figure 2-16).
Figure 2-16 Selecting the wizard
There are three different ways to create a Resource Model with the Workbench:
Resource Model wizard The Resource Model wizard provides a series of dialog boxes that guide us through the whole process of creating a simplified Resource Model without writing scripts or code. Step-by-step Resource Model This approach provides dialog boxes that guide us
48
through the procedure in the order defined in the IBM Tivoli Monitoring Users Guide Version 5.1.1, SH19-4569. However, when we have completed this procedure, we must write the script that governs the Resource Model.
Empty Resource Model Using this approach, we can define the Resource Model elements without following a specific order.
In our experience it is always better to start out using the Resource Model wizard to generate the template for the Resource Model, unless we are cloning a Resource Model. The Resource Model wizard generates a good structure for the VisitTree function. If Resource Models are developed using the Resource Model wizard, this will force a level of conformity. In this procedure, we select the Resource Model Wizard in this window in order to explain the major procedures of creating a new Resource Model. 3. Selecting the data source. The next window prompts you to select the type of data source, as shown in Figure 2-17 on page 50.
49
Figure 2-17 Selecting the data source
The data source types are as follows:

CIM/WMI
This tells the wizard whether this model will be a CIM-based Resource Model or a compatibility mode model.
DM Classic Edition Collection This tells the wizard that we are creating a compatibility mode Resource Model and that we will be migrating a MCSL or CSL based collection into this Resource Model. Custom script
This tells the wizard that we are creating a Resource Model based on a custom numeric or string monitor. For more information on this, see Chapter 10, Creating a custom script Resource Model on page 411.
50
If you selected JavaScript, you can also select the supported platform for the Resource Model. If you selected VBA, the selected platform is fixed to w32ix86. This is because VBA Resource Model runs on only Windows platform. 4. Selecting a class. The first window after we selected the Resource Model wizard selection asks us to sign on to the CIM browser (Figure 2-18).
Figure 2-18 Connecting to namespace
The next window shows all of the compiled resource classes in the root/CIMV2 name space (Figure 2-19 on page 52). You can choose a CIM/WMI class to be monitored by Resource Model.
51
Figure 2-19 Selecting a CIM class
5. Selecting the properties. The next window shows you properties in the CIM class (Figure 2-20 on page 53). The Available area displays a set of properties that the CIM Class possesses. If you choose a property and click the -> button in the center of the window, the selected property appears on the Selected area. Then you can use properties on the Selected area in further steps.
52
Figure 2-20 Selecting properties
6. Filtering In the next window, you can set filtering conditions to limit the data collection by using the WQL language (Figure 2-21 on page 54). WQL is an abbreviation of WMI Query Language. WQL is a kind of dialect of SQL to query WMI. In using WQL, you can use a similar syntax with SQL. For more information, see the WMI SDK on the Microsoft Web site at:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/wmisdk/wmi /wmi_start_page.asp
53
Figure 2-21 Filtering
7. Specifying the event trigger condition In the next window, you can specify the trigger condition for a TEC or TBSM event (Figure 2-22 on page 55). Select properties and click the -> button to enter the trigger condition. If you specify a trigger condition here, the definitions of Event and Threshold are automatically created.
54
Figure 2-22 Specifying the event trigger condition
Note: You can specify only one trigger condition for each property in this window. If you wants to add multiple trigger conditions for one property, you have to modify the Resource Model, including the decision tree script after completing the wizard. If you would like to learn more about implementing multiple trigger conditions (this means thresholds as well) for one property, see Chapter 10, Creating a custom script Resource Model on page 411.
Depending on the type of property, the next window shows different options for trigger conditions (Figure 2-23 on page 56). If you select numeric property, the options become mathematical and use comparison operators such as <, >, and so on. If you select string property, the trigger condition becomes string matches, such as Is not equal, Contain, and so on.
55
Figure 2-23 Entering the trigger condition
Note: These values, except for the condition option (<, is equal to, and so on) can be changed when you distribute the profile. Keep in mind you cannot change the condition option on the Tivoli Desktop.
These conditions are automatically reflected in the decision tree script shown in Example 2-5.
Example 2-5 Decision tree script
' Thresholds section '<<THRESHOLDS_INFO>> Svc.DefineThreshold "Thr_Avail_le", 10000.000000 '<<\THRESHOLDS_INFO>> ##### omission ##### ' Event definition section '<<EVENTS_INFO>> Svc.DefineEvent "Ev_TMW_Memory_Avail_is_equal_or_too_low", "Avail,LowerBound", "__RELPATH" '<<\EVENTS_INFO>>
##### omission #####
56
If (curAvail <= Svc.GetThreshold("Thr_Avail_le") ) Then Svc.SetMapNumElement(hPropTable,"LowerBound",Svc.GetThreshold("Thr_Avail_le")) Svc.SendEventEx "Ev_TMW_Memory_Avail_is_equal_or_too_low", hPropTable End If
8. Logging In the next window, you can select properties to be logged (Figure 2-24). If you select properties, these properties will be logged by the ITM Engine. The logged data will be used in reporting functions, such as the Web Health Console or Tivoli Data Warehouse.
Figure 2-24 Selecting the properties to log
9. Cycle time The last window of the Resource Model wizard prompts you to input cycle time in seconds (Figure 2-25 on page 58). You can set the default cycle time for your Resource Model. Remember that you will be able to change the cycle time when distributing a profile to an endpoint.
57
Figure 2-25 Cycle time
10.Saving the source file Finally, the wizard will end, and you should save the source file before proceeding to the next step (Figure 2-26). You can save the source file by clicking File Save As.
Figure 2-26 Saving the source file
Note: The dmws files are the Resource Model developed in Visual Basic Script. The Resource Models developed in JavaScript have the file extension of dmjsws.
11.Building the package You need to build the package to register your Resource Model into ITM. To build the package, select Build Build Package (Figure 2-27 on page 59).
58
Then you can build a tar file which includes various definition files constructing your Resource Model.
Figure 2-27 Building the package
As described in 3.1.2, Physical components on page 73, each tar file consists of various files: configuration file, decision tree script file and Dependency files. 12.Building the TEC BAROC If you intend to send events to a TEC server, you need to build TEC BAROC files and import them into a TEC rulebase. To build the BAROC files, select Build Build TEC BAROC (Figure 2-28 on page 60). Then you can build a TEC BAROC file that reflects the definition of Event in your Resource Model.
59
Figure 2-28 Building the TEC BAROC file
Note: The TEC classes in your TEC BAROC file inherits Tmw2k.baroc, which is provided by IBM Tivoli Monitoring Version 5.1.1. Therefore you need to import Tmw2k.baroc before importing the TEC BAROC file you created. For more information about TEC configurations, see The IBM Tivoli Monitoring Workbench Users Guide Version 5.1.1, SH19-4571.
2.3.2 Cloning existing Resource Models

In spite of creating new Resource Models, if you already have a Resource Model, you can clone it and create a new Resource Model. IBM Tivoli Monitoring Version 5.1.1 and IBM Tivoli Monitoring family of products principally provide sample Resource Models that you can modify using Workbench. You can clone those sample Resource Models to create new ones more suitable for your environment.
60
1. Opening a Resource Model To clone a Resource Model, open the existing Resource Model by selecting File Open. 2. Modifying Resource Model elements You need to modify some elements in the Resource Model. How you modify the Resource Model depends on how you want the Resource Model to behave. However, to create another Resource Model from an original one, you must change at least all of the following elements to avoid an internal name conflict: Properties Events Thresholds
2.3.3 Registering a Resource Model into ITM

You will need to register your Resource Model before you can use it with IBM Tivoli Monitoring Version 5.1.1. 1. Copying the package file To register your Resource Model into IBM Tivoli Monitoring Version 5.1.1, copy the tar package file to the TMR Server using your choice of remote copy tools, such as FTP. Use the binary mode for FTP to copy the tar package file.
Workbench PC
Binary tar file
TMR Server
Figure 2-29 Copying the package file
2. Registering the Resource Model After copying the package file to your TMR server, you can register it into IBM Tivoli Monitoring Version 5.1.1. To register the package file, use the wdmrm command, as shown in Example 2-6 on page 62.
61
Example 2-6 Registering the Resource Model

wdmrm -add YourRMFileName.tar
2.4 Tools and extra information

This section will provide useful information about various tools and techniques that will help you be successful with Resource Models.
2.4.1 WorkBench command line interface

IBM Tivoli Monitoring Version 5.1.1 Workbench provides a very simple CLI to use some of its functions from command prompts. This basically helps in automating Resource Model package builds from the source workspaces, and to modify some of its components without running the GUI-based tool. Before we start using the Workbench CLI, we might want to add the Workbench bin directory into the path. The command usage is:
wdmwbcli wdmwbcli wdmwbcli wdmwbcli wdmwbcli wdmwbcli wdmwbcli resmodworkspace resmodworkspace resmodworkspace resmodworkspace resmodworkspace resmodworkspace resmodworkspace -bldpkg outputPackage -expmsgcat messagecatalog -expjmsgcat javamessagecatalog -bldtecbaroc tecbaroc -setdep interp depfile [outputworkspace] -setdectree dectreefile [outputworkspace] -setver major minor [outputworkspace]
Where:
resmodworkspace outputPackage messagecatalog
The *.dmws of the dmjsws project file The output tar file The output message catalog The output TEC BAROC file The dependency interpreter type The dependency file name associated with the interpreter type The name of the output *.dmws or *.dmjsws project file The decision tree file The Resource Model major version number
javamessagecatalog The output Java message catalog tecbaroc interp depfile outputworkspace dectreefile major
62
minor
The Resource Model minor version number
The command usage is:

wdmwbcli resmodworkspace -bldpkg outputPackage
Builds the Resource Model tar from the source workspace.

wdmwbcli resmodworkspace -expmsgcat messagecatalog
Exports the Resource Model message catalog.

wdmwbcli resmodworkspace -expjmsgcat javamessagecatalog
Exports the Resource Model Java message catalog to use with Web Health Console.
wdmwbcli resmodworkspace -bldtecbaroc tecbaroc
Exports the TEC BAROC file with the definitions of all the events generated by the source Resource Model.
wdmwbcli resmodworkspace -setdep interp depfile [outputworkspace]
Adds the specified depfile as a Resource Model dynamic dependency for the given interp (use all to add the file for all the available interps).
wdmwbcli resmodworkspace -setdectree dectreefile [outputworkspace]
Sets the JavaScript or Visual Basic Code to the specified Resource Model. JavaScript files can only be set to .dmwjsws workspaces, while Visual Basic files can only be set to .dmws.
wdmwbcli resmodworkspace -setver major minor [outputworkspace]
Changes the version of the specified Resource Model. Examples:

wdmwbcli ITSO_FileSystem.dmjsws -bldpkg ITSO_FileSystem.tar wdmwbcli ITSO_FileSystem.dmjsws -expmsgcat ITSO_FileSystem.msg
2.4.2 Microsoft tools

The Microsoft tools are discussed in the following sections.
WMI SDK
See:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/wmisdk/wmi/wmi _start_page.asp
63
WMI Providers
See:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/wmisdk/wmi/man aged_objects_and_providers.asp
Windows NT and 2000 Resource Kit

Two tools that are very effective for creating artificial load balances on a Windows 2000 endpoint are cpustres.exe and probe.exe. In the PhysicalDisk and LogicalDisk examples, we used the diskmax.bat command. This is a command that has been customized to use the probe.exe tool. Appendix B, Additional material on page 495 has instructions on how to download files from the Web. There is a diskmax.zip file at that site and it has all of the diskmax files that were used in the examples.
Microsoft script debugger

See:
http://msdn.microsoft.com/downloads/default.asp?url=/downloads/topic.asp?URL=/M SDN-FILES/028/001/175/topic.xml
How to use the Microsoft script debugger:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/sdbug/Html/sdb ug_17.asp
2.4.3 Saxsoft
The Workbench implements the Sax interpreter, which differs slightly from other Visual Basic interpreters. The following is the Saxsoft Web site:
http://www.saxsoft.com
2.4.4 Rhino
JavaScript Workbench uses Rhino. Rhino is an open-source implementation of JavaScript written entirely in Java. The following are Rhino Web sites:
http://www.mozilla.org/rhino/ http://www.mozilla.org/rhino/download.html
The Rhino shell allows us to run scripts from files or interactively at a command line.
Rhino shell
Download the zip file for rhino. The zip file will contain a single JAR file, js.jar. We then need to add the JAR file to the class path.
64
We can start the Rhino shell using the following command:

java org.mozilla.javascript.tools.shell.Main
We can execute a JavaScript by passing the file as an argument:

java org.mozilla.javascript.tools.shell.Main test.js
There are many options for running scripts. See the associated documentation for more details.
Rhino debugger
The Mozilla Rhino JavaScript shell includes a debugger. The debugger runs as a Java program:
java org.mozilla.javascript.tools.debugger.Main
The options are the same as the shell. For more information see:
http://www.mozilla.org/rhino/debugger.html
65
66
Chapter 3.
Resource Models
The Resource Model is the key concept of the IBM Tivoli Monitoring Version 5.1.1 product. Resource Models are used to model a business-relevant object, such as the CPU of a machine or the memory of a machine. In order to configure the various components of the IBM Tivoli Monitoring Version 5.1.1 profile, it is important to have a basic understanding of components of the Resource Model. This chapter provides details on what Resource Models are. The following topics are discussed in this chapter: Resource Model overview Resource Models
67
3.1 Resource Model overview

In order to properly utilize the Resource Model architecture implemented by IBM Tivoli Monitoring Version 5.1.1, it is important to have a solid understanding of the components, terminology, and design behind this architecture. Understanding the internals will also make it easier to understand the impact of changing the out-of-the-box parameters of the IBM Tivoli Monitoring Version 5.1.1 profile. The following sections will describe components included in the Resource Model from the logical and physical point of view.
3.1.1 Logical components

The Resource Model can be considered a combination package of monitoring criteria and monitoring conditions. It contains not only monitoring target information but also the trigger conditions, events, and actions based on the so called best practice. The ITM Engine executes multiple Resource Models distributed by the Tivoli Desktop. The Resource Model retrieves the management information through various interfaces, including CIM/WMI, and then analyzes that information. The variety of the management interface is one of the advantages of IBM Tivoli Monitoring. We generically name such management interfaces as the Provider, which will be well described in Chapter 4, Providers on page 109. The Resource Model has various logical components that are closely related to each other, as shown in Figure 3-1 on page 69. In this section, we briefly cover the major logical components that are characteristics of a Resource Model.
68
Managed Server
ITM Engine Resource Model

Threshold Threshold Threshold Indication Occurrence / Hole Cycle Time Parameters Indication Occurrence / Hole
Distributing Profiles
Tivoli Desktop
Send Events
TEC / TBSM
Workbench
Defining Resource Model - Dynamic Model - Decision Tree Script - Events / Thresholds - Parameters - Logging - Cycle Time - Dependency Custom Scripts DM Classic Monitor Probes
Interface
WMI (CIMOM) WMI Provider DLLs
TSL (CIMOM) ILT
Operating System & Application Resources
Figure 3-1 Logical components of the Resource Model
A Resource Model contains the following major elements: Dynamic Models Events (one or more) Thresholds (one or more) Parameters (one or more) Logging A decision tree script Dependencies
Dynamic Models
The Dynamic Model can be considered the essential element of a Resource Model. Except for the custom script Resource Model, each Resource Model
Chapter 3. Resource Models
69
contains one Dynamic Model, where you specify the resources you are going to monitor, the properties of each resource you are going to consider, and the type of data collection you will implement. A Dynamic Model contains a set of predefined Common Information Model (CIM) classes that describe the status of each resource. A class is a list of properties relevant to the specified resource. The Workbench shows the list of available CIM classes contained in the CIM repository of WMI on your local machine. The instances of the classes are provided by WMI Providers. If the resource you need is not described by any class contained in the CIM repository, you can add it, together with its associated Provider.
Thresholds
Each Resource Model defines one or more thresholds. The threshold value that you specify in the Workbench dialog boxes becomes the default for that particular Resource Model. However, it can be changed before distribution from the tmw2k profile definition dialog boxes. Typically, this value represents a limit for a satisfactory resource state. If the monitored resource exceeds this limit, an indication is generated. However, in the Workbench, thresholds can also represent any other numeric criteria on which your data collection is based. These thresholds will be used to filter the indications, thus allowing the Monitoring Engine to skip processing (or ignore) indications that are out-of-scope. A threshold is a numeric value that you specify and that is used according to the monitoring algorithm you write in the script.
Events
An event is a change in the status of a resource. Within IBM Tivoli Monitoring Version 5.1.1, an event notifies you that a specified resource state is abnormal or problematic. In the Workbench, a distinction is made between an indication and an event. An indication is generated when the state of a given resource meets specific criteria you have defined. However, an indication does not trigger any action; only when indications are aggregated do they become an event. The cycles during which the indication is generated are called occurrences. On the other hand, the cycles during which no indication is generated are called holes. Only events can trigger some actions, notify that there is a problem in your resource state and, if enabled, send notification to the Tivoli Enterprise Console server and Tivoli Business Systems Manager.
70
Assume that there is a resource property that changes its value rapidly. The decision tree would be visited every cycle, and as part of this, the value of the resource property is retrieved. In Figure 3-2, the vertical dashed lines represent the moments of the queries, and the point at which the dotted lines meet the graph are values that are the results of the inquiries. The one horizontal dashed line represents the threshold. Values above that line are considered potential problems and will trigger an indication. Every time the values of the resource properties exceed the thresholds, the Resource Model will generate an indication. If the value of the resource property drops below the threshold for a particular cycle, then no indication is generated, and the event aggregator counts the non-occurrence of an indication as a hole. So, if we define an event as four occurrences and one hole when we configure our profile, then based on the indications generated in Figure 3-2, the event will be generated when the fourth indication occurs. If we had two consecutive holes, then the occurrence count would be reset to zero and a clearing event would be sent if it was configured to send a clearing event.
Tip: The concept of holes can be a bit confusing if you do not realize that the number of holes specified in your profile represent the acceptable number of consecutive holes, not the accumulated number of holes over a sliding window of time.
In dica tion # 4 Indication #3
metric values
In dica tion # 1
Ind ication #2
threshold
.
}
C ycle Time
.
2 consecutive holes
C learing eve nt
tim e
Ma x # o f hole s is 1 and they are not co nse cutive
Figure 3-2 Sampling of volatile metric
71
Parameters
While thresholds can be only numeric values, parameters can be lists of numbers or strings. Using parameters enables you to customize your Resource Model. You can define different parameters as required. The list of numbers or strings you specify for each parameter can represent the instances you want to monitor, or a limit you do not want your resource to exceed, depending on how you use this setting in your script. Within the Workbench, you can define default values for the different parameters, and these values are customizable in tmw2k profile definition dialog boxes.
Logging
The logging functions allows you to store data regarding the attributes of the resource you want to monitor. Data is stored in a local database and can be accessed using Health Console. Within the Workbench, you can specify what and how you want to log. However, logging is disabled by default.
Decision tree script

The decision tree script contains the algorithm that you write in VisualBasic or JavaScript to govern the whole monitoring process. The Workbench automatically generates either the VisualBasic or the JavaScript decision tree script part, which contains the information you have specified when you have created and configured the Resource Model. If you change one of the settings in the Workbench dialog boxes, the corresponding data is also automatically updated in the script. You cannot modify these settings directly in the script. The script has a default structure that is common to all the Resource Models. By default, the decision tree script contains three basic functions and one subroutine, but you can add some more to them. The default functions are the following: Main This is a subroutine used by Workbench (or any other Visual Basic IDE) for debugging the Resource Model. The Monitoring Engine does not call it. This subroutine performs the following functions: Creates the TMWService.Utils Calls the SetDefaultConfiguration function Calls the Init function Enters the monitoring loop (collect data, visit the decision tree script, and wait cycle time)
72
This subroutine should not be modified. If you do, unpredictable results may occur. SetDefaultConfiguration The SetDefaultConfiguration initializes the object on the basis of the settings defined in the events, thresholds, and parameters dialog boxes. If you change one of the settings contained in these dialog boxes, the corresponding data is updated in this function. On the contrary, you cannot change those settings by modifying them directly in this function. The SetDefaultConfiguration function is called just once, when the Resource Model is started. Therefore, if necessary, you can write additional initialization code at the end of this function. Init Init is called after the settings defined in the SetDefaultConfiguration function have been replaced with the values coming from the profiles of Tivoli Distributed Monitoring Workbench Version 4.1. At this point, the settings are replaced with the new ones. VisitTree VisitTree contains the monitoring algorithm and is called at the beginning of each cycle time. You have to write the monitoring algorithm in VisualBasic or JavaScript, defining how to use all the values and variables previously set. This function checks the algorithm and implements it. It processes the collected data according to thresholds and parameters settings, and, if necessary, sends an event.
Dependencies
Sometimes, to run a Resource Model on an endpoint, you may need to ensure that all the prerequisite files for successful execution are available at the endpoint that is monitored. For example, when you want to add a new class to the CIM repository, you need to transfer a MOF file, or, if you want to use a new Provider, you need to add the DLL or ILT code that implements it. In these cases, you can add dependencies to your Resource Model and transfer them to the endpoint along with the Resource Model.
3.1.2 Physical components

The Workbench puts together various files composing the Resource Model to a tar package file, which contains a configuration file, a decision tree file, an MOF file, and dependency files. Figure 3-1 on page 69 shows the combination of the files composing the Resource Model.
73
Resource Model Tar File

Configuration File Logging: Dynamic Model(s): Parameter(s): Action(s): Threshold(s): Event(s): Message Catalogs Reference Model Functions: SetDefaultConfiguration(Svc) Init(Svc) VisitTree(Svc) JavaScript -or- Visual Basic Script
Provider(s):
MOF(s):
Custom Scripts() Dependencies Files
Custom Files(s)
Figure 3-3 Physical components in the Resource Model
Configuration file (.conf)

The configuration details of the Resource Model are obtained by the Monitoring Engine from the configuration file. These configuration details include the Resource Model name, platform name, name of the decision tree file, name of the MOF file, and so on.
Decision tree script file (.js or .vba)

The decision tree file (Visual Basic script or JavaScript for Windows platform and JavaScript for UNIX/LINUX platforms) contains both the initialization settings for the Resource Model and the algorithm that is used by the analyzer to determine if a problem is encountered in the resources described by the Resource Model.
Dependency files (optional: .java, .a, .so and so on)

If the resource mode has dependencies, the registered files are distributed to the Monitoring Engine. The typical dependency files are the following:
Custom Script File
The custom script file used by the Resource Model is distributed by initial profile distribution to an endpoint.
74
ILT / TSL Library Files The Java based Provider needs some library files, which are used in the two surfaces: ILT (Instrumentation Library Layer) and TSL (Touchpoint Service Layer). These library files are distributed during the first time of the profile distribution. MOF File(.mof)
The MOF file contains the particular Resource Model's class description and event definitions. The classes are derived from the corresponding base classes of the resources. The base classes for the model to resources association, and classes that describe physical resources used in the Resource Models with respect to the instance Providers, are provided in a base MOF file and resources MOF file respectively. These additional MOF files are distributed to the endpoint the first time a tmw2k profile is distributed to it.
3.1.3 Types of Resource Models

The Resource Model can be categorized by the type of script and the type of Provider, as shown in Table 3-1. When you create your own Resource Model, you can choose the type of Resource Model. You can also see that some of the Resource Models require additional components. Make sure you know what kind of Resource Models exist and what you need before creating the Resource Models.
Table 3-1 Resource Model types
Script type Provider Windows UNIX
Supported VBA CustomScript DM Monitor Prove WMI Provider DLL X X X
Requirement
Supported N/A N/A N/A
Requirement N/A N/A N/A
75
Script type
Provider
Windows
UNIX
Supported JavaScript CustomScript DM Monitor Prove Java ILT X X X
Requirement Windows Scripting 5.6 Windows Scripting 5.6 Windows Scripting 5.6 JRE 1.3.X
Supported X X X
Requirement JRE 1.3.X JRE 1.3.X JRE 1.3.X
X means supported. Blank means no requirement. N/A means Not Available
Categorized by the script type of the decision tree script, we have two major types of Resource Models:
VBA
The VBA Resource Model has a decision tree script written in Visual Basic for Applications (VBA). This Resource Model is only available on Windows platform. The VBA Resource Model is more tightly integrated with Windows and provides extra capabilities, such as debugging the Resource Model. The JavaScript Resource Model has a decision tree script written in JavaScript. The JavaScript Resource Model supports both of UNIX and Windows. On UNIX, the JavaScript Resource Model is the only supported Resource Model type. It requires the Java Runtime Environment (JRE) on UNIX. On Windows, it requires Windows Scripting 5.6, and if you use the JavaScript Resource Model with Java ILT, you need to install JRE on Windows.
JavaScript
3.2 Resource Models

Based on the best practices that IBM Tivoli Monitoring Version 5.1.1 provides, there are three major groups of Resource Models: Windows UNIX OS/400
76
As sample Resource Models, IBM Tivoli Monitoring Version 5.1.1 also provides the following two groups: Tivoli Web Component Manager (Sample Only: For Migration Purposes) Exchange (Sample Only) In this section, we introduce what Resource Models are included in each major group. Then we will focus on explaining details of each Resource Model, especially for Windows and UNIX.
3.2.1 Resource Models for each platform

We briefly describe the contents of Resource Models provided by IBM Tivoli Monitoring Version 5.1.1 for each platform.
Windows
Table 3-2 on page 78 summarizes the Resource Models included for Windows.You can see that some of the Resource Models have limitations for the support platform or need additional requirements. They are all Visual Basic based Resource Models utilizing WMI.
77
Table 3-2 Windows Resource Models

Windows 2000 (Pro, Server, Adv. Serv.) Resource Model Description Additional requirements
Memory
This Resource Model highlights the memory problems: cache, available bytes, paging and so on. This Resource Model highlights the Network Interface Problems: broadcast frames, percentage usage, and so on. This Resource Model examines the Windows Event Log for events that are specified by the user through the parameter configuration. This Resource Model checks the TCP and UDP port numbers you specify. This Resource Model highlights the following problems: disk usage and bytes per second transferred.
X X X
Network Interface Card
X N N SNMP A A Network Monitoring Agent X X X
Parametric event log
Parametric TCP/IP Ports Logical Disk
X X X SNMP
X X X diskperf
78
Windows XP (Professional)
Windows NT
Windows 2000 (Pro, Server, Adv. Serv.)
Resource Model
Description
Additional requirements
Physical Disk
This Resource Model detects bottlenecks specifically associated with all physical disks that are configured on the system. This model highlights the following problems: disk usage and bytes transferred per second. This Resource Model detects bottlenecks happening within or from the CPU. This Resource Model looks for bottlenecks relating to the processes running on the system and highlights the high usage. This Resource Model looks for bottlenecks found within the TCP/IP protocol. This Resource Model examines the Windows Event Log for events normally require immediate attention.
X X X diskperf
Processor
X X X
Services
X X X
TCP/IP
X X X SNMP
EventLog
X X X
Windows XP (Professional)
Windows NT
79
UNIX
Table 3-3 summarizes the Resource Models for UNIX. You can see that some of the Resource Models have platform support limitations or need an SNMP agent as an additional requirement. They are all JavaScript based Resource Models.
Table 3-3 UNIX Resource Models
Linux (Red Hat, SuSE, Turbo) for Intel Resource Model Description Additional requirements
CPU
This Resource Model detects problems with the CPU, such as high System Utilization. The file Resource Model gives information about files in the system. This Resource Model measures how efficiently the file systems are being used. This Resource Model provides information about how the memory is used. The Network Interface Resource Model detects problems with the following installed network interfaces: Loopback, Ethernet, and Token-Ring.
X X X X X
File
X X X X X
File System Memory
X X X X X
X X X X X
Network Interface
X X X X X SNMP
80
Linux (SuSE) for S/390
Solaris
HP-UX
AIX
Linux (Red Hat, SuSE, Turbo) for Intel
Resource Model
Description
Additional requirements
Network RPC-NFS
The Network RPC-NFS Resource Model detects problems and monitors the performance of the RPC and NFS servers and clients. The Process Resource Model looks for bottlenecks in running processes. Problems include: process down, too much CPU time, and zombie. The Security Resource Model provides information about files and the users logged onto the system and highlights the problems: resource property change, suspicious activity, and so on.
N X N N N / / / / A A A A
Process
X X X X X
Security
X X X X X
OS/400
Table 3-4 on page 82 summarizes the Resource Models for OS/400. They are all JavaScript based Resource Models.
Linux (SuSE) for S/390
Solaris
HP-UX
AIX
81
Table 3-4 OS/400 Resource Models

OS400 Resource Model Description
ASP Disk Mirroring
The ASP Disk Mirroring Resource Model, given an input of one or more ASP numbers, gets a list of disks for each ASP, checking the mirroring status of each disk. The ASP Utilization Resource Model monitors the Auxiliary Storage Pool (ASP) Utilization for the specified ASPs and sends events if the ASP is approaching capacity. This Resource Model monitors the overall CPU utilization of the system. This Resource Model monitors the interactive CPU utilization of the system. This Resource Model monitors the status of the configuration objects. The user can enter one or more configuration object names and types. The Database CPU Utilization Resource Model checks if the system is exceeding its threshold limit for database CPU utilization. The Distribution Queues Resource Model monitors the status of the high and normal priority service levels for distribution queues. This Resource Model finds specific messages in the history log. This Resource Model checks if the system is exceeding its threshold limit for Interactive Feature CPU utilization. This Resource Model checks a jobs Job Log for specific messages. The parameters contain the message numbers and text strings to match. This Resource Model monitors that one or more job queues, which have jobs queued to them, are assigned to a subsystem so that the jobs can be started. This Resource Model monitors the job status.
ASP Utilization
Basic CPU Utilization Basic Interactive CPU Utilization Configuration Objects
X X X
Database CPU Utilization
Distribution Queues
History Log Interactive Feature CPU Utilization Job Log
X X
Job Queue
Job Status
82
Management Central Network Attributes
This Resource Model monitors all Management Central events and forwards them to TEC. This Resource Model monitors the network attributes. The user provides one or more network attribute names along with a corresponding value. The Output Queues Resource Model checks if the output queues and their writers are active. This Resource Model allows you to monitor native objects and files for owner, size, and change date. The Storage Pools Resource Model monitors and logs the metrics for storage pools. This Resource Model checks the status of a list of subsystems and sends an event if there is a subsystem that is not active. This Resource Model monitors the overall system resources for system and ASP utilization. The user inputs one or more system value names along with a corresponding value as its desired value. This Resource Model monitors the status of one or more TCP interface. This Resource Model monitors the TCP service.
Output Queues Parametric Object and File Storage Pools Subsystem
System Disk Resources System Value
TCP Interface TCP Service

3.2.2 Windows Resource Models

Each of the following sections will describe the threshold logic that will generate indicators from Windows Resource Models. First of all, we explain how to read the table in the following sections: The row header contains the name of the thresholds that exist for a certain Resource Model. The left cell header contains the name of the indication that is generated.
83
OS400
Resource Model
Description
X X
X X X X
X X
X X
The Correlation column may contain a number, which indicates a correlation with another indication. The correlation function is available only for the Windows ITM Engine. The other cells of the table contain one of the following:
T F Blank
This indicates true, which means that the threshold has been reached or exceeded. This indicates false, which means the threshold has not been reached or exceeded. This means that this threshold is not used to determine this indicator.
Examples: The indication Low Logical Disk Space is generated when the threshold for Low Disk Space value is true. The indication Slow Logical Drive is generated when both the thresholds for High Queue Length and Total disk Bytes Read Per Second are exceeded.
Memory Resource Model

In this model, some indications are triggered due to some calculations based upon resource properties. Therefore, we included the column Calculation, which does not reflect a threshold value that can be adjusted by a user. You can learn how the calculation works by referring the decision tree script on the Workbench. The dependencies for the memory Resource Model are shown in Table 3-5 on page 85.
84
Table 3-5 Memory Resource Model dependencies

Minimum committed bytes Thresholds Minimum available bytes Excessive page faults
Low cache hits percent (moving average of...) CopyReadHits MDLReadHits DataMapHits PinReadHits
Excessive paging
Properties Correlation Calculated

a
Indications
High paging TMW_HighPaging Low available memory TMW_LowAvail Low available causing hard paging TMW_LowAvailCausingHardPaging Low available causing many problems TMW_LowAvailCausingManyProblems Low available causing soft paging and page file resizing TMW_LowAvailCausingSoftPagePagefile Resize Low available memory is causing excessive soft paging TMW_LowAvailCausingSoftPaging Low available with a high working set TMW_LowAvailHighWS Low available memory with a small page file TMW_LowAvailWithSmallPageFile Low available with high cache TMW_LowAvailHighCache
F T T
b
T 2 4 T T
T T
T T
F T
T 5
T T T
F T
c
Calculation
T
d
85
Minimum committed bytes
Thresholds Minimum available bytes Excessive page faults
Low cache hits percent (moving average of...) CopyReadHits MDLReadHits DataMapHits
Excessive paging
Properties Correlation Calculated

a
Indications
Low copy read hits TMW_LowCopyReadHits Low data map hits TMW_LowDataMapHits Low MDL read hits TMW_LowMDLReadHits Low pin read hits TMW_LowPinReadHits Memory leak in private bytes TMW_MemoryLeakInPB Memory leak in system code TMW_MemoryLeakInSC Memory leak in system drivers TMW_MemoryLeakInSD The page file is resizing TMW_PageFileResizing F T 5
T T T T T
e
PinReadHits
a. Calculated field: Commit Limit - Commit Bytes. b. Working set is larger than cache but less than available memory or working set is less than cache, and cache is less than available memory (that means not enough physical RAM). c. Working set is larger than cache and larger than available memory. d. Working set is less than cache, but cache is larger than available memory. e. Process increases private bytes since last visit and is among top five consumers. f. Amount of system memory increases. g. Amount of memory in device drivers increases.
86
Calculation
T
f
T
g
Network Interface Card Resource Model

The dependencies for the Network Interface Card (NIC) Resource Model are shown in Table 3-6.
Table 3-6 Network Interface Card Resource Model dependencies
High percentage of bytes pers second Thresholds
Indications
High errored ratio TMW_HighErroredRatio Network Interface Card overworked TMW_NICOverworked Network Interface Card too slow TMW_NICTooSlow High broadcast frames TMW_HighBroadcastFrames Adjust work items TMW_AdjustWorkItems Server overloaded TMW_ServerOverloaded 3
T T T T F T T F T F F T T
Properties BroadcastFrames
Redirector
Server
87
High work item shortage
High percent broadcast
High percent utilization
High error out ratio
High output queue
High current
Correlation
High percentage of bytes pers second
Thresholds
Indications
High current commands TMW_HighCurrentCommands Redirector overloaded TMW_RedirectorOverloaded Redirector affecting server TMW_RedirectorAffectingServer Redirector overloaded affecting segment TMW_RedirectorOverloadedAffecting Segment Segment affecting redirector TMW_SegmentAffectingRedirector Segment affecting server TMW_SegmentAffectingServer Server overloaded affecting segment TMW_ServerOverloadedAffecting Segment F F
F T T
Redirector
Server
F F T
T T T
F F F
F F T
F F
T T T
T T T
88
High output queue
High current
Correlation
High percentage of bytes pers second
Thresholds
Indications
Server affecting redirector TMW_ServerAffectingRedirector
Redirector
Server
Parametric event log Resource Model

This Resource Model examines the Windows NT or Windows 2000 event log and will send an indication if one of the user-specified events occur and is logged in the Windows event log. The dependencies for the parametric event log Resource Model are shown in Table 3-7 on page 90.
89
High output queue
High current
Correlation
Table 3-7 Parametric event log Resource Model dependencies

Windows event logged Thresholds
Indications
NT event log occurred TMW_NTEventLogOccurred
Correlation Service failing service Correlation
This Resource Model is used to examine the user-specified services for availability and any non-stable conditions. The dependencies for the Parametric Services Resource Model are shown in Table 3-8.
Table 3-8 Parametric Services Resource Model dependencies
Service stopped service Thresholds
Indications
Parametric services failing service TMW_ParamServicesFailingService Parametric services stopped service TMW_ParamServicesStoppedService
T T
Parametric TCP/IP Ports Resource Model

This Resource Model checks the user-specified TCP and UDP port numbers and generates events whenever these ports are in a specified state or states. The dependencies for the Parametric TCP/IP Ports Resource Model are shown in Table 3-9 on page 91.
90
Table 3-9 Parametric TCP/IP Ports Resource Model dependencies

Status of the defined port Thresholds
Indications
Parametric Port status TMW_ParamPortStatus
Correlation High bytes per second High percent usage High queue length
Logical Disk Resource Model

The dependencies for the Logical Disk Resource Model are shown in Table 3-10.
Table 3-10 Logical Disk Resource Model dependencies
Thresholds
Read
High read bytes per second TMW_HighLogicalDiskReadBytesSec High write bytes per second TMW_HighLogicalDiskWriteBytesSec High transfer rate TMW_HighLogicalDiskXferRate High percent disk time TMW_HighLogicalPercentDiskTime Logical disk possible fragmentation TMW_LogicalPossibleFrag
7 8 9 1, 2, 6, 10 11
T F T
F T T
Total disk
Indications
T T T F F
T T T T T
F F F T F
Low disk space
Correlation
Write
91
High bytes per second
Thresholds
High percent usage
High queue length
Read
Slow logical drive TMW_SlowLogicalDrive Low logical disk space TMW_LowLogicalDiskSpace
13 4
Total disk
Indications
T T
Physical Disk Resource Model

The dependencies for the Physical Disk Resource Model are shown in Table 3-11.
Table 3-11 Physical Disk Resource Model dependencies
High bytes per second Thresholds
High percent usage
Write
Read
High percent disk time TMW_HighPhysicalPercentDiskTime High transfer rate TMW_HighPhysicalDiskXferRate High read bytes per second TMW_HighPhysicalDiskReadBytesSec
6, 10 9 7 T T T F
Total disk
Properties indications
F T T
T T T
92
High queue length
Correlation
T F F
Low disk space
Correlation
Write
High bytes per second
Thresholds
High percent usage Total disk
High write bytes per second TMW_HighPhysicalDiskWriteBytesSec Physical disk possible fragmentation TMW_PhysicalPossibleFrag Slow physical drive TMW_SlowPhysicalDrive
8 11 13
Write
Read
Properties indications
T F T
T T
In addition to the thresholds, you may specify the number of printer queues and jobs within each printer queue that will be examined by the Resource Model. These settings influence the performance and CPU load generated by Tivoli Distribute Monitoring (Advanced Edition) 4.1. The dependencies for the Printing Resource Model are shown in Table 3-12.
Table 3-12 Printing Resource Model dependencies
Out of paper errors per day Thresholds Not ready errors per day
Out of paper errors
Job errors per day
Indications
High job errors per day TMW_HighJobErrorsPerDay High job errors TMW_HighJobErrors
T T
Percent processor
Not ready errors
Correlation
Job errors
High queue length
Correlation
F F T
93
Out of paper errors per day
Thresholds Not ready errors per day
Out of paper errors
Job errors per day
Indications
High not ready errors per day TMW_HighNotReadyErrorsPerDay High not ready errors TMW_HighNotReadyErrors High out of paper errors per day TMW_HighOutOfPaperErrorsPerDay High out of paper errors TMW_HighOutOfPaperErrors High current percent time TMW_HighCurrentPercentTime
T T T T T
In addition to the thresholds, it is possible to specify the number of processes that are analyzed. The dependencies for the Process Resource Model are shown in Table 3-13.
Table 3-13 Process Resource Model dependencies
High CPU use Thresholds Correlation Max handles
Indications
Process high CPU TMW_ProcessHighCPU Process handle leak TMW_ProcessHandleleak
12
T T
Processor Resource Model

The dependencies for the Processor Resource Model are shown in Table 3-14.
94
Percent processor
Not ready errors
Correlation
Job errors
Table 3-14 Processor Resource Model dependencies

High interrupts per second High CPU usage user priv Thresholds High CPU usage interrupt High CPU usage process High percent usage delta
High CPU usage
Indications
Busy Hardware TMW_BusyHardware CPU Cannot Keep Up With HW TMW_CPUCantKeepUpWithHW HW Keeping CPU Busy TMW_HWKeepingCPUBusy High Processes TMW_HighProcesses Processor Busy TMW_ProcessorBusy High Percent Usage Delta TMW_HighPercentUsageDelta
T T T
T T T F F T F
T F F T Fa
12
T T
a. The processor queue length is greater than the total number of CPUs plus the TotalCPUsMod threshold.
Services Resource Model

The services model works in a slightly different way. The threshold values have a logical value set of {0, 1}. In contrast to the usual meaning, these values are Boolean variables. Everything greater than zero is equal to true; zero means false. If the value is set to 1 or a number greater than that, then the indications may be triggered when the corresponding service either failed or was stopped. In addition to that, IBM Tivoli Monitoring Version 5.1.1 will try to restart a stopped service. If that fails, another event is generated and sent to TEC. The dependencies for the Services Resource Model are shown in Table 3-15 on page 96.
Total CPUs mod
Correlation
95
Table 3-15 Services Resource Model dependencies

LanmanWorkstation Thresholds LanmanServer
EventLog
NtLmSsp
Netlogon
Browser
Indications
Any failing service TMW_ServicesFailingService
T T T T T T T
Services stopped service TMW_ServicesStoppedService
T T T T T T T
Note: Windows NT or Windows 2000 machines that are part of a workgroup do not run the Netlogon service; starting this service will fail. Therefore, to avoid large numbers of reoccurring service events on workgroup members, you should turn off monitoring for this service by setting the Resource Model property to zero for the Netlogon service.
TCP/IP Resource Model

The dependencies for the TCP/IP Resource Model are shown in Table 3-16 on page 97.
96
Lcfd
Table 3-16 TCP/IP Resource Model dependencies

High fragment ratio FragmentsReceived, DatagramsReceived Thresholds Low segments Moderate DG
Indications
High ping TMW_HighPing High fragment ratio TMW_HighFragRatio Segments resubmitted TMW_SegmentsReXmit 3
F T T
EventLog Resource Model

This model works in a different way. It scans the NT event log and sends indications when it finds an event of a specific type. It does not depend on thresholds. You can specify how many events are examined. This number will affect the performance of IBM Tivoli Monitoring Version 5.1.1. The event log indications are: NT event log 9 (TMW_EventID9) The device [name] did not respond within the time-out period. NT event log 11 (TMW_EventID11) The driver detected a controller error on [text]. NT event log 15 (TMW_EventID15) The device [name] is not ready for access yet.
SegementsRetransmitted
Properties
Correlation
Datagramsreceived
SegmentsReceived
High segment retransmitted
97
NT event log 2011 (TMW_EventID2011) The server's configuration parameter ipstacksize is too small for the server to use a local device. Please increase the value of this parameter. NT event log 2511 (TMW_EventID2511) The server service was unable to recreate the share name because the directory path no longer exists. NT event log 3013 (TMW_EventID3013) The redirector has timed out a request to [text]. NT event log 7023 (TMW_EventID7023) The [name] service terminated with the following error: [text].
Correlated events
Correlated events are generated from two indications, in most cases, originated in different Resource Models. Table 3-17 provides an overview of the dependencies of the correlated events. For a more detailed description of the correlated events, refer to the IBM Tivoli Monitoring Resource Model Reference Version 5.1.1, SH19-4570.
Table 3-17 Table of correlated indications
Generated indication Correlated indication
TMW_BusyDriveFromPaging
TMW_HighLogicalPercentDiskTime TMW_HighPaging indication
TMW_BusyDriveFromLowAvail
TMW_LowAvailCausingManyProblems TMW_HighLogicalPercentDiskTime
TMW_CongestedTCPNetwork
TMW_NICOverworked TMW_SegmentsReXmit
TMW_CriticallyLowDiskSpace
TMW_LowAvailCausingSoftPagePagefileR esize TMW_LowLogicalDiskSpace
TMW_CriticalMemoryLeakInWS
TMW_MemoryLeakInPB TMW_LowAvailHighWS
98
Generated indication
Correlated indication
TMW_FaultyDiskSubsystem
TMW_HighPhysicalPercentDiskTime TMW_BusyHardware indication TMW_HighLogicalPercentDiskTime
TMW_HighDiskReadBytesSec
TMW_HighPhysicalDiskReadBytesSec TMW_HighLogicalDiskReadBytesSec
TMW_HighDiskWriteBytesSec
TMW_HighLogicalDiskWriteBytesSec TMW_HighPhysicalDiskWriteBytesSec
TMW_HighDriveXferRate
TMW_HighLogicalDiskXferRate TMW_HighPhysicalDiskXferRate
10
TMW_HighPercentDiskTime
TMW_HighPhysicalPercentDiskTime TMW_HighLogicalPercentDiskTime
11
TMW_PossibleFrag
TMW_LogicalPossibleFrag TMW_PhysicalPossibleFrag
12
TMW_ProcessHoggingCPU
TMW_HighProcesses TMW_ProcessHighCPU
13
TMW_SlowHardDrive
TMW_SlowPhysicalDrive TMW_SlowLogicalDrive
3.2.3 UNIX Resource Models

The tables in this section are for the UNIX/Linux Resource Models. Each table can be interpreted in the same way as the Windows reference models. Any differences or unique characteristics to a specific table will be documented with the relevant tables.
CPU Resource Model

This Resource Model detects problems with the central processing unit of a computer, for example, how long processes wait in the queue to be processed. The dependencies for the CPU Resource Model are shown in Table 3-18 on page 100.
99
Table 3-18 CPU Resource Model

Percentage of CPU idle Thresholds
Properties Indications Low
High CPU overload Low_IdleCPUUsage High CPU usage by system High_SysCPUUsage
T T
Memory Resource Model

This Resource Model provides information about how the memory is used. The dependencies for the Resource Model are shown in Table 3-19.
Table 3-19 Memory Resource Model
Percentage of available virtual storage Percentage of available swap space Thresholds
Memory page-out rate
Indications
Low storage space LowStorage Low swap space LowSwap System thrashing Thrashing
T T T T
100
Memory page-in rate
Percentage of CPU used by system
File Resource Model

The file Resource Model gives information about files in the system. This Resource Model does not have thresholds that certain conditions are compared against. Instead, it checks for changes in files, file attributes, and so on. We provide the system resource that it uses to calculate which event should be generated. The dependencies for this Resource Model are shown in Table 3-20.
Table 3-20 File Resource Model
Change in file attributes Thresholds
/etc/passwd
Properties
/etc/group
Indications
File changed FileChanged File attributes changed FilesAttributeChange File not present FileNotPresent
T T
This event is generated if the file does not exist.
Process Resource Model

The Process Resource Model looks for bottlenecks that occur in running processes. Problems highlighted include: A process uses too much CPU time. Too many zombie processes in the system. A process is stopped or killed. A process that was requested does not exist. This Resource Model monitors processes that are specified in the parameter list. By default, it monitors lcfd and syslogd. The dependencies for this Resource Model are shown in Table 3-21 on page 102.
/etc/hosts
Change in CRC
Change in file
T F
101
Table 3-21 Process Resource Model

Max zombie processes Thresholds Percent of CPU used syslogd lcfd
Properties
Indications
High number of zombie processes HighZombieProcesses Process consuming high CPU ProcessHighCPU Process killed or nonexistent ProcessKilledOrNotExisting Process stopped ProcessStopped
T T Sent if a process is killed or does not exist. Sent for each monitored process that is stopped.
Network Interface Resource Model

The Network Interface Resource Model detects problems with all the installed network interfaces. Events are generated when performance data, such as bytes per second in and out and sessions with errors or requests, becomes critical. The dependencies for this Resource Model are shown in Table 3-22 on page 103.
102
Table 3-22 Network Interface Resource Model

Percent of packet collision Thresholds
Output packets in error
Input packets in error
Token Ring, Ethernet, or LOOPBACK
Properties
Interface
Interface status
UP&NOTRUNNING
Indications
High percentage packet collision HighPacktsCollision High output packets in error HighOutErrorPacks High input packets in error HighInputErPacks Interface not enabled InterfaceNotEnabled Interface not operational InterfaceNotOperat Unknown interface status IntStatUnknown Network Interface Card not supported IntNotSupported
a. Ethernet interface only.
Ta
T T
T T T T T F T
T T
T T
File system Resource Model

This Resource Model measures how efficiently the file systems are being used. The dependencies for this Resource Model are shown in Table 3-23 on page 104.
UP&RUNNING
UNKNOWN
Down
T T
103
Table 3-23 File system Resource Model

Percentage of File System Space Available Thresholds
Percentage of file system space used
Indications
Fragmented file system FragmentedFileSystem Low percent space available LowPercSpcAvail Low space available LowKAvail Low percentage of available I-nodes LowPercInodesAvail
T T
F T T T
Security Resource Model

The Security Resource Model provides information about files and the users logged onto the system. It highlights the following items or changes that might indicate security breaches: Property changes, such as the owner, group, or attributes, for certain files The number of logons onto the system by the same user A suspect superuser An account that is not valid for root The dependencies for the Resource Model are shown in Table 3-24 on page 105 and Table 3-25 on page 106.
104
Percentage of available I-nodes
Percentage of I-nodes used
Available space (KB)
Table 3-24 Security Resource Model and file monitoring: Part 1

Alternative groups Thresholds Special groups Defined users Special users
Null password
Supergroups
Properties Superusers
Instrumentation
Custom logins
root
Duplicated account DuplicatedAccount High log-in number for user HighLoggingNumber Suspect super group SuspectSuperGroup Account not valid for root NotRegularRootAccount Null password PasswordNull Suspect superuser SuspectSuperUser F
F F
F F T
root
Indications
T F F F T
T Ta
a. This indicator will also happen for a group with a null password, but only for HP-UX 10 and Solaris 2 systems.
105
Duplicated
UID -1
UID 0
T T
Table 3-25 Security Resource Model and file monitoring: Part 2

Files to be monitored Thresholds Alternative owners
Alternative groups
File owner Matches
File group
File Exists
Properties Matches Member
Indications
Illegal owner IllegalOwner Illegal group IllegalGroup Wrong file mode WrongMode Nonexistent file FileNoteExisting
F F
T T T F F
F T
Network RPC/NFS Resource Model

The Network RPC/NFS Resource Model detects problems and monitors the performance of the RPC and NFS servers and clients. This Resource Model should only be distributed to Solaris machines. The dependencies for this Resource Model are shown in Table 3-26 on page 107.
106
Matches
Member
File mode
T T F
Table 3-26 Network RPC/NFS Resource Model (Sun Solaris specific)

Percent of Sever RPC duplicate requests Thresholds Percent of NFS svr readlink operations
Percent of Client RPC retranmissions
Percent of NFS svr getattr operations
Percent of client RPC calls in timeout
Indications
High NFS server read operations HighNFSSrvRead High duplicate RPC server calls HighPercDupReqs High retransmitted calls HighPercRetrans High network traffic NetworkBusy High NFS buffer size HighNFSBufferSize High NFS server get-attribute operations HighNFSSrvGetattr High RPC bad calls HighPercRPCBadCalls Slow network NetworkSlow High NFS server readlink operations HighNFSSrvReadLink High timeout and badxids HighTimeoutsAnd_Badxids
T T T T T T T T
T T T T T
107
Percent of NFS svr write operations
Percent of NFS server read ops
Percent of client RPC badxids
Percent of bad RPC calls
108
Indications Thresholds
High timeout and badxids HighTimeoutsAnd_Badxids
High NFS server write operations HighNFSSrvWrites
Percent of NFS server read ops Percent of Sever RPC duplicate requests Percent of Client RPC retranmissions Percent of NFS svr getattr operations Percent of bad RPC calls Percent of NFS svr readlink operations Percent of client RPC badxids
IBM Tivoli Monitoring: Creating Resource Models and Providers T T
Percent of client RPC calls in timeout Percent of NFS svr write operations
Chapter 4.
Providers
IBM Tivoli Monitoring is able to gather data not only from CIM data sources but also from Tivoli Distributed Monitoring (Classic Edition) monitors and custom scripts (Compatibility Mode). In this way, ITM provides a set of data sources, or Providers, that support not only the enhanced ITM architecture, but also a migration path for those already supported by Tivoli Distributed Monitoring (Classic Edition). To fully leverage the new technologies, new work should be performed in the native environment, where the monitored data is collected from the underlying CIM implementation. This chapter provides a background on the technologies supported by the ITM architecture as well as discussions on the methods by which Tivoli has implemented these technologies. The following topics are discussed in this chapter: Overview and terminology Industry technologies (WBEM, CIM, and JMX specifications) Tivoli implementations
109
4.1 Overview
Various management technologies exist in the Information Technology industry today. This has resulted in a vast array of management methods. In Figure 4-1, four methods chosen due to their relevance to the ITM Provider discussion, are compared.
IT Management Methods
Physical
Management Application
Tivoli Monitoring
ITM Engine
Network
Fault, Configuration, Performance
Desktop
Fault, Configuration, Performance
Managed Resource Definition
MOF
MIB
MIF
Service Layer & Infrastructure
CIM (M12, WMI)
SNMP
DMI
Physical Managed Objects
Managed Resource
Network Devices
Desktop Systems
Figure 4-1 IT management methods
Physical: The physical management techniques vary per industry or technology. Many of the current standards in the IT industry are legacy specifications originally implemented as a point solution to manage specific types of devices in a specific way. Management Application: This layer refers to how management will be applied, such as specified instrumentation or uses. Some methods may refer to physical software, as the flexibility of the technology may not be limited to specific topics. Managed Resource Definition: This layer exists to define the objects in a manner that is applicable to the service layer. Service Layer & Infrastructure: This layer determines the management technique is applied and interacts with the physical managed objects.
110
Physical Managed Objects: In the Information Technologies arena, these objects can vary from routers and servers, to individual disk drives and application modules. Tivoli ITM: The implementation of IBM Tivoli Monitoring includes technologies based on open industry standards and apply methods designed to better model the physical devices, compared to previous monitoring solutions. ITM Engine: The ITM Engine provides the infrastructure to support numerous applications for management. It exists in two forms: a Windows version and a Java-based cross-platform version. Each addresses the same product requirements but within the context of the platform as well as supporting platform dependent technologies. This is best explained in Java-based ITM Engine overview on page 120. MOF: The Managed Object Format, as described in 4.2.3, Managed Object Format (MOF) on page 114. CIM (M12 & WMI): The Common Information Model implementation is described in Java-based ITM Engine overview on page 120 and Windows-based ITM Engine overview on page 123, respectively. Managed Resource: The physical items against which data Providers are executing to obtain metrics. Network: This method is primarily implemented for network availability and performance applications, such as network segment and device monitoring. Fault, Configuration, Performance: This list indicates the various information types that the network method applies to. This data, following the MIB format, is available through SNMP requests. MIB: The Management Information Base is a schema that defines the hierarchical order of a set of management objects, each with its own unique identifier, and is accessible through the SNMP protocol. SNMP: The Simple Network Management Protocol specification for sending and receiving MIB data. This is typically implemented by a manager that generates the information requests and an agent that receives, processes, and responds to requests. Network Devices: Though the most common uses for the network management methods are with devices such as routers, switches, and firewalls, most vendors provide software services for workstation and server operating systems as well. Desktop: This method is most commonly implemented within configuration management applications, such as inventory. Fault, Configuration, Performance: This list indicates the various information types that the desktop method applies to. This data, following the MIF format, is available through DMI requests.
Chapter 4. Providers
111
MIF: The Management Information Framework is a schema that defines the standard manageable attributes of workstation and server products. DMI: The Desktop Management Interface is a standard way for sending management information across a network to a central site. Desktop Systems: Though desktop systems are the most common use for the DMI implementation, it has become increasingly useful for server management in lights out data centers.
4.2 Industry technologies

To improve the positioning and capabilities of products, numerous companies are forming organizations together to drive the direction of these technologies as a joint effort. One such group is the Distributed Management Task Force, Inc. (DMTF). The DMTF is the industry organization that is leading the development, adoption, and unification of management standards and initiatives for desktop, enterprise, and Internet environments. Working with key technology vendors and affiliated standards groups, the DMTF is enabling a more integrated, cost-effective, and less crisis-driven approach to management through interoperable management solutions. IBM is a board member of the DMTF and has incorporated many of the specifications created by the organization within the ITM product suite. The diagram show in Figure 4-2 on page 113 helps explain the relationships of the applicable technologies.
112
Management Technologies
Application Management Application
WBEM Technologies CIM Layer MOF WMI
JMX
MOF
Interface
Provider Layer
COM
MBean
Managed Resources
Figure 4-2 Management technologies
4.2.1 Web-Based Enterprise Management (WBEM)

WBEM is a set of management and Internet standard technologies developed by the DMTF to unify the management of enterprise computing environments. WBEM provides the ability for the industry to deliver a well-integrated set of standard-based management tools leveraging Internet technologies. Included in the WBEM initiative is a data model, an encoding specification, and a transport mechanism, We will not discuss WBEM further except for the Common Information Model (CIM) data model and its applicable technologies. Additional information on the WBEM initiatives can be obtained from the DMTF at:
http://dmtf.org/standards/standard_wbem.php
4.2.2 The Common Information Model (CIM)

The DMTF CIM is a specified approach to the management of systems and networks that applies the basic object-oriented structuring and conceptualization techniques. The specification formally introduces the language and methodologies for describing object-oriented enterprise management data within an extensible schema. The CIM schema enables applications from different
113
developers on different platforms to describe management data in a standard format so that it can be shared among a variety of management applications.
Associations
Unlike many common object models, CIM does not allow ordinary classes to contain references to other classes. Instead, CIM uses a special kind of class called an association to link instances of classes together. An association class is a class that has at least two references and the association qualifier. Classes that are not associations may not have any references. Reference properties may not be arrays. Therefore, there is one instance of an association class for every pair of classes that is associated (assuming a binary association).
CIM Object Manager (CIMOM)

The CIMOM is the core component to the implementation of the CIM specification. The CIMOM manages the CIM schema, instantiation, communication, and operation of the physical Providers that represent the CIM classes stored within the namespace of the local host. This local storage location represents the schema and is typically implemented as either a file system, a registry, or a binary database.
4.2.3 Managed Object Format (MOF)

The management information is described in a language based on Interface Definition Language (IDL) called the Managed Object Format (MOF). This document uses the term MOF Specification to refer to a collection of management information described in a manner conformant to the MOF syntax. The MOF syntax is a way to describe object definitions in a text format. It establishes the syntax for writing definitions. The main components of a MOF specification are textual descriptions of classes, associations, properties, references, methods, and instance declarations and their associated qualifiers. Comments within the MOF are permitted and advised. In addition to specifying the managed objects, a MOF specification can be processed using a compiler. To assist the process of compilation, a MOF specification consists of a series of compiler directives.
MOF usage
The managed object descriptions in a MOF specification can be validated against an active namespace. Such validation is typically implemented in an entity acting in the role of a server. This section describes the behavior of an implementation when introducing a MOF specification into a namespace. Typically, such a process validates both the syntactic correctness of a MOF specification, as well as the semantic correctness of such a specification against
114
a particular Implementation. A MOF specification can be validated for the syntactic correctness through the use of a MOF compiler.
Class declarations
A class declaration is treated as an instruction to create a new class.The ability to add classes or modify classes within a namespace from a MOF specification is determined by the CIMOM implementation. Different vendors may or may not support this capability. Any class referenced within another class must exist at the time the MOF specification makes that reference, that is, forward references are not allowed.
Instance declarations
Classes must be defined before they are used to declare instances. However, if a class definition is already resident within the namespace, that class declaration need not appear in a MOF specification that introduces the instances of that class. Any instance declaration is treated as an instruction to create a new instance where the object's key values do not already exist, or an instruction to modify an existing instance where an object with identical key values already exists.
4.2.4 CIM Provider layer

The CIM Provider layer consists of the software implementation of the CIM class that the CIM represents. This software implementation performs the actual instrumentation and management as defined by the MOF specification. The operations can consist of methods that retrieve or set properties of the physical resource through software, hardware, or other application interfaces. The Provider layer can vary a great deal regarding how it is implemented; Java classes, COM objects, and platform specific binaries are examples. The common tie between all Provider types is that they implement an interface for the CIMOM on which they were designed to execute.
4.2.5 Windows Management Interface (WMI)

Windows Management Instrumentation (WMI) is a component of the Microsoft Windows operating system that provides management information and control in an enterprise environment. By applying industry standards, managers can use WMI to query and set information on desktop systems, applications, networks, and other enterprise components. Developers can use WMI to create event monitoring applications that alert users when important incidents occur.
115
WMI offers a variety of programming interfaces such as C++, open database connectivity (ODBC), Visual Basic, or HTML, that developers can use to customize management applications. System administrators can use WMI by using scripts to automate administration tasks. WMI can integrate with Windows components, such as Active Directory, to allow for a consistent management interface. A management application communicates with WMI through a variety of interfaces, such as Visual Basic, C++, ODBC, and Microsoft ActiveX. All of the WMI interfaces in turn are based on the Component Object Model (COM). WMI retrieves information about an enterprise from different sources, such as hardware, the registry, or other user-defined sources. Like a management application, WMI communicates with a data source using a COM interface. After WMI retrieves information about an enterprise, WMI stores the data using the Common Information Model (CIM). The WMI architecture consists of the following components: Managed objects and Provider WMI infrastructure WMI management applications
Managed objects and Providers

A managed object is a logical or physical enterprise component, such as a hard drive, network router, database system, or operating system component. A managed object communicates with WMI through a Provider. In the case of WMI, a Provider is a COM object that monitors a managed object for WMI. Similar to a driver, a Provider supplies WMI with data from a managed object. A Provider also handles messages from WMI to the managed object. For example, the Microsoft Windows Platform SDK ships with a Registry Provider, which accesses information on the system registry. WMI passes information from the Providers to the WMI infrastructure.
WMI infrastructure
The WMI infrastructure is a Windows operating system component that moves and stores information about managed objects. The WMI infrastructure consists of two components: the Windows Management service, and the WMI repository. The Windows Management service acts as an intermediary between the Providers, management applications, and the WMI repository, placing information from a Provider into the WMI repository. The Windows Management service also accesses the WMI repository in response to queries and instructions from management applications. Finally, the Windows Management service can pass information directly between a Provider and a management application. In
116
contrast, the WMI repository acts as a storage area for information passed in by the various Providers.
WMI management applications

A management application is an application that interacts with the WMI infrastructure. A management application can query the Windows Management service for information regarding a managed object. Alternately, a management application can instruct the Windows Management service to send instructions to a managed object.
4.2.6 Java Management Extensions (JMX)

JMX defines a standard instrumentation model: MBeans, for use in Java programs and by Java management applications. JMX also specifies a set of complementary services that work with MBean instrumentation to monitor and manage Java-based applications. These services range from simple monitors and timers to a powerful relation service that can be used to create user-defined associations between MBeans in named roles and a mechanism for dynamically loading new instrumentation/services at run time.
JMX architecture
The Java Management Extensions (JMX) Instrumentation and Agent Specification Version 1.0 defines an architecture and services for application and network management. JMX provides a standard mechanism for management of Java-based resources and management through the Java platform. Figure 4-3 illustrates the JMX architecture.
Figure 4-3 JMX MBean server
117
The architecture is divided into the following three levels: Instrumentation MBean Agent
Instrumentation
JMX instrumentation provides mechanisms for describing and accessing JMX Manageable Resources. JMX Manageable Resources are those aspects of a domain that provide some management interface to the user or administrator. JMX Manageable Resources can be developed as pure Java applications or application components or they can be Java wrappers around native resources. MBeans are the concrete representations of JMX Manageable Resources. MBeans come in two basic types: standard and dynamic. The JMX Specification provides a detailed description of these basic types and their subtypes.
MBean
An MBean (or Managed Bean) is a Java object that implements a specific interface and conforms to certain design patterns. These requirements formalize the representation of the resources management interface in the MBean. The management interface of a resource is the set of all necessary information and controls that a management application needs to operate on the resource. MBeans are either standard or dynamic. Standard MBeans are Java objects that conform to certain design patterns derived from the JavaBeans component model. Dynamic MBeans conform to a specific interface that offers more flexibility at run time.
Agent
The Agent Level of the architecture is responsible for combining JMX instrumentation and services as well as providing a uniform interface to the components of the Distributed Services layer. Conceptually, a JMX Agent is composed of an MBeanServer instance, a set of MBeans representing managed resources, a minimum number of agent services implemented as MBeans, and at least one protocol adapter or connector server. The agent may be part of a daemon process running on a machine or it may be embedded within the application being managed.
Distributed services
In the first version of the JMX specification, this level of the architecture is unspecified. However, its role is clear: it connects the JMX Agent to the external world of management consoles and applications.
118
JMX-based management
Run-time management of resources is illustrated in Figure 4-4.
Figure 4-4 Management agent
Events or attribute changes in the managed resources trigger higher level events in the monitor(s) listening/watching for those events/changes. These higher level events are sent to a decision maker. This decision maker may be a human sitting at a management console, or another software component. The decision maker is responsible for taking an appropriate action in response to the event. Those actions are then turned into control directives that act on the managed resources. In the JMX model, managed resources are MBeans. The JMX monitors are service MBeans that are part of the JMX agent level. JMX does not specify any standard decision makers. However, in the case where the decision maker is a software component, it would also be a service MBean registered with the MBeanServer. Control directives are carried out by invoking methods or setting attributes on specific MBeans via the MBeanServer interface.
4.3 Tivoli implementations

The Tivoli implementation of the previously discussed technologies can best be addressed first by presenting the engine components and any platform specific implementation issues. Second, the legacy support capabilities of the engine will be addressed. Third, the technologies required to support a CIM-based Provider
119
is discussed. Finally, a brief discussion on the implementation of Java Management Bean technology is presented.
4.3.1 ITM Engine components

The ITM Engine consists of multiple logical components, which have been implemented with two different approaches to resolve specific needs. The original approach was to create the engine for the Windows platform to make use of the WMI infrastructure. The later approach was that of the Java-based engine. The Java engine provides a key capability that is not obtainable from the Windows engine, cross-platform operation. It is this capability that drives the development efforts of the newer product releases. This is confirmed when one considers the Windows engine enhancement to provide support to Java ILTs. We will therefore present the engine logical components by discussing the unique features of the Java platform, then the Windows platform, and finally the components common to both.
Note: For a physical component discussion, please refer to Chapter 1, IBM Tivoli Monitoring architecture on page 3.
Java-based ITM Engine overview

The Java-based ITM Engine is a cross platform implementation of the original Windows design. The Java engine provides cross-platform capabilities that cannot be offered by the Windows engine, as well as a simplified ILT Provider interface. These features include: Ability to operate on multiple platforms, including various flavors of UNIX and OS/400. Ability to load and execute Java-base ILT classes, which in-turn provides cross-platform monitoring solutions. This can reduce development and maintenance costs. All of the logical components within the Java engine are both common to both engines. Therefore, we will introduce these components here to better explain the commonalities. Figure 4-5 on page 121 provides a diagram of the logical components of the Java version of the ITM Engine. This diagram will be referenced throughout this chapter as a thumbnail image.
Attention: Thumbnail images have been implemented within sub-topics for quick reference to the logical components utilized within the area of discussion. It is recommended that the larger diagrams be referenced when conducting an in-depth analysis.
120
ITM Engine Logical Components (Java)

Custom Scripts
Resource
Resource
Resource
Figure 4-5 ITM Engine Logical Components (Java)
Common components
The logical components common to both engines are those focused on the integration with the TME infrastructure as well as those that handle the Java ILT operation. The diagrams in Figure 4-6 on page 122 highlight only the components within the Windows and Java engines that are common. For greater engine detail, please refer to Figure 4-5 and Figure 4-7 on page 124.
121
ITM Engine Logical Components (Windows)


TMWService WMI APIs DM Classic Monitor Probes DM Classic Monitor Probes WMI (CIMOM) Custom Scripts ILT Manager for Java (WMI Provider DLL) WMI Provider DLLs Java Virtual Machine (JVM) Launch (Class Loader) ILT Providers Resource Resource Resource Resource Resource ILT Provider JNI Binary Library MBean Server MBean1 Resource Resource JMX ILT
COM Objects
Custom Scripts
Java Class Loader ILT Providers Resource ILT Provider JNI Native Binaries MBean Server MBean(s) JMX ILT
Figure 4-6 Common logical components for Windows and Java
The logical components shared between the Java and Windows engines are: Resource Models: The Resource Models are packages containing a variety of files required for configuration and that provide the desired functionality, the details of which can be referenced in Chapter 3, Resource Models on page 67. Analyzer: The analyzer performs the core functionality for the ITM Engine. TMWService (Service Object): The service object is implemented in two ways; one for each of the engine types. For Windows, the TMWService is an COM object, where as in Java it is a class. Both are instantiated by the Analyzer and passed to the Resource Model script functions for reference by the model to specific methods. DM Classic & Custom Script Support: Both of these logical components are actually implemented through the use of the shell method of the service object and any associated dependency files within the Resource Model. Launch (Class Loader): The ITM Engine actually provides three levels of class loading, two of which are relevant to the loading of ILTs. Common: This class loader handles classes packed in jar files placed into the %LCF_DATDIR%\LCFNEW\ITM\PACS path. This loader is dynamic, meaning that classes packed as *.jar files can be added dynamically to the path. Category-Specific: This class loader handles classes packed in jar files placed into the %LCF_DATDIR%\LCFNEW\ITM\PACS\<category> and the %LCF_DATDIR%\LCFNEW\Tmw2k\Unix\Classes\<category> path.
122
This loader is also dynamic and can dynamically add jar-packed classes to the path. Instrumentation Library Type (ILT) Providers: This component represents the actual Java classes responsible for interfacing the TSL to the instrumentation mechanism, typically additional classes. Three types of instrumentation classes are represented: Providers: This component refers to the actual Java class that performs the actual instrumentation. In this component, this work is performed strictly through Java code. JNI & Native binary libraries: The use of Java Native Interface methods can be implemented within the Provider class to reference C/C++ libraries compiled for specific platforms. This method is much less portable than is the straight Java code. JMX ILT: This refers to the implementation of an MBean agent to load MBeans from management enabled Java applications that provide the MBean server. Within the ITM Engine, an MBean loader has been provided, so it is not required to learn ILT to be able to gather metrics from MBean enabled applications. Resources: Resources are anything that the metrics are provided for by the ILT. An ILT can be designed to interface with an operating system and poll configuration or performance data. An ILT can also be designed using application APIs to poll metrics internal to the application. Along the same design theory, an ILT can be implemented that connects to MBeans within Java-based applications, which is typical with Web-based solutions such as WebSphere, to poll configuration and metric data.
Windows-based ITM Engine overview

The Windows-based ITM Engine is a platform specific implementation. Therefore, the most significant difference is that the TSL has not been implemented within the Windows engine, as the WMI provides all CIMOM functionality. Additional differences include enhancements over previous products and a few capabilities that cannot be offered by the Java engine. These features include: The ability to instantiate COM objects within the Resource Model script. The ability to reference WMI registered Providers through direct WMI API calls, internal to the engine components. Product enhancements were implemented to support the Java ILT components. Due to the nature of the platform specific engine and WMI APIs, the supporting of the ILTs requires complexities not found in the Java based engine. The first component to address these integration issue is the registration of the ILT
123
Manager as a WMI Provider DLL. This ensures that the ILTs will operate through the engine as a native WMI Provider, which offers consistent performance through the engine and allows WMI to control the Provider. The ILT Manager embeds a Java Virtual Machine that in turn hosts the Java ILTs. This supports the Java requirements of the TSL components and the custom ILT classes. Figure 4-7 provides a diagram of the relationship between the logical components of the Windows version of the ITM Engine. This diagram will be referenced throughout this chapter as a thumbnail image. As stated earlier, the thumbnail images are for general reference for the localized topics.

COM Objects
Figure 4-7 ITM Engine Logical Components (Windows)
Windows ITM Engine COM support

The ITM Engine for the Windows platform utilizes the Microsoft Script Host to process the VBScript and JScript within Resource Models. It is the script host that permits the declaration of Component Object Model (COM) objects within the Resource Models. An example of implementing a COM object within a Resource Model is provided in Chapter 11, File monitoring Resource Model example on page 447.
124
For a comprehensive explanation of the Microsoft Windows Script Host capabilities, refer to:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/script56/html/ wsorigettingstarted.asp
Figure 4-8 highlights only the components within the Windows engine that is utilized for COM references within VBScript-based Resource Models. For greater engine detail, please refer to 4.3.1, ITM Engine components on page 120.
COM Objects
Figure 4-8 Logical components for Windows COM support
Windows ITM Engine native WMI support

The ITM Engine for the Windows platform is integrated at the API level with the WMI components of the OS. This was done because WMI is the formal implementation of the WBEM specification by Microsoft. The WMI Providers are accessible through the Dynamic Data CIM declarations within the Resource Model and can be browsed through the ITM Workbench. In order to provide cross engine Java ILT class support, a class loader has been included within the Windows ITM Engine. This is implemented as a Java Virtual Machine (JVM) registered to WMI as a native Provider. This allows for consistent interfacing between the ITM Engine and WMI. The JVM based class loader handles the loading and execution of the Java based ILTs distributed within Resource Models. This integration method allows the Windows ITM Engine to execute the same Java ILT classes as the pure Java ITM Engine.
125
Note: Any coding done in the Java classes that may be specific to an operating system may not be portable. This is an issue that should be considered when coding the Java classes. For example, if JNI is used to access platform specific binary libraries, a corresponding Windows binary will be required to support the JNI references.
Though the Java ILT class and Provider class can be written in a platform independent manner, the differences between the Microsoft CIM implementation through WMI and the Tivoli implementation through the M12 specification mandate that different MOF files be created. The following requirements for the Windows MOF should be noted: Add the Dynamic qualifier to the CIM class. Use M12JavaProvider and not com.tivoli.dmunix.ep.touchpoint.cimom.ifc.M12JavaProvider as the Provider for the class instances and properties. Specify the CIMV2 namespace using a pragma statement. For an example of a Windows MOF implementation, please reference Chapter 9, Creating a log-file Resource Model and ILT on page 333.
Attention: The utility xmof was created by Tivoli ITM developers to handle the conversion of a TSL compatible MOF to a Windows compatible MOF, but it is not widely available yet. It has been provided at the download site for this redbook. For a detailed example of the usage of the utility and the implementation of the Windows MOF requirements, please refer to Chapter 9, Creating a log-file Resource Model and ILT on page 333. Additional information is also available from the Microsoft Developer Network at:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/kmarch/hh/k march/wmi_2fjb.asp
Figure 4-9 on page 127 highlights only the components within the Windows engine that are utilized for WMI integration and native support. For greater engine detail, please refer to 4.3.1, ITM Engine components on page 120.
126

COM Objects
Figure 4-9 Logical components for Windows WMI native support
4.3.2 Legacy support

The ITM product provides functionality to support pre-existing DM Classic collections and custom scripts. This functionality can also be used to implement a new functionality that a developer may not feel is appropriate or cost effective to create an ILT for. This functionality is performed through the use of the shell method within the service object. For a more detailed explanation of its use, please refer to Appendix A, Service Object Method Library, of the IBM Tivoli Monitoring Workbench User's Guide Version 5.1.1, SH19-4571. Both legacy types will require additional dependencies within the Resource Model that will vary depending on the functionality required. These dependencies will be specified by the model developer and added through the use of the Workbench during the creation of the model. We have provided an example, available in Chapter 10, Creating a custom script Resource Model on page 411, demonstrating the use of the shell method that should help explain the dependency issues as well.
Custom scripts
The diagrams in Figure 4-10 on page 128 highlight only the components within the Windows and Java engines that are utilized for legacy support of the custom scripts. For greater engine detail, please refer to 4.3.1, ITM Engine components on page 120.
127


COM Objects
Custom Scripts
Figure 4-10 Logical components for Windows and Java custom scripts
DM Classic
The diagrams in Figure 4-11 highlight only the components within the Windows and Java engines that are utilized for legacy support of DM Classic collections. For greater engine detail, please refer to 4.3.1, ITM Engine components on page 120.


TMWService WMI APIs DM Classic Monitor Probes
Custom Scripts
WMI Provider DLLs
Java Virtual Machine (JVM) Launch (Class Loader) ILT Providers ILT Provider JNI Binary Library MBean Server MBean1 JMX ILT
Custom Scripts
ILT Manager for Java (WMI Provider DLL)
WMI (CIMOM)
COM Objects
Resource
Resource
Resource
Resource
Resource
Resource
Resource
Resource
Figure 4-11 Logical components for Windows and Java DM Classic
128
4.3.3 Touchpoint Service Layer

The Touchpoint Service Layer (TSL), formally referred to as the Manageability (M12) Model Specification, is Tivolis implementation of the CIM specification for Java engine only. The basic premise of the manageability model is that the manageability of a resource can be defined independently of the tool that manages it. This implies that the manageability of a resource is neutral both to the scale of the management tool, and the approach the tool takes to management. The same characteristics of a resource are appropriate for a low-end workgroup, or a high-end ASP solution. The model is implemented through a series of interface layers to segregate specific functionality. Management (M9) is the act of managing. It is the active process of monitoring, altering, and making decisions about a resource. Manageability (M12) defines what is manageable about a resource. It is a static definition of the properties of a resource that support management. The M12 model incorporates the WBEM initiatives through the use of the Common Information Model (CIM) meta schema for its modeling language.
4.3.4 CIM object definition

The M12 model uses the Common Information Model (CIM) meta schema for its modeling language. It has several characteristics that make it a good fit for the information the M12 model needs to express: UML compatible model IDL like syntax XML form of notation Easily extendable The CIM meta schema defines an information model that represents management information. An information model is a set of rules that define a method for structuring information. The tabular structure used by relational databases is an example of an information model. The rules of the model may be expressed as formal grammar, graphically, or through other means. CIM takes an object-oriented approach to structuring data; therefore, the meta schema contains rules for building an object model. The CIM object model has many characteristics in common with other object models, such as those supported by C++ or Java, but it also has many unique characteristics. Among the unique or unusual characteristics used by the M12 model are qualifiers and associations.
129
Qualifiers
The CIM meta model provides a mechanism for associating meta data with elements of the model. The meta data describes characteristics of the model element with which it is associated. This mechanism is a qualifier. Qualifiers allow the meta schema to be extended in a limited and controlled fashion. Qualifiers associate name-value pairs with part of the object model. For example, a property that specifies distance could have a units qualifier with the value "yards". The meta model defines a set of standard qualifiers. Some of these qualifiers are used by the meta model to control its own behavior, while others provide standard definitions for common user requirements. In addition, users of the model may define additional qualifiers as needed. Qualifiers provide a more flexible and controllable mechanism for adding semantics to an object model than other mechanisms, such as overloading property or class names. The M12 model defines a set of qualifiers that provide the "words" in the language a resource uses to communicate its management characteristics to a management tool. The CIM specification provides specific key words or qualifiers that can be utilized within the MOF file to more clearly define the class being described.
Standard CIM qualifiers

Key: Property qualifier that identifies the key property for the resource. This is used in a similar way to an index in a data table. Provider: Class/Property qualifier that identifies the library (class) that implements an Instance/Property interface in order to provide data about the resource. Description: Class/Property qualifier that describes the resource/property.
Non-standard CIM qualifiers

M12_Instrumentation(type.ILT class|mapping string|operation): In the M12 model, this qualifier is used to instruct the TSL about which ILT Manager (type) and which ILT (ILT class) are able to perform the specified operation and to pass data to them. type: This is always Java. ILT Class: This is the Java class that implements the ILT, and it must be specified with the complete package (with no .class extension). mapping string: This is a string whose meaning is known to the ILT.
130
Note: ILT implementations may choose to process the mapping string, such as for parameter substitution. Such substitutions use the parameters passed into the ILT call. For example, a mapping string passed into a get call has the instance identity and the target property available.
operation: The allowed operations are: Enum: Only when the qualifier is associated with the class Get: When the qualifier is associated with the class and property Invoke: When the qualifier is associated with the class and method
It is required that all classes have an M12_Instrumentation qualifier for the Enum operation. It is also required that an M12_Instrumentation qualifier for the Get be present for the following: Property level: It means that the property will be collected singularly (reference getProperty on page 132). Class Level: It means that all the properties that do not have any M12_Instrumentation qualifier associated will be collected within the same request (reference getMultipleProperties on page 132). It is also required that an M12_Instrumentation qualifier for the Invoke operation be present for every method. As an alternative, when the instrumentation string is the same for every method, a single M12_Instrumentation qualifier for the Invoke operation can be set at the class level.
4.3.5 Tivoli ILT Provider Interface

The term ILT Provider Interface refers specifically to the ILTInterface Java class that must be implemented by a custom ILT. This implementation ensures the appropriate methods will be supported to provide interfacing functionality from the TSL to the custom ILT. Essentially, the Launcher within the ITM Engine will load the custom ILT class, then make the ILTInterface class method calls to the custom ILT class. This will become more clear in Chapter 5, Engineering a Java ILT on page 137. The diagrams in Figure 4-12 on page 132 highlight only the components within the Windows and Java engines that are utilized for supporting ILTs. For greater engine detail, please refer to 4.3.1, ITM Engine components on page 120.
131


COM Objects
Custom Scripts
Figure 4-12 Logical components for Windows and Java ILTs
The ILTInterface class includes numerous methods to provide a comprehensive interface from the TSL to the pluggable ILT. These methods must be supported by the ILT, as they are invoked by the TSL. That is, once the ILT class has been loaded, the TSL invokes the interface methods within the custom ILT class.
enumerateInstances
The enumerateInstances method returns all M12ObjectIdentity objects that identify all the instances belonging to the class specified in the classPath.
getProperty
The getProperty method gets the value (in String format) of the specified property for the identified object.
getMultipleProperties
The getMultipleProperties method gets the value (in String format) of the specified properties for the identified object.
invokeMethod
The invokeMethod method invokes the specified method on the CIM instance belonging to the class specified in the classPath]
setProperty
The setProperty method is not invoked yet by the ITM Engine.
132
create
The create method is not invoked yet by the ITM Engine.
destroy
The destroy method is not invoked yet by the ITM Engine.
4.3.6 Tivoli Management Extensions for Java (TMX4J)

TMX4J is Tivoli's implementation of the Java Management Extensions (JMX) Specification. It implements all of the specified JMX interfaces and classes but has yet to be tested for complete conformance by the JMX Technology Compatibility Kit. Changes have been made to the ITM Engine between the 4.1 and the 5.1 product sets. The only JMX support embedded within the engine is that of an ILT wrapper, provided to load the MBeans to gather metrics only. Thus, custom integration does not require knowing the intricacies of the ILT Provider type, only knowing MBean technology. This may provide a more familiar environment for developers of Web-based e-commerce systems such as WebSphere Application Server It should be noted that the TMX4J is available through the IBM AlphaWorks web site at http://www.alphaworks.ibm.com/tech/TMX4J. There is no cost to download the Tivoli implementation package and acquiring the package is recommended to obtain greater detail on this subject.
133
134
Part 2
Part
Practical examples
In this part, we provide practical examples of how to create an IBM Tivoli Monitoring Version 5.1.1 solution for the following common problems: Monitoring with SNMP Monitoring log files Monitoring/Utilizing custom scripts File change monitoring (such as Web site or operating system crucial files) These specific solutions are not intended to be an out-of-the-box, all encompassing answer for each problem covered, but are intended to provide a basis that can be expanded and/or customized to suit your specific needs. They are also examples that can be used to create a new custom instrumentation for many problems that face IT administrators today.
135
136
Chapter 5.
Engineering a Java ILT

This chapter provides an in-depth discussion of the components required to engineer and implement a custom Provider of the type ILT for the Java platform. Specifically, these items are addressed as if they were implemented within the included ITSO_Sample Resource Model. The model can also be used as a template for creating your own ILT centric model. It should be noted, due to the complexities and intricacies of software development, this chapter in no way attempts to explain the syntax, use of, or nuances of the Java language, the Java development environment, or object oriented development terminology and methods. Therefore, it is highly recommended that these skill sets be developed prior to beginning work on a custom Provider. There are many available resources from IBM and Sun that can assist with gaining these skills.
137
5.1 Terminology
Many of the concepts and technologies discussed within this example are new to Tivoli Administrators. Therefore, we will define a few key terms as they are referenced throughout this chapter. Provider: As discussed in Chapter 4, Providers on page 109, this will refer to the conceptual component that operates as an instrument and provides operational metrics to the ITM Engine. ILT: The use of ILT refers to a specific Provider type. This type meets the requirements of the M12 specification discussed in Chapter 4, Providers on page 109 and is simply more specific than simply stating the Provider. ILT class: This is in reference to the Java class, written for the included example, that implements the ILTInterface class. Provider class: This is in reference to the Java class, written for the included example, that is instantiated within the ILT class and actually performs the metering of resources.
5.2 Planning and design

Though the purpose of this exercise is to demonstrate a custom ILT, the deployment of it to the Tivoli environment will require a complete Resource Model. Thus, during the planning phase of this Resource Model, the initial goal was defined as providing an ILT example that included a demonstration of how to create a base ILT, the required CIM definition, and provide Administrator configurable parameters that would be passed to the ILT. Though the planning and design phase followed a traditional top-down methodology, the development of the model was performed from the bottom up. The Managed Object Format (MOF) file was created first to define the CIM class, followed by the supporting ILT and Provider Java classes, and finally the Resource Model wrapper was created through the ITM Workbench. The planning section describes the components and details using the top-down approach. This is done to provide familiar terms and component references, then drill down into greater detail after topic introductions. The components addressed through this method include the Resource Model, CIM class, ILT class, and Provider class.
138
5.2.1 Resource Model

The requirements for this Resource Model are straight forward: Demonstrate the use of JavaScript within a Resource Model. Provide a parameter that will be used by the ILT and can be configured by Administrators through the Tivoli Desktop. Keep the Resource Model within the primary scope of this redbook and focus on instrumentation (not logging, events, or attributes). Ensure a good demonstration of supportability through easily traceable and consistent naming conventions throughout the Resource Model, CIM, and ILT. Implement base functionality that would permit a large number of readers to use the sample as a template. Provide a complete template by demonstrating the use of all supported ILT data types. Based on these requirements, it was determined that the model would be created initially through the ITM Workbench Resource Model Wizard under the name ITSO_Sample and in the standard model category for the redbook, ITSO_RMs.
5.2.2 CIM class

Based on the requirements determined from the planning of the Resource Model, it was obvious that a new CIM class had to be developed to provide the required information to the Resource Model. There are four specific requirements for the CIM definition that were determined: The CIM class must demonstrate the use of the Tivoli M12 qualifiers. The CIM class must include descriptor elements to support user-friendly CIM namespace browsing. The CIM class must include at least one property of each of the supported data types. The properties must follow a naming convention, defined as ITSO_SampleVar_<var_type>, to keep within the defined supportability requirement. A high-level CIM class definition was determined as follows: class ITSO_Sample ITSO_SampleVar_inst: The property designated as the class instance key ITSO_SampleVar_str: Property of the type string
Chapter 5. Engineering a Java ILT
139
ITSO_SampleVar_bln: Property of the type boolean ITSO_SampleVar_si8: Property of the type 8-bit signed integer ITSO_SampleVar_si16: Property of the type 16-bit signed integer ITSO_SampleVar_si32: Property of the type 32-bit signed integer ITSO_SampleVar_si64: Property of the type 64-bit signed integer ITSO_SampleVar_ui8: Property of the type 8-bit unsigned integer ITSO_SampleVar_ui16: Property of the type 16-bit unsigned integer ITSO_SampleVar_ui32: Property of the type 32-bit unsigned integer ITSO_SampleVar_r32: Property of the type 32-bit real ITSO_SampleVar_r64: Property of the type 64-bit real
5.2.3 ILT class

The ILT class exists to provide the dynamically pluggable interface between the TSL and the actual instrumentation Provider. Therefore, the ILT for this sample must meet the following requirements: The ILT class must follow the defined supportability requirement and should use the name ITSO_SampleIlt to be clearly associated with the CIM class and Provider it will be binding. Implement tracing functionality to better follow the supportability requirement. The ILT class must implement the required M12 functionality to: Support the ILTInterface specification. (All required methods for this interface are implemented within the ITSO_SampleIlt.) Demonstrate the retrieval of instance identification, parameters being passed from the Resource Model, and the values of the properties. (Only relevant methods will be coded for the ITSO_SampleIlt.) The ILT class should provide any internal private methods as needed to support the custom functionality.
5.2.4 Provider class

The Provider class exists to perform the physical instrumentation or provide interfacing to native binary libraries via Java Native Interface (JNI) calls. In the case of this sample, the Provider must meet the following requirements: The Provider class must follow the defined supportability requirement and should use the name ITSO_Sample to be clearly associated with the ILT class it will be instantiated by.
140
The Provider class must implement tracing functionality to better follow the supportability requirement. The Provider class must include methods to handle each of the following: Object creation: Performed by the method ITSO_Sample. Instance initialization and discovery. Methods to service each property of the CIM class by providing either a static or dynamic value. Note that providing a method to service the property does not mandate each property have its own set of service methods.
5.2.5 Component reference

In review of the aforementioned design requirements, the ITM Engine Logical Components diagram can be revisited. The components of the engine that will be utilized by the planned Resource Model within this chapter can be seen in Figure 5-1 on page 142. Those components that will not be used within the ITSO_Sample are presented in gray to de-emphasize their significance.
141

Custom Scripts
ILT Providers
ILT JNI Native Binaries
JMX ILT MBean Server MBean(s)
Resource
Resource
Resource
Figure 5-1 Java ITM Engine logical components
5.3 Implementing
The implementation phase of the design includes a variety of efforts as well as a variety of tools. As mentioned in 5.2.5, Component reference on page 141, the implementation was handled in a bottom-up fashion due to each layer being dependent on the layer below. Therefore, the four components to be created below are presented in the order of development: The Managed Object Format (MOF) file ITSO_Sample.mof was developed with a text editor, but compiled and imported with mofcomp. The Java class for the ILT ITSO_SampleIlt.java was developed with a text editor and the IBM JDK 1.3.1. The Provider class, ITSO_Sample.java, was developed with a text editor and the IBM JDK 1.3.1.
142
The Resource Model ITSO_Sample.dmjsws was developed with the ITM Workbench.
5.3.1 Managed Object Format (MOF)

In the ITSO_Sample, we have implemented only the core requirements for the object definition. This was to ensure the sample was easy to understand as well as easily customizable. In many cases, additional descriptors may be required to ensure the object behaves in a precise and predictable manner.
Commenting MOF files

The use of comments within the MOF file is acceptable and, as demonstrated, quite helpful in the maintenance and enhancement of custom classes. This is reflected with the creation of a document history section within the header comments of the MOF file shown in Example 5-1.
Example 5-1 ITSO_Sample.mof
//---------------------------------------------------------------------------// // ITSO_Sample.mof // // Description: // This file is a textual definition of the ITSO_Sample CIM class. // // History: // Date Author Description // -------- ------------------ -----------------------------------------// 04/15/03 ITSO Redbook Team Original file. // //----------------------------------------------------------------------------
CIM qualifiers
The number of qualifiers implemented was kept to a minimum, again to meet the functional requirements while maintaining a clean and easy to understand design. The qualifiers used are presented in the order in which they appear in the MOF file. For additional detail on the purpose of each qualifier, please refer to Chapter 4, Providers on page 109.
Description
The Description qualifier is used throughout the ITSO_Sample class definition and is highly recommended as a best practice for both classes and class properties. This is because the description information can be viewed by CIM browsing utilities once the MOF file is compiled into a localized CIM repository. A
143
sample of the Description qualifier as used for the class description itself is shown in Example 5-2.
Example 5-2 ITSO_Sample.java: description qualifier
[ Description ("ITSO Sample: This sample was created to provide to help " "clarify the creation of a custom ILT and Provider. There " "are many details that have not been included, incuding " "additional M12 qualifiers within the MOF. However, the " "core functionality does provide a complete model from " "which to work."),
In this case, the MOF file was loaded into the Windows CIM repository during development and was browsed through the ITM Workbench. The Description qualifiers are viewable from the Dynamic Model dialog boxs Show Description feature. Notice in Figure 5-2 that the description for the class and the class properties are all displayed. This is extremely useful when a CIM class will be implemented by multiple Resource Model developers.
Figure 5-2 ITM Workbench: about selected class
Provider
The Provider qualifier is used within the ITSO_Sample class definition to define the library (class) that will implement an instance interface to the sample Provider class. As the ITM Java engine has the TSL embedded, we will be using the M12JavaProvider in Example 5-3.
Example 5-3 ITSO_Sample.java: Provider qualifier
provider("com.tivoli.dmunix.ep.touchpoint.cimom.ifc.M12JavaProvider"),
144
M12_Instrumentation
The M12_Instrumentation was implemented within the ITSO_Sample class only and not at the class property level. The M12 specification requires that all classes have an Enum operation. This tells the class loader which class (in this case, ITSO_SampleIlt) to associate with the enumeration functionality of the instrumentation. We have additionally provided a Get operation for the class to specify which class will be associated with all non-specified properties, that is, it is possible to associate specific properties within the class to specific classes on an individual basis, which will allow the singular collection of the property data through the class method getProperty. In our ITSO_Sample class, this was not a concern, and collection was routed through getMultipleProperties method by providing the default Get operation within the M12 qualifier shown in Example 5-4.
Example 5-4 ITSO_Sample.java: M12_Instrumentatoin qualifier
M12_Instrumentation { "Java.com.ibm.tivoli.monitoring.ITSO_Sample.ITSO_SampleIlt | | ENUM", "Java.com.ibm.tivoli.monitoring.ITSO_Sample.ITSO_SampleIlt | | GET"} ]
Key
The key property qualifier is used within the ITSO_Sample class itself to define the property ITSO_SampleVar_inst as the primary key or index to the class. In the case of the sample, this key represents the instance of the class. A sample of the Description qualifier is shown in Example 5-5.
Example 5-5 TSO_Sample.java: key qualifier
class ITSO_Sample { // Attribute, Instance Count. [ Description("The ITSO_SampleVar_inst property defines the instance of " "the provider." ), key ] sint32 ITSO_SampleVar_inst;
5.3.2 ILT Java class

The ILT class, ITSO_SampleILT, is the interface between the TSL of the ITM Engine and the custom Provider. The actual interfacing is handled through the implementation of the M12 Public Operations as defined by the ILTInterface class. There are a variety of design strategies that can be implemented within the required methods; however, the end goal to support multiple instances remains the same.
145
To parallel a real-world example, if the CIM class has been designed to represent a Network Interface, the ILT class would be created to handle the initialization of the Provider class(es) and incoming data requests from the ITM Engine through the supported ILTInterface methods, determine which CIM properties need to be acquired from the Provider through M12 method calls, and perform the acquisition through the appropriate Provider instances. Specifically, in the case of the Network Interface reference, the ILT would receive the instance and property requests through the ILTInterface methods as specified through the M12 qualifiers in the MOF, then perform the acquisition through the appropriate Provider instance for any defined properties such as link up or down, bytes per second sent and received, and interface type for the Ethernet0 instance.
Commenting Java files

Comments have been implemented within the Java file, as demonstrated in Example 5-6. As with the MOF file, comments are quite helpful in the maintenance and enhancement of custom classes and are always a best practice in the software development arena.
Example 5-6 ITSO_SampleIlt.java: comment header
//-----------------------------------------------------------------------------// // ITSO_SampleIlt.java // // Description: // This file is the ITSO_Sample Instrumentation Library Type (ILT) // implementation. This is the class instantiated by the "touchpoint" // layer. This class will execute methods in the "ITSO_Sample.java" file, // which is the physical "provider" and performs the actual data // acquisition. // // Various classes are referenced throughout this file. ILT Supported // Classes, which are documented, in the IBM Tivoli Monitoring Workbench Users Guide // Version 5.1.1, SH19-4571, include: // M12ClassPath // M12IdentityElement // M12ObjectIdentity // M12PreportySet // M12Exception // ParameterSet // ParameterSetList // // History: // Date Author Description // -------- ------------------ -----------------------------------------// 04/15/03 ITSO Redbook Team Original file. //
146
//------------------------------------------------------------------------------
Java package
The naming standard implemented by Tivoli PAC developers is that the Java package for the ILT be in the path com.ibm.tivoli.monitoring. This naming convention was implemented for the ITSO_Sample and can be seen in both the ILT and Provider classes. This ensures that all required classes for the ILT are handled by the same ITM Engine loader, providing consistent class access. The package declaration within both immediately follows the comment header and can be seen in Example 5-7.
Example 5-7 ITSO_SampleIlt.java: package declaration
//---------------------------------------------------------------------------package com.ibm.tivoli.monitoring.ITSO_Sample;
Java imports
Various Java classes were utilized within the sample. These classes were declared through the standard Java import statement, as shown in Example 5-8.
Example 5-8 ITSO_SampleIlt.java: import declarations
import import import import import com.ibm.tivoli.monitoring.ITSO_Sample.ITSO_Sample; com.tivoli.dmunix.ep.touchpoint.base.*; com.tivoli.javautils.Trace; java.util.Enumeration; java.util.Vector;
The first import, com.ibm.tivoli.monitoring.ITSO_Sample.ITSO_Sample, allows for the referencing of the Provider class ITSO_Sample. This class is defined in the file ITSO_Sample.java and is defined as part of the same package as the ILT class. The relevant jar file for this import is ITSO_Sample.jar, of which this file is a part. The second import, com.tivoli.dmunix.ep.touchpoint.base.*, supports the ILT Interface class as well as the M12 ILT Public Operations, which are well documented in Appendix D Instrumentation Library Type Interface (ILT), in the IBM Tivoli Monitoring Workbench User's Guide Version 5.1.1, SH19-4571. The relevant jar file for this import is dm_m12.jar. The third import, com.tivoli.javautils.Trace, supports writing to the trace_dmxengine.log file via the Trace class. The relevant jar file for this import is javautils.jar.
147
The fourth import, java.util.Enumeration, supports the Enumeration class, which supports the creating of a series of elements. This is viewable in the declaration of the enumerateInstances method. The fifth import, java.util.Vector, supports the Vector class which allows for dynamically sized lists through the use of Java pointers. In the case of our sample, it provides the means to obtain the list of parameters passed from the ITM Engine.
ILT interface implementation

The ITSO_Sample class implements the ILTInterface class interface, as demonstrated in Example 5-9.
Example 5-9 TSO_SampleIlt.java: class implementation
public class ITSO_SampleIlt implements ILTInterface
Supporting class methods

A creator method, ITSO_SampleIlt, was included in the class, as seen in Example 5-10. This method is automatically executed at the instantiation of the ILT sample by the ITM Engine. Its purpose is to perform any class initialization work required.
Example 5-10 ITSO_SampleIlt.java: creator
public ITSO_SampleIlt() { pitso_sample = new ITSO_Sample(); trace = Trace.getTraceInstance(); }
ILT public operations (methods)

To correctly support the interfacing of our ILT with the M12 specification, all public operations (methods) should be implemented. Not all ILTs may require operational code within the methods. Again, in an attempt to create an easily understandable template, all methods were put in place to support the interface and commented, though code has only been written in methods that mandated specific functionality. Methods that were not mandated for this sample had tracing calls added to permit detailed debugging of Resource Models through the trace_dmxengine.log file.
148
getProperty
This operation, shown in Example 5-11, was implemented with the intent that if an M12_Instrumentation qualifier was added to any property within the MOF file, those individual properties would be obtained through this method. As the M12_Instrumentation qualifier was not added to individual properties within the ITSO_Sample.mof, this method is not utilized by the engine. We will however, provide an explanation, as it would be the most likely implemented function in custom ILTs.
Example 5-11 ITSO_SampleIlt.java: getProperty method
public String getProperty( M12ObjectIdentity m12objectidentity, String sPropertyName, String sMapping, ParameterSet parameterset ) throws M12Exception { try { M12IdentityElement m12identityelement = m12objectidentity.getScopingPath()[0]; M12PropertySet m12propertyset = m12identityelement.getIdentity(); // Determine which instance is being checked by the // Management Layer. String sKey = m12propertyset.getProperty("ITSO_SampleVar_inst"); trace.log(3, "ITSO_SampleIlt", "getProperty: called for ITSO_SampleVar_inst " + sKey); // Get the attributes being checked by the Management Layer. // Get the current attribute values. String sValue = getITSOAttribute(sKey, sPropertyName); trace.log(3, "ITSO_SampleIlt", "getITSOAttribute: " + sPropertyName + " = " + sValue); return sValue; } catch(Exception exception) { trace.exception("ITSO_SampleIlt", "getProperty", exception); M12Exception m12exception = new M12Exception(exception); throw m12exception; } }
149
This operation, shown in Example 5-12, was implemented to support the handling of multiple properties, as the MOF file has a class level M12_Instrumentation qualifier. This class level qualifier designates the ITSO_SampleILT class as the handler of all properties without individual instrumentation statements.
Example 5-12 ITSO_SampleIlt.java: getMultipleProperties method
public M12PropertySet getMultipleProperties( M12ObjectIdentity m12objectidentity, Vector vPropertyList, String sMapping, ParameterSet parameterset ) throws M12Exception { try { M12IdentityElement m12identityelement = m12objectidentity.getScopingPath()[0]; M12PropertySet m12propertyset = m12identityelement.getIdentity(); // Determine which instance is being checked by the // Management Layer. String sKey = m12propertyset.getProperty("ITSO_SampleVar_inst"); M12PropertySet m12propertyset1 = new M12PropertySet(); trace.log(3, "ITSO_SampleIlt", "getMultipleProperty: called for ITSO_SampleVar_inst " + sKey); for(int i = 0; i < vPropertyList.size(); i++) { // Get the property being checked by the Management Layer. String sProperty = (String)vPropertyList.elementAt(i); // Get the current attribute values. String sValue = getITSOAttribute(sKey, sProperty); m12propertyset1.setProperty(sProperty, sValue); } trace.log(3, "ITSO_SampleIlt", "getMultipleProperty: returning " + WriteBuffer(m12propertyset1)); return m12propertyset1; } catch(Exception exception) { trace.exception("ITSO_SampleIlt", "getMultipleProperty", exception); M12Exception m12exception = new M12Exception(exception); throw m12exception;
150
} }
enumerateInstances
This operation, shown in Example 5-13, was implemented to support the enumeration of instances of the CIM class, that is, this function will determine how many instances of the monitored object exist and will handle the appropriate configuration of those instances as well as return the count.
Example 5-13 ITSO_SampleIlt.java: enumerateInstances method
public Enumeration enumerateInstances( M12ClassPath m12classpath, String sMapping, ParameterSet parameterset ) throws M12Exception { try { // Variable Declaration. StringBuffer stringbuffer = new StringBuffer(); Vector vector = new Vector(); //-----------------------------------------------------------------// Get the parameters from the caller. // We are obtaining the parameters prior to declaring instances so // we can configure an instance for each parameter. //-----------------------------------------------------------------Enumeration enumeration = parameterset.parametersNames(); Vector vParam = (Vector)parameterset.getParam("ITSO_ArrayGUI"); if(vParam == null) { trace.log(1, "ITSO_SampleIlt", "enumerateInstances: no parameters found"); return null; } // Process the ITSO_ArrayGUI parameter. String asITSOArrayGui[] = new String[vParam.size()]; for(int iIndex = 0; iIndex < vParam.size(); iIndex++) { // Get the string array element from the vector element. asITSOArrayGui[iIndex] = (String)vParam.elementAt(iIndex); trace.log( 3, "ITSO_SampleIlt", "enumerateInstances: asITSOArrayGui[" + iIndex + "] = " + asITSOArrayGui[iIndex]); } //-----------------------------------------------------------------// Acquire a vector (pointer) from the calling ILT Manager.
151
// This section handles the registration of instances of this // Instrumentation. //-----------------------------------------------------------------int aiInst[] = pitso_sample.getITSO_Instances( asITSOArrayGui ); if(aiInst == null) { trace.log(1, "ITSO_SampleIlt", "enumerateInstances: no instances found"); return null; } for(int jIndex = 0; jIndex < aiInst.length; jIndex++) { trace.log( 3, "ITSO_SampleIlt", "enumerateInstances: aiInst[" + jIndex + "] = " + aiInst[jIndex]); M12PropertySet m12propertyset = new M12PropertySet(); m12propertyset.setProperty( "ITSO_SampleVar_inst", String.valueOf(aiInst[jIndex]) ); M12IdentityElement m12identityelement = new M12IdentityElement( m12classpath.getClassName(), m12classpath.getNameSpace(), m12propertyset); vector.add( new M12ObjectIdentity( new M12IdentityElement[] { m12identityelement } ) ); } return vector.elements(); } catch(Exception exception) { trace.exception("ITSO_SampleIlt", "enumerateInstances", exception); M12Exception m12exception = new M12Exception(exception); throw m12exception; } }
setProperty
This method was implemented for explanatory purposes only, as it is included in the M12 specification, but is not yet supported. Therefore, only tracing elements were included within the code and it will not be presented here.
invokeMethod
This method actually provides two interfaces. Both were implemented for explanatory purposes only, as they are included in the M12 specification. These methods are supported; however, due to time constraints, the invocation of class methods was not pursued for this sample. Therefore, only tracing elements were included within the code and it will not be presented here.
152
create
destroy
ILT supported classes

The implementation of the M12 interfacing for this ILT requires that various ILT support classes be used. Table 5-1 discusses the various classes and their role within the sample.
Table 5-1 ILT supported classes
ILT supported classes Implementation notes
M12ClassPath
This identifies the class whose instances have to be enumerated or whose method is to be invoked. This is implemented as a passed parameter to the ILT Public Operation methods and is used to identify the instance of the resource. This is implemented within ILT Public Operation methods and is used to identify the instance of the resource. This is obtained through the M12ObjectIdentity. This is implemented within ILT Public Operation methods and is used to retrieve property values for the instance. This is obtained through the M12IdentityElement. This is implemented through ILT Public Operation methods to define the exception type thrown. This is implemented through implemented ILT Public Operation methods and is used to receive parameters passed by the client. This class was not utilized in this sample.
M12ObjectIdentity
M12IdentityElement
M12PropertySet
M12Exception
ParameterSet
ParameterSetList
153
Custom methods
These methods are not part of the required ILT interfacing and are only used from a utility perspective. They allow for cleaner code as well as a single point of management for common functions.
getITSOAttribute
This method, shown in Example 5-14, was developed as a centrally manageable function to handle the actual calling of the methods within the Provider instances. The function is passed the reference to the instance key and the class property, both specified in the CIM definition.
Example 5-14 ITSO_SampleIlt.java: getITSOAttribute method
private String getITSOAttribute( String sValue, String sProperty ) throws Exception { //---------------------------------------------------------------------// // MOF Declared Types // // There is an "if" structure for each of the variable types that this // sample supports. // //---------------------------------------------------------------------int iIndex = (new Integer(sValue)).intValue(); //---------------------------------------------------------------------// string ITSO_SampleVar_str //---------------------------------------------------------------------if(sProperty.equals("ITSO_SampleVar_str")) { String sReturn = new String( pitso_sample.getITSO_SampleVar_str(iIndex) ); return sReturn; } //---------------------------------------------------------------------// boolean ITSO_SampleVar_bln //---------------------------------------------------------------------if(sProperty.equals("ITSO_SampleVar_bln")) { Boolean blnVar = new Boolean(pitso_sample.getITSO_SampleVar_bln(iIndex)); return blnVar.toString(); }
154
//---------------------------------------------------------------------// sint8 ITSO_SampleVar_si8 // sint16 ITSO_SampleVar_si16 // sint32 ITSO_SampleVar_si32 // sint64 ITSO_SampleVar_si64 //---------------------------------------------------------------------if( (sProperty.equals("ITSO_SampleVar_si8")) || (sProperty.equals("ITSO_SampleVar_si16")) || (sProperty.equals("ITSO_SampleVar_si32")) || (sProperty.equals("ITSO_SampleVar_si64")) ) { Integer intVar = new Integer(pitso_sample.getITSO_SampleVar_si(iIndex)); return intVar.toString(); } //---------------------------------------------------------------------// uint8 ITSO_SampleVar_ui8 // uint16 ITSO_SampleVar_ui16 // uint32 ITSO_SampleVar_ui32 //---------------------------------------------------------------------if( (sProperty.equals("ITSO_SampleVar_ui8")) || (sProperty.equals("ITSO_SampleVar_ui16")) || (sProperty.equals("ITSO_SampleVar_ui32")) ) { Integer intVar = new Integer(pitso_sample.getITSO_SampleVar_ui(iIndex)); return intVar.toString(); } //---------------------------------------------------------------------// real32 ITSO_SampleVar_r32 // real64 ITSO_SampleVar_r64 //---------------------------------------------------------------------if( (sProperty.equals("ITSO_SampleVar_r32")) || (sProperty.equals("ITSO_SampleVar_r64")) ) { Double dblVar = new Double(pitso_sample.getITSO_SampleVar_r(iIndex)); return dblVar.toString(); } //---------------------------------------------------------------------// Unknown property. //---------------------------------------------------------------------else { throw new Exception(sProperty + ": unknown property"); }
155
WriteBuffer
This is essentially a utility method that was created for the purpose of easily dumping values from a passed M12PropertySet class to a String object that is returned to the caller.
5.3.3 Provider Java class

The Provider class ITSO_Sample handles class instance initialization, management, and initialization of any private data members relevant to the class instance, and methods to provide values for specific CIM properties to the instantiating ILT class. Therefore, this class is a completely custom class designed around a specific use as designed by the CIM. Its functionality has been segregated from the aforementioned ILT class, ITSO_SampleILT, as it is designed to be instantiated for each CIM object reference. If the CIM class has been designed to represent a Network Interface Card (NIC), the Provider would be created to acquire information on the NIC. In such a case, there may be multiple NICs in the host that this Resource Model is running on. Thus, the Provider would be designed to handle these instances through the initialization method and would have internal data members (properties) or additional classes that are instance specific. With any development situation, there are numerous ways to handle such issues. The complexities associated with more advanced instance handling could make this sample quite difficult for the beginning ILT developer to follow. Additionally, making the sample excessively instance oriented may make it difficult to implement for more basic purposes. Thus, the ITSO_Sample has therefore been simplified to provide the capabilities of referencing instances as a starting point for custom development through simple indexing or key values in the CIM class. This Provider class has been created to provide hardcoded numeric values and slightly dynamic strings. The code within the methods can be as advanced as required to fulfill the needs of the ILT. Optionally, as is the case with many of the resources models shipped with ITM, the methods can utilize the JNI API and implement platform specific binary libraries. Such libraries are typically developed in C or C++ and are done so for performance reasons. Such development is typically outside the scope of most administrators job functions. The use of JNI is well suited for access to platform dependent binary libraries using APIs not available in Java. For example, in the case of file permissions, UNIX platforms typically implement them in the familiar rwx-rwx-rwx format while
156
the Windows platform handles file permissions in a different way. Therefore, Java offers the least common denominator among the supported platforms. However, since ITM is monitoring a specific platform, that which the model is running on, it is required to access some low level features related to the specific monitored platform. Here, JNI support the platform integration by using a library to access C/C++ code that performs API calls that are operating system specific.
Commenting Java files

Comments have been implemented within the Java file, as demonstrated by the file header shown in Example 5-15. As with the previous files, comments are quite helpful in the maintenance and enhancement of custom classes and are always a best practice in the software development arena.
Example 5-15 ITSO_Sample.java: comment header
//-----------------------------------------------------------------------------// // ITSO_Sample.java // // Description: // This file is the ITSO_Sample Provider to the ILT. This can perform the // actual the actual data acquisition, call other classes, or via JNI // perform calls to "native" binaries. // // History: // Date Author Description // -------- ------------------ -----------------------------------------// 04/15/03 ITSO Redbook Team Original file. // //------------------------------------------------------------------------------
Java package
The same package naming convention, com.ibm.tivoli.monitoring, was implemented for the ITSO_SampleILT class and has been implemented within this class. This ensures that all required classes for the ILT are handled by the same ITM Engine loader, providing consistent class access. The package declaration within this class immediately follows the comment header and can be seen in Example 5-16.
Example 5-16 ITSO_Sample.java: package declaration
//---------------------------------------------------------------------------package com.ibm.tivoli.monitoring.ITSO_Sample;
157
Java imports
Various Java classes were utilized within the sample Provider. These classes were declared through the standard Java import statement shown in Example 5-17.
Example 5-17 ITSO_Sample.java: import statements
import com.tivoli.javautils.Trace; import java.util.*;
Custom methods
These methods exist to represent the CIM object ITSO_Sample from a software perspective, not from a physical attribute perspective. This means that a method exists within the Provider class to handle class instance initialization, and access to any private data members relevant to each class instance. These routines are completely custom to the class and will most likely not exist in your Provider implementation. They will realistically be replaced with more appropriate get property methods (as required by your Provider specification), but will still be referenced from within your ILT class.
ITSO_Sample
This is the class creator that supports the initialization of the Provider class instance. In the case of this Provider, only one instance is created by the ITSO_SampleILT. This creator method performs no specialized functions other than to initialize the Trace class, as shown in Example 5-18.
Example 5-18 ITSO_Sample.java: Creator method
public ITSO_Sample() { trace = Trace.getTraceInstance(); }
getITSO_Instances
This method, as shown in Example 5-19 on page 159, retrieves an array of values of the variable ITSO_SampleVar_instr which, being designated as the class key, are used for instance referencing by the M12 layer. The ITSO_SampleILT class method enumerateInstances call this getITSO_Instances method to obtain this instance array and register the values to the M12PropertySet class via the setProperty method.
158
Example 5-19 ITSO_Sample.java: getITSO_Instance method

public synchronized int[] getITSO_Instances( String asParams[] ) { // The instances will be referenced by number to keep it simple. trace.log(3, "ITSO_Sample", "getITSO_Instances asParams.length=" + asParams.length); int[] aiInst = new int[asParams.length]; for(int iIndex = 0; iIndex < asParams.length; iIndex++) { // Get the string array element from the vector element. trace.log(3, "ITSO_Sample", "getITSO_Instances iIndex=" + iIndex); aiInst[iIndex] = iIndex; trace.log(3, "ITSO_Sample", "getITSO_Instances aiInst[" + iIndex + "]" + aiInst[iIndex]); } return aiInst; }
getITSO_SampleVar_str
This method, as shown in Example 5-20, provides a retrieval of the value for the string variable ITSO_SampleVar_str for the instance passed. The ITSO_SampleILT class method getITSOAttribute determines which variables are to be obtained through this method.
Example 5-20 ITSO_Sample.java: getITSO_SampleVar_str method
public static synchronized String getITSO_SampleVar_str(int iIndex) { // Add logic to check the correct instance (index) of the resource. // For this example, to demonstrate differences based on instances, // we are building a string that includes the index number. String sReturn = "iIndex_" + iIndex; return sReturn; }
getITSO_SampleVar_si
This method, as shown in Example 5-21 on page 160, provides a retrieval of the value for all of the signed integer variables designated ITSO_SampleVar_si for the instance passed. The ITSO_SampleILT class method getITSOAttribute determines which variables are to be obtained through this method.
159
Example 5-21 ITSO_Sample.java: getITSO_SampleVar_si method

public static synchronized int getITSO_SampleVar_si(int iIndex) { // Add logic to check the correct instance (index) of the resource. return -1; }
getITSO_SampleVar_ui
This method, shown in Example 5-22, provides a retrieval of the value for all of the unsigned integer variables designated ITSO_SampleVar_ui for the instance passed. The ITSO_SampleILT class method getITSOAttribute determines which variables are to be obtained through this method.
Example 5-22 ITSO_Sample.java: getITSO_SampleVar_ui method
public static synchronized int getITSO_SampleVar_ui(int iIndex) { // Add logic to check the correct instance (index) of the resource. return 1; }
getITSO_SampleVar_r
This method, shown in Example 5-23, provides a retrieval of the value for all of the real or floating point variables designated ITSO_SampleVar_r for the instance passed. The ITSO_SampleILT class method getITSOAttribute determines which variables are to be obtained through this method.
Example 5-23 ITSO_Sample.java: getITSO_SampleVar_r method
public static synchronized double getITSO_SampleVar_r(int iIndex) { // Add logic to check the correct instance (index) of the resource. return 3.14; }
getITSO_SampleVar_bln
This method, shown in Example 5-24 on page 161, provides a retrieval of the value for all of the boolean variables designated ITSO_SampleVar_bln for the instance passed. The ITSO_SampleILT class method getITSOAttribute determines which variables are to be obtained through this method.
160
Example 5-24 ITSO_Sample.java: getITSO_SampleVar_bln method

public static synchronized boolean getITSO_SampleVar_bln(int iIndex) { // Add logic to check the correct instance (index) of the resource. return true; }

Resource Models are the encapsulation of various ITM Engine configuration files, logic scripting files, and dependency files. In this discussion, each of these items will be discussed as they were implemented within this model.
General settings
These items were configured through the ITM Workbench General Setting dialog box, as shown in Figure 5-3.
Figure 5-3 ITM Workbench: General Settings
When the General Settings configuration was completed, the ITM Workbench engine automatically added the service class method calls to SetModelName, SetProfileName, and SetCycleTime along with their associated parameters to the JavaScript function SetDefaultConfiguration, as demonstrated in Example 5-25 on page 162.
161
Example 5-25 ITSO_Sample.dmjsws: General info

// General info section //<<GENERAL_INFO>> Svc.SetModelName ("ITSO_Sample"); Svc.SetProfileName ("1324421"); Svc.SetCycleTime (60); //<<\GENERAL_INFO>>
Dynamic Model
The Dynamic Model components of a Resource Model allow for the acquisition of data through various methods. The method of interfacing to an ILT is through the CIMOM. In this example, the CIM class ITSO_Sample was selected from the namespace root\default, as shown in Figure 5-4. .
Figure 5-4 ITM Workbench: Dynamic Model
An alias was then defined, ITSO_Sample, for use by the various Service calls within the JavaScript. The use of an alias simplifies the service method parameters. Additionally, the CIM class properties shown in Table 5-2 on page 163 were selected for use within the JavaScript within the Resource Model.
162
Table 5-2 CIM class properties

Class property Property type
ITSO_SampleVar_inst ITSO_SampleVar_str ITSO_SampleVar_bln ITSO_SampleVar_si8 ITSO_SampleVar_si16 ITSO_SampleVar_si32 ITSO_SampleVar_si64 ITSO_SampleVar_ui8 ITSO_SampleVar_ui16 ITSO_SampleVar_ui32 ITSO_SampleVar_r32 ITSO_SampleVar_r64
Numeric String Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric Numeric
When the Dynamic Data CIM selection was completed, the ITM Workbench engine automatically added the service class method call to DefineClass and the associated parameters to the JavaScript function SetDefaultConfiguration as shown in Example 5-26. Notice that the all numeric properties are passed as a single parameter as is the string property.
Example 5-26 ITSO_Sample.dmjsws: Dynamic info
// Dynamic Model section //<<DATA_INFO>> Svc.DefineClass ("CIM", "ITSO_Sample", "ROOT\\DEFAULT:ITSO_Sample", "", "ITSO_SampleVar_ui16,ITSO_SampleVar_si16,ITSO_SampleVar_r64,ITSO_SampleVar_r32, ITSO_SampleVar_bln,ITSO_SampleVar_si8,ITSO_SampleVar_ui32,ITSO_SampleVar_si64,I TSO_SampleVar_inst,ITSO_SampleVar_si32,ITSO_SampleVar_ui8", "ITSO_SampleVar_str", "None", "", 0, 1); //<<\DATA_INFO>>
Parameters
For this example, as shown in Figure 5-5 on page 164, a single parameter was used to demonstrate how a parameter list provided to a Tivoli Administrator could be used to alter the operation of the ILT. In this case, the parameter ITSO_ArrayGUI was created as the type String List with the default values added: Mike, Craig, and Kiyo.
163
Figure 5-5 ITM Workbench: parameters
When the parameter was added through the Workbench GUI, the ITM Workbench engine automatically added the service class method call DefineStrParameter and the associated parameters to the JavaScript function SetDefaultConfiguration, as shown in Example 5-27.
Example 5-27 ITSO_Sample.dmjsws: Parameters
// Parameters section //<<PARAMETERS_INFO>> Svc.DefineStrParameter ("ITSO_ArrayGUI", "Mike,Craig,Kiyo"); //<<\PARAMETERS_INFO>>
Note: It is possible to make dynamic lists not available to an Administrator via the Tivoli Desktop. This can be useful to allow a Resource Model to dynamically change its operation. To implement a hidden parameter, add a call to the Svc.DefineStrParameter method within the SetDefaultConfiguration function of the Resource Model by directly coding it in the script. Do not add it through the tree-view by right-clicking. Adding it through the tree-view makes it visible to the Administrators, while directly coding it does not. Thus, adding the call to the JavaScript will enable the parameter, but will not provide the GUI requirement, thus hiding it from the Administrator.
Dependencies
The dependencies for this Resource Model include a MOF file containing the class definition and a jar file containing the ILT and Provider classes. This example was created specifically for the Java platforms supported by ITM. Since the platforms supported by this model were enabled in the Resource Models General Settings, both the ITSO_Sample.mof and the ITSO_Sample.jar files were added to the All dependency tab.
164
Note: If this model were ported to Windows, a few items need to be considered. First, there is a JRE dependency in the ITM Engine that executes the Java ILT and Provider code. Therefore, a Windows JRE must be installed on the client. Second, the Windows platform has slightly different MOF requirements. Therefore, the MOF file used in this example would have to be added under every supported operating system so that the Windows specific MOF file can be included under the Windows leaf.
JavaScript
The script within the Resource Model was originally created through the ITM Workbench Resource Model Wizard. This provided a good shell script that was modified for our needs. This section will discuss only the changes made to the JavaScript.
SetDefaultConfiguration
In this Resource Model function, shown in Example 5-28, the customization was primarily done through the aforementioned ITM Workbench engine-generated script. The only note-worthy additions beyond those changes were two calls to the service objects Trace methods. This permitted tracing of the Resource Model within the trace_dmxengine.log file, in an effort to allow end users to better understand the models operation.
Example 5-28 ITSO_Sample.dmjsws: SetDefaultConfiguration function
function SetDefaultConfiguration (Svc) { Svc.Trace (0, "ITSO_Sample: SetDefaultConfiguration - start" ); // General info section //<<GENERAL_INFO>> Svc.SetModelName ("ITSO_Sample"); Svc.SetProfileName ("105510562"); Svc.SetCycleTime (60); //<<\GENERAL_INFO>> // Thresholds section //<<THRESHOLDS_INFO>> //<<\THRESHOLDS_INFO>> // Parameters section //<<PARAMETERS_INFO>> Svc.DefineStrParameter ("ITSO_ArrayGUI", "Mike,Craig,Kiyo"); //<<\PARAMETERS_INFO>> // Note:In the DefineClass method, we create an ALIAS of "ITSO_Sample" //to the actual CIM Namespace declaration for our class.
165
//This will be referenced by the AssociateParameterToClass //method later. // // Dynamic Model section //<<DATA_INFO>> Svc.DefineClass ("CIM", "ITSO_Sample", "ROOT\\DEFAULT:ITSO_Sample", "", "ITSO_SampleVar_ui16,ITSO_SampleVar_si16,ITSO_SampleVar_r64,ITSO_SampleVar_r32,ITSO_SampleVar_u i32,ITSO_SampleVar_si8,ITSO_SampleVar_bln,ITSO_SampleVar_si64,ITSO_SampleVar_ui8,ITSO_SampleVar _si32,ITSO_SampleVar_inst", "ITSO_SampleVar_str", "None", "", 0, 1); //<<\DATA_INFO>> // Event definition section //<<EVENTS_INFO>> //<<\EVENTS_INFO>> // Logging definition section //<<LOGGING_INFO>> //<<\LOGGING_INFO>> // Place your additional intializing code below Svc.Trace (0, "ITSO_Sample: SetDefaultConfiguration - end" ); return (0); }
Init
The Init function, shown in Example 5-29 on page 167, provides the initialization requirements for the Resource Model. In the case of the ITSO_Sample, very little initialization was required. In addition to the trace file logging we provided, we performed our variable initialization for the function, followed by our requirements. In the requirements, we did have to address the passing of configuration parameters to the ILT. In the case of the Resource Model parameter ITSO_ArrayGUI, which is passed from the ITM Engine during the initial Resource Model configuration to the ILT, we had to verify that it does contain at least one string value. Without any string values, our ILT would not be able to initialize. Therefore, within the initialization function, we obtain the dimension of, or number of values within, the array ITSO_ArrayGUI. The obtained dimension is validated to ensure it is greater than zero. If the dimension is acceptable, our next core function is the call to the AssociateParameterToClass method, which will register the Resource Model parameter within the ITM Engine and allow our instantiated ILT class to look up and obtain the parameter and its contents. If the dimension is not acceptable, that is, it is equal to zero, we return with the error code value 801. The error codes used by the ITM Engine are available in Chapter 6, Resource Model Troubleshooting, of the IBM Tivoli Monitoring Workbench User's Guide Version 5.1.1, SH19-4571 and should always be used within the Resource Model.
166
Example 5-29 ITSO_Sample.dmjsws: Init function

function Init(Svc) { Svc.Trace (0, "ITSO_Sample: Init - start" ); // Variable Initialization var dimension = 0; var t=0; // Process the parameter lists. // (2) Have been implemented to show various methods of use. // - ITSO_StringListGUI is an RM Parameter made available to the Tivoli // Admins via the Desktop. // dimension= Svc.GetStrParameterCount("ITSO_ArrayGUI"); if (dimension > 0 ) { Svc.Trace (0, "ITSO_Sample: Init - dimension =" + dimension); // Note: This is the reference to the alias "ITSO_Sample" created in // the DefineClass method. Svc.AssociateParameterToClass ("ITSO_ArrayGUI","ITSO_Sample"); } else { Svc.Trace (0, "ITSO_Sample: ITSO_ArrayGUI parameter is empty"); return(801); // Return an error if the Resource Model is dependant // on the paramater to function. "Unable to start." } Svc.Trace (0, "ITSO_Sample: Init - end" ); return (0); }
VisitTree
The VisitTree function, shown in Example 5-30 on page 168, was customized to perform the actual monitoring algorithm. In the case of the ITSO_Sample, the algorithm consists of simply polling each of the CIM class properties. The purpose of such simple logic is to demonstrate the retrieval of the data from the ILT class and to provide logging to the ITM Engine log file. The logging provides a method for tracing the functionality of the entire model and ILT during regular operation. Typical logic in the VisitTree function may include, but is not limited to, posting events, performing calculations and data comparisons, as well as logging data
167
retrieved from the ILT to the local database for collection and roll-up to the Tivoli Data Warehouse product.
Example 5-30 ITSO_Sample.dmjsws: VisitTree function
function VisitTree(Svc) { // Variable Declaration var curITSO_SampleVar_inst; var curITSO_SampleVar_str; var curITSO_SampleVar_bln; var curITSO_SampleVar_ui8; var curITSO_SampleVar_ui16; var curITSO_SampleVar_ui32; var curITSO_SampleVar_si8; var curITSO_SampleVar_si16; var curITSO_SampleVar_si32; var curITSO_SampleVar_si64; var curITSO_SampleVar_r32; var curITSO_SampleVar_r64; var iInstanceCount; var idx; var sTraceOut; // Determine how many instances of the ITSO_Sample CIM Class exist. iInstanceCount = Svc.GetNumOfInst("ITSO_Sample"); Svc.Trace(0,"ITSO_Sample: VisitTree: iInstanceCount = "+ iInstanceCount ); for ( idx = 0; idx < iInstanceCount; idx++) { // Variable type demonstration:String curITSO_SampleVar_str = Svc.GetStrProperty("ITSO_Sample", idx, "ITSO_SampleVar_str"); sTraceOut = "GetNumProperty: curITSO_SampleVar_str = " + curITSO_SampleVar_str; Svc.Trace( 0, sTraceOut ); // Variable type demonstration:Boolean curITSO_SampleVar_bln= Svc.GetNumProperty("ITSO_Sample", idx, "ITSO_SampleVar_bln"); sTraceOut = "GetNumProperty: curITSO_SampleVar_bln = " + curITSO_SampleVar_bln; Svc.Trace( 0, sTraceOut ); // Variable type demonstration:Unsigned Integer 8 curITSO_SampleVar_ui8 = Svc.GetNumProperty("ITSO_Sample", idx, "ITSO_SampleVar_ui8"); sTraceOut = "GetNumProperty: curITSO_SampleVar_ui8 = " + curITSO_SampleVar_ui8 ; Svc.Trace( 0, sTraceOut ); // Variable type demonstration:Unsigned Integer 16 curITSO_SampleVar_ui16 = Svc.GetNumProperty("ITSO_Sample", idx, "ITSO_SampleVar_ui16"); sTraceOut = "GetNumProperty: curITSO_SampleVar_ui16 = " + curITSO_SampleVar_ui16 ; Svc.Trace( 0, sTraceOut );
168
// Variable type demonstration:Unsigned Integer 32 curITSO_SampleVar_ui32 = Svc.GetNumProperty("ITSO_Sample", idx, "ITSO_SampleVar_ui32"); sTraceOut = "GetNumProperty: curITSO_SampleVar_ui32 = " + curITSO_SampleVar_ui32 ; Svc.Trace( 0, sTraceOut ); // Variable type demonstration:Signed Integer 8 curITSO_SampleVar_si8 = Svc.GetNumProperty("ITSO_Sample", idx, "ITSO_SampleVar_si8"); sTraceOut = "GetNumProperty: curITSO_SampleVar_si8 = " + curITSO_SampleVar_si8 ; Svc.Trace( 0, sTraceOut ); // Variable type demonstration:Signed Integer 16 curITSO_SampleVar_si16 = Svc.GetNumProperty("ITSO_Sample", idx, "ITSO_SampleVar_si16"); sTraceOut = "GetNumProperty: curITSO_SampleVar_si16 = " + curITSO_SampleVar_si16 ; Svc.Trace( 0, sTraceOut ); // Variable type demonstration:Signed Integer 32 curITSO_SampleVar_si32 = Svc.GetNumProperty("ITSO_Sample", idx, "ITSO_SampleVar_si32"); sTraceOut = "GetNumProperty: curITSO_SampleVar_si32 = " + curITSO_SampleVar_si32 ; Svc.Trace( 0, sTraceOut ); // Variable type demonstration:Signed Integer 64 curITSO_SampleVar_si64 = Svc.GetNumProperty("ITSO_Sample", idx, "ITSO_SampleVar_si64"); sTraceOut = "GetNumProperty: curITSO_SampleVar_si64 = " + curITSO_SampleVar_si64 ; Svc.Trace( 0, sTraceOut ); // Variable type demonstration:Real 32 curITSO_SampleVar_r32 = Svc.GetNumProperty("ITSO_Sample", idx, "ITSO_SampleVar_r32"); sTraceOut = "GetNumProperty: curITSO_SampleVar_r32 = " + curITSO_SampleVar_r32 ; Svc.Trace( 0, sTraceOut ); // Variable type demonstration:Real 64 curITSO_SampleVar_r64 = Svc.GetNumProperty("ITSO_Sample", idx, "ITSO_SampleVar_r64"); sTraceOut = "GetNumProperty: curITSO_SampleVar_r64 = " + curITSO_SampleVar_r64 ; Svc.Trace( 0, sTraceOut ); } return (0); }
5.4 Packaging
The various components discussed within this chapter must be packaged into a Resource Model tar file. The Resource Model Tar File relationship diagram, shown in Figure 5-6 on page 170, shows all the components of a typical
169
Resource Model, with those not used within the ITSO_Sample presented in light gray to de-emphasize their significance.

Configuration File Logging:
Parameter(s): ITSO_ArrayGUI Dynamic Model(s): CIM Class "ITSO_Sample"
JavaScript -or- Visual Basic Script
Action(s): Threshold(s): Event(s): Message Catalogs

Provider(s): "ITSO_Sample.jar" MOF(s): "ITSO_Sample.mof" Reference Model Functions:
SetDefaultConfiguration(Svc) Init(Svc) VisitTree(Svc)
Custom Files(s)
Figure 5-6 ITSO_Sample.tar: Resource Model Tar File
5.4.1 Testing and importing the MOF

The ITSO_Sample.mof file is compiled with the mofcomp utility, as shown in Example 5-31.
Example 5-31 mofcomp CLI
mofcomp -N:root\default ITSO_Sample.mof
The actual output from this process is shown in Figure 5-7 on page 171.
170
Figure 5-7 mofcomp output
5.4.2 Java compilation

The ITSO_Sample.java file is compiled by using the javac tool included with the JDK, as shown in Example 5-32.
Example 5-32 javac CLI
javac -classpath c:\ITSO_Sample;dm_m12.jar;javautils.jar ITSO_Sample.java -d c:\ITSO_Sample
The actual output from this Java compiler process is shown in Figure 5-8 on page 172.
171
Figure 5-8 javac output
Next, the ITSO_SampleILT.java file is compiled by using the javac tool included with the JDK, as shown in Example 5-33.
Example 5-33 javac CLI
javac -classpath c:\ITSO_Sample;dm_m12.jar;javautils.jar ITSO_SampleIlt.java -d c:\ITSO_Sample
The actual output from this process is shown in Figure 5-9.
Figure 5-9 javac output
172
5.4.3 Making the jar file

The ITSO_Sample.jar Java package file is built by using the jar tool included with the JDK, as shown in Example 5-34.
Example 5-34 jar CLI
jar -cvf ITSO_Sample.jar com/
The actual output from this process is shown in Figure 5-10.
Figure 5-10 jar output
5.4.4 Assembling the Resource Model

Upon completing the testing of ITSO_Sample.mof and the building of ITSO_Sample.jar, the two files must be added to the ITSO_Sample.dmjsws Resource Model file. This is done through the ITM Workbench, as shown in Figure 5-11 on page 174.
173
Figure 5-11 ITM Workbench: Tree view pane
5.4.5 Building the Resource Model

The Resource Model needs to be built through the ITM Workbench menu. Select Build Build Package, as shown in Figure 5-12 on page 175. This will open the Save As dialog box, as shown in Figure 5-13 on page 175.
174
Figure 5-12 ITM Workbench: Build menu
Figure 5-13 ITM Workbench: Save As
175
5.5 ITSO_Sample template

The files in this section were created for the purpose of providing an easy to follow Provider template. This template can be used to create custom ILT Providers to integrate with applications and operating systems.
5.5.1 ITSO_Sample.mof
The complete MOF file used for the ITSO Sample Resource Model is shown in Example 5-35.
Example 5-35 ITSO_Sample.mof
//-----------------------------------------------------------------------------// // ITSO_Sample.mof // // Description: // This file is a textual definition of the ITSO_Sample CIM class. // // History: // Date Author Description // -------- ------------------ -----------------------------------------// 04/15/03 ITSO Redbook Team Original file. // //-----------------------------------------------------------------------------[ Description ("ITSO Sample - This sample was created to provide to help " "clarify the creation of a custom ILT and Provider. There " "are many details that have not been included, incuding " "additional M12 qualifiers within the MOF. However, the " "core functionality does provide a complete model from " "which to work."), provider("com.tivoli.dmunix.ep.touchpoint.cimom.ifc.M12JavaProvider"), M12_Instrumentation { "Java.com.ibm.tivoli.monitoring.ITSO_Sample.ITSO_SampleIlt | | ENUM", "Java.com.ibm.tivoli.monitoring.ITSO_Sample.ITSO_SampleIlt | | GET"} ] class ITSO_Sample { // Attribute, Instance Count. [ Description("The ITSO_SampleVar_inst property defines the instance of " "the provider." ), key ] sint32 ITSO_SampleVar_inst; // Attribute, String. [ Description("The ITSO_SampleVar_str property demonstrates the use of" "a string data type." ) ]
176
string
ITSO_SampleVar_str;
// Attribute, Boolean. [ Description("The ITSO_SampleVar_bln property demonstrates the use of" "a boolean data type." ) ] boolean ITSO_SampleVar_bln; // Attribute, Signed Integer 8-bit. [ Description("The ITSO_SampleVar_si8 property demonstrates the use of" "an 8-bit signed integer data type." ) ] sint8 ITSO_SampleVar_si8; // Attribute, Signed Integer 16-bit. [ Description("The ITSO_SampleVar_str property demonstrates the use of" "a 16-bit signed integer data type." ) ] sint16 ITSO_SampleVar_si16; // Attribute, Signed Integer 32-bit. [ Description("The ITSO_SampleVar_str property demonstrates the use of" "a 32-bit signed integer data type." ) ] sint32 ITSO_SampleVar_si32; // Attribute, Signed Integer 64-bit. [ Description("The ITSO_SampleVar_str property demonstrates the use of" "a 64-bit signed integer data type." ) ] sint64 ITSO_SampleVar_si64; // Attribute, Unsigned Integer 8-bit. [ Description("The ITSO_SampleVar_str property demonstrates the use of" "an 8-bit unsigned integer data type." ) ] uint8 ITSO_SampleVar_ui8; // Attribute, Unsigned Integer 16-bit. [ Description("The ITSO_SampleVar_str property demonstrates the use of" "a 16-bit unsigned integer data type." ) ] uint16 ITSO_SampleVar_ui16; // Attribute, Unsigned Integer 32-bit. [ Description("The ITSO_SampleVar_str property demonstrates the use of" "a 32-bit unsigned integer data type." ) ] uint32 ITSO_SampleVar_ui32; // Attribute, Floating Point 32-bit. [ Description("The ITSO_SampleVar_str property demonstrates the use of" "a 32-bit floating point data type." ) ] real32 ITSO_SampleVar_r32; // Attribute, Floating Point 64-bit. [ Description("The ITSO_SampleVar_str property demonstrates the use of"
177
real64 };
"a 64-bit floating point data type." ) ] ITSO_SampleVar_r64;
5.5.2 ITSO_SampleIlt.java
The complete ILT class for the ITSO_Sample Resource Model is shown in Example 5-36.
Example 5-36 ITSO_SampleIlt.java
//-----------------------------------------------------------------------------// // ITSO_SampleILT.java // // Description: // This file is the ITSO_Sample Instrumentation Library Type (ILT) // implementation. This is the class instantiated by the "touchpoint" // layer. This class will execute methods in the "ITSO_Sample.java" file, // which is the physical "provider" and performs the actual data // acquisition. // // Various classes are referenced throughout this file. ILT Supported // Classes, which are documented, in the IBM Tivoli Monitoring Workbench User's Guide // Version 5.1.1, SH19-4571, include: // M12ClassPath // M12IdentityElement // M12ObjectIdentity // M12PreportySet // M12Exception // ParameterSet // ParameterSetList // // History: // Date Author Description // -------- ------------------ -----------------------------------------// 04/15/03 ITSO Redbook Team Original file. // //-----------------------------------------------------------------------------package com.ibm.tivoli.monitoring.ITSO_Sample; import import import import import com.ibm.tivoli.monitoring.ITSO_Sample.ITSO_Sample; com.tivoli.dmunix.ep.touchpoint.base.*; // "dm_m12.jar" com.tivoli.javautils.Trace; // "javautils.jar" java.util.Enumeration; java.util.Vector;
public class ITSO_SampleIlt implements ILTInterface
178
{ //-------------------------------------------------------------------------// Instantiate the required class. //-------------------------------------------------------------------------private ITSO_Sample pitso_sample; private Trace trace;
//-------------------------------------------------------------------------// ITSO_SampleIlt class - Creator method. //-------------------------------------------------------------------------public ITSO_SampleIlt() { pitso_sample = new ITSO_Sample(); trace = Trace.getTraceInstance(); } //-------------------------------------------------------------------------// Instrumentation Library Type (ILT) // - Public Operations // // Note: This is documented in the IBM Tivoli Monitoring Workbench User's Guide Version // 5.1.1, SH19-4571. // //-------------------------------------------------------------------------//-------------------------------------------------------------------------// // getProperty // // Supported: YES // // Syntax: // public java.lang.String getProperty( M12ObjectIdentity targetInstance, // java.lang.String propertyName, // java.lang.String mappingString, // ParameterSet parms ) // throws M12Exception // // Parameters: // targetInstance: M12ObjectIdentity that identifies the instance of // the resource to be accessed. // propertyName: The property whose value is required. // mappingString: Any string that has been specified in the // M12_Instrumentation qualifier for the GET operation // type for this property. // parms: A ParameterSet object filled by the client with // parameters associated to this property. //
179
// Description: // Gets the value (in String format) of the specified property for the // identified object. // // Returns: // String: The value for property propertyName. Property values have // to be CIM standard types and ILT converts them to string // format according to the CIM standards. // // Exceptions Thrown: // M12Exception //-------------------------------------------------------------------------public String getProperty( M12ObjectIdentity m12objectidentity, String sPropertyName, String sMapping, ParameterSet parameterset ) throws M12Exception { try { M12IdentityElement m12identityelement = m12objectidentity.getScopingPath()[0]; M12PropertySet m12propertyset = m12identityelement.getIdentity(); // Determine which instance is being checked by the // Management Layer. String sKey = m12propertyset.getProperty("ITSO_SampleVar_inst"); trace.log(3, "ITSO_SampleIlt", "getProperty: called for ITSO_SampleVar_inst " + sKey); // Get the attributes being checked by the Management Layer. // Get the current attribute values. String sValue = getITSOAttribute(sKey, sPropertyName); trace.log(3, "ITSO_SampleIlt", "getITSOAttribute: " + sPropertyName + " = " + sValue); return sValue; } catch(Exception exception) { trace.exception("ITSO_SampleIlt", "getProperty", exception); M12Exception m12exception = new M12Exception(exception); throw m12exception; } } //-------------------------------------------------------------------------// // getMultipleProperties //
180
// Supported: YES // // Syntax: // public M12PropertySet getMultipleProperties( // M12ObjectIdentity targetInstance, // java.util.Vector propertyList, // java.lang.String mappingString, // ParameterSet parms ) // throws M12Exception // // Parameters: // targetInstance: M12ObjectIdentity that identifies the instance of // the resource to be accessed. // propertyList: The list of properties whose value is required. // mappingString: Any string that has been specified in the // M12_Instrumentation qualifier for the GET operation // type for the class which the specified instance // belongs to. // parms: A ParameterSet object filled by the client with // parameters associated to the class which the // specified instance belongs to. // // Description: // Gets the value (in String format) of the specified properties for the // identified object. // // Returns: // M12PropertySet: the values of the requested properties. // // Exceptions Thrown: // M12Exception // //-------------------------------------------------------------------------public M12PropertySet getMultipleProperties( M12ObjectIdentity m12objectidentity, Vector vPropertyList, String sMapping, ParameterSet parameterset ) throws M12Exception { try { M12IdentityElement m12identityelement = m12objectidentity.getScopingPath()[0]; M12PropertySet m12propertyset = m12identityelement.getIdentity(); // Determine which instance is being checked by the // Management Layer. String sKey = m12propertyset.getProperty("ITSO_SampleVar_inst");
181
M12PropertySet m12propertyset1 = new M12PropertySet(); trace.log(3, "ITSO_SampleIlt", "getMultipleProperty: called for ITSO_SampleVar_inst " + sKey); for(int i = 0; i < vPropertyList.size(); i++) { // Get the property being checked by the Management Layer. String sProperty = (String)vPropertyList.elementAt(i); // Get the current attribute values. String sValue = getITSOAttribute(sKey, sProperty); m12propertyset1.setProperty(sProperty, sValue); } trace.log(3, "ITSO_SampleIlt", "getMultipleProperty: returning " + WriteBuffer(m12propertyset1)); return m12propertyset1; } catch(Exception exception) { trace.exception("ITSO_SampleIlt", "getMultipleProperty", exception); M12Exception m12exception = new M12Exception(exception); throw m12exception; } } //-------------------------------------------------------------------------// // enumerateInstances // // Supported: YES // // Syntax: // public java.util.Enumeration enumerateInstances( // M12ClassPath classPath, // java.lang.String mappingString, // ParameterSet parms ) // throws M12Exception // // Parameters: // classPath: The M12ClassPath identifying the class whose instances // have to be enumerated. // mappingString: Any string that has been specified in the // M12_Instrumentation qualifier for the ENUM operation // type for this class. // parms: A ParameterSet object filled by the client with // parameters for ILT. //
182
// Description // Returns all M12ObjectIdentity objects that identify all the instances // belonging to the class specified in the classPath. // // Returns: // Enumeration of instances identity (M12ObjectIdentity). // // Exceptions Thrown: // M12Exception // //-------------------------------------------------------------------------public Enumeration enumerateInstances( M12ClassPath m12classpath, String sMapping, ParameterSet parameterset ) throws M12Exception { try { // Variable Declaration. StringBuffer stringbuffer = new StringBuffer(); Vector vector = new Vector(); //-----------------------------------------------------------------// Get the parameters from the caller. // We are obtaining theparameters prior to declaring instances so // we can configure an instance for each parameter. //-----------------------------------------------------------------Enumeration enumeration = parameterset.parametersNames(); Vector vParam = (Vector)parameterset.getParam("ITSO_ArrayGUI"); if(vParam == null) { trace.log(1, "ITSO_SampleIlt", "enumerateInstances: no parameters found"); return null; } // Process the ITSO_ArrayGUI parameter. String asITSOArrayGui[] = new String[vParam.size()]; for(int iIndex = 0; iIndex < vParam.size(); iIndex++) { // Get the string array element from the vector element. asITSOArrayGui[iIndex] = (String)vParam.elementAt(iIndex); trace.log( 3, "ITSO_SampleIlt", "enumerateInstances: asITSOArrayGui[" + iIndex + "] = " + asITSOArrayGui[iIndex]); } //-----------------------------------------------------------------// Acquire a vector (pointer) from the calling ILT Manager. // This section handles the registration of instances of this
183
// Instrumentation. //-----------------------------------------------------------------int aiInst[] = pitso_sample.getITSO_Instances( asITSOArrayGui ); if(aiInst == null) { trace.log(1, "ITSO_SampleIlt", "enumerateInstances: no instances found"); return null; } for(int jIndex = 0; jIndex < aiInst.length; jIndex++) { trace.log( 3, "ITSO_SampleIlt", "enumerateInstances: aiInst[" + jIndex + "] = " + aiInst[jIndex]); M12PropertySet m12propertyset = new M12PropertySet(); m12propertyset.setProperty( "ITSO_SampleVar_inst", String.valueOf(aiInst[jIndex]) ); M12IdentityElement m12identityelement = new M12IdentityElement( m12classpath.getClassName(), m12classpath.getNameSpace(), m12propertyset); vector.add( new M12ObjectIdentity( new M12IdentityElement[] { m12identityelement } ) ); } return vector.elements(); } catch(Exception exception) { trace.exception("ITSO_SampleIlt", "enumerateInstances", exception); M12Exception m12exception = new M12Exception(exception); throw m12exception; } } //-------------------------------------------------------------------------// // setProperty // // Supported: NO // // Syntax: // public java.lang.String setProperty( M12ObjectIdentity targetInstance, // java.lang.String propertyName, // java.lang.String propertyValue, // java.lang.String mappingString, // ParameterSet parms ) // throws M12Exception //
184
// Parameters: // targetInstance: M12ObjectIdentity that identifies the instance of the // resource to be accessed. // propertyName: The property whose value is to be set. // propertyValue: The property value to be set. // mappingString: Any string that has been specified in the // M12_Instrumentation qualifier for the SET operation // type for this property. // parms: A ParameterSet object filled by the client with // parameters associated to this property. // // Description: // Sets the value (in String format) of the specified property for the // identified object. // // Returns: // String: the new value of the specified property. // // Exceptions Thrown: // M12Exception // //-------------------------------------------------------------------------public String setProperty( M12ObjectIdentity m12objectidentity, String sName, String sValue, String sMapping, ParameterSet parameterset ) throws M12Exception { trace.log(3, "ITSO_SampleIlt", "setProperty: " + "sName=" + sName + ", sValue=" + sValue + ", sMapping=" + sMapping ); return null; } //-------------------------------------------------------------------------// // invokeMethod // // Supported: YES // // Syntax: // public java.lang.String invokeMethod( M12ClassPath classPath, // java.lang.String methodName, // java.lang.String mappingString, // ParameterSet parms, // ParameterSet inParms, // ParameterSet outParms )
185
// throws M12Exception // // Parameters: // classPath: The M12ClassPath that identifies the class // whose method has to be called. // methodName: The name of the method to be called. // mappingString: Any string that has been specified in the // M12_Instrumentation qualifier for the INVOKE // operation type for this method. // parms: A ParameterSet object filled by the client with // parameters for this method. // inParms: A ParameterSet object filled by the client with // parameters to be passed to the method. // outParms: A ParameterSet object created by the client and // filled by the method with output results. // // Description: // Invokes the specified method on the CIM instance belonging to // the class specified in the classPath. // // Returns: // String: The result of the method. Result values have to be CIM // standard types and ILT converts them to string format // according to the CIM standards. // // Exceptions Thrown: // M12Exception // //-------------------------------------------------------------------------public String invokeMethod( M12ClassPath m12classpath, String sMethodName, String sMapping, ParameterSet parameterset, ParameterSet parameterset1, ParameterSet parameterset2 ) throws M12Exception { trace.log(3, "ITSO_SampleIlt", "invokeMethod(1): " + "sMethodName=" + sMethodName + ", sMapping=" + sMapping ); return null; }
//-------------------------------------------------------------------------// // invokeMethod // // Supported: YES
186
// // Syntax: // public java.lang.String invokeMethod( M12ObjectIdentity targetInstance, // java.lang.String methodName, // java.lang.String mappingString, // ParameterSet parms, // ParameterSet inParms, // ParameterSet outParms) // throws M12Exception // // Parameters: // targetInstance: M12ObjectIdentity that identifies the instance // whose method has to be called. // methodName: The name of the method to be called. // mappingString: Any string that has been specified in the // M12_Instrumentation qualifier for the INVOKE // operation type for this method. // parms: A ParameterSet object filled by the client with // parameters for this method. // inParms: A ParameterSet object filled by the client with // parameters to be passed to the method. // outParms: A ParameterSet object created by the client and // filled by the method with output results. // // Description: // Invokes the specified method on the identified CIM instance. // // Returns: // String: The result of the method. Result values have to be CIM // standard types and ILT converts them to string format // according to the CIM standards. // // Exceptions Thrown: // M12Exception // //-------------------------------------------------------------------------public String invokeMethod( M12ObjectIdentity m12objectidentity, String sMethodName, String sMapping, ParameterSet parameterset, ParameterSet parameterset1, ParameterSet parameterset2 ) throws M12Exception { trace.log(3, "ITSO_SampleIlt", "invokeMethod(2): " + "sMethodName=" + sMethodName + ", sMapping=" + sMapping ); return null; }
187
//-------------------------------------------------------------------------// // create // // Supported: NO // // Syntax: // public void create( M12ObjectIdentity targetInstance, // java.lang.String mappingString, // ParameterSet parms ) // throws M12Exception // // Parameters: // targetInstance: M12ObjectIdentity that identifies the instance // of the resource to be created. // mappingString: Any string that has been specified in the // M12_Instrumentation qualifier for the CREATE // operation type for the class whose instance to // be created will belong to. // parms: A ParameterSet object filled by the client // with parameters for the ILT. // // Description // Creates an instance of the resource that will be identified by // the specified targetInstance. // // Returns: // void // // Exceptions Thrown: // M12Exception // //-------------------------------------------------------------------------public void create( M12ObjectIdentity m12objectidentity, String sMapping, ParameterSet parameterset ) throws M12Exception { trace.log(3, "ITSO_SampleIlt", "create: sMapping=" + sMapping ); }
//-------------------------------------------------------------------------// // destroy // // Supported: NO
188
// // Syntax: // public void destroy( M12ObjectIdentity targetInstance, // java.lang.String mappingString, // ParameterSet parms ) // throws M12Exception // // Parameters : // targetInstance: M12ObjectIdentity that identifies the instance // of the resource to be deleted. // mappingString: Any string that has been specified in the // M12_Instrumentation qualifier for the CREATE // operation type for the class whose instance to // be deleted belongs to. // parms: A ParameterSet object filled by the client // with parameters for the ILT. // // Description: // Deletes an instance of the resource identified by the specified // targetInstance. // // Returns: // void // // Exceptions Thrown: // M12Exception // //-------------------------------------------------------------------------public void destroy( M12ObjectIdentity m12objectidentity, String sMapping, ParameterSet parameterset ) throws M12Exception { trace.log(3, "ITSO_SampleIlt", "destroy: sMapping=" + sMapping ); } //-------------------------------------------------------------------------// // Custom Class Methods // // The following methods are custom methods created to provide better // programatic structure. // //-------------------------------------------------------------------------//-------------------------------------------------------------------------// // GetAttributeTypes //
189
// This method is internal to the class and is designed to segregate the // ILT Operations from our own supporting methods. It is simply to provide // cleaner & easier to maintain code. // //-------------------------------------------------------------------------private String getITSOAttribute( String sValue, String sProperty ) throws Exception { //---------------------------------------------------------------------// // MOF Declared Types // // There is an "if" structure for each of the variable types that this // sample supports. // //---------------------------------------------------------------------int iIndex = (new Integer(sValue)).intValue(); //---------------------------------------------------------------------// string ITSO_SampleVar_str //---------------------------------------------------------------------if(sProperty.equals("ITSO_SampleVar_str")) { String sReturn = new String( pitso_sample.getITSO_SampleVar_str(iIndex) ); return sReturn; } //---------------------------------------------------------------------// boolean ITSO_SampleVar_bln //---------------------------------------------------------------------if(sProperty.equals("ITSO_SampleVar_bln")) { Boolean blnVar = new Boolean(pitso_sample.getITSO_SampleVar_bln(iIndex)); return blnVar.toString(); } //---------------------------------------------------------------------// sint8 ITSO_SampleVar_si8 // sint16 ITSO_SampleVar_si16 // sint32 ITSO_SampleVar_si32 // sint64 ITSO_SampleVar_si64 //---------------------------------------------------------------------if( (sProperty.equals("ITSO_SampleVar_si8")) || (sProperty.equals("ITSO_SampleVar_si16")) || (sProperty.equals("ITSO_SampleVar_si32")) ||
190
(sProperty.equals("ITSO_SampleVar_si64")) ) { Integer intVar = new Integer(pitso_sample.getITSO_SampleVar_si(iIndex)); return intVar.toString(); } //---------------------------------------------------------------------// uint8 ITSO_SampleVar_ui8 // uint16 ITSO_SampleVar_ui16 // uint32 ITSO_SampleVar_ui32 //---------------------------------------------------------------------if( (sProperty.equals("ITSO_SampleVar_ui8")) || (sProperty.equals("ITSO_SampleVar_ui16")) || (sProperty.equals("ITSO_SampleVar_ui32")) ) { Integer intVar = new Integer(pitso_sample.getITSO_SampleVar_ui(iIndex)); return intVar.toString(); } //---------------------------------------------------------------------// real32 ITSO_SampleVar_r32 // real64 ITSO_SampleVar_r64 //---------------------------------------------------------------------if( (sProperty.equals("ITSO_SampleVar_r32")) || (sProperty.equals("ITSO_SampleVar_r64")) ) { Double dblVar = new Double(pitso_sample.getITSO_SampleVar_r(iIndex)); return dblVar.toString(); } //---------------------------------------------------------------------// Unknown property. //---------------------------------------------------------------------else { throw new Exception(sProperty + ": unknown property"); } }
//-------------------------------------------------------------------------// // WriteBuffer // // This method is internal to the class and is designed to write the // variable returned from the ILT Operations to the output string. It is
191
// strictly to support better logging. // //-------------------------------------------------------------------------private String WriteBuffer( M12PropertySet m12propertyset ) { Enumeration enumeration = m12propertyset.propertyNames(); StringBuffer stringbuffer = new StringBuffer(); String sElement; String sProperty; for(; enumeration.hasMoreElements(); stringbuffer.append(sElement + " = " + sProperty + " ")) { sElement = (String)enumeration.nextElement(); sProperty = m12propertyset.getProperty(sElement); } return stringbuffer.toString(); } }
5.5.3 ITSO_Sample.java
The complete Provider class for the ITSO_Sample Resource Model is shown in Example 5-37.
Example 5-37 ITSO_Sample.java
//-----------------------------------------------------------------------------// // ITSO_Sample.java // // Description: // This file is the ITSO_Sample Provider to the ILT. This can perform the // actual the actual data acquisition, call other classes, or via JNI // perform calls to "native" binaries. // // History: // Date Author Description // -------- ------------------ -----------------------------------------// 04/15/03 ITSO Redbook Team Original file. // //-----------------------------------------------------------------------------package com.ibm.tivoli.monitoring.ITSO_Sample; import com.tivoli.javautils.Trace; import java.util.*;
192
public class ITSO_Sample { // Declare local members. private Trace trace; private Map ITSO_SampleMap; //-------------------------------------------------------------------------// ITSO_Sample class - Creator method. //-------------------------------------------------------------------------public ITSO_Sample() { trace = Trace.getTraceInstance(); }
//-------------------------------------------------------------------------// ITSO_Sample: This method should configure an instance for each item in // the array. //-------------------------------------------------------------------------public synchronized int[] getITSO_Instances( String asParams[] ) { // The instances will be referenced by number to keep it simple. trace.log(3, "ITSO_Sample", "getITSO_Instances asParams.length=" + asParams.length); int[] aiInst = new int[asParams.length]; for(int iIndex = 0; iIndex < asParams.length; iIndex++) { // Get the string array element from the vector element. trace.log(3, "ITSO_Sample", "getITSO_Instances iIndex=" + iIndex); aiInst[iIndex] = iIndex; trace.log(3, "ITSO_Sample", "getITSO_Instances aiInst[" + iIndex + "]" + aiInst[iIndex]); } return aiInst; }
//---------------------------------------------------------------------// getITSO_SampleVar_String // // Implement the code or reference to the code that will "provide" the // value requested. // // This method spceifically returns a "dummy" value for the String. It // does not actually perform any lookups or references to system data. //---------------------------------------------------------------------public static synchronized String getITSO_SampleVar_str(int iIndex) {
193
// Add logic to check the correct instance (index) of the resource. // For this example, to demonstrate differences based on instances, // we are building a string that includes the index number. String sReturn = "iIndex_" + iIndex; return sReturn; }
//---------------------------------------------------------------------// getITSO_SampleVar_SignedInt // // Implement the code or reference to the code that will "provide" the // value requested. // // This method spceifically returns a "dummy" value for the Signed Int. // It does not actually perform any lookups or references to system // data. //---------------------------------------------------------------------public static synchronized int getITSO_SampleVar_si(int iIndex) { // Add logic to check the correct instance (index) of the resource. return -1; }
//---------------------------------------------------------------------// getITSO_SampleVar_UnsignedInt // // Implement the code or reference to the code that will "provide" the // value requested. // // This method spceifically returns a "dummy" value for the Unsigned // Int. It does not actually perform any lookups or references to // system data. //---------------------------------------------------------------------public static synchronized int getITSO_SampleVar_ui(int iIndex) { // Add logic to check the correct instance (index) of the resource. return 1; }
//---------------------------------------------------------------------// getITSO_SampleVar_Real // // Implement the code or reference to the code that will "provide" the // value requested. //
194
// This method spceifically returns a "dummy" value for the Floating // Point. It does not actually perform any lookups or references to // system data. //---------------------------------------------------------------------public static synchronized double getITSO_SampleVar_r(int iIndex) { // Add logic to check the correct instance (index) of the resource. return 3.14; }
//---------------------------------------------------------------------// getITSO_SampleVar_Boolean // // Implement the code or reference to the code that will "provide" the // value requested. // // This method spceifically returns a "dummy" value for the Floating // Point. It does not actually perform any lookups or references to // system data. //---------------------------------------------------------------------public static synchronized boolean getITSO_SampleVar_bln(int iIndex) { // Add logic to check the correct instance (index) of the resource. return true; } }
5.5.4 Resource Model JavaScript

The complete JavaScript, as implemented within the ITSO_Sample Resource Model file, is shown in Example 5-38
Example 5-38 ITSO_Sample.dmjsws JavaScript
//'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' // IBM Tivoli Monitoring // Decision Tree script // // History: // Date Author Description // -------- ------------------ -----------------------------------------// 04/15/03 ITSO Redbook Team Original file. // //''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
// This function is used to define the settings of the Resource Model
195
// It is called only once, when the Resource Model is started. // Don't modify remarks containing tags like <<....>> ... <<\...>> // You can write additional initializing code in this function if required. function SetDefaultConfiguration (Svc) { Svc.Trace (0, "ITSO_Sample: SetDefaultConfiguration - start" ); // General info section //<<GENERAL_INFO>> Svc.SetModelName ("ITSO_Sample"); Svc.SetProfileName ("460108578"); Svc.SetCycleTime (60); //<<\GENERAL_INFO>> // Thresholds section //<<THRESHOLDS_INFO>> //<<\THRESHOLDS_INFO>> // Parameters section //<<PARAMETERS_INFO>> Svc.DefineStrParameter ("ITSO_ArrayGUI", "Mike,Craig,Kiyo"); //<<\PARAMETERS_INFO>> // Note: In the DefineClass method, we create an ALIAS of "ITSO_Sample" // of the actual CIM Namespace declaration for our class. // This will be referenced by the AssociateParameterToClass // method later. // // Dynamic Model section //<<DATA_INFO>> Svc.DefineClass ("CIM", "ITSO_Sample", "ROOT\\DEFAULT:ITSO_Sample", "", "ITSO_SampleVar_ui16,ITSO_SampleVar_si16,ITSO_SampleVar_r64,ITSO_SampleVar_r32,ITSO_SampleVar_u i32,ITSO_SampleVar_si8,ITSO_SampleVar_bln,ITSO_SampleVar_si64,ITSO_SampleVar_ui8,ITSO_SampleVar _si32,ITSO_SampleVar_inst", "ITSO_SampleVar_str", "None", "", 0, 1); //<<\DATA_INFO>> // Event definition section //<<EVENTS_INFO>> //<<\EVENTS_INFO>> // Logging definition section //<<LOGGING_INFO>> //<<\LOGGING_INFO>> // Place your additional intializing code below Svc.Trace (0, "ITSO_Sample: SetDefaultConfiguration - end" ); return (0); }
196
// This function is called by the DM For Windows Analyzer after that // the Resource Model default settings have been overridden // It is called only once, when the Resource Model is started. // You can write additional initializing code in this function if required // to use the thresholds and parameters values function Init(Svc) { Svc.Trace (0, "ITSO_Sample: Init - start" ); // Variable Initialization var dimension = 0; var t=0; // Process the parameter lists. // (2) Have been implemented to show various methods of use. // - ITSO_StringListGUI is an RM Parameter made available to the Tivoli Admins // via the Desktop. // dimension= Svc.GetStrParameterCount("ITSO_ArrayGUI"); if (dimension > 0 ) { Svc.Trace (0, "ITSO_Sample: Init - dimension =" + dimension); // Note: This is the reference to the alias "ITSO_Sample" created in the // DefineClass method. Svc.AssociateParameterToClass ("ITSO_ArrayGUI","ITSO_Sample"); } else { Svc.Trace (0, "ITSO_Sample: ITSO_ArrayGUI parameter is empty"); return(801); // Return an error if the Resource Model is dependant // on the paramater to function. "Unable to start." } Svc.Trace (0, "ITSO_Sample: Init - end" ); return (0); }
// This function contains the monitoring algorithm // It is called cyclically after a cycle time has elapsed // Implement the the monitoring code here function VisitTree(Svc) { // Variable Declaration var curITSO_SampleVar_inst; var curITSO_SampleVar_str;
197
var var var var var var var var var var var var var
curITSO_SampleVar_bln; curITSO_SampleVar_ui8; curITSO_SampleVar_ui16; curITSO_SampleVar_ui32; curITSO_SampleVar_si8; curITSO_SampleVar_si16; curITSO_SampleVar_si32; curITSO_SampleVar_si64; curITSO_SampleVar_r32; curITSO_SampleVar_r64; iInstanceCount; idx; sTraceOut;
// Determine how many instances of the ITSO_Sample CIM Class exist. iInstanceCount = Svc.GetNumOfInst("ITSO_Sample"); Svc.Trace(0,"ITSO_Sample: VisitTree: iInstanceCount = "+ iInstanceCount ); for ( idx = 0; idx < iInstanceCount; idx++) { // Variable type demonstration: String curITSO_SampleVar_str = Svc.GetStrProperty("ITSO_Sample", idx, "ITSO_SampleVar_str"); sTraceOut = "GetNumProperty: curITSO_SampleVar_str = " + curITSO_SampleVar_str; Svc.Trace( 0, sTraceOut ); // Variable type demonstration: Boolean curITSO_SampleVar_bln= Svc.GetNumProperty("ITSO_Sample", idx, "ITSO_SampleVar_bln"); sTraceOut = "GetNumProperty: curITSO_SampleVar_bln = " + curITSO_SampleVar_bln; Svc.Trace( 0, sTraceOut ); // Variable type demonstration: Unsigned Integer 8 curITSO_SampleVar_ui8 = Svc.GetNumProperty("ITSO_Sample", idx, "ITSO_SampleVar_ui8"); sTraceOut = "GetNumProperty: curITSO_SampleVar_ui8 = " + curITSO_SampleVar_ui8 ; Svc.Trace( 0, sTraceOut ); // Variable type demonstration: Unsigned Integer 16 curITSO_SampleVar_ui16 = Svc.GetNumProperty("ITSO_Sample", idx, "ITSO_SampleVar_ui16"); sTraceOut = "GetNumProperty: curITSO_SampleVar_ui16 = " + curITSO_SampleVar_ui16 ; Svc.Trace( 0, sTraceOut ); // Variable type demonstration: Unsigned Integer 32 curITSO_SampleVar_ui32 = Svc.GetNumProperty("ITSO_Sample", idx, "ITSO_SampleVar_ui32"); sTraceOut = "GetNumProperty: curITSO_SampleVar_ui32 = " + curITSO_SampleVar_ui32 ; Svc.Trace( 0, sTraceOut ); // Variable type demonstration: Signed Integer 8 curITSO_SampleVar_si8 = Svc.GetNumProperty("ITSO_Sample", idx, "ITSO_SampleVar_si8"); sTraceOut = "GetNumProperty: curITSO_SampleVar_si8 = " + curITSO_SampleVar_si8 ; Svc.Trace( 0, sTraceOut );
198
// Variable type demonstration: Signed Integer 16 curITSO_SampleVar_si16 = Svc.GetNumProperty("ITSO_Sample", idx, "ITSO_SampleVar_si16"); sTraceOut = "GetNumProperty: curITSO_SampleVar_si16 = " + curITSO_SampleVar_si16 ; Svc.Trace( 0, sTraceOut ); // Variable type demonstration: Signed Integer 32 curITSO_SampleVar_si32 = Svc.GetNumProperty("ITSO_Sample", idx, "ITSO_SampleVar_si32"); sTraceOut = "GetNumProperty: curITSO_SampleVar_si32 = " + curITSO_SampleVar_si32 ; Svc.Trace( 0, sTraceOut ); // Variable type demonstration: Signed Integer 64 curITSO_SampleVar_si64 = Svc.GetNumProperty("ITSO_Sample", idx, "ITSO_SampleVar_si64"); sTraceOut = "GetNumProperty: curITSO_SampleVar_si64 = " + curITSO_SampleVar_si64 ; Svc.Trace( 0, sTraceOut ); // Variable type demonstration: Real 32 curITSO_SampleVar_r32 = Svc.GetNumProperty("ITSO_Sample", idx, "ITSO_SampleVar_r32"); sTraceOut = "GetNumProperty: curITSO_SampleVar_r32 = " + curITSO_SampleVar_r32 ; Svc.Trace( 0, sTraceOut ); // Variable type demonstration: Real 64 curITSO_SampleVar_r64 = Svc.GetNumProperty("ITSO_Sample", idx, "ITSO_SampleVar_r64"); sTraceOut = "GetNumProperty: curITSO_SampleVar_r64 = " + curITSO_SampleVar_r64 ; Svc.Trace( 0, sTraceOut ); } return (0); }
199
200
Chapter 6.
Creating an SNMP Resource Model for Windows

In this chapter, we cover the basics on how to create a Resource Model from a new Windows Management Instrumentation (WMI) Provider, specifically using the WMI SNMP Provider. We link the new management classes into the WMI Repository and create a Resource Model underpinning the new management classes and data feeds. The scope of this example is limited to IBM Tivoli Monitoring operating on a Microsoft Windows NT-based operating system within the COM+ architecture (Windows XP, Windows 2000, and Windows NT). Though this is Windows-centric, the concept of SNMP is open to all platforms. The same concepts apply to IBM Tivoli Monitoring when it is running cross-platform within the Java components of the IBM Tivoli Monitoring architecture (refer to Chapter 7, Creating an SNMP Resource Model for Java on page 231 for more details). This chapter describes the following: Designing the ITSO_SNMP_Interface_Bps Resource Model Creating the ITSO_SNMP_Interface_Bps Resource Model ITSO_SNMP_Interface_Bps source code
201
6.1 Designing the Resource Model

In this scenario, we will demonstrate how to create a new Resource Model, ITSO_SNMP_Interface_Bps, that will take data from SNMP sources and report on key performance metrics, such as the interface traffic density on Windows 2000 machines.
6.1.1 Design overview

The Resource Model utilizes the WMI SNMP Provider to monitor the MIB variable through WMI. The overview of ITSO_SNMP_Interface_Bps Resource Model is shown in Figure 6-1.
Monitored Server
W MI ITSO_SNMP_Interface_Bps Resource Model SNMP Service MIB-II System MIB-II Interfaces MIB-II IP MIB-II TCP MIB-II UDP W MI SNMP Provider
ITM Engine
Endpoint
Figure 6-1 Design overview of ITSO_SNMP_Interface_Bps Resource Model
The WMI SNMP Provider is an extension of WMI provided by Microsoft. The WMI SNMP Provider allows us to access MIB variables provided by Microsoft Windows SNMP Service through the WMI interface. Currently, SNMP is one of the most widely used network management protocols. It has a huge advantage in the network management realm, which means you can follow best practices for network management by using SNMP. Moreover, you can also integrate the best practices of network management into ITM using the WMI SNMP Provider. Microsoft Windows SNMP Service supports the RFC1213 MIB-II, which has general attributes related to the network level information of the device. The MIB-II specification is made of several groups including System, Interfaces, and IP. In this scenario, we will utilize the ifInOctets MIB variable and the ifOutOctets MIB variable included in the Interfaces group of MIB-II to monitor the performance of interfaces. Both of them are the COUNTER type MIB variables, which is the total number of octets (8 bits) received on the interface. As long as
202
the system runs, the ifInOctets MIB variable and the ifOutOctets MIB variable continuously grow. This makes for easy comparisons within the Resource Model. The ITSO_SNMP_Interface_Bps Resource Model checks the difference between the current value of the MIB variable and previous one. If the delta between the current variable and previous one becomes more than the threshold attribute you specify, the ITSO_SNMP_Interface_Bps Resource Model recognizes the interface has the traffic problem. For your convenience, ITSO_SNMP_Interface_Bps calculate octets measurement into bits (you can specify the threshold in bits per second (bps)).
Note: For more information about the WMI or the WMI SNMP Provider, see the following link:
http://www.microsoft.com/technet/default.asp
6.1.2 What part of ITM will we use?

In review of the aforementioned design requirements, the ITM Engine Logical Components diagram can be revisited. The components of the engine that will be utilized by this example can be seen in Figure 6-2 on page 204. Those components that will not be used within the ITSO_SNMP_Interface_Bps are presented in light gray to de-emphasize their significance. It is based on the WMI SNMP Provider, which can run only on the Windows platform.
Chapter 6. Creating an SNMP Resource Model for Windows
203

TMWService WMI APIs DM Classic Monitor Probes WMI (CIMOM) Custom Scripts ILT Manager for Java (WMI Provider DLL) WMI Provider DLLs Java Virtual Machine (JVM) Launch (Class Loader) ILT Providers Resource Resource Resource Resource Resource ILT JNI Binary Library JMX ILT MBean Server MBean1
COM Objects
Figure 6-2 ITM Engine logical components
6.1.3 Detailed design Resource Model

Before you create a Resource Model, we recommend that you have a clear idea of your design. For example, let us describe the detailed design of the ITSO_SNMP_Interface_Bps Resource Model.
External design
First, we define the threshold as external inputs of the Resource Model as shown in Table 6-1. You can change values of the threshold when distributing your profile.
Table 6-1 The indication
Indications Default
Thr_ifOutOctets_in Thr_ifInOctets_in
Increased by 100000 Increased by 100000
204
Internal design
To create the Resource Model smoothly, we recommend that you make a list of elements of your Resource Model, as shown in Table 6-2.
Table 6-2 List of elements
Elements Contents
Internal Name Descriptive Name Category Internal Name Category Descriptive Name Dynamic Model Events
ITSO_SNMP_Interface_Bps ITSO_SNMP_Interface_Bps Monitor ITSO_RMs ITSO Resource Models SNMP_RFC1213_MIB_ifTable Ev_SNMP_RFC1213_MIB_ifTable_ifOut Octets_grows_too_much Ev_SNMP_RFC1213_MIB_ifTable_ifInO ctets_grows_too_much Thr_ifOutOctets_in Thr_ifInOctets_in none none none
Thresholds Parameters Logging Dependency
6.2 Creating the Resource Model

This section describes how to create the ITSO_SNMP_Interface_Bps Resource Model by using the following procedures: 1. Installing SNMP and WMI SNMP on the managed machine 2. Creating a new SNMP Resource Model 3. Testing the Resource Model
6.2.1 Installing SNMP and WMI SNMP on the managed machine

Usually, Windows servers do not have the SNMP service and WMI SNMP Provider installed. We installed these components with the following steps.
205
Installing the SNMP Service

First, install the SNMP Service. 1. Install the SNMP Service by right-clicking the My Network Places icon and then selecting Properties. 2. In the Network and Dial-up Connections window, select Advanced Settings Optional Networking Components in the top menu, as shown in Figure 6-3.
Figure 6-3 Installing Optional Networking Components
3. In the Windows Optional Network Components Wizard window, select Management and Monitoring Tools and click on Details. 4. Select Simple Network Management Protocol in the Management and Monitoring Tools window, as illustrated in Figure 6-4 on page 207, and click OK.
206
Figure 6-4 Installing the SNMP Service
5. Click Next in the Windows Optional Network Components Wizard window and, when asked for additional files, locate them under SNMP_Source_Files_From_CD directory on your Windows 2000 licensed media. 6. Close the Network and Dial-up Connections window
Configuring the SNMP agent

After installing the SNMP Service, you need to edit the SNMP configuration to use it with WMI. 7. Select Start Settings Control Panel Administrative Tools Services. 8. Locate the SNMP Service service. 9. Right-click on SNMP Service and select Properties. 10.In the SNMP Service Properties (Local Computer) window, click on the Traps tab.
207
11.Add public as a community name by typing the word public into the Community name field and click Add to list. 12.Click Add... and enter the machine's IP address into the Host name, IP or IPX address: field and click Add. When you are done with adding the IP address, your configuration should be similar to Figure 6-5, but with your IP address in the Trap destinations field.
Figure 6-5 Enabling SNMP Services
13.Click OK to continue in the SNMP Service Properties (Local Computer) window. 14.Close the Services window and the Administrative Tools.
Installing WMI SNMP

This step is only required on the machine that will run the IBM Tivoli Monitoring engine and the Resource Model and on the machine that will run the Workbench. For your reference, here are some instructions on how to activate the Provider for Windows XP and Windows NT. Remember, SNMP Providers cannot be installed on or run on Windows 9x platforms.
208
Windows XP a. Use the following instructions to install the SNMP Provider: b. From the Control Panel, select Add/Remove Programs. c. Select Add/Remove Windows Components and then, in the Windows Components Wizard, select Management and Monitoring Tools. d. Select Simple Network Management Protocol and WMI SNMP Provider and then click OK. e. Follow the steps in the wizard to complete the installation. Windows NT version 4.0: Install the SNMP Provider when installing the WMI core or from the Internet (use http://www.microsoft.com/downloads). Windows 2000 For Windows 2000 machines, you need to follow these steps. a. Expand wbemsnmp.ex_ from the Windows 2000 CD by using a command prompt, as shown in Example 6-1. If you execute the expand command successfully, you will see the results shown in Example 6-1.
Example 6-1 Expanding the wbemsnmp.exe command
C:\temp\>expand "Your_CDROM_Drive:\I386\WBEMSNMP.EX_" wbemsnmp.exe Microsoft (R) File Expansion Utility Version 5.00.2134.1 Copyright (C) Microsoft Corp 1990-1999. All rights reserved. Expanding Your_CDROM_Drive:\I386\WBEMSNMP.EX_ to wbemsnmp.exe. Your_CDROM_Drive:\I386\WBEMSNMP.EX_: 817605 bytes expanded to 8614 90 bytes, 5% increase.
b. Run wbemsnmp.exe by double-clicking the extracted file. This will display the WMI SNMP Provider Installation Wizard, as shown in Figure 6-6 on page 210.
209
Figure 6-6 Installing the WMI SNMP Provider
c. Click Next to install the WMI SNMP Provider. d. Click Finish to complete and close the installation of the WMI SNMP Provider. e. Next, load SNMP MIB classes into the WMI Provider. As a Provider, the WMI SNMP Provider acts as a bridge between SNMP data and WMI classes. Therefore, you must have classes in WMI that represent different aspects of an SNMP-enabled device. To do so, you must use the SNMP information module compiler (smi2smir) to compile SNMP management information from the SNMP format into the equivalent CIM schema definitions. You can then direct the output of the information compiler into an SNMP schema database called the SNMP Module Information Repository (SMIR) or to several different kinds of MOF files. The compiler runs in command-line mode, using one MIB file as input. The following command loads a specified MIB file into the SMIR:
smi2smir /a <MIB file>
f. Load the mib_ii.mib file into the SMIR, which is located in the Your_System_Drive:\winnt\system32 directory by executing the following command from a MS-DOS command prompt, as shown in Example 6-2.
210
Example 6-2 Loading the mib_ii.mib file into the SMIR

C:\WINNT\system32>c:\winnt\system32\wbem\snmp\smi2smir /a c:\winnt\system32\mib_ii.mib smi2smir : Version 1.50.1085.0000 : MIB definitions compiled from "mib_ii.mib" smi2smir : Syntax Check successful on "mib_ii.mib" smi2smir : Semantic Check successful on "mib_ii.mib" smi2smir : Loaded "mib_ii.mib" successfully into the SMIR
Note: You can obtain a list of MIBs that ship with the Windows 2000 implementation of SNMP by referring to the Microsoft TechNet at:
6.2.2 Creating the new SNMP Resource Model

During this section we will create a new Resource Model which will consume data from the new Provider and the new CIM Name space.
Creating a new Resource Model

1. Open the IBM Tivoli Monitoring WorkBench by clicking Start Programs IBM Tivoli Monitoring 5.1.1 WorkBench WorkBench. 2. Initialize the Resource Model Wizard by pressing Ctrl-N, or by selecting File New from the menu bar. 3. In the New window, select VBA Resource Model, because the WMI SNMP Provider we are working with is only applicable to Microsoft Servers. Click on OK in this window. 4. In the New Resource Model Workspace window, select the default selection (Resource Model Wizard) and click on OK. 5. In the Resource Model Wizard: Select Data Source Type window, select the default CIM/WMI option by clicking on Next>. 6. In the Connect to Name Space: window, click the lock icon in the left side of the window, as shown in Figure 6-7 on page 211.
Figure 6-7 Connect to namespace
211
7. In the Browse for NameSpace window, ensure that you connect to the root namespace by ensuring that the Starting Namespace: field has the word root in it. Figure 6-8 shows you a similar window. Validate that your machine name is displayed in the Machine Name: field. When you are done validating both fields, click Connect.
Figure 6-8 Browse for Namespace
8. In the WMI Tivoli DM WorkBench Login window, select OK to authenticate the current credential set (make sure you are logged on as Administrator or an equivalent user ID). Select OK. 9. As shown in Figure 6-9 on page 213, expand the root namespace by clicking + (plus sign) next to root. Expand the snmp namespace by clicking + next to snmp. Select localhost by clicking on it, and then click OK.
212
Figure 6-9 Browse for Namespace to localhost
10.Click OK in the Browse For Namespace window. Click OK in the WMI Tivoli DM WorkBench Login window. 11.This will open the localhost snmp namespace on your machine. You will now see the window Resource Model Wizard: Select a class on your machine. Select the SNMP_RFC1213_MIB_ifTable class by doing the following steps: a. Expand the SnmpMacro class by clicking +. b. Expand the SnmpObjectType class by clicking +. c. Click on SNMP_RFC1213_MIB_ifTable. Validate that you see classes similar to the ones in Figure 6-10 on page 214.
213
Figure 6-10 Selecting a class
d. Once you validate your input, click Next. 12.In the Resource Model Wizard: Select Properties window, select the following properties by selecting the property and then clicking on the -> button. The properties that you need to select are: ifDescr ifIndex ifSpeed ifInOctets ifOutOctets You should see a window similar to Figure 6-11 on page 215.
214
Figure 6-11 Selecting properties
13.When done, click the Collection Test button in the Resource Model Wizard: Select Properties window. Validate that you see results similar to Figure 6-12 on page 216.
215
Figure 6-12 Collection test
14.Click Close in the Collected Instances window, and click Next in the Resource Model Wizard: Select Properties window. 15.The next window is Resource Model Wizard: Filtering. We specify a filter to exclude MS TCP Loopback Interface. Click the -> button in the middle of the window. Select the <> condition from the drop down selector and specify MS TCP Loopback Interface in the right input area.
Figure 6-13 Filter condition
16.When done, you will see the window shown in Figure 6-14 on page 217. Click Next.
216
Figure 6-14 Filtering
17.In the Resource Model Wizard: Specify the Event Triggering Condition window, we want to define the triggering criteria for the ifInOctets property and the ifOutOctets property. Click on ifInOctets first and click the -> button. 18.The Enter the Triggering Condition window appears. Select Increase at least by by clicking the drop-down box next to ifInOctets:. 19.In the blank field next to Increase at least by, enter 100000. Then click OK. 20.Do the same procedure for the ifOutOctets property. After that, validate the event trigger condition, as shown in Figure 6-15 on page 218.
217
Figure 6-15 Entering the trigger condition
21.Select OK in the Enter the Triggering Condition window and select Next in the Resource Model Wizard: Specify the Event Triggering Condition window. 22.Select which properties will be logged for Tivoli Enterprise Data Warehouse (TEDW) use in the Resource Model Wizard: Select the Properties to Log window. Leave this selection blank. Click Finish to complete the process and create the new Resource Model. 23.Select the default (which is 30) by clicking OK in the Enter the Cycle Time window. 24.Save the new Resource Model by selecting File Save As in the top menu.
Inputting values into the bits per second field

Follow these steps to input the values for the bits per second field: 1. Defining a new variable: the DeltaifOutBps and the DeltaifInBps in the VisitTree script.
218
a. To navigate to the VisitTree, click the drop-down box next to the Proc: field, and click on VisitTree (see Figure 6-16).
Figure 6-16 Using the Proc drop down selector
b. The cursor will now jump to the VisitTree. c. Locate the following statement: hPropTable = Svc.CreateMap(). d. Add the lines in Example 6-3 to the front of hPropTable = Svc.CreateMap(). These variables are used to store the delta values in the bit per second.
Example 6-3 Defining variables
Dim DeltaifOutBps As Double Dim DeltaifInBps As Double
2. Setting the initial value as the current value. a. Switch back to the VisitTree procedure by clicking the drop-down box and changing the value to VisitTree. b. Locate the hashKey = Str(curifIndex) line. Add the lines in Example 6-4 on page 220, except for the italic portions after hashKey = Str(curifIndex) line. Without this, the Resource Model initially set 0 to the OldifInOctets and the OldifOutOctets will cause unexpected events in the first monitoring cycle, because these MIB variables are the COUNTER type.
219
Example 6-4 Setting the first time values

hashKey = Str(curifIndex) OldifInOctets = curifInOctets OldifOutOctets = curifOutOctets found = Svc.ExistsMapElement(hTableifOutOctets, hashKey)
3. Calculating the delta variables in bps. c. In the VisitTree, locate the if ((flagNotFirstRun = True) And ( found <> 0 )) Then line. Add the lines in Example 6-5 to the front of the if ((flagNotFirstRun = True) And ( found <> 0 )) Then line.
Example 6-5 Editing decision tree script example 4
End If DeltaifInBps = (curifInOctets * 8 - OldifInOctets * 8) / Svc.GetCycleTime() DeltaifOutBps = (curifOutOctets * 8 - OldifOutOctets * 8) / Svc.GetCycleTime() If ((flagNotFirstRun = True) And ( found <> 0 )) Then
Note: The formulas used in the above example are well known practices. As we mentioned before, the ifInOctets MIB variable and the ifOutOctets MIB variable are octet (8 bits) values. If you compare them with the threshold expressed by the bit per second (bps), you need to calculate them as follows:
1. Multiple the octet value by 8. 2. Calculate the difference between the current bit value and previous one. 3. Divide the delta by the cycle time to calculate bps. When using full-duplex interface mode, you need to monitor in and out separately. Optionally, if you need the interface utilization in spite of the bps, divide the bps value by the ifSpeed MIB variable. Then you can obtain the interface utilization in the percent. 4. Changing the variable to be compared d. In the VisitTree, locate If ((curifInOctets - OldifInOctets) > Svc.GetThreshold("Thr_ifInOctets_in") ) Then line. Change (curifInOctets - OldifInOctets)to DeltaifInBps. In the next line, change curifInOctets - OldifInOctets to DeltaifInBps.
220
e. Locate the If ((curifOutOctets - OldifOutOctets) > Svc.GetThreshold("Thr_ifOutOctets_in") ) Then line. Change (curifInOctets - OldifInOctets) to DeltaifInBps. In the next line, change curifOutOctets - OldifOutOctets to DeltaifOutBps. Validate that you see the lines similar to the ones in Example 6-6.
Example 6-6 Editing decision tree script example 5
If ((flagNotFirstRun = True) And ( found <> 0 )) Then If (DeltaifInBps > Svc.GetThreshold("Thr_ifInOctets_in") ) Then Svc.SetMapNumElement(hPropTable,"Delta", DeltaifInBps) Svc.SetMapNumElement(hPropTable,"MaxAllowedDelta",Svc.GetThreshold("Thr_ifInOct ets_in")) Svc.SendEventEx "Ev_SNMP_RFC1213_MIB_ifTable_ifInOctets_grows_too_much", hPropTable End If If ( DeltaifOutBps > Svc.GetThreshold("Thr_ifOutOctets_in") ) Then Svc.SetMapNumElement(hPropTable,"Delta", DeltaifOutBps) Svc.SetMapNumElement(hPropTable,"MaxAllowedDelta",Svc.GetThreshold("Thr_ifOutOc tets_in")) Svc.SendEventEx "Ev_SNMP_RFC1213_MIB_ifTable_ifOutOctets_grows_too_much", hPropTable End If End If '((flagNotFirstRun = True) And ( found <> 0 ))
5. Build the Resource Model by selecting Build Build Package. 6. Save the new Resource Model by selecting File Save As. 7. Test that your new changes are correct by selecting DecisionTree Run in the top menu. If you do not get breakpoints within the WorkBench, your changes were made successfully. If you do find problems, make sure your changes correspond to the instructions in this document. 8. Close the IBM Tivoli Monitoring WorkBench by selecting File Exit.
6.2.3 Packaging the Resource Model

The various components discussed within this chapter must be packaged into a Resource Model tar file built with the Workbench. The Resource Model Tar File relationship diagram in Figure 6-17 on page 222 shows all components of a typical Resource Model, with those components that are not used within the ITSO_SNMP_Interface_Bps presented in light gray to de-emphasize their significance.
221

Configuration File Logging: Parameter(s): Action(s): Threshold(s):
Thr_ifOutOctets_in Thr_ifInOctets_in
JavaScript -or- Visual Basic Script Dynamic Model(s): CIM Class "SNMP_RFC1213_MIB_ifTable"
Event(s):
Ev_SNMP_RFC1213_MIB_ifTable_ifOutOctets_grows_too_much Ev_SNMP_RFC1213_MIB_ifTable_ifInOctets_grows_too_much
Reference Model Functions: ITSO_SNMP_Interface_Bps.vba
Message Catalogs
Provider(s):
MOF(s):
Custom Files(s)
Figure 6-17 Resource Model Tar File
Copy the package file to the TMR Server and register it to IBM Tivoli Monitoring Version 5.1.1, as shown in Example 6-7.
# wdmrm -add WizRM_SNMP_RFC1213_MIB_ifTable.tar IBM Tivoli Monitoring - Adding new Resource Model Copying WizRM_SNMP_RFC1213_MIB_ifTable.cat msgfile ... Copying WizRM_SNMP_RFC1213_MIB_ifTable.cat zipfile ...
IBM Tivoli Monitoring - Resource Model utility Parsing configuration file WizRM_SNMP_RFC1213_MIB_ifTable.conf ... Configuration file successfully parsed. Checking for event redefinition... Starting resource WizRM_SNMP_RFC1213_MIB_ifTable registration ... the resource WizRM_SNMP_RFC1213_MIB_ifTable has been successfully stored. Registration completed.
222
Installation completed.
When completed successfully, distribute the ITSO_SNMP_Interface_Bps Resource Model to the endpoint.
6.2.4 Testing the Resource Model

In this scenario, we use the debug function of the Workbench to test the new Resource Model. Do the following steps: 1. Open the IBM Tivoli Monitoring WorkBench by selecting Start Programs IBM Tivoli Monitoring 5.1.1 WorkBench WorkBench. 2. Open the ITSO_SNMP_Interface_Bps Resource Model by selecting File Open in the menu bar. 3. To navigate to the VisitTree, click the drop down selector next to the Proc: field, and click on VisitTree. Then click on the flagNotFirstRun = True line to set the cursor. 4. Select Debug Step to Cursor in the menu bar. Then locate the flagNotFirstRun = True line again. The cursor is set correctly when it turns yellow, as shown in Figure 6-18.
Figure 6-18 Step to cursor
5. Check the values of the variables, such as DeltaifInBps and DeltaifOutBps by clicking on Quick Watch in the right-click menu of these variables. You can see the result of the Quick Watch in the Immediate tab, as shown in Figure 6-19.
Figure 6-19 Quick Watch
223
6. In this cycle, the Resource Model does not generate the event, because the difference between the delta is lower than the threshold for the first time. To generate the event, copy the huge file (more than 100 MB) through the network interface. During the copy operation, ifInOctets and ifOutOctets continously grow and delta will exceed the threshold. 7. While the copy is running, select the flagNotFirstRun = True line and select Debug Step to Cursor in the menu bar. Then locate the flagNotFirstRun = True line again. You have to wait the length of the cycle time to see if the flagNotFirstRun = True line becomes yellow. 8. At this time, you know an event is generated in the Event Aggregator pane when the flagNotFirstRun = True line turns yellow, as shown in Figure 6-20.
Figure 6-20 Debugging the Resource Model
224
9. Check the values of the variables by right-clicking on any of these variables and selecting Quick Watch.
6.3 ITSO_SNMP_Interface_Bps source code

The files in this section were created for the purpose of this example.
6.3.1 ITSO_SNMP_Interface_Bps.vba
The decision tree script code used for the ITSO_SNMP_Interface_Bps Resource Model is shown in in its entirety in Example 6-8.
Example 6-8 Decision tree script
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ' IBM Tivoli Monitoring ' Decision Tree script ' ' This file has been generated by IBM Tivoli Monitoring Workbench ' ' 04/03/2003 14:54:24 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' Dim hTableifOutOctets As Integer Dim hTableifInOctets As Integer
' This subroutine implements the monitoring algorithm ' This subroutine is used for debugging the new Resource Model with the Workbench (or any other VB IDE). ' Remeber that this subroutine will never be called by the monitoring engine. ' Please, do not modify it. Public Sub Main() ' Creating an instance of the TMWService Object... Dim TMWService As Object Set TMWService = CreateObject("TMWService.Utilities") Dim RetVal As Long ' Calling the SetDefaultConfiguration (...) function to configure the ' Resource Model. RetVal = SetDefaultConfiguration (TMWService) If (RetVal = 0) Then
225
' At this point the monitoring engine will override default settings. ' Calling Init (...). RetVal = Init (TMWService) If (RetVal = 0) Then ' Entering the monitoring loop... ' It will loop forever. Do While (RetVal = 0) ' Collect Data TMWService.CollectData ' Visit the decision tree RetVal = VisitTree(TMWService) If (RetVal = 0) Then ' Wait for a cycle time TMWService.EndVisit Wait TMWService.GetCycleTime() End If 'VisitTree = 0 Loop End If 'Init = 0 End If 'SetDefaultConfiguration = 0 ' Clean up used resources TMWService.Dispose End Sub
' This function is used to define the settings of the Resource Model ' It is called only once, when the Resource Model is started. ' Don't modify remarks containing tags like <<....>> ... <<\...>> ' You can write additional initializing code in this function if required. Public Function SetDefaultConfiguration (Svc As Object) As Long ' General info section '<<GENERAL_INFO>> Svc.SetModelName "ITSO_SNMP_Interface_Bps" Svc.SetProfileName "1040968" Svc.SetCategory "ITSO_RMs"
226
Svc.SetCycleTime 30 '<<\GENERAL_INFO>> ' Thresholds section '<<THRESHOLDS_INFO>> Svc.DefineThreshold "Thr_ifOutOctets_in", 100000.000000 Svc.DefineThreshold "Thr_ifInOctets_in", 100000.000000 '<<\THRESHOLDS_INFO>> ' Parameters section '<<PARAMETERS_INFO>> '<<\PARAMETERS_INFO>> ' Dynamic Model section '<<DATA_INFO>> Svc.DefineClass "CIM", "root\snmp\localhost:SNMP_RFC1213_MIB_ifTable", "root\snmp\localhost:SNMP_RFC1213_MIB_ifTable", "WHERE ifDescr <> ""MS TCP Loopback Interface""", "ifIndex,ifSpeed,ifOutOctets,ifInOctets", "ifDescr", "None", "", 0, 1 '<<\DATA_INFO>> ' Event definition section '<<EVENTS_INFO>> Svc.DefineEvent "Ev_SNMP_RFC1213_MIB_ifTable_ifOutOctets_grows_too_much", "ifIndex,ifOutOctets,OldifOutOctets,Delta,MaxAllowedDelta", "" Svc.DefineEvent "Ev_SNMP_RFC1213_MIB_ifTable_ifInOctets_grows_too_much", "ifIndex,ifInOctets,OldifInOctets,Delta,MaxAllowedDelta", "" '<<\EVENTS_INFO>> ' Logging definition section '<<LOGGING_INFO>> '<<\LOGGING_INFO>> ' Place your additional intializing code below
SetDefaultConfiguration = 0 End Function
' This function is called by the monitoring engine after that ' the Resource Model default settings have been overridden ' It is called only once, when the Resource Model is started. ' You can write additional initializing code in this function if required ' to use the thresholds and parameters values Public Function Init(Svc As Object) As Long hTableifOutOctets = Svc.CreateMap()
227
hTableifInOctets = Svc.CreateMap() Init = 0 End Function
' This function contains the monitoring algorithm ' It is called ciclically after a cycle time has elapsed ' Implement the the monitoring code here Public Function VisitTree(Svc As Object) As Long Dim Dim Dim Dim Dim curifIndex As Double curifSpeed As Double curifOutOctets As Double curifInOctets As Double curifDescr As String
Dim hashKey As String Dim found As Long Static flagNotFirstRun As Boolean Dim OldifOutOctets As Double Dim OldifInOctets As Double Dim Dim Dim Dim Dim Dim hPropTable As Long numOfInstances As Long idx As Long ParamCount As Long ParamIdx As Long Different As Boolean
'Define additional Dim Dim DeltaifOutBps As Double Dim DeltaifInBps As Double hPropTable = Svc.CreateMap() numOfInstances = Svc.GETNUMOFINST("root\snmp\localhost:SNMP_RFC1213_MIB_ifTable") For idx = 0 To numOfInstances - 1 Svc.RemoveMapAll(hPropTable) curifIndex = Svc.GetNumProperty("root\snmp\localhost:SNMP_RFC1213_MIB_ifTable", idx, "ifIndex") Svc.SetMapNumElement(hPropTable,"ifIndex",curifIndex)
228
curifSpeed = Svc.GetNumProperty("root\snmp\localhost:SNMP_RFC1213_MIB_ifTable", idx, "ifSpeed") Svc.SetMapNumElement(hPropTable,"ifSpeed",curifSpeed) curifOutOctets = Svc.GetNumProperty("root\snmp\localhost:SNMP_RFC1213_MIB_ifTable", idx, "ifOutOctets") Svc.SetMapNumElement(hPropTable,"ifOutOctets",curifOutOctets) curifInOctets = Svc.GetNumProperty("root\snmp\localhost:SNMP_RFC1213_MIB_ifTable", idx, "ifInOctets") Svc.SetMapNumElement(hPropTable,"ifInOctets",curifInOctets) curifDescr = Svc.GetStrProperty("root\snmp\localhost:SNMP_RFC1213_MIB_ifTable", idx, "ifDescr") Svc.SetMapStrElement(hPropTable,"ifDescr",curifDescr) hashKey = Str(curifIndex) ' OldifInOctets = curifInOctets OldifOutOctets = curifOutOctets found = Svc.ExistsMapElement(hTableifOutOctets, hashKey) If found Then OldifOutOctets = Svc.GetMapNumValue(hTableifOutOctets, hashKey) Svc.SetMapNumElement(hPropTable,"OldifOutOctets",OldifOutOctets) End If found = Svc.ExistsMapElement(hTableifInOctets, hashKey) If found Then OldifInOctets = Svc.GetMapNumValue(hTableifInOctets, hashKey) Svc.SetMapNumElement(hPropTable,"OldifInOctets",OldifInOctets) End If 'ifInUtil = ( curifInOctets * 8 - OldifInOctets * 8 ) / ( curifSpeed * Svc.GetCycleTime() ) 'ifOutUtil = ( curifOutOctets * 8 - OldifOutOctets * 8 ) / ( curifSpeed * Svc.GetCycleTime() ) DeltaifInBps = ( curifInOctets * 8 - OldifInOctets * 8 ) / Svc.GetCycleTime() DeltaifOutBps = ( curifOutOctets * 8 - OldifOutOctets * 8 ) / Svc.GetCycleTime() If ((flagNotFirstRun = True) And ( found <> 0 )) Then If (DeltaifInBps > Svc.GetThreshold("Thr_ifInOctets_in") ) Then Svc.SetMapNumElement(hPropTable,"Delta", DeltaifInBps) Svc.SetMapNumElement(hPropTable,"MaxAllowedDelta",Svc.GetThreshold( "Thr_ifInOctets_in"))
229
Svc.SendEventEx "Ev_SNMP_RFC1213_MIB_ifTable_ifInOctets_grows_too_much", hPropTable End If If ( DeltaifOutBps > Svc.GetThreshold("Thr_ifOutOctets_in") ) Then Svc.SetMapNumElement(hPropTable,"Delta", DeltaifOutBps) Svc.SetMapNumElement(hPropTable,"MaxAllowedDelta",Svc.GetThreshold( "Thr_ifOutOctets_in")) Svc.SendEventEx "Ev_SNMP_RFC1213_MIB_ifTable_ifOutOctets_grows_too_much", hPropTable End If End If '((flagNotFirstRun = True) And ( found <> 0 )) flagNotFirstRun = True Svc.SetMapNumElement(hTableifOutOctets,hashKey, curifOutOctets) Svc.SetMapNumElement(hTableifInOctets,hashKey, curifInOctets) Next Svc.DestroyMap(hPropTable) VisitTree = 0 End Function
230
Chapter 7.
Creating an SNMP Resource Model for Java

In Chapter 6, Creating an SNMP Resource Model for Windows on page 201, we demonstrated how to create a Resource Model utilizing the SNMP WMI Provider for the Windows platform. In this chapter, our focus will be the creation of a custom ILT to integrate an IBM developed SNMP package specifically for the Java platform. Though we are implementing the IBM SNMP Java package, we will only discuss the classes used within our ILT and the SNMP details as they relate to this effort. We will use the ITSO_Sample ILT introduced in Chapter 5, Engineering a Java ILT on page 137, as a template to minimize development time. This chapter describes the following topics: Terminology relevant to this implementation Planning and design of the ITSO_SnmpProbe ILT and Resource Model Implementing the ITSO_SnmpProbe ILT and Resource Model ITSO_SnmpProbe source code
231
7.1 Terminology
Many of the concepts and technologies discussed within this chapter may be new to non-network administrators. As this chapter can be a valuable example of how to implement third party Java packages, we will define a few key terms as they are referenced throughout this chapter to eliminate potential confusion.
Java Package SNMP
A Java package is a pre-compiled set of classes contained within a jar file. Simple Network Management Protocol is a protocol for Internet network management services. It is formally specified in a series of related RFC documents. Management Information Block is a collection of objects that describe an SNMP manageable entity. There is only one SNMP MIB. All the other MIBs that are cited herein are extensions to the SNMP MIB. Designers of network equipment decide which features of their products will be accessible via SNMP, and then create hardware and software to support this management. The collection of the descriptions of all of these features is called a Management Information Base (MIB), and a description of an individual manageable feature in the MIB is referred to as a MIB Variable. Each branch of the MIB Tree has a number and a name, and the complete path from the top of the tree down to the point of interest forms the name. A name created in this way is known as an Object ID or OID. Every process running on a UNIX system is identified by a unique number called the process ID (PID).
MIB
OID
PID
7.2 Planning and design

During the planning phase of this Resource Model, the primary objectives were defined as providing an ILT example that would utilize the IBM SNMP Java package for the purpose of performing an SNMP poll of specific MIB values on a remote device. Secondary objectives included a demonstration of how to implement the ILT template, the required CIM definition, and provide any configurable parameters required to be passed to the ILT. In the planning and design phase of this Resource Model, we followed the same top-down methodology as our previous examples, while the development of the model was again performed from the bottom up. The Managed Object Format
232
(MOF) file was created first to define the CIM class, followed by the supporting ILT and Provider Java classes, and finally the Resource Model wrapper was created through the ITM Workbench.

The requirements for this Resource Model are straight forward: Demonstrate the use of JavaScript within a Resource Model. Demonstrate the use of the ITSO_Sample ILT template provided in Chapter 5, Engineering a Java ILT on page 137. Provide a host name parameter that permits Administrators to define a list of hosts that the SNMP probe will remotely poll. Keep the Resource Model within the primary scope of this redbook and focus on instrumentation; not logging, events, or attributes. Ensure a good demonstration of supportability through easily traceable and consistent naming conventions throughout the model, CIM, and ILT. Implement base functionality that would permit a large number of readers to use the sample as a starting point for more advanced SNMP integration. Based on these requirements, it was determined that the model would be created from a copy of the ITSO_Sample under the name ITSO_SnmpProbe and in the standard model category for the redbook (ITSO_RMs).
7.2.2 CIM class

Based on the requirements determined by the planning of the Resource Model, a new CIM class had to be defined to provide the required MIB information to the Resource Model. There are three specific requirements for the CIM definition that were determined: The class properties must follow a naming convention consistent with the naming defined by MIB standards, to keep with the defined supportability requirement. The CIM class must implement the Tivoli M12 qualifiers. The CIM class must include descriptor elements to support user-friendly CIM namespace browsing.
Note: Though this Resource Model was designed for the Java platform, it could be enhanced to support the Windows platform. This would require the creation of an additional MOF file that would include the Windows requirements, as explained in other chapters of this book.
Chapter 7. Creating an SNMP Resource Model for Java
233
A high-level CIM class definition was determined as follows: Class ITSO_SnmpProbe ifIndex: The class instance key obtained from the OID 1.3.6.1.2.1.2.2.1.1. ifDescr: Parameter of the type string obtained from the OID 1.3.6.1.2.1.2.2.1.2. ifSpeed: Parameter of the type string obtained from the OID 1.3.6.1.2.1.2.2.1.5. ifInOctets: Parameter of the type string obtained from the OID 1.3.6.1.2.1.2.2.1.10. ifOutOctets: Parameter of the type string obtained from the OID 1.3.6.1.2.1.2.2.1.16.
7.2.3 ILT class

The ILT class exists to provide the dynamically pluggable interface discussed earlier. Therefore, the ILT for this sample must meet the following requirements: The ILT class must follow the defined supportability requirement and should use the name ITSO_SnmpProbeIlt to be clearly associated with the CIM class and Provider it will be binding. The ILT must following the IBM Tivoli PAC development team defined packaging naming standard and should use the Java package name com.ibm.tivoli.monitoring.ITSO_SnmpProbe. Implement tracing functionality to better follow the supportability requirement. The ILT class must implement the required M12 functionality to: Support the ILTInterface specification. Implement the retrieval of instance identification, parameters being passed from the Resource Model, and the values of the parameters. The ILT class should provide any internal private methods as needed to support the SNMP polling functionality.
234
7.2.4 Provider class

This Provider class exists to perform the physical instrumentation through the SNMP package. In the case of this sample, the Provider must meet the following requirements: The Provider class must follow the defined supportability requirement and should use the name ITSO_SnmpProbe to be clearly associated with the ILT class it will be instantiated by. The ILT must following the IBM Tivoli PAC development team defined packaging naming standard and should use the Java package name com.ibm.tivoli.monitoring.ITSO_SnmpProbe. The Provider class must implement tracing functionality to better follow the supportability requirement. The Provider class must include methods to handle each of the following: Object creation: performed by the method ITSO_SnmpProbe. Instance initialization and discovery. In the case of this model, the Java class Vector and the vector methods were implemented to handle the dynamic number of network interfaces on the remote device. Methods to service each property of the CIM class by providing the dynamic MIB values polled by the implemented SNMP classes.
7.2.5 Component reference

In review of the aforementioned design requirements, the ITM Engine Logical Components diagram can be revisited. The components of the engine that will be utilized by the planned Resource Model within this chapter can be seen in Figure 7-1 on page 236. Those components that will not be used within the ITSO_SnmpProbe are presented in light gray to de-emphasize their significance.
235

Custom Scripts
ILT Providers
Resource
Resource
Resource
Figure 7-1 Java: ITM logical components
7.3 Implementing
The implementation phase of the design includes a variety of efforts as well as a variety of tools. As mentioned in 7.2.5, Component reference on page 235, the implementation was handled in a bottom-up fashion due to each layer being dependent on the layer below. Therefore, the four components to be created below are presented in the order of development: The Managed Object Format (MOF) file ITSO_SnmpProbe.mof was developed with a text editor but compiled and imported with mofcomp. The Java class for the ILT ITSO_SnmpProbeIlt.java was developed with a text editor and the IBM JDK 1.3.1. The Provider class ITSO_SnmpProbe.java, was developed with a text editor and the IBM JDK 1.3.1.
236
The supporting class, SnmpInterface.java, was developed with a text editor and the IBM JDK 1.3.1. The Resource Model ITSO_SnmpProbe.dmjsws was developed with the ITM Workbench.
7.3.1 Managed object format

In the ITSO_SnmpProbe, we have implemented only the core requirements for the object definition. This was to ensure the sample was easy to understand as well as easily customizable. In many cases, additional descriptors may be required to ensure the object behaves in a precise and predictable manner.
CIM qualifiers
The qualifiers implemented followed the ITSO_Sample implementation to meet the functional requirements while maintaining a clean and easy to understand design. Unlike the template however, this Resource Model has specific real-world requirements. Those requirements include specific use of the qualifiers to ensure a usable and logic MOF file.
Description
The Description qualifier is used throughout the ITSO_SnmpProbe class definition as a development best practice for both classes and class properties, ensuring the description information can be viewed by CIM browsing utilities once the MOF file is compiled into a localized CIM repository. The use of the Description qualifier within this sample is demonstrated in Example 7-1 for both the class as well as the first property declaration.
Example 7-1 ITSO_SnmpProbe.mof: Description usage
[ Description ("ITSO SNMP Probe: This class was created to demonstrate the " "integration of the IBM SNMP Java API with an ITM provider."), . . . [ Description("This property defines the index of the interface " "being poled. The associated OID is 1.3.6.1.2.1.2.2.1.1" ), key ]
The MOF file was loaded into the Windows CIM repository during development and was browsed through the ITM Workbench. The Description qualifiers are viewable from the Dynamic Model dialog boxs Show Description feature. Notice in Figure 7-2 on page 238 that the description for the class and the class properties are all displayed. This is extremely useful when a CIM class will be implemented by multiple Resource Model developers.
237
Figure 7-2 ITM Workbench: About selected class
Provider
The Provider qualifier is used within the ITSO_SnmpProbe class definition to define the library (class) that will implement an instance interface to the Provider class. As this model is designed specifically for the ITM Java engine, we will again use the M12JavaProvider, as demonstrated in Example 7-2.
Example 7-2 ITSO_SnmpProbe.mof: Provider usage
provider("com.tivoli.dmunix.ep.touchpoint.cimom.ifc.M12JavaProvider"),
M12 _Instrumentation
The M12_Instrumentation qualifier is used within the ITSO_SnmpProbe class definition to define the package and class that will perform the physical instrumentation actions for both the ENUM and GET functionalities. This model is designed specifically for the ITM Java engine, so the Java class ITSO_SnmpProbeIlt contained in the package Java.com.ibm.tivoli.monitoring.ITSO_SnmpProbe is defined as the instrumentation class(es) and is demonstrated in Example 7-3.
Example 7-3 ITSO_SnmpProbe.mof: M12_Instrumentation usage
M12_Instrumentation { "Java.com.ibm.tivoli.monitoring.ITSO_SnmpProbe.ITSO_SnmpProbeIlt | | ENUM", "Java.com.ibm.tivoli.monitoring.ITSO_SnmpProbe.ITSO_SnmpProbeIlt | | GET"}
238
Key
The key property qualifier is used within the ITSO_SnmpProbe class itself to define the property ifIndex as the primary key or index to the class. In this class, this property is the instance of the network interface obtained through the SNMP MIB polling of the host. This property, along with the others polled for the interfaces, is maintained by the instance of the class SnmpInterface. To simplify the mapping between the ITSO_SnmpProbe instances and the MIB network interfaces, a direct relationship was created. That is, the interface instance value retrieved from the host through the SNMP polling of the MIB value ifIndex is used by ITSO_SnmpProbe as the actual instance key within the private SnmpInterface class. The definition of this qualifier is demonstrated in Example 7-4.
Example 7-4 ITSO_SnmpProbe.mof: Key usage
// Attribute, Instance Count. [ Description("This property defines the index of the interface " "being poled. The associated OID is 1.3.6.1.2.1.2.2.1.1" ), key ] string ifIndex;
7.3.2 ILT Java class

The ILT class, ITSO_SnmpProbeILT, is the interface between the TSL of the ITM Engine and the custom Provider. The actual interfacing is handled through the implementation of the M12 Public Operations, as defined by this class. This CIM class has been designed to represent an SNMP MIB Network Interface. Therefore, this ILT class was created to handle multiple requirements: The initialization of the Provider class Incoming data requests from the ITM Engine through the supported ILTInterface methods Determining which CIM properties need to be acquired from the Provider through M12 method calls Performing the SNMP integration tasks and package management. This in itself is composed of a few sub-requirements SNMP package initialization and declarations Session management Host communications Vector management for multiple, dynamically allocated network interface objects Mapping of MIB OID values retrieved to SnmpInterface class properties
239
Commenting Java Files

As discussed in Chapter 5, Engineering a Java ILT on page 137, comments have been implemented within this Providers Java files. This is a best practice in the software development arena and will appear throughout this class, as demonstrated in Example 7-5.
Example 7-5 ITSO_SnmpProbeIlt.java: Comment header
//----------------------------------------------------------------------------// // ITSO_SnmpProbeILT.java // // Description: // This file is the ITSO_SnmpProbe Instrumentation Library Type (ILT) // implementation. This is the class instantiated by the "touchpoint" // layer. This class will execute methods in the "ITSO_SnmpProbe.java" // file, which is the physical "provider" and performs the actual data // acquisition. // // History: // Date Author Description // -------- ------------------ -----------------------------------------// 05/13/03 ITSO Redbook Team Original file. // //-----------------------------------------------------------------------------
Java package
The naming standard implemented by Tivoli PAC developers is that the Java package for the ILT be in the path com.ibm.tivoli.monitoring. This naming convention was implemented for the ITSO_SnmpProbe and can be seen in both the ILT and Provider classes. This ensures that all required classes for the ILT are handled by the same ITM Engine loader, providing consistent class access. The package declaration within both immediately follows the comment header and can be seen in Example 7-6.
Example 7-6 ITSO_SnmpProbeIlt.java: Package declaration
package com.ibm.tivoli.monitoring.ITSO_SnmpProbe; // PAC Development // naming convention.
Java imports
Various Java classes were utilized within the sample. These classes were declared through the standard Java import statement, as shown in Example 7-7 on page 241.
240
Example 7-7 ITSO_SnmpProbeIlt.java: Import declarations

import import import import import com.ibm.tivoli.monitoring.ITSO_SnmpProbe.*; com.tivoli.dmunix.ep.touchpoint.base.*; com.tivoli.javautils.Trace; java.util.Enumeration; java.util.Vector; // // // // // "ITSO_SnmpProbe.class" "dm_m12.jar" "javautils.jar" Java Class Java Class
The first import, com.....ITSO_SnmpProbe, allows for the referencing of the Provider class ITSO_SnmpProbe. This class is defined in the file ITSO_SnmpProbe.java and is defined as part of the same package as the ILT class. The relevant jar file for this import is ITSO_SnmpProbe.jar, of which this file is a part. The second import, com.tivoli.dmunix.ep.touchpoint.base.*, supports the ILT Interface class as well as the M12 ILT Public Operations, which are well documented in Appendix D, Instrumentation Library Type Interface (ILT), in the IBM Tivoli Monitoring Workbench Users Guide, Version 5.1.1, SH19-4571. The relevant jar file for this import is dm_m12.jar. The third import, com.tivoli.javautils.Trace, supports writing to the trace_dmxengine.log file via the Trace class. The relevant jar file for this import is javautils.jar. The fourth import, java.util.Enumeration, supports the Enumeration class, which supports the creating of a series of elements. This is viewable in the declaration of the enumerateInstances method. The fifth import, java.util.Vector, supports the Vector class, which allows for dynamically sized lists through the use of Java pointers. In the case of this class, it provides both the means to obtain the list of parameters passed from the ITM Engine and an internal method to handle the dynamic list of network interface classes obtained from the SNMP polling process.
ILT interface implementation

The ITSO_SnmpProbe class implements the ILTInterface class interface, as demonstrated in Example 7-8.
Example 7-8 TSO_SnmpProbeIlt.java: Class implementation
public class ITSO_SnmpProbeIlt implements ILTInterface
Supporting class methods

A creator method, ITSO_SnmpProbeIlt, was included in the class, as seen in Example 7-9 on page 242. This method is automatically executed at the
241
instantiation of the ILT sample by the ITM Engine. Its purpose is to perform any class initialization work required.
Example 7-9 ITSO_SnmpProbeIlt.java: Creator
//-------------------------------------------------------------------------// ITSO_SnmpProbeIlt class - Creator method. //-------------------------------------------------------------------------public ITSO_SnmpProbeIlt() { pSnmpProbe = new ITSO_SnmpProbe(); trace = Trace.getTraceInstance(); }
ILT public operations (methods)

To correctly support the interfacing of our ILT with the M12 specification, all public operations (methods) should be implemented. Not all ILTs may require operational code within the methods. Methods that were not mandated for this sample were implemented but without any logging. This was done to keep the code as simple and clean as possible.
getProperty
As the ITSO_Sample files were used as the basis of this Provider, this operation was included. However, we did not add the M12_Instrumentation qualifier to any individual properties within the MOF file, ITSO_SnmpProbe.mof, for this class. Therefore, this method is not utilized by the engine.
This operation, shown in Example 7-10 on page 243, was implemented to support the handling of multiple properties, as the MOF file has a class level M12_Instrumentation qualifier. This class level qualifier designates the ITSO_SnmpProbeILT class as the handler of all properties without individual instrumentation statements. In the case of the SnmpInterface class, all of the values are obtained simultaneously from the host(s) specified in the model parameters. Of course, the values are not actually obtained simultaneously, but are acquired through the SNMP session within the same request issued to the host. This returns a set of values that are walked through by the ILT and loaded into the SnmpInterface classes maintained within the Provider class, ITSO_SnmpProbe.
242
Example 7-10 ITSO_SnmpProbeIlt.java: getMultipleProperties method

public M12PropertySet getMultipleProperties( M12ObjectIdentity m12objectidentity, Vector vPropertyList, String sMapping, ParameterSet parameterset ) throws M12Exception { int iIndex; try { M12IdentityElement m12identityelement = m12objectidentity.getScopingPath()[0]; M12PropertySet m12propertyset = m12identityelement.getIdentity(); // Determine which instance is being checked by the // Management Layer. String sKey = m12propertyset.getProperty("ifIndex"); M12PropertySet m12propertyset1 = new M12PropertySet(); trace.log( 3, "ITSO_SnmpProbeIlt", "getMultipleProperty: called for ifIndex " + sKey); // Update the instance. // This is performed once as the entire SNMP polling // is performed to fill the data structure simultaneously // to ensure data validition and SNMP efficiency. // As in the Provider, the index is physically 0 to n, // where n equals iIndex-1. iIndex = (new Integer(sKey)).intValue(); iIndex--; // Update the individual requested properties. for(int i = 0; i < vPropertyList.size(); i++) { // Get the property being checked by the Management Layer. String sProperty = (String)vPropertyList.elementAt(i); // Get the current property values. String sValue = getAttribute(iIndex, sProperty); m12propertyset1.setProperty(sProperty, sValue); } trace.log( 3, "ITSO_SnmpProbeIlt", "getMultipleProperty: returning " + WriteBuffer(m12propertyset1)); return m12propertyset1;
243
} catch(Exception exception) { trace.exception("ITSO_SnmpProbeIlt", "getMultipleProperty", exception); M12Exception m12exception = new M12Exception(exception); throw m12exception; } }
enumerateInstances
This operation, shown in Example 7-11, was implemented to support the enumeration of instances of the ITSO_SnmpProbe CIM class. This function will determine how many instances of the monitored object, in this case, the Network Interfaces on the specified hosts, exist, and will handle appropriate configuration of those instances as well as return the count.
Example 7-11 ITSO_SnmpProbeIlt.java: enumerateInstances method
public Enumeration enumerateInstances( M12ClassPath m12classpath, String sMapping, ParameterSet parameterset ) throws M12Exception { try { // Variable Declaration. StringBuffer stringbuffer = new StringBuffer(); Vector vector = new Vector(); //-----------------------------------------------------------------// Get the parameters from the caller. // We are obtaining the parameters prior to declaring instances so // we can configure an instance for specific parameters as needed. //-----------------------------------------------------------------Enumeration enumeration = parameterset.parametersNames(); Vector vHostnames = (Vector)parameterset.getParam("ITSO_Hostnames"); if(vHostnames == null) { trace.log( 3, "ITSO_SnmpProbeIlt", "enumerateInstances: no ITSO_Hostnames parameters found"); return null; } //-----------------------------------------------------------------// NOTE: // This routine has been hardcoded to only perform the pole // on a single hostname, the first.
244
// // //
// This application has numerous "hooks'n'latches" to support // multiple hostnames, though we're stopping work here. // Demonstrating the integration with the IBM SNMP Java package // was the goal, NOT trying to replace NetView! //-----------------------------------------------------------------// Process the ITSO_Hostnames parameter. String asHostnames[] = new String[vHostnames.size()]; asHostnames[] = new String[1]; for(int iIndex = 0; iIndex < vHostnames.size(); iIndex++) { // HARDCODED for only the first hostname! int iIndex = 0; // Get the string array element from the vector element. asHostnames[iIndex] = (String)vHostnames.elementAt(iIndex); trace.log( 3, "ITSO_SnmpProbeIlt", "enumerateInstances: asHostnames[" + iIndex + "]=" + asHostnames[iIndex]); } //-----------------------------------------------------------------// Acquire a vector (pointer) from the calling ILT Manager. // This section handles the registration of instances of this // Instrumentation. //-----------------------------------------------------------------String asInst[] = pSnmpProbe.getInstances( asHostnames ); if(asInst == null) { trace.log( 3, "ITSO_SnmpProbeIlt", "enumerateInstances: no instances found"); return null; } for(int jIndex = 0; jIndex < asInst.length; jIndex++) { trace.log( 3, "ITSO_SnmpProbeIlt", "enumerateInstances: aiInst[" + jIndex + "] = " + asInst[jIndex]); M12PropertySet m12propertyset = new M12PropertySet(); m12propertyset.setProperty( "ifIndex", String.valueOf(asInst[jIndex]) ); M12IdentityElement m12identityelement = new M12IdentityElement( m12classpath.getClassName(), m12classpath.getNameSpace(), m12propertyset); vector.add( new M12ObjectIdentity( new M12IdentityElement[] { m12identityelement } ) ); }
//
245
return vector.elements(); } catch(Exception exception) { trace.exception("ITSO_SnmpProbeIlt", "enumerateInstances", exception); M12Exception m12exception = new M12Exception(exception); throw m12exception; } }
setProperty
This method, shown in Example 7-12, was implemented due to its inclusion in the M12 specification, but is not yet supported. Therefore, the tracing elements that were included within the code from the ITSO_Sample template were removed for cleanliness sake.
Example 7-12 ITSO_SnmpProbeIlt.java: setProperty method
public String setProperty( M12ObjectIdentity m12objectidentity, String sName, String sValue, String sMapping, ParameterSet parameterset ) throws M12Exception { return null; }
invokeMethod
This method, shown in Example 7-13, actually provides two interfaces. Both were implemented, as they are included in the M12 specification. These methods are supported; however, the invocation of these class methods was not required for this sample. Therefore, the tracing elements that were included within the ITSO_Sample template code were removed.
Example 7-13 ITSO_SnmpProbeIlt.java: invokeMethod method
public String invokeMethod( M12ClassPath m12classpath, String sMethodName, String sMapping, ParameterSet parameterset, ParameterSet parameterset1, ParameterSet parameterset2 ) throws M12Exception { return null;
246
create
This method, shown in Example 7-14, was implemented only as it is included in the M12 specification, though it is not yet supported. Therefore, the tracing elements that were included within the ITSO_Sample template code were removed.
Example 7-14 ITSO_SnmpProbeIlt.java: Create method
public void create( M12ObjectIdentity m12objectidentity, String sMapping, ParameterSet parameterset ) throws M12Exception { return; }
destroy
This method, shown in Example 7-15, was implemented only as it is included in the M12 specification, though it is not yet supported. Therefore, the tracing elements that were included within the ITSO_Sample template code were removed.
Example 7-15 ITSO_SnmpProbeIlt.java: Destroy method
public void destroy( M12ObjectIdentity m12objectidentity, String sMapping, ParameterSet parameterset ) throws M12Exception { return; }
ILT supported classes

The implementation of the M12 interfacing for this ILT requires that various ILT support classes be used. These classes were implemented by default through our use of the ITSO_Sample template and can be referenced in Chapter 5, Engineering a Java ILT on page 137. As these classes were not modified beyond the template implementation, we will not discuss them within this sample.
Custom methods
These methods are not part of the required ILT interfacing and are only used from a utility perspective. They allow for cleaner code as well as a single point of management for common functions.
247
getITSOAttribute
This method, shown in Example 7-16, was developed as a centrally manageable function to handle the actual calling of the methods within the Provider instances. The function is passed from the reference to the instance key and the class property, which are both specified in the CIM definition.
Example 7-16 ITSO_SnmpProbeIlt.java: getITSOAttribute method
private String getAttribute( int iIndex, String sProperty ) throws Exception { //---------------------------------------------------------------------// Process each CIM class property. //---------------------------------------------------------------------if(sProperty.equals("ifIndex")) { String sReturn = new String( pSnmpProbe.getifIndex(iIndex) ); return sReturn; } else if(sProperty.equals("ifDescr")) { String sReturn = new String( pSnmpProbe.getifDescr(iIndex) ); return sReturn; } else if(sProperty.equals("ifSpeed")) { String sReturn = new String( pSnmpProbe.getifSpeed(iIndex) ); return sReturn; } else if(sProperty.equals("ifInOctets")) { String sReturn = new String( pSnmpProbe.getifInOctets(iIndex) ); return sReturn; } else if(sProperty.equals("ifOutOctets")) { String sReturn = new String( pSnmpProbe.getifOutOctets(iIndex) ); return sReturn; } //---------------------------------------------------------------------// Unknown property. //---------------------------------------------------------------------else { throw new Exception(sProperty + ": unknown property"); }
248
WriteBuffer
This is essentially a utility method that was created for the purpose of easily dumping values from a passed M12PropertySet class to a String object that is returned to the caller (see Example 7-17).
Example 7-17 ITSO_SnmpProbeIlt.java: WriteBuffer method
private String WriteBuffer( M12PropertySet m12propertyset ) { Enumeration enumeration = m12propertyset.propertyNames(); StringBuffer stringbuffer = new StringBuffer(); String sElement; String sProperty; for(; enumeration.hasMoreElements(); stringbuffer.append(sElement + " = " + sProperty + " ")) { sElement = (String)enumeration.nextElement(); sProperty = m12propertyset.getProperty(sElement); } return stringbuffer.toString(); }
7.3.3 Provider Java class

The Provider class, ITSO_SnmpProbe handles class instance initialization, management and initialization of any private data members relevant to the class instance, and methods to provide values for specific CIM properties to the instantiating ILT class. Therefore, this class is a completely custom class designed around a specific use designed by the CIM. Its functionality has been segregated from the aforementioned ILT class, ITSO_SnmpProbeILT, as it is designed to be instantiated for each CIM object reference. This class has been designed to represent a Network Interface on a remote host and therefore, as a Provider, handles all relevant management for the SNMP package as well as the parsing of MIB data and management of the interface class. As there may be multiple interfaces on the host, the Provider functionality has been designed to handle dynamic quantities of the remote host interface instances through the private use of a Java vector class. Support for the vector class includes initialization, internal management of the vector data within the member functions, and the implementation of the class SnmpInterface that represents the actual MIB fields probed.
249
The instance management by this Provider class is designed to be as straightforward and simple in design as possible. For each interface found through the SNMP probing of OIDs on the remote hosts specified, an instance of SnmpInterface is created and filled with the MIB data. Each of these SnmpInterface classes is added to the private vector table as a form of static storage to maintain persistence between function calls. As this model was written for the processing of a single remote host, though hooks are provided for more complex future operation, the index mapping of the SnmpInterface class to CIM ITSO_SnmpProbe instances is simple. The index within the private vector table is used as the instance index by the Resource Model. This Provider class obtains data by probing specific SNMP OID values on remote hosts. The code within the methods that perform these tasks include the interfacing to an SNMP Java package. This package was obtained through internal channels at IBM, but is available at the IBM Redbooks Web site as part of the downloadable code from this book. The SNMP package has been included in numerous IBM products, including IBM Tivoli Monitoring 5.1.0 (though subsequently removed from 5.1.1), and has an excellent track record for stability. Delving into the use of this package is not for the weak-of-heart, as both Java and SNMP skill sets are required proper implementation. Please be advised that this package is provided as-is with no support from the team that developed this book or from IBM support.
Java package
The naming standard implemented by Tivoli PAC developers is that the Java package for the ILT be in the path com.ibm.tivoli.monitoring. This naming convention was implemented for the ITSO_SnmpProbe and has been implemented within this class as well. This ensures that all required classes for the ILT are handled by the same ITM Engine loader, providing consistent class access. The package declaration within both immediately follows the comment header and can be seen in Example 7-18.
Example 7-18 ITSO_SnmpProbe.java: Package declaration
package com.ibm.tivoli.monitoring.ITSO_SnmpProbe; // PAC Development // naming convention.
Java imports
Various Java classes were utilized within the sample Provider. These classes were declared through the standard Java import statement, as shown in Example 7-19 on page 251.
250
Example 7-19 ITSO_SnmpProbe.java: Java imports

import import import import import import import com.tivoli.javautils.Trace; com.tivoli.snmp.data.*; com.tivoli.snmp.utils.*; com.tivoli.snmp.*; java.util.*; java.util.Vector; java.io.Serializable; // // // // // // // For debugging. SNMP Requirement SNMP Requirement SNMP Requirement Dynamic object array handler. SNMP Requirement
Custom methods
These methods exist to represent the CIM object ITSO_SnmpProbe from a software perspective, not from a physical attribute perspective. This means that a method exists within the Provider class to handle class instance initialization, and access to any private data members relevant to each class instance. These routines are completely custom to the class and will most likely not exist in your Provider implementation. They will realistically be replaced with more appropriate get property methods, as is required by your Provider specification, but will still be referenced from within your ILT class.
ITSO_SnmpProbe
This is the class creator that supports the initialization of the Provider class instance. In the case of this Provider, only one instance is created by the ITSO_SnmpProbeILT. This creator method performs no specialized functions other than to initialize the Trace class, as shown in Example 7-20.
Example 7-20 ITSO_SnmpProbe.java: ITSO_SnmpProbe
public ITSO_SnmpProbe() { trace = Trace.getTraceInstance(); }
getInstances
This method generates an array of values representing the interface instance derived from the SnmpInterface class property ifIndex stored in the vector. This property is designated as the class key, and is therefore used for instance referencing by the M12 layer. Though this implementation does not maximize potential efficiencies, such as searching the vector based on the key or perform more in-depth M12 value mapping, it does meet the requirements for this model to be functional as well as provide a logical basis for enhancement. For reference, the ITSO_SnmpProbeIlt class method enumerateInstances calls this getInstances method to obtain this instance array and register the values to the M12PropertySet class via the setProperty method.
251
In this method, you will note that though the code exists to process a complete list of host names to be polled, it is commented out in favor of hardcoded restrictions forcing only one host, the first in the list, to be processed. This was determined to be the best solution to address time restrictions during the development while providing hooks within the code that readers may expand upon. You will see yet another hook for such enhancements in that a host name string exists within the SnmpInterface.java class, as demonstrated later in this section. There are two logical sections to this method. The first section handles the building of or updating to the vector table for each host name within the passed-in host name array asHostnames and is demonstrated in Example 7-21. The actual manipulation of the vectors is handled through the method snmpPole. The snmpPole method is designed to throw an exception during potential errors and is therefore wrapped within a try-catch.
Example 7-21 ITSO_SnmpProbe.java: getInstances vector table
// The instances will be referenced by number to keep it simple. // for(int iIndex = 0; iIndex < asHostnames.length; iIndex++) for(int iIndex = 0; iIndex < 1; iIndex++) { // Get the string array element from the vector element. trace.log( 3, "ITSO_SnmpProbe", "getInstances iIndex=" + iIndex); // Poll the SNMP information to determine how to index the array. try { // Perform the initial pole: // Configure the vector snmpPole(asHostnames[iIndex]); trace.log( 3, "ITSO_SnmpProbe", "getInstances: vInterfaceList.size()=" + vInterfaceList.size()); } catch (Exception eSnmpPole) { trace.exception("ITSO_SnmpProbeIlt", "getInstances", eSnmpPole); } }
The second logical section of this method is the population of the instance array with the instance keys, as demonstrated in Example 7-22 on page 253. The keys are maintained within the SnmpInterface class instances stored in the vector table. Therefore, to obtain these values, we must load each of the classes within
252
the vector table, copy the ifIndex class property into our array aifIndex, and finally return the array to the calling method.
Example 7-22 ITSO_SnmpProbe.java: getInstances array population
// Build the string list of ifIndex(es) from the vector. iTemp = vInterfaceList.size(); trace.log( 3, "ITSO_SnmpProbe", "getInstances iTemp=" + iTemp); String aifIndex[] = new String[iTemp]; if( vInterfaceList.size() > 0 ) { for(int iIndex = 0; iIndex < vInterfaceList.size(); iIndex++) { // SNMPInterface siTemp = (SNMPInterface) vInterfaceList.elementAt(iIndex); aifIndex[iIndex] = siTemp.ifIndex; } return aifIndex; } else { return null; }
getifIndex
This method, as shown in Example 7-23, provides a retrieval of the value for the string variable ifIndex for the instance passed. Only two lines are required within this method. The first obtains a temporary copy of the SnmpInterface instance stored in the vector table at the index specified by this methods parameter ifIndex. The second line simply returns the value of the ifIndex property contained within the temporary SnmpInterface class. This method is called by the ITSO_SnmpProbeILT class method getITSOAttribute.
Example 7-23 ITSO_SnmpProbe.java: getifIndex
public static synchronized String getifIndex(int iIndex) { SNMPInterface siTemp = (SNMPInterface) vInterfaceList.elementAt(iIndex); return siTemp.ifIndex; }
253
getifDescr
This method, as shown in Example 7-24, provides a retrieval of the value for the string variable ifDescr for the instance passed. Only two lines are required within this method. The first obtains a temporary copy of the SnmpInterface instance stored in the vector table at the index specified by this methods parameter ifDescr. The second line simply returns the value of the ifIndex property contained within the temporary SnmpInterface class. This method is called by the ITSO_SnmpProbeILT class method getITSOAttribute.
Example 7-24 ITSO_SnmpProbe.java: getifDescr
public static synchronized String getifDescr(int iIndex) { SNMPInterface siTemp = (SNMPInterface) vInterfaceList.elementAt(iIndex); return siTemp.ifDescr; }
getifSpeed
This method, as shown in Example 7-25, provides a retrieval of the value for the string variable ifSpeed for the instance passed. Only two lines are required within this method. The first obtains a temporary copy of the SnmpInterface instance stored in the vector table at the index specified by this methods parameter ifSpeed. The second line simply returns the value of the ifIndex property contained within the temporary SnmpInterface class. This method is called by the ITSO_SnmpProbeILT class method getITSOAttribute.
Example 7-25 ITSO_SnmpProbe.java: getifSpeed
public static synchronized String getifSpeed(int iIndex) { SNMPInterface siTemp = (SNMPInterface) vInterfaceList.elementAt(iIndex); return siTemp.ifSpeed; }
getifInOctets
This method, as shown in Example 7-26 on page 255, provides a retrieval of the value for the string variable ifInOctets for the instance passed. Only two lines are required within this method. The first obtains a temporary copy of the SnmpInterface instance stored in the vector table at the index specified by this methods parameter ifInOctets. The second line simply returns the value of the ifIndex property contained within the temporary SnmpInterface class. This method is called by the ITSO_SnmpProbeILT class method getITSOAttribute.
254
Example 7-26 ITSO_SnmpProbe.java: getifInOctet

public static synchronized String getifInOctets(int iIndex) { SNMPInterface siTemp = (SNMPInterface) vInterfaceList.elementAt(iIndex); return siTemp.ifInOctets; }
getifOutOctets
This method, as shown in Example 7-27, provides a retrieval of the value for the string variable ifOutOctets for the instance passed. Only two lines are required within this method. The first obtains a temporary copy of the SnmpInterface instance stored in the vector table at the index specified by this methods parameter ifOutOctets. The second line simply returns the value of the ifIndex property contained within the temporary SnmpInterface class. This method is called by the ITSO_SnmpProbeILT class method getITSOAttribute.
Example 7-27 ITSO_SnmpProbe.java: getifOutOctets
public static synchronized String getifOutOctets(int iIndex) { SNMPInterface siTemp = (SNMPInterface) vInterfaceList.elementAt(iIndex); return siTemp.ifOutOctets; }
snmpPole
This method is the key integration point of the SNMP package. We will address this method in the logical blocks to clarify the functionality. Though not considered a logical block of code, the function header, variable declaration, and initial trace logging seen in Example 7-28 are important. The snmpPole method is declared as throwing an exception. Internally, we do not throw any exceptions in this method, though it was believed at design time that this routine could do so in future enhancements.
Example 7-28 ITSO_SnmpProbe.java, snmpPole: Header and declarations
//-------------------------------------------------------------------------// snmpGetInterfaces: This method will poll the host via SNMP for the // actual interface data. //-------------------------------------------------------------------------public static synchronized void snmpPole(String sHostname) throws Exception { // Variable Initialization SnmpSession session;
255
// Jen some log info. trace.log( 3, "ITSO_SnmpProbe", "snmpPole: Starting.");
The first logical block in Example 7-29 is based on a Java try-catch implementation, as the SNMP package is designed to throw exceptions. Within the try, the SNMP session is initialized with a specific port number, 12345. Note that this could be implemented as a Resource Model Parameter, to allow administrators to configure which port is used by the model. After initialization of the package, an SNMP session is created by the host specified within the variable sHostname.
Example 7-29 ITSO_SnmpProbe.java: snmpPole: Session initialization
try { // Initialize the API SnmpV1API.initialize(12345); // Open a session to the specified host session = SnmpSession.open( sHostname ); } catch (Exception e) { trace.log( 3, "ITSO_SnmpProbe", "snmpPole: Unable to open session to." + sHostname); return; }
The second logical block, viewed in Example 7-30, performs the initial SNMP query to obtain the number of interface instances that exist on the host to which the session was previously opened. The OID queried is 1.3.6.1.2.1.2.1.0, which maps to the MIB II value ifNumber. This represents the number of interface instances. The queried response is passed to the initVector method to dynamically perform initialization or adjustments to the SnmpInterfaces vector list.
Example 7-30 ITSO_SnmpProbe.java: snmpPole: Initial interface query
// // Get the Instances of Interface(s) // SnmpPDU getPDU = session.makePDU(); getPDU.operation = SnmpPDU.GET; getPDU.addVarBind("1.3.6.1.2.1.2.1.0"); SnmpPDU rsp = session.send(getPDU); initVector(rsp);
// // // // // //
Allocate a PDU. Perform a get. Request "ifNumber". Send and receive the PDU synchronously. Build the Vector list.
256
trace.log( 3, "ITSO_SnmpProbe", "snmpPole: Vector initialized.");
The third logical block configures the getNext instance of the SnmpPDU class for future queries. These queries will obtain the interface data values for each of the instances that exist on the host to which the session was previously opened. The OIDs queried and the associated MIB II values are commented within Example 7-31.
Example 7-31 ITSO_SnmpProbe.java: snmpPole: Interface query
// // Get the Interface(s) // Do a getnext and walk through the udptable // SnmpPDU getNext = session.makePDU(); getNext.operation = SnmpPDU.GETNEXT; OID oid = new OID("1.3.6.1.2.1.2.2.1.1"); getNext.addVarBind(oid); getNext.addVarBind("1.3.6.1.2.1.2.2.1.2"); getNext.addVarBind("1.3.6.1.2.1.2.2.1.5"); getNext.addVarBind("1.3.6.1.2.1.2.2.1.10"); getNext.addVarBind("1.3.6.1.2.1.2.2.1.16"); // ifIndex // // // // ifDescr ifSpeed ifInOctets ifOutOctets
The fourth logical block demonstrated in Example 7-32 is the core logic that queries and analyses the remote hosts interfaces using the previously configured getNext instance of the SnmpPDU class. Each query will obtain the interface data values for one instance that exists on the host to which the session was previously opened. After performing the query, the response is validated for errors and data types, then the response data structure is handed off to the updateInterfaces method for processing against the vector list. Upon completion of the update, the next interface is queried and the process is repeated. This continues until all of the interfaces have been queried. As a note, this routine has been written generically so that it is host independent and is in fact parameterized. This will make enhancement to multi-host processing easier.
Example 7-32 ITSO_SnmpProbe.java: snmpPole: Walking the PDU
// // Step through the Interface(s) // boolean done = false; while ( ! done ) { // Send the getnext and receive the response. rsp = session.send(getNext);
257
// Make sure that no errors occurred. if ( rsp.errorStatus == SnmpPDU.NOERROR ) { // Check the OID of the first varbind. OID rspOID = rsp.varBindAt(0).getOID(); // Is it still in the udptable? if ( rspOID.startsWith(oid) ) { updateInterfaces(rsp); // Now set up for retrieving the next row of the table getNext = rsp; getNext.operation = SnmpPDU.GETNEXT; } else { done = true; } } else { done = true; } } trace.log( 3, "ITSO_SnmpProbe", "snmpPole: Interfaces Updated.");
The final logical block is more a clean-up segment than block. Simply stated, as is visible in Example 7-33, the SNMP session is closed, then the package clean-up is performed through the termination method. Finally, for debug enhancement, some logging is generated.
Example 7-33 ITSO_SnmpProbe.java: snmpPole: Session clean-up
// Perform clean-up by closing session and terminating API. session.close(); SnmpAPI.terminate(); // Jen some log info. trace.log( 3, "ITSO_SnmpProbe", "snmpPole: Exiting."); }
initVector
This method is primarily for vector management. We will address this method in two logical blocks, the first being presented in Example 7-34 on page 259. The initVector method is declared a private method to ensure that the integrity of the vector list is maintained. Beyond the declaration, we validate the PDU. Though a
258
PDU should be validated, and is in the calling method, this is a good practice in any object oriented language. The core logic of this block, visible within the Java for loop, provides a method to walk through each OID structure. Though we know only one OID was specified in Example 7-30 on page 256 to obtain the interface instance count, we have implemented a software development best practice by processing a potentially dynamic number of class instances through the for. The value we are concerned with, ifNumber, is obtained and stored in the variable, ifNumber, local to the method for use by our second logical block.
Example 7-34 ITSO_SnmpProbe.java: initVector: Determine instance count
private static void initVector(SnmpPDU pdu) { int ifNumber = 0; if ( pdu.errorStatus == SnmpPDU.NOERROR ) { // Walk the PDU to find the ifNumber. for ( int i = 0; i < pdu.varBindListSize(); i++ ) { // Extract the variable binding SnmpVarBind vb = pdu.varBindAt(i); OID oid = vb.getOID(); Serializable var = vb.getVar(); // MIB-II, // OID = // Descr trace.log( Interface Group 1.3.6.1.2.1.2.1.0 ifNumber 3, "ITSO_SnmpProbe", "initVector: oid=" + oid + " value = " + var); if( oid.equals( new OID("1.3.6.1.2.1.2.1.0") ) ) { // Determine at what capacity to create the vector. String sTemp = new String(var.toString()); ifNumber = (new Integer(sTemp)).intValue(); trace.log( 3, "ITSO_SnmpProbe", "initVector: ifNumber=" + ifNumber); } }
This logical block, the second of the methods, performs one of two possible functions based on the outcome of the if structure. If the vector has not been initialized, due to the fact that the class is being executed for the first time, then the vector list is set to a new Vector class, initialized to contain the number of elements queried previously and stored in ifNumber. The second possible outcome of the if structure is designed to use a pre-existing vector list. This will occur on every execution except the first. Step
259
one in this procedure begins with removing all elements or SnmpInterface class instances from our vector list. Step two is to perform an ensureElements method against the vector list passing the ifNumber value. This method and value will ensure the dynamically sizable vector list is sized to maintain all of the interface data that will be obtained through the SNMP query process.
Example 7-35 ITSO_SnmpProbe.java: initVector: Vector adjustment
// Check to see if the vector is empty. // This indicates an initial poll. if( vInterfaceList == null ) { // Create the vector with the capacity. vInterfaceList = new Vector(ifNumber); // Log interfaces capacity the vector is configured for. trace.log( 3, "ITSO_SnmpProbe", "initVector: vInterfaceList==null, capacity()=" + vInterfaceList.capacity()); } else { // Ensure the capacity of the vector list. vInterfaceList.removeAllElements(); trace.log( 3, "ITSO_SnmpProbe", "initVector: All elements removed."); // Ensure the capacity of the vector list. vInterfaceList.ensureCapacity(ifNumber); trace.log( 3, "ITSO_SnmpProbe", "initVector: vInterfaceList!=null, capacity()=" + vInterfaceList.capacity()); } } else { // This logs, but should really throw an Exception as no Vector list has been // created due to the bad PDU. trace.log( 3, "ITSO_SnmpProbe", "initVector: Bad pdu=" + pdu); } }
updateInterfaces
The updateInterfaces method shown in Example 7-36 on page 261 is, from a logical perspective, quite simple. Essentially, it is passed the response of the getNext PDU data from the snmpPole method, as seen in Example 7-32 on
260
page 257. This PDU class reference is locally defined as pdu within this method for simplicity.
Example 7-36 ITSO_SnmpProbe.java: updateInterfaces: Declaration and initialization
private static void updateInterfaces(SnmpPDU pdu) { // Determine if the SNMP stack encountered an error. if( pdu.errorStatus == SnmpPDU.NOERROR ) { // Variable Declaration SNMPInterface siBuffer = new SNMPInterface(); String sBufConv;
After validation and local variable initialization, the core logic is presented within the Java for loop. Each of the network interfaces on the remotely queried host is processed by stepping through the PDU list provided to this method. For each of the PDUs processed, each variable within the PDU is processed. Processing of variables is done by binding to the variable, obtaining the associated OID for that variable, then comparing the OID string to the known OID hardcoded within the various methods of the ITSO_SnmpProbe class. The comparisons are handled through the lengthy if-else structure at the lower portion of this method.
Example 7-37 ITSO_SnmpProbe.java: updateInterfaces: Core logic
// Walk through all of the OIDs requested. for ( int i = 0; i < pdu.varBindListSize(); i++ ) { // extract the variable binding SnmpVarBind vb = pdu.varBindAt(i); OID oid = vb.getOID(); Serializable var = vb.getVar(); // Convert the instance from the OID string to an (int). String sOID = oid.toString(); //------------------------------------------// Update the Interface class properties // based on the instance and OID. //------------------------------------------if ( var instanceof OctetString ) { sBufConv = ((OctetString) var).toDisplayString(); } else { sBufConv = var.toString(); }
261
trace.log( 3, "ITSO_SnmpProbe", "updateInterfaces: " + oid + "=" + sBufConv); // ifNumber OID=1.3.6.1.2.1.2.2.1.1.<iIndex> if( sOID.startsWith("1.3.6.1.2.1.2.2.1.1.") ) { siBuffer.ifIndex = sBufConv; } // ifDescr OID=1.3.6.1.2.1.2.2.1.2.<iIndex> else if( sOID.startsWith("1.3.6.1.2.1.2.2.1.2.") ) { siBuffer.ifDescr = sBufConv; } // ifSpeed OID=1.3.6.1.2.1.2.2.1.5.<iIndex> else if( sOID.startsWith("1.3.6.1.2.1.2.2.1.5.") ) { siBuffer.ifSpeed = sBufConv; } // ifInOctets OID=1.3.6.1.2.1.2.2.1.10.<iIndex> else if( sOID.startsWith("1.3.6.1.2.1.2.2.1.10.") ) { siBuffer.ifInOctets = sBufConv; } // ifOutOctets OID=1.3.6.1.2.1.2.2.1.16.<iIndex> else if( sOID.startsWith("1.3.6.1.2.1.2.2.1.16.") ) { siBuffer.ifOutOctets = sBufConv; } } //--------------------------------------------------// Update the vector with the interface information. //--------------------------------------------------vInterfaceList.addElement(siBuffer); } else { // This logs, but should really throw an Exception as no Vector // list has been created due to the bad PDU. trace.log( 3, "ITSO_SnmpProbe", "updateInterfaces: Bad pdu=" + pdu); } }
262

Resource Models are the encapsulation of various ITM Engine configuration files, logic scripting files, and dependency files. In this discussion, each of these items will be discussed as they were implemented within this model.
General settings
These items were configured through the ITM Workbench General Setting dialog box, as shown in Figure 7-3.
Figure 7-3 ITM Workbench: General Settings
When the General Settings configuration was completed, the ITM Workbench engine automatically added the service class method calls to SetModelName, SetProfileName, and SetCycleTime, along with their associated parameters to the JavaScript function SetDefaultConfiguration, as demonstrated in Example 7-38
Example 7-38 ITSO_SnmpProbe.dmjsws: General info
// General info section //<<GENERAL_INFO>> Svc.SetModelName ("ITSO_SnmpProbe"); Svc.SetProfileName ("62971518"); Svc.SetCycleTime (60); //<<\GENERAL_INFO>>
Dynamic Model
The Dynamic Model components of a Resource Model allow for the acquisition of data through various methods. The method of interfacing to an ILT is through the
263
CIMOM. In this example, the CIM Class ITSO_SnmpProbe was selected from the namespace root\default, as shown in Figure 7-4.
Figure 7-4 ITM Workbench: Dynamic Model
An alias was then defined, ITSO_SnmpProbe, for use by the various Service calls within the JavaScript. The use of an alias simplifies the service method parameters. Additionally, the CIM class properties shown in Table 7-1 were selected for use within the JavaScript within the Resource Model.
Table 7-1 CIM class properties
Class property Property type
ifIndex ifDescr ifSpeed ifInOctets ifOutOctets
String String String String String
When the Dynamic Data CIM selection was completed, the ITM Workbench engine automatically added the service class method call to DefineClass and the associated parameters to the JavaScript function SetDefaultConfiguration as
264
Example 7-39 shows. Notice that the all numeric properties are passed as a single parameter, as is the string property.
Example 7-39 ITSO_SnmpProbe.dmjsws: Dynamic info
// Dynamic Model section //<<DATA_INFO>> Svc.DefineClass ("CIM", "ITSO_SnmpProbe", "ROOT\\default:ITSO_SnmpProbe", "", "", "ifDescr,ifIndex,ifSpeed,ifOutOctets,ifInOctets", "None", "", 0, 1); //<<\DATA_INFO>>
Parameters
For this example, as shown in Figure 7-5, a single parameter was used to demonstrate how a parameter list provided to a Tivoli Administrator could be used to alter the operation of the ILT. In this case, the parameter ITSO_ArrayGUI was created as the type String List with the default values added: pacs007 and pacs005.
Note: In this specific case, we populate the parameter list based on host names of machines available to us that were capable of SNMP (pacs007 and pacs005). As a Resource Model developer, you should choose host names of machines or devices that are SNMP capable in your environment. This list is editable by the Tivoli Administrator, so more names may be added without recreating the Resource Model.
Figure 7-5 ITM Workbench: Parameters
When the parameter was added through the Workbench GUI, the ITM Workbench engine automatically added the service class method call
265
DefineStrParameter and the associated parameters to the JavaScript function SetDefaultConfiguration, as shown in Example 7-40.
Example 7-40 ITSO_SnmpProbe.dmjsws: Parameters
// Parameters section //<<PARAMETERS_INFO>> Svc.DefineStrParameter ("ITSO_Hostnames", "pacs007,pacs005"); //<<\PARAMETERS_INFO>>
JavaScript
The script within the Resource Model originated from the ITSO_Sample template model discussed in Chapter 5, Engineering a Java ILT on page 137. The model was modified through the ITM Workbench and was a reasonable shell model modified for our needs. This section will discuss only the changes made to the JavaScript.
In this Resource Model function, shown in Example 7-41, the customization was primarily done through the aforementioned ITM Workbench engine-generated script. The only note-worthy additions beyond those changes were two calls to the service objects Trace methods. This permitted tracing of the Resource Model is within the trace_dmxengine.log file, in an effort to allow end users to better understand the models operation.
Example 7-41 ITSO_SnmpPorbe.dmjsws: SetDefaultConfiguration function
function SetDefaultConfiguration (Svc) { Svc.Trace (0, "ITSO_SnmpProbe: SetDefaultConfiguration - start" ); // General info section //<<GENERAL_INFO>> Svc.SetModelName ("ITSO_SnmpProbe"); Svc.SetProfileName ("62971518"); Svc.SetCycleTime (60); //<<\GENERAL_INFO>> // Thresholds section //<<THRESHOLDS_INFO>> //<<\THRESHOLDS_INFO>> // Parameters section //<<PARAMETERS_INFO>> Svc.DefineStrParameter ("ITSO_Hostnames", "pacs007,pacs005"); //<<\PARAMETERS_INFO>>
266
// Note:In the DefineClass method, we create an ALIAS of "ITSO_SnmpProbe" to the actual CIM Namespace declaration for our class. //This will be referenced by the AssociateParameterToClass method later. // // Dynamic Model section //<<DATA_INFO>> Svc.DefineClass ("CIM", "ITSO_SnmpProbe", "ROOT\\default:ITSO_SnmpProbe", "", "", "ifDescr,ifIndex,ifSpeed,ifOutOctets,ifInOctets", "None", "", 0, 1); //<<\DATA_INFO>> // Event definition section //<<EVENTS_INFO>> //<<\EVENTS_INFO>> // Logging definition section //<<LOGGING_INFO>> //<<\LOGGING_INFO>> // Place your additional intializing code below Svc.Trace (0, "ITSO_SnmpProbe: SetDefaultConfiguration - end" ); return (0); }
Init
The Init function, shown in Example 7-42 on page 268, provides the initialization requirements for the Resource Model. In the case of ITSO_SnmpProbe, very little initialization was required. Above the trace file logging we provided, we performed our variable initialization for the function, followed by our requirements. In the requirements, we did have to address the passing of configuration parameters to the ILT. In the case of the Resource Model parameter ITSO_Hostnames, which is passed from the ITM Engine during the initial Resource Model configuration to the ILT, we had to verify that it does contain at least one string value. Without any string values, our ILT would not be able to initialize. Therefore, within the initialization function, we obtain the dimension of, or number of values within, the array ITSO_Hostnames. The obtained dimension is validated to ensure it is greater than zero. If the dimension is acceptable, our next core function is the call to the AssociateParameterToClass method, which will register the Resource Model parameter within the ITM Engine and allow our instantiated ILT class to look up and obtain the parameter and its contents. If the dimension is not acceptable, that is, it is equal to zero, we return with the error code value 801.
267
Example 7-42 ITSO_SnmpProbe.dmjsws: Init function

function Init(Svc) { // Logging Svc.Trace (0, "ITSO_SnmpProbe: Init - start" ); // Variable Initialization var dimHostnames = 0; var dimOIDs = 0; var t=0; // Process the parameter lists. dimHostnames = Svc.GetStrParameterCount("ITSO_Hostnames"); if (dimHostnames > 0 ) { Svc.Trace (0, "ITSO_Hostnames: Init - dimHostnames =" + dimHostnames ); // Note: This is the reference to the alias "ITSO_SnmpProbe" created in the DefineClass method. Svc.AssociateParameterToClass ("ITSO_Hostnames","ITSO_SnmpProbe"); } else { Svc.Trace (0, "ITSO_SnmpProbe: ITSO_Hostnames parameter is empty"); return(801); } Svc.Trace (0, "ITSO_SnmpProbe: Init - end" ); return (0); }
VisitTree
The VisitTree function, shown in Example 7-43, was customized to perform the actual monitoring algorithm. In the case of the ITSO_SnmpProbe, the algorithm consists of simply polling each of the CIM class properties. The purpose of such simple logic is to demonstrate the retrieval of the data from the ILT class and to provide tracing to the ITM Engine log file. The tracing provides a method for tracing the functionality of the entire model and ILT during regular operation.
Example 7-43 ITSO_SnmpProbe.dmjsws: VisitTree function
function VisitTree(Svc) { // Variable Declaration var iHostnameCount; var iInstanceCount; var iIndex;
268
var sTraceOut; var var var var var curifIndex; curifDescr; curifSpeed; curifInOctets; curifOutOctets;
// Determine how many hostnames were configured by the Administrator. iHostnameCount = Svc.GetStrParameterCount("ITSO_Hostnames"); Svc.Trace(0,"ITSO_SnmpProbe: VisitTree: iHostnameCount = " + iHostnameCount ); // Determine how many Instances of the ITSO_SnmpProbe class exist. // There will be 1 instance for each interface on each host. iInstanceCount = Svc.GetNumOfInst("ITSO_SnmpProbe"); Svc.Trace(0,"ITSO_SnmpProbe: VisitTree: iInstanceCount = "+ iInstanceCount ); // Process all of the instances for ( iIndex= 0; iIndex < iInstanceCount; iIndex++) { // ifDescr OID = 1.3.6.1.2.1.2.2.1.2 curifDescr = Svc.GetStrProperty("ITSO_SnmpProbe", iIndex, "ifDescr"); Svc.Trace( 0, "GetStrProperty: ifDescr = " + curifDescr ); // ifSpeed OID = 1.3.6.1.2.1.2.2.1.5 curifSpeed = Svc.GetStrProperty("ITSO_SnmpProbe", iIndex, "ifSpeed"); Svc.Trace( 0, "GetStrProperty: ifSpeed = " + curifSpeed ); // ifInOctets OID = 1.3.6.1.2.1.2.2.1.10 curifInOctets = Svc.GetStrProperty("ITSO_SnmpProbe", iIndex, "ifInOctets"); Svc.Trace( 0, "GetStrProperty: ifInOctets = " + curifInOctets ); // ifOutOctets OID = 1.3.6.1.2.1.2.2.1.16 curifOutOctets = Svc.GetStrProperty("ITSO_SnmpProbe", iIndex, "ifOutOctets"); Svc.Trace( 0, "GetStrProperty: ifOutOctets = " + curifOutOctets ); } return (0); }
269
7.4 Packaging
The various components discussed within this chapter must be packaged into a Resource Model tar file. The Resource Model Tar File relationship diagram, shown in Figure 7-6 shows all the components of a typical Resource Model, with those not used within the ITSO_SnmpProbe presented in light gray to de-emphasize their significance.

Configuration File Logging: Parameter(s): ITSO_Hostnames Action(s): Threshold(s): Event(s): Message Catalogs Provider(s): "ITSO_SnmpProbe.jar" MOF(s): "ITSO_SnmpProbe.mof" Custom Files(s) "Snmp.jar" Dependencies Files Reference Model Functions: SetDefaultConfiguration(Svc) Init(Svc) VisitTree(Svc) Dynamic Model(s): CIM Class "ITSO_SnmpProbe" JavaScript
Custom Scripts()
Figure 7-6 ITSO_SnmpProbe.tar: Resource Model Tar File
7.4.1 Testing and importing the MOF

The ITSO_SnmpProbe.mof file is compiled with the mofcomp utility, as shown in Example 7-44.
Example 7-44 mofcomp CLI
mofcomp -N:root\default ITSO_SnmpProbe.mof
270
Figure 7-7 mofcomp output
7.4.2 Java compilation

The SnmpInterface.java file is compiled with the use of the javac tool that is included with the JDK, as shown in Example 7-45.
Example 7-45 SnmpInterface.java: javac CLI
javac -classpath c:\ITSO_SnmpProbe SNMPInterface.java -d c:\ITSO_SnmpProbe
The actual output from this java compiler process is shown in Figure 7-8 on page 272.
271
Figure 7-8 SnmpInterface.java: javac output
The ITSO_SnmpProbe.java file is compiled with the use of the javac tool that is included with the JDK, as shown in Example 7-46.
Example 7-46 ITSO_SnmpProbe.java: javac CLI
javac -classpath c:\ITSO_SnmpProbe;dm_m12.jar;javautils.jar;snmp.jar ITSO_SnmpProbe.java -d c:\ITSO_SnmpProbe
The actual output from this java compiler process is shown in Figure 7-9.
Figure 7-9 ITSO_SnmpProbe.java: javac output
272
The ITSO_SnmpProbeILT.java file is compiled with the use of the javac tool that is included with the JDK, as shown in Example 7-47.
Example 7-47 ITSO_SnmpProbeILT.java: javac CLI
javac -classpath c:\ITSO_SnmpProbe;dm_m12.jar;javautils.jar;snmp.jar ITSO_SnmpProbeIlt.java -d c:\ITSO_SnmpProbe
The actual output from this java compiler process is shown in Figure 7-10.
Figure 7-10 ITSO_SnmpProbeILT.java: javac output
7.4.3 Making the jar file

The ITSO_SnmpProbe.jar Java package file is built with the use of the jar tool that is included with the JDK, as shown in Example 7-48.
Example 7-48 jar CLI
jar -cvf ITSO_SnmpProbe.jar com/
273
Figure 7-11 jar output
7.4.4 Assembling the Resource Model

Upon completing the testing of ITSO_SnmpProbe.mof and the building of ITSO_SnmpProbe.jar, the two files must be added to the ITSO_SnmpProbe.dmjsws Resource Model file. This is done through the ITM Workbench, as shown in Figure 7-12 on page 275.
274
Figure 7-12 ITM Workbench: Tree view pane
7.4.5 Building the Resource Model

The Resource Model then needs to be built by selecting the ITM Workbench menu Build Build Package, as shown in Figure 7-13 on page 276. This will open the Save As dialog box, as shown in Figure 7-14 on page 277.
275
Figure 7-13 ITM Workbench: Build menu
276
Figure 7-14 ITM Workbench: Save As dialog
7.5 ITSO_SnmpProbe source code

The following files were created to demonstrate the integration of the IBM SNMP Java package within a custom ILT type Provider. This Resource Model was based on the ITSO_Sample template provided in Chapter 5, Engineering a Java ILT on page 137.
7.5.1 ITSO_SnmpProbe.mof
The complete MOF file used for the ITSO_SnmpProbe Resource Model is shown in Example 7-49.
Example 7-49 ITSO_SnmpProbe.mof
//-----------------------------------------------------------------------------// // ITSO_SnmpProbe.mof // // Description: // This file is a textual definition of the ITSO_SnmpProbe CIM class. // //-----------------------------------------------------------------------------[ Description ("ITSO SNMP Probe - This class was created to demonstrate the "
277
"integration of the IBM SNMP Java API with an ITM provider."), provider("com.tivoli.dmunix.ep.touchpoint.cimom.ifc.M12JavaProvider"), M12_Instrumentation { "Java.com.ibm.tivoli.monitoring.ITSO_SnmpProbe.ITSO_SnmpProbeIlt | | ENUM", "Java.com.ibm.tivoli.monitoring.ITSO_SnmpProbe.ITSO_SnmpProbeIlt | | GET"} ] class ITSO_SnmpProbe { // Attribute, Instance Count. [ Description("This property defines the index of the interface " "being poled. The associated OID is 1.3.6.1.2.1.2.2.1.1" ), key ] string ifIndex; // Attribute, String. [ Description("This property defines the Description of the interface " "being poled. The associated OID is 1.3.6.1.2.1.2.2.1.2" ) ] string ifDescr; // Attribute, String. [ Description("This property defines the Speed of the interface " "being poled. The associated OID is 1.3.6.1.2.1.2.2.1.5" ) ] string ifSpeed; // Attribute, String. [ Description("This property defines the Input Octets of the interface " "being poled. The associated OID is 1.3.6.1.2.1.2.2.1.10" ) ] string ifInOctets; // Attribute, String. [ Description("This property defines the Output Octets of the interface " "being poled. The associated OID is 1.3.6.1.2.1.2.2.1.16" ) ] string ifOutOctets; };
7.5.2 ITSO_SnmpProbeILT.Java
The complete ILT class for the ITSO_SnmpProbe Resource Model is shown in Example 7-50.
Example 7-50 ITSO_SnmpProbeILT.Java
//-----------------------------------------------------------------------------// // ITSO_SnmpProbeILT.java // // Description: // This file is the ITSO_SnmpProbe Instrumentation Library Type (ILT)
278
// implementation. This is the class instantiated by the "touchpoint" // layer. This class will execute methods in the "ITSO_SnmpProbe.java" // file, which is the physical "provider" and performs the actual data // acquisition. // //-----------------------------------------------------------------------------package com.ibm.tivoli.monitoring.ITSO_SnmpProbe; // PAC Development // naming convention. import com.ibm.tivoli.monitoring.ITSO_SnmpProbe.*; // "ITSO_SnmpProbe.class" import com.tivoli.dmunix.ep.touchpoint.base.*; // "dm_m12.jar" import com.tivoli.javautils.Trace; // "javautils.jar" import java.util.Enumeration; // Java Class import java.util.Vector; // Java Class public class ITSO_SnmpProbeIlt implements ILTInterface { //-------------------------------------------------------------------------// Instantiate the required class. //-------------------------------------------------------------------------private ITSO_SnmpProbe pSnmpProbe; private Trace trace;
//-------------------------------------------------------------------------// ITSO_SnmpProbeIlt class - Creator method. //-------------------------------------------------------------------------public ITSO_SnmpProbeIlt() { pSnmpProbe = new ITSO_SnmpProbe(); trace = Trace.getTraceInstance(); } //-------------------------------------------------------------------------// Instrumentation Library Type (ILT) // - Public Operations //-------------------------------------------------------------------------//-------------------------------------------------------------------------// // getProperty // // Supported: YES // // Syntax: // public java.lang.String getProperty( M12ObjectIdentity targetInstance, // java.lang.String propertyName, // java.lang.String mappingString, // ParameterSet parms ) // throws M12Exception
279
// // Parameters: // targetInstance - M12ObjectIdentity that identifies the instance of the // resource to be accessed. // propertyName The property whose value is required. // mappingString - Any string that has been specified in the // M12_Instrumentation qualifier for the GET operation // type for this property. // parms A ParameterSet object filled by the client with // parameters associated to this property. // // Description: // Gets the value (in String format) of the specified property for the // identified object. // // Returns: // String - The value for property propertyName. Property values have to // be CIM standard types and ILT converts them to string format // according to the CIM standards. // // Exceptions Thrown: // M12Exception //-------------------------------------------------------------------------public String getProperty( M12ObjectIdentity m12objectidentity, String sProperty, String sMapping, ParameterSet parameterset ) throws M12Exception { int iIndex; try { M12IdentityElement m12identityelement = m12objectidentity.getScopingPath()[0]; M12PropertySet m12propertyset = m12identityelement.getIdentity(); // Determine which instance is being checked by the // Management Layer. String sKey = m12propertyset.getProperty("ifIndex"); trace.log( 3, "ITSO_SnmpProbeIlt", "getProperty: called for iInstance " + sKey); // Update the instance. iIndex = (new Integer(sKey)).intValue(); // Get the current property values. String sValue = getAttribute(iIndex, sProperty); trace.log( 3, "ITSO_SnmpProbeIlt",
280
"getAttribute: " + sProperty + " = " + iIndex); return sValue; } catch(Exception exception) { trace.exception("ITSO_SnmpProbeIlt", "getProperty", exception); M12Exception m12exception = new M12Exception(exception); throw m12exception; } } //-------------------------------------------------------------------------// // getMultipleProperties // // Supported: YES // // Syntax: // public M12PropertySet getMultipleProperties( // M12ObjectIdentity targetInstance, // java.util.Vector propertyList, // java.lang.String mappingString, // ParameterSet parms ) // throws M12Exception // // Parameters: // targetInstance - M12ObjectIdentity that identifies the instance of the // resource to be accessed. // propertyList The list of properties whose value is required. // mappingString - Any string that has been specified in the // M12_Instrumentation qualifier for the GET operation // type for the class which the specified instance // belongs to. // parms A ParameterSet object filled by the client with // parameters associated to the class which the // specified instance belongs to. // // Description: // Gets the value (in String format) of the specified properties for the // identified object. // // Returns: // M12PropertySet - the values of the requested properties. // // Exceptions Thrown: // M12Exception // //-------------------------------------------------------------------------public M12PropertySet getMultipleProperties(
281
M12ObjectIdentity m12objectidentity, Vector vPropertyList, String sMapping, ParameterSet parameterset ) throws M12Exception { int iIndex; try { M12IdentityElement m12identityelement = m12objectidentity.getScopingPath()[0]; M12PropertySet m12propertyset = m12identityelement.getIdentity(); // Determine which instance is being checked by the // Management Layer. String sKey = m12propertyset.getProperty("ifIndex"); M12PropertySet m12propertyset1 = new M12PropertySet(); trace.log( 3, "ITSO_SnmpProbeIlt", "getMultipleProperty: called for ifIndex " + sKey); // Update the instance. // This is performed once as the entire SNMP polling // is performed to fill the data structure simultaneously // to ensure data validition and SNMP efficiency. // As in the Provider, the index is physically 0 to n, // where n equals iIndex-1. iIndex = (new Integer(sKey)).intValue(); iIndex--; // Update the individual requested properties. for(int i = 0; i < vPropertyList.size(); i++) { // Get the property being checked by the Management Layer. String sProperty = (String)vPropertyList.elementAt(i); // Get the current property values. String sValue = getAttribute(iIndex, sProperty); m12propertyset1.setProperty(sProperty, sValue); } trace.log( 3, "ITSO_SnmpProbeIlt", "getMultipleProperty: returning " + WriteBuffer(m12propertyset1)); return m12propertyset1; } catch(Exception exception) {
282
trace.exception("ITSO_SnmpProbeIlt", "getMultipleProperty", exception); M12Exception m12exception = new M12Exception(exception); throw m12exception; } } //-------------------------------------------------------------------------// // enumerateInstances // // Supported: YES // // Syntax: // public java.util.Enumeration enumerateInstances( // M12ClassPath classPath, // java.lang.String mappingString, // ParameterSet parms ) // throws M12Exception // // Parameters: // classPath The M12ClassPath identifying the class whose instances // have to be enumerated. // mappingString - Any string that has been specified in the // M12_Instrumentation qualifier for the ENUM operation // type for this class. // parms A ParameterSet object filled by the client with // parameters for ILT. // // Description // Returns all M12ObjectIdentity objects that identify all the instances // belonging to the class specified in the classPath. // // Returns: // Enumeration of instances identity (M12ObjectIdentity). // // Exceptions Thrown: // M12Exception // //-------------------------------------------------------------------------public Enumeration enumerateInstances( M12ClassPath m12classpath, String sMapping, ParameterSet parameterset ) throws M12Exception { try { // Variable Declaration. StringBuffer stringbuffer = new StringBuffer();
283
Vector vector = new Vector(); //-----------------------------------------------------------------// Get the parameters from the caller. // We are obtaining the parameters prior to declaring instances so // we can configure an instance for specific parameters as needed. //-----------------------------------------------------------------Enumeration enumeration = parameterset.parametersNames(); Vector vHostnames = (Vector)parameterset.getParam("ITSO_Hostnames"); if(vHostnames == null) { trace.log( 3, "ITSO_SnmpProbeIlt", "enumerateInstances: no ITSO_Hostnames parameters found"); return null; } //-----------------------------------------------------------------// NOTE: // This routine has been hardcoded to only perform the pole // on a single hostname, the first. // This application has numerous "hooks'n'latches" to support // multiple hostnames, though we're stopping work here. // Demonstrating the integration with the IBM SNMP Java package // was the goal, NOT trying to replace NetView! //-----------------------------------------------------------------// Process the ITSO_Hostnames parameter. String asHostnames[] = new String[vHostnames.size()]; asHostnames[] = new String[1]; for(int iIndex = 0; iIndex < vHostnames.size(); iIndex++) { // HARDCODED for only the first hostname! int iIndex = 0; // Get the string array element from the vector element. asHostnames[iIndex] = (String)vHostnames.elementAt(iIndex); trace.log( 3, "ITSO_SnmpProbeIlt", "enumerateInstances: asHostnames[" + iIndex + "]=" + asHostnames[iIndex]); } //-----------------------------------------------------------------// Acquire a vector (pointer) from the calling ILT Manager. // This section handles the registration of instances of this // Instrumentation. //-----------------------------------------------------------------String asInst[] = pSnmpProbe.getInstances( asHostnames ); if(asInst == null) { trace.log( 3, "ITSO_SnmpProbeIlt",
// // //
//
284
"enumerateInstances: no instances found"); return null; } for(int jIndex = 0; jIndex < asInst.length; jIndex++) { trace.log( 3, "ITSO_SnmpProbeIlt", "enumerateInstances: aiInst[" + jIndex + "] = " + asInst[jIndex]); M12PropertySet m12propertyset = new M12PropertySet(); m12propertyset.setProperty( "ifIndex", String.valueOf(asInst[jIndex]) ); M12IdentityElement m12identityelement = new M12IdentityElement( m12classpath.getClassName(), m12classpath.getNameSpace(), m12propertyset); vector.add( new M12ObjectIdentity( new M12IdentityElement[] { m12identityelement } ) ); } return vector.elements(); } catch(Exception exception) { trace.exception("ITSO_SnmpProbeIlt", "enumerateInstances", exception); M12Exception m12exception = new M12Exception(exception); throw m12exception; } } //-------------------------------------------------------------------------// // setProperty // // Supported: NO // // Syntax: // public java.lang.String setProperty( M12ObjectIdentity targetInstance, // java.lang.String propertyName, // java.lang.String propertyValue, // java.lang.String mappingString, // ParameterSet parms ) // throws M12Exception // // Parameters: // targetInstance - M12ObjectIdentity that identifies the instance of the // resource to be accessed. // propertyName The property whose value is to be set.
285
// propertyValue - The property value to be set. // mappingString - Any string that has been specified in the // M12_Instrumentation qualifier for the SET operation // type for this property. // parms A ParameterSet object filled by the client with // parameters associated to this property. // // Description: // Sets the value (in String format) of the specified property for the // identified object. // // Returns: // String - the new value of the specified property. // // Exceptions Thrown: // M12Exception // //-------------------------------------------------------------------------public String setProperty( M12ObjectIdentity m12objectidentity, String sName, String sValue, String sMapping, ParameterSet parameterset ) throws M12Exception { return null; } //-------------------------------------------------------------------------// // invokeMethod // // Supported: YES // // Syntax: // public java.lang.String invokeMethod( M12ClassPath classPath, // java.lang.String methodName, // java.lang.String mappingString, // ParameterSet parms, // ParameterSet inParms, // ParameterSet outParms ) // throws M12Exception // // Parameters: // classPath The M12ClassPath that identifies the class // whose method has to be called. // methodName The name of the method to be called. // mappingString - Any string that has been specified in the // M12_Instrumentation qualifier for the INVOKE
286
// operation type for this method. // parms A ParameterSet object filled by the client with // parameters for this method. // inParms A ParameterSet object filled by the client with // parameters to be passed to the method. // outParms A ParameterSet object created by the client and // filled by the method with output results. // // Description: // Invokes the specified method on the CIM instance belonging to // the class specified in the classPath. // // Returns: // String - The result of the method. Result values have to be CIM // standard types and ILT converts them to string format // according to the CIM standards. // // Exceptions Thrown: // M12Exception // //-------------------------------------------------------------------------public String invokeMethod( M12ClassPath m12classpath, String sMethodName, String sMapping, ParameterSet parameterset, ParameterSet parameterset1, ParameterSet parameterset2 ) throws M12Exception { return null; } //-------------------------------------------------------------------------// // invokeMethod // // Supported: YES // // Syntax: // public java.lang.String invokeMethod( M12ObjectIdentity targetInstance, // java.lang.String methodName, // java.lang.String mappingString, // ParameterSet parms, // ParameterSet inParms, // ParameterSet outParms) // throws M12Exception // // Parameters: // targetInstance - M12ObjectIdentity that identifies the instance
287
// whose method has to be called. // methodName The name of the method to be called. // mappingString - Any string that has been specified in the // M12_Instrumentation qualifier for the INVOKE // operation type for this method. // parms A ParameterSet object filled by the client with // parameters for this method. // inParms A ParameterSet object filled by the client with // parameters to be passed to the method. // outParms A ParameterSet object created by the client and // filled by the method with output results. // // Description: // Invokes the specified method on the identified CIM instance. // // Returns: // String - The result of the method. Result values have to be CIM // standard types and ILT converts them to string format // according to the CIM standards. // // Exceptions Thrown: // M12Exception // //-------------------------------------------------------------------------public String invokeMethod( M12ObjectIdentity m12objectidentity, String sMethodName, String sMapping, ParameterSet parameterset, ParameterSet parameterset1, ParameterSet parameterset2 ) throws M12Exception { return null; } //-------------------------------------------------------------------------// // create // // Supported: NO // // Syntax: // public void create( M12ObjectIdentity targetInstance, // java.lang.String mappingString, // ParameterSet parms ) // throws M12Exception // // Parameters: // targetInstance - M12ObjectIdentity that identifies the instance
288
// of the resource to be created. // mappingString - Any string that has been specified in the // M12_Instrumentation qualifier for the CREATE // operation type for the class whose instance to // be created will belong to. // parms - A ParameterSet object filled by the client // with parameters for the ILT. // // Description // Creates an instance of the resource that will be identified by // the specified targetInstance. // // Returns: // void // // Exceptions Thrown: // M12Exception // //-------------------------------------------------------------------------public void create( M12ObjectIdentity m12objectidentity, String sMapping, ParameterSet parameterset ) throws M12Exception { return; }
//-------------------------------------------------------------------------// // destroy // // Supported: NO // // Syntax: // public void destroy( M12ObjectIdentity targetInstance, // java.lang.String mappingString, // ParameterSet parms ) // throws M12Exception // // Parameters : // TargetInstance - M12ObjectIdentity that identifies the instance // of the resource to be deleted. // mappingString -Any string that has been specified in the // M12_Instrumentation qualifier for the CREATE // operation type for the class whose instance to // be deleted belongs to. // parms A ParameterSet object filled by the client // with parameters for the ILT.
289
// // Description: // Deletes an instance of the resource identified by the specified // targetInstance. // // Returns: // void // // Exceptions Thrown: // M12Exception // //-------------------------------------------------------------------------public void destroy( M12ObjectIdentity m12objectidentity, String sMapping, ParameterSet parameterset ) throws M12Exception { return; } //-------------------------------------------------------------------------// // Custom Class Methods // // The following methods are custom methods created to provide better // programatic structure. // //-------------------------------------------------------------------------//-------------------------------------------------------------------------// // getAttribute // // This method is internal to the class and is designed to segregate the // ILT Operations from our own supporting methods. It is simply to provide // cleaner & easier to maintain code. // //-------------------------------------------------------------------------private String getAttribute( int iIndex, String sProperty ) throws Exception { //---------------------------------------------------------------------// Process each CIM class property. //---------------------------------------------------------------------if(sProperty.equals("ifIndex")) { String sReturn = new String( pSnmpProbe.getifIndex(iIndex) ); return sReturn;
290
} else if(sProperty.equals("ifDescr")) { String sReturn = new String( pSnmpProbe.getifDescr(iIndex) ); return sReturn; } else if(sProperty.equals("ifSpeed")) { String sReturn = new String( pSnmpProbe.getifSpeed(iIndex) ); return sReturn; } else if(sProperty.equals("ifInOctets")) { String sReturn = new String( pSnmpProbe.getifInOctets(iIndex) ); return sReturn; } else if(sProperty.equals("ifOutOctets")) { String sReturn = new String( pSnmpProbe.getifOutOctets(iIndex) ); return sReturn; } //---------------------------------------------------------------------// Unknown property. //---------------------------------------------------------------------else { throw new Exception(sProperty + ": unknown property"); } }
//-------------------------------------------------------------------------// // WriteBuffer // // This method is internal to the class and is designed to write the // variable returned from the ILT Operations to the output string. It is // strictly to support better logging. // //-------------------------------------------------------------------------private String WriteBuffer( M12PropertySet m12propertyset ) { Enumeration enumeration = m12propertyset.propertyNames(); StringBuffer stringbuffer = new StringBuffer(); String sElement; String sProperty; for(; enumeration.hasMoreElements(); stringbuffer.append(sElement + " = " + sProperty + " ")) {
291
sElement = (String)enumeration.nextElement(); sProperty = m12propertyset.getProperty(sElement); } return stringbuffer.toString(); } }
7.5.3 ITSO_SnmpProbe.Java
The complete Provider class for the ITSO_SnmpProbe Resource Model is shown in Example 7-51.
Example 7-51 ITSO_SnmpProbe.Java
//-----------------------------------------------------------------------------// // ITSO_SnmpProbe.java // // Description: // This file is the ITSO_SnmpProbe Provider to the ILT. // This class is the actual instrumentation layer in that it interfaces to // and manages said interfacing of the SNMP stack directly. // //-----------------------------------------------------------------------------package com.ibm.tivoli.monitoring.ITSO_SnmpProbe; // PAC Development // naming convention. import import import import import import import com.tivoli.javautils.Trace; com.tivoli.snmp.data.*; com.tivoli.snmp.utils.*; com.tivoli.snmp.*; java.util.*; java.util.Vector; java.io.Serializable; // // // // // // // For debugging. SNMP Requirement SNMP Requirement SNMP Requirement Dynamic object array handler. SNMP Requirement
public class ITSO_SnmpProbe { // Declare local members. private static Trace trace; static Vector vInterfaceList; //-------------------------------------------------------------------------// ITSO_SnmpProbe class - Creator method. //-------------------------------------------------------------------------public ITSO_SnmpProbe() {
292
trace = Trace.getTraceInstance(); }
//-------------------------------------------------------------------------// ITSO_SnmpProbe - This method should configure an instance for each item // in the array. //-------------------------------------------------------------------------public synchronized String[] getInstances( String asHostnames[] ) { int iTemp; // The instances will be referenced by number to keep it simple. for(int iIndex = 0; iIndex < asHostnames.length; iIndex++) for(int iIndex = 0; iIndex < 1; iIndex++) { // Get the string array element from the vector element. trace.log( 3, "ITSO_SnmpProbe", "getInstances iIndex=" + iIndex); // Poll the SNMP information to determine how to index the array. try { // Perform the initial pole: // Configure the vector snmpPole(asHostnames[iIndex]); trace.log( 3, "ITSO_SnmpProbe", "getInstances: vInterfaceList.size()=" + vInterfaceList.size()); } catch (Exception eSnmpPole) { trace.exception("ITSO_SnmpProbeIlt", "getInstances", eSnmpPole); } } // Build the string list of ifIndex(es) from the vector. iTemp = vInterfaceList.size(); trace.log( 3, "ITSO_SnmpProbe", "getInstances iTemp=" + iTemp); String aifIndex[] = new String[iTemp]; if( vInterfaceList.size() > 0 ) { for(int iIndex = 0; iIndex < vInterfaceList.size(); iIndex++) { // SNMPInterface siTemp = (SNMPInterface) vInterfaceList.elementAt(iIndex); aifIndex[iIndex] = siTemp.ifIndex; }
//
293
return aifIndex; } else { return null; } } // Return the individual values from the Interface vector. public static synchronized String getifIndex(int iIndex) { SNMPInterface siTemp = (SNMPInterface) vInterfaceList.elementAt(iIndex); return siTemp.ifIndex; } public static synchronized String getifDescr(int iIndex) { SNMPInterface siTemp = (SNMPInterface) vInterfaceList.elementAt(iIndex); return siTemp.ifDescr; } public static synchronized String getifSpeed(int iIndex) { SNMPInterface siTemp = (SNMPInterface) vInterfaceList.elementAt(iIndex); return siTemp.ifSpeed; } public static synchronized String getifInOctets(int iIndex) { SNMPInterface siTemp = (SNMPInterface) vInterfaceList.elementAt(iIndex); return siTemp.ifInOctets; } public static synchronized String getifOutOctets(int iIndex) { SNMPInterface siTemp = (SNMPInterface) vInterfaceList.elementAt(iIndex); return siTemp.ifOutOctets; }
//-------------------------------------------------------------------------// snmpGetInterfaces - This method will poll the host via SNMP for the // actual interface data. //-------------------------------------------------------------------------public static synchronized void snmpPole(String sHostname) throws Exception { // Variable Initialization
294
SnmpSession session; // Jen some log info. trace.log( 3, "ITSO_SnmpProbe", "snmpPole: Starting."); // try { // Initialize the API SnmpV1API.initialize(12345); // Open a session to the specified host session = SnmpSession.open( sHostname ); } catch (Exception e) { trace.log( 3, "ITSO_SnmpProbe", "snmpPole: Unable to open session to." + sHostname); return; } // // Get the Instances of Interface(s) // SnmpPDU getPDU = session.makePDU(); getPDU.operation = SnmpPDU.GET; getPDU.addVarBind("1.3.6.1.2.1.2.1.0"); SnmpPDU rsp = session.send(getPDU);
// Allocate a PDU. // Perform a get. // Request "ifNumber". // Send and receive the PDU // synchronously. initVector(rsp); // Build the Vector list. trace.log( 3, "ITSO_SnmpProbe", "snmpPole: Vector initialized."); // // Get the Interface(s) // Do a getnext and walk through the udptable // SnmpPDU getNext = session.makePDU(); getNext.operation = SnmpPDU.GETNEXT; OID oid = new OID("1.3.6.1.2.1.2.2.1.1"); getNext.addVarBind(oid); getNext.addVarBind("1.3.6.1.2.1.2.2.1.2"); getNext.addVarBind("1.3.6.1.2.1.2.2.1.5"); getNext.addVarBind("1.3.6.1.2.1.2.2.1.10"); getNext.addVarBind("1.3.6.1.2.1.2.2.1.16"); // // Step through the Interface(s) // // ifIndex // // // // ifDescr ifSpeed ifInOctets ifOutOctets
295
boolean done = false; while ( ! done ) { // Send the getnext and receive the response. rsp = session.send(getNext); // Make sure that no errors occurred. if ( rsp.errorStatus == SnmpPDU.NOERROR ) { // Check the OID of the first varbind. OID rspOID = rsp.varBindAt(0).getOID(); // Is it still in the udptable? if ( rspOID.startsWith(oid) ) { updateInterfaces(rsp); // Now set up for retrieving the next row of the table getNext = rsp; getNext.operation = SnmpPDU.GETNEXT; } else { done = true; } } else { done = true; } } trace.log( 3, "ITSO_SnmpProbe", "snmpPole: Interfaces Updated."); // Perform clean-up by closing session and terminating API. session.close(); SnmpAPI.terminate(); // Jen some log info. trace.log( 3, "ITSO_SnmpProbe", "snmpPole: Exiting."); }
// // initVector // private static void initVector(SnmpPDU pdu) { int ifNumber = 0;
296
if ( pdu.errorStatus == SnmpPDU.NOERROR ) { // Walk the PDU to find the ifNumber. for ( int i = 0; i < pdu.varBindListSize(); i++ ) { // Extract the variable binding SnmpVarBind vb = pdu.varBindAt(i); OID oid = vb.getOID(); Serializable var = vb.getVar(); // MIB-II, // OID = // Descr trace.log( Interface Group 1.3.6.1.2.1.2.1.0 ifNumber 3, "ITSO_SnmpProbe", "initVector: oid=" + oid + " value = " + var); if( oid.equals( new OID("1.3.6.1.2.1.2.1.0") ) ) { // Determine at what capacity to create the vector. String sTemp = new String(var.toString()); ifNumber = (new Integer(sTemp)).intValue(); trace.log( 3, "ITSO_SnmpProbe", "initVector: ifNumber=" + ifNumber); }
} // Check to see if the vector is empty. // This indicates an initial poll. if( vInterfaceList == null ) { // Create the vector with the capacity. vInterfaceList = new Vector(ifNumber); // Log interfaces capacity the vector is configured for. trace.log( 3, "ITSO_SnmpProbe", "initVector: vInterfaceList==null, capacity()=" + vInterfaceList.capacity()); } else { // Ensure the capacity of the vector list. vInterfaceList.removeAllElements(); trace.log( 3, "ITSO_SnmpProbe", "initVector: All elements removed."); // Ensure the capacity of the vector list. vInterfaceList.ensureCapacity(ifNumber); trace.log( 3, "ITSO_SnmpProbe", "initVector: vInterfaceList!=null, capacity()=" + vInterfaceList.capacity());
297
} } else { // This logs, but should really throw an Exception as no Vector list has been // created due to the bad PDU. trace.log( 3, "ITSO_SnmpProbe", "initVector: Bad pdu=" + pdu); } }
// // updateInterfaces // private static void updateInterfaces(SnmpPDU pdu) { // Determine if the SNMP stack encountered an error. if ( pdu.errorStatus == SnmpPDU.NOERROR ) { // Variable Declaration SNMPInterface siBuffer = new SNMPInterface(); String sBufConv; // Walk through all of the OIDs requested. for ( int i = 0; i < pdu.varBindListSize(); i++ ) { // extract the variable binding SnmpVarBind vb = pdu.varBindAt(i); OID oid = vb.getOID(); Serializable var = vb.getVar(); // Convert the instance from the OID string to an (int). String sOID = oid.toString(); //------------------------------------------// Update the Interface class properties // based on the instance and OID. //------------------------------------------if ( var instanceof OctetString ) { sBufConv = ((OctetString) var).toDisplayString(); } else { sBufConv = var.toString(); } trace.log( 3, "ITSO_SnmpProbe", "updateInterfaces: " + oid + "=" + sBufConv);
298
// ifNumber OID=1.3.6.1.2.1.2.2.1.1.<iIndex> if( sOID.startsWith("1.3.6.1.2.1.2.2.1.1.") ) { siBuffer.ifIndex = sBufConv; } // ifDescr OID=1.3.6.1.2.1.2.2.1.2.<iIndex> else if( sOID.startsWith("1.3.6.1.2.1.2.2.1.2.") ) { siBuffer.ifDescr = sBufConv; } // ifSpeed OID=1.3.6.1.2.1.2.2.1.5.<iIndex> else if( sOID.startsWith("1.3.6.1.2.1.2.2.1.5.") ) { siBuffer.ifSpeed = sBufConv; } // ifInOctets OID=1.3.6.1.2.1.2.2.1.10.<iIndex> else if( sOID.startsWith("1.3.6.1.2.1.2.2.1.10.") ) { siBuffer.ifInOctets = sBufConv; } // ifOutOctets OID=1.3.6.1.2.1.2.2.1.16.<iIndex> else if( sOID.startsWith("1.3.6.1.2.1.2.2.1.16.") ) { siBuffer.ifOutOctets = sBufConv; } } //--------------------------------------------------// Update the vector with the interface information. //--------------------------------------------------vInterfaceList.addElement(siBuffer); } else { // This logs, but should really throw an Exception as no Vector // list has been created due to the bad PDU. trace.log( 3, "ITSO_SnmpProbe", "updateInterfaces: Bad pdu=" + pdu); } } }
299
7.5.4 SnmpInterface.Java
The supporting Java class used for tracking MIB Interface data for the ITSO_SnmpProbe Resource Model is shown in Example 7-52.
Example 7-52 SnmpInterface.Java
//-----------------------------------------------------------------------------// // SnmpInterface.java // // Description: // This file // //-----------------------------------------------------------------------------package com.ibm.tivoli.monitoring.ITSO_SnmpProbe; // PAC Development // naming convention. // Define the class that will maintain each instance data set. public class SNMPInterface { String sHostname = " "; String ifIndex = " "; String ifDescr = " "; String ifSpeed = " "; String ifInOctets = " "; String ifOutOctets = " "; public SNMPInterface() { } }
7.5.5 Resource Model JavaScript

The complete JavaScript that was implemented within the ITSO_SnmpProbe Resource Model file is shown in Example 7-53.
Example 7-53 ITSO_SnmpProbe.dmjsws JavaScript
//'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' // IBM Tivoli Monitoring // Decision Tree script // // 03/26/2003 15:54:41 //''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
300
// This function is used to define the settings of the Resource Model // It is called only once, when the Resource Model is started. // Don't modify remarks containing tags like <<....>> ... <<\...>> // You can write additional initializing code in this function if required. function SetDefaultConfiguration (Svc) { Svc.Trace (0, "ITSO_SnmpProbe: SetDefaultConfiguration - start" ); // General info section //<<GENERAL_INFO>> Svc.SetModelName ("ITSO_SnmpProbe"); Svc.SetProfileName ("3830007"); Svc.SetCycleTime (60); //<<\GENERAL_INFO>> // Thresholds section //<<THRESHOLDS_INFO>> //<<\THRESHOLDS_INFO>> // Parameters section //<<PARAMETERS_INFO>> Svc.DefineStrParameter ("ITSO_Hostnames", "pacs007,pacs005"); //<<\PARAMETERS_INFO>> // Note: In the DefineClass method, we create an ALIAS of "ITSO_SnmpProbe" // to the actual CIM Namespace declaration for our class. // This will be referenced by the AssociateParameterToClass method later. // // Dynamic Model section //<<DATA_INFO>> Svc.DefineClass ("CIM", "ITSO_SnmpProbe", "ROOT\\default:ITSO_SnmpProbe", "", "", "ifDescr,ifIndex,ifSpeed,ifOutOctets,ifInOctets", "None", "", 0, 1); //<<\DATA_INFO>> // Event definition section //<<EVENTS_INFO>> //<<\EVENTS_INFO>> // Logging definition section //<<LOGGING_INFO>> //<<\LOGGING_INFO>> // Place your additional intializing code below Svc.Trace (0, "ITSO_SnmpProbe: SetDefaultConfiguration - end" ); return (0); }
301
// This function is called by the DM For Windows Analyzer after that // the Resource Model default settings have been overridden // It is called only once, when the Resource Model is started. // You can write additional initializing code in this function if required // to use the thresholds and parameters values function Init(Svc) { // Logging Svc.Trace (0, "ITSO_SnmpProbe: Init - start" ); // Variable Initialization var dimHostnames = 0; var dimOIDs = 0; var t=0; // Process the parameter lists. dimHostnames = Svc.GetStrParameterCount("ITSO_Hostnames"); if (dimHostnames > 0 ) { Svc.Trace (0, "ITSO_Hostnames: Init - dimHostnames =" + dimHostnames ); // Note: This is the reference to the alias "ITSO_SnmpProbe" created // in the DefineClass method. Svc.AssociateParameterToClass ("ITSO_Hostnames","ITSO_SnmpProbe"); } else { Svc.Trace (0, "ITSO_SnmpProbe: ITSO_Hostnames parameter is empty"); return(801); } Svc.Trace (0, "ITSO_SnmpProbe: Init - end" ); return (0); }
// This function contains the monitoring algorithm // It is called cyclically after a cycle time has elapsed // Implement the the monitoring code here function VisitTree(Svc) { // Variable Declaration var iHostnameCount; var iInstanceCount; var iIndex; var sTraceOut; var curifIndex; var curifDescr;
302
var curifSpeed; var curifInOctets; var curifOutOctets; // Determine how many hostnames were configured by the Administrator. iHostnameCount = Svc.GetStrParameterCount("ITSO_Hostnames"); Svc.Trace(0,"ITSO_SnmpProbe: VisitTree: iHostnameCount = " + iHostnameCount ); // Determine how many Instances of the ITSO_SnmpProbe class exist. // There will be 1 instance for each interface on each host. iInstanceCount = Svc.GetNumOfInst("ITSO_SnmpProbe"); Svc.Trace(0,"ITSO_SnmpProbe: VisitTree: iInstanceCount = "+ iInstanceCount ); // Process all of the instances for ( iIndex= 0; iIndex < iInstanceCount; iIndex++) { // ifDescrOID = 1.3.6.1.2.1.2.2.1.2 curifDescr = Svc.GetStrProperty("ITSO_SnmpProbe", iIndex, "ifDescr"); Svc.Trace( 0, "GetStrProperty: ifDescr = " + curifDescr ); // ifSpeedOID = 1.3.6.1.2.1.2.2.1.5 curifSpeed = Svc.GetStrProperty("ITSO_SnmpProbe", iIndex, "ifSpeed"); Svc.Trace( 0, "GetStrProperty: ifSpeed = " + curifSpeed ); // ifInOctetsOID = 1.3.6.1.2.1.2.2.1.10 curifInOctets = Svc.GetStrProperty("ITSO_SnmpProbe", iIndex, "ifInOctets"); Svc.Trace( 0, "GetStrProperty: ifInOctets = " + curifInOctets ); // ifOutOctetsOID = 1.3.6.1.2.1.2.2.1.16 curifOutOctets = Svc.GetStrProperty("ITSO_SnmpProbe", iIndex, "ifOutOctets"); Svc.Trace( 0, "GetStrProperty: ifOutOctets = " + curifOutOctets ); } return (0); }
303
304
Chapter 8.
Creating a log-file Resource Model

Sometimes, there is a requirement to pick specific lines from within log files. This is normally handled by a log-file adapter. Log-file adapters, however, do not provide advanced logic capabilities on the local host as ITM does within the Resource Model scripting engine. Therefore, we thought a useful example would be to create a Java based Resource Model, capable of running on Linux based machines as well as Microsoft Windows, that would provide basic log-file parsing.
Attention: You will need to install the JRE provided with ITM for this Resource Model to work on Microsoft windows machines. The best way to do this is to use the command wdmdistrib -p <profile-name> -J <JRE Path> <endpoint>.
305
8.1 Engine component utilization: Overview

In this section, we will give a graphical presentation of the ITM Engine sub-components that will be exercised by this Resource Model. Those components that will not be used within the log-file Resource Model are presented in light gray to de-emphasize their significance, which can be seen in Figure 8-1.

TMWService WMI APIs DM Classic Monitor Probes WMI (CIMOM) Custom Scripts ILT Manager for Java (WMI Provider DLL) WMI Provider DLLs Java Virtual Machine (JVM) Launch (Class Loader) ILT Providers Resource Resource Resource Resource Resource ILT JNI Binary Library JMX ILT MBean Server MBean1
COM Objects
Figure 8-1 Resource Model sub-components for Windows
You will notice from Figure 8-2 on page 307 that the path, in the Java ITM Engine, from Resource Model to resource is a lot more direct and has many less levels to traverse.
306

Custom Scripts
ILT Providers
Resource
Resource
Resource
Figure 8-2 Resource Model sub-components for Java
8.2 Creating the MOF files

Before we can start creating the Resource Model it will be necessary to create and compile two MOF files, which are shown in Example 8-1 and Example 8-2 on page 308.
Example 8-1 Windows MOF file
// produced by WMIMOFWriter from ITSO_Lab03.mof #pragma namespace ("\\\\.\\ROOT\\CIMV2") //============================================= // LogEvent //============================================= [Dynamic, M12_Instrumentation("Java.com.tivoli.wmftools.ilt.logfileadapter.LogfileAdapter | FileName=c:/tmp/logfile1.log ; gnuRegExp='^(.*?)$'; | ENUM"), Provider("M12JavaProvider")] class LogEvent
Chapter 8. Creating a log-file Resource Model
307
{ [Dynamic, M12_Instrumentation("Java.com.tivoli.wmftools.ilt.logfileadapter.LogfileAdapter | gnuRegExp='^(.*?)$'; SubExp=1; | GET"), Provider("M12JavaProvider")] string errorMessage; [key] string FileName; [key] uint32 Offset; [Dynamic, M12_Instrumentation("Java.com.tivoli.wmftools.ilt.logfileadapter.LogfileAdapter | gnuRegExp='^(.*?)$'; SubExp=1; | GET"), Provider("M12JavaProvider")] string timeStamp; };
Note: An important part of Example 8-1 on page 307 is a section called FileName=c:/tmp/logfile.log. This is where you specify the name and path of the file that you wish to monitor. Using forward slashes / is fine. This is the only section that needs changing to make it work on your endpoint. The file will be available for download.
Example 8-2 UNIX MOF file
// produced by UnixMOFWriter from ITSO_Lab03.mof //============================================= // LogEvent //============================================= [M12_Instrumentation("Java.com.tivoli.wmftools.ilt.logfileadapter.LogfileAdapter | FileName=/tmp/logfile1.log ; gnuRegExp='^(.*?)$'; | ENUM"), Provider("com.tivoli.dmunix.ep.touchpoint.cimom.ifc.M12JavaProvider")] class LogEvent { [M12_Instrumentation("Java.com.tivoli.wmftools.ilt.logfileadapter.LogfileAdapter | gnuRegExp='^(.*?)$'; SubExp=1; | GET"), Provider("com.tivoli.dmunix.ep.touchpoint.cimom.ifc.M12JavaProvider")] string errorMessage; [key] string FileName; [key] uint32 Offset; [M12_Instrumentation("Java.com.tivoli.wmftools.ilt.logfileadapter.LogfileAdapter | gnuRegExp='^(.*?)$'; SubExp=1; | GET"), Provider("com.tivoli.dmunix.ep.touchpoint.cimom.ifc.M12JavaProvider")] string timeStamp; };
308
The only difference between the two examples is that the first file has the line #pragma namespace ("\\\\.\\ROOT\\CIMV2") included to associate the MOF file with the Microsoft Windows WMI component.
8.3 Compiling the MOF file

If you have read Chapter 11, File monitoring Resource Model example on page 447, you will already know how to handle this task; if not, then you must follow these steps: 1. Start Workbench, if it is not already running. 2. Open a new Java Resource Model by selecting File New and then selecting the Java Script Resource Model, as shown in Figure 8-3.
Figure 8-3 Workbench new Resource Model window
3. Select the Java Script Resource Model and click on OK, as shown in Figure 8-4.
Figure 8-4 Select VBA or JavaScript language
309
4. Select the Resource Model Wizard, as shown in Figure 8-5.
Figure 8-5 Workspace selection window
5. We will be using a CIM/WMI data source type. Select the following platforms: Solaris, linux-ix86, hpux10, aix4-r1, and linux-s390. Press OK, as shown in Figure 8-6 on page 311.
310
Figure 8-6 Select data source window
6. When the Connect to namespace: dialog box appears, click OK, as shown in Figure 8-7.
Figure 8-7 Connect to namespace window
7. When the WMI Tivoli DM Workbench Login box appears, leave the username and password fields empty and click OK, as shown in Figure 8-8.
311
Figure 8-8 Username/password selection
8. The Browse to namespace box will re-appear. Click OK. 9. The Resource Model Wizard: Select a Class window should now be open, as shown in Figure 8-9 on page 312.
Figure 8-9 Select a Class window
312
10.On the bottom right of the dialog box in Figure 8-9, just above the Show Description... button, you will see a button named MOF Compiler; double-click on it. 11.When the WMI MOF Compiler Wizard window opens, as in Figure 8-10 on page 313, click Next.
Figure 8-10 MOF compiler action select
12.Make sure that the Namespace window says root\CIMV2 and click on the Browse button. Navigate to where you saved your MOF file from the previous section. We saved it at C:\Program Files\Tivoli\IBM Tivoli Monitoring Workbench\samples\WinJavaLogfile\ITSO_Lab03-wmi.mof, as shown in Figure 8-11 on page 314. Click Next.
313
Figure 8-11 MOF file path and namespace
13.In the Specify update options window, we will be using the top or first option within both radio selection boxes, as shown in Figure 8-12 on page 315.
314
Figure 8-12 MOF compiler wizard update options window
14.Click Finish and your MOF will be compiled and added to the repository, as shown in Figure 8-13.
Figure 8-13 MOF compile results window
315
8.4 Creating the Resource Model

1. You should now see the Resource Model Wizard: Select a Class window, as shown in Figure 8-14. Your entry will be revealed by scrolling down till you get to LogEvent. Click on LogEvent in the left hand pane and then click Next.
Figure 8-14 Resource Model Wizard: Select a Class window
2. Select the bottom four items from the table on the Select Properties window and click on the right pointing arrow to place them in the selected table, as in Figure 8-15 on page 317, and then click Next.
316
Figure 8-15 Resource Model Wizard: Select Properties window
3. When you see Figure 8-16 on page 318, click Next, as there is no information that we need to enter.
317
Figure 8-16 Resource Model Wizard: Filtering window
4. In Figure 8-17 on page 319, There is no data entry required, so click Next.
318
Figure 8-17 Resource Model Wizard: Specify the Event Triggering Conditions
5. In Figure 8-18 on page 320, no additional information is required, so click Next.
319
Figure 8-18 Resource Model Wizard: Select the Properties to log window
6. You will now be presented with Figure 8-19. We chose 120 seconds as our cycle time. You may enter anything that you like.
Figure 8-19 Resource Model cycle time data entry panel
7. The IBM Tivoli Monitoring Workbench window will now be presented, as shown in Figure 8-20 on page 321.
320
Figure 8-20 IBM Tivoli Monitoring Workbench main window
8. We now need to add the MOF file for the UNIX part of the Dynamic Model. Right-click on CIM Classes under Dynamic Model and click Add. The Connect to namespace dialog box will open. Click the button to the right of the drop-down box, called Browse for Namespace, enter root\default in the starting namespace box, and then click Connect. The password box will re-appear; click OK twice. You should now see a window similar to Figure 8-21 on page 322.
321
Figure 8-21 Dynamic Model data entry
9. Double-click the MOF compiler icon on the top left hand side of the dialog box and compile in the file called ITSO_Lab03-unix.mof. Your Dynamic Model dialog box should now look like Figure 8-22 on page 323.
322
10.Move the fields errorMessage, FileName, Offset and timestamp from the available column to the selected column using the arrow directors between the columns. You should now see a window that is similar to Figure 8-23 on page 324.
323
11.Click OK.Your main Workbench window should now look like Figure 8-24 on page 325.
324
8.5 Constructing the Resource Model: Events

In this section, we will be opening the Events section of the monitoring tree to create an event that we will use to send information about changes to the log files that we are monitoring to TEC. We will do the following steps: 1. In the events section of the monitor tree, right-click on Events and click on Add. Enter Ev_LogEvent in InternalName, click on the Add button under attributes, enter Offset as a type numeric, and click on the Key button to make it a key. Click the Add button again and enter FileName as a type string and click the key button to make it a key. Click the Add button again and enter timestamp as a type string. Click the Add button one last time and add errorMessage as a type string. Leave the Clearing Event box blank, set the number of occurrences to one and holes to zero, and in the notification panel,
325
make sure that Send to TEC is checked and the severity type is set to Warning. In the string resources panel, set the descriptive name to Log Event. The message field is what is displayed in the TEC console. Anything that is between two @ symbols is a variable and will be substituted by the engine when the event is dispatched to TEC. In the description field, you describe when this event will be triggered. When it looks similar to Figure 8-25, click OK.
Figure 8-25 Event construction window
2. Your Workbench should now have an event defined, as shown in Figure 8-26 on page 327.
326
8.6 Constructing the Resource Model: Dependencies

In this section, we will set some dependencies that are required for the operating system. 1. Expand the dependencies tree. Right-click on the All section under the dependencies tree and click Add. A dialog box will open. Navigate to where you downloaded the wmftools.jar, highlight it, and click Open. Repeat this procedure for the file gnu-regexp-1.1.1.jar. 2. Right-click on the win32-ix86 tree and click Add. A dialog box will open. Navigate to where you saved the file ITSO_Lab03-wmi.mof, highlight it, and click Open. 3. Right-click all UNIX type trees, one at a time, and click Add. A dialog box will open. Navigate to where you saved the file ITSO_Lab03-unix.mof, highlight it,
327
and click Open. The aim here is to add the MOF file to all the UNIX dependencies.You should now have dependencies set for all sections under the dependencies tree, as shown in Figure 8-27
8.7 Constructing the Resource Model: Inserting code

We have listed the Setdefaultconfiguration, Init, and VisitTree subroutines. You may cut and paste these sections into your Workbench Resource Models, if you choose, but we expect that the easiest way will be to download the whole Resource Model from the IBM Redbooks Web site at:
http://www.ibm.com/redbooks
1. The SetDefaultConfiguration subroutine (see Example 8-3 on page 329) has some special code to define three global variables: hPropTable, interpType, and classType. It also contains two removeclass statements. These will
328
remove both classes already defined. This allows the if..else combination to set up the Resource Model correctly, depending on what sort of interpreter type is discerned.
Example 8-3 SetDefaultConfiguration subroutine
//''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' // IBM Tivoli Monitoring // Decision Tree script // // This file has been generated by IBM Tivoli Monitoring Workbench // // 04/08/2003 19:44:28 //'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
var hPropTable; var interpType;
// This function is used to define the settings of the Resource Model // It is called only once, when the Resource Model is started. // Don't modify remarks containing tags like <<....>> ... <<\...>> // You can write additional initializing code in this function if required. function SetDefaultConfiguration (Svc) { interpType = Svc.GetInterp(); // General info section //<<GENERAL_INFO>> Svc.SetModelName ("WizRM_LogEvent"); Svc.SetProfileName ("775316562"); Svc.SetCycleTime (30); //<<\GENERAL_INFO>> // Thresholds section //<<THRESHOLDS_INFO>> //<<\THRESHOLDS_INFO>> // Parameters section //<<PARAMETERS_INFO>> //<<\PARAMETERS_INFO>> // Dynamic Model section //<<DATA_INFO>> Svc.DefineClass ("CIM", "ROOT\\CIMV2:LogEvent", "ROOT\\CIMV2:LogEvent", "", "Offset", "timeStamp,FileName,errorMessage", "None", "", 0, 1);
329
Svc.DefineClass ("CIM", "ROOT\\DEFAULT:LogEvent", "ROOT\\DEFAULT:LogEvent", "", "Offset", "timeStamp,FileName,errorMessage", "None", "", 0, 1); //<<\DATA_INFO>> // Event definition section //<<EVENTS_INFO>> Svc.DefineEvent ("Ev_LogEvent", "Offset", "FileName,timestamp,errorMessage"); //<<\EVENTS_INFO>> // Logging definition section //<<LOGGING_INFO>> //<<\LOGGING_INFO>> // Place your additional intializing code below Svc.RemoveClass("ROOT\\CIMV2:LogEvent"); Svc.RemoveClass("ROOT\\DEFAULT:LogEvent"); if (interpType == "w32-ix86") { Svc.DefineClass ("CIM", "LogEvent", "ROOT\\CIMV2:LogEvent", "", "Offset", "timeStamp,FileName,errorMessage", "None", "", 0, 1); } else{ Svc.DefineClass ("CIM", "LogEvent", "ROOT\\DEFAULT:LogEvent", "", "Offset", "timeStamp,FileName,errorMessage", "None", "", 0, 1); } return (0); }
2. The Init subroutine is executed only once at the start of the Resource Model. Its basic function is to initialize variables. It needs to have some extra code installed to create a property table. Property tables are used to accumulate data and then discharge that data in sending an event. Make sure that your subroutine looks like Example 7-4.
Example 8-4 Init subroutine
// This function is called by the DM For Windows Analyzer after that // the Resource Model default settings have been overridden // It is called only once, when the Resource Model is started. // You can write additional initializing code in this function if required // to use the thresholds and parameters values function Init(Svc) { hPropTable = Svc.CreateMap(); return (0);
330
3. The VisitTree subroutine (see Example 8-5) is executed each time that cycle time expires. It is here that the intelligence of the Resource Model is invoked. It also needs some code inserted.
Example 8-5 VisitTree subroutine
// This function contains the monitoring algorithm // It is called cyclically after a cycle time has elapsed // Implement the monitoring code here function VisitTree(Svc) { var FileName; var Offset; var timestamp; var errorMessage; var line; re = /(\D+ \D+ \d+ \d+:\d+:\d+ \d+ )(.*)/i; var numOfInstances; var idx;
numOfInstances = Svc.GetNumOfInst("LogEvent"); for ( idx = 0; idx < numOfInstances; idx++) { Svc.RemoveMapAll(hPropTable); FileName = Svc.GetStrProperty("LogEvent", idx, "FileName"); Svc.SetMapStrElement(hPropTable,"FileName", FileName); Offset = Svc.GetNumProperty("LogEvent", idx, "Offset"); Svc.SetMapNumElement(hPropTable,"Offset", Offset); line = Svc.GetStrProperty("LogEvent", idx, "timeStamp"); timestamp = line.match(re); Svc.Trace(2,"Match$1 is " + RegExp.$1); Svc.Trace(2,"Match$2 is " + RegExp.$2); timestamp = RegExp.$1; Svc.SetMapStrElement(hPropTable,"timestamp", timestamp); errorMessage = RegExp.$2; Svc.SetMapStrElement(hPropTable,"errorMessage", errorMessage); Svc.SendEventEx ("Ev_LogEvent",hPropTable); } return (0);
331
8.8 The flow of the code

At the bottom of this subroutine, after the line // Place your additional initializing code below, you will notice two removeclass statements. As we are going to unitize CIM structures based on interpreter type, we need to remove both structures. The if..else then redefines the CIM model required based on the interpreter typed obtained at the top of the subroutine by the Svc.GetInterp statement.
Init subroutine
The Init subroutine is always executed once per Resource Model per start of the Tmw2k.exe engine. There is a little extra code for this Resource Model that defines hPropTable by the method Svc.CreateMap. It is important to define it in the Init subroutine as this should only be done once.
VisitTree subroutine
This subroutine runs each time the cycle time expires. It gets the number of occurrences of LogEvent and then constructs a simple loop to process them. The key point to note is the declaration variable re. In the examples case, it is set to re = /(\D+ \D+ \d+ \d+:\d+:\d+ \d+ )(.*)/i. An example of the log file that we constructed looks like Wed Dec 15 01:23:11 2002 Thread 1 advanced to log sequence 23. An application of the above regular expression to the above line would yield Wed Dec 15 01:23:11 in the variable timestamp and the remainder of the line in errorMessage. Please note that this is the example that we used and it would process every line in your log file. In real life you would code your regular expression to a much finer point to ensure that you only show the lines of the log file in which you were interested. The process would continue until all the instances of logevent were processed and the whole process is then repeated after the cycle timer expires
332
Chapter 9.
Creating a log-file Resource Model and ILT

In Chapter 8, Creating a log-file Resource Model on page 305, we described how to create a Resource Model utilizing the log file ILT provided by the ITM Component Service. In this chapter, our focus will be on the creation of our own ILT to analyze the specified log file. We will use the ITSO_Sample ILT introduced in Chapter 5, Engineering a Java ILT on page 137 as a template. Therefore, this chapter is also an example of how to extend the ITSO_Sample ILT for a specific objective. This chapter includes various hints and tips for creating your own ILT code. This chapter describes the following topics: Designing the ITSO_LogfileLite Resource Model and ILT Creating the ITSO_LogfileLite Resource Model and ILT ITSO_LogfileLite source code
333
9.1 Designing the ITSO_LogfileLite Resource Model and ILT

In this section, we describe how to design the ITSO_LogfileLite Resource Model.

The ITSO_LogfileLite Resource Model monitors multiple log files specified by the parameters and counts the matching lines for the pattern specified by the other parameter. For example, if you specify /opt/IBMHTTPServer/logs/access_log as the log file name and 404 as the pattern, the ITSO_LogfileLite will periodically read the delta part of the /opt/IBMHTTPServer/logs/access_log and count the number of the lines that contain the 404. If the number of the matching lines exceeds the threshold, the ITSO_LogfileLite will generate the appropriate event. Then the administrator knows that many errors are occurring in the log files. The ITSO_LogfileLite ILT is the management interface between the target log files and the ITSO_LogfileLite Resource Model. The ITSO_LogfileLite ILT accesses the log file and collects the required information. Then it reports the management information to the Resource Model in the form of the CIM repository. The overview of ITSO_LogfileLite Resource Model is shown in Figure 9-1 on page 335.
334
1 Get values of the instances from ILT
6 Compare with Thresholds Generate events
Parameters ITSO_LogfileLite_FileName ITSO_LogfileLite_Pattern Thresholds
ITSO_LogfileLite Resource Model

Thr_EventNum_gt
ITSO_LogfileLite.mof ITSO_LogfileLite-wmi.mof
2 Pass through file names Pass through patterns 5 Return values
ITSO_LogfileLite ILT/Provider
4 Store values of each instances Store offset values
3 Read log files Count matched lines
Log file
Log file
Log file
Figure 9-1 Design overview of ITSO_LogfileLite Resource Model
The ITSO_LogfileLite Resource Model and the ILT tightly cooperate with each other and exchange management information. Here is the rough flow of how the ITSO_LogfileLite Resource Model and the ILT work: 1. The ITSO_LogfileLite Resource Model receives the parameters and the thresholds and then invokes the various methods to retrieve data from ITSO_LogfileLite ILT. 2. When retrieving the data, the ITSO_LogfileLite Resource Model hands names of the log files and the patterns to the ITSO_LogfileLite ILT. 3. The ITSO_LogfileLite ILT reads the delta part of the log files and counts the matching lines.
Chapter 9. Creating a log-file Resource Model and ILT
335
4. Then the ITSO_LogfileLite ILT stores the CIM values of each instance and also stores the offset information of each file. The offset information is provided for the purpose of getting the delta part. It is just the last line number checked by the ITSO_LogfileLite ILT. 5. The ITSO_LogfileLite ILT returns the appropriate values for each property to the ITSO_LogfileLite Resource Model. 6. The ITSO_LogfileLite Resource Model compares the result from the ITSO_LogfileLite ILT with the threshold. If the result is exceeding the threshold, the ITSO_LogfileLite Resource Model will generate the appropriate event.
Note: The ITSO_LogfileLite Resource Model has the limitation of supporting the rotation algorithm of the log file. Most applications have a rotation function to maintain their log files. In general, if the rotation occurs, the log file is copied to another name and the original log file is initialized. The ITSO_LogfileLite Resource Model can detect the initialization of the log file by checking that the offset is lower than the previous last line. Then the ITSO_LogfileLite Resource Model will check the log file from the first line. However, it will not check the other file, which is generated by the rotation tools. Therefore, events generated just before the rotation invoking can be lost.

This example uses the white part of the ITM Engine, as shown in Figure 9-2 on page 337 and Figure 9-3 on page 337. It is based on the Java ILT, which can support both of the UNIX and Windows platforms.
336

TMWService
WMI APIs DM Classic Monitor Probes WMI (CIMOM) Custom Scripts ILT Manager for Java (WMI Provider DLL) WMI Provider DLLs Java Virtual Machine (JVM) Launch (Class Loader) ILT Providers ILT JNI Binary Library JMX ILT MBean Server MBean1
Resource
COM Objects
Resource
Resource
Resource
Resource
Figure 9-2 Windows ITM Engine Logical Components
Java, IT M Engine Logical Components

Analyzer Reso urce M odel R eso urce M o del Reso urce M odel S ervice Object R eso urce M o del Resource M o del
Custom Scripts
Launch (C lass Lo ader)
ILT Pro viders
ILT JN I Native Binaries
JM X ILT M Bean Server M Bean(s)
Reso urce
R eso urce
Reso urce
R eso urces (OS & Applicatio ns)
Figure 9-3 UNIX ITM Engine Logical Components
337
9.1.3 The detailed design of the ITSO_LogfileLite Resource Model

We describe the detailed design of the ITSO_LogfileLite Resource Model in this section.
External design of the ITSO_LogfileLite Resource Model

First, we define the parameter and the threshold as external inputs of the Resource Model, as shown in Table 9-1 and Table 9-2. The ITSO_LogfileLite Resource Model receives multiple file names to monitor as the parameter list. The ITSO_LogfileLite Resource Model also accept multiple words of regular expression for the pattern matching.
Table 9-1 The parameter
Parameter Default
ITSO_LogfileLite_FileName (STRING-LIST TYPE) ITSO_LogfileLite_Pattern (STRING-LIST TYPE)
/tmp/log1.log Thread

Indications Default
ITSO_LogfileLite_EventNum_too_high
>5
Internal design of the ITSO_LogfileLite Resource Model

To create the Resource Model smoothly, we recommend that you make a list of elements of your Resource Model, as shown in Table 9-3.
Table 9-3 A list of elements of the ITSO_LogfileLite Resource Model
Elements Contents
Internal Name Descriptive Name Category Internal Name Category Descriptive Name Dynamic Model Events Thresholds Parameters
ITSO_LogfileLite_RM ITSO_LogfileLite ITSO_RMs ITSO Resource Models ITSO_LogfileLite ITSO_LogfileLite_EventNum_too_high Thr_EventNum_gt ITSO_LogfileLite_FileName ITSO_LogfileLite_Pattern
338
Elements
Contents
Logging Dependency
none ALL: ITSO_LogfileLite.jar aix4-r1: ITSO_LogfileLite.mof linux-i86: ITSO_LogfileLite.mof w32-ix86: ITSO_LogfileLite-wmi.mof
Defining the algorithm

To write the decision tree script, we recommend that you start by drawing a flowchart that shows how the algorithm works, as in Figure 9-4 on page 340.
339
Start
Count the number of the instances and set "0" to i variable
GetProperty of the Instance(i)
Exceeding Threshold?
Yes Send event No
i++
Last instance?
End
Figure 9-4 Flowchart of ITSO_LogfileLite decision tree script
340
9.2 Creating the ITSO_LogfileLite Resource Model and ILT

Following the base design described in 9.1, Designing the ITSO_LogfileLite Resource Model and ILT on page 334, we move forward to creating the ITSO_LogfileLite Resource Model and ILT. We discuss how to create the ITSO_LogfileLite Resource Model and ILT with the following procedures: 1. Setting up the development environment 2. Creating the MOF file 3. Creating the ITSO_LogfileLite ILT code 4. Creating the Resource Model 5. Packaging 6. Testing the Resource Model
9.2.1 Setting up the development environment

First, you need to set up the development environment, especially for writing the Java code. 1. Installing the Java 2 SDK To develop the Java ILT code, you need the Java 2 SDK environment first. We recommend you use the same version of the Java with the one installed in the monitored machine, as is required by ITM.
Note: In this example, we use the Java 2 SDK 1.3.1, which is available in the following URL:
http://java.sun.com
2. Setting the PATH To enter Java 2 SDK commands in the DOS prompt, you need the adequate PATH environment variable in the system configuration. Click on the Windows Start menu and select Setting Control Panel System. In the next window, select the Advanced tab and click on the Environment Variable button. Locate the PATH environment variable and add <Java SDK installed Directory>/bin with the javac command and the jar command. 3. Setting the CLASSPATH To smoothly compile the Java ILT of the IBM Tivoli Monitoring Version 5.1.1, you can optionally add the jar files of IBM Tivoli Monitoring Version 5.1.1 to
341
the CLASSPATH environment variable. The jar files of IBM Tivoli Monitoring Version 5.1.1 are included in <Workbench_installed_directory>\Lcfnew\Tmw2k\Unix\bin. Without this, you will need to use the -classpath option every time you compile Java ILT/Provider code. Click on the Windows Start menu and select Setting Control Panel System. In the next window, select the Advanced tab and click on the Environment Variable button. Locate the CLASSPATH environment variable and edit it, as shown in Figure 9-5.
Figure 9-5 Setting the CLASSPATH environment variable
In this example, we use the GNU Regexp Java package for better pattern matching in the Java code. Therefore, we add the gnu-regexp-1.1.1.jar file to CLASSPATH as well. You can find the gnu-regexp-1.1.1.jar file in $BINDIR/lcf_bundle.40/generic/cmptsvcs/gnu.regexp/gnu-regexp-1.1.1.jar if you installed the ITM component service.
Note: For more information about the GNU Regexp see the following URL. You can also obtain the latest gnu-regexp package there.
http://www.cacas.org/java/gnu/regexp/
4. Creating the working directory In the working directory, you should create the directory structure following the structure of the Java package. In this example, we use com.ibm.tivoli.monitoring.ITSO_LogfileLite as the package name. Therefore, we create the directory for the Java ILT code, as shown in Example 9-1
Example 9-1 Creating the working directory
c:\> mkdir <working dir>/com/ibm/tivoli/monitoring/ITSO_LogfileLite
342
9.2.2 Creating the MOF file

To prepare the CIM Class and properties required, you need to create the MOF file and compile it into the name space. The MOF files must be different between UNIX and Windows. Therefore, we create two MOF files, ITSO_LogfileLite.mof for UNIX and ITSO_LogfileLite-wmi.mof for Windows, to use the ITSO_LogfileLite Resource Model on the cross-platform environment. ITSO_LogfileLite.mof We create the ITSO_LogfileLite.mof file as the UNIX MOF file. It is also a basic MOF file that you will compile with the MOF compiler. The ITSO_LogfileLite.mof defines the required class and properties in the CIM repository, as shown in Example 9-2.
Example 9-2 ITSO_LogfileLite.mof
1://--------------------------------------------------------------------------2:// 3:// ITSO_LogfileLite.mof 4:// 5:// Description: 6:// This file is a textual definition of the ITSO_LogfileLite CIM class. 7:// 8://--------------------------------------------------------------------------9:[ 10:Description ("ITSO LogfileLite"), 11:provider("com.tivoli.dmunix.ep.touchpoint.cimom.ifc.M12JavaProvider"), 12:M12_Instrumentation 13:{"Java.com.ibm.tivoli.monitoring.ITSO_LogfileLite.ITSO_LogfileLiteIlt | | 14:ENUM", 15: "Java.com.ibm.tivoli.monitoring.ITSO_LogfileLite.ITSO_LogfileLiteIlt | | 16:GET"} 17:] 18:class ITSO_LogfileLite 19:{ 20: [key]string FileName;// Attribute, Instance key FileName. 21: sint32 EventNum;// Attribute, Eventnum. 22:};
Let us explain the important parts of the ITSO_LogfileLite.mof: a. Line 18: We define a class named the ITSO_LogfileLite in this line. The class name will be shown in the CIM browser when creating the Resource Model. b. Line 20 to 21: These lines define two properties: FileName and EventNum, as shown in Table 9-4 on page 344.
343
Table 9-4 Properties

Property FileName Type Description
string
The FileName indicates the log file name that is being monitored. It takes over file names from the Parameter ITSO_LogfileLite_FileName. The EventNum indicates the number of the events that are counted by the log files for each cycle.
EventNum
sint32
The instance values of these CIM properties construct a kind of table-type structure. The [key] in line 20 means that the FileName is the key property and must be unique. Table 9-5 shows an example set of the property values for each instance.
Table 9-5 An example of the values of the properties
Properties Instances FileName [key] EventNum
Instances A Instances B Instances C
/tmp/log1.log /tmp/log2.log /tmp/log3.log
10 0 7
ITSO_LogfileLite-wmi.mof To use the ILT on Windows, you need another MOF file that the WMI can understand. We create the ITSO_LogfileLite-wmi.mof for the Windows platform, as shown in Example 9-3.
Example 9-3 ITSO_LogfileLite-wmi.mof
1: // produced by WMIMOFWriter from ITSO_LogfileLite.mof 2: #pragma namespace ("\\\\.\\ROOT\\CIMV2") 3: //============================================= 4: // ITSO_LogfileLite 5: //============================================= 6: [Description("ITSO LogfileLite"), Dynamic, M12_Instrumentation{"Java.com.ibm.tivoli.monitoring.ITSO_LogfileLite.ITSO_Logfi leLiteIlt | | ENUM", "Java.com.ibm.tivoli.monitoring.ITSO_LogfileLite.ITSO_LogfileLiteIlt | | GET"}, provider("M12JavaProvider")] 7: class ITSO_LogfileLite 8: { 9: sint32 EventNum; 10: [key] 11: string FileName;
344
12: };
The differences between UNIX and Windows in this case are: Line 2: On Windows MOFs, specify the cimv2 namespace:
#pragma namespace("\\\\.\\ROOT\\CIMV2")
Line 6: On Windows MOFs, add the Dynamic qualifier to the CIM class. Line 6: On Windows MOFs, use M12JavaProvider and not com.tivoli.dmunix.ep.touchpoint.cimom.ifc.M12JavaProvider as the Provider for the instances and properties. See 4.2.3, Managed Object Format (MOF) on page 114 for more information about the MOF file.
9.2.3 Creating the ITSO_LogfileLite ILT code

Next, we create the Java code for the ILT.
Summarizing the relation

Following the terminology described in 5.1, Terminology on page 138, we separate the ILT into two Java classes. One Java class is the ILT class, which implements the ILTInterface class. The other is the Provider class, which is instantiated within the ILT class and actually performs the metering of resources. Each class has methods for the specific objectives that are related to each other, as shown in Figure 9-6.
ITSO_LogfileLite Resource Model ITSO_LogfileLite ILT ITSO_LogfileLite Provider
getProperty GetStrProperty GetNumProperty getMultipleProperties getITSOAttribute getITSO_LogfileLiteVar_ EventNum
GetNumOfInst
enumerateInstances
getITSO_Instances
AssociateParameter ToClass Parameters Parameterset
Figure 9-6 The relationship of the methods
345
The left big box named ITSO_LogfileLite Resource Model is a group of major methods that are used to retrieve values from the ILT. These methods are called in the decision tree script of the Resource Model. The AssociateParameterToClass() method in the decision tree script is very important, as it hands the parameter lists to the ILT code. The middle big box named ITSO_LogfileLite ILT is a group of the major methods included in the ILT class. Using these methods, the ILT class accepts requests from the Resource Model and invokes the appropriate methods of the Provider code. The right big box named ITSO_LogfileLite Provider is a group of the major methods included in the Provider class. The Provider code executes the low level operation to the managed resource directly and get the required information.
File location
To fit the directory structure into the package name, you need to put two Java class codes in the following directory under the working directory:
The ILT class code
com/ibm/tivoli/monitoring/ITSO_LogfileLite/ ITSO_LogfileLiteILT.java
The Provider class code com/ibm/tivoli/monitoring/ITSO_LogfileLite/ ITSO_LogfileLite.java
Creating the ITSO_LogfileLite ILT

In this section, we describe how to create the Java ILT class, ITSO_LogfileLiteILT.java. Following Chapter 5, Engineering a Java ILT on page 137, we implement major operations in the ITSO_LogfileLite ILT class, as shown in Table 9-6.
Table 9-6 Operations in the ITSO_LogfileLite ILT
ILT public operation Notes
getProperty
Added supporting Java code to support retrieval of one property from the Provider. The getProperty invokes the getITSOAttribute for one time. Added supporting Java code to support retrieval of multiple properties from the Provider. The getMultipleProperties invokes the getITSOAttribute multiple times.
346
ILT public operation
Notes
enumerateInstances
Added supporting Java code to handle passed Resource Model parameters and instantiation. The enumerateInstances method invokes the getITSO_Instances method, which is from the Provider. Added supporting Java code to handle get the attribute of the specified property from the Provider. The getITSOAttribute method invokes the getITSO_LogfileLiteVar_EventNum method, which is from the Provider. Only log tracing was added, as this method was not required for this sample. Only log tracing was added, as this method was not required for this sample. Only log tracing was added, as this method was not required for this sample. Only log tracing was added, as this method was not required for this sample. Only log tracing was added, as this method was not required for this sample.
getITSOAttribute
setProperty invokeMethod (first interface) invokeMethod (second interface) create destroy
Based on the ITSO_Sample ILT introduced in Chapter 5, Engineering a Java ILT on page 137, we have added some additional code to handle the required task. Let us explain the important parts of the ILT class code. Defining the class In the beginning of the code, you need to define the package and class. a. Line 24: This line defines the package name in which the ILT code is included. b. Line 26 to 31: This line imports other classes from outside the code. c. Line 33: This line defines the ILT class. Combining with the package name, the fully qualified class name is determined as the com.ibm.tivoli.monitoring.ITSO_LogfileLite.ITSO_LogfileLiteIlt. You can see that our MOF file in Example 9-2 on page 343 uses this name.
347
Example 9-4 Defining the package of the ITSO_LogfileLiteILT.java

24: package com.ibm.tivoli.monitoring.ITSO_LogfileLite; // Part of the ILT package. 25: 26: import com.ibm.tivoli.monitoring.ITSO_LogfileLite.ITSO_LogfileLite; // Provider Class 27: import com.tivoli.dmunix.ep.touchpoint.base.*; // ITM Class : "dm_m12.jar" 28: import com.tivoli.javautils.Trace; // ITM Class : "javautils.jar" 29: import java.util.Enumeration; // Java Class 30: import java.util.Vector; // Java Class 31: import java.util.*; // Java Class 32: 33: public class ITSO_LogfileLiteIlt implements ILTInterface 34: {
Note: We use the com.ibm.tivoli.monitoring.<ILT_General_Name> as the package name, following the naming convention recommended by the developer.
Defining the global hashtable The offset in this example means the number of the last line checked by the ITSO_LogfileLite ILT. We define a global hashtable offsetarray at Line 41 in Example 9-5 to keep the offset information of each file. You can set or get variables from the offsetarray anywhere in the ILT class code. The offsetarray hashtable is initialized only when the ITM Engine starts up. This helps the ILT class to maintain the offset information through all cycles in which the ITM Engine starts up.
Example 9-5 Defining the global hashtable
41: // Define the global hashtable. .... 46: private Hashtable offsetarray = new Hashtable();
Getting the values of the ITSO_LogfileLite_Pattern parameter In this example, the ITSO_LogfileLite Resource Model hands two parameter lists to the ILT class: ITSO_LogfileLite_Pattern parameter and ITSO_LogfileLite_FileName parameter. These parameter lists are associated with the CIM class by using the AssociateParameterToClass() method in the Init part of the decision tree script. The ITSO_LogfileLite_Pattern parameter is extracted into the array of the patterns in the GetPropert() and GetMultipleProperties(). Example 9-6 on page 349 shows you a part of the GetProperty() and GetMultipleProperties() in the Java ILT class.
348
a. Line 117: This line gets the ITSO_LogfileLite_Pattern parameter into a Vector vParam. b. Line 125 to 133: These lines map the contents of the Vector vParam into the one dimension array named asITSO_LogfileLite_Pattern(). c. Line 147: The asITSO_LogfileLite_Pattern() array is passed to the getITSOAttribute() method as the pattern for the matching.
Example 9-6 Getting values of the ITSO_LogfileLite_Pattern parameter
113: //-----------------------------------------------------------------114: // Get the parameters of the patterns from the caller. 115: //-----------------------------------------------------------------116: Enumeration enumeration = parameterset.parametersNames(); 117: Vector vParam = (Vector)parameterset.getParam("ITSO_LogfileLite_Pattern"); 118: if(vParam == null) 119: { 120: trace.log(1, "ITSO_LogfileLiteIlt", "enumerateInstances: no parameters found"); 121: return null; 122: } 123: 124: // Process the ITSO_LogfileLite_Pattern parameter. 125: String asITSO_LogfileLite_Pattern[] = new String[vParam.size()]; 126: for(int iIndex = 0; iIndex < vParam.size(); iIndex++) 127: { 128: // Get the string array element from the vector element. 129: asITSO_LogfileLite_Pattern[iIndex] = (String)vParam.elementAt(iIndex); 130: trace.log( 3, "ITSO_LogfileLiteIlt", 131: "enumerateInstances: asITSO_LogfileLite_Pattern[" + iIndex + 132: "] = " + asITSO_LogfileLite_Pattern[iIndex]); 133: } 134: 135: M12IdentityElement m12identityelement = 136: m12objectidentity.getScopingPath()[0]; 137: M12PropertySet m12propertyset = m12identityelement.getIdentity(); 138: 139: // Determine which instance is being checked by the 140: // Management Layer. 141: String sKey = m12propertyset.getProperty("FileName"); 142: trace.log(3, "ITSO_LogfileLiteIlt", 143: "getProperty: called for FileName " + sKey); 144: 145: // Get the attributes being checked by the Management Layer. 146: // Get the current attribute values. 147: String sValue = getITSOAttribute(sKey, sPropertyName, asITSO_LogfileLite_Pattern); 148: trace.log(3, "ITSO_LogfileLiteIlt", 149: "getITSOAttribute: " + sPropertyName + " = " + sValue);
349
150: return sValue;
Getting values of the ITSO_LogfileLite_FileName parameter Example 9-7 shows you a part of the enumerateInstances method in the Java ILT class code. a. Line 316: This line puts the ITSO_LogfileLite_FileName parameter into a Vector vParam. b. Line 323 to 332: These lines map the contents of the Vector vParam into the one dimension array named asITSOArrayGui(). c. Line 339: The asITSOArrayGui() array is passed to the getITSO_Instances() method, which is a Provider call to create a list of the instance keys. The result of the getITSO_Instances() method is set to aiInst[]. d. Line 347 to 360: These lines set the values in the aiInst() into the M12PropertySet using the setProperty call.
Example 9-7 Getting values of the ITSO_LogfileLite_FileName parameter
310: //-----------------------------------------------------------------311: // Get the parameters from the caller. 312: // We are obtaining the parameters prior to declaring instances so 313: // we can configure an instance for each parameter. 314: //-----------------------------------------------------------------315: Enumeration enumeration = parameterset.parametersNames(); 316: Vector vParam = (Vector)parameterset.getParam("ITSO_LogfileLite_FileName"); 317: if(vParam == null) 318: { 319: trace.log(1, "ITSO_LogfileLiteIlt", "enumerateInstances: no parameters found"); 320: return null; 321: } 322: 323: // Process the ITSO_LogfileLite_FileName parameter. 324: String asITSOArrayGui[] = new String[vParam.size()]; 325: for(int iIndex = 0; iIndex < vParam.size(); iIndex++) 326: { 327: // Get the string array element from the vector element. 328: asITSOArrayGui[iIndex] = (String)vParam.elementAt(iIndex); 329: trace.log( 3, "ITSO_LogfileLiteIlt", 330: "enumerateInstances: asITSOArrayGui[" + iIndex + 331: "] = " + asITSOArrayGui[iIndex]); 332: } 333: 334: //-----------------------------------------------------------------335: // Acquire a vector (pointer) from the calling ILT Manager.
350
336: 337: 338: 339: 340: 341: 342: 343: 344: 345: 346: 347: 348: 349: 350: 351: 352: 353: 354: 355: 356: 357: 358: 359: 360: 361: 362: 363:
// This section handles the registration of instances of this // Instrumentation. //-----------------------------------------------------------------String aiInst[] = pitso_logfilelite.getITSO_Instances( asITSOArrayGui ); if(aiInst == null) { trace.log(1, "ITSO_LogfileLiteIlt", "enumerateInstances: no instances found"); return null; } for(int jIndex = 0; jIndex < aiInst.length; jIndex++) { trace.log( 3, "ITSO_LogfileLiteIlt", "enumerateInstances: aiInst[" + jIndex + "] = " + aiInst[jIndex]); M12PropertySet m12propertyset = new M12PropertySet(); m12propertyset.setProperty( "FileName", aiInst[jIndex] ); M12IdentityElement m12identityelement = new M12IdentityElement( m12classpath.getClassName(), m12classpath.getNameSpace(), m12propertyset); vector.add( new M12ObjectIdentity( new M12IdentityElement[] { m12identityelement } ) ); } return vector.elements(); }
Getting attributes for each properties The getITSOAttribute() method is internal to the class and is designed to segregate the ILT operations from our own supporting methods. a. Line 644 and 684 and 692: The getITSOAttribute() method changes its behavior depending on the property name that is passed as the sProperty. If the sProperty is the EventNum, it will return the event number of the log file specified as the sValue. If the sProperty is the FileName, it will return just sValue as the file name. If the sProperty is the unknown property, it will throw an exception. b. Line 653 to 661: Before invoking the Provider call, the offset value is retrieved from the global hashtable offsetarray, which sends the last line number value to the getITSO_LogfileLiteVar_EventNum(). c. Line 667: The getITSOAttribute() method invokes a Provider call named the getITSO_LogfileLiteVar_EventNum() method, which will execute a specific task for the log file, as described in Getting the EventNum value
351
on page 354. The getITSO_LogfileLiteVar_EventNum() uses the offset information to determine which line to start counting.
Example 9-8 Getting attributes for each properties
627: //-----------------------------------------------------------------------628: // 629: // GetAttributeTypes 630: // 631: // This method is internal to the class and is designed to segregate the 632: // ILT Operations from our own supporting methods. It is simply to provide 633: // cleaner & easier to maintain code. 634: // 635: //-----------------------------------------------------------------------636: private String getITSOAttribute( String sValue, 637: String sProperty, 638: String asITSO_LogfileLite_Pattern[] ) 639: throws Exception 640: { 641: //---------------------------------------------------------------------642: // Return the EventNum value 643: //---------------------------------------------------------------------644: if( (sProperty.equals("EventNum"))) 645: { 646: String offset = "-1"; 647: int r = 0; 648: 649: // Retrieve the offset value for the filename from the offsetarray 650: // hashtable. If the offsetarray doesn't have the appropriate offset, 651: // assign "-1" to the offset variable and keep it in the offsetarray. 652: 653: String v = (String)offsetarray.get(sValue); 654: 655: if ( v == null ) { 656: offset = "-1"; 657: offsetarray.put(sValue, offset); 658: } 659: else { 660: offset = v; 661: } 662: 663: // Run the getITSO_LogfileLiteVar_EventNum() and assign the result 664: // to the intVar[] array. 665: // intVar[] = { EventNum, offset } 666: 667: int intVar[] = pitso_logfilelite.getITSO_LogfileLiteVar_EventNum(sValue, asITSO_LogfileLite_Pattern, offset); 668: 669: // Keep the new offset value in the offsetarray hashtable.
352
670: 671: 672: 673: 674: 675: 676: 677: 678: 679: 680: 681: 682: 683: 684: 685: 686: 687: 688: 689: 690: 691: 692: 693: 694: 695:
offsetarray.put(sValue, String.valueOf(intVar[1])); // Trace trace.log( 3, "ITSO_LogfileLiteIlt", "getITSOAttribute result offset" + intVar[1] + " EventNum = " + intVar[0] + " FileName = " + sValue); trace.log( 3, "ITSO_LogfileLiteIlt", "global array: offset" + (String)offsetarray.get(sValue)); // Return the EventNum value. return String.valueOf(intVar[0]); } //---------------------------------------------------------------------// Return the FileName value //---------------------------------------------------------------------if( (sProperty.equals("FileName"))) { return sValue; } //---------------------------------------------------------------------// Unknown property. //---------------------------------------------------------------------else { throw new Exception(sProperty + ": unknown property"); } }
Creating the ITSO_LogfileLite Provider code

In this section, we describe how to create the Java Provider class ITSO_LogfileLite.java. We implement major operations in the ITSO_LogfileLite Provider class, as shown in Table 9-7.
Table 9-7 Operations in the ITSO_LogfileLite Provider
ILT public operation Notes
getITSO_Instances getITSO_LogfileLiteVar_EventNum
Added supporting Java code to organize an array of the instance key sets. Added supporting Java code to support the specific task for the EventNum property. The getITSO_LogfileLiteVar_EventNum method reads the delta part of the specific log file and count lines matching the specified pattern.
353
The Provider class is called from the ILT class. The Provider class takes charge of the specific tasks that have directory access to the management resource (the log file in this example). Let us explain the important parts of the Provider class code: Defining the class In the beginning of the code, you need to define the package and class. a. Line 11: This line defines the package name in which the Provider class is included. b. Line 13 to 17: These lines import other classes from outside of the code. You can see the import statement for the gnu.regexp package, which is used for the better pattern matching. c. Line 20: This line defines the Provider class. Combining with the package name, the fully qualified class name is com.ibm.tivoli.monitoring.ITSO_LogfileLite.ITSO_LogfileLite. The ILT Class code imports the Provider class using this name in the import statement, as shown in Line 26 of Example 9-4 on page 348.
Example 9-9 Defining the package of the ITSO_LogfileLite.java
11: package com.ibm.tivoli.monitoring.ITSO_LogfileLite; of the ILT package. 12: 13: import com.tivoli.javautils.Trace; // "javautils.jar" 14: import gnu.regexp.*; // GNU REGEXP package 15: import java.lang.*; // Java Class 16: import java.util.*; // Java Class 17: import java.io.*; // Java Class 18: 19: 20: public class ITSO_LogfileLite 21: { // Part
Getting the EventNum value The getITSO_LogfileLiteVar_EventNum() method is responsible for the most important task, which reads the delta part of the specific log file and count lines matching the specified pattern. a. Line 78 and 80: These lines open a log file. b. Line 83 to 110: These lines compare whole lines in the log file with patterns. If it finds the matching line in the part that is older than the offset, it increases the c1 counter. If it finds the matching line in the part that is newer than the offset, it increase the c2 counter. c. Line 90: This line compiles a pattern for use in the regexps getmatch() methods.
354
d. Line 119 to 123: If the offset is still -1, it means this is the first time. Therefore, it discards the result and reports 0 as the EventNum. e. Line 124 to 132: If the last line number is lower than the offset, the file was initialized. Therefore, it returns the c1 value, which is the counter that is older than offset. On the other hand, if the last line number is higher than the offset, it returns the c2 value, which is the counter that is newer than offset.
Example 9-10 getITSO_LogfileLiteVar_EventNum
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: 84: 85: 86: 87: 88: 89: 90: 91: 92: //---------------------------------------------------------------------// getITSO_LogfileLiteVar_EventNum //---------------------------------------------------------------------public static synchronized int[] getITSO_LogfileLiteVar_EventNum( String i, String as[], String offset ) { // retrieve pattern(); int c = 0; int c1 = 0; int c2 = 0; int obj = 0; int lastline; int[] retarray = new int[2]; try { RE re = null; REMatch mat; String sl = offset; // offSet = retrieve offSet(i);
// Create a FileReader object FileReader fr = new FileReader(i); BufferedReader br = new BufferedReader(fr); LineNumberReader lr = new LineNumberReader(fr); // Read strings in the file String line; while((line = lr.readLine()) != null) { for(int iIndex = 0; iIndex < as.length; iIndex++) { // Compile the string for the pattern matching try { re = new RE(as[iIndex]); } catch (REException e) { break;
355
93: } 94: 95: Integer tmp = Integer.valueOf(sl); 96: obj = tmp.intValue(); 97: 98: // Pattern match 99: mat = re.getMatch(line); 100: if (mat != null) { 101: 102: if (obj > lr.getLineNumber()) { 103: c1++; // Increase the counter older than the offset 104: } else { 105: c2++; // Increase the counter newer than the offset 106: } 107: 108: } 109: } 110: } 111: 112: // Store the lastline number 113: 114: lastline = lr.getLineNumber(); 115: 116: // Close the FileReader object 117: fr.close(); 118: 119: if ( offset == "-1" ) { // If the offset is "-1", this is the first time. 120: retarray[0] = 0 ; // Discards the result and 121: // returns "0" as the EventNum. 122: retarray[1] = lastline ; 123: } 124: else { 125: if ( lastline < obj ) { // If the lastline is lower than offset, the file was initialized. 126: retarray[0] = c1; // Returns the c1 value which is the counter older than offset 127: retarray[1] = lastline; 128: } else { // If lastline is upper than offset, 129: retarray[0] = c2; // returns the c2 value which is the counter newer than offset 130: retarray[1] = lastline; 131: } 132: } 133: 134: } 135: catch (Exception e) { 136: ; 137: }
356
138: return retarray; 139: }
Compiling the Java classes

You now have two Java class codes of ITSO_LogfileLite ILT under the working directory:
The ILT class code
com/ibm/tivoli/monitoring/ITSO_LogfileLite/ ITSO_LogfileLiteILT.java
The Provider class code com/ibm/tivoli/monitoring/ITSO_LogfileLite/ ITSO_LogfileLite.java

You need to compile these Java files to use them in the ITSO_LogfileLite Resource Model. 1. First, you need to compile the Provider class ITSO_LogfieLite.java, because the ILT class imports the Provider class. Keep in mind that you have to have the required jar files and class files in the CLASSPATH, as described in 9.2.1, Setting up the development environment on page 341. Compile the Java codes, as in Example 9-11.
Example 9-11 Compiling the Java classes
c:\> cd <working dir> c:\<working dir>> javac com/ibm/tivoli/monitoring/ITSO_LogfileLite/ITSO_LogfileLite.java c:\<working dir>> javac com/ibm/tivoli/monitoring/ITSO_LogfileLite/ITSO_LogfileLiteILT.java
2. If the compile completes without errors, create a jar file that includes all of the required class files, as shown in Example 9-12. When distributing the profile, the jar file will be distributed to the Endpoint directory as a dependency file.
Example 9-12 Creating the jar file
c:\<working dir> jar cvf ./ITSO_LogfieLite.jar com/ibm/tivoli/monitoring/ITSO_LogfileLite/*.class c:\<working dir> jar tvf ./ITSO_LogfieLite.jar 0 Thu Apr 24 10:04:54 CDT 2003 META-INF/ 71 Thu Apr 24 10:04:54 CDT 2003 META-INF/MANIFEST.MF 2173 Thu Apr 24 10:00:40 CDT 2003 com/ibm/tivoli/monitoring/ITSO_LogfileLite/ITSO_LogfileLite.class 7691 Thu Apr 24 10:00:48 CDT 2003 com/ibm/tivoli/monitoring/ITSO_LogfileLite/ITSO_LogfileLiteIlt.class
357
Note: The ITM Engine has the CLASSPATH pointing the specific jar files of IBM Tivoli Monitoring Version 5.1.1, which are located in $LCF_DATDIR/LCFNEW/Tmw2k/Unix/bin. Therefore, you do not need to add these jar files to your own jar file for this procedure.
9.2.4 Creating the Resource Model

You now have the required files to create your Resource Model: the MOF files and the ILT/Provider class code. Like the other examples, we use the Resource Model Wizard to create a base template and extend it into a better one.
Using the Wizard

Let us begin by clicking on the New icon in the left side of the Workbench toolbar, as shown in Figure 9-7
Figure 9-7 Creating a new Resource Model
In the next window, we choose the Resource Model Wizard and the JavaScript Resource Model. Then you have to choose the data source, as shown in Figure 9-8 on page 359. Select the CIM/WMI and supported platforms. In this example, we choose aix4-r1, linux-ix86, solaris2, and w32-ix86 as supported platforms.
358
Figure 9-8 Selecting data source
Figure 9-9 prompts you to select the namespace to connect. Click the OK button and connect to the root/CIMV2 namespace.
Figure 9-9 Connect to namespace
The next window shows you the CIM classes included in the root/CIMV2 namespace. You need to compile the ITSO_LogfileLite.mof file to use the required class. Double-click the MOF Compiler icon, as shown in Figure 9-9 on page 354.
359
Figure 9-10 Launching the MOF Compiler
In the MOF Compiler Wizard, select Compile a MOF file and click the Next button. The next window asks you to input the file name of the MOF file. Enter ITSO_LogfileLite.mof with the full path. Modify the namespace as root/CIMV2, because you need to compile the MOF file into the root/CIMV2 namespace when you use it on the Windows platform. Then click the Next button.
Note: The IBM Tivoli Monitoring Users Guide Version 5.1.1, SH19-4569 states that you should use the root/default namespace for UNIX. However, in fact, you can use any namespace on UNIX. Therefore, the root/CIMV2 is also valid for the UNIX platform.
360
Figure 9-11 Selecting a MOF file
The next window prompts you to select the update option. Leave the default setting and click the Finish button. If you have no error in the next window, as shown in Figure 9-12, the compile was done successfully. If you received any error messages, check the syntax of your MOF file.
Figure 9-12 Completing the compile
361
After the compile of the MOF file is done, you can see the ITSO_LogfileLite CIM class in the next window. If you do not have the class name yet, reconnect to the root/CIMV2 namespace by clicking on the lock icon next to the root/CIMV2 to refresh the list.
Figure 9-13 Selecting the class
In the next window, you can specify the filtering (we have no filtering for this example). Leave the default setting and click on the Next button. In the next window, you can specify the trigger condition of the event. Select the EventNum and click the > button in the middle. The next window prompts you to enter a trigger condition, as shown in Figure 9-14 on page 363. Enter 5 as the Threshold. This mean the event will be generated when the EventNum becomes greater than 5.
362
Figure 9-14 Trigger condition
In the next window, you can specify properties to be logged. We select no property to be logged in this scenario. Leave the default setting. At the end of the wizard, the Workbench prompts you to set the default cycle time. After that task is done, template creation of your ITSO_LogfileLite Resource Model is complete. We recommend that you save the file before proceeding to the next step.
Editing the Resource Model

You now have a basic template of the ITSO_LogfileLite Resource Model. Now we have to modify the Resource Model to use our own ILT/Provider. Follow these steps: 1. Changing properties The wizard sets the default property of the Resource Model. You can change it by double-clicking the thermometer icon on the left side of the Workbench. In the next window, you can change the property of the Resource Model. Referring to the list in Table 9-3 on page 338, we set the property, as shown in Figure 9-15 on page 364.
363
Figure 9-15 Property of the ITSO_LogfileLite Resource Model
2. Setting the alias name of the CIM class The AssociateParameterToClass() method requires the alias name of the CIM class to be ITSO_LogfileLite. Select the ROOT/CIMV2:ITSO_LogfileLite icon under the Dynamic Model. Right-click on it and select Modify. In the next window, enter ITSO_LogfileLite in the Use Alias area, as shown in Figure 9-16 on page 365, and then click OK.
364
Figure 9-16 Setting the alias name of the CIM class
After this procedure, you can use ITSO_LogfileLite as the name of the CIM class in the decision tree script. 3. Modifying event The wizard creates an event using the default naming convention, such as the Ev_ITSO_LogfileLite_EventNum_too_high shown in this example. In this step, we change the default setting of the event. Because you need to input a number of attributes in the event setting, we recommend that you prepare lists of the event setting, as shown in Table 9-8 on page 366, in advance. Double-click the Ev_ITSO_LogfileLite_EventNum_too_high icon under the Events icon. In the next window, change the event setting to what is shown in Figure 9-17 on page 366.
365
Figure 9-17 Changing the event setting
Note: The ITM Engine will distinguish events by the key attribute. To distinguish events by the log file name, we choose the FileName as a key attribute.
Table 9-8 The event of ITSO_LogfileLite_EventNum_too_high
Elements Contents
Internal Name Attributes Aggregation Setting Keys Clearing Event Occurrence/Hole Notification Send to TEC/TBSM Severity
ITSO_LogfileLite_EventNum_too_high. NUMERIC: EventNum, UpperBound. STRING: FileName. FileName. Yes. 1 / 0. Yes. CRITICAL.
366
Elements
Contents
String Resources
Descriptive Name Message
ITSO_LogfileLite_EventNum_too_high. ITSO_LogfileLite_EventNum_too_high: The property EventNum(@EventNum@) of the instance (FileName=@FileName@) is greater than @UpperBound@.
Note: If you check the Clearing Event, it will generates TMW_Clearing Event when the problem is resolved, which means the number of the matching line becomes lower than the threshold.
4. Modifying the threshold The wizard creates one threshold using the default naming rule. In this step, we change the default setting of the threshold. At this time, we also recommend that you prepare a list of threshold settings, as shown in Table 9-9, in advance. Double-click the Thr_EventNum_gt icon under the Thresholds icon. In the next window, change the threshold setting, as shown in Figure 9-18.
Figure 9-18 Changing the threshold setting Table 9-9 The threshold definition for Thr_EventNum_gt
Elements Value
Internal Name Descriptive Name Default Value Description
Thr_EventNum_gt Thr_EventNum_gt 5 Thr_EventNum_gt
367
5. Adding parameters We add two parameters that indicate the log file name and the pattern. Double-clicking the Parameters icon on the left side of the Workbench. In the next window, enter the parameter name, as shown in Figure 9-19 and Figure 9-20. We create two parameters: ITSO_LogfileLite_Pattern and ITSO_LogfileLite_FileName.
Figure 9-19 Adding the ITSO_LogfileLite_Pattern parameter
Figure 9-20 Adding the ITSO_LogfileLite_FileName parameter
6. Adding dependencies The ITSO_LogfileLite Resource Model needs dependency files: MOF files and a jar file containing ILT/Provider class files. The jar file of the ILT/Provider class can be used on all platforms because it is written purely in Java. Therefore, you can put the jar file in the ALL platform section. On the other hand, for the MOF file, you need to use different MOF files between the UNIX
368
platform and the Windows platform. Therefore, we put the MOF files in each platforms dependencies. Table 9-10 shows a summary of the dependencies.
Table 9-10 Dependency files for each platform
Platform File Description
ALL
ITSO_LogfileLite.jar gnu-regexp-1.1.1.jar
The jar file containing the ILT/Provider Class. The jar file containing the gnu-regexp package. The MOF file for the UNIX platform. The MOF file for the UNIX platform. The MOF file for the UNIX platform. The MOF file for the Windows platform.
aix4-r1 linux-i86 solaris2 w32-ix86
ITSO_LogfileLite.mof ITSO_LogfileLite.mof ITSO_LogfileLite.mof ITSO_LogfileLite-wmi.mof
When completed, you can see that the dependency files are correctly added, as shown in Figure 9-21 on page 370.
369
Figure 9-21 Dependencies
7. Editing the decision tree script To implement the required monitoring function, edit the decision tree script. Refer to the flowchart shown in Figure 9-4 on page 340, which describes the detailed design of the decision tree script before continuing with this section. Let us explain the important parts of our modification of the decision tree script. SetDefaultConfiguration The SetDefaultConfiguration function defines the settings of the Resource Model. It is called only once, when the Resource Model starts. The contents of the SetDefaultConfiguration function automatically reflects what you defined in the left pane of the Workbench, such as events, thresholds, parameters, and so on. Therefore, you do not need to change this part of this example. shows the decision tree script of the SetDefaultConfiguration function.
370
Example 9-13 The decision tree script of the ITSO_LogfileLite: SetDefaultConfiguration

13: function SetDefaultConfiguration (Svc) 14: { 15: Svc.Trace (0, "ITSO_LogfileLite: SetDefaultConfiguration - start" ); 16: 17: // General info section 18: //<<GENERAL_INFO>> 19: Svc.SetModelName ("ITSO_LogfileLite_RM"); 20: Svc.SetProfileName ("80652796"); 21: Svc.SetCycleTime (60); 22: //<<GENERAL_INFO>> 23: 24: // Thresholds section 25: //<<THRESHOLDS_INFO>> 26: Svc.DefineThreshold ("Thr_EventNum_gt", 5.000000); 27: //<<THRESHOLDS_INFO>> 28: 29: // Parameters section 30: //<<PARAMETERS_INFO>> 31: Svc.DefineStrParameter ("ITSO_LogfileLite_Pattern", "Thread"); 32: Svc.DefineStrParameter ("ITSO_LogfileLite_FileName", "/tmp/log1.log"); 33: //<<PARAMETERS_INFO>> 34: 35: // Note:In the DefineClass method, we create an ALIAS of "ITSO_LogfileLite" to the actual CIM Namespace declaration for our class. 36: //This will be referenced by the AssociateParameterToClass method later. 37: // 38: // Dynamic Model section 39: //<<DATA_INFO>> 40: Svc.DefineClass ("CIM", "ITSO_LogfileLite", "ROOT\CIMV2:ITSO_LogfileLite", "", "EventNum", "FileName", "None", "", 0, 1); 41: //<<DATA_INFO>> 42: 43: // Event definition section 44: //<<EVENTS_INFO>> 45: Svc.DefineEvent ("ITSO_LogfileLite_EventNum_too_high", "EventNum,UpperBound", "FileName"); 46: //<<EVENTS_INFO>> 47: 48: // Logging definition section 49: //<<LOGGING_INFO>> 50: //<<LOGGING_INFO>> 51: 52: // Place your additional intializing code below 53: Svc.Trace (0, "ITSO_LogfileLite: SetDefaultConfiguration - end" ); 54: 55: return (0);
371
56: }
Init The Init function is called after the completion of the SetDefaultConfiguration. We use the Init function to call the AssociateParameterToClass() method. The descriptions of the lines below refer to lines in Example 9-14. i. Line 77-90: Associating the ITSO_LogfileLite_FileName: Using the AssociateParameterToClass() method, we associate the ITSO_LogfileLite_FileName to the ITSO_LogfileLite CIM class. ii. Line 77-90: Associating the ITSO_LogfileLite_Pattern: Using the AssociateParameterToClass() method, we associate the ITSO_LogfileLite_Pattern to the ITSO_LogfileLite CIM class.
Example 9-14 The decision tree script of the ITSO_LogfileLite: Init
64: function Init(Svc) 65: { 66: // Logging 67: Svc.Trace (0, "ITSO_LogfileLite: Init - start" ); 68: 69: // Variable Initialization 70: var dimension = 0; 71: var t=0; 72: 73: // 74: // Process the parameter lists. 75: // ITSO_LogfileLite_FileName 76: // 77: dimension= Svc.GetStrParameterCount("ITSO_LogfileLite_FileName"); 78: if (dimension > 0 ) 79: { 80: Svc.Trace (0, "ITSO_LogfileLite: Init - dimension =" + dimension); 81: 82: // Note:This is the reference to the alias "ITSO_LogfileLite" created in the DefineClass method. 83: // 84: Svc.AssociateParameterToClass ("ITSO_LogfileLite_FileName","ITSO_LogfileLite"); 85: } 86: else 87: { 88: Svc.Trace (0, "ITSO_LogfileLite: ITSO_LogfileLite_FileName parameter is empty"); 89: return(801);// Return an error if the Resource Model is dependant on the paramater to function. 90: }
372
91: 92: // 93: // Process the parameter lists. 94: // ITSO_LogfileLite_Pattern 95: dimension= Svc.GetStrParameterCount("ITSO_LogfileLite_Pattern"); 96: if (dimension > 0 ) 97: { 98: Svc.Trace (0, "ITSO_LogfileLite: Init - dimension =" + dimension); 99: 100: // Note:This is the reference to the alias "ITSO_LogfileLite" created in the DefineClass method. 101: // 102: Svc.AssociateParameterToClass ("ITSO_LogfileLite_Pattern","ITSO_LogfileLite"); 103: } 104: else 105: { 106: Svc.Trace (0, "ITSO_LogfileLite: ITSO_LogfileLite_FileName parameter is empty"); 107: return(802);// Return an error if the Resource Model is dependant on the paramater to function. 108: } 109: 110: Svc.Trace (0, "ITSO_LogfileLite: Init - end" ); 111: return (0); 112: }
VisitTree The VisitTree function contains the monitoring algorithm. It is called cyclically after a cycle time has elapsed. The actual monitoring task should be written here. The following description of lines refer to lines shown in Example 9-15 on page 374. i. Line 121 to 132: Define variables: We define the variables used in further steps. In fact, you can use additional valuables without defining them in some case. However, we recommend that you define variables explicitly. ii. Line 138: Count the number of instances: Using GetNumOfInst(), we calculate the number of instances to decide how many times we execute the loop. iii. Line 141 and Line 159: Start the loop/End the loop: We create a loop that retrieves each instance and checks them. iv. Line 144 and 148: Get the properties: Using the GetNumProperty() method and the GetStrProperty() method, we get the value of the properties.
373
v. Line 152 to 157: Check the threshold and send the events: We compare the curEventNum variable with the Thr_EventNum_gt threshold. If it exceeds the threshold, the SendEventEx() will generate an event.
Example 9-15 The decision tree script of the ITSO_LogfileLite: VisitTree
119: function VisitTree(Svc) 120: { 121: // Variable Declaration 122: var curEventNum; 123: var curFileName; 124: 125: var hPropTable; 126: var iParameterCount; 127: var iInstanceCount; 128: var idx; 129: var sTraceOut; 130: 131: hPropTable = Svc.CreateMap(); 132: 133: // 134: iParameterCount= Svc.GetStrParameterCount("ITSO_LogfileLite_FileName"); 135: Svc.Trace(0,"ITSO_LogfileLite: VisitTree: iParameterCount = " + iParameterCount ); 136: 137: // 138: iInstanceCount = Svc.GetNumOfInst("ITSO_LogfileLite"); 139: Svc.Trace(0,"ITSO_LogfileLite: VisitTree: iInstanceCount = "+ iInstanceCount ); 140: 141: for ( idx = 0; idx < iInstanceCount; idx++) 142: { 143: 144: curEventNum = Svc.GetNumProperty("ITSO_LogfileLite", idx, "EventNum"); 145: sTraceOut = "GetNumProperty: curEventNum = " + curEventNum ; 146: Svc.Trace( 0, sTraceOut ); 147: 148: curFileName = Svc.GetStrProperty("ITSO_LogfileLite", idx, "FileName"); 149: sTraceOut = "GetStrProperty: FileName = " + curFileName ; 150: Svc.Trace( 0, sTraceOut ); 151: 152: if (curEventNum > Svc.GetThreshold("Thr_EventNum_gt") ) { 153: Svc.SetMapNumElement(hPropTable,"UpperBound",Svc.GetThreshold("Thr_EventNum_gt" )); 154: Svc.SetMapNumElement(hPropTable,"EventNum",curEventNum ); 155: Svc.SetMapStrElement(hPropTable,"FileName",curFileName ); 156: Svc.SendEventEx ("ITSO_LogfileLite_EventNum_too_high",hPropTable);
374
157: 158: 159: 160: 161: 162: 163: 164: 165: 166:
} } Svc.DestroyMap(hPropTable); return (0); }
9.2.5 Packaging
The various components discussed within this chapter must be packaged into a Resource Model tar file; you build this tar file with the Workbench. The Resource Model Tar File relationship diagram in Figure 9-22 shows all components of a typical Resource Model, with those not used within the ITSO_LogfileLite presented in light gray to de-emphasize their significance.

Configuration File Logging: Parameter(s):
ITSO_LogfileLite_FileName ITSO_LogfileLite_Pattern
Dynamic Model(s): CIM Class "ITSO_LogfileLite"
Action(s): Threshold(s): Thr_EventNum_gt Event(s):

ITSO_LogfileLite_EventNum_too_high
Reference Model Functions: ITSO_LogfileLite_RM.js
Message Catalogs MOF(s): ITSO_LogfileLite.mof ITSO_LogfileLite-wmi.mof Custom Files(s) Dependencies Files
Provider(s): ITSO_LogfileLite.jar
Custom Scripts()
Figure 9-22 Packaging
375
Copy the package file to TMR Server and register it with IBM Tivoli Monitoring Version 5.1.1, as shown in Example 9-16.
Example 9-16 Registering the ITSO_LogfileLite Resource Model
# wdmrm -add ITSO_LogfileLite_RM.tar IBM Tivoli Monitoring - Adding new Resource Model Copying ITSO_LogfileLite_RM.cat msgfile ... Copying ITSO_LogfileLite_RM.cat zipfile ... IBM Tivoli Monitoring - Resource Model utility Parsing configuration file ITSO_LogfileLite_RM.conf ... Configuration file successfully parsed. Checking for event redefinition... Starting resource ITSO_LogfileLite_RM registration ... the resource ITSO_LogfileLite_RM has been successfully stored. Registration completed. Installation completed.

In this section, we describe how to set up the environment to run the ITSO_LogfileLite Resource Model and then describe how it is tested.
Setting the environment

The ITSO_LogfileLite Resource Model is a Java ILT based Resource Model that works on both UNIX and Windows. It requires JRE as a runtime environment. On UNIX, you should have already installed JRE as the required software of the ITM Engine. Therefore, you do not need special requirements. On the other hand, the Windows ITM Engine is not implemented in Java. In addition to the ITM basic engine, the m12javaProvider is provided for the purpose of supporting Java ILT on Windows, which needs Java Runtime Environment 1.3 or 1.3.1. Therefore, you need additional setup for the ITM Engine to work with a Java-based Resource Model. Follow the IBM Tivoli Monitoring Users Guide Version 5.1.1, SH19-4569 and install the following software on your Windows machines: Java Runtime Environment (JRE) 1.3 or 1.3.1 Microsoft Windows Script Host 5.6 After installing IBM Tivoli Monitoring, you should use the DMLinkJre task to link the product to your JRE.
376
Distributing the profile

After the JRE is set, you can distribute the profile, including the ITSO_LogfileLite Resource Model. Let us explain what the profile setting of the ITSO_LogfileLite Resource Model looks like. Category and Resource Model When adding the Resource Model to the profile, the ITSO_LogfileLite Resource Model is displayed, as shown in Figure 9-23. Also, you can see the category name and Resource Models. The thresholds and cycle time are also displayed here. You are able to edit both of them.
Figure 9-23 Category and Resource Model
Parameters Click the Parameters button shown in Figure 9-23, and the Parameters window will be displayed, as in Figure 9-23. You can see two parameters in
377
the ITSO_LogfileLite Resource Model: ITSO_LogfileLite_FileName (Figure 9-24) and ITSO_LogfileLite_Pattern (Figure 9-25 on page 379). ITSO_LogfileLite_FileName Enter file names you want to monitor in the normal expression on each platform. For example, on UNIX, you can specify /tmp/log1.log, and on Windows, you can specify c:\temp\log1.log. If you specify a file that does not exist, it will be ignored when monitoring.
Figure 9-24 Parameter ITSO_LogfileLite_FileName
ITSO_LogfileLite_Pattern Enter the regular expression you want to use for the pattern matching. It is used by the GNU Regexp package in the ITSO_LogfileLite Resource Model. For example, if you enter Thread as a regular expression, the line containing Thread will be matched. If you enter ^[0-9]+ .* as a regular expression, the lines starting with a number will be matched, such as 001 This line starts with a number. See the following URL for more details about the regular expression:
378
Figure 9-25 Parameter ITSO_LogfileLite_Pattern
Note: If you specify multiple values in the ITSO_LogfileLite_Pattern, the ITSO_LogfileLite Resource Model will report the total number of matched lines of all patterns.
Events Click on the Indications button shown in Figure 9-23 on page 377. You can see the event definition, as shown in Figure 9-26 on page 380.
379
Figure 9-26 Event ITSO_LogfileLite_EventNum_too_high
Testing the ITSO_LogfileLite Resource Model

In this section, we describe how to test the ITSO_LogfileLite Resource Model on the UNIX endpoint. The major procedures are the same as the Windows platform. We definitely describe it if there is any difference between UNIX and Windows. Set the parameters as follows and distribute the profile to your endpoint: ITSO_LogfileLite_FileName: tmp/log1.log c:\temp\log1.log ITSO_LogfileLite_Pattern :404 Then check to see if the ITSO_LogfileLite Resource Model works.
380
Checking the distributed files After a successful distribution of the profile, you should see that the dependency files are copied into the appropriate directory of the endpoint. Check the following specific files for this Resource Model: a. ITSO_LogfileLite.jar This file is the jar file containing the ILT class file and the Provider class file. On both UNIX and Windows, you can find it in the directory $LCFD_DATDIR/LCFNEW/Tmw2k/Unix/Classes/ITSO_RMs. b. ITSO_LogfileLite-wmi.mof This file is the MOF file for the Windows platform. On Windows, you can find it in the directory $LCFD_DATDIR/LCFNEW/Tmw2k/Mof. On UNIX, the MOF file will not be extracted in the endpoint directory. c. ITSO_LogfileLite.js This is the decision tree script file in JavaScript. On Windows, you can find it in the directory $LCFD_DATDIR/LCFNEW/Tmw2k/Dec. On UNIX, you can find it in the directory $LCFD_DATDIR/LCFNEW/Tmw2k/Unix/Dec. Checking the result of the wdmlseng command The wdmlseng command is useful for checking the status of the Resource Model. Run the wdmlseng command to check your Resource Model, as shown in Example 9-17.
Example 9-17 Checking the result of the wdmlseng command
# wdmlseng -e pacs006-ep Forwarding the request to the engine...
The following profiles are running: ITSO_Lab01_PF#pacs007-region ITSO_LogfileLite_RM: Running
If you have any status other than Running, check trace files. Checking the trace and log files The ITM Engine has powerful trace and log files for problem determination. We have mainly used the trace and log files summarized in Table 9-11 on page 382. If you find any Java exception or error message in these files, it indicates the possible problem and cause.
381
Table 9-11 Summary of the useful trace and log files

Platform File Name Description
UNIX
msg_dmxengine.log
This log maintains the general behavior of the UNIX ITM Engine, such as the start, the initializing, and sending events. This log maintains the detailed behavior of the UNIX ITM Engine, including the internal variables condition. This log maintains the detailed behavior of the Windows ITM Engine, including the internal variables condition. This log maintains the detailed behavior of the Windows m12javaProvider, including the internal variables condition.
trace_dmxengine.log
Windows
Tmw2k.log
trace_ILTManagerForJava. log
You can also change the trace level by using the wdmtrceng command from your TMR server or managed node. When investigating problems or testing code, we usually set it to level 3, as shown in Example 9-18, and see how the variables in the Resource Model/ILT acts.
Example 9-18 Setting the trace level
# wdmtrceng -e EP_Name 3 8000000
Example 9-19 is an example of how the trace_dmxengine.log shows the values in the Resource Model. This file contains the trace information from not only the Resource Model but also the ILT code. We embedded a log method in some important places of the ILT code. The message shown in Example 9-19 is the result of the call trace.log( 3, ITSO_LogfileLiteIlt, getITSOAttribute result offset + intVar[1] + EventNum = + intVar[0] + FileName = + sValue) in the ILT code.
Example 9-19 Sample message in the trace file
<F>1050608620158<F>Thu Apr 17 14:43:40 CDT 2003<F>AMW<F>Engine<F>pacs006-ep<F>15884<F>OTHER<F>ITSO_LogfileLiteIlt<F><F>Thr ead[TmrSrvAction_RMTimer,5,main]<F>getITSOAttribute result offset37 EventNum = 0 FileName = /tmp/log1.log<F>None
Generating the event Let us make the ITSO_LogfileLite Resource Model generate an event. We create a sample file that looks like Apaches access log, as shown in Example 9-20 on page 383.
382
Example 9-20 Sample.log

[root@pacs006 logs]# cat /tmp/sample.log a.b.c.d - - [17/Apr/2003:15:37:08 -0500] a.b.c.d - - [17/Apr/2003:15:37:41 -0500] a.b.c.d - - [17/Apr/2003:15:37:42 -0500] a.b.c.d - - [17/Apr/2003:15:37:42 -0500] a.b.c.d - - [17/Apr/2003:15:37:43 -0500] a.b.c.d - - [17/Apr/2003:15:37:43 -0500] a.b.c.d - - [17/Apr/2003:15:37:44 -0500] a.b.c.d - - [17/Apr/2003:15:37:44 -0500] a.b.c.d - - [17/Apr/2003:15:37:44 -0500] a.b.c.d - - [17/Apr/2003:15:37:44 -0500] a.b.c.d - - [17/Apr/2003:15:37:45 -0500] a.b.c.d - - [17/Apr/2003:15:37:58 -0500] a.b.c.d - - [17/Apr/2003:15:37:58 -0500] a.b.c.d - - [17/Apr/2003:15:37:58 -0500] "GET "GET "GET "GET "GET "GET "GET "GET "GET "GET "GET "GET "GET "GET /footer.gif HTTP/1.1" 200 968 /failpage.html HTTP/1.1" 404 310 /failpage.html HTTP/1.1" 404 310 /failpage.html HTTP/1.1" 404 310 /failpage.html HTTP/1.1" 404 310 /failpage.html HTTP/1.1" 404 310 /failpage.html HTTP/1.1" 404 310 /failpage.html HTTP/1.1" 404 310 /failpage.html HTTP/1.1" 404 310 /failpage.html HTTP/1.1" 404 310 /failpage.html HTTP/1.1" 404 310 / HTTP/1.1" 304 /whole.jpg HTTP/1.1" 304 /Configure.jpg HTTP/1.1" 304
Add this sample.log file in the end of the monitored log file, in this case, /tmp/log1.log, as shown in Example 9-21. This will add 14 lines, which has 10 lines containing the pattern word 404.
Example 9-21 /tmp/log1.log
[root@pacs006 logs]# cat /tmp/sample.log >> /tmp/log1.log
Wait one cycle time, then you can see an event generated in the msg_dmxengine.log (Example 9-22). It indicates that the EventNum is 10, which matches the number of the 404 lines in the /tmp/sample.log file.
Example 9-22 Checking the event in the msg_dmxengine.log
<F>1050612525319<F>Thu Apr 17 15:48:45 CDT 2003<F>AMW<F>Engine<F>pacs006-ep<F>15884<F>AMW2002I<F>AMW2002I The event ITSO_LogfileLite_EventNum_too_high;modelname="ITSO_LogfileLite_RM";profilename= "ITSO_Lab01_PF#pacs007-region";filename="/tmp/log1.log";eventid="1050612525077" ;severity="CRITICAL";event_key="ITSO_LogfileLite_EventNum_too_high|FileName=/tm p/log1.log;";eventnum= 10.0;upperbound= 5.0;hostname="pacs006-ep";origin="9.3.5.36";adapter_host="pacs006-ep";date="04/ 17/200303:48:45 PM";msg="ITSO_LogfileLite_EventNum_too_high: The property EventNum(10.0) of the instance (FileName=/tmp/log1.log) is greater than 5.0";END ^A has been sent to Tivoli Enterprise Console.<F>INFO
You can also check that an indication occurred by using the wdmlseng command with the -verbose option, as shown in Example 9-23 on page 384. The
383
percentage value indicates the health level of the indication. If it shows the value 0%, it reaches the occurrence count and generates the event.
Example 9-23 Checking the event using the wdmlseng command
# wdmlseng -e pacs006-ep -verbose Forwarding the request to the engine... The following profiles are running: ITSO_Lab01_PF#pacs007-region ITSO_LogfileLite_RM: Running ITSO_LogfileLite_EventNum_too_high 0 %
9.3 ITSO_LogfileLite source code

The following files were created for the purpose of this example.
9.3.1 ITSO_LogfileLite.mof
The UNIX MOF file used for the ITSO_LogfileLite Resource Model is shown in its entirety in Example 9-24.
Example 9-24 ITSO_LogfileLite.mof
//---------------------------------------------------------------------------// // ITSO_LogfileLite.mof // // Description: // This file is a textual definition of the ITSO_LogfileLite CIM class. // //---------------------------------------------------------------------------[ Description ("ITSO LogfileLite"), provider("com.tivoli.dmunix.ep.touchpoint.cimom.ifc.M12JavaProvider"), M12_Instrumentation {"Java.com.ibm.tivoli.monitoring.ITSO_LogfileLite.ITSO_LogfileLiteIlt | | ENUM", "Java.com.ibm.tivoli.monitoring.ITSO_LogfileLite.ITSO_LogfileLiteIlt | | GET"} ] class ITSO_LogfileLite { [key]string FileName;// Attribute, Instance key FileName. sint32 EventNum;// Attribute, Eventnum.
384
};
9.3.2 ITSO_LogfileLite-wmi.mof
The Windows MOF file used for the ITSO_LogfileLite Resource Model is shown in its entirety in Example 9-25.
Example 9-25 ITSO_LogfileLite Windows MOF file
// produced by WMIMOFWriter from ITSO_LogfileLite.mof #pragma namespace ("\\\\.\\ROOT\\CIMV2") //============================================= // ITSO_LogfileLite //============================================= [Description("ITSO LogfileLite"), Dynamic, M12_Instrumentation{"Java.com.ibm.tivoli.monitoring.ITSO_LogfileLite.ITSO_Logfi leLiteIlt | | ENUM", "Java.com.ibm.tivoli.monitoring.ITSO_LogfileLite.ITSO_LogfileLiteIlt | | GET"}, provider("M12JavaProvider")] class ITSO_LogfileLite { sint32 EventNum; [key] string FileName; };
9.3.3 ITSO_LogfileLiteILT.java
The ILT Java Class code used for the ITSO_LogfileLite Resource Model is shown in its entirety in Example 9-26.
Example 9-26 ITSO_LogfileLite ITLT Java Class
//----------------------------------------------------------------------------// // ITSO_LogfileLiteILT.java // // Description: // This file is the ITSO_LogfileLite Instrumentation Library Type (ILT) // implementation. This is the class instantiated by the "touchpoint" // layer. This class will execute methods in the "ITSO_LogfileLite.java" file, // which is the physical "provider" and performs the actual data // acquisition. // // Various classes are referenced throughout this file. ILT Supported // Classes, which are documented, in the IBM Tivoli Monitoring Workbench // User's Guide Version 5.1.1, SH19-4571, include:
385
// M12ClassPath// M12IdentityElement // M12ObjectIdentity // M12PreportySet // M12Exception // ParameterSet // ParameterSetList // //----------------------------------------------------------------------------package com.ibm.tivoli.monitoring.ITSO_LogfileLite; // Part of the ILT package. import com.ibm.tivoli.monitoring.ITSO_LogfileLite.ITSO_LogfileLite; // Provider Class import com.tivoli.dmunix.ep.touchpoint.base.*; // ITM Class : "dm_m12.jar" import com.tivoli.javautils.Trace; // ITM Class : "javautils.jar" import java.util.Enumeration; // Java Class import java.util.Vector; // Java Class import java.util.*; // Java Class public class ITSO_LogfileLiteIlt implements ILTInterface { //-------------------------------------------------------------------------// Instantiate the required class. //-------------------------------------------------------------------------private ITSO_LogfileLite pitso_logfilelite; private Trace trace; // Define the gloal hashtable. // offsetarray hashtable = { FileName, offset } // This hashtable keeps the offset variables which record the lastline number // checked by the ITSO_LogfileLite ILT. // This hashtable is initialized only when the ITM Engine starts. private Hashtable offsetarray = new Hashtable();
//-------------------------------------------------------------------------// ITSO_LogfileLiteIlt class - Creator method. //-------------------------------------------------------------------------public ITSO_LogfileLiteIlt() { pitso_logfilelite = new ITSO_LogfileLite(); trace = Trace.getTraceInstance(); }
386
//-------------------------------------------------------------------------// Instrumentation Library Type (ILT) // - Public Operations // // Note: This is documented in the IBM Tivoli Monitoring Workbench User's // Guide Version 5.1.1, SH19-4571. // //--------------------------------------------------------------------------
//-------------------------------------------------------------------------// //getProperty // //Supported: YES // //Syntax: // public java.lang.String getProperty( M12ObjectIdentity targetInstance, // java.lang.String propertyName, // java.lang.String mappingString, // ParameterSet parms ) // throws M12Exception // //Parameters: // targetInstance - M12ObjectIdentity that identifies the instance of the // resource to be accessed. // propertyName The property whose value is required. // mappingString - Any string that has been specified in the // M12_Instrumentation qualifier for the GET operation // type for this property. // parms A ParameterSet object filled by the client with // parameters associated to this property. // //Description: // Gets the value (in String format) of the specified property for the // identified object. // //Returns: // String - The value for property propertyName. Property values have to // be CIM standard types and ILT converts them to string format // according to the CIM standards. // //Exceptions Thrown: // M12Exception //--------------------------------------------------------------------------
387
public String getProperty( M12ObjectIdentity m12objectidentity, String sPropertyName, String sMapping, ParameterSet parameterset ) throws M12Exception { try { // Variable Declaration. StringBuffer stringbuffer = new StringBuffer(); Vector vector = new Vector();
//-----------------------------------------------------------------// Get the parameters of the patterns from the caller. //-----------------------------------------------------------------Enumeration enumeration = parameterset.parametersNames(); Vector vParam = (Vector)parameterset.getParam("ITSO_LogfileLite_Pattern"); if(vParam == null) { trace.log(1, "ITSO_LogfileLiteIlt", "enumerateInstances: no parameters found"); return null; } // Process the ITSO_LogfileLite_FileName parameter. String asITSO_LogfileLite_Pattern[] = new String[vParam.size()]; for(int iIndex = 0; iIndex < vParam.size(); iIndex++) { // Get the string array element from the vector element. asITSO_LogfileLite_Pattern[iIndex] = (String)vParam.elementAt(iIndex); trace.log( 3, "ITSO_LogfileLiteIlt", "enumerateInstances: asITSO_LogfileLite_Pattern[" + iIndex + "] = " + asITSO_LogfileLite_Pattern[iIndex]); } M12IdentityElement m12identityelement = m12objectidentity.getScopingPath()[0]; M12PropertySet m12propertyset = m12identityelement.getIdentity(); // Determine which instance is being checked by the // Management Layer. String sKey = m12propertyset.getProperty("FileName"); trace.log(3, "ITSO_LogfileLiteIlt", "getProperty: called for FileName " + sKey);
388
// Get the attributes being checked by the Management Layer. // Get the current attribute values. String sValue = getITSOAttribute(sKey, sPropertyName, asITSO_LogfileLite_Pattern); trace.log(3, "ITSO_LogfileLiteIlt", "getITSOAttribute: " + sPropertyName + " = " + sValue); return sValue; } catch(Exception exception) { trace.exception("ITSO_LogfileLiteIlt", "getProperty", exception); M12Exception m12exception = new M12Exception(exception); throw m12exception; } }
//-------------------------------------------------------------------------// //getMultipleProperties // //Supported: YES // //Syntax: // public M12PropertySet getMultipleProperties( // M12ObjectIdentity targetInstance, // java.util.Vector propertyList, // java.lang.String mappingString, // ParameterSet parms ) // throws M12Exception // //Parameters: // targetInstance - M12ObjectIdentity that identifies the instance of the // resource to be accessed. // propertyList The list of properties whose value is required. // mappingString - Any string that has been specified in the // M12_Instrumentation qualifier for the GET operation // type for the class which the specified instance // belongs to. // parms A ParameterSet object filled by the client with // parameters associated to the class which the // specified instance belongs to. // //Description: // Gets the value (in String format) of the specified properties for the // identified object. // //Returns: // M12PropertySet - the values of the requested properties.
389
// //Exceptions Thrown: // M12Exception // //-------------------------------------------------------------------------public M12PropertySet getMultipleProperties( M12ObjectIdentity m12objectidentity, Vector vPropertyList, String sMapping, ParameterSet parameterset ) throws M12Exception { try { // Variable Declaration. StringBuffer stringbuffer = new StringBuffer(); Vector vector = new Vector();
//-----------------------------------------------------------------// Get the parameters of the patterns from the caller. //-----------------------------------------------------------------Enumeration enumeration = parameterset.parametersNames(); Vector vParam = (Vector)parameterset.getParam("ITSO_LogfileLite_Pattern"); if(vParam == null) { trace.log(1, "ITSO_LogfileLiteIlt", "enumerateInstances: no parameters found"); return null; } // Process the ITSO_LogfileLite_FileName parameter. String asITSO_LogfileLite_Pattern[] = new String[vParam.size()]; for(int iIndex = 0; iIndex < vParam.size(); iIndex++) { // Get the string array element from the vector element. asITSO_LogfileLite_Pattern[iIndex] = (String)vParam.elementAt(iIndex); trace.log( 3, "ITSO_LogfileLiteIlt", "enumerateInstances: asITSO_LogfileLite_Pattern[" + iIndex + "] = " + asITSO_LogfileLite_Pattern[iIndex]); } M12IdentityElement m12identityelement = m12objectidentity.getScopingPath()[0]; M12PropertySet m12propertyset = m12identityelement.getIdentity();
390
// Determine which instance is being checked by the // Management Layer. String sKey = m12propertyset.getProperty("FileName"); M12PropertySet m12propertyset1 = new M12PropertySet(); trace.log(3, "ITSO_LogfileLiteIlt", "getMultipleProperty: called for FileName " + sKey); for(int i = 0; i < vPropertyList.size(); i++) { // Get the property being checked by the Management Layer. String sProperty = (String)vPropertyList.elementAt(i); // Get the current attribute values. String sValue = getITSOAttribute(sKey, sProperty, asITSO_LogfileLite_Pattern ); m12propertyset1.setProperty(sProperty, sValue); } trace.log(3, "ITSO_LogfileLiteIlt", "getMultipleProperty: returning " + WriteBuffer(m12propertyset1)); return m12propertyset1; } catch(Exception exception) { trace.exception("ITSO_LogfileLiteIlt", "getMultipleProperty", exception); M12Exception m12exception = new M12Exception(exception); throw m12exception; } }
//-------------------------------------------------------------------------// //enumerateInstances // //Supported: YES // //Syntax: // public java.util.Enumeration enumerateInstances( // M12ClassPath classPath, // java.lang.String mappingString, // ParameterSet parms ) // throws M12Exception // //Parameters: // classPath The M12ClassPath identifying the class whose instances
391
// have to be enumerated. // mappingString - Any string that has been specified in the // M12_Instrumentation qualifier for the ENUM operation // type for this class. // parms A ParameterSet object filled by the client with // parameters for ILT. // //Description // Returns all M12ObjectIdentity objects that identify all the instances // belonging to the class specified in the classPath. // //Returns: // Enumeration of instances identity (M12ObjectIdentity). // //Exceptions Thrown: // M12Exception // //-------------------------------------------------------------------------public Enumeration enumerateInstances( M12ClassPath m12classpath, String sMapping, ParameterSet parameterset ) throws M12Exception { try { // Variable Declaration. StringBuffer stringbuffer = new StringBuffer(); Vector vector = new Vector();
//-----------------------------------------------------------------// Get the parameters from the caller. // We are obtaining the parameters prior to declaring instances so // we can configure an instance for each parameter. //-----------------------------------------------------------------Enumeration enumeration = parameterset.parametersNames(); Vector vParam = (Vector)parameterset.getParam("ITSO_LogfileLite_FileName"); if(vParam == null) { trace.log(1, "ITSO_LogfileLiteIlt", "enumerateInstances: no parameters found"); return null; } // Process the ITSO_LogfileLite_FileName parameter. String asITSOArrayGui[] = new String[vParam.size()];
392
for(int iIndex = 0; iIndex < vParam.size(); iIndex++) { // Get the string array element from the vector element. asITSOArrayGui[iIndex] = (String)vParam.elementAt(iIndex); trace.log( 3, "ITSO_LogfileLiteIlt", "enumerateInstances: asITSOArrayGui[" + iIndex + "] = " + asITSOArrayGui[iIndex]); }
//-----------------------------------------------------------------// Acquire a vector (pointer) from the calling ILT Manager. // This section handles the registration of instances of this // Instrumentation. //-----------------------------------------------------------------String aiInst[] = pitso_logfilelite.getITSO_Instances( asITSOArrayGui ); if(aiInst == null) { trace.log(1, "ITSO_LogfileLiteIlt", "enumerateInstances: no instances found"); return null; } for(int jIndex = 0; jIndex < aiInst.length; jIndex++) { trace.log( 3, "ITSO_LogfileLiteIlt", "enumerateInstances: aiInst[" + jIndex + "] = " + aiInst[jIndex]); M12PropertySet m12propertyset = new M12PropertySet(); m12propertyset.setProperty( "FileName", aiInst[jIndex] ); M12IdentityElement m12identityelement = new M12IdentityElement( m12classpath.getClassName(), m12classpath.getNameSpace(), m12propertyset); vector.add( new M12ObjectIdentity( new M12IdentityElement[] { m12identityelement } ) ); } return vector.elements(); } catch(Exception exception) { trace.exception("ITSO_LogfileLiteIlt", "enumerateInstances", exception); M12Exception m12exception = new M12Exception(exception); throw m12exception;
393
} }
//-------------------------------------------------------------------------// //setProperty // //Supported: NO // //Syntax: // public java.lang.String setProperty( M12ObjectIdentity targetInstance, // java.lang.String propertyName, // java.lang.String propertyValue, // java.lang.String mappingString, // ParameterSet parms ) // throws M12Exception // //Parameters: // targetInstance - M12ObjectIdentity that identifies the instance of the // resource to be accessed. // propertyName The property whose value is to be set. // propertyValue - The property value to be set. // mappingString - Any string that has been specified in the // M12_Instrumentation qualifier for the SET operation // type for this property. // parms A ParameterSet object filled by the client with // parameters associated to this property. // //Description: // Sets the value (in String format) of the specified property for the // identified object. // //Returns: // String - the new value of the specified property. // //Exceptions Thrown: // M12Exception // //-------------------------------------------------------------------------public String setProperty( M12ObjectIdentity m12objectidentity, String sName, String sValue, String sMapping, ParameterSet parameterset ) throws M12Exception { trace.log(3, "ITSO_LogfileLiteIlt", "setProperty: " +
394
"sName=" + sName + ", sValue=" + sValue + ", sMapping=" + sMapping ); return null; }
//-------------------------------------------------------------------------// //invokeMethod // //Supported: YES // //Syntax: // public java.lang.String invokeMethod( M12ClassPath classPath, // java.lang.String methodName, // java.lang.String mappingString, // ParameterSet parms, // ParameterSet inParms, // ParameterSet outParms ) // throws M12Exception // //Parameters: // classPath - The M12ClassPath that identifies the class // whose method has to be called. // methodName -The name of the method to be called. // mappingString -Any string that has been specified in the // M12_Instrumentation qualifier for the INVOKE // operation type for this method. // parms - A ParameterSet object filled by the client with // parameters for this method. // inParms -A ParameterSet object filled by the client with // parameters to be passed to the method. // outParms -A ParameterSet object created by the client and // filled by the method with output results. // //Description: // Invokes the specified method on the CIM instance belonging to // the class specified in the classPath. // //Returns: // String - The result of the method. Result values have to be CIM // standard types and ILT converts them to string format // according to the CIM standards. // //Exceptions Thrown: // M12Exception //
395
//-------------------------------------------------------------------------public String invokeMethod( M12ClassPath m12classpath, String sMethodName, String sMapping, ParameterSet parameterset, ParameterSet parameterset1, ParameterSet parameterset2 ) throws M12Exception { trace.log(3, "ITSO_LogfileLiteIlt", "invokeMethod(1): " + "sMethodName=" + sMethodName + ", sMapping=" + sMapping ); return null; }
//-------------------------------------------------------------------------// //invokeMethod // //Supported: YES // //Syntax: // public java.lang.String invokeMethod( M12ObjectIdentity targetInstance, // java.lang.String methodName, // java.lang.String mappingString, // ParameterSet parms, // ParameterSet inParms, // ParameterSet outParms) // throws M12Exception // //Parameters: // targetInstance - M12ObjectIdentity that identifies the instance // whose method has to be called. // methodName - The name of the method to be called. // mappingString - Any string that has been specified in the // M12_Instrumentation qualifier for the INVOKE // operation type for this method. // parms -A ParameterSet object filled by the client with // parameters for this method. // inParms -A ParameterSet object filled by the client with // parameters to be passed to the method. // outParms A ParameterSet object created by the client and // filled by the method with output results. // //Description: // Invokes the specified method on the identified CIM instance.
396
// //Returns: // String - The result of the method. Result values have to be CIM // standard types and ILT converts them to string format // according to the CIM standards. // //Exceptions Thrown: // M12Exception // //-------------------------------------------------------------------------public String invokeMethod( M12ObjectIdentity m12objectidentity, String sMethodName, String sMapping, ParameterSet parameterset, ParameterSet parameterset1, ParameterSet parameterset2 ) throws M12Exception { trace.log(3, "ITSO_LogfileLiteIlt", "invokeMethod(2): " + "sMethodName=" + sMethodName + ", sMapping=" + sMapping ); return null; }
//-------------------------------------------------------------------------// //create // //Supported: NO // //Syntax: // public void create( M12ObjectIdentity targetInstance, // java.lang.String mappingString, // ParameterSet parms ) // throws M12Exception // //Parameters: // targetInstance - M12ObjectIdentity that identifies the instance // of the resource to be created. // mappingString - Any string that has been specified in the // M12_Instrumentation qualifier for the CREATE // operation type for the class whose instance to // be created will belong to. // parms - A ParameterSet object filled by the client // with parameters for the ILT. //
397
//Description // Creates an instance of the resource that will be identified by // the specified targetInstance. // //Returns: // void // //Exceptions Thrown: // M12Exception // //-------------------------------------------------------------------------public void create( M12ObjectIdentity m12objectidentity, String sMapping, ParameterSet parameterset ) throws M12Exception { trace.log(3, "ITSO_LogfileLiteIlt", "create: sMapping=" + sMapping ); }
//-------------------------------------------------------------------------// //destroy // //Supported: NO // //Syntax: // public void destroy( M12ObjectIdentity targetInstance, // java.lang.String mappingString, // ParameterSet parms ) // throws M12Exception // //Parameters : // targetInstance - M12ObjectIdentity that identifies the instance // of the resource to be deleted. // mappingString -Any string that has been specified in the // M12_Instrumentation qualifier for the CREATE // operation type for the class whose instance to // be deleted belongs to. // parms - A ParameterSet object filled by the client // with parameters for the ILT. // //Description: // Deletes an instance of the resource identified by the specified // targetInstance. // //Returns:
398
// void // //Exceptions Thrown: // M12Exception // //-------------------------------------------------------------------------public void destroy( M12ObjectIdentity m12objectidentity, String sMapping, ParameterSet parameterset ) throws M12Exception { trace.log(3, "ITSO_LogfileLiteIlt", "destroy: sMapping=" + sMapping ); }
//-------------------------------------------------------------------------// // Custom Class Methods // // The following methods are custom methods created to provide better // programatic structure. // //--------------------------------------------------------------------------
//-------------------------------------------------------------------------// // GetAttributeTypes // // This method is internal to the class and is designed to segregate the // ILT Operations from our own supporting methods. It is simply to provide // cleaner & easier to maintain code. // //-------------------------------------------------------------------------private String getITSOAttribute( String sValue, String sProperty, String asITSO_LogfileLite_Pattern[] ) throws Exception { //---------------------------------------------------------------------// Return the EventNum value //---------------------------------------------------------------------if( (sProperty.equals("EventNum"))) { String offset = "-1"; int r = 0;
399
// Retrieve the offset value for the filename from the offsetarray // hashtable. If the offsetarray doesn't have the appropriate offset, // assign "-1" to the offset variable and keep it in the offsetarray. String v = (String)offsetarray.get(sValue); if ( v == null ) { offset = "-1"; offsetarray.put(sValue, offset); } else { offset = v; } // Run the getITSO_LogfileLiteVar_EventNum() and assign the result // to the intVar[] array. // intVar[] = { EventNum, offset } int intVar[] = pitso_logfilelite.getITSO_LogfileLiteVar_EventNum(sValue, asITSO_LogfileLite_Pattern, offset); // Keep the new offset value in the offsetarray hashtable. offsetarray.put(sValue, String.valueOf(intVar[1])); // Trace trace.log( 3, "ITSO_LogfileLiteIlt", "getITSOAttribute result offset" + intVar[1] + " EventNum = " + intVar[0] + " FileName = " + sValue); trace.log( 3, "ITSO_LogfileLiteIlt", "global array: offset" + (String)offsetarray.get(sValue)); // Return the EventNum value. return String.valueOf(intVar[0]); } //---------------------------------------------------------------------// Return the FileName value //---------------------------------------------------------------------if( (sProperty.equals("FileName"))) { return sValue; } //---------------------------------------------------------------------// Unknown property.
400
//---------------------------------------------------------------------else { throw new Exception(sProperty + ": unknown property"); } }
//-------------------------------------------------------------------------// // WriteBuffer // // This method is internal to the class and is designed to write the // variable returned from the ILT Operations to the output string. It is // strictly to support better logging. // //-------------------------------------------------------------------------private String WriteBuffer( M12PropertySet m12propertyset ) { Enumeration enumeration = m12propertyset.propertyNames(); StringBuffer stringbuffer = new StringBuffer(); String sElement; String sProperty; for(; enumeration.hasMoreElements(); stringbuffer.append(sElement + " = " + sProperty + " ")) { sElement = (String)enumeration.nextElement(); sProperty = m12propertyset.getProperty(sElement); } return stringbuffer.toString(); } }
9.3.4 ITSO_LogfileLite.java
The Provider Java class code used for the ITSO_LogfileLite Resource Model is shown in its entirety in Example 9-27.
Example 9-27 ITSO_LogfileLite Provider Java class
//----------------------------------------------------------------------------// // ITSO_LogfileLite.java // // Description: // This file is the ITSO_LogfileLite Provider to the ILT. This can perform the
401
// actual the actual data acquisition, call other classes, or via JNI // perform calls to "native" binaries. // //----------------------------------------------------------------------------package com.ibm.tivoli.monitoring.ITSO_LogfileLite; // Part of the ILT package. import import import import import com.tivoli.javautils.Trace; // "javautils.jar" gnu.regexp.*; // GNU REGEXP package java.lang.*; // Java Class java.util.*; // Java Class java.io.*; // Java Class
public class ITSO_LogfileLite { // Declare local members. private Trace trace; private Map ITSO_LogfileLiteMap;
//-------------------------------------------------------------------------// ITSO_LogfileLite class - Creator method. //-------------------------------------------------------------------------public ITSO_LogfileLite() { trace = Trace.getTraceInstance(); }
//-------------------------------------------------------------------------// ITSO_LogfileLite - This method should configure an instance for each item in // the array. //-------------------------------------------------------------------------public synchronized String[] getITSO_Instances( String asParams[] ) { // The instances will be referenced by the FileName. trace.log(3, "ITSO_LogfileLite", "getITSO_Instances asParams.length=" + asParams.length); String[] aiInst = new String[asParams.length]; for(int iIndex = 0; iIndex < asParams.length; iIndex++) { // Get the string array element from the vector element.
402
trace.log(3, "ITSO_LogfileLite", "getITSO_Instances iIndex=" + iIndex); aiInst[iIndex] = asParams[iIndex]; trace.log(3, "ITSO_LogfileLite", "getITSO_Instances aiInst[" + iIndex + "]" + aiInst[iIndex]); } return aiInst; } //---------------------------------------------------------------------// getITSO_LogfileLiteVar_EventNum //---------------------------------------------------------------------public static synchronized int[] getITSO_LogfileLiteVar_EventNum( String i, String as[], String offset ) { // retrieve pattern(); int c = 0; int c1 = 0; int c2 = 0; int obj = 0; int lastline; int[] retarray = new int[2]; try { RE re = null; REMatch mat; String sl = offset; // offSet = retrieve offSet(i);
// Create a FileReader object FileReader fr = new FileReader(i); BufferedReader br = new BufferedReader(fr); LineNumberReader lr = new LineNumberReader(fr); // Read strings in the file String line; while((line = lr.readLine()) != null) { for(int iIndex = 0; iIndex < as.length; iIndex++) { // Compile the string for the pattern matching try { re = new RE(as[iIndex]); } catch (REException e) { break;
403
} Integer tmp = Integer.valueOf(sl); obj = tmp.intValue(); // Pattern match mat = re.getMatch(line); if (mat != null) { if (obj > lr.getLineNumber()) { c1++; // Increase the counter older than the offset } else { c2++; // Increase the counter newer than the offset } } } } // Store the lastline number lastline = lr.getLineNumber(); // Close the FileReader object fr.close(); if ( offset == "-1" ) { first time. retarray[0] = 0 ; // If the offset is "-1", this is the // Discards the result and // returns "0" as the EventNum.
retarray[1] = lastline ; } else { if ( lastline < obj ) { // If the lastline is lower than offset, the file was initialized. retarray[0] = c1; // Returns the c1 value which is the counter older than offset retarray[1] = lastline; } else { // If lastline is upper than offset, retarray[0] = c2; // returns the c2 value which is the counter newer than offset retarray[1] = lastline; } } } catch (Exception e) { ; }
404
return retarray; } }
9.3.5 ITSO_LogfileLite_RM.js
The decision tree script code used for the ITSO_LogfileLite Resource Model is shown in its entirety in Example 9-28.
Example 9-28 ITSO_LogfileLite decision tree script
//''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' '''''''''''''''''''''''''''''''''''''''' // IBM Tivoli Monitoring // Decision Tree script // // 03/26/2003 15:54:41 //''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' '''''''''''''''''''''''''''''''''''''''
// This function is used to define the settings of the Resource Model // It is called only once, when the Resource Model is started. // Don't modify remarks containing tags like <<....>> ... <<\...>> // You can write additional initializing code in this function if required. function SetDefaultConfiguration (Svc) { Svc.Trace (0, "ITSO_LogfileLite: SetDefaultConfiguration - start" ); // General info section //<<GENERAL_INFO>> Svc.SetModelName ("ITSO_LogfileLite_RM"); Svc.SetProfileName ("167475453"); Svc.SetCycleTime (60); //<<\GENERAL_INFO>> // Thresholds section //<<THRESHOLDS_INFO>> Svc.DefineThreshold ("Thr_EventNum_gt", 3.000000); //<<\THRESHOLDS_INFO>> // Parameters section //<<PARAMETERS_INFO>> Svc.DefineStrParameter ("ITSO_LogfileLite_Pattern", "aaa"); Svc.DefineStrParameter ("ITSO_LogfileLite_FileName", "/tmp/log1.log"); //<<\PARAMETERS_INFO>>
405
// Note:In the DefineClass method, we create an ALIAS of "ITSO_LogfileLite" to the actual CIM Namespace declaration for our class. // This will be referenced by the AssociateParameterToClass method later. // // Dynamic Model section //<<DATA_INFO>> Svc.DefineClass ("CIM", "ITSO_LogfileLite", "ROOT\\CIMV2:ITSO_LogfileLite", "", "EventNum", "FileName", "None", "", 0, 1); //<<\DATA_INFO>> // Event definition section //<<EVENTS_INFO>> Svc.DefineEvent ("ITSO_LogfileLite_EventNum_too_high", "EventNum,UpperBound", "FileName"); //<<\EVENTS_INFO>> // Logging definition section //<<LOGGING_INFO>> //<<\LOGGING_INFO>> // Place your additional intializing code below Svc.Trace (0, "ITSO_LogfileLite: SetDefaultConfiguration - end" ); return (0); }
// This function is called by the DM For Windows Analyzer after that // the Resource Model default settings have been overridden // It is called only once, when the Resource Model is started. // You can write additional initializing code in this function if required // to use the thresholds and parameters values function Init(Svc) { // Logging Svc.Trace (0, "ITSO_LogfileLite: Init - start" ); // Variable Initialization var dimension = 0; var t=0; // Process the parameter lists. // (2) Have been implemented to show various methods of use. // - ITSO_StringListGUI is an RM Parameter made available to the Tivoli Admins via the Desktop. // dimension= Svc.GetStrParameterCount("ITSO_LogfileLite_FileName"); if (dimension > 0 )
406
{ Svc.Trace (0, "ITSO_LogfileLite: Init - dimension =" + dimension); // Note:This is the reference to the alias "ITSO_LogfileLite" created in the DefineClass method. // Svc.AssociateParameterToClass ("ITSO_LogfileLite_FileName","ITSO_LogfileLite"); } else { Svc.Trace (0, "ITSO_LogfileLite: ITSO_LogfileLite_FileName parameter is empty"); return(801);// Return an error if the Resource Model is dependant on the paramater to function. } // Process the parameter lists. // - ITSO_StringListGUI is an RM Parameter made available to the Tivoli Admins via the Desktop. // dimension= Svc.GetStrParameterCount("ITSO_LogfileLite_Pattern"); if (dimension > 0 ) { Svc.Trace (0, "ITSO_LogfileLite: Init - dimension =" + dimension); // Note:This is the reference to the alias "ITSO_LogfileLite" created in the DefineClass method. // Svc.AssociateParameterToClass ("ITSO_LogfileLite_Pattern","ITSO_LogfileLite"); } else { Svc.Trace (0, "ITSO_LogfileLite: ITSO_LogfileLite_FileName parameter is empty"); return(802);// Return an error if the Resource Model is dependant on the paramater to function. } Svc.Trace (0, "ITSO_LogfileLite: Init - end" ); return (0); }
// This function contains the monitoring algorithm // It is called ciclically after a cycle time has elapsed // Implement the the monitoring code here
407
function VisitTree(Svc) { // Variable Declaration var curEventNum; var curFileName; var var var var var hPropTable; iParameterCount; iInstanceCount; idx; sTraceOut;
hPropTable = Svc.CreateMap(); // iParameterCount= Svc.GetStrParameterCount("ITSO_LogfileLite_FileName"); Svc.Trace(0,"ITSO_LogfileLite: VisitTree: iParameterCount = " + iParameterCount ); // iInstanceCount = Svc.GetNumOfInst("ITSO_LogfileLite"); Svc.Trace(0,"ITSO_LogfileLite: VisitTree: iInstanceCount = "+ iInstanceCount ); for ( idx = 0; idx < iInstanceCount; idx++) { // Variable type demonstration:Signed Integer 32 curEventNum = Svc.GetNumProperty("ITSO_LogfileLite", idx, "EventNum"); sTraceOut = "GetNumProperty: curEventNum = " + curEventNum ; Svc.Trace( 0, sTraceOut ); curFileName = Svc.GetStrProperty("ITSO_LogfileLite", idx, "FileName"); sTraceOut = "GetStrProperty: FileName = " + curFileName ; Svc.Trace( 0, sTraceOut ); if (curEventNum > Svc.GetThreshold("Thr_EventNum_gt") ) { Svc.SetMapNumElement(hPropTable,"UpperBound",Svc.GetThreshold("Thr_EventNum_gt" )); Svc.SetMapNumElement(hPropTable,"EventNum",curEventNum ); Svc.SetMapStrElement(hPropTable,"FileName",curFileName ); Svc.SendEventEx ("ITSO_LogfileLite_EventNum_too_high",hPropTable); } } Svc.DestroyMap(hPropTable); return (0);
408
409
410
10
Chapter 10.
Creating a custom script Resource Model

IBM Tivoli Monitoring Version 5.1.1 Workbench provides a way to create a custom script Resource Model within the Workbench wizard. The custom script Resource Model monitors a result generated by a custom script that you create. If you have a monitoring script, you can easily import it into your Resource Model. The custom script Resource Model is one of the easiest ways to integrate IBM Tivoli Monitoring Version 5.1.1 with managed resources that are not supported by default Resource Models. This chapter describes example procedures to create a custom script Resource Model by using the Workbench wizard. As an example, we create a Resource Model that monitors the number of the specified processes running on the system. In addition, this chapter describes how you can add the function to utilize multiple levels of thresholds and how you can make your Resource Model parametric. This chapter describes the following topics: Designing the ITSO_ProcessNum Resource Model Creating a custom script Resource Model ITSO_ProcessNum source code
411
10.1 Designing the ITSO_ProcessNum Resource Model

Let us explain the overview of the ITSO_ProcessNum custom script Resource Model, which we will create in this chapter. The process monitoring is one of the most popular monitoring functions in the availability management area. Though IBM Tivoli Monitoring Version 5.1.1 provides the process monitoring function, we found the monitoring function for the number of the process is not provided by the current IBM Tivoli Monitoring Version 5.1.1. When you monitor an application that has multiple process instances on a system, such as httpd, you should monitor the number of the process rather than monitor the up or down of the process. Therefore, we choose the number of instances of a specific process to be monitored as a scenario in order to show you the basic procedures needed to create a custom script Resource Model.

The ITSO_ProcessNum Resource Model periodically executes a script that monitors the number of instances of a specific process. When the number of instances of the process becomes higher or lower than the threshold that you specified in advance, the ITSO_ProcessNum Resource Model generates the appropriate event. The overview of ITSO_ProcessNum Resource Model is shown in Figure 10-1.
Monitored Server ProcessNum RM

script ITM engine Endpoint
httpd httpd httpd httpd
Figure 10-1 Design overview of ITSO_ProcessNum Resource Model

This example uses the white part of the ITM Engine shown in Figure 10-2 on page 413. This example uses custom scripts to retrieve the data from the resource.
412

Custom Scripts
ILT Providers
Resource
Resource
Resource
Figure 10-2 ITM Engine Logical Components
10.1.3 The detailed design of the ITSO_ProcessNum Resource Model

Before you create a Resource Model, we recommend that you have a clear idea of your design. For example, let us describe the detailed design of the ITSO_ProcessNum Resource Model.
External design
First, we define the parameters and the thresholds as external inputs of the Resource Model, as shown in Table 10-1 on page 414 and Table 10-2 on page 414. The ITSO_ProcessNum Resource Model receives multiple process names as parameters and monitors them. The ITSO_ProcessNum Resource Model also utilizes multiple levels of thresholds. You can change values of parameters and thresholds when distributing your profile.
Chapter 10. Creating a custom script Resource Model
413
Table 10-1 The parameter

Parameter Default
Process Name (STRING TYPE)
httpd

Indications Default
The number of the process becomes very high The number of the process becomes high The number of the process becomes low
> 10 >5 <2
Internal design
To create the Resource Model smoothly, we recommend that you make a list of the elements of your Resource Model, as shown in Table 10-3.
Table 10-3 A list of elements of the ITSO_ProcessNum Resource Model
Elements Contents
Internal Name Descriptive Name Category Internal Name Category Descriptive Name Dynamic Model Events
ITSO_ProcessNum Process number ITSO_RMs ITSO Resource Models none Ev_process_num_becomes_very_high Ev_process_num_becomes_high Ev_process_num_becomes_low Thr_process_num_becomes_very_high Thr_process_num_becomes_high Thr_process_num_becomes_low Param_proc_name none process_num.sh
Thresholds
Parameters Logging Dependency
Defining the algorithm

To write the decision tree script, we recommend you start by drawing a flowchart that shows how the algorithm works, as shown in Figure 10-3 on page 415.
414
Start Read parameters into array and set i to 0
Read array(i) Run process_num.sh script
Is the result very high?
No Is the result high? Yes
Yes Send event
Send event No
Is the result low? Yes Send event
No Log i++
Last parameter?
End
Figure 10-3 Flowchart of ITSO_ProcessNum Resource Model
415
10.2 Creating a custom script Resource Model

As described in Chapter 2, Workbench on page 25, we recommend that you use the Workbench wizard to create a template of your Resource Model. Then you can modify it and make it more suitable for your environment. We discuss how to create the ITSO_LogfileLite ILT/Resource Model with the following procedures. 1. Using the wizard to create a custom script Resource Model 2. Extending the functions of the Resource Model 3. Packaging 4. Testing the Resource Model
10.2.1 Using the wizard to create a custom script Resource Model

1. Preparing the script First, you need to write a custom script on the monitored system. We create a sample script for ITSO_ProcessNum Resource Model, as shown in Example 10-1. The custom script Resource Model checks the standard output from your custom script. Therefore, the custom script must print its result to standard output.
Example 10-1 process_num.ksh
#!/bin/ksh PROCESS_NAME=$1 ps -A -o "args"|grep -v grep|grep -v $0|grep "$PROCESS_NAME"|wc -l
Note: The custom script runs on the shell environment with variables defined by the lcfd_env.sh, such as LCFROOT, LCF_TEMPDIR, and so on. Instead of writing the special file name or directory name in the script, you may want to use these variables to make your custom script widely usable.
After you finish writing the script, make sure it works in a stand-alone environment, and then copy the script to your PC where you will use the Workbench.
Example 10-2 Running process_num.sh
root@pacs007[/work/itso] process_num.ksh 7 httpd
416
Note: If you select FTP to copy a script from the UNIX machine to the Windows PC where you use Workbench, use the binary mode to keep the original new line code of a script. If you changed the script on your PC, the new line code will be changed to the CR/LF, which is used in the Windows environment. If this happens, you can convert the new line code from the CR/LF to the LF. The bash and tr commands are included in the bin directory of the Workbench. Do the following:
bash tr -d \015 < input_filename > output_filename cp output_filename input_filename
2. Using the wizard Now you have a custom script in your PC. You can import it into your Resource Model by using the Workbench wizard. Let us begin by clicking on the New icon in the left side of the Workbench toolbar, as shown in Figure 10-4
Figure 10-4 Creating a new ITM Workbench project
In the next window, we choose the Resource Model Wizard and the JavaScript Resource Model. Then you have the window to choose the data source, as shown in Figure 10-5 on page 418. Select the Custom Script and supported platforms. In this example, we choose aix4-r1 and linux-ix86 as supported platforms, which are running in our environment.
417
Figure 10-5 Selecting data source
The next window (Figure 10-6 on page 419) prompts you to import your custom script. Click on the Browse button to select your own script. In addition to the script, you are able to specify arguments in the Shell command input area. We specify httpd as an argument here. Later, we will modify the Resource Model and make this argument parametric. As a script type, we select NUMERIC, because our script returns a numeric variable, which is the number of the process.
418
Figure 10-6 Importing the custom script
In the next window, you can specify the trigger condition of the event. We enter a trigger condition, as shown in Figure 10-7 on page 420. This means the event will be generated when the number of the process becomes greater than five. We will add two more event trigger conditions in 10.2.2, Extending the functions of the Resource Model on page 421.
419
Figure 10-7 Trigger condition
In the next window (Figure 10-8 on page 421), you can specify the properties to be logged. When using a custom script Resource Model, the only property you can choose here is the ScriptResult. No properties are logged in this scenario. At the end of the wizard, the Workbench prompts you to set the default cycle time. After that, you complete the wizard and create a template of your custom script Resource Model. We recommend that you should save the file before proceeding to the next step.
420
Figure 10-8 Saving the Resource Model file
10.2.2 Extending the functions of the Resource Model

You now have a basic template of the ITSO_ProcessNum Resource Model. With further procedures, you can make your ITSO_ProcessNum Resource Model more useful. 1. Changing properties The wizard sets the default property of the Resource Model. You can change it by double-clicking on the thermometer icon in the left side of the Workbench, as shown in Figure 10-9 on page 422.
421
Figure 10-9 ITM Workbench thermometer icon
In the next window, you can change the property of the Resource Model. Referring to the list in Table 10-3 on page 414, we set the properties as shown in Figure 10-10 on page 423.
422
Figure 10-10 Changing properties
2. Modifying and adding events The wizard creates an event using the default naming rule, such as Ev_process_num_ksh_httpd_ScriptResult_too_high, shown in this example. In this step, we change the default setting of the event and add two more events. Because you need to input a number of attributes in the event setting, we recommend that you prepare lists of the event setting, as shown in Table 10-4 on page 425, Table 10-5 on page 426, and Table 10-6 on page 426, in advance. First, double-click the Ev_process_num_ksh_httpd_ScriptResult_too_high icon under the Events icon, as shown in Figure 10-11 on page 424.
423
Figure 10-11 Opening the event setting
In the next window, we change the event setting, as shown in Figure 10-12 on page 425. To add more events, double-click on the Events icon in the left side of the Workbench. You will see a empty dialog box where you can input a new event setting.
424
Figure 10-12 Changing the event setting
Note: The ITM Engine will distinguish events by the key attribute. To distinguish events by the process name, we choose the Param_proc_name as a key attribute.
Table 10-4 The event of Ev_process_num_becomes_very_high
Elements Contents
Ev_process_num_becomes_very_high. NUMERIC: ScriptResult, UpperBound_veryhigh STRING: prev_value, value, relation_delta, Param_proc_name. Param_proc_name. Yes. 1 / 0. Yes. CRITICAL.
425
Elements
Contents
String Resources
The number of the process becomes very high. The number of the process becomes very high: Process name is @Param_proc_name@: Process number is @ScriptResult@ and greater than @UpperBound_veryhigh@.
Table 10-5 The event of Ev_process_num_becomes_high

Elements Contents
Internal Name Attributes Aggregation Setting Keys Clearing Event Occurrence/Hole Notification Send to TEC/TBSM Severity String Resources Descriptive Name Message
Ev_process_num_becomes_high. NUMERIC: ScriptResult, UpperBound_high STRING: prev_value, value, relation_delta, Param_proc_name. Param_proc_name. Yes. 1 / 0. Yes / Yes. WARNING. The number of the process becomes high. The number of the process becomes high: Process name is @Param_proc_name@: Process number is @ScriptResult@ and greater than @UpperBound_high@.
Table 10-6 The event definition for Ev_process_num_becomes_low

Elements Contents
Ev_process_num_becomes_low. NUMERIC: ScriptResult, LowerBound_low STRING: prev_value, value, relation_delta, Param_proc_name. Param_proc_name. Yes. 1 / 0. Yes / Yes. CRITICAL.
426
Elements
Contents
String Resources
The number of the process becomes low. The number of the process becomes low: Process name is @Param_proc_name@: Process number is @ScriptResult@ and less than @LowerBound_low@.
3. Adding thresholds The wizard creates only one threshold using the default naming rule. In this step, we change the default setting of the threshold and add two more thresholds. At this time, we also recommend that you prepare lists of the threshold setting, as shown in Table 10-7, Table 10-8 on page 428, and Table 10-9 on page 428 in advance. Double-click the Thr_ScriptResult_gt icon under the Thresholds icon. In the next window, we change the threshold setting as shown in Figure 10-13. To add more thresholds, double-click on the Thresholds icon in the left side of the Workbench. Then you will see an empty dialog box into which you can enter a new threshold setting.
Figure 10-13 Changing the threshold setting Table 10-7 The threshold definition for Ev_process_num_becomes_veryhigh
Elements Value
Thr_process_num_becomes_very_high Threshold for very high 10 Threshold for very high
427
Table 10-8 The threshold definition for Ev_process_num_becomes_high

Elements Value
Thr_process_num_becomes_high Threshold for high 5 Threshold for high
Table 10-9 The threshold definition for Ev_process_num_becomes_low

Elements Value
Thr_process_num_becomes_low Threshold for low 2 Threshold for low
4. Adding parameter The wizard does not create any parameters when creating the custom script Resource Model. We add a parameter that indicates the process name. We choose the STRING TYPE to monitor multiple processes by the ITSO_ProcessNum Resource Model. You can add a parameter by double-clicking on the Parameters icon in the left side of the Workbench.
Figure 10-14 Adding the parameter
When you use the list type of the parameter, you need to create a loop in the decision tree script to handle multiple parameters. In the next topic, we will discuss this.
428
5. Editing the decision tree script To implement the monitoring algorithm, we edit the decision tree script as shown in Example 10-3 on page 430. Let us explain the important part of our modification in the decision tree script. We use limited methods in this decision tree script. For more information about the Object Method Library, see Appendix A, Service Object Method Library, in the IBM Tivoli Monitoring Workbench Users Guide Version 5.1.1, SH19-4571. a. Line 14 to 16: Define additional variables We define additional variables used in further steps. In fact, you can use additional variables without defining them. However, we recommend that you define variables explicitly. b. Line 18: Count the number of parameters Using GetStrParameterCount(), we calculate the number of parameters to decide how many times we execute the loop. c. Line 23,24 and Line 73,74: Start the loop/End the loop We create a loop that handles each parameter one by one. d. Line 26: Get the parameter We get the value of the parameter by using the GetStrParameter() method. e. Line 32: Set the loop ID to hashkey We set the loop ID to the hashkey variable. This decision tree script uses the hashkey to determine the previous result of the script. We intend to distinguish the result by the loop ID. f. Line 35: Modify the argument for the custom script Using the value of the parameter, we set the argument for the custom script. To insert a blank space between the script and the variable, insert a blank space after the script name:
Shell ("process_num.ksh "+ParamTmp) _ ___________________^____________
If you would like to check the return code of the script, use the GetShellRetCode method, which gives the return code of the script.
429
Note: The Shell() method executes a script and puts the result into a variable. The Svc.Shell method will only return one line of standard output. There is a difference in the behavior between the UNIX and Windows platforms in regards to the Svc.Shell method when we tested it.
Windows Any process launched via this method has a 60-second time limit. If the process does not terminate, it is killed. If the launched process results in a non-zero return code or empty output, the Resource Model is stopped and put into error status. This will be changed in a future release or patched to mimic the behavior on the UNIX platform. UNIX Processes launched via this method have no time limit. A hung or looping process could cause the entire Resource Model to hang. If the launched process results in a non-zero return code or empty output, the Resource Model continues running. g. Line 50 to 54: Put variables into hPropTable We put the values of the parameters and the thresholds into the hPropTable map table. Later, we will use the hPropTable map table and its attributes in the SendEventEx(). h. Line 56 to 68: Check the thresholds We compare the script result and three thresholds using multiple if statements. Generally, if Ev_process_num_becomes_very_high occurs, Ev_process_num_becomes_high also occurs. To avoid two events in this situation, we structure if statements to check Thr_process_num_becomes_high only when the process number is not exceeding the Thr_process_num_becomes_very_high.
Example 10-3 The decision tree script of the ITSO_ProcessNum
1: 2: 3: 4: 5: 6: 7: function VisitTree(Svc) { var curScriptResult; var hashKey; var found; var OldScriptResult; var hPropTable;
430
8: var ProbeArgCount; 9: var ProbeArgIdx; 10: var ParamCount; 11: var ParamIdx; 12: var Different; 13: 14: //Define additional parameters 15: var NumOfParam; 16: var ParamTmp; 17: 18: //Count the number of parameters 19: NumOfParam = Svc.GetStrParameterCount("Param_proc_name"); 20: 21: hPropTable = Svc.CreateMap(); 22: 23: //Start the loop 24: for (i = 0; i < NumOfParam ; i++) { 25: 26: //Get the parameter 27: ParamTmp = Svc.GetStrParameter("Param_proc_name",i); 28: 29: //Implementation for the monitor ScriptResult 30: Svc.RemoveMapAll(hPropTable); 31: 32: //Set the loop id to hashkey 33: hashKey = i ; 34: 35: //Modify the argument for the custom script 36: curScriptResult = Svc.Shell ("process_num.ksh "+ParamTmp); 37: 38: Svc.SetMapNumElement(hPropTable,"ScriptResult",curScriptResult); 39: found = Svc.ExistsMapElement(hTableScriptResult, hashKey); 40: if (found) 41: OldScriptResult = Svc.GetMapNumValue(hTableScriptResult, hashKey); 42: else 43: OldScriptResult = 0; 44: 45: Svc.SetMapNumElement(hPropTable,"OldScriptResult",OldScriptResult); 46: Svc.SetMapStrElement(hPropTable,"prev_value", OldScriptResult); 47: Svc.SetMapStrElement(hPropTable,"value", curScriptResult); 48: Svc.SetMapStrElement(hPropTable,"relation_delta", OldScriptResult curScriptResult); 49: 50: //Put variables to hPropTable 51: Svc.SetMapStrElement(hPropTable,"Param_proc_name",ParamTmp); 52: Svc.SetMapNumElement(hPropTable,"UpperBound_veryhigh",Svc.GetThreshold("Thr_pro cess_num_becomes_very_high"));
431
53: Svc.SetMapNumElement(hPropTable,"UpperBound_high",Svc.GetThreshold("Thr_process _num_becomes_high")); 54: Svc.SetMapNumElement(hPropTable,"LowerBound_low",Svc.GetThreshold("Thr_process_ num_becomes_low")); 55: 56: //Check the thresholds 57: if (curScriptResult > Svc.GetThreshold("Thr_process_num_becomes_very_high") ) { 58: Svc.SendEventEx ("Ev_process_num_becomes_very_high",hPropTable); 59: } 60: else { 61: if (curScriptResult > Svc.GetThreshold("Thr_process_num_becomes_high") ) { 62: Svc.SendEventEx ("Ev_process_num_becomes_high",hPropTable); 63: } 64: } 65: 66: if (curScriptResult < Svc.GetThreshold("Thr_process_num_becomes_low") ) { 67: Svc.SendEventEx ("Ev_process_num_becomes_low",hPropTable); 68: } 69: 70: Svc.SetMapStrElement(hPropTable,"key", "@"); 71: Svc.SetMapNumElement(hTableScriptResult, hashKey, curScriptResult); 72: 73: // End of the loop 74: } 75: 76: Svc.DestroyMap(hPropTable); 77: 78: return (0); 79: 80: }
10.2.3 Packaging
The various components discussed within this chapter must be packaged into a Resource Model tar file by building with the Workbench. The Resource Model Tar File relationship diagram in Figure 10-15 on page 433 shows all the components of a typical Resource Model, with those not used within the ITSO_ProcessNum presented in light gray to de-emphasize their significance.
432

Configuration File Logging: Parameter(s):
Param_proc_name
Dynamic Model(s): none
Action(s): Threshold(s):
Thr_process_num_becomes_very_high Thr_process_num_becomes_high Thr_process_num_becomes_low
Event(s):
Ev_process_num_becomes_very_high Ev_process_num_becomes_high Ev_process_num_becomes_low
Reference Model Functions: ITSO_ProcessNum.js
Message Catalogs
Provider(s):
MOF(s):
Custom Scripts() process_num.sh
Custom Files(s) Dependencies Files
Figure 10-15 Packaging
Copy the package file to the TMR Server and register it to IBM Tivoli Monitoring Version 5.1.1, as shown in Example 10-4.
# wdmrm -add ITSO_ProcessNum.tar IBM Tivoli Monitoring - Adding new Resource Model Copying ITSO_ProcessNum.cat msgfile ... Copying ITSO_ProcessNum.cat zipfile ... IBM Tivoli Monitoring - Resource Model utility Parsing configuration file ITSO_ProcessNum.conf ... Configuration file successfully parsed. Checking for event redefinition... Starting resource ITSO_ProcessNum registration ... the resource ITSO_ProcessNum has been successfully stored. Registration completed. Installation completed.
433

You have now completed creating the ITSO_ProcessNum Resource Model. We can proceed to the testing phase. In this section, we describe how to test the Resource Model.
Setting up the environment

To test the Resource Model, we installed the IBM HTTP Server as the monitored process. You can easily control the number of the child processes of the IBM HTTP Server, which is httpd, by editing the httpd.conf file.
Distributing the profile

After the JRE setting is done, you can distribute the profile, including the ITSO_ProcessNum Resource Model. Let us explain what the profile setting of the ITSO_ProcessNum Resource Model looks like. Category and Resource Model When adding the Resource Model to the profile, The profile view of the ITSO_ProcessNum Resource Model is shown in Figure 10-16 on page 435. You can see the category name and Resource Models. The thresholds and cycle time are also displayed here. Both of them are editable.
434
Figure 10-16 Category and Resource Model
Parameters Click the Parameter button, as shown in Figure 10-16. You can see a parameter, Param_proc_name, in the ITSO_ProcessNum Resource Model. Param_proc_name Enter the process names you want to monitor with the same format that the output of the ps -A -o args command uses. For example, you can specify httpd (Figure 10-17 on page 436) or java -classpath /usr/lib.
435
Figure 10-17 Parameter of the ITSO_ProcessNum
Events Click the Indications button, as shown in Figure 10-16 on page 435. You can see the event definition, as shown in Figure 10-18 on page 437.
436
Figure 10-18 Event I of the ITSO_ProcessNum
Testing the ITSO_ProcessNum Resource Model

In this section, we describe how to test the ITSO_ProcessNum Resource Model. Set the parameter and the threshold as follows and distribute the profile to your endpoint: Parameter: Param_proc_name: http Threshold: Thr_process_num_becomes_very_high: 10 Threshold: Thr_process_num_becomes_high: 5 Threshold: Thr_process_num_becomes_low: 2 Check out how the ITSO_ProcessNum Resource Model works on the above setting.
437
Checking the distributed files After a successful distribution of the profile, you should see that the important files are copied into the appropriate directories of the endpoint first. Check the following specific files for this Resource Model: a. process_num.ksh This file is the script file distributed as a dependency file. You can find it in the directory $LCFD_DATDIR/LCFNEW/Tmw2k/Unix/customscripts. If you have a problem in using this ITSO_ProcessNum Resource Model, run the process_num.ksh of the distributed one. It will help the problem determination in the first step. b. ITSO_ProcessNum.js This is the decision tree script file in JavaScript. You can find it in the directory $LCFD_DATDIR/LCFNEW/Tmw2k/Unix/Dec. Checking the result of the wdmlseng command The wdmlseng command is useful for checking the status of the Resource Model. Run the wdmlseng command to check your Resource Model, as shown in Example 10-5.
Example 10-5 Checking the result of the wdmlseng
# wdmlseng -e pacs006-ep -verbose Forwarding the request to the engine... The following profiles are running: customscriptRM-PF#pacs007-region ITSO_ProcessNum: Running
If you have any status other than Running, check the trace files in Appendix A, Testing a Java Resource Model on page 481. Generating the events To verify that the ITSO_ProcessNum Resource Model generates events, we completed four scenarios in the lab, as shown in Table 10-10.
Table 10-10 ITSO_ProcessNum Resource Model scenarios
Case Case Name
CASE 1 CASE 2 CASE 3 CASE 4
Normal Ev_process_num_becomes_high Ev_process_num_becomes_very_high Ev_process_num_becomes_low
438
Let us summarize our test results:
Case 1: Description Procedure Result
Normal Change the number of the httpd processes to 4 and check that no event is generated. Start httpd by setting StartServers to 4 and MinSpareServers to 3 in the httpd.conf. No event was generated.
The Case 1 test results are shown in Example 10-6.

Example 10-6 Case 1 results
# wdmlseng -e pacs006-ep -verbose Forwarding the request to the engine... The following profiles are running: customscriptRM-PF#pacs007-region ITSO_ProcessNum: Running Ev_process_num_becomes_high 100 % Ev_process_num_becomes_very_high 100 % Ev_process_num_becomes_low 100 %
Case 2: Description
Ev_process_num_becomes_high Change the number of the httpd processes to 7 and check that the Ev_process_num_becomes_high is generated. Restart httpd by setting StartServers to 7 in the httpd.conf. The Ev_process_num_becomes_high was generated.
Procedure Result
The Case 2 results are shown in Example 10-7.

# wdmlseng -e pacs006-ep -verbose Forwarding the request to the engine... The following profiles are running: customscriptRM-PF#pacs007-region ITSO_ProcessNum: Running Ev_process_num_becomes_high 0 % Ev_process_num_becomes_very_high 100 % Ev_process_num_becomes_low 100 % [root@pacs006 logs]# tail msg_dmxengine.log <F>1048797190457<F>Thu Mar 27 14:33:10 CST 2003<F>AMW<F>Engine<F>pacs006-ep<F>32576<F>AMW2002I<F>AMW2002I The event
439
Ev_process_num_becomes_high;modelname="ITSO_ProcessNum";profilename="customscri ptRM-PF#pacs007-region";prev_value="5";event_key="Ev_process_num_becomes_high|P aram_proc_name=httpd;";param_proc_name="httpd";value=" 8";eventid="1048797190198";relation_delta="-3";severity="WARNING";upperbound_hi gh= 5.0;scriptresult= 8.0 ;hostname="pacs006-ep";origin="9.3.5.36";adapter_host="pacs006-ep";date="03/27/ 2003 02:33:10 PM";msg="The number of the process becomes high: Process name is httpd: Process number is 8.0 and greater than 5.0";END has been sent to Tivoli Enterprise Console.<F>INF
Case 3: Description
Ev_process_num_becomes_very_high Changes the number of the httpd processes to 12 and checks that the Ev_process_num_becomes_very_high is generated. Restarts httpd after setting StartServers to 12 in the httpd.conf. The Ev_process_num_becomes_very_high was generated. Then the Ev_process_num_becomes_high was cleared.
Procedure Result

# wdmlseng -e pacs006-ep -verbose Forwarding the request to the engine... The following profiles are running: customscriptRM-PF#pacs007-region ITSO_ProcessNum: Running Ev_process_num_becomes_high 100 % Ev_process_num_becomes_very_high 0 % Ev_process_num_becomes_low 100 % [root@pacs006 logs]# tail msg_dmxengine.log <F>1048797430481<F>Thu Mar 27 14:37:10 CST 2003<F>AMW<F>Engine<F>pacs006-ep<F>32576<F>AMW2002I<F>AMW2002I The event Ev_process_num_becomes_very_high;modelname="ITSO_ProcessNum";profilename="custo mscriptRM-PF#pacs007-region";prev_value="8";event_key="Ev_process_num_becomes_v ery_high|Param_proc_name=httpd;";param_proc_name="httpd";value=" 11";eventid="1048797430190";relation_delta="-3";severity="CRITICAL";upperbound_ veryhigh= 10.0;scriptresult= 11.0;hostname="pacs006-ep";origin="9.3.5.36";adapter_host="pacs006-ep";date="03 /27/2003 02:37:10 PM";msg="The number of the process becomes very high: Process name is httpd: Process numberis 11.0 and greater than 10.0";END has been sent to Tivoli Enterprise Console.<F>INFO
440
<F>1048797430724<F>Thu Mar 27 14:37:10 CST 2003<F>AMW<F>Engine<F>pacs006-ep<F>32576<F>AMW2002I<F>AMW2002I The event TMW_Clearing;modelname="ITSO_ProcessNum";profilename="customscriptRM-PF#pacs007 -region";eventname="Ev_process_num_becomes_high";eventid="1048797190198";event_ key="Ev_process_num_becomes_high|Param_proc_name=httpd;";slotkey="Ev_process_nu m_becomes_high|Param_proc_name=httpd;";severity="HARMLESS";distrib_admin="Root_ pacs007-region";hostname="pacs006-ep";origin="9.3.5.36";adapter_host="pacs006-e p";date="03/27/2003 02:37:10 PM";msg="The problem described by Ev_process_num_becomes_high no longer exists.";END has been sent to Tivoli Enterprise Console.<F>INFO
Case 4: Description Procedure Result
Ev_process_num_becomes_low Stops the httpd and checks that the Ev_process_num_becomes_low is generated. Stops httpd. The Ev_process_num_becomes_low was generated. Then the Ev_process_num_becomes_very_high was cleared.

# wdmlseng -e pacs006-ep -verbose Forwarding the request to the engine... The following profiles are running: customscriptRM-PF#pacs007-region ITSO_ProcessNum: Running Ev_process_num_becomes_high 100 % Ev_process_num_becomes_very_high 100 % Ev_process_num_becomes_low 0 % [root@pacs006 logs]# tail msg_dmxengine.log <F>1048797700448<F>Thu Mar 27 14:41:40 CST 2003<F>AMW<F>Engine<F>pacs006-ep<F>32576<F>AMW2002I<F>AMW2002I The event Ev_process_num_becomes_low;modelname="ITSO_ProcessNum";profilename="customscrip tRM-PF#pacs007-region";prev_value="11";event_key="Ev_process_num_becomes_low|Pa ram_proc_name=httpd;";param_proc_name="httpd";value=" 0";eventid="1048797700187";relation_delta="11";severity="CRITICAL";lowerbound_l ow= 2.0;scriptresult= 0.0 ;hostname="pacs006-ep";origin="9.3.5.36";adapter_host="pacs006-ep";date="03/27/ 2003 02:41:40 PM";msg="The number of the process becomes low: Process name is httpd: Process number is 0.0 and less than 2.0";END has been sent to Tivoli Enterprise Console.<F>INFO <F>1048797700692<F>Thu Mar 27 14:41:40 CST 2003<F>AMW<F>Engine<F>pacs006-ep<F>32576<F>AMW2002I<F>AMW2002I The event
441
TMW_Clearing;modelname="ITSO_ProcessNum";profilename="customscriptRM-PF#pacs007 -region";eventname="Ev_process_num_becomes_very_high";eventid="1048797430190";e vent_key="Ev_process_num_becomes_very_high|Param_proc_name=httpd;";slotkey="Ev_ process_num_becomes_very_high|Param_proc_name=httpd;";severity="HARMLESS";distr ib_admin="Root_pacs007-region";hostname="pacs006-ep";origin="9.3.5.36";adapter_ host="pacs006-ep";date="03/27/2003 02:41:40 PM";msg="The problem described by Ev_process_num_becomes_very_high no longer exists.";END has been sent to Tivoli Enterprise Console.<F>INFO
10.3 ITSO_ProcessNum source code

The following files were created for the purpose of this example.
10.3.1 ITSO_ProcessNum.js
The decision tree script code used for the ITSO_ProcessNum Resource Model is shown in its entirety in Example 10-10.
Example 10-10 ITSO_ProcessNum decision tree script
//''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' '''''''''''''''''''''''''''''''''''''''' // IBM Tivoli Monitoring // Decision Tree script // // This file has been generated by IBM Tivoli Monitoring Workbench // // 03/24/2003 16:09:00 //''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ''''''''''''''''''''''''''''''''''''''' var hTableScriptResult; var flagNotFirstRun = 0;
// This function is used to define the settings of the Resource Model // It is called only once, when the Resource Model is started. // Don't modify remarks containing tags like <<....>> ... <<\...>> // You can write additional initializing code in this function if required. function SetDefaultConfiguration (Svc) { // General info section
442
//<<GENERAL_INFO>> Svc.SetModelName ("ITSO_ProcessNum"); Svc.SetProfileName ("510308484"); Svc.SetCycleTime (30); //<<\GENERAL_INFO>> // Thresholds section //<<THRESHOLDS_INFO>> Svc.DefineThreshold ("Thr_process_num_becomes_very_high", 10.000000); Svc.DefineThreshold ("Thr_process_num_becomes_high", 5.000000); Svc.DefineThreshold ("Thr_process_num_becomes_low", 2.000000); //<<\THRESHOLDS_INFO>> // Parameters section //<<PARAMETERS_INFO>> Svc.DefineStrParameter ("Param_proc_name", "httpd"); //<<\PARAMETERS_INFO>> // Dynamic Model section //<<DATA_INFO>> //<<\DATA_INFO>> // Event definition section //<<EVENTS_INFO>> Svc.DefineEvent ("Ev_process_num_becomes_low", "ScriptResult,LowerBound_low", "prev_value,value,relation_delta,Param_proc_name"); Svc.DefineEvent ("Ev_process_num_becomes_very_high", "ScriptResult,UpperBound_veryhigh", "prev_value,value,relation_delta,Param_proc_name"); Svc.DefineEvent ("Ev_process_num_becomes_high", "ScriptResult,UpperBound_high", "prev_value,value,relation_delta,Param_proc_name"); //<<\EVENTS_INFO>> // Logging definition section //<<LOGGING_INFO>> //<<\LOGGING_INFO>> // Place your additional intializing code below
return (0); }
// This function is called by the DM For Windows Analyzer after that // the Resource Model default settings have been overridden
443
// It is called only once, when the Resource Model is started. // You can write additional initializing code in this function if required // to use the thresholds and parameters values function Init(Svc) { hTableScriptResult = Svc.CreateMap(); return (0); }
// This function contains the monitoring algorithm // It is called ciclically after a cycle time has elapsed // Implement the the monitoring code here function VisitTree(Svc) { var curScriptResult; var hashKey; var found; var OldScriptResult; var hPropTable; var ProbeArgCount; var ProbeArgIdx; var ParamCount; var ParamIdx; var Different; //Define additional valuables var NumOfParam; var ParamTmp; //Count the number of parameters NumOfParam = Svc.GetStrParameterCount("Param_proc_name"); hPropTable = Svc.CreateMap(); //Start the loop for (i = 0; i < NumOfParam ; i++) { //Get the parameter ParamTmp = Svc.GetStrParameter("Param_proc_name",i); //Implementation for the monitor ScriptResult Svc.RemoveMapAll(hPropTable); //Set the loop id to hashkey
444
hashKey = i ; //Modify the argument for the custom script curScriptResult = Svc.Shell ("process_num.ksh "+ParamTmp); Svc.SetMapNumElement(hPropTable,"ScriptResult",curScriptResult); found = Svc.ExistsMapElement(hTableScriptResult, hashKey); if (found) OldScriptResult = Svc.GetMapNumValue(hTableScriptResult, hashKey); else OldScriptResult = 0; Svc.SetMapNumElement(hPropTable,"OldScriptResult",OldScriptResult); Svc.SetMapStrElement(hPropTable,"prev_value", OldScriptResult); Svc.SetMapStrElement(hPropTable,"value", curScriptResult); Svc.SetMapStrElement(hPropTable,"relation_delta", OldScriptResult curScriptResult); //Put valuables to hPropTable Svc.SetMapStrElement(hPropTable,"Param_proc_name",ParamTmp); Svc.SetMapNumElement(hPropTable,"UpperBound_veryhigh",Svc.GetThreshold("Thr_pro cess_num_becomes_very_high")); Svc.SetMapNumElement(hPropTable,"UpperBound_high",Svc.GetThreshold("Thr_process _num_becomes_high")); Svc.SetMapNumElement(hPropTable,"LowerBound_low",Svc.GetThreshold("Thr_process_ num_becomes_low")); //Check the thresholds if (curScriptResult > Svc.GetThreshold("Thr_process_num_becomes_very_high") ) { Svc.SendEventEx ("Ev_process_num_becomes_very_high",hPropTable); } else { if (curScriptResult > Svc.GetThreshold("Thr_process_num_becomes_high") ) { Svc.SendEventEx ("Ev_process_num_becomes_high",hPropTable); } } if (curScriptResult < Svc.GetThreshold("Thr_process_num_becomes_low") ) { Svc.SendEventEx ("Ev_process_num_becomes_low",hPropTable); } Svc.SetMapStrElement(hPropTable,"key", "@"); Svc.SetMapNumElement(hTableScriptResult, hashKey, curScriptResult);
445
// End of the loop } Svc.DestroyMap(hPropTable); return (0); }
10.3.2 ITSO_ProcessNum.ksh
The shell script code used for the ITSO_ProcessNum Resource Model is shown in its entirety in Example 10-11.
Example 10-11 ITSO_ProcessNum shell script
#!/bin/ksh PROCESS_NAME=$1 ps -A -o "args"|grep -v grep|grep -v $0|grep "$PROCESS_NAME"|wc -l
446
11
Chapter 11.
File monitoring Resource Model example

This Resource Model example addresses the real-world situation where some files crucial to system operation can become corrupt, be deleted, or maliciously altered. Files such as /etc/hosts, /etc/passwd, and vital HTML page files may need to be monitored to ensure that their integrity remains. This Resource Model will provide monitoring for such crucial files and will provide an alert when the files have changed. Optionally, it will make a backup of these files and, after alerting you, will automatically replace them, thus restoring their integrity. The goal with this Resource Model was to create a JavaScript that would run on both the ITM Java platform and the ITM Microsoft platform.
447
11.1 Engine component utilization: Overview

In this section, we will provide a graphical presentation of the ITM Engine sub-components that will be used by this Resource Model. Those components that will not be used within this model are presented in light gray to de-emphasize their significance. Figure 11-1 and Figure 11-2 on page 449 show the sub-components used by this Resource Model. You will notice from Figure 11-1 that the path, when you use ActiveX components, from Resource Model to resource is a lot more direct and has fewer component levels to traverse.

TMWService
WMI APIs DM Classic Monitor Probes WMI (CIMOM) Custom Scripts ILT Manager for Java (WMI Provider DLL) WMI Provider DLLs Java Virtual Machine (JVM) Launch (Class Loader) ILT Providers ILT JNI Binary Library JMX ILT MBean Server MBean1
Resource
COM Objects
Resource
Resource
Resource
Resource
Figure 11-1 Resource Model sub-components for Windows
448

Custom Scripts
ILT Providers
Resource
Resource
Resource
Figure 11-2 Resource Model sub-components for Java
11.2 Compiling DMXFile MOF into Workbench

Before we create this Resource Model, we have to extract the MOF file from DMXFile and compile it in the Workbench. Dependencies will also need to be extracted.
11.2.1 Extraction of MOF from DMXFile resource monitor

Follow these steps: 1. Start Workbench. 2. Open the DMXFile Resource Model by selecting File Open C:/Program Files/IBM Tivoli Monitoring/samples/unix/DMXFile.dmjsws. Or the directory where you have installed Workbench. 3. Select Build Export Mof and save the MOF file in the default directory. This will be the directory where you opened the file.
Chapter 11. File monitoring Resource Model example
449
4. You will need to transfer these files manually over to the directory where you will eventually save your Resource Model.
11.2.2 Strip UNIX control characters from the MOF file

The MOF file created in the previous section needs to have the UNIX control characters stripped from the file before it will compile. To do this task, open the file in Microsoft Wordpad and then save it. Your MOF file may now be called DMXFile.mof.txt. Rename it to DMXFile.mof.
11.2.3 Extraction of dependencies from the DMXFile resource monitor

Follow these steps: 1. Start Workbench, if it is not already running. 2. Open the DMXFile Resource Model by selecting File Open C:/Program Files/IBM Tivoli Monitoring/samples/unix/DMXFile.dmjsws or the directory where you have Workbench installed. 3. Open the dependencies tree and expand each of the OS entries contained in the tree. You should see a file called libDMXfile.* under each OS. 4. Right-click each lib file and select Extract. Save the file to the UNIX samples directory. There should be three types to save: .so, .sl, and .a. The same file, libDMXFILE.so, is used for linux-ix86, linux-s390, and solaris. 5. You will need to transfer these files manually over to the directory where you will eventually save your Resource Model. 6. Close the DMXFile Resource Model.
11.2.4 Compiling the MOF file to the CIM repository

1. Start Workbench, if it is not already running. 2. Open a new Java Resource Model by clicking on File New and then selecting Java Script Resource Model (see Figure 11-3 on page 451).
450
Figure 11-3 Workbench new Resource Model window
3. Select JavaScript Resource Model and click on OK (see Figure 11-4).
Figure 11-4 Select VBA or JavaScript language
4. Select Resource Model Wizard (see Figure 11-5 on page 452).
451
Figure 11-5 Workspace selection window
5. We will be using a CIM/WMI data source type. Select the following platforms: Solaris, linux-ix86, hpux10, aix4-r1, and linux-s390, and then click on OK (see Figure 11-6 on page 453).
452
Figure 11-6 Select data source window
6. When the Connect to namespace: dialog box appears, click the browse for namespace icon to the right of the drop-down box, as shown in Figure 11-7.
Figure 11-7 Connect to namespace window
7. In the starting namespace box, enter \default so that it reads root\default, then click on Connect (see Figure 11-8 on page 454).
453
Figure 11-8 Browse For Namespace window
8. When the WMI Tivoli DM Workbench Login box appears, do not enter a username or password; just click on OK (see Figure 11-9).
Figure 11-9 Username/password selection
9. The Browse for Namespace box will re-appear. Click on OK. 10.The Resource Model Wizard: Selected Class window should now be open (see Figure 11-10 on page 455).
454
Figure 11-10 Select a class window
11.On the bottom right of the dialog box, just above the Show Description button, you will see a button named MOF Compiler; double-click it. 12.When the WMI MOF Compiler Wizard window opens, as in Figure 11-11 on page 456, just click on Next.
455
Figure 11-11 MOF compiler action select
13.Make sure that the Namespace field says root\default and click on the Browse button. Navigate to where you saved your MOF file from the previous section. It should be in C:\Program Files\Tivoli\IBM Tivoli Monitoring Workbench\samples\Unix\DMXFile.mof, as shown in Figure 11-12 on page 457. Click on Next.
456
Figure 11-12 MOF file path and namespace
14.In the Specify update options window, we will be using the top or first option within both radio selection boxes (see Figure 11-13 on page 458).
457
Figure 11-13 MOF compiler wizard update options window
15.Click on Finish and your MOF will be compiled and added to the repository (see Figure 11-14).
Figure 11-14 MOF compile successful results window
458
16.If you get a window similar to Figure 11-15, then you probably need to open the MOF file and save it as a PC type file to get rid of the UNIX control codes. Once that has been done, go back to step 15.
Figure 11-15 MOF compile error results window
11.3 Constructing the Resource Model: Dynamic Model

1. Continuing from the last section, you should now see the Resource Model Wizard: Select a Class window, as shown in Figure 11-16 on page 460, with your DMXFile class added. Click Next.
459
Figure 11-16 Resource Model Wizard: Select a Class window
2. Select the bottom six items from the table and click on the right pointing arrow to place them in the selected table so that it looks like Figure 11-17 on page 461 and then click Next.
460
Figure 11-17 Resource Model wizard properties selection window
3. When you see the window in Figure 11-18 on page 462, click Next, as you do not need to enter any information.
461
Figure 11-18 Resource Model wizard triggering conditions selection window
4. In the window shown in Figure 11-19 on page 463, no additional information is required, so click Next twice.
462
Figure 11-19 Resource Model wizard filtering selection window
5. You will now be presented with the Cycle Time window, as shown in Figure 11-20. We chose 120 seconds as our cycle time. You may enter anything that is suitable for your environment to use a default value for your Resource Model.
Figure 11-20 Resource Model cycle time data entry panel
463
6. The IBM Tivoli Monitoring Workbench window will now be presented, as shown in Figure 11-21.
11.3.1 Constructing the Resource Model: Events

In this section, we will be opening the Events section of the monitoring tree to create two events that we will use to send information about changes to the files that we are monitoring to TEC. 1. In the Events section of the monitor tree, right-click on Events and click on Add. Enter FileChangeOnly in InternalName field, click on the Add button under attributes, and enter pathname as a type string. Click on the Key button to make it a key, leave the Clearing Event box blank, and set the number of occurrences to one and holes to zero. In the notification panel, make sure that Send to TEC is checked and the severity type is set to Warning. In the string resources panel, set the descriptive name to File Change Only. The message field is what is displayed in the TEC console. Anything that is between two @ symbols is a variable and will be substituted by the engine when the event is
464
dispatched to TEC. In the description field, describe when this event will be triggered. When it looks similar to Figure 11-22, click OK.
2. We need to add another event. In the Events section of the monitor tree, right-click on Events and click on Add. Enter FileChangeRestored to the InternalName field, click on the Add button under Attributes, and enter pathname as a type string. Click the Key button to make it a key, leave the Clearing Event box blank, and set the number of occurrences to one and holes to zero. In the notification panel, make sure that Send to TEC is checked and the severity type is set to Warning. In the string resources panel, set the descriptive name to File Change Restored. The message field is what is displayed in the TEC console. Anything that is between two @ symbols is a variable and will be substituted by the engine when the event is dispatched to TEC. In the description field, describe when this event will be triggered. When it looks similar to Figure 11-23 on page 466, click OK.
465
3. Your Workbench should now have two events defined, as shown in Figure 11-24 on page 467.
466
11.3.2 Constructing the Resource Model: Parameters

In this section, we will define two parameters. One will contain the name and path of the file to be monitored. The other will contain the action to take when the monitor detects that the file has changed. 1. In the Parameters section of the monitor tree, right-click on Parameters and click on Add. Set the InternalName and DescriptiveName to ChangeAction. Set the drop-down type box to STRING LIST. Click on the Add Value button and enter AdviseOnly. Click on the Add Value button and enter Restore. Make sure that your Parameters dialog box looks similar to Figure 11-25 on page 468.
467
Figure 11-25 Parameter data entry window
2. In the Parameters section of the monitor tree, right-click on Parameters and click on Add. Set the InternalName to FileList and the Descriptive Name to Files to be checked. Set the drop-down type box to STRING LIST. Click on the Add Value button and enter /etc/passwd.Click on the Add Value button and enter /etc/group. Click on the Add Value button and enter /etc/hosts. We chose these three files, but you can choose any files that are applicable to your systems. Make sure that your Parameters dialog box looks similar to Figure 11-26.
Figure 11-26 Parameter data entry window
3. You should now have two parameters defined under the Parameters section of the monitor tree, as per Figure 11-27 on page 469.
468
11.3.3 Constructing the Resource Model: Dependencies

In this section we will set some dependencies that are required for each operating system type. You will note that the name of the dependency file for all the Linux systems and Solaris is the same. 1. Expand all of the dependencies tree. Right-click on the All section under the dependencies tree and click on Add. A dialog box will open. Navigate to where you saved DMXFile.mof, highlight it, and click on Open. 2. Right-click on the aix4-r1 section under the dependencies tree and click on Add. Navigate to where you saved libDMXFile.a, highlight it, and click on Open. 3. Right-click the hpux10 section under the dependencies tree and click on Add. Navigate to where you saved the libDMXFile.sl, highlight it, and click on Open.
469
4. Right-click on the linux-ix86 section under the dependencies tree and click on Add. Navigate to where you saved libDMXFile.so, highlight it, and click on Open. 5. Right-click on the linux-s390 section under the dependencies tree and click on Add. Navigate to where you saved libDMXFile.so, highlight it, and click on Open. 6. Right-click on the solaris2 tree and click on Add. Navigate to where you saved the libDMXFile.so, highlight it, and click on Open. You should now have dependencies set for all sections under the dependencies tree, as in Figure 11-28.
11.3.4 Constructing the Resource Model: Inserting code

We have listed both the Init and the VisitTree subroutines. You may cut and paste these sections into your Workbench Resource Models, if you choose, but
470
we expect that the easiest way will be to download the whole Resource Model from the Redbook Web site:
1. There was one special function added. It is called GetLastModDate. As Microsoft JavaScript does not provide any native way to access file attributes, we had to use the ActiveX object Scripting.FileSystemObject. This returns the date last modified as a string. For details, see Example 11-1.
Example 11-1 GetLastModDate function
function GetLastModDate(filespec) { var fso, f, s; fso = new ActiveXObject("Scripting.FileSystemObject"); f = fso.GetFile(filespec); s = f.DateLastModified; return (s); }
2. The Init subroutine is executed only once at the start of the Resource Model. Its basic function is to initialize variables. It needs to have some extra code installed. Make sure that your subroutine looks similar to Example 11-2.
Example 11-2 Init subroutine
// This function is called by the DM For Windows Analyzer after that // the Resource Model default settings have been overridden // It is called only once, when the Resource Model is started. // You can write additional initializing code in this function if required // to use the thresholds and parameters values function Init(Svc) { Svc.Trace(2,"Start Init"); var dimension = 0; var t=0; dimension= Svc.GetStrParameterCount("FileList"); interpType = Svc.GetInterp(); if (dimension > 0 ) { if (interpType == "w32-ix86") { Svc.Trace(2,"Interp is Windows"); }else{ Svc.Trace(2,"Interp is Unix"); Svc.AssociateParameterToClass ("FileList","File"); } } else { Svc.Trace (0, "The Files to Be Checked parameter is empty");
471
return(1); }
for (k=0; check cTime mTime }
k < dimension ; k++) { [k]= -5 ; [k]= -5 ; [k]= -5 ;
Svc.Trace(2, "End Init"); return (0); }
3. The VisitTree subroutine is executed each time the cycle time expires. It is here that the intelligence of the Resource Model is invoked. It also needs some code inserted. Make sure that you subroutine looks is similar to Example 11-3. This Resource Model will be available for downloading from the Redbooks Web site at:
Example 11-3 VisitTree subroutine

// This function contains the monitoring algorithm // It is called cyclically after a cycle time has elapsed // Implement the monitoring code here function VisitTree(Svc) { Svc.Trace(2,"Start evaluate"); var instancesF=0; var i=0; var j=0; var k=0; var var var var var var var var var var var var numsize =0; nummodificationTime = 0; numchangeTime = 0; numcrc32 = 0; strsize =""; strnummodificationTime = ""; strnumchangeTime = ""; strnumcrc32 = ""; strpathName =""; FileAction=""; TempCmd; curScriptResult;
472
var var var var var var
filelen= 0; strtmp=""; flagNotFound= true; masktemp=0; strtmpfile=""; flagEvent = 0;
filelen = Svc.GetStrParameterCount("FileList"); var existing = new Array ( filelen ); for (k=0; k < filelen; k++) { existing[k] = 0; } if (interpType=="w32-ix86") { Svc.Trace(2,"Interp is Windows in VisitTree"); if (flagFirstTime){ j=0; while ( j < filelen ){ Svc.Trace(3, "Its first time so just store file details and make backups" ); strtmpfile = Svc.GetStrParameter("FileList", j); FileAction = Svc.GetStrParameter("ChangeAction", j); mTime[j]= GetLastModDate(strtmpfile); if (FileAction =="Restore") { TempCmd = "cp "+strtmpfile+" "+strtmpfile+".ITMBackup"; curScriptResult = Svc.Shell (TempCmd); } j += 1; } flagFirstTime=false; } else { j=0; while ( j < filelen ) { strtmpfile = Svc.GetStrParameter("FileList", j); strpathName = strtmpfile + ""; Svc.Trace(3, "File is " + strtmpfile); nummodificationTime = GetLastModDate(strtmpfile); strnummodificationTime = nummodificationTime + ""; strnumchangeTime = strnummodificationTime; Svc.Trace(3, " ModTime is " + strnummodificationTime); Svc.Trace(3, "Old ModTime is " + mTime[ j] ); stroldmodtime = mTime[ j] + ""; FileAction = Svc.GetStrParameter("ChangeAction", j); if ((strnummodificationTime != stroldmodtime) && (nummodificationTime != -1 )) { Svc.Trace(3, "In modtime if file action= " + FileAction);
473
mTime[j] = nummodificationTime; if (FileAction =="Restore") { flagEvent = 1; } else { flagEvent = 2; } switch ( flagEvent ) { case 1 : flagFirstTime=true; Svc.SendEvent ("FileChangeRestored", strpathName ); TempCmd = "cp "+strtmpfile+".ITMBackup"+" "+strtmpfile; curScriptResult = Svc.Shell (TempCmd); break; case 2 : Svc.SendEvent ("FileChangeOnly", strpathName ); break; default : } } flagEvent = 0; j += 1; } } }else { if (flagFirstTime){ i=0; instancesF=Svc.GetNumOfInst("File"); while (i < instancesF){ numsize = Svc.GetNumProperty ("File",i,"size"); nummodificationTime = Svc.GetNumProperty ("File",i,"modificationTime"); numchangeTime = Svc.GetNumProperty ("File",i,"changeTime"); numcrc32 = Svc.GetNumProperty ("File",i,"crc32"); strpathName = Svc.GetStrProperty ("File",i,"pathName"); strnumsize= numsize+""; strnummodificationTime = nummodificationTime+""; strnumchangeTime = numchangeTime+""; strnumcrc32 = numcrc32+""; Svc.Trace(3, "end Get attributes"); j=0; while ( j < filelen ){ strtmpfile = Svc.GetStrParameter("FileList", j); FileAction = Svc.GetStrParameter("ChangeAction", j); if ( strpathName.equals (strtmpfile) ){ existing [j] = 1;
474
check[ j] = numcrc32; cTime [ j]= numchangeTime; mTime[j]= nummodificationTime; j = filelen; if (FileAction =="Restore") { TempCmd = "cp "+strtmpfile+" "+strtmpfile+".ITMBackup"; curScriptResult = Svc.Shell (TempCmd); } } j += 1; } i=i+1; } flagFirstTime=false; } else { i=0; instancesF=Svc.GetNumOfInst("File"); while (i < instancesF) { numsize = Svc.GetNumProperty ("File",i,"size"); nummodificationTime = Svc.GetNumProperty ("File",i,"modificationTime"); numchangeTime = Svc.GetNumProperty ("File",i,"changeTime"); numcrc32 = Svc.GetNumProperty ("File",i,"crc32"); strpathName = Svc.GetStrProperty ("File",i,"pathName"); strnumsize= numsize+""; strnummodificationTime = nummodificationTime+""; strnumchangeTime = numchangeTime+""; strnumcrc32 = numcrc32+""; j=0; while ( j < filelen ) { strtmpfile = Svc.GetStrParameter("FileList", j); FileAction = Svc.GetStrParameter("ChangeAction", j); if ( strpathName.equals (strtmpfile) ) { existing [j] = 1; if (( numchangeTime != cTime[ j] ) && ( numchangeTime != -1 )) { cTime[ j]= numchangeTime; if (FileAction =="Restore") { flagEvent = 1; } else { flagEvent = 2; } if ((nummodificationTime != mTime[ j] ) && (nummodificationTime != -1 )) { mTime[j]= nummodificationTime; if (FileAction =="Restore") { flagEvent = 1; } else {
475
flagEvent = 2; } } } if ((numcrc32 != check[j] ) && (numcrc32 != -1)) { check[j]= numcrc32; if (FileAction =="Restore") { flagEvent = 1; } else { flagEvent = 2; } } switch ( flagEvent ) { case 1 : flagFirstTime=true; Svc.SendEvent ("FileChangeRestored", "", strtmpfile); TempCmd = "cp "+strtmpfile+".ITMBackup"+" "+strtmpfile; curScriptResult = Svc.Shell (TempCmd); break; case 2 : Svc.SendEvent ("FileChangeOnly", "", strtmpfile); break; default : } j = filelen; flagEvent = 0; } j += 1; } i=i+1; } } } Svc.Trace(2, "End evaluate"); return (0) }
11.3.5 The flow of the code

GetLastModDate subroutine
This subroutine uses an Microsoft ActiveX component to get the date last modified of any file listed in the input parameters of the Resource Model. It is called from the VisitTree subroutine as required. ActiveX was used to avoid the JavaScript limitations with reading and opening files.
476
Init subroutine
The Init subroutine is always executed once per Resource Model at the start of the Tmw2k.exe engine. There is a little extra code for this Resource Model that checks that there are parameters defined. If none are defined, then the Resource Model will return a False termination code and end. The interpreter type is also discerned and stored in the variable interpType for later use in the VisitTree subroutine. Once this has completed, the array used for data storage is created, based upon how many parameters are supplied.
VisitTree subroutine
This subroutine consists of a couple of loops divided by an if..else structure to segregate the code for Microsoft Windows or Java. The first loop is only visited on the first cycle period of the Resource Model. Here all instances of files and their properties are checked as per the Dynamic Model. There is another internal loop that checks if it matches one of our parameter files. If it matches, our other parameter, ChangeAction, is checked. If ChangeAction is set to Restore, then a backup copy is created. The file properties are also stored in the data array. Future iterations of the first loop are blocked by the variable FlagFirstTime being set to false. If FlagFirstTime is not set to False, then the second loop is executed. The first section of this loop is the same as the first loop. In the second section, you will notice that various attributes of the files that match our parameters are checked. Different combinations of these attributes will produce either a Flagevent 1 or 2. Flagevent 1 will result in the an event being escalated and the file restored from backup. Flagevent2 will only product an event, with no file restoration. The whole process is then repeated after the cycle timer expires.
477
478
Part 3
Part
Appendixes
479
480
Appendix A.
Testing a Java Resource Model

This appendix describes how to test a Resource Model from a developers perspective. Since the introduction of Distributed Monitoring 4.1 Advanced Edition, it has been possible to develop Resource Models for several platforms (also named interps) even though the Workbench shipped with ITM Version 5.1.1 is only available on the Windows platform. Unfortunately, there is not a consolidated approach to developing a Java Resource Model and testing it. The typical development life cycle of a Java Resource Model can be described as an interactive process based on the following steps: Workbench development and build. Resource Model installation in the ITM environment using the wdmrm command. Testing by pushing the profile on the application object. Log file analysis to find possible bugs.
481
ITM Engine tracing and clean-up

Note: In order to replace an existing Resource Model with a newer version of the same Resource Model, the version number of the new Resource Model must be greater than the version number of the existing Resource Model. The wdmrm command will then replace the existing Resource Model with the new Resource Model. If you do not update the version number, then you will have to change the name of the new Resource Model in order to install it into your Tivoli Enterprise environment.
Before performing a log file analysis, set the log level to 3 using the wdmtrceng command (see Example A-1).
Example: A-1 wdmtrceng
wdmtrceng -e <endpoint>"" 3 -1
To make the interactive development process of a Resource Model easier, it is useful to have a clean ITM Engine prior to pushing a profile containing the new version of the Resource Model. An engine without any Resource Models processes the latest MOF files, uses the newest JavaScript, and loads the upgraded ILTs and Providers. Before removing the Resource Models from the engine, stop it with the wdmcmd command (see Example A-2).
Example: A-2 wdmcmd
wdmcmd -stop -e <endpoint>
Now, you should remove any Resource Models from the target engine. A cleanrm.sh script prototype removes all the Resource Models from a Java ITM Engine, specifically on the UNIX platform, and is shown in Example A-3.
Example: A-3 The cleanrm.sh script
# removes the serialized MOF files, dont remove __namespace rm $LCFNEW/Tmw2k/Unix/data/cimom/persistence/classes/root/<mof filenames> # removes the ilts and providers classes rm $LCFNEW/Tmw2k/Unix/Classes/com/tivoli/dmunix/ep/ilts/*.class rm $LCFNEW/Tmw2k/Unix/Classes/com/tivoli/dmunix/ep/providers/*.class #removes the javascript file rm $LCFNEW/Tmw2k/Unix/Dec/*.js # removes Resource Models rm $LCFNEW/Tmw2k/Unix/data/rm/*.zip rm $LCFNEW/Tmw2k/Rm/*.zip # removes the logs rm $LCFNEW/AMW/logs/*.log
482
rm $LCFNEW/AMW/logs/*.old # removes the profiles rm $LCFNEW/Tmw2k/Unix/data/profiles/*.dmprf
Push the profile and analyze the log files for possible bugs.
Debugging the Init function

The script component of a Resource Model has two main functions invoked by the service object: the Init and the VisitTree methods. The Init function is intended to check the parameters used by the Resource Model and associate the parameters to a CIM class or to a CIM class property. If the Resource Model is dependant on a parameter lists and the list(s) are empty, there may be some cases when the Resource Model is unable to start. A simple approach to providing user feedback that explains the lack of parameter list values is to return a value between 801 and 1000. This ensures that when a profile containing a Resource Model with empty parameter lists is pushed to an endpoint, the user will get a missed prerequisites error from the wdmlseng command. As shown in the code snippet in the Example A-4, the Resource Model will not start unless there is at least one parameter that contains at least one value. In this case, the return value is 801, which corresponds to a missing prerequisite having a value of 1. In case the parameter filenameDifference contains no values, the missing prerequisite will be 2 (return code 802) while the value is 3 if the parameter contains more than that one value. Note that a different return code should be associated to each error so that the user is able to verify the missing parameter. Edit the profile and re-distribute the profile.
Example: A-4 Using missed prerequisites return values
dimension1= dimension2= dimension3= dimension4= Svc.GetStrParameterCount("filenameDifference"); Svc.GetStrParameterCount("filenameCRC"); Svc.GetStrParameterCount("driveletter"); Svc.GetStrParameterCount("filenamePattern");
if ( (dimension==0) && (dimension1==0) && (dimension2==0) && (dimension3==0) &&(dimension4==0) ) { Svc.Trace(0, "IBM DMOS2FileSystem All the parameters are empty."); return 801; } if (dimension == 0 ) { Svc.Trace(0, "IBM DMOS2FileSystem No values specified for the filename permission."); return 802; }
Appendix A. Testing a Java Resource Model
483
else if (dimension == 1) { Svc.AssociateParameterToClass ("filenameP","OS2FileSystem"); } else if (dimension > 1) { Svc.Trace(0, "IBM DMOS2FileSystem Too many values in the filename permission."); return 803; }
If the user does not have access to the documentation describing the Resource Model, or the Resource Model has not been thoroughly documented, a way to verify the missing parameters is to inspect the trace_dmxengine.log file. Example A-4 on page 483 requires that you look for entries related to the Init function for the specified Resource Model (for example, DMOS2Filesystem). To perform this task, instead of accessing the monitored machine, use the serviceability task DMCollectEPLog. It will create a user-named tar file on the endpoint. Next, transfer the tar file to a convenient location, such as your development machine, un-tar it, and inspect the trace_dmxengine.log. In case there is no ftp server available on the monitored machine, it is possible to use the wadminep command shown in Example A-5. This command will transfer the tar file created with the DMCollectEPLog task from the monitored machine to the local machine, given the local machine has the Tivoli binaries loaded to support the wadminep command.1
Example: A-5 wadminep
wadminep <ep-label> get_file <endpoint-dir>/<engine-logs>.tar <engine-logs>.tar
After retrieving the tar file, untar it, open the trace_dmxengine.log file with an editor, and inspect at the log entries. In case you are working on a windows platform where you have installed the Workbench, use either the tar utility available in the bin subdirectory of the IBM Tivoli Monitoring Workbench installation directory or Winzip to decompress the file. The only drawback to this approach consists of having to collect the log files in order to verify the missing parameter or consult the related Resource Model documentation. A more consistent approach makes use of the ITM event to notify the user that something is going wrong on the endpoint. In this case, the event is related to the Resource Model itself. Therefore, when a parameter does not contain the required values, not only does the Init function return a missed prerequisites value, but it sends an event as
The wadminep command has several unsupported options, such as view_directory <directoy-name> and remove_file <file-name>.
1
484
well. This could be implemented through an EmptyParameter event (with indications 1 and holes 0), as shown in Example A-6.
Example: A-6 sendEmptyParameter function
function sendEmptyParameterEvent(Svc, paramName) { var hPropTable = Svc.CreateMap(); Svc.SetMapStrElement(hPropTable,"parameter",paramName); Svc.SendEventEx ("EmptyParameter",hPropTable); Svc.DestroyMap(hPropTable); }
A sendEmptyParameter function can be invoked in the Init before returning the missed prerequisites value, as shown in Example A-7.
Example: A-7 Sending the EmptyParameter event
if (dimension == 0 ) { Svc.Trace(0, "IBM DMOS2FileSystem No values specified for the filename permission."); Svc.sendEmptyParameterEvent(Svc,filenameDifference); return 802; }
After enabling both the profile and the events themselves to be sent to the Tivoli Enterprise Console (TEC), it is possible to check the Resource Model behavior when there is an error in the parameters configuration. There are two ways to verify the events received from a Resource Model: either through the command line or with the TEC. The most useful commands to inspects the events received by TEC are:
wtdumprl wtdumper d
Verifies whether an event has arrived or not. Verifies if an event has been parsed and stored. This requires that the active rule set contain a Resource Model in the baroc file.
wtdbclear -el -t 0 -p FALSE Removes all the events already received form the TEC database.
In case TEC has not been installed in the Tivoli Management Region, it is possible to specify a task to be executed when the event occurs. In this way the messages concerning the parameters will be shown in the Tivoli Distributed Monitoring Notice Group.
485
Debugging the VisitTree function

The same approach described for the Init can be used to develop and test the VistTree function in a Resource Model. In this case, if there is an unrecoverable error in the VisitTree, the return value is a value between 201 and 400. Other return codes and behaviors can be seen in Chapter 6, Resource Model Troubleshooting, in the IBM Tivoli Monitoring Workbench Users Guide Version 5.1.1, SH19-4571. As in the Init section, there are some conditions that require you to inform the user about errors that occur during the monitoring activity. This could be done with a corresponding event. For example, if you are monitoring a file for changes, and the file does not exist, an event not related to any specific threshold will be sent (that is, sendFileDoesNotExist), as shown in Example A-8.
Example: A-8 The sendFileDoesNotExist function
function sendFileDoesNotExist(Svc, param, paramName) { var hPropTable = Svc.CreateMap(); Svc.SetMapStrElement(hPropTable,"fileName",Svc.GetStrParameter(param, 0)); Svc.SetMapStrElement(hPropTable,"parameter",paramName); Svc.SendEventEx ("FileDoesNotExist",hPropTable); Svc.DestroyMap(hPropTable); }
This behavior requires that the pair ILT and Provider returns a specific value in case the file does not exist as described in Example A-9.
Example: A-9 The sendFileDoes Not Exist resource event
curfileDiff = Svc.GetNumProperty("OS2FileSystem", idx, "fileDiff"); . . . if (curfileDiff ==-2) { sendFileDoesNotExist(Svc,"filenameDifference","Filename Difference") }
Aside from developing and testing the Resource Model for boundary conditions, you must test the Resource Model main functionalities, in particular if all the events are fired when expected and their properties are filled with the metrics collected from the resource. From a functional point of view, all the events are fired when a threshold is exceeded by a metric. Since there are some conditions that are very difficult to create, it is very unlikely that the developer is able to generate the expected event easily. The simulated data Provider is a way to overcome this hurdle.
486
Simulating data Providers

The main concern of a Resource Model developer is to perform a white box test where all the branches in the VisitTree function are exercised. Usually, the VisitTree function contains several conditional blocks where the property values returned by the data Provider are compared against user defined thresholds in order to make a decision whether to send an event or not. See Example A-10 for a code snippet that represents the typical event check pattern.
Example: A-10 Event conditional branch
curfilePerm = Svc.GetStrProperty("OS2FileSystem", idx, "filePerm"); . . . if (!(curfilePerm.equals(previousfilePerm))) { var hPropTable = Svc.CreateMap(); var file=Svc.GetStrParameter("filenamePattern", 0); Svc.SetMapStrElement(hPropTable,"File", file); Svc.SetMapStrElement(hPropTable,"currentPermissions", curfilePerm); Svc.SetMapStrElement(hPropTable,"previousPermissions", previousfilePerm); Svc.SendEventEx ("FilePermissionsChanged",hPropTable); Svc.DestroyMap(hPropTable); }
Unfortunately, in some cases, it is very difficult to test all these branches with a real data Provider since it requires you to stress the resource in such a way to create the expected value that will trigger the event. In this case, it could be useful to create a simulated data Provider. The simulated data Provider has the same interface as the actual data Provider so that it is run-time compatible with it. The only real difference between the simulated data Provider and the real data Provider is that the simulator obtains its data from the user or a user provided data file versus querying a resource. This allows the user to control the data the Provider will report back to the Resource Model, which allows the developer to test the Resource Model more effectively and efficiently. Therefore, the user has to develop a simulator able to read from a file the values that will be retuned to the ILT and in turn to the VisitTree. This file could be structured in such a way that each expected Provider property has a list of expected values that will be read and returned at each cycle time: fsUsed, 10, 20, 30 and so on. After developing this Provider simulator and pushing the Resource Model to the monitored platform, replace the real Provider class file (for example,
487
DMOS2FileSystem.class) with the fake one in the LCFNEW/Tmw2k/Unix/Classes/ directory. Next, the engine should be restarted so that the Resource Model will be thoroughly exercised using the Provider data file.
Verifying the Resource Model logging

Another issue is the problem to verify whether the Resource Model is logging and the values being logged. An alternate way to verify that the Resource Model is logging instead of using the Web health console is through a query tool made available from the QuadCap Web site (http://www.quadcap.com/home.html), since the ITM Engine embeds QuadCap QED as an in-process pure Java local database to store logged data. The file created under the LCFNEW/Tmw2k/Unix/data/logger/dblogger directory should be collected and moved to the machine where the Quadcap Embeddable Server Admin Tool is installed. This tool is basically a query tool based on an HTML interface. After starting it (on Windows, open the Start Menu and select Programs QuadcapEmbeddable Database Start Qued), open an HTML browser and connect to http://127.0.0.1:8080.
488
Figure A-1 The Quadcap Embeddable Server
Click on the Quadcap Embeddable Server Admin Tool link and connect using a user admin and password admin. After logging in, connect to the database and open it using the interface shown in Figure A-2 on page 490.
489
Figure A-2 Opening the database
Using the Quadcap Embeddable Server Admin Tool, connect to the database and query the tables shown in Table A-1 through Table A-8 on page 493.
Tables
The tables created on the engine local database follow.
Table A-1 Endpoints
Field name Data type Notes
EID HOST_NAME IP_ADDRESS ENDPOINT_LABEL GMT_OFFSET
INTEGER VARCHAR(120) VARCHAR(20) VARCHAR(64) INTEGER
Automatically generated number.
Minutes in the range [-720,720].
490
Table A-2 RmProfiles

CATEGORY PROFILE RESOURCE_MODEL ID EID INSERT_SEQ
VARCHAR(128) VARCHAR(256) VARCHAR(128) BIGINT INTEGER INTEGER Automatically generated number used by the ETL1. This is the CRC32 of the key fields [0,2^32-1].
Table A-3 Resources

RESOURC CONTEXT RCID ID EID INSERT_SEQ
VARCHAR(128) VARCHAR(256) BIGINT BIGINT INTEGER INTEGER Automatically generated number used by the ETL1. This is the CRC32 of the key fields [0,2^32-1].
Table A-4 Metrics

NAME RCID MID STAT EID INSERT_SEQ
VARCHAR(120) BIGINT BIGINT VARCHAR(8) INTEGER INTEGER
Automatically generated number.
This is the CRC32 of the key fields [0,2^32-1].
Automatically generated number used by the ETL1.
491
Table A-5 Instances

INSTANCE_KEY IID RCID EID INSERT_SEQ
VARCHAR(2096) BIGINT BIGINT INTEGER INTEGER Automatically generated number used by the ETL1. This is the CRC32 of the key fields [0,2^32-1].
Table A-6 Categories

NAME RCID CID EID INSERT_SEQ
VARCHAR(128) BIGINT BIGINT INTEGER INTEGER Automatically generated number used by the ETL1. This is the CRC32 of the key fields [0,2^32-1].
Table A-7 MetricsData

MID METRICVALUE TIMEKEY TIMEKEY_DTTM IID EID INSERT_SEQ
BIGINT FLOAT INTEGER TIMESTAMP BIGINT INTEGER INTEGER Automatically generated number used by the ETL1. Number of seconds since the epoch.
492
Table A-8 CategoriesData

CID CATEGORYVALUE TIMEKEY TIMEKEYDTTM IID EID INSERT_SEQ
BIGINT VARCHAR(128) INTEGER TIMESTAMP BIGINT INTEGER INTEGER Automatically generated number used by the ETL1. Number of seconds since the epoch.
493
494
Appendix B.
Additional material
This redbook refers to additional material that can be downloaded from the Internet as described below.
Locating the Web material

The Web material associated with this redbook is available in softcopy on the Internet from the IBM Redbooks Web server. Point your Web browser to:
ftp://www.redbooks.ibm.com/redbooks/SG246900
Alternatively, you can go to the IBM Redbooks Web site at:

ibm.com/redbooks
Select the Additional materials and open the directory that corresponds with the redbook form number, SG246900.
Using the Web material

The additional Web material that accompanies this redbook includes the following files:
File name sg246900.zip
Description Zipped Code Samples
495
System requirements for downloading the Web material

The following system configuration is recommended:
Hard disk space: Operating System: Processor : Memory:
5 MB minimum Windows or UNIX Any Any
How to use the Web material

Create a subdirectory (folder) on your workstation, and unzip the contents of the Web material zip file into this folder.
496
Abbreviations and acronyms

API
Application Programming Interface Common Information Model CIM Object Management Component Object Model Dynamic Link Library Distributed Monitoring Desktop Management Interface Desktop Management Task Force Graphical User Interface International Business Machines Corporation Integrated Development Environment Interface Definition Language Information Library Type IBM Tivoli Monitoring IBM Tivoli Monitoring Workbench International Technical Support Organization Java Development Kit
JMX JNI JRE JVM LCF LCFD M12 M9 MCSL
Java Management Extension Java Native Interface Java Runtime Environment Java Virtual Machine Light Client Framework Light Client Framework Daemon Manageability Management Monitoring Collection Specification Language Microsoft Data Access Components Management Information Block Management Information Format Managed Object Format Network File System Network Interface Card Open Database Connectivity Object ID Proactive Analysis Component Relational Database Management System Remote Procedure Call
CIM CIMOM COM DLL DM DMI
DMTF
MDAC MIB MIF MOF NFS NIC ODBC OID PAC RDBMS RPC
GUI IBM
IDE
IDL ILT ITM ITMWB ITSO
JDK
497
SDK SNMP
Software Development Kit Simple Network Management Protocol Tivoli Business Systems Manager Tivoli Enterprise Console Tivoli Enterprise Data Warehouse Tivoli Management Framework Tivoli Management Region Touchpoint Service Layer Visual Basic Visual Basic for Applications Web-based Enterprise Management Windows Management Instrumentation
TBSM TEC TEDW TMF TMR TSL VB VBA WBEM
WMI
498
Related publications
The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this redbook.
IBM Redbooks
For information on ordering these publications, see How to get IBM Redbooks on page 501. Note that some of the documents referenced here may be available in softcopy only.
IBM Tivoli Monitoring for Databases: Database Management Make Simple, SG24-6613 IBM Tivoli Monitoring Version 5.1: Advanced Resource Monitoring, SG24-5519 Introducing IBM Tivoli Monitoring for Web Infrastructure, SG24-6618
Other publications
These publications are also relevant as further information sources:
IBM Tivoli Monitoring Resource Model Reference Version 5.1.1, SH19-4570 IBM Tivoli Monitoring Users Guide Version 5.1.1, SH19-4569 IBM Tivoli Monitoring Workbench User's Guide Version 5.1.1, SH19-4571
Online resources
These Web sites and URLs are also relevant as further information sources: How to use the Microsoft Script Debugger
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/sdbug/Html /sdbug_17.asp
IBM Redbooks
Java SDK download

http://java.sun.com
499
Microsoft Script Debugger

http://msdn.microsoft.com/downloads/default.asp?url=/downloads/topic.asp?UR L=/MSDN-FILES/028/001/175/topic.xml
Microsoft Windows Developer Network

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/kmarch/hh/ kmarch/wmi_2fjb.asp
Microsoft Windows Script Host Information

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/script56/h tml/wsorigettingstarted.asp
Microsoft Windows SNMP download

http://www.microsoft.com/downloads
Microsoft WMI information

Mozilla.org Rhino Downloads

http://www.mozilla.org/rhino/download.html
QuadCab
http://www.quadcap.com/home.html
Regular Expressions for Java

Rhino
http://www.mozilla.org/rhino/
Rhino Debugger
http://www.mozilla.org/rhino/debugger.html
Sax Interpreter
http://www.saxsoft.com/Basic/Details
Sax.net
http://www.saxsoft.com
Tivoli Developers Domain

http://www.ibm.com/software/tivoli/info/pa/monitor/index.jsp
Tivoli Management Extensions for Java (TMX4J) at IBM AlphaWorks

http://www.alphaworks.ibm.com/tech/TMX4J
WBEM Initiatives at DMTF

http://dmtf.org/standards/standard_wbem.php
500
WMI Providers
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/wmisdk/wmi /managed_objects_and_providers.asp
WMI SDK
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/wmisdk/wmi /wmi_start_page.asp
How to get IBM Redbooks

You can search for, view, or download Redbooks, Redpapers, Hints and Tips, draft publications and Additional materials, as well as order hardcopy Redbooks or CD-ROMs, at this Web site:
ibm.com/redbooks
Related publications
501
502
Index
Symbols
.dmjsws 26 .dmws 26 /etc/hosts 447 /etc/passwd 447 CIM classes 321 CIM definition 138, 232233, 248 CIM Name space 211 CIM object 251 CIM Object Manager (CIMOM) 114 CIM properties 249, 344 CIM Provider Layer 115 CIM Qualifiers 143, 237 CIM repository 70, 237 CIM schema 114 CIM values 336 CIMOM 264 class PhysicalDisk 32 TMW_PhysicalDisk 31 Class Declarations 115 class property 248 CLASSPATH 342, 357 classType 328 clean ITM Engine 482 cleanrm.sh 482 clearing event 71 Collected Instances 216 collection 168 Collection Test 215 COM object 124 COM objects 115 COM+ architecture 201 command wdmwbcli 62 Commenting Java Files 146, 157, 240 Commenting MOF Files 143 Common Components 121 Common Information Model (CIM) 6, 9, 70 Compatibility Mode 109 compile 342, 357 compiled 143, 172 Configuring the SNMP Agent 207 consecutive holes 71 Correlated events 98 CPU Resource Model 99 create 133, 153, 247, 347 cross-platform 201 CSL 50
A
Action manager 20, 23 Active Directory 116 ActiveX 448, 471 additional variables 429 aggregated 18 aggregator 71 aifIndex 253 aiInst 350 algorithm 268 Analyzer 8, 2021 analyzer component 8 Application Programming Interfaces (APIs) 9 argument 429 asHostnames 252 asITSO_LogfileLite_Pattern 349 asITSOArrayGui 350 AssociateParameterToClass 267, 348, 364, 372 AssociateParameterToClass method 346 Associations 114
B
BAROC 26 best practice 68 best practices 76
C
C++ 116, 129 ChangeAction 467, 477 CIM 9, 68, 111, 139 name space 31 CIM browser 3132, 343 limitation 32 CIM Class 264, 343 CIM class 156, 167, 233 CIM class property 483
503
curEventNum 374 CurrentDiskQLength 35 custom ILT 231 Custom Methods 154, 158, 247, 251 custom numeric monitor 50 custom script 411, 416 custom string monitor 50 Cycle Time 463 Cycle time 31 cycle time 320, 434 cycles 70
dynamic MIB values 235 Dynamic Model 8, 28, 34, 42, 162, 321, 477 Dynamic Model components 263 Dynamic Model elements 41 Dynamic Models 69 dynamic value 141 dynamically plug-able 234
E
EmptyParameter 485 Endpoint 6 engine 3 ensureElements method 260 ENUM 238 Enum 131, 145 enumerateInstances 132, 148, 151, 244, 251, 347, 350 Enumeration 148 Enumeration class 241 error code 166 Ev_ITSO_LogfileLite_EventNum_too_high 365 Ev_LogEvent 325 Ev_process_num_becomes_high 430, 439 Ev_process_num_becomes_low 441 Ev_process_num_becomes_very_high 430, 440 Ev_process_num_ksh_httpd_ScriptResult_too_hig h 423 Event aggregator 2021 event aggregator 35, 42 Event correlator 20, 22 event element properties Actions 37 Aggregation settings 37 Attributes 36 Internal name 36 Notification 37 String resources 37 event elements 3435, 41 EventLog Resource Model 97 EventNum 351, 362, 383 Events 1819, 6970, 379, 436, 464 events 18, 370 External design 204, 413
D
data Provider 487 data source type CIM/WMI 50 Custom script 50 DM Classic Edition Collection 50 debug 223, 258 debugging Resource Model 48 Decision Tree 41 decision tree 71 decision tree script 28, 69, 339, 346, 348, 365, 370, 414, 428 DefineClass 264 DefineStrParameter 164, 266 Dependencies 1819, 69, 327 dependencies 469 Description qualifier 237 DescriptiveName 467 destroy 133, 153, 247, 347 dimension 267 DiskBytesSec 35 distribute 223 Distributed Management Task Force, Inc. 112 DM collections 127 DM custom scripts 127 dm_m12.jar 241 DMCollectEPLog 484 DMI 112 dmjsws 58 DMLinkJre 376 DMTF 112 dmws 58 DMXFile 449 DMXFile.dmjsws 449 Dynamic Link Libraries (DLL) 19
F
File Resource Model 101 File system Resource Model 103
504
FileChangeOnly 464 FileChangeRestored 465 FileName 308 FlagFirstTime 477 flowchart 339
I
IBM AlphaWorks 133 IBM HTTP Server 434 IBM SNMP Java package 231 IBM Tivoli Data Warehouse 4, 6 IBM Tivoli Event Console 4 IBM Tivoli Monitoring Workbench 4 IBM Tivoli Web Health Console 4 ifDescr 214, 234, 254 ifIndex 214, 234 ifIndex class 253 ifInOctets 214, 234, 254 ifInOctets MIB variable 203 ifInOctets property 217 ifNumber 256, 259 ifOutOctets 202, 214, 234, 255 ifOutOctets MIB variable 203 ifOutOctets property 217 ifSpeed 214, 234, 254 ILT 8, 12, 137138, 486 ILT Class 354 ILT class 138, 145, 167, 178, 234, 267, 347, 357 ILT classes 120 ILT code 346, 382 ILT developer 156 ILT Interface class 147 ILT Interface Implementation 148 ILT Java Class 239 ILT Provider 133 ILT Provider Interface 131 ILT Providers 176 ILT Public Operations (Methods) 148 ILT Supported Classes 153 ILT template 232 ILTInterface 131, 146, 234 ILTInterface class 345 ILTInterface class interface 241 ILTInterface methods 239 ILTManagerForJava1.log 12 indication generation 42 Indications 436 indications 18, 70 Init 166, 267, 332, 348, 372, 471 Init function 484 initialization 166 initVector 258 Installing SNMP Service 206 Instance Declarations 115 Instance discovery 235
G
GET 238 getifDescr 254 getifIndex 253 getifInOctets 254 getifOutOctets 255 getifSpeed 254 getInstances 251 getITSO_Instances 158, 350 getITSO_LogfileLiteVar_EventNum 351, 354 getITSO_SampleVar_bln 160 getITSO_SampleVar_r 160 getITSO_SampleVar_si 159 getITSO_SampleVar_str 159 getITSO_SampleVar_ui 160 getITSOAttribute 154, 159, 248, 253254, 347, 349 GetLastModDate 471 getmatch 354 GetMultipleProperties 348 getMultipleProperties 132, 150, 242, 346 getNext 257 GetNumProperty 373 GetPropert 348 getProperty 132, 149, 242, 346 GetShellRetCode 429 GetStrParameter 429 GetStrParameterCount 429 GetStrProperty 373 GNU Regexp Java package 342 gnu.regexp package 354 gnu-regexp-1.1.1.jar 327
H
hashKey 219 hashkey variable 429 Health Console 19 hole 18 holes 21, 70 hPropTable 219, 328, 332, 430 HTML 116 httpd 412, 434 httpd.conf 439
Index
505
Instance initialization 141, 235 instance management 250 instrumentation 4, 23 Instrumentation LIbrary Type (ILT) Providers 123 Instrumentation Library Type Interface (ILT) 147 Integrated Development Environment (IDE) 25 integration point 255 Interface Definition Language (IDL) 114 Interfaces group 202 Internal design 205, 414 InternalName 464465, 467 interpreter Rhino 48, 64 Sax 48, 64 interpType 328, 477 invokeMethod 132, 152, 246, 347 islogging 11, 15 ITM Data Warehouse 19 ITM Engine 89, 68, 111 ITM Engine Components 120 ITM Engine loader 147, 240 ITM Engine log file 167 ITM Java engine 238 ITSO_ArrayGUI 163, 166, 265 ITSO_Hostnames 267 ITSO_Lab03-unix.mof 322 ITSO_Lab03-wmi.mof 313 ITSO_LogfileLite 334 ITSO_LogfileLite CIM class 362, 372 ITSO_LogfileLite ILT 334, 346 ITSO_LogfileLite Provider 346 ITSO_LogfileLite.jar 381 ITSO_LogfileLite.java 353, 357, 401 ITSO_LogfileLite.js 381 ITSO_LogfileLite.mof 343, 359, 384 ITSO_LogfileLite_FileName 348, 350, 368, 372, 378 ITSO_LogfileLite_Pattern 348, 368, 372, 378 ITSO_LogfileLite_RM.js 405 ITSO_LogfileLiteILT.java 357, 385 ITSO_LogfileLite-wmi.mof 343, 381, 385 ITSO_ProcessNum 412413, 432 ITSO_ProcessNum.js 438, 442 ITSO_ProcessNum.ksh 446 ITSO_RMs 139 ITSO_Sample 137, 140, 147, 156, 158, 162, 195 ITSO_Sample ILT 231 ITSO_Sample template 246 ITSO_Sample.dmjsws 143, 173
ITSO_Sample.jar 147, 173 ITSO_Sample.java 142, 147, 171, 192 ITSO_Sample.mof 142, 170, 173, 176 ITSO_SampleILT 145, 156157 ITSO_SampleIlt 140, 148 ITSO_SampleILT.java 172 ITSO_SampleIlt.java 142, 148, 178 ITSO_SampleVar_bln 140 ITSO_SampleVar_inst 139 ITSO_SampleVar_r32 140 ITSO_SampleVar_r64 140 ITSO_SampleVar_si 159 ITSO_SampleVar_si16 140 ITSO_SampleVar_si32 140 ITSO_SampleVar_si64 140 ITSO_SampleVar_si8 140 ITSO_SampleVar_str 139 ITSO_SampleVar_ui16 140 ITSO_SampleVar_ui32 140 ITSO_SampleVar_ui8 140 ITSO_SNMP_Interface_Bps 202, 221 ITSO_SNMP_Interface_Bps.vba 225 ITSO_SnmpProbe 234235, 241, 249, 251, 264 ITSO_SnmpProbe CIM class 244 ITSO_SnmpProbe class 237, 261 ITSO_SnmpProbe ILT 231 ITSO_SnmpProbe.dmjsws 237, 274 ITSO_SnmpProbe.jar 241, 273274 ITSO_SnmpProbe.Java 292 ITSO_SnmpProbe.java 236, 241, 272 ITSO_SnmpProbe.mof 236, 242, 270, 274, 277 ITSO_SnmpProbeILT 239, 249, 251, 253254 ITSO_SnmpProbeIlt 234, 238, 241 ITSO_SnmpProbeILT class 242 ITSO_SnmpProbeILT.Java 278 ITSO_SnmpProbeILT.java 273 ITSO_SnmpProbeIlt.java 236
J
jar 273 jar file 357 jar files 12, 15, 18 Java 8, 12, 15, 129 Java class 345 Java classes 19, 115, 240 Java compiler 171 Java Engine 120 Java engine 8
506
Java files 357 Java ILT 165, 336 Java ILT class 125 Java Imports 147, 158, 240, 250 Java Management Extensions (JMX) 117, 133 Java Native Interface (JNI) 140 Java Package 147, 157, 232, 240, 250 Java package 173 Java package file 273 Java pointers 241 Java RDBMS 19 Java Resource Model 481 Java Runtime Environment 376 java.util.Enumeration 241 java.util.Vector 241 javac 171172, 271273 JavaScript 1718, 47, 76, 165, 263, 300, 476 JavaScript function 266 JavaScript Resource Model 417 javautils.jar 147 JDK 271273 JMX 117 JMX Agent 118 JMX Architecture 117 JMX ILT 123 JMX instrumentation 118 JMX Manageable Resources 118 JNI 156 JNI & Native binary libraries 123 JNI API 156 JRE 305
logging elements 40 logging.properties 11 Logical Components 141, 203, 235 logical components 15, 68, 120 Logical Disk Resource Model 91
M
M12 129, 139140 Manageability 8 M12 functionality 234 M12 interfacing 247 M12 layer 251 M12 method calls 239 M12 Public Operations 239 M12 qualifier 145 M12 qualifiers 146, 233 M12 specification 148, 242, 246 M12_Instrumentation 131, 145, 238 M12_Instrumentation qualifier 149, 242 M12ClassPath 153 M12Exception 153 M12IdentityElement 153 M12JavaProvider 126, 144, 238 m12javaProvider 376 M12ObjectIdentity 153 M12PropertySet 153, 156, 350 M12PropertySet class 249, 251 Management 8 Manageability 129 manageability 8 Manageability (M12) Model Specification 129 Managed Object Format (MOF) 17, 114, 143 Managed Object Format (MOF) file 232 Managed Objects 116 Managed Resource 110111 Management 129 Management Application 110 management applications 116 Management Framework 8 management function 8 MBean 118 MBeans 117 MCSL 50 MDAC 19 Memory Resource Model 84, 100 method SendEvent 36 SendEventEx 36
K
key property qualifier 145, 239
L
language scripting 47 library 238 LogEvent 316 log-file adapter 305 Logger 20, 22 Logging 18, 69 logging element 41 properties Context 41 Properties 41 Resource 41
Index
507
Svc.DefineClass 33 Svc.DefineEvent 36 Svc.DefineThreshold 46 Svc.GetModelName 29 Svc.GETNUMOFINST 45 Svc.GetNumProperty 45 Svc.GetNumPropery 45 Svc.GetStrProperty 45 Svc.GetThreshold 46 Svc.LogInst 41, 45 Svc.LogInstEx 41 Svc.SENDEVENT 46 Svc.SendEventEx 36 Svc.SetModelName 29 SvcSendEvent 36 metric data 19 MIB 111, 232 MIB data 250 MIB fields 249 MIB II 256 MIB information 233 MIB values 232 MIB variable 202 mib_ii.mib 210 MIB-II specification 202 Microsoft Access 12 Microsoft Access 2000 Jet engine 19, 22 Microsoft ActiveX 116 Microsoft script debugger 64 Microsoft Script Host 124 MIF 112 MinSpareServers 439 MOF 12, 111 MOF Compile Wizard 360 MOF Compiler 313, 359 MOF file 143, 176, 237, 361, 449 MOF files 307, 358 MOF specification 114 MOF syntax 114 MOF Usage 114 mofcomp 170, 270 monitoring algorithm 18, 429 MS TCP Loopback Interface 216 msg_dmxengine.log 13, 383 msg_ILTManagerForJava.log 12 multiple parameters 428 multiple thresholds 413
N
name space root/CIMV2 31 Namespace 212, 313 namespace 115, 233, 359, 453 Network Devices 111 Network Interface Card Resource Model 87 Network Interface Resource Model 102 Network Interfaces 244 Network RPC/NFS Resource Model 106 Non-Standard CIM Qualifiers 130 nstalling WMI SNMP 208 NUMERIC 418
O
Object creation 235 object oriented language 259 occurrence 70 occurrences 2122 offsetarray 348, 351 ogging.properties 15 OID 232, 261 OID structure. 259 OIDs 250 open database connectivity (ODBC) 116 operating system libraries 9
P
PAC 147 Packaging 169 Param_proc_name 435 parameter 265, 428 Parameters 8, 18, 69, 72, 163, 467 parameters 8, 232, 335, 368, 370, 413 ParameterSet 153 ParameterSetList 153 parametric 418 Parametric event log Resource Model 89 Parametric TCP/IP Ports Resource Model 90 pattern matching 338 PDU 261 PDU class 261 Perfmon 45 Physical Disk Resource Model 92 Physical Managed Objects 111 PhysicalDiskModel 27, 32 PID 232 pragma 126
508
Process Resource Model 101 process_num.ksh 438 Processor Resource Model 94 Property tables 330 Provider 9, 68, 73, 75, 138, 144, 165, 238, 486 Provider class 138, 192, 235, 345, 353, 357 Provider classes 147 Provider code 346 Provider instances 154 Provider Java Class 156 Provider Java classes 233 Provider Layer 20, 23 Provider layer 9 Provider template 176 Providers 116, 123 public operations (methods) 242
Q
QED 488 QuadCap 488 Quadcap 15 Qualifiers 130
properties 29 Supported platforms 31 Resource Model JavaScript 195 Resource Model Tar File 169, 270, 375 Resource Model tar file 221, 432 Resource Model threads 44 Resource Models 26 Resources 9, 123 response script variables 36 retrieval 254 RFC1213 MIB-II 202 Rhino Debugger 65 shell 64 Web sites 64 Rhino interpreter 48, 64 roll-up 168 root/CIMV2 51 root/CIMV2 namespace 359 rotation function 336
S R
Redbooks Web site 501 Contact us xxi regular expression 338, 378 relationship diagram 169 resource class Class properties 33 Collection info 33 Filtering 33 property fields 33 Resource Kit 64 Resource Model 4, 8, 17 Category descriptive name 30 Category internal name 30 creating Empty Resource Model 49 recommendation 49 Resource Model wizard 48 Step-by-step Resource Model 48 Cycle time 31 debugging 48 Description 30 Descriptive name 29 Internal name 29 Major and minor version 31 Sax interpreter 48, 64 Saxsoft Web site 64 Scheduler 2021 scripting language 47 Scripting.FileSystemObject 471 ScriptResult 420 SDK 341 Security Resource Model 104 sendEmptyParameter function 485 SendEventEx 374, 430 sendFileDoesNotExist 486 Service Layer 110 Service Object API 17 Services Resource Model 95 Session management 239 SetCycleTime 263 SetDefaultConfiguration 163165, 263, 266, 328, 332, 370 SetModelName 263 SetProfileName 263 setProperty 132, 152, 246, 347, 350 shell script 165 Shell() method 430 sHostname 256
Index
509
simulated data Provider 486 SMIR 210 SNMP 111, 201, 232 SNMP capable 265 SNMP classes 235 SNMP configuration 207 SNMP Java package 250 SNMP MIB Network Interface 239 SNMP Module Information Repository (SMIR) 210 SNMP OID values 250 SNMP package 235, 255 SNMP polling 234, 241 SNMP probe 233 SNMP Providers 208 SNMP query 260 SNMP session 242, 256, 258 SNMP_RFC1213_MIB_ifTable 213 SnmpInterface 239 SnmpInterface class 242, 250251, 253, 260 SnmpInterface.Java 300 SnmpInterface.java 237, 252, 271 SnmpMacro 213 SnmpObjectType 213 SnmpPDU class 257 snmpPole 252, 255 snmpPole method 260 source code 277 sProperty 351 Standard CIM Qualifiers 130 StartServers 439 static value 141 Str(curifIndex) 219 String object 249 string property 163 STRING TYPE 428 sValue 351 Svc.CreateMap() 219 Svc.DefineStrParameter 164 Svc.Shell method 430 syntax 361
T
TCP/IP Resource Model 96 TEC 325, 464 TEC baroc file 63 test 481 The Common Information Model (CIM) 113 Thr_EventNum_gt 367, 374
Thr_ScriptResult_gt 427 threshold 18, 70 threshold element properties Default value 39 Description 39 Descriptive name 39 Internal name 39 threshold elements 35, 38, 41 threshold setting 427 Thresholds 18, 6970 thresholds 335, 370, 413, 434 Tivoli Distributed Monitoring 109 Tivoli Distributed Monitoring Notice Group 485 Tivoli Endpoint 8 Tivoli Enterprise Console (TEC) 485 Tivoli Enterprise Data Warehouse (TEDW) 218 TMW_HighPercentUsage 38 TMW_HighProcesses 22 TMW_PhysicalDisk 29 TMW_PhysicalDiskModel 27 TMW_ProcessHighCPU 22 TMW_ProcessHoggingCPU 22 TMW_SlowPhysicalDrive 35 Tmw2k 8 tmw2k 70 Tmw2k.exe 332 Tmw2k.log 11 TMWService 8 TMX4J 133 tools 62 top-down methodology 232 Touchpoint 6, 8 Touchpoint Service Layer (TSL) 129 Touchpoint service layer (TSL) 8 Trace class 147, 241 trace level 382 trace logs 19 trace_dmxengine.log 13, 147148, 241, 266, 382, 484 trace_dmxeu.log 13 trace_dmxntv.log 13 trace_ILTManagerForJava.log 12 tracing 234 trigger condition 419 Triggering Condition 218 TSL 140
510
U
UNIX MOF file 343 updateInterfaces 260 updateInterfaces method 257
V
variable definitions 45 VBA 12, 15, 76 Vector class 259 vector list 258 Vector management 239 vector management 258 vector table 250, 253254 Vector vParam 349350 VisitTree 18, 42, 167, 219, 268, 331332, 373, 476477 VisitTree function 487 VisitTree methods 483 VisitTree subroutine 477 Visual Basic 1718, 42, 47, 116
CLI 62 defined 25 three panes 27 WQL filter 33 WriteBuffer 156, 249 wrmadd 26
X
XML 14 xmof 126
W
wadminep 484 WBEM 113 WBEM specification 125 wbemsnmp.ex_ 209 wbemsnmp.exe 209 wdmcmd 12, 15, 482 wdmlseng 383, 438, 483 wdmrm 482 wdmtrceng 19, 382, 482 wdmwbcli 63 Web Health Console 63 Web-Based Enterprise Management 113 WHERE Clause 33 Windows Management Instrumentation (WMI) 6 Windows Management Interface (WMI) 115 wmftools.jar 327 WMI 8, 68 WMI Infrastructure 116 WMI Management Applications 117 WMI MOF compiler wizard 455 WMI Performance Monitoring Provider 42 WMI Providers 64, 70 WMI repository 116 WMI SDK 63 WMI SNMP Provider 201202 Workbench
Index
511
512
IBM Tivoli Monitoring Version 5.1.1: Creating Resource Models and Providers
(1.5 spine) 1.5<-> 1.998 789 <->1051 pages
Back cover
IBM Tivoli Monitoring Version 5.1.1

Creating Resource Models and Providers
Practical step-by-step development examples Creating cross-platform Java resource models Provider engineering and implementation
This IBM Redbook focuses on using the IBM Tivoli Monitoring Workbench to build Resource Models (RMs) that use existing ILT providers and custom ILT Java providers. You will learn how to create a custom ILT provider using the supplied Java templates to examine and provide data to ITM for analysis within the Resource Model that you created through the ITM Workbench. The ITM Workbench is used for developing, debugging, and packaging Resource Models for IBM Tivoli Monitoring. You will learn how to use the step-by-step wizards provided by the ITM Workbench to create RMs to monitor any number of your IT resources, including operating systems, databases, hardware, and networking resources and applications. In addition, you will learn about the Common Information Model (CIM) used to store metrics and how to collect data stored in a CIM format. Upon completion, you will be able to create, test, and deploy monitoring solutions quickly and efficiently in order to create an autonomic environment.
INTERNATIONAL TECHNICAL SUPPORT ORGANIZATION
BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE IBM Redbooks are developed by the IBM International Technical Support Organization. Experts from IBM, Customers and Partners from around the world create timely technical information based on realistic scenarios. Specific recommendations are provided to help you implement IT solutions more effectively in your environment.
For more information: ibm.com/redbooks

SG24-6900-00 ISBN 0738453102

IBM Tivoli Monitoring Version 5.1.1 Creating Resource Models and Providers Sg246900

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

IBM Tivoli Monitoring Version 5.1.1 Creating Resource Models and Providers Sg246900

Uploaded by

Copyright:

Available Formats

Front cover

IBM Tivoli Monitoring Version 5.1.1

Copyright IBM Corp. 2003. All rights reserved.

IBM Tivoli Monitoring: Creating Resource Models and Providers

IBM Tivoli Monitoring: Creating Resource Models and Providers

How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503

IBM Tivoli Monitoring: Creating Resource Models and Providers

Copyright IBM Corp. 2003. All rights reserved.

IBM Tivoli Monitoring: Creating Resource Models and Providers

IBM Tivoli Monitoring: Creating Resource Models and Providers

IBM Tivoli Monitoring: Creating Resource Models and Providers

Copyright IBM Corp. 2003. All rights reserved.

IBM Tivoli Monitoring: Creating Resource Models and Providers

Copyright IBM Corp. 2003. All rights reserved.

IBM Tivoli Monitoring: Creating Resource Models and Providers

The team that wrote this redbook

Copyright IBM Corp. 2003. All rights reserved.

IBM Tivoli Monitoring: Creating Resource Models and Providers

Theo Winkelmann Technical Evangelist, IBM Software Group

Become a published author

Send your comments in an Internet note to:

IBM Tivoli Monitoring: Creating Resource Models and Providers

Copyright IBM Corp. 2003. All rights reserved.

IBM Tivoli Monitoring: Creating Resource Models and Providers

IBM Tivoli Monitoring architecture

Copyright IBM Corp. 2003. All rights reserved.

1.2 High level architecture

IBM Tivoli Monitoring: Creating Resource Models and Providers

TMR TMR TMR TMR Tivoli Event Console In

ITM ITM HeartBeat HeartBeat

Design Create Design , Create, Deb ug Debug

ITM Engine ITM Engine

Figure 1-1 High level architecture view

1.3 Engine features and abilities

Chapter 1. IBM Tivoli Monitoring architecture

1.4 Endpoint integration

1.4.1 ITM data flow

IBM Tivoli Monitoring: Creating Resource Models and Providers

Figure 1-2 ITM data flow diagram: all platforms

Chapter 1. IBM Tivoli Monitoring architecture

IBM Tivoli Monitoring: Creating Resource Models and Providers

CIM components and the Provider layer

1.4.2 Directory structures

Chapter 1. IBM Tivoli Monitoring architecture

Figure 1-3 Windows LCFD directory structure

IBM Tivoli Monitoring: Creating Resource Models and Providers

Figure 1-4 Windows ITM directory structure

Chapter 1. IBM Tivoli Monitoring architecture

Java platform on UNIX

IBM Tivoli Monitoring: Creating Resource Models and Providers

Figure 1-5 UNIX directory structure

Chapter 1. IBM Tivoli Monitoring architecture

Figure 1-6 Java ITM on UNIX directory structure

IBM Tivoli Monitoring: Creating Resource Models and Providers

1.5 ITM Engine architecture

Chapter 1. IBM Tivoli Monitoring architecture

Windows, ITM Engine Logical Components

Resources (OS & Applications)

Figure 1-7 ITM Engine components for Windows

IBM Tivoli Monitoring: Creating Resource Models and Providers

Java, ITM Engine Logical Components

DM Classic Monitor Probes

Launch (Class Loader)