Ibm tivoli monitoring version 5.1.1 creating resource models and providers sg246900

ibm.com/redbooks

IBM Tivoli Monitoring Version 5.1.1Creating Resource Models and Providers

Tony BheKiyonobu Inayama

Craig ListerMassimiliano Parlione

Michael Vesich

Practical step-by-step development examples

Creating cross-platform Java resource models

Provider engineering and implementation

Front cover


August 2003

International Technical Support Organization

SG24-6900-00

© Copyright International Business Machines Corporation 2003. All rights reserved.Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADPSchedule Contract with IBM Corp.

First Edition (August 2003)

This edition applies to Version 5, Release 1, Modification 1 of IBM Tivoli Monitoring.

Note: Before using this information and the product it supports, read the information in “Notices” on page xvii.

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiTrademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xixThe team that wrote this redbook. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xixBecome a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiComments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi

Part 1. ITM fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 1. IBM Tivoli Monitoring architecture . . . . . . . . . . . . . . . . . . . . . . . 31.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.2 High level architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3 Engine features and abilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.4 Endpoint integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.4.1 ITM data flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.4.2 Directory structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

1.5 ITM Engine architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151.5.1 Engine input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171.5.2 Engine output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191.5.3 Engine components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Chapter 2. Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262.2 Using Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

2.2.1 The Workbench panes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272.2.2 Elements in Resource Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282.2.3 Looking at the PhysicalDiskModel . . . . . . . . . . . . . . . . . . . . . . . . . . 28

2.3 Creating Resource Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462.3.1 Creating Resource Models using the wizard. . . . . . . . . . . . . . . . . . . 462.3.2 Cloning existing Resource Models . . . . . . . . . . . . . . . . . . . . . . . . . . 602.3.3 Registering a Resource Model into ITM . . . . . . . . . . . . . . . . . . . . . . 61

2.4 Tools and extra information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622.4.1 WorkBench command line interface . . . . . . . . . . . . . . . . . . . . . . . . . 622.4.2 Microsoft tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

© Copyright IBM Corp. 2003. All rights reserved. iii

2.4.3 Saxsoft . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642.4.4 Rhino. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Chapter 3. Resource Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673.1 Resource Model overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

3.1.1 Logical components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683.1.2 Physical components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733.1.3 Types of Resource Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

3.2 Resource Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763.2.1 Resource Models for each platform . . . . . . . . . . . . . . . . . . . . . . . . . 773.2.2 Windows Resource Models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 833.2.3 UNIX Resource Models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Chapter 4. Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1094.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1104.2 Industry technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

4.2.1 Web-Based Enterprise Management (WBEM) . . . . . . . . . . . . . . . . 1134.2.2 The Common Information Model (CIM). . . . . . . . . . . . . . . . . . . . . . 1134.2.3 Managed Object Format (MOF) . . . . . . . . . . . . . . . . . . . . . . . . . . . 1144.2.4 CIM Provider layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1154.2.5 Windows Management Interface (WMI) . . . . . . . . . . . . . . . . . . . . . 1154.2.6 Java Management Extensions (JMX) . . . . . . . . . . . . . . . . . . . . . . . 117

4.3 Tivoli implementations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1194.3.1 ITM Engine components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1204.3.2 Legacy support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1274.3.3 Touchpoint Service Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1294.3.4 CIM object definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1294.3.5 Tivoli ILT Provider Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1314.3.6 Tivoli Management Extensions for Java (TMX4J). . . . . . . . . . . . . . 133

Part 2. Practical examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Chapter 5. Engineering a Java ILT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1375.1 Terminology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1385.2 Planning and design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

5.2.1 Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1395.2.2 CIM class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1395.2.3 ILT class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1405.2.4 Provider class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1405.2.5 Component reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

5.3 Implementing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1425.3.1 Managed Object Format (MOF) . . . . . . . . . . . . . . . . . . . . . . . . . . . 1435.3.2 ILT Java class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1455.3.3 Provider Java class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

iv IBM Tivoli Monitoring: Creating Resource Models and Providers

5.3.4 Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1615.4 Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

5.4.1 Testing and importing the MOF. . . . . . . . . . . . . . . . . . . . . . . . . . . . 1705.4.2 Java compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1715.4.3 Making the jar file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1735.4.4 Assembling the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . 1735.4.5 Building the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

5.5 ITSO_Sample template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1765.5.1 ITSO_Sample.mof. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1765.5.2 ITSO_SampleIlt.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1785.5.3 ITSO_Sample.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1925.5.4 Resource Model JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Chapter 6. Creating an SNMP Resource Model for Windows . . . . . . . . . 2016.1 Designing the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

6.1.1 Design overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2026.1.2 What part of ITM will we use? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2036.1.3 Detailed design Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . 204

6.2 Creating the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2056.2.1 Installing SNMP and WMI SNMP on the managed machine . . . . . 2056.2.2 Creating the new SNMP Resource Model . . . . . . . . . . . . . . . . . . . 2116.2.3 Packaging the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . 2216.2.4 Testing the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

6.3 ITSO_SNMP_Interface_Bps source code. . . . . . . . . . . . . . . . . . . . . . . . 2256.3.1 ITSO_SNMP_Interface_Bps.vba . . . . . . . . . . . . . . . . . . . . . . . . . . 225

Chapter 7. Creating an SNMP Resource Model for Java . . . . . . . . . . . . . 2317.1 Terminology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2327.2 Planning and design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

7.2.1 Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2337.2.2 CIM class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2337.2.3 ILT class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2347.2.4 Provider class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2357.2.5 Component reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

7.3 Implementing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2367.3.1 Managed object format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2377.3.2 ILT Java class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2397.3.3 Provider Java class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2497.3.4 Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

7.4 Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2707.4.1 Testing and importing the MOF. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2707.4.2 Java compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2717.4.3 Making the jar file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Contents v

7.4.4 Assembling the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . 2747.4.5 Building the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

7.5 ITSO_SnmpProbe source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2777.5.1 ITSO_SnmpProbe.mof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2777.5.2 ITSO_SnmpProbeILT.Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2787.5.3 ITSO_SnmpProbe.Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2927.5.4 SnmpInterface.Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3007.5.5 Resource Model JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

Chapter 8. Creating a log-file Resource Model . . . . . . . . . . . . . . . . . . . . . 3058.1 Engine component utilization: Overview . . . . . . . . . . . . . . . . . . . . . . . . . 3068.2 Creating the MOF files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3078.3 Compiling the MOF file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3098.4 Creating the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3168.5 Constructing the Resource Model: Events . . . . . . . . . . . . . . . . . . . . . . . 3258.6 Constructing the Resource Model: Dependencies . . . . . . . . . . . . . . . . . 3278.7 Constructing the Resource Model: Inserting code . . . . . . . . . . . . . . . . . 3288.8 The flow of the code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

Chapter 9. Creating a log-file Resource Model and ILT . . . . . . . . . . . . . . 3339.1 Designing the ITSO_LogfileLite Resource Model and ILT . . . . . . . . . . . 334

9.1.1 Design overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3349.1.2 What part of ITM will we use? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3369.1.3 The detailed design of the ITSO_LogfileLite Resource Model . . . . 338

9.2 Creating the ITSO_LogfileLite Resource Model and ILT. . . . . . . . . . . . . 3419.2.1 Setting up the development environment . . . . . . . . . . . . . . . . . . . . 3419.2.2 Creating the MOF file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3439.2.3 Creating the ITSO_LogfileLite ILT code . . . . . . . . . . . . . . . . . . . . . 3459.2.4 Creating the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3589.2.5 Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3759.2.6 Testing the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

9.3 ITSO_LogfileLite source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3849.3.1 ITSO_LogfileLite.mof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3849.3.2 ITSO_LogfileLite-wmi.mof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3859.3.3 ITSO_LogfileLiteILT.java. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3859.3.4 ITSO_LogfileLite.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4019.3.5 ITSO_LogfileLite_RM.js . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405

Chapter 10. Creating a custom script Resource Model . . . . . . . . . . . . . . 41110.1 Designing the ITSO_ProcessNum Resource Model . . . . . . . . . . . . . . . 412

10.1.1 Design overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41210.1.2 What part of ITM will we use? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41210.1.3 The detailed design of the ITSO_ProcessNum Resource Model . 413

10.2 Creating a custom script Resource Model . . . . . . . . . . . . . . . . . . . . . . 416

vi IBM Tivoli Monitoring: Creating Resource Models and Providers

10.2.1 Using the wizard to create a custom script Resource Model . . . . 41610.2.2 Extending the functions of the Resource Model . . . . . . . . . . . . . . 42110.2.3 Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43210.2.4 Testing the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434

10.3 ITSO_ProcessNum source code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44210.3.1 ITSO_ProcessNum.js . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44210.3.2 ITSO_ProcessNum.ksh. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446

Chapter 11. File monitoring Resource Model example . . . . . . . . . . . . . . 44711.1 Engine component utilization: Overview . . . . . . . . . . . . . . . . . . . . . . . . 44811.2 Compiling DMXFile MOF into Workbench. . . . . . . . . . . . . . . . . . . . . . . 449

11.2.1 Extraction of MOF from DMXFile resource monitor . . . . . . . . . . . 44911.2.2 Strip UNIX control characters from the MOF file . . . . . . . . . . . . . . 45011.2.3 Extraction of dependencies from the DMXFile resource monitor . 45011.2.4 Compiling the MOF file to the CIM repository . . . . . . . . . . . . . . . . 450

11.3 Constructing the Resource Model: Dynamic Model . . . . . . . . . . . . . . . 45911.3.1 Constructing the Resource Model: Events . . . . . . . . . . . . . . . . . . 46411.3.2 Constructing the Resource Model: Parameters . . . . . . . . . . . . . . 46711.3.3 Constructing the Resource Model: Dependencies . . . . . . . . . . . . 46911.3.4 Constructing the Resource Model: Inserting code . . . . . . . . . . . . 47011.3.5 The flow of the code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476

Part 3. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479

Appendix A. Testing a Java Resource Model . . . . . . . . . . . . . . . . . . . . . . 481ITM Engine tracing and clean-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482Debugging the Init function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483Debugging the VisitTree function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486Simulating data Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487Verifying the Resource Model logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490

Appendix B. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495

System requirements for downloading the Web material . . . . . . . . . . . . . 496How to use the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496

Abbreviations and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497

Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499Other publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499

Contents vii

How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503

viii IBM Tivoli Monitoring: Creating Resource Models and Providers

Figures

1-1 High level architecture view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51-2 ITM data flow diagram: all platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71-3 Windows LCFD directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101-4 Windows ITM directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111-5 UNIX directory structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131-6 Java ITM on UNIX directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . 141-7 ITM Engine components for Windows . . . . . . . . . . . . . . . . . . . . . . . . . . 161-8 ITM Engine components for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171-9 Engine sub-components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201-10 Graph of holes and occurrences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222-1 Introduction of the Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262-2 Panes in the Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272-3 TMW_PhsyicalDiskModel general settings . . . . . . . . . . . . . . . . . . . . . . 292-4 Example of descriptive name in a profile . . . . . . . . . . . . . . . . . . . . . . . . 302-5 PhysicalDiskModel general settings . . . . . . . . . . . . . . . . . . . . . . . . . . . 312-6 Opening the CIM browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322-7 PhysicalDisk resource class definitions . . . . . . . . . . . . . . . . . . . . . . . . . 332-8 Profile indications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352-9 TMW_SlowPhysicalDrive event element settings . . . . . . . . . . . . . . . . . 362-10 PhysicalDiskModel thresholds in a profile . . . . . . . . . . . . . . . . . . . . . . . 382-11 PhysicalDiskModel HighPercentUsage threshold profile display . . . . . . 392-12 PhysicalDiskModel logging element profile display . . . . . . . . . . . . . . . . 402-13 PhysicalDiskModel percent disk usage element profile display . . . . . . . 412-14 Creating a Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472-15 Selecting JavaScript or Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . 472-16 Selecting the wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482-17 Selecting the data source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502-18 Connecting to namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512-19 Selecting a CIM class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522-20 Selecting properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532-21 Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542-22 Specifying the event trigger condition . . . . . . . . . . . . . . . . . . . . . . . . . . 552-23 Entering the trigger condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562-24 Selecting the properties to log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572-25 Cycle time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582-26 Saving the source file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582-27 Building the package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592-28 Building the TEC BAROC file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

© Copyright IBM Corp. 2003. All rights reserved. ix

2-29 Copying the package file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613-1 Logical components of the Resource Model . . . . . . . . . . . . . . . . . . . . . 693-2 Sampling of volatile metric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713-3 Physical components in the Resource Model . . . . . . . . . . . . . . . . . . . . 744-1 IT management methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1104-2 Management technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1134-3 JMX MBean server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1174-4 Management agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1194-5 ITM Engine Logical Components (Java) . . . . . . . . . . . . . . . . . . . . . . . 1214-6 Common logical components for Windows and Java . . . . . . . . . . . . . 1224-7 ITM Engine Logical Components (Windows) . . . . . . . . . . . . . . . . . . . . 1244-8 Logical components for Windows COM support . . . . . . . . . . . . . . . . . 1254-9 Logical components for Windows WMI native support . . . . . . . . . . . . 1274-10 Logical components for Windows and Java custom scripts. . . . . . . . . 1284-11 Logical components for Windows and Java DM Classic . . . . . . . . . . . 1284-12 Logical components for Windows and Java ILTs. . . . . . . . . . . . . . . . . 1325-1 Java ITM Engine logical components . . . . . . . . . . . . . . . . . . . . . . . . . 1425-2 ITM Workbench: about selected class . . . . . . . . . . . . . . . . . . . . . . . . . 1445-3 ITM Workbench: General Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1615-4 ITM Workbench: Dynamic Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1625-5 ITM Workbench: parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1645-6 ITSO_Sample.tar: Resource Model Tar File . . . . . . . . . . . . . . . . . . . . 1705-7 mofcomp output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1715-8 javac output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1725-9 javac output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1725-10 jar output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1735-11 ITM Workbench: Tree view pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1745-12 ITM Workbench: Build menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1755-13 ITM Workbench: Save As . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1756-1 Design overview of ITSO_SNMP_Interface_Bps Resource Model . . . 2026-2 ITM Engine logical components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2046-3 Installing Optional Networking Components . . . . . . . . . . . . . . . . . . . . 2066-4 Installing the SNMP Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2076-5 Enabling SNMP Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2086-6 Installing the WMI SNMP Provider. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2106-7 Connect to namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2116-8 Browse for Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2126-9 Browse for Namespace to localhost . . . . . . . . . . . . . . . . . . . . . . . . . . 2136-10 Selecting a class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2146-11 Selecting properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2156-12 Collection test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2166-13 Filter condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2166-14 Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

x IBM Tivoli Monitoring: Creating Resource Models and Providers

6-15 Entering the trigger condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2186-16 Using the Proc drop down selector . . . . . . . . . . . . . . . . . . . . . . . . . . . 2196-17 Resource Model Tar File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2226-18 Step to cursor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2236-19 Quick Watch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2236-20 Debugging the Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2247-1 Java: ITM logical components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2367-2 ITM Workbench: About selected class. . . . . . . . . . . . . . . . . . . . . . . . . 2387-3 ITM Workbench: General Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2637-4 ITM Workbench: Dynamic Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2647-5 ITM Workbench: Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2657-6 ITSO_SnmpProbe.tar: Resource Model Tar File . . . . . . . . . . . . . . . . . 2707-7 mofcomp output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2717-8 SnmpInterface.java: javac output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2727-9 ITSO_SnmpProbe.java: javac output. . . . . . . . . . . . . . . . . . . . . . . . . . 2727-10 ITSO_SnmpProbeILT.java: javac output . . . . . . . . . . . . . . . . . . . . . . . 2737-11 jar output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2747-12 ITM Workbench: Tree view pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2757-13 ITM Workbench: Build menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2767-14 ITM Workbench: Save As dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2778-1 Resource Model sub-components for Windows . . . . . . . . . . . . . . . . . 3068-2 Resource Model sub-components for Java . . . . . . . . . . . . . . . . . . . . . 3078-3 Workbench new Resource Model window . . . . . . . . . . . . . . . . . . . . . . 3098-4 Select VBA or JavaScript language . . . . . . . . . . . . . . . . . . . . . . . . . . . 3098-5 Workspace selection window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3108-6 Select data source window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3118-7 Connect to namespace window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3118-8 Username/password selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3128-9 Select a Class window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3128-10 MOF compiler action select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3138-11 MOF file path and namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3148-12 MOF compiler wizard update options window . . . . . . . . . . . . . . . . . . . 3158-13 MOF compile results window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3158-14 Resource Model Wizard: Select a Class window. . . . . . . . . . . . . . . . . 3168-15 Resource Model Wizard: Select Properties window . . . . . . . . . . . . . . 3178-16 Resource Model Wizard: Filtering window. . . . . . . . . . . . . . . . . . . . . . 3188-17 Resource Model Wizard: Specify the Event Triggering Conditions . . . 3198-18 Resource Model Wizard: Select the Properties to log window . . . . . . 3208-19 Resource Model cycle time data entry panel . . . . . . . . . . . . . . . . . . . . 3208-20 IBM Tivoli Monitoring Workbench main window . . . . . . . . . . . . . . . . . 3218-21 Dynamic Model data entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3228-22 Dynamic Model data entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3238-23 Dynamic Model data entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

Figures xi

8-24 IBM Tivoli Monitoring Workbench main window . . . . . . . . . . . . . . . . . 3258-25 Event construction window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3268-26 IBM Tivoli Monitoring Workbench main window . . . . . . . . . . . . . . . . . 3278-27 IBM Tivoli Monitoring Workbench main window . . . . . . . . . . . . . . . . . 3289-1 Design overview of ITSO_LogfileLite Resource Model . . . . . . . . . . . . 3359-2 Windows ITM Engine Logical Components . . . . . . . . . . . . . . . . . . . . . 3379-3 UNIX ITM Engine Logical Components . . . . . . . . . . . . . . . . . . . . . . . . 3379-4 Flowchart of ITSO_LogfileLite decision tree script. . . . . . . . . . . . . . . . 3409-5 Setting the CLASSPATH environment variable . . . . . . . . . . . . . . . . . . 3429-6 The relationship of the methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3459-7 Creating a new Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3589-8 Selecting data source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3599-9 Connect to namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3599-10 Launching the MOF Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3609-11 Selecting a MOF file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3619-12 Completing the compile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3619-13 Selecting the class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3629-14 Trigger condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3639-15 Property of the ITSO_LogfileLite Resource Model . . . . . . . . . . . . . . . 3649-16 Setting the alias name of the CIM class. . . . . . . . . . . . . . . . . . . . . . . . 3659-17 Changing the event setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3669-18 Changing the threshold setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3679-19 Adding the ITSO_LogfileLite_Pattern parameter . . . . . . . . . . . . . . . . . 3689-20 Adding the ITSO_LogfileLite_FileName parameter . . . . . . . . . . . . . . . 3689-21 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3709-22 Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3759-23 Category and Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3779-24 Parameter ITSO_LogfileLite_FileName . . . . . . . . . . . . . . . . . . . . . . . . 3789-25 Parameter ITSO_LogfileLite_Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . 3799-26 Event ITSO_LogfileLite_EventNum_too_high . . . . . . . . . . . . . . . . . . . 38010-1 Design overview of ITSO_ProcessNum Resource Model . . . . . . . . . . 41210-2 ITM Engine Logical Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41310-3 Flowchart of ITSO_ProcessNum Resource Model . . . . . . . . . . . . . . . 41510-4 Creating a new ITM Workbench project. . . . . . . . . . . . . . . . . . . . . . . . 41710-5 Selecting data source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41810-6 Importing the custom script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41910-7 Trigger condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42010-8 Saving the Resource Model file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42110-9 ITM Workbench thermometer icon. . . . . . . . . . . . . . . . . . . . . . . . . . . . 42210-10 Changing properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42310-11 Opening the event setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42410-12 Changing the event setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42510-13 Changing the threshold setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427

xii IBM Tivoli Monitoring: Creating Resource Models and Providers

10-14 Adding the parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42810-15 Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43310-16 Category and Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43510-17 Parameter of the ITSO_ProcessNum . . . . . . . . . . . . . . . . . . . . . . . . . 43610-18 Event I of the ITSO_ProcessNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43711-1 Resource Model sub-components for Windows . . . . . . . . . . . . . . . . . 44811-2 Resource Model sub-components for Java . . . . . . . . . . . . . . . . . . . . . 44911-3 Workbench new Resource Model window . . . . . . . . . . . . . . . . . . . . . . 45111-4 Select VBA or JavaScript language . . . . . . . . . . . . . . . . . . . . . . . . . . . 45111-5 Workspace selection window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45211-6 Select data source window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45311-7 Connect to namespace window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45311-8 Browse For Namespace window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45411-9 Username/password selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45411-10 Select a class window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45511-11 MOF compiler action select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45611-12 MOF file path and namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45711-13 MOF compiler wizard update options window . . . . . . . . . . . . . . . . . . . 45811-14 MOF compile successful results window . . . . . . . . . . . . . . . . . . . . . . . 45811-15 MOF compile error results window . . . . . . . . . . . . . . . . . . . . . . . . . . . 45911-16 Resource Model Wizard: Select a Class window. . . . . . . . . . . . . . . . . 46011-17 Resource Model wizard properties selection window . . . . . . . . . . . . . 46111-18 Resource Model wizard triggering conditions selection window . . . . . 46211-19 Resource Model wizard filtering selection window. . . . . . . . . . . . . . . . 46311-20 Resource Model cycle time data entry panel . . . . . . . . . . . . . . . . . . . . 46311-21 IBM Tivoli Monitoring Workbench main window . . . . . . . . . . . . . . . . . 46411-22 Event construction window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46511-23 Event construction window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46611-24 IBM Tivoli Monitoring Workbench main window . . . . . . . . . . . . . . . . . 46711-25 Parameter data entry window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46811-26 Parameter data entry window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46811-27 IBM Tivoli Monitoring Workbench main window . . . . . . . . . . . . . . . . . 46911-28 IBM Tivoli Monitoring Workbench main window . . . . . . . . . . . . . . . . . 470A-1 The Quadcap Embeddable Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 489A-2 Opening the database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490

Figures xiii

xiv IBM Tivoli Monitoring: Creating Resource Models and Providers

Tables

2-1 Supported Resource Model type per operating system. . . . . . . . . . . . . 473-1 Resource Model types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753-2 Windows Resource Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783-3 UNIX Resource Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803-4 OS/400 Resource Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823-5 Memory Resource Model dependencies . . . . . . . . . . . . . . . . . . . . . . . . 853-6 Network Interface Card Resource Model dependencies . . . . . . . . . . . . 873-7 Parametric event log Resource Model dependencies . . . . . . . . . . . . . . 903-8 Parametric Services Resource Model dependencies . . . . . . . . . . . . . . 903-9 Parametric TCP/IP Ports Resource Model dependencies . . . . . . . . . . . 913-10 Logical Disk Resource Model dependencies . . . . . . . . . . . . . . . . . . . . . 913-11 Physical Disk Resource Model dependencies . . . . . . . . . . . . . . . . . . . . 923-12 Printing Resource Model dependencies . . . . . . . . . . . . . . . . . . . . . . . . 933-13 Process Resource Model dependencies . . . . . . . . . . . . . . . . . . . . . . . . 943-14 Processor Resource Model dependencies . . . . . . . . . . . . . . . . . . . . . . 953-15 Services Resource Model dependencies. . . . . . . . . . . . . . . . . . . . . . . . 963-16 TCP/IP Resource Model dependencies. . . . . . . . . . . . . . . . . . . . . . . . . 973-17 Table of correlated indications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 983-18 CPU Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003-19 Memory Resource Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003-20 File Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1013-21 Process Resource Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1023-22 Network Interface Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . 1033-23 File system Resource Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1043-24 Security Resource Model and file monitoring: Part 1 . . . . . . . . . . . . . . 1053-25 Security Resource Model and file monitoring: Part 2 . . . . . . . . . . . . . . 1063-26 Network RPC/NFS Resource Model (Sun Solaris specific) . . . . . . . . . 1075-1 ILT supported classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1535-2 CIM class properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1636-1 The indication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2046-2 List of elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2057-1 CIM class properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2649-1 The parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3389-2 The indication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3389-3 A list of elements of the ITSO_LogfileLite Resource Model. . . . . . . . . 3389-4 Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3449-5 An example of the values of the properties . . . . . . . . . . . . . . . . . . . . . 3449-6 Operations in the ITSO_LogfileLite ILT . . . . . . . . . . . . . . . . . . . . . . . . 346

© Copyright IBM Corp. 2003. All rights reserved. xv

9-7 Operations in the ITSO_LogfileLite Provider . . . . . . . . . . . . . . . . . . . . 3539-8 The event of ITSO_LogfileLite_EventNum_too_high. . . . . . . . . . . . . . 3669-9 The threshold definition for Thr_EventNum_gt . . . . . . . . . . . . . . . . . . 3679-10 Dependency files for each platform . . . . . . . . . . . . . . . . . . . . . . . . . . . 3699-11 Summary of the useful trace and log files . . . . . . . . . . . . . . . . . . . . . . 38210-1 The parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41410-2 The indication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41410-3 A list of elements of the ITSO_ProcessNum Resource Model . . . . . . 41410-4 The event of Ev_process_num_becomes_very_high . . . . . . . . . . . . . 42510-5 The event of Ev_process_num_becomes_high . . . . . . . . . . . . . . . . . . 42610-6 The event definition for Ev_process_num_becomes_low . . . . . . . . . . 42610-7 The threshold definition for Ev_process_num_becomes_veryhigh . . . 42710-8 The threshold definition for Ev_process_num_becomes_high . . . . . . 42810-9 The threshold definition for Ev_process_num_becomes_low . . . . . . . 42810-10 ITSO_ProcessNum Resource Model scenarios . . . . . . . . . . . . . . . . . 438A-1 Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490A-2 RmProfiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491A-3 Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491A-4 Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491A-5 Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492A-6 Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492A-7 MetricsData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492A-8 CategoriesData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493

xvi IBM Tivoli Monitoring: Creating Resource Models and Providers

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.

© Copyright IBM Corp. 2003. All rights reserved. xvii

TrademarksThe 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 IBM Tivoli Monitoring: Creating Resource Models and Providers

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 redbookThis 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

© Copyright IBM Corp. 2003. All rights reserved. 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 BlatchleyInternational Technical Support Organization, Austin Center

Wade AllenSoftware Developer, IBM Software Group

Kevin P. FergusonSoftware Developer, IBM Software Group

Steve GutierrezSoftware Developer, IBM Software Group

Jason HooperSenior Software Engineer, IBM Software Group

Bill HorneSoftware Developer, IBM Software Group

Richard F. ReedSystems Integrator Consultant, IBM Software Group

xx IBM Tivoli Monitoring: Creating Resource Models and Providers

Theo WinkelmannTechnical Evangelist, IBM Software Group

Become a published authorJoin 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 welcomeYour 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:

[email protected]

� Mail your comments to:

IBM Corporation, International Technical Support OrganizationDept. JN9B Building 003 Internal Zip 283411400 Burnet RoadAustin, Texas 78758-3493

Preface xxi

http://www.redbooks.ibm.com/residencies.html

http://www.redbooks.ibm.com/residencies.html

http://www.redbooks.ibm.com/

http://www.ibm.com/redbooks/


http://www.redbooks.ibm.com/contacts.html

xxii IBM Tivoli Monitoring: Creating Resource Models and Providers

Part 1 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

Part 1

© Copyright IBM Corp. 2003. All rights reserved. 1

2 IBM Tivoli Monitoring: Creating Resource Models and 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.1 OverviewIBM 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 architectureFigure 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.


Figure 1-1 High level architecture view

1.3 Engine features and abilitiesITM 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

DesignCreateDebug

Resource

Model

TMRTMR

Install

Defaults

Profile

Get Data

DisplayWeb Health

Console

Customize/Distribute

EndpointWindows NT/2000

EndpointUnix/Linux

ITMHeartBeat

ITM EngineITM Engine

Distribute

Data Warehouse

Rollup

Trend Analysis

Workbench

Design, Create, Debug

TMRTMR

Install

DefaultsProfile

Get Data

Display Web Health Console

Customize/Distribute

ITMHeartBeat

Distribute

Data WarehouseRollup

Trend Analysis

Workbench

Tivoli Event Console EndpointUnix/Linux

ITM EngineEndpointWindows NT/2000

ITM Engine

Resource

Model

Chapter 1. IBM Tivoli Monitoring architecture 5

� Event correlation (Windows® only)

� Event aggregation

� Event management

� Data logging

The engine’s 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 engine’s 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 Microsoft®’s implementation of CIM, Windows Management Instrumentation (WMI). The UNIX® component of CIM is provided via IBM Tivoli’s own CIM implementation, which is called Touchpoint.

1.4 Endpoint integrationThere 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 flowIt 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.


Figure 1-2 ITM data flow diagram: all platforms

Platform Specific CIM Implementations

Reference s ITM Logical Diagrams:Touchpoint (Java)

-or-WMI (Windows)

ITM Engine

Resources (OS & Applications)

EventHandling

Analyzer

TMWService(Java Class)

1

2

3

4

5

ITM

Eng

ine

LCF

TM

E

Data Flow

Provider Layer


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 façade 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 façade 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 layerThe 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.

ResourcesResources 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 structuresWhen 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 platformFigure 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.


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


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 UNIXFigure 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.


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


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


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 architectureFigure 1-7 on page 16 highlights the logical components that comprise the Windows platform ITM Engine.


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.

Windows, ITM Engine Logical ComponentsAnalyzer


TMWService

WMI APIs

WMI (CIMOM)

ILT Manager for Java (WMI Provider DLL)

JMX ILTILT

Launch (Class Loader)

MBeanServer

MBean1Resource Resource Resource

WM

I P

rovi

der

DLL

s

Resource

Java Virtual Machine (JVM)

Resource

Providers

CO

M O

bjec

ts

DM

Cla

ssic

Mon

itor

Pro

bes

Cus

tom

Scr

ipts

ILT

JNI

BinaryLibrary

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

Provider


Figure 1-8 ITM Engine components for Java

1.5.1 Engine inputTo 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 endpoint’s 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

Java, ITM Engine Logical ComponentsAnalyzer


Service Object

ILT


NativeBinariesResource Resource Resource

Providers

DM

Cla

ssic

Mon

itor

Pro

bes

Cus

tom

Scr

ipts

JMX ILT

MBeanServer

MBean(s)

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

Java Class Loader

ILT

JNI

Provider


� 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 componentEvery 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 thresholdsEach 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.

ParametersWhile 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.


DependenciesWhen 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 outputWhen 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.

EventsThe 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 dataThe 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 Microsoft’s 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 logsAs 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.


� 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 componentsThe 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.

Figure 1-9 Engine sub-components

ITM5.1.1 Engine ComponentsAnalyzer

Interpreter

Service Object(COM orJava) Scheduler

Decision Tree(VBA or JS) TEC or TBSM

EventAggregator

Correlator(Windows

Only)

ActionManager Logger

CIM Implementation

System Resources(CPU, Memory, Disks etc)

Providers - ILTs

BackOffice Applications

Providers - ILTs


SchedulerAny 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 scheduler’s 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

AnalyzerThe 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 aggregatorWhen 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


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.

Figure 1-10 Graph of holes and occurrences

Event correlatorThere 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.

LoggerThe 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.

time

met

ri c v

a lue

s

. .. .

threshold

Indication #1 Ind ication #2

Indication #3Indication #4

Max # o f holes is 1 and they are not consecutive

2 consecutive holes

Clearing event}

Cycle Time


Action managerThis 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 layerThe 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.


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

2


2.1 IntroductionThe 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.

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 Developer’s 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.

Workbench

Source File.dmws

.dmjsws

Package.tar

BAROC.baroc

copy wdmrmcommand

wrbcommand

Package.tar

BAROC.baroc

ITM

TEC

Edit

BuildRegister

Workbench PC TMR Server


http://www-3.ibm.com/software/tivoli/info/pa/monitor/index.jsp

2.2 Using WorkbenchBefore 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 panesThe 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 model’s 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 ModelsUsing 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 PhysicalDiskModelIn this section, we describe how you can view each elements by using the PhysicalDiskModel.


The properties of the PhysicalDiskModelTo 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.

Descriptive name 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.


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.

Category internal name 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.

Category descriptive name 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.


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.

Figure 2-5 PhysicalDiskModel general settings

Major and minor version This is the internal version of the Resource Model.

Supported platforms 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 PhysicalDiskModelThe 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).

' General info section'<<GENERAL_INFO>>Svc.SetModelName "TMW_PhysicalDiskModel"Svc.SetProfileName "411749921"Svc.SetCategory "Windows"Svc.SetCycleTime 120'<<\GENERAL_INFO>>


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.


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.

Collection info This is used to optionally set sort options for data that may need to be in sorted order.

Filtering 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


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,PercentDiskReadTime,AvgDiskReadQLength,DiskReadBytesSec,DiskReadsSec,DiskBytesSec,CurrentDiskQLength,AvgDiskQLength,PercentDiskTime,AvgDiskWriteQLength,DiskWritesSec,DiskWriteBytesSec", "PhysicalDisk", "None", "", 0, 1'<<\DATA_INFO>>

The event element of the PhysicalDiskModelThe 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.


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.


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.

Attributes 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.


Aggregation settingsThis 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.

String resources 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.

Actions 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.

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,DiskReadBytesSec,DiskWriteBytesSec", "PhysicalDisk"'<<\EVENTS_INFO>>


The threshold element of the PhysicalDiskModelThe 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.


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).

Default value This is the default value associated with the internal name. The HighQLength is 3 by default.

Descriptive name This is the name that is used for the IBM Tivoli Monitoring profile display, as seen in Figure 2-10 on page 38.

Description This is used for documentation purposes.

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.000000Svc.DefineThreshold "HighQLength", 3.000000Svc.DefineThreshold "HighPercentUsage", 90.000000'<<\THRESHOLDS_INFO>>


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.


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.

Resource 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.

Properties 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.

The decision tree script of the PhysicalDiskModelAs 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


� 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 Microsoft’s WMI to retrieve CIM data. WMI is Microsoft’s 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.

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 Public Function VisitTree(Svc As Object) As Long2 Dim numAvgQLength As Long, numCurrentDiskQLength As Long, numAvgReadQLength As Long3 Dim numAvgWriteQLength As Long, bytDiskReadBytesSec As Long, bytDiskWriteBytesSec As Long4 Dim numDiskReadsSec As Long, numDiskWritesSec As Long, numDiskXfersSec As Long5 Dim numDiskBytesSec As Long, numPercentDiskTime As Long, numPercentDiskReadTime As Long6 Dim numPercentDiskWriteTime As Long, numTotalDisks As Long, flagHighPhysicalQLength As Long7 Dim flagHighPhysicalXferRate As Long, flagHighPhysicalReadRate As Long,8 flagHighPhysicalWriteRate As Long9 Dim flagHighPhysicalPercentTime As Long, i As Long10 Dim strPhysicalDisk As String1112 i = 0

Note: Remember the event aggregator is not in the decision tree code. It is part of the IBM Tivoli Monitoring engine.


1314 numTotalDisks = Svc.GETNUMOFINST(“TMW_PhysicalDisk”)15 16 Do While i < numTotalDisks17 flagHighPhysicalQLength = 018 flagHighPhysicalXferRate = 019 flagHighPhysicalReadRate = 020 flagHighPhysicalWriteRate = 021 flagHighPhysicalPercentTime = 02223 strPhysicalDisk = Svc.GetStrProperty(“TMW_PhysicalDisk”, i, “PhysicalDisk”)2425 If strPhysicalDisk <> “_Total” Then26 strPhysicalDisk = Mid$(strPhysicalDisk, 1, 1)27 bytDiskReadBytesSec = Svc.GetNumProperty(“TMW_PhysicalDisk”, i, “DiskReadBytesSec”)28 bytDiskWriteBytesSec = Svc.GetNumProperty(“TMW_PhysicalDisk”, i,39 “DiskWriteBytesSec”)30 numDiskReadsSec = Svc.GetNumProperty(“TMW_PhysicalDisk”, i, “DiskReadsSec”)31 numDiskWritesSec = Svc.GetNumProperty(“TMW_PhysicalDisk”, i, “DiskWritesSec”)32 numCurrentDiskQLength = Svc.GetNumProperty(“TMW_PhysicalDisk”, i,33 “CurrentDiskQLength”)34 numAvgQLength = Svc.GetNumProperty(“TMW_PhysicalDisk”, i, “AvgDiskQLength”)35 numAvgReadQLength = Svc.GetNumProperty(“TMW_PhysicalDisk”, i, “AvgDiskReadQLength”)36 numAvgWriteQLength = Svc.GetNumProperty(“TMW_PhysicalDisk”, i,37 “AvgDiskWriteQLength”)38 numDiskBytesSec = Svc.GetNumProperty(“TMW_PhysicalDisk”, i, “DiskBytesSec”)39 bytDiskReadBytesSec = Svc.GetNumProperty(“TMW_PhysicalDisk”, i, “DiskReadBytesSec”)40 bytDiskWriteBytesSec = Svc.GetNumProperty(“TMW_PhysicalDisk”, i,41 “DiskWriteBytesSec”)42 numPercentDiskTime = Svc.GetNumProperty(“TMW_PhysicalDisk”, i, “PercentDiskTime”)43 numPercentDiskReadTime = Svc.GetNumProperty(“TMW_PhysicalDisk”, i,44 “PercentDiskReadTime”)45 numPercentDiskWriteTime = Svc.GetNumProperty(“TMW_PhysicalDisk”, i,46 “PercentDiskWriteTime”)4748 'Log instance data stuff49 Svc.LogInst “Percent Disk Usage”, “PhysicalDisk”, numPercentDiskReadTime,50 strPhysicalDisk51 Svc.LogInst “Bytes Transferred”, “PhysicalDisk”, numDiskBytesSec, strPhysicalDisk52 Svc.LogInst “Queue Length”, “PhysicalDisk”, numAvgQLength, strPhysicalDisk5354 If numCurrentDiskQLength > Svc.GetThreshold(“HighQLength”) Then55 flagHighPhysicalQLength = 156 End If5758 If numDiskBytesSec > Svc.GetThreshold(“HighBytesSec”) Then59 flagHighPhysicalXferRate = 160 End If61


62 If bytDiskReadBytesSec > Svc.GetThreshold(“HighBytesSec”) Then63 flagHighPhysicalReadRate = 164 End If65 66 If bytDiskWriteBytesSec > Svc.GetThreshold(“HighBytesSec”) Then67 flagHighPhysicalWriteRate = 168 End If6970 If numPercentDiskTime > Svc.GetThreshold(“HighPercentUsage”) Then71 flagHighPhysicalPercentTime = 172 End If7374 If flagHighPhysicalQLength = 1 Then75 If flagHighPhysicalXferRate = 1 Then76 Svc.SENDEVENT “TMW_SlowPhysicalDrive”, _77 numCurrentDiskQLength, _78 numPercentDiskTime, _79 numAvgQLength, _80 numAvgReadQLength, _81 numAvgWriteQLength, _82 bytDiskReadBytesSec, _83 bytDiskWriteBytesSec, _84 strPhysicalDisk85 Else8687 Some code deleted8889 i = i + 190 Loop91 VisitTree = 092 End Function

Let us examine the code in Example 2-4 on page 42:

� Line 1

This is the VisitTree function definition.

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);}


� Line 2–10

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 26–45. 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 48–52

These lines are unconditional calls to the Svc.LogInst methods for the three logging elements defined in Figure 2-12 on page 40.


� Line 54–56

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 58–60

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 74–84

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 27–46.

� Line 89–90

This line increments and loops back to get the next instance.

� LIne 91–92

Return back to the IBM Tivoli Monitoring Version 5.1.1 engine.

2.3 Creating Resource ModelsThe 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 wizardUsing 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.


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 X X

Visual Basic X N/A


– 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.

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 wizardThe 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 ModelThis approach provides dialog boxes that guide us

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.


http://www.saxsoft.com/Basic/Details

through the procedure in the order defined in the IBM Tivoli Monitoring User’s 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 ModelUsing 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.


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 CollectionThis 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.


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.


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.


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




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.


Figure 2-22 Specifying the event trigger condition

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.

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.


Figure 2-23 Entering the trigger condition

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 #####

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.


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.


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

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).

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.


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.


Figure 2-28 Building the TEC BAROC file

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.

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 User’s Guide Version 5.1.1, SH19-4571.


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 ITMYou 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.

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.

Workbench PC TMR Server

Binary

tar file


Example 2-6 Registering the Resource Model

wdmrm -add YourRMFileName.tar

2.4 Tools and extra informationThis 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 interfaceIBM 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 resmodworkspace -bldpkg outputPackagewdmwbcli resmodworkspace -expmsgcat messagecatalogwdmwbcli resmodworkspace -expjmsgcat javamessagecatalogwdmwbcli resmodworkspace -bldtecbaroc tecbarocwdmwbcli resmodworkspace -setdep interp depfile [outputworkspace]wdmwbcli resmodworkspace -setdectree dectreefile [outputworkspace]wdmwbcli resmodworkspace -setver major minor [outputworkspace]

Where:

resmodworkspace The *.dmws of the dmjsws project file

outputPackage The output tar file

messagecatalog The output message catalog

javamessagecatalog The output Java message catalog

tecbaroc The output TEC BAROC file

interp The dependency interpreter type

depfile The dependency file name associated with the interpreter type

outputworkspace The name of the output *.dmws or *.dmjsws project file

dectreefile The decision tree file

major The Resource Model major version number


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.tarwdmwbcli ITSO_FileSystem.dmjsws -expmsgcat ITSO_FileSystem.msg

2.4.2 Microsoft toolsThe Microsoft tools are discussed in the following sections.

WMI SDKSee:





WMI ProvidersSee:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/wmisdk/wmi/managed_objects_and_providers.asp

Windows NT and 2000 Resource KitTwo 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 debuggerSee:

http://msdn.microsoft.com/downloads/default.asp?url=/downloads/topic.asp?URL=/MSDN-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/sdbug_17.asp

2.4.3 SaxsoftThe 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 RhinoJavaScript 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 shellDownload 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.





http://www.mozilla.org/rhino/

http://www.mozilla.org/rhino/download.html


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 debuggerThe 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



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.


� Resource Model overview

� Resource Models

3


3.1 Resource Model overviewIn 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 componentsThe 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.


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 ModelsThe Dynamic Model can be considered the essential element of a Resource Model. Except for the custom script Resource Model, each Resource Model

Operating System & ApplicationResources

Inte

rfac

eITM Engine

Resource Model

IndicationThreshold

Threshold

Threshold

TEC / TBSM

Occurrence / Hole

IndicationOccurrence / Hole

Cycle TimeWorkbench

Defining Resource Model- Dynamic Model- Decision Tree Script- Events / Thresholds- Parameters- Logging- Cycle Time- Dependency

Managed Server

Parameters Tivoli Desktop

DistributingProfiles

Send Events

ILTWMI

ProviderDLLs

DM

Cla

ssic

Mon

itor P

robe

s

Cus

tom

Scr

ipts WMI

(CIMOM)TSL

(CIMOM)

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.

ThresholdsEach 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.

EventsAn 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.


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.

Figure 3-2 Sampling of volatile metric

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.

time

met

ri c v

a lue

s

. .. .

threshold

Indication #1 Ind ication #2

Indication #3Indication #4

Max # o f holes is 1 and they are not consecutive

2 consecutive holes

Clearing event}

Cycle Time


ParametersWhile 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.

LoggingThe 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 scriptThe 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)


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.

DependenciesSometimes, 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 componentsThe 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.


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.

Dependencies Files

Provider(s): MOF(s):

Custom Scripts() Custom Files(s)

JavaScript -or- Visual Basic Script

Dynamic Model(s):

Reference Model Functions:

SetDefaultConfiguration(Svc)Init(Svc)

VisitTree(Svc)

Message Catalogs

Configuration File

Event(s):

Action(s):

Threshold(s):

Logging:

Resource Model Tar File

Parameter(s):


ILT / TSL Library FilesThe 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 ModelsThe 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 Requirement Supported Requirement

VBA CustomScript X N/A N/A

DM Monitor Prove

X N/A N/A

WMI Provider DLL

X N/A N/A


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.

JavaScript 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.

3.2 Resource ModelsBased 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®

JavaScript CustomScript X Windows Scripting 5.6

X JRE 1.3.X

DM Monitor Prove

X Windows Scripting 5.6

X JRE 1.3.X

Java ILT X Windows Scripting 5.6JRE 1.3.X

X JRE 1.3.X

Script type Provider Windows UNIX

Supported Requirement Supported Requirement


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 platformWe briefly describe the contents of Resource Models provided by IBM Tivoli Monitoring Version 5.1.1 for each platform.

WindowsTable 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.


Table 3-2 Windows Resource Models

Resource Model Description

Win

do

ws

NT

Win

do

ws

2000

(P

ro, S

erve

r, A

dv.

Ser

v.)

Win

do

ws

XP

(P

rofe

ssio

nal

)

Additional requirements

Memory This Resource Model highlights the memory problems: cache, available bytes, paging and so on.

X X X

Network Interface Card

This Resource Model highlights the Network Interface Problems: broadcast frames, percentage usage, and so on.

X NA

NA

SNMPNetwork Monitoring Agent

Parametric event log

This Resource Model examines the Windows Event Log for events that are specified by the user through the parameter configuration.

X X X

Parametric TCP/IP Ports

This Resource Model checks the TCP and UDP port numbers you specify.

X X X SNMP

Logical Disk This Resource Model highlights the following problems: disk usage and bytes per second transferred.

X X X diskperf



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.

X X X diskperf

Processor This Resource Model detects bottlenecks happening within or from the CPU.

X X X

Services This Resource Model looks for bottlenecks relating to the processes running on the system and highlights the high usage.

X X X

TCP/IP This Resource Model looks for bottlenecks found within the TCP/IP protocol.

X X X SNMP

EventLog This Resource Model examines the Windows Event Log for events normally require immediate attention.

X X X


Win

do

ws

NT

Win

do

ws

2000

(P

ro, S

erve

r, A

dv. S

erv.

)

Win

do

ws

XP

(P

rofe

ssio

nal

)

Additional requirements


UNIXTable 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

Resource Model

Description

AIX

®

So

lari

s

HP

-UX

Lin

ux

(Red

Hat

, Su

SE

, Tu

rbo

) fo

r In

tel®

Lin

ux

(Su

SE

) fo

r S

/390

®

Additionalrequirements

CPU This Resource Model detects problems with the CPU, such as high System Utilization.

X X X X X

File The file Resource Model gives information about files in the system.

X X X X X

File System

This Resource Model measures how efficiently the file systems are being used.

X X X X X

Memory This Resource Model provides information about how the memory is used.

X X X X X

Network Interface

The Network Interface Resource Model detects problems with the following installed network interfaces: Loopback, Ethernet, and Token-Ring.

X X X X X SNMP



OS/400Table 3-4 on page 82 summarizes the Resource Models for OS/400. They are all JavaScript based Resource Models.

Network RPC-NFS

The Network RPC-NFS Resource Model detects problems and monitors the performance ofthe RPC and NFS servers and clients.

N/A

X N/A

N/A

N/A

Process The Process Resource Model looks for bottlenecks in running processes. Problems include: process down, too much CPU time, and zombie.

X X X X X

Security The Security Resource Model provides information about files and the users logged onto thesystem and highlights the problems: resource property change, suspicious activity, and so on.

X X X X X

Resource Model

Description

AIX

®

So

lari

s

HP

-UX

Lin

ux

(Red

Hat

, Su

SE

, Tu

rbo

) fo

r In

tel®

Lin

ux

(Su

SE

) fo

r S

/390

®

Additionalrequirements


Table 3-4 OS/400 Resource Models


OS

400

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.

X

ASP Utilization 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.

X

Basic CPU Utilization This Resource Model monitors the overall CPU utilization of the system.

X

Basic Interactive CPU Utilization

This Resource Model monitors the interactive CPU utilization of the system.

X

Configuration Objects This Resource Model monitors the status of the configuration objects. The user can enter one or more configuration object names and types.

X

Database CPU Utilization The Database CPU Utilization Resource Model checks if the system is exceeding its threshold limit for database CPU utilization.

X

Distribution Queues The Distribution Queues Resource Model monitors the status of the high and normal priority service levels for distribution queues.

X

History Log This Resource Model finds specific messages in the history log.

X

Interactive Feature CPU Utilization

This Resource Model checks if the system is exceeding its threshold limit for Interactive Feature CPU utilization.

X

Job Log This Resource Model checks a job’s Job Log for specific messages. The parameters contain the message numbers and text strings to match.

X

Job Queue 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.

X

Job Status This Resource Model monitors the job status. X



3.2.2 Windows Resource ModelsEach 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.

Management Central This Resource Model monitors all Management Central events and forwards them to TEC.

X

Network Attributes This Resource Model monitors the network attributes. The user provides one or more network attribute names along with a corresponding value.

X

Output Queues The Output Queues Resource Model checks if the output queues and their writers are active.

X

Parametric Object and File This Resource Model allows you to monitor native objects and files for owner, size, and change date.

X

Storage Pools The Storage Pools Resource Model monitors and logs the metrics for storage pools.

X

Subsystem This Resource Model checks the status of a list of subsystems and sends an event if there is a subsystem that is not active.

X

System Disk Resources This Resource Model monitors the overall system resources for system and ASP utilization.

X

System Value The user inputs one or more system value names along with a corresponding value as its desired value.

X

TCP Interface This Resource Model monitors the status of one or more TCP interface.

X

TCP Service This Resource Model monitors the TCP service. X


OS

400


� 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 This indicates true, which means that the threshold has been reached or exceeded.

F This indicates false, which means the threshold has not been reached or exceeded.

Blank 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 ModelIn 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.


Table 3-5 Memory Resource Model dependencies

Thresholds

Co

rrel

atio

n

Exc

essi

ve p

age

fau

lts

Exc

essi

ve p

agin

g

Min

imu

m a

vaila

ble

byte

s

Min

imu

m c

om

mit

ted

byte

s

Low

cac

he

hit

s p

erce

nt

(mov

ing

ave

rag

e o

f...)

Cal

cula

tio

n

Properties

Indications

Cal

cula

ted

a

Co

pyR

ead

Hit

s

Dat

aMap

Hit

s

MD

LR

ead

Hit

s

Pin

Rea

dH

its

High pagingTMW_HighPaging

1 T F

Low available memoryTMW_LowAvail

T Tb

Low available causing hard pagingTMW_LowAvailCausingHardPaging

T T T F

Low available causing many problemsTMW_LowAvailCausingManyProblems

2 T T T T

Low available causing soft paging and page file resizingTMW_LowAvailCausingSoftPagePagefileResize

4T F T T

Low available memory is causing excessive soft pagingTMW_LowAvailCausingSoftPaging

T F T F

Low available with a high working setTMW_LowAvailHighWS

5 T Tc

Low available memory with a small page fileTMW_LowAvailWithSmallPageFile

T T

Low available with high cacheTMW_LowAvailHighCache

T Td


Low copy read hitsTMW_LowCopyReadHits

T

Low data map hitsTMW_LowDataMapHits

T

Low MDL read hitsTMW_LowMDLReadHits

T

Low pin read hitsTMW_LowPinReadHits

T

Memory leak in private bytesTMW_MemoryLeakInPB

5 Te

Memory leak in system codeTMW_MemoryLeakInSC

Tf

Memory leak in system driversTMW_MemoryLeakInSD

Tg

The page file is resizingTMW_PageFileResizing

F T

a. Calculated field: Commit Limit - Commit Bytes.b. Working set is larger than cache but less than available memory orworking 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.

Thresholds

Co

rrel

atio

n

Exc

essi

ve p

age

fau

lts

Exc

essi

ve p

agin

g

Min

imu

m a

vaila

ble

byt

es

Min

imu

m c

om

mitt

ed b

ytes

Low

cac

he

hit

s p

erce

nt

(mov

ing

ave

rag

e o

f...)

Cal

cula

tio

n

Properties

Indications

Cal

cula

ted

a

Co

pyR

eadH

its

Dat

aMap

Hit

s

MD

LR

ead

Hits

Pin

Rea

dH

its


Network Interface Card Resource ModelThe dependencies for the Network Interface Card (NIC) Resource Model are shown in Table 3-6.

Table 3-6 Network Interface Card Resource Model dependencies

Thresholds

Co

rrel

atio

n

Hig

h e

rro

r o

ut

rati

o

Hig

h o

utp

ut

qu

eue

Hig

h p

erce

nt

bro

adca

st

Hig

h p

erce

nta

ge

of b

ytes

per

s se

con

d

Hig

h p

erce

nt

uti

lizat

ion

Hig

h c

urr

ent

Hig

h w

ork

item

sh

ort

age

Properties

Indications

Bro

adca

stF

ram

es

Ser

ver

Red

irec

tor

Net

wo

rk In

terf

ace

Car

d

High errored ratioTMW_HighErroredRatio

T

Network Interface Card overworkedTMW_NICOverworked

3 T T

Network Interface Card too slowTMW_NICTooSlow

T F

High broadcast framesTMW_HighBroadcastFrames

T T

Adjust work itemsTMW_AdjustWorkItems

F F T

Server overloadedTMW_ServerOverloaded

T F T


High current commandsTMW_HighCurrentCommands

F F T

Redirector overloadedTMW_RedirectorOverloaded

T F T

Redirector affecting serverTMW_RedirectorAffectingServer

F F T T T

Redirector overloaded affecting segmentTMW_RedirectorOverloadedAffectingSegment

F T T T

Segment affecting redirectorTMW_SegmentAffectingRedirector

F F F T T

Segment affecting serverTMW_SegmentAffectingServer

F F F T T

Server overloaded affecting segmentTMW_ServerOverloadedAffectingSegment

F T T T

Thresholds

Co

rrel

atio

n

Hig

h e

rro

r ou

t ra

tio

Hig

h o

utp

ut q

ueu

e

Hig

h p

erce

nt b

road

cast

Hig

h p

erce

nta

ge

of

byte

s p

ers

seco

nd

Hig

h p

erce

nt u

tiliz

atio

n

Hig

h c

urr

ent

Hig

h w

ork

item

sh

ort

age

Properties

Indications

Bro

adca

stF

ram

es

Ser

ver

Red

irec

tor

Net

wo

rk In

terf

ace

Car

d


Parametric event log Resource ModelThis 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.

Server affecting redirectorTMW_ServerAffectingRedirector

F T F T T

Thresholds

Co

rrel

atio

n

Hig

h e

rro

r ou

t ra

tio

Hig

h o

utp

ut q

ueu

e

Hig

h p

erce

nt b

road

cast

Hig

h p

erce

nta

ge

of

byte

s p

ers

seco

nd

Hig

h p

erce

nt u

tiliz

atio

n

Hig

h c

urr

ent

Hig

h w

ork

item

sh

ort

age

Properties

Indications

Bro

adca

stF

ram

es

Ser

ver

Red

irec

tor

Net

wo

rk In

terf

ace

Car

d


Table 3-7 Parametric event log Resource Model dependencies

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

Parametric TCP/IP Ports Resource ModelThis 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.

Thresholds

Indications Cor

rela

tion

Win

dow

s ev

ent l

ogg

ed

NT event log occurredTMW_NTEventLogOccurred

T

Thresholds

Indications

Co

rrel

atio

n

Ser

vice

fai

ling

ser

vice

Ser

vice

sto

pp

ed s

ervi

ce

Parametric services failing serviceTMW_ParamServicesFailingService

T

Parametric services stopped serviceTMW_ParamServicesStoppedService

T


Table 3-9 Parametric TCP/IP Ports Resource Model dependencies

Logical Disk Resource ModelThe dependencies for the Logical Disk Resource Model are shown in Table 3-10.

Table 3-10 Logical Disk Resource Model dependencies

Thresholds

Indications Co

rrel

atio

n

Sta

tus

of t

he

def

ined

po

rt

Parametric Port statusTMW_ParamPortStatus

T

Thresholds

Indications

Co

rrel

atio

n

Hig

h b

ytes

per

sec

on

d

Hig

h p

erce

nt

usag

e

Hig

h q

ueu

e le

ngth

Low

dis

k sp

ace

Rea

d

Wri

te

Tota

ld

isk

High read bytes per secondTMW_HighLogicalDiskReadBytesSec

7 T F T T F

High write bytes per secondTMW_HighLogicalDiskWriteBytesSec

8 F T T T F

High transfer rateTMW_HighLogicalDiskXferRate

9 T T T T F

High percent disk timeTMW_HighLogicalPercentDiskTime

1, 2,6, 10

F T T

Logical disk possible fragmentationTMW_LogicalPossibleFrag

11 F T F


Physical Disk Resource ModelThe dependencies for the Physical Disk Resource Model are shown in Table 3-11.

Table 3-11 Physical Disk Resource Model dependencies

Slow logical driveTMW_SlowLogicalDrive

13 T T

Low logical disk spaceTMW_LowLogicalDiskSpace

4 T

Thresholds

Indications

Co

rrel

atio

n

Hig

h b

ytes

per

sec

on

d

Hig

h p

erce

nt u

sag

e

Hig

h q

ueu

e le

ng

th

Low

dis

k sp

ace

Rea

d

Wri

te

Tota

ld

isk

ThresholdsC

orr

elat

ion

Hig

h b

ytes

per

sec

on

d

Hig

h p

erce

nt u

sag

e

Hig

h q

ueu

e le

ng

th

Propertiesindications

Rea

d

Wri

te

Tota

l d

isk

High percent disk timeTMW_HighPhysicalPercentDiskTime

6,10

F T T

High transfer rateTMW_HighPhysicalDiskXferRate

9 T T T T F

High read bytes per secondTMW_HighPhysicalDiskReadBytesSec

7 T F T T F


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

High write bytes per secondTMW_HighPhysicalDiskWriteBytesSec

8 F T T T F

Physical disk possible fragmentationTMW_PhysicalPossibleFrag

11 F T F

Slow physical driveTMW_SlowPhysicalDrive

13 T T

Thresholds

Co

rrel

atio

n

Hig

h b

ytes

per

sec

on

d

Hig

h p

erce

nt

usa

ge

Hig

h q

ueu

e le

ng

th

Propertiesindications

Rea

d

Wri

te

Tota

l di

sk

Thresholds

Indications

Co

rrel

atio

n

Job

err

ors

per

day

Job

err

ors

No

t re

ady

erro

rs p

er d

ay

No

t re

ady

erro

rs

Ou

t o

f p

aper

err

ors

per

day

Ou

t o

f p

aper

err

ors

Per

cen

t p

roce

sso

r

High job errors per dayTMW_HighJobErrorsPerDay

T

High job errorsTMW_HighJobErrors

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

Processor Resource ModelThe dependencies for the Processor Resource Model are shown in Table 3-14.

High not ready errors per dayTMW_HighNotReadyErrorsPerDay

T

High not ready errorsTMW_HighNotReadyErrors

T

High out of paper errors per dayTMW_HighOutOfPaperErrorsPerDay

T

High out of paper errorsTMW_HighOutOfPaperErrors

T

High current percent timeTMW_HighCurrentPercentTime

T

Thresholds

Indications

Co

rrel

atio

n

Job

err

ors

per

day

Job

err

ors

No

t re

ady

erro

rs p

er d

ay

No

t re

ady

erro

rs

Ou

t o

f p

aper

err

ors

per

day

Ou

t o

f p

aper

err

ors

Per

cen

t p

roce

sso

r

Thresholds

Indications Co

rrel

atio

n

Hig

h C

PU

use

Max

han

dle

s Process high CPUTMW_ProcessHighCPU

12 T

Process handle leakTMW_ProcessHandleleak

T


Table 3-14 Processor Resource Model dependencies

Services Resource ModelThe 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.

Thresholds

Indications

Co

rrel

atio

n

Hig

h C

PU

usa

ge

Hig

h C

PU

usa

ge

inte

rru

pt

Hig

h C

PU

usa

ge

pro

cess

Hig

h C

PU

usa

ge

use

r p

riv

Hig

h in

terr

upts

per

sec

on

d

Hig

h p

erce

nt

usa

ge

del

ta

Tota

l CP

Us

mo

d

Busy HardwareTMW_BusyHardware

5 T T T

CPU Cannot Keep Up With HWTMW_CPUCantKeepUpWithHW

T T F T

HW Keeping CPU BusyTMW_HWKeepingCPUBusy

T T F Fa

High ProcessesTMW_HighProcesses

12 T F T

Processor BusyTMW_ProcessorBusy

T F F

High Percent Usage DeltaTMW_HighPercentUsageDelta

T

a. The processor queue length is greater than the total number of CPUs plus the TotalCPUsMod threshold.


Table 3-15 Services Resource Model dependencies

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

Thresholds

Indications Bro

wse

r

Eve

ntL

og

Net

log

on

NtL

mS

sp

Lan

man

Ser

ver

Lan

man

Wo

rkst

atio

n

Lcf

d

Any failing serviceTMW_ServicesFailingService

T

T

T

T

T

T

T

Services stopped serviceTMW_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.


Table 3-16 TCP/IP Resource Model dependencies

EventLog Resource ModelThis 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.


The driver detected a controller error on [text].


The device [name] is not ready for access yet.

Thresholds

Co

rrel

atio

n Mo

der

ate

DG

Low

seg

men

ts

Hig

h f

rag

men

t ra

tio

Hig

h s

egm

ent

retr

ansm

itte

d

Properties

Indications

Dat

agra

msr

ecei

ved

Seg

men

tsR

ecei

ved

Fra

gm

ents

Rec

eive

d,

Dat

agra

msR

ecei

ved

Seg

emen

tsR

etra

nsm

itte

d

High pingTMW_HighPing

T F

High fragment ratioTMW_HighFragRatio

T

Segments resubmittedTMW_SegmentsReXmit

3 T



The server's configuration parameter ipstacksize is too small for the server to use a local device. Please increase the value of this parameter.


The server service was unable to recreate the share name because the directory path no longer exists.


The redirector has timed out a request to [text].


The [name] service terminated with the following error: [text].

Correlated eventsCorrelated 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

1 TMW_BusyDriveFromPaging TMW_HighLogicalPercentDiskTime

TMW_HighPaging indication

2 TMW_BusyDriveFromLowAvail TMW_LowAvailCausingManyProblems

TMW_HighLogicalPercentDiskTime

3 TMW_CongestedTCPNetwork TMW_NICOverworked

TMW_SegmentsReXmit

4 TMW_CriticallyLowDiskSpace TMW_LowAvailCausingSoftPagePagefileResize

TMW_LowLogicalDiskSpace

5 TMW_CriticalMemoryLeakInWS TMW_MemoryLeakInPB

TMW_LowAvailHighWS


3.2.3 UNIX Resource ModelsThe 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 ModelThis 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.

6 TMW_FaultyDiskSubsystem TMW_HighPhysicalPercentDiskTime

TMW_BusyHardware indication


7 TMW_HighDiskReadBytesSec TMW_HighPhysicalDiskReadBytesSec

TMW_HighLogicalDiskReadBytesSec

8 TMW_HighDiskWriteBytesSec TMW_HighLogicalDiskWriteBytesSec

TMW_HighPhysicalDiskWriteBytesSec

9 TMW_HighDriveXferRate TMW_HighLogicalDiskXferRate

TMW_HighPhysicalDiskXferRate

10 TMW_HighPercentDiskTime TMW_HighPhysicalPercentDiskTime


11 TMW_PossibleFrag TMW_LogicalPossibleFrag

TMW_PhysicalPossibleFrag

12 TMW_ProcessHoggingCPU TMW_HighProcesses

TMW_ProcessHighCPU

13 TMW_SlowHardDrive TMW_SlowPhysicalDrive

TMW_SlowLogicalDrive

Generated indication Correlated indication


Table 3-18 CPU Resource Model

Memory Resource ModelThis 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

Thresholds

Per

cent

age

of

CP

U id

le

Per

cent

age

of

CP

U u

sed

by

syst

em

Properties

Indications Low

High CPU overloadLow_IdleCPUUsage

T

High CPU usage by systemHigh_SysCPUUsage

T

Thresholds

Indications Per

cen

tag

e o

f av

aila

ble

vi

rtu

al s

tora

ge

Per

cen

tag

e o

f av

aila

ble

sw

ap s

pac

e

Mem

ory

pag

e-ou

t ra

te

Mem

ory

pag

e-in

rat

e

Low storage spaceLowStorage

T

Low swap spaceLowSwap

T

System thrashingThrashing

T T


File Resource ModelThe 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

Process Resource ModelThe 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.

Thresholds

Cha

ng

e in

file

Cha

ng

e in

file

att

ribu

tes

Cha

ng

e in

CR

C

Properties

Indications

/etc

/pas

swd

/etc

/gro

up

/etc

/ho

sts

File changedFileChanged

T T T

File attributes changedFilesAttributeChange

T F

File not presentFileNotPresent

This event is generated if the file does not exist.


Table 3-21 Process Resource Model

Network Interface Resource ModelThe 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.

Thresholds

Max

zom

bie

pro

cess

es

Per

cen

t of

CP

U u

sed

Properties

Indications lcfd

sysl

ogd

High number of zombie processesHighZombieProcesses

T

Process consuming high CPUProcessHighCPU

T

Process killed or nonexistentProcessKilledOrNotExisting

Sent if a process is killed or does not exist.

Process stoppedProcessStopped

Sent for each monitored process that is stopped.


Table 3-22 Network Interface Resource Model

File system Resource ModelThis 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.

Thresholds

Per

cen

t o

f pa

cket

co

llisi

on

Ou

tpu

t p

acke

tsin

err

or

Inp

ut

pac

kets

in e

rro

r

Inte

rfac

e

Interfacestatus

Properties

Indications Toke

n R

ing

, Eth

ern

et,

or

LO

OP

BA

CK

Dow

n

UP

&N

OTR

UN

NIN

G

UN

KN

OW

N

UP

&R

UN

NIN

G

High percentage packet collisionHighPacktsCollision

T Ta T T

High output packets in errorHighOutErrorPacks

T T T T

High input packets in errorHighInputErPacks

T T T T

Interface not enabledInterfaceNotEnabled

T T

Interface not operationalInterfaceNotOperat

T T

Unknown interface statusIntStatUnknown

T T

Network Interface Card not supportedIntNotSupported

F

a. Ethernet interface only.


Table 3-23 File system Resource Model

Security Resource ModelThe 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.

Thresholds

Per

cen

tag

e o

f I-n

od

es u

sed

Per

cen

tag

e o

f Fi

le S

yste

m S

pac

e A

vaila

ble

Per

cen

tag

e o

f fil

e sy

stem

sp

ace

use

d

Ava

ilab

le s

pac

e (K

B)

Per

cen

tag

e o

f av

aila

ble

I-n

od

es

Indications

Fragmented file systemFragmentedFileSystem

T F

Low percent space availableLowPercSpcAvail

T T

Low space availableLowKAvail

T

Low percentage of available I-nodesLowPercInodesAvail

T


Table 3-24 Security Resource Model and file monitoring: Part 1

Thresholds

Spe

cial

use

rs

Def

ined

use

rs

Spe

cial

gro

ups

Alte

rnat

ive

gro

up

s

Cus

tom

log

ins

Inst

rum

enta

tio

n

Properties

Indications

UID

-1

UID

0

roo

t

Su

per

use

rs

roo

t

Su

per

gro

up

s

Nu

ll p

assw

ord

Du

plic

ated

Duplicated accountDuplicatedAccount

F F T

F F T

High log-in number for userHighLoggingNumber

F T

Suspect super groupSuspectSuperGroup

T F F

Account not valid for rootNotRegularRootAccount

F T

F F T

Null passwordPasswordNull

Ta

Suspect superuserSuspectSuperUser

T F F

a. This indicator will also happen for a group with a null password, but only for HP-UX 10 and Solaris 2 systems.


Table 3-25 Security Resource Model and file monitoring: Part 2

Network RPC/NFS Resource ModelThe 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.

Thresholds

Alt

ern

ativ

e ow

ner

s

File

gro

up

File

s to

be

mo

nito

red

Alt

ern

ativ

e g

rou

ps

File

ow

ner

File

mo

de

Properties

Indications

Mem

ber

Mat

ches

File

Exi

sts

Mem

ber

Mat

ches

Mat

ches

Illegal ownerIllegalOwner

F T F T

Illegal groupIllegalGroup

F T F T T

Wrong file modeWrongMode

T F

Nonexistent fileFileNoteExisting

F


Table 3-26 Network RPC/NFS Resource Model (Sun Solaris specific)

Thresholds

Indications

Per

cen

t of

NF

S s

erve

r re

ad o

ps

Per

cen

t of

Sev

er R

PC

dup

licat

e re

qu

ests

Per

cen

t of

Clie

nt

RP

C r

etra

nmis

sio

ns

Per

cen

t of

NF

S s

vr g

etat

tr o

per

atio

ns

Per

cen

t of

bad

RP

C c

alls

Per

cen

t of

NF

S s

vr r

ead

link

op

erat

ion

s

Per

cen

t of

clie

nt

RP

C b

adxi

ds

Per

cen

t of

clie

nt

RP

C c

alls

in t

imeo

ut

Per

cen

t of

NF

S s

vr w

rite

op

erat

ion

s

High NFS server read operationsHighNFSSrvRead

T

High duplicate RPC server callsHighPercDupReqs

T

High retransmitted callsHighPercRetrans

T

High network trafficNetworkBusy

T T

High NFS buffer sizeHighNFSBufferSize

T T

High NFS server get-attribute operationsHighNFSSrvGetattr

T

High RPC bad callsHighPercRPCBadCalls

T

Slow networkNetworkSlow

T T

High NFS server readlink operationsHighNFSSrvReadLink

T

High timeout and badxidsHighTimeoutsAnd_Badxids

T


High timeout and badxidsHighTimeoutsAnd_Badxids

T

High NFS server write operationsHighNFSSrvWrites

T

Thresholds

Indications

Per

cen

t o

f N

FS s

erve

r re

ad o

ps

Per

cen

t o

f S

ever

RP

C d

upl

icat

e re

qu

ests

Per

cen

t o

f C

lien

t R

PC

ret

ran

mis

sio

ns

Per

cen

t o

f N

FS s

vr g

etat

tr o

pera

tion

s

Per

cen

t o

f ba

d R

PC

cal

ls

Per

cen

t o

f N

FS s

vr r

ead

link

op

erat

ion

s

Per

cen

t o

f cl

ien

t R

PC

bad

xid

s

Per

cen

t o

f cl

ien

t R

PC

cal

ls in

tim

eou

t

Per

cen

t o

f N

FS s

vr w

rite

op

erat

ion

s


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.


� Overview and terminology

� Industry technologies (WBEM, CIM, and JMX specifications)

� Tivoli implementations

4


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.

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.

Fault,Configuration,Performance

ManagementApplication

Fault,Configuration,Performance

ManagedResourceDefinition

MIB MIF

Service Layer &Infrastructure

SNMP DMI

PhysicalManagedObjects

Network Devices DesktopSystems

IT Management Methods

Physical Network Desktop

ITM Engine

MOF

CIM(M12, WMI)

ManagedResource

TivoliMonitoring


– 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 technologiesTo 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.


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

Management Technologies

WBEM

ProviderLayer

Managed Resources

MOF MOF

MBean

Management Application

Tech

nolo

gies

Inte

rface

App

licat

ion

COM

JMX

WMICIMLayer



developers on different platforms to describe management data in a standard format so that it can be shared among a variety of management applications.

AssociationsUnlike 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 usageThe 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


a particular Implementation. A MOF specification can be validated for the syntactic correctness through the use of a MOF compiler.

Class declarationsA 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 declarationsClasses 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 layerThe 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.


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 ProvidersA 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 infrastructureThe 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


contrast, the WMI repository acts as a storage area for information passed in by the various Providers.

WMI management applicationsA 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 architectureThe 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


The architecture is divided into the following three levels:

� Instrumentation

� MBean

� Agent

InstrumentationJMX 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.

MBeanAn 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 resource’s 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.

AgentThe 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 servicesIn 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.


JMX-based managementRun-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 implementationsThe 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


is discussed. Finally, a brief discussion on the implementation of Java Management Bean technology is presented.

4.3.1 ITM Engine componentsThe 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.

Java-based ITM Engine overviewThe 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.

Note: For a physical component discussion, please refer to Chapter 1, “IBM Tivoli Monitoring architecture” on page 3.

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.


Figure 4-5 ITM Engine Logical Components (Java)

Common componentsThe 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.

ITM Engine Logical Components (Java)Analyzer


Service Object

ILT



Providers

DM

Cla

ssic

Mon

itor

Pro

bes

Cus

tom

Scr

ipts

JMX ILT

MBeanServer

MBean(s)

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

Java Class Loader

ILT

JNI

Provider


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.

ITM Engine Logical Components (Windows)Analyzer


TMWService

WMI APIs

WMI (CIMOM)


JMX ILTILT


MBeanServer


WM

I P

rovi

der

DLL

s

Resource


Resource

Providers

CO

M O

bjec

ts

DM

Cla

ssic

Mon

itor

Pro

bes

Cus

tom

Scr

ipts

ILT

JNI

BinaryLibrary

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

Provider



Service Object

ILT


NativeBinaries

Resource Resource Resource

Providers

DM

Cla

ssic

Mon

itor

Pro

bes

Cus

tom

Scr

ipts

JMX ILT

MBeanServer

MBean(s)

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

Java Class Loader

ILT

JNI

Provider


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 overviewThe 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


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.

Figure 4-7 ITM Engine Logical Components (Windows)

Windows ITM Engine COM supportThe 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.



TMWService

WMI APIs

WMI (CIMOM)


JMX ILTILT


MBeanServer


WM

I P

rovi

der

DLL

s

Resource


Resource

Providers

CO

M O

bjec

ts

DM

Cla

ssic

Mon

itor

Pro

bes

Cus

tom

Scr

ipts

ILT

JNI

BinaryLibrary

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

Provider


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.

Figure 4-8 Logical components for Windows COM support

Windows ITM Engine native WMI supportThe 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.



TMWService

WMI APIs

WMI (CIMOM)


JMX ILTILT


MBeanServer


WM

I P

rovi

der

DLL

s

Resource


Resource

Providers

CO

M O

bjec

ts

DM

Cla

ssic

Mon

itor

Pro

bes

Cus

tom

Scr

ipts

ILT

JNI

BinaryLibrary

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

Provider



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.

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.

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.

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/kmarch/wmi_2fjb.asp



Figure 4-9 Logical components for Windows WMI native support

4.3.2 Legacy supportThe 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 scriptsThe 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.



TMWService

WMI APIs

WMI (CIMOM)


JMX ILTILT


MBeanServer


WM

I P

rovi

der

DLL

s

Resource


Resource

Providers

CO

M O

bjec

ts

DM

Cla

ssic

Mon

itor

Pro

bes

Cus

tom

Scr

ipts

ILT

JNI

BinaryLibrary

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

Provider


Figure 4-10 Logical components for Windows and Java custom scripts

DM ClassicThe 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.

Figure 4-11 Logical components for Windows and Java DM Classic



TMWService

WMI APIs

WMI (CIMOM)


JMX ILTILT


MBeanServer


WM

I P

rovi

der

DLL

s

Resource


Resource

Providers

CO

M O

bjec

ts

DM

Cla

ssic

Mon

itor

Pro

bes

Cus

tom

Scr

ipts

ILT

JNI

BinaryLibrary

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

Provider



Service Object

ILT


NativeBinaries


Providers

DM

Cla

ssic

Mon

itor

Pro

bes

Cus

tom

Scr

ipts

JMX ILT

MBeanServer

MBean(s)

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

Java Class Loader

ILT

JNI

Provider



Service Object

ILT


NativeBinaries


Providers

DM

Cla

ssic

Mon

itor

Pro

bes

Cus

tom

Scr

ipts

JMX ILT

MBeanServer

MBean(s)

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

Java Class Loader

ILT

JNI

Provider



TMWService

WMI APIs

WMI (CIMOM)


JMX ILTILT


MBeanServer


WM

I P

rovi

der

DLL

s

Resource


Resource

Providers

CO

M O

bjec

ts

DM

Cla

ssic

Mon

itor

Pro

bes

Cus

tom

Scr

ipts

ILT

JNI

BinaryLibrary

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

Provider


4.3.3 Touchpoint Service LayerThe Touchpoint Service Layer (TSL), formally referred to as the Manageability (M12) Model Specification, is Tivoli’s 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 definitionThe 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.


QualifiersThe 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.


– 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 InterfaceThe 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.

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.


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.

enumerateInstancesThe enumerateInstances method returns all M12ObjectIdentity objects that identify all the instances belonging to the class specified in the classPath.

getPropertyThe getProperty method gets the value (in String format) of the specified property for the identified object.

getMultiplePropertiesThe getMultipleProperties method gets the value (in String format) of the specified properties for the identified object.

invokeMethodThe invokeMethod method invokes the specified method on the CIM instance belonging to the class specified in the classPath]

setPropertyThe setProperty method is not invoked yet by the ITM Engine.



TMWService

WMI APIs

WMI (CIMOM)


JMX ILTILT


MBeanServer


WM

I P

rovi

der

DLL

s

Resource


Resource

Providers

CO

M O

bjec

ts

DM

Cla

ssic

Mon

itor

Pro

bes

Cus

tom

Scr

ipts

ILT

JNI

BinaryLibrary

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

Provider



Service Object

ILT


NativeBinaries


Providers

DM

Cla

ssic

Mon

itor

Pro

bes

Cus

tom

Scr

ipts

JMX ILT

MBeanServer

MBean(s)

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

Java Class Loader

ILT

JNI

Provider


createThe create method is not invoked yet by the ITM Engine.

destroyThe 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.


http://www.alphaworks.ibm.com/tech/TMX4J

Part 2 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.

Part 2


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.

5


5.1 TerminologyMany 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 designThough 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.


5.2.1 Resource ModelThe 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 classBased 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_ui8: Property of the type 8-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 classThe 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 classThe 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.


� 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 referenceIn 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.


Figure 5-1 Java ITM Engine logical components

5.3 ImplementingThe 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.



Service Object

ILTILT

Launch(Class Loader)

JNI


Providers

DM

Cla

ssic

Mon

itor

Pro

bes

Cus

tom

Scr

ipts

JMX ILT

MBeanServer

MBean(s)

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel


� 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 filesThe 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 qualifiersThe 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.

DescriptionThe 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


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 box’s 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

ProviderThe 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"),


M12_InstrumentationThe 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"}

]

KeyThe 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 classThe 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.


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 filesComments 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 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.//


//------------------------------------------------------------------------------

Java packageThe 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 importsVarious 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 com.ibm.tivoli.monitoring.ITSO_Sample.ITSO_Sample;import com.tivoli.dmunix.ep.touchpoint.base.*;import com.tivoli.javautils.Trace;import java.util.Enumeration;import 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.


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 implementationThe 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 methodsA 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.


getPropertyThis 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;

}}


getMultiplePropertiesThis 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 )


try{



// 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;


}}

enumerateInstancesThis 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 )


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.


// 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;

}}

setPropertyThis 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.

invokeMethodThis 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.


createThis 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.

destroyThis 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.

ILT supported classesThe 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.

M12ObjectIdentity This is implemented as a passed parameter to the ILT Public Operation methods and is used to identify the instance of the resource.

M12IdentityElement This is implemented within ILT Public Operation methods and is used to identify the instance of the resource. This is obtained through the M12ObjectIdentity.

M12PropertySet This is implemented within ILT Public Operation methods and is used to retrieve property values for the instance. This is obtained through the M12IdentityElement.

M12Exception This is implemented through ILT Public Operation methods to define the exception type thrown.

ParameterSet This is implemented through implemented ILT Public Operation methods and is used to receive parameters passed by the client.

ParameterSetList This class was not utilized in this sample.


Custom methodsThese 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.

getITSOAttributeThis 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 = newString( pitso_sample.getITSO_SampleVar_str(iIndex) );

return sReturn;}

//----------------------------------------------------------------------// boolean ITSO_SampleVar_bln//----------------------------------------------------------------------if(sProperty.equals("ITSO_SampleVar_bln")){

Boolean blnVar = newBoolean(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")) ||(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 = newDouble(pitso_sample.getITSO_SampleVar_r(iIndex));

return dblVar.toString();}

//----------------------------------------------------------------------// Unknown property.//----------------------------------------------------------------------else{

throw new Exception(sProperty + ": unknown property");}


}

WriteBufferThis 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 classThe 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 administrator’s 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


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 filesComments 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 packageThe 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;


Java importsVarious 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 methodsThese 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_SampleThis 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_InstancesThis 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.


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_strThis 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_siThis 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.


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_uiThis 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_rThis 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_blnThis 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.


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;

}

5.3.4 Resource ModelResource 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 settingsThese 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.


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 ModelThe 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.


Table 5-2 CIM class properties

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,ITSO_SampleVar_inst,ITSO_SampleVar_si32,ITSO_SampleVar_ui8", "ITSO_SampleVar_str", "None", "", 0, 1);

//<<\DATA_INFO>>

ParametersFor 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.

Class property Property type

ITSO_SampleVar_inst Numeric

ITSO_SampleVar_str String

ITSO_SampleVar_bln Numeric

ITSO_SampleVar_si8 Numeric




ITSO_SampleVar_ui8 Numeric



ITSO_SampleVar_r32 Numeric

ITSO_SampleVar_r64 Numeric


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>>

DependenciesThe 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 Model’s General Settings, both the ITSO_Sample.mof and the ITSO_Sample.jar files were added to the All dependency tab.

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.


JavaScriptThe 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.

SetDefaultConfigurationIn 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 model’s operation.

Example 5-28 ITSO_Sample.dmjsws: SetDefaultConfiguration function

function SetDefaultConfiguration (Svc){

Svc.Trace (0, "ITSO_Sample: SetDefaultConfiguration - start" );


// Thresholds section//<<THRESHOLDS_INFO>>//<<\THRESHOLDS_INFO>>


// Note:In the DefineClass method, we create an ALIAS of "ITSO_Sample" //to the actual CIM Namespace declaration for our class.

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.


//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_ui32,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 belowSvc.Trace (0, "ITSO_Sample: SetDefaultConfiguration - end" );

return (0);}

InitThe 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.


Example 5-29 ITSO_Sample.dmjsws: Init function

function Init(Svc){

Svc.Trace (0, "ITSO_Sample: Init - start" );

// Variable Initializationvar 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);

}

VisitTreeThe 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


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 Declarationvar 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:StringcurITSO_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:BooleancurITSO_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 8curITSO_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:Signed Integer 8curITSO_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:Real 32curITSO_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 64curITSO_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 PackagingThe 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


Resource Model, with those not used within the ITSO_Sample presented in light gray to de-emphasize their significance.

Figure 5-6 ITSO_Sample.tar: Resource Model Tar File

5.4.1 Testing and importing the MOFThe 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.

Dependencies Files

Provider(s):"ITSO_Sample.jar"

MOF(s):"ITSO_Sample.mof"



Dynamic Model(s):CIM Class "ITSO_Sample"



VisitTree(Svc)

Message Catalogs

Configuration File

Event(s):

Action(s):

Threshold(s):

Logging:


Parameter(s):ITSO_ArrayGUI


Figure 5-7 mofcomp output

5.4.2 Java compilationThe 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.


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


5.4.3 Making the jar fileThe 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 ModelUpon 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.


Figure 5-11 ITM Workbench: Tree view pane

5.4.5 Building the Resource ModelThe 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.


Figure 5-12 ITM Workbench: Build menu

Figure 5-13 ITM Workbench: Save As


5.5 ITSO_Sample templateThe 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.mofThe 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." ) ]


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, 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"


"a 64-bit floating point data type." ) ] real64 ITSO_SampleVar_r64;};

5.5.2 ITSO_SampleIlt.javaThe 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 com.ibm.tivoli.monitoring.ITSO_Sample.ITSO_Sample;import com.tivoli.dmunix.ep.touchpoint.base.*; // "dm_m12.jar"import com.tivoli.javautils.Trace; // "javautils.jar"import java.util.Enumeration;import java.util.Vector;

public class ITSO_SampleIlt implements ILTInterface


{ //-------------------------------------------------------------------------- // 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. //


// 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 //


// 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");


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. //


// 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


// 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 //


// 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 )


// 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


// // 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; }


//-------------------------------------------------------------------------- // // 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


// // 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 //


// 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")) ||


(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


// 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.javaThe 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.*;


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) {


// 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. //


// 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 JavaScriptThe 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


// 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" );




// 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_ui32,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>>



// Place your additional intializing code belowSvc.Trace (0, "ITSO_Sample: 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 valuesfunction Init(Svc){

Svc.Trace (0, "ITSO_Sample: Init - start" );


// 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 herefunction VisitTree(Svc){

// Variable Declarationvar 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 );


// Variable type demonstration: StringcurITSO_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: BooleancurITSO_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 8curITSO_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: Signed Integer 8curITSO_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: Real 32curITSO_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 64curITSO_SampleVar_r64 = Svc.GetNumProperty("ITSO_Sample", idx, "ITSO_SampleVar_r64");sTraceOut = "GetNumProperty: curITSO_SampleVar_r64 = " + curITSO_SampleVar_r64 ;Svc.Trace( 0, sTraceOut );

}

return (0);}


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

6


6.1 Designing the Resource ModelIn 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 overviewThe 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.

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

SNMP Service

MIB-II SystemMIB-II Interfaces

MIB-II IPMIB-II TCPMIB-II UDP

W MI

W MISNMP

Provider

Endpoint

Monitored Server

ITM Engine

ITSO_SNMP_Interface_BpsResource Model


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)).

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.

Note: For more information about the WMI or the WMI SNMP Provider, see the following link:

http://www.microsoft.com/technet/default.asp

Chapter 6. Creating an SNMP Resource Model for Windows 203


Figure 6-2 ITM Engine logical components

6.1.3 Detailed design Resource ModelBefore 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 designFirst, 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



TMWService

WMI APIs

WMI (CIMOM)


JMX ILTILT


MBeanServer


WM

I P

rovi

der

DLL

s

Resource


Resource

Providers

CO

M O

bjec

ts

DM

Cla

ssic

Mon

itor

Pro

bes

Cus

tom

Scr

ipts

ILT

JNI

BinaryLibrary

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

Indications Default

Thr_ifOutOctets_in Increased by 100000

Thr_ifInOctets_in Increased by 100000


Internal designTo 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

6.2 Creating the Resource ModelThis 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 machineUsually, Windows servers do not have the SNMP service and WMI SNMP Provider installed. We installed these components with the following steps.

Elements Contents

Internal Name ITSO_SNMP_Interface_Bps

Descriptive Name ITSO_SNMP_Interface_Bps Monitor

Category Internal Name ITSO_RMs

Category Descriptive Name ITSO Resource Models

Dynamic Model SNMP_RFC1213_MIB_ifTable

Events Ev_SNMP_RFC1213_MIB_ifTable_ifOutOctets_grows_too_muchEv_SNMP_RFC1213_MIB_ifTable_ifInOctets_grows_too_much

Thresholds Thr_ifOutOctets_inThr_ifInOctets_in

Parameters none

Logging none

Dependency none


Installing the SNMP ServiceFirst, 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.


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 agentAfter 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.


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 SNMPThis 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.


� 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.exeMicrosoft (R) File Expansion Utility Version 5.00.2134.1Copyright (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 861490 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.


http://www.microsoft.com/downloads

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.


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.mibsmi2smir : 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

6.2.2 Creating the new SNMP Resource ModelDuring 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 Model1. 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

Note: You can obtain a list of MIBs that ship with the Windows 2000 implementation of SNMP by referring to the Microsoft TechNet at:




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.


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.


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.


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.


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.


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.


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 fieldFollow 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.


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 DoubleDim 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.


Example 6-4 Setting the first time values

hashKey = Str(curifIndex)

OldifInOctets = curifInOctetsOldifOutOctets = 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

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.

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.


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 )) ThenIf (DeltaifInBps > Svc.GetThreshold("Thr_ifInOctets_in") ) Then

Svc.SetMapNumElement(hPropTable,"Delta", DeltaifInBps)

Svc.SetMapNumElement(hPropTable,"MaxAllowedDelta",Svc.GetThreshold("Thr_ifInOctets_in"))

Svc.SendEventEx "Ev_SNMP_RFC1213_MIB_ifTable_ifInOctets_grows_too_much", hPropTableEnd IfIf ( 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", hPropTableEnd IfEnd 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 ModelThe 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.


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.

Dependencies Files




Dynamic Model(s):CIM Class

"SNMP_RFC1213_MIB_ifTable"


ITSO_SNMP_Interface_Bps.vba

Message Catalogs

Resource Model Tar FileConfiguration File

Event(s):Ev_SNMP_RFC1213_MIB_ifTable_ifOutOctets_grows_too_muchEv_SNMP_RFC1213_MIB_ifTable_ifInOctets_grows_too_much

Threshold(s):Thr_ifOutOctets_inThr_ifInOctets_in

Action(s):

Logging:

Parameter(s):


Installation completed.

When completed successfully, distribute the ITSO_SNMP_Interface_Bps Resource Model to the endpoint.

6.2.4 Testing the Resource ModelIn 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


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


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 codeThe files in this section were created for the purpose of this example.

6.3.1 ITSO_SNMP_Interface_Bps.vbaThe 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 IntegerDim 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 ObjectSet TMWService = CreateObject("TMWService.Utilities")

Dim RetVal As Long

' Calling the SetDefaultConfiguration (...) function to configure the' Resource Model.RetVal = SetDefaultConfiguration (TMWService)

If (RetVal = 0) Then


' At this point the monitoring engine will override default settings.

' Calling Init (...).RetVal = Init (TMWService)


' Entering the monitoring loop...' It will loop forever.Do While (RetVal = 0)

' Collect DataTMWService.CollectData

' Visit the decision treeRetVal = VisitTree(TMWService)


' Wait for a cycle timeTMWService.EndVisitWait TMWService.GetCycleTime()

End If 'VisitTree = 0

Loop

End If 'Init = 0

End If 'SetDefaultConfiguration = 0

' Clean up used resourcesTMWService.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"


Svc.SetCycleTime 30'<<\GENERAL_INFO>>

' Thresholds section'<<THRESHOLDS_INFO>>Svc.DefineThreshold "Thr_ifOutOctets_in", 100000.000000Svc.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 valuesPublic Function Init(Svc As Object) As Long

hTableifOutOctets = Svc.CreateMap()


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 herePublic Function VisitTree(Svc As Object) As Long

Dim curifIndex As DoubleDim curifSpeed As DoubleDim curifOutOctets As DoubleDim curifInOctets As DoubleDim curifDescr As String

Dim hashKey As StringDim found As LongStatic flagNotFirstRun As Boolean

Dim OldifOutOctets As DoubleDim OldifInOctets As Double

Dim hPropTable As LongDim numOfInstances As LongDim idx As LongDim ParamCount As LongDim ParamIdx As LongDim Different As Boolean

'Define additional DimDim DeltaifOutBps As DoubleDim 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)


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 = curifInOctetsOldifOutOctets = curifOutOctets

found = Svc.ExistsMapElement(hTableifOutOctets, hashKey)If found Then

OldifOutOctets = Svc.GetMapNumValue(hTableifOutOctets, hashKey)Svc.SetMapNumElement(hPropTable,"OldifOutOctets",OldifOutOctets)

End Iffound = 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 )) ThenIf (DeltaifInBps > Svc.GetThreshold("Thr_ifInOctets_in") ) Then

Svc.SetMapNumElement(hPropTable,"Delta", DeltaifInBps)Svc.SetMapNumElement(hPropTable,"MaxAllowedDelta",Svc.GetThreshold(

"Thr_ifInOctets_in"))


Svc.SendEventEx "Ev_SNMP_RFC1213_MIB_ifTable_ifInOctets_grows_too_much", hPropTable

End IfIf ( 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", hPropTableEnd If

End If '((flagNotFirstRun = True) And ( found <> 0 ))

flagNotFirstRun = TrueSvc.SetMapNumElement(hTableifOutOctets,hashKey, curifOutOctets)Svc.SetMapNumElement(hTableifInOctets,hashKey, curifInOctets)

Next

Svc.DestroyMap(hPropTable)

VisitTree = 0

End Function


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

7


7.1 TerminologyMany 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 A Java package is a pre-compiled set of classes contained within a jar file.

SNMP Simple Network Management Protocol is a protocol for Internet network management services. It is formally specified in a series of related RFC documents.

MIB 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.

OID 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.

PID Every process running on a UNIX system is identified by a unique number called the process ID (PID).

7.2 Planning and designDuring 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


(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.

7.2.1 Resource ModelThe 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 classBased 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 classThe 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.


7.2.4 Provider classThis 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 referenceIn 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.


Figure 7-1 Java: ITM logical components

7.3 ImplementingThe 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.



Service Object

ILTILT


JNI


Providers

DM

Cla

ssic

Mon

itor

Pro

bes

Cus

tom

Scr

ipts

JMX ILT

MBeanServer

MBean(s)

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel


� 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 formatIn 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 qualifiersThe 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.

DescriptionThe 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 box’s 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.


Figure 7-2 ITM Workbench: About selected class

ProviderThe 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 _InstrumentationThe 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"}


KeyThe 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 classThe 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


Commenting Java FilesAs discussed in Chapter 5, “Engineering a Java ILT” on page 137, comments have been implemented within this Provider’s 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 packageThe 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 importsVarious 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.


Example 7-7 ITSO_SnmpProbeIlt.java: Import declarations

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 Classimport java.util.Vector; // 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 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.

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 implementationThe 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 methodsA 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


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.

getPropertyAs 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.

getMultiplePropertiesThis 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.


Example 7-10 ITSO_SnmpProbeIlt.java: getMultipleProperties method

public M12PropertySet getMultipleProperties(M12ObjectIdentity m12objectidentity,Vector vPropertyList,String sMapping,ParameterSet parameterset )


int iIndex;

try{



// 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 current property values.String sValue = getAttribute(iIndex, sProperty);m12propertyset1.setProperty(sProperty, sValue);

}

trace.log( 3, "ITSO_SnmpProbeIlt","getMultipleProperty: returning " +

WriteBuffer(m12propertyset1));return m12propertyset1;



trace.exception("ITSO_SnmpProbeIlt","getMultipleProperty", exception);

M12Exception m12exception = new M12Exception(exception);throw m12exception;

}}

enumerateInstancesThis 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 )


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.


// 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 =



}



trace.exception("ITSO_SnmpProbeIlt","enumerateInstances", exception);


}}

setPropertyThis 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 )


return null;}

invokeMethodThis 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 )


return null;


}

createThis 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 )


return;}

destroyThis 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 )


return;}

ILT supported classesThe 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 methodsThese 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.


getITSOAttributeThis 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");}


}

WriteBufferThis 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 classThe 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.


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 packageThe 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 importsVarious 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.


Example 7-19 ITSO_SnmpProbe.java: Java imports

import com.tivoli.javautils.Trace; // For debugging.import com.tivoli.snmp.data.*; // SNMP Requirementimport com.tivoli.snmp.utils.*; // SNMP Requirementimport com.tivoli.snmp.*; // SNMP Requirementimport java.util.*; //import java.util.Vector; // Dynamic object array handler.import java.io.Serializable; // SNMP Requirement

Custom methodsThese 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_SnmpProbeThis 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(){


getInstancesThis 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.


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 vectorsnmpPole(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


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;}

getifIndexThis 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 method’s 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;

}


getifDescrThis 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;

}

getifSpeedThis 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;

}

getifInOctetsThis 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 method’s 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.


Example 7-26 ITSO_SnmpProbe.java: getifInOctet

public static synchronized String getifInOctets(int iIndex){

SNMPInterface siTemp = (SNMPInterface) vInterfaceList.elementAt(iIndex);return siTemp.ifInOctets;

}

getifOutOctetsThis 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 method’s 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;

}

snmpPoleThis 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 InitializationSnmpSession session;


// 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 APISnmpV1API.initialize(12345);

// Open a session to the specified hostsession = 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(); // Allocate a PDU.getPDU.operation = SnmpPDU.GET; // Perform a get.getPDU.addVarBind("1.3.6.1.2.1.2.1.0"); // Request "ifNumber".SnmpPDU rsp = session.send(getPDU); // Send and receive the PDU

// synchronously.initVector(rsp); // Build the Vector list.


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"); // ifIndexgetNext.addVarBind(oid);getNext.addVarBind("1.3.6.1.2.1.2.2.1.2"); // ifDescrgetNext.addVarBind("1.3.6.1.2.1.2.2.1.5"); // ifSpeedgetNext.addVarBind("1.3.6.1.2.1.2.2.1.10"); // ifInOctetsgetNext.addVarBind("1.3.6.1.2.1.2.2.1.16"); // 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);


// 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 tablegetNext = 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.");

}

initVectorThis 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


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 bindingSnmpVarBind vb = pdu.varBindAt(i);OID oid = vb.getOID();Serializable var = vb.getVar();

// MIB-II, Interface Group// OID = 1.3.6.1.2.1.2.1.0// Descr - ifNumbertrace.log( 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


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);

}}

updateInterfacesThe 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


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 DeclarationSNMPInterface 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 bindingSnmpVarBind 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);

// 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);}

}


7.3.4 Resource ModelResource 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 settingsThese 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 ModelThe 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_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

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

Class property Property type

ifIndex String

ifDescr String

ifSpeed String

ifInOctets String

ifOutOctets String


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>>

ParametersFor 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.

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

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.


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>>

JavaScriptThe 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.

SetDefaultConfigurationIn 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 object’s 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 model’s operation.

Example 7-41 ITSO_SnmpPorbe.dmjsws: SetDefaultConfiguration function

function SetDefaultConfiguration (Svc){

Svc.Trace (0, "ITSO_SnmpProbe: SetDefaultConfiguration - start" );





// 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>>



// Place your additional intializing code belowSvc.Trace (0, "ITSO_SnmpProbe: SetDefaultConfiguration - end" );

return (0);}

InitThe 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.


Example 7-42 ITSO_SnmpProbe.dmjsws: Init function

function Init(Svc){

// LoggingSvc.Trace (0, "ITSO_SnmpProbe: Init - start" );

// Variable Initializationvar 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);

}

VisitTreeThe 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


// Variable Declarationvar iHostnameCount;var iInstanceCount;var iIndex;


var sTraceOut;

var curifIndex;var curifDescr;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 instancesfor ( iIndex= 0; iIndex < iInstanceCount; iIndex++) {

// ifDescr OID = 1.3.6.1.2.1.2.2.1.2curifDescr = Svc.GetStrProperty("ITSO_SnmpProbe", iIndex, "ifDescr");Svc.Trace( 0, "GetStrProperty: ifDescr = " + curifDescr );

// ifSpeed OID = 1.3.6.1.2.1.2.2.1.5curifSpeed = Svc.GetStrProperty("ITSO_SnmpProbe", iIndex, "ifSpeed");Svc.Trace( 0, "GetStrProperty: ifSpeed = " + curifSpeed );

// ifInOctets OID = 1.3.6.1.2.1.2.2.1.10curifInOctets = Svc.GetStrProperty("ITSO_SnmpProbe", iIndex,

"ifInOctets");Svc.Trace( 0, "GetStrProperty: ifInOctets = " + curifInOctets );

// ifOutOctets OID = 1.3.6.1.2.1.2.2.1.16curifOutOctets = Svc.GetStrProperty("ITSO_SnmpProbe", iIndex,

"ifOutOctets");Svc.Trace( 0, "GetStrProperty: ifOutOctets = " + curifOutOctets );

}

return (0);}


7.4 PackagingThe 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.

Figure 7-6 ITSO_SnmpProbe.tar: Resource Model Tar File

7.4.1 Testing and importing the MOFThe 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


Dependencies Files

Provider(s):"ITSO_SnmpProbe.jar"

MOF(s):"ITSO_SnmpProbe.mof"

Custom Scripts()

JavaScript

Dynamic Model(s):CIM Class "ITSO_SnmpProbe"



VisitTree(Svc)

Message Catalogs

Configuration File

Event(s):

Action(s):

Threshold(s):

Logging:


Parameter(s):ITSO_Hostnames

Custom Files(s)"Snmp.jar"


Figure 7-7 mofcomp output

7.4.2 Java compilationThe 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.


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


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 fileThe 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/



Figure 7-11 jar output

7.4.4 Assembling the Resource ModelUpon 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.


Figure 7-12 ITM Workbench: Tree view pane

7.4.5 Building the Resource ModelThe 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.


Figure 7-13 ITM Workbench: Build menu


Figure 7-14 ITM Workbench: Save As dialog

7.5 ITSO_SnmpProbe source codeThe 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.mofThe 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 "


"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.JavaThe 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)


// 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 Classimport 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


//// 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 )


int iIndex;

try{



// 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",


"getAttribute: " + sProperty + " = " + iIndex);return sValue;


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(


M12ObjectIdentity m12objectidentity,Vector vPropertyList,String sMapping,ParameterSet parameterset )


int iIndex;

try{



// 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 current property values.String sValue = getAttribute(iIndex, sProperty);m12propertyset1.setProperty(sProperty, sValue);

}

trace.log( 3, "ITSO_SnmpProbeIlt","getMultipleProperty: returning " +

WriteBuffer(m12propertyset1));return m12propertyset1;



trace.exception("ITSO_SnmpProbeIlt","getMultipleProperty", exception);


}}

//--------------------------------------------------------------------------//// 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 )


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.// 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 =



}


trace.exception("ITSO_SnmpProbeIlt","enumerateInstances", exception);


}}

//--------------------------------------------------------------------------//// 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 )


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////--------------------------------------------------------------------------public String invokeMethod( M12ClassPath m12classpath,

String sMethodName,String sMapping,ParameterSet parameterset,ParameterSet parameterset1,ParameterSet parameterset2 )


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.//// 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 )


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.//// 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,



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.


//// Description:// Deletes an instance of the resource identified by the specified// targetInstance.//// Returns:// void//// Exceptions Thrown:// M12Exception////--------------------------------------------------------------------------public void destroy( M12ObjectIdentity m12objectidentity,



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;


}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 + " ")){


sElement = (String)enumeration.nextElement();sProperty = m12propertyset.getProperty(sElement);

}

return stringbuffer.toString();}

}

7.5.3 ITSO_SnmpProbe.JavaThe 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 com.tivoli.javautils.Trace; // For debugging.import com.tivoli.snmp.data.*; // SNMP Requirementimport com.tivoli.snmp.utils.*; // SNMP Requirementimport com.tivoli.snmp.*; // SNMP Requirementimport java.util.*; //import java.util.Vector; // Dynamic object array handler.import java.io.Serializable; // SNMP Requirement

public class ITSO_SnmpProbe{

// Declare local members.private static Trace trace;static Vector vInterfaceList;

//--------------------------------------------------------------------------// ITSO_SnmpProbe class - Creator method.//--------------------------------------------------------------------------public ITSO_SnmpProbe(){



//--------------------------------------------------------------------------// 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 vectorsnmpPole(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;

}


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


SnmpSession session;

// Jen some log info.trace.log( 3, "ITSO_SnmpProbe", "snmpPole: Starting.");

//try{

// Initialize the APISnmpV1API.initialize(12345);

// Open a session to the specified hostsession = 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(); // Allocate a PDU.getPDU.operation = SnmpPDU.GET; // Perform a get.getPDU.addVarBind("1.3.6.1.2.1.2.1.0"); // Request "ifNumber".SnmpPDU rsp = session.send(getPDU); // 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"); // ifIndexgetNext.addVarBind(oid);getNext.addVarBind("1.3.6.1.2.1.2.2.1.2"); // ifDescrgetNext.addVarBind("1.3.6.1.2.1.2.2.1.5"); // ifSpeedgetNext.addVarBind("1.3.6.1.2.1.2.2.1.10"); // ifInOctetsgetNext.addVarBind("1.3.6.1.2.1.2.2.1.16"); // ifOutOctets

//// Step through the Interface(s)//


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 tablegetNext = 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;


if ( pdu.errorStatus == SnmpPDU.NOERROR ){

// Walk the PDU to find the ifNumber.for ( int i = 0; i < pdu.varBindListSize(); i++ ){

// Extract the variable bindingSnmpVarBind vb = pdu.varBindAt(i);OID oid = vb.getOID();Serializable var = vb.getVar();

// MIB-II, Interface Group// OID = 1.3.6.1.2.1.2.1.0// Descr - ifNumbertrace.log( 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());


}}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 DeclarationSNMPInterface siBuffer = new SNMPInterface();String sBufConv;

// Walk through all of the OIDs requested.for ( int i = 0; i < pdu.varBindListSize(); i++ ){

// extract the variable bindingSnmpVarBind 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);


// 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);}

}}


7.5.4 SnmpInterface.JavaThe 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 JavaScriptThe 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//''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''


// 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" );




// 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>>



// Place your additional intializing code belowSvc.Trace (0, "ITSO_SnmpProbe: SetDefaultConfiguration - end" );

return (0);}



// LoggingSvc.Trace (0, "ITSO_SnmpProbe: Init - start" );

// Variable Initializationvar 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 herefunction VisitTree(Svc){

// Variable Declarationvar iHostnameCount;var iInstanceCount;var iIndex;var sTraceOut;

var curifIndex;var curifDescr;


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 instancesfor ( iIndex= 0; iIndex < iInstanceCount; iIndex++) {

// ifDescrOID = 1.3.6.1.2.1.2.2.1.2curifDescr = Svc.GetStrProperty("ITSO_SnmpProbe", iIndex, "ifDescr");Svc.Trace( 0, "GetStrProperty: ifDescr = " + curifDescr );

// ifSpeedOID = 1.3.6.1.2.1.2.2.1.5curifSpeed = Svc.GetStrProperty("ITSO_SnmpProbe", iIndex, "ifSpeed");Svc.Trace( 0, "GetStrProperty: ifSpeed = " + curifSpeed );

// ifInOctetsOID = 1.3.6.1.2.1.2.2.1.10curifInOctets = Svc.GetStrProperty("ITSO_SnmpProbe", iIndex, "ifInOctets");Svc.Trace( 0, "GetStrProperty: ifInOctets = " + curifInOctets );

// ifOutOctetsOID = 1.3.6.1.2.1.2.2.1.16curifOutOctets = Svc.GetStrProperty("ITSO_SnmpProbe", iIndex, "ifOutOctets");Svc.Trace( 0, "GetStrProperty: ifOutOctets = " + curifOutOctets );

}

return (0);}


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.

8

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>.


8.1 Engine component utilization: OverviewIn 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.

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.



TMWService

WMI APIs

WMI (CIMOM)


JMX ILTILT


MBeanServer


WM

I P

rovi

der

DLL

s

Resource


Resource

Providers

CO

M O

bjec

ts

DM

Cla

ssic

Mon

itor

Pro

bes

Cus

tom

Scr

ipts

ILT

JNI

BinaryLibrary

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel


Figure 8-2 Resource Model sub-components for Java

8.2 Creating the MOF filesBefore 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



Service Object

ILTILT


JNI


Providers

DM

Cla

ssic

Mon

itor

Pro

bes

Cus

tom

Scr

ipts

JMX ILT

MBeanServer

MBean(s)

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

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;

};

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;};

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.


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 fileIf 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


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.


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.


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


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.


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.


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


8.4 Creating the Resource Model1. 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.


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.


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.


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.


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.


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.


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.



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.



11.Click OK.Your main Workbench window should now look like Figure 8-24 on page 325.



8.5 Constructing the Resource Model: EventsIn 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,


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.



8.6 Constructing the Resource Model: DependenciesIn 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,


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 codeWe 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



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;


interpType = Svc.GetInterp();

// General info section//<<GENERAL_INFO>>Svc.SetModelName ("WizRM_LogEvent");Svc.SetProfileName ("775316562");Svc.SetCycleTime (30);//<<\GENERAL_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);


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>>


// 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


hPropTable = Svc.CreateMap();

return (0);


}

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 herefunction 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);


}

8.8 The flow of the code

SetDefaultConfigurationAt 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 subroutineThe 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 subroutineThis 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


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.


� Designing the ITSO_LogfileLite Resource Model and ILT

� Creating the ITSO_LogfileLite Resource Model and ILT

� ITSO_LogfileLite source code

9


9.1 Designing the ITSO_LogfileLite Resource Model and ILT

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

9.1.1 Design overviewThe 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.


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.

ITSO_LogfileLite Resource Model

ITSO_LogfileLite ILT/Provider

ITSO_LogfileLite.mofITSO_LogfileLite-wmi.mof

Log file Log file Log file

3Read log filesCount matched lines

2Pass through file namesPass through patterns

5Return values

4Store values of each instancesStore offset values

Parameters

ITSO_LogfileLite_FileNameITSO_LogfileLite_Pattern

Thresholds

Thr_EventNum_gt

1Get values of the instances from ILT

6Compare with ThresholdsGenerate events

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.

9.1.2 What part of ITM will we use?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.

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.


Figure 9-2 Windows ITM Engine Logical Components

Figure 9-3 UNIX ITM Engine Logical Components



TMWService

WMI APIs

WMI (CIMOM)


JMX ILTILT


MBeanServer


WM

I P

rovi

der

DLL

s

Resource


Resource

Providers

CO

M O

bjec

ts

DM

Cla

ssic

Mon

itor

Pro

bes

Cus

tom

Scr

ipts

ILT

JNI

BinaryLibrary

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel



Service Object

ILTILT


JNI

NativeBinaries


Providers

DM

Cla

ssic

Mo

nito

r P

robe

s

Cus

tom

Scr

ipts

JM X ILT

M BeanServer

MBean(s)

ResourceM odel

ResourceModel

ResourceM odel

ResourceModel

ResourceM odel


9.1.3 The detailed design of the ITSO_LogfileLite Resource ModelWe describe the detailed design of the ITSO_LogfileLite Resource Model in this section.

External design of the ITSO_LogfileLite Resource ModelFirst, 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


Internal design of the ITSO_LogfileLite Resource ModelTo 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

Parameter Default

ITSO_LogfileLite_FileName (STRING-LIST TYPE) /tmp/log1.log

ITSO_LogfileLite_Pattern (STRING-LIST TYPE) Thread

Indications Default

ITSO_LogfileLite_EventNum_too_high > 5

Elements Contents

Internal Name ITSO_LogfileLite_RM

Descriptive Name ITSO_LogfileLite



Dynamic Model ITSO_LogfileLite

Events ITSO_LogfileLite_EventNum_too_high

Thresholds Thr_EventNum_gt

Parameters ITSO_LogfileLite_FileNameITSO_LogfileLite_Pattern


Defining the algorithmTo 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.

Logging none

Dependency ALL: ITSO_LogfileLite.jaraix4-r1: ITSO_LogfileLite.moflinux-i86: ITSO_LogfileLite.mofw32-ix86: ITSO_LogfileLite-wmi.mof

Elements Contents


Figure 9-4 Flowchart of ITSO_LogfileLite decision tree script

Exceeding Threshold?

End

Start

GetProperty of the Instance(i)

Send event

i++

Last instance?

No

Yes

Count the number of the instances and set "0" to i variable


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


9.2.1 Setting up the development environmentFirst, 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.

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

Note: In this example, we use the Java 2 SDK 1.3.1, which is available in the following URL:

http://java.sun.com


http://java.sun.com

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.

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

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/



9.2.2 Creating the MOF fileTo 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.mof4:// 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_LogfileLite19:{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.


Table 9-4 Properties

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

� 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.mof2: #pragma namespace ("\\\\.\\ROOT\\CIMV2")3: //=============================================4: // ITSO_LogfileLite5: //=============================================6: [Description("ITSO LogfileLite"), Dynamic, M12_Instrumentation{"Java.com.ibm.tivoli.monitoring.ITSO_LogfileLite.ITSO_LogfileLiteIlt | | ENUM", "Java.com.ibm.tivoli.monitoring.ITSO_LogfileLite.ITSO_LogfileLiteIlt | | GET"}, provider("M12JavaProvider")]7: class ITSO_LogfileLite8: {9: sint32 EventNum;10: [key]11: string FileName;

Property Type Description

FileName string The FileName indicates the log file name that is being monitored. It takes over file names from the Parameter ITSO_LogfileLite_FileName.

EventNum sint32 The EventNum indicates the number of the events that are counted by the log files for each cycle.

PropertiesInstances

FileName [key] EventNum

Instances A /tmp/log1.log 10

Instances B /tmp/log2.log 0

Instances C /tmp/log3.log 7


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 codeNext, we create the Java code for the ILT.

Summarizing the relationFollowing 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.

Figure 9-6 The relationship of the methods

ITSO_LogfileLite ILT ITSO_LogfileLite Provider

getProperty

getMultipleProperties

enumerateInstances

getITSOAttribute

getITSO_Instances

getITSO_LogfileLiteVar_EventNum

ITSO_LogfileLiteResource Model

GetStrPropertyGetNumProperty

GetNumOfInst

AssociateParameterToClass

Parameters Parameterset


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 locationTo 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 ILTIn 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.

getMultipleProperties Added supporting Java code to support retrieval of multiple properties from the Provider. The getMultipleProperties invokes the getITSOAttribute multiple times.


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.

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.

getITSOAttribute 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.

setProperty Only log tracing was added, as this method was not required for this sample.

invokeMethod (first interface) Only log tracing was added, as this method was not required for this sample.

invokeMethod (second interface) Only log tracing was added, as this method was not required for this sample.

create Only log tracing was added, as this method was not required for this sample.

destroy Only log tracing was added, as this method was not required for this sample.



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 Class27: 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 Class30: import java.util.Vector; // Java Class31: import java.util.*; // Java Class32: 33: public class ITSO_LogfileLiteIlt implements ILTInterface34: {

� 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.

Note: We use the com.ibm.tivoli.monitoring.<ILT_General_Name> as the package name, following the naming convention recommended by the developer.


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 the140: // 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);


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 so313: // 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.


336: // This section handles the registration of instances of this337: // Instrumentation.338: //------------------------------------------------------------------339: String aiInst[] = pitso_logfilelite.getITSO_Instances( asITSOArrayGui );340: if(aiInst == null)341: {342: trace.log(1, "ITSO_LogfileLiteIlt",343: "enumerateInstances: no instances found");344: return null;345: }346: 347: for(int jIndex = 0; jIndex < aiInst.length; jIndex++)348: {349: trace.log( 3, "ITSO_LogfileLiteIlt", "enumerateInstances: aiInst[" +350: jIndex + "] = " + aiInst[jIndex]);351: M12PropertySet m12propertyset = new M12PropertySet();352: m12propertyset.setProperty( "FileName",353: aiInst[jIndex] );354: M12IdentityElement m12identityelement =355: new M12IdentityElement( m12classpath.getClassName(),356: m12classpath.getNameSpace(),357: m12propertyset);358: vector.add( new M12ObjectIdentity( new M12IdentityElement[]359: { m12identityelement } ) );360: }361: 362: return vector.elements();363: }

� 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”


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: // GetAttributeTypes630: //631: // This method is internal to the class and is designed to segregate the632: // ILT Operations from our own supporting methods. It is simply to provide633: // cleaner & easier to maintain code.634: //635: //------------------------------------------------------------------------636: private String getITSOAttribute( String sValue,637: String sProperty,638: String asITSO_LogfileLite_Pattern[] )639: throws Exception640: {641: //----------------------------------------------------------------------642: // Return the EventNum value643: //----------------------------------------------------------------------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 offsetarray650: // 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 result664: // 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.


670: offsetarray.put(sValue, String.valueOf(intVar[1]));671: 672: // Trace673: trace.log( 3, "ITSO_LogfileLiteIlt", "getITSOAttribute result offset" +674: intVar[1] + " EventNum = " + intVar[0] + " FileName = " + sValue);675: trace.log( 3, "ITSO_LogfileLiteIlt", "global array: offset" +676: (String)offsetarray.get(sValue));677: 678: // Return the EventNum value.679: return String.valueOf(intVar[0]);680: }681: //----------------------------------------------------------------------682: // Return the FileName value683: //----------------------------------------------------------------------684: if( (sProperty.equals("FileName")))685: {686: return sValue;687: }688: 689: //----------------------------------------------------------------------690: // Unknown property.691: //----------------------------------------------------------------------692: else {693: throw new Exception(sProperty + ": unknown property");694: }695: }

Creating the ITSO_LogfileLite Provider codeIn 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


getITSO_Instances Added supporting Java code to organize an array of the instance key sets.

getITSO_LogfileLiteVar_EventNum 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.


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; // Part of the ILT package.12: 13: import com.tivoli.javautils.Trace; // "javautils.jar"14: import gnu.regexp.*; // GNU REGEXP package15: import java.lang.*; // Java Class16: import java.util.*; // Java Class17: import java.io.*; // Java Class18: 19: 20: public class ITSO_LogfileLite21: {

� 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 regexp’s getmatch() methods.


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: // getITSO_LogfileLiteVar_EventNum57: //----------------------------------------------------------------------58: 59: public static synchronized int[] getITSO_LogfileLiteVar_EventNum( String i,60: String as[],61: String offset )62: {63: // retrieve pattern();64: int c = 0;65: int c1 = 0;66: int c2 = 0;67: int obj = 0;68: int lastline;69: int[] retarray = new int[2];70: 71: try {72: RE re = null;73: REMatch mat;74: 75: String sl = offset; // offSet = retrieve offSet(i);76: 77: // Create a FileReader object78: FileReader fr = new FileReader(i);79: BufferedReader br = new BufferedReader(fr);80: LineNumberReader lr = new LineNumberReader(fr);81: 82: // Read strings in the file83: String line;84: while((line = lr.readLine()) != null) {85: 86: for(int iIndex = 0; iIndex < as.length; iIndex++) {87: 88: // Compile the string for the pattern matching89: try {90: re = new RE(as[iIndex]);91: } catch (REException e) {92: break;


93: }94: 95: Integer tmp = Integer.valueOf(sl);96: obj = tmp.intValue();97: 98: // Pattern match99: mat = re.getMatch(line);100: if (mat != null) {101: 102: if (obj > lr.getLineNumber()) {103: c1++; // Increase the counter older than the offset104: } else {105: c2++; // Increase the counter newer than the offset106: }107: 108: }109: }110: }111: 112: // Store the lastline number113: 114: lastline = lr.getLineNumber();115: 116: // Close the FileReader object117: fr.close();118: 119: if ( offset == "-1" ) { // If the offset is "-1", this is the first time.120: retarray[0] = 0 ; // Discards the result and121: // 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 offset127: 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 offset130: retarray[1] = lastline;131: }132: }133: 134: }135: catch (Exception e) {136: ;137: }


138: return retarray;139: }

Compiling the Java classesYou 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.javac:\<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/*.classc:\<working dir> jar tvf ./ITSO_LogfieLite.jar0 Thu Apr 24 10:04:54 CDT 2003 META-INF/71 Thu Apr 24 10:04:54 CDT 2003 META-INF/MANIFEST.MF2173 Thu Apr 24 10:00:40 CDT 2003 com/ibm/tivoli/monitoring/ITSO_LogfileLite/ITSO_LogfileLite.class7691 Thu Apr 24 10:00:48 CDT 2003 com/ibm/tivoli/monitoring/ITSO_LogfileLite/ITSO_LogfileLiteIlt.class


9.2.4 Creating the Resource ModelYou 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 WizardLet 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.

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.


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.


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 User’s 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.


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


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.


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 ModelYou 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.


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.


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.


Figure 9-17 Changing the event setting

Table 9-8 The event of ITSO_LogfileLite_EventNum_too_high

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.

Elements Contents

Internal Name ITSO_LogfileLite_EventNum_too_high.

Attributes NUMERIC: EventNum, UpperBound.STRING: FileName.

Aggregation Setting

Keys FileName.

Clearing Event Yes.

Occurrence/Hole 1 / 0.

Notification Send to TEC/TBSM

Yes.

Severity CRITICAL.


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

String Resources

Descriptive Name ITSO_LogfileLite_EventNum_too_high.

Message ITSO_LogfileLite_EventNum_too_high: The property EventNum(@EventNum@) of the instance (FileName=@FileName@) is greater than @UpperBound@.

Elements Contents

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.

Elements Value

Internal Name Thr_EventNum_gt

Descriptive Name Thr_EventNum_gt

Default Value 5

Description Thr_EventNum_gt


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


platform and the Windows platform. Therefore, we put the MOF files in each platform’s dependencies. Table 9-10 shows a summary of the dependencies.

Table 9-10 Dependency files for each platform

When completed, you can see that the dependency files are correctly added, as shown in Figure 9-21 on page 370.

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.

aix4-r1 ITSO_LogfileLite.mof The MOF file for the UNIX platform.

linux-i86 ITSO_LogfileLite.mof The MOF file for the UNIX platform.

solaris2 ITSO_LogfileLite.mof The MOF file for the UNIX platform.

w32-ix86 ITSO_LogfileLite-wmi.mof The MOF file for the Windows platform.


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.


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 section18: //<<GENERAL_INFO>>19: Svc.SetModelName ("ITSO_LogfileLite_RM");20: Svc.SetProfileName ("80652796");21: Svc.SetCycleTime (60);22: //<<GENERAL_INFO>>23: 24: // Thresholds section25: //<<THRESHOLDS_INFO>>26: Svc.DefineThreshold ("Thr_EventNum_gt", 5.000000);27: //<<THRESHOLDS_INFO>>28: 29: // Parameters section30: //<<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 section39: //<<DATA_INFO>>40: Svc.DefineClass ("CIM", "ITSO_LogfileLite", "ROOT\CIMV2:ITSO_LogfileLite", "", "EventNum", "FileName", "None", "", 0, 1);41: //<<DATA_INFO>>42: 43: // Event definition section44: //<<EVENTS_INFO>>45: Svc.DefineEvent ("ITSO_LogfileLite_EventNum_too_high", "EventNum,UpperBound", "FileName");46: //<<EVENTS_INFO>>47: 48: // Logging definition section49: //<<LOGGING_INFO>>50: //<<LOGGING_INFO>>51: 52: // Place your additional intializing code below53: Svc.Trace (0, "ITSO_LogfileLite: SetDefaultConfiguration - end" );54: 55: return (0);


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: // Logging67: Svc.Trace (0, "ITSO_LogfileLite: Init - start" );68: 69: // Variable Initialization70: var dimension = 0;71: var t=0;72: 73: //74: // Process the parameter lists.75: // ITSO_LogfileLite_FileName76: //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: else87: {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: }


91: 92: //93: // Process the parameter lists.94: // ITSO_LogfileLite_Pattern95: 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: else105: {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.


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 Declaration122: 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);


157: }158: 159: }160: 161: Svc.DestroyMap(hPropTable);162: 163: return (0);164: }165: 166:

9.2.5 PackagingThe 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.

Figure 9-22 Packaging

Dependencies Files

Provider(s):ITSO_LogfileLite.jar

MOF(s):ITSO_LogfileLite.mof

ITSO_LogfileLite-wmi.mof



Dynamic Model(s):CIM Class "ITSO_LogfileLite"


ITSO_LogfileLite_RM.js

Message Catalogs


Event(s):ITSO_LogfileLite_EventNum_too_high

Action(s):

Threshold(s):Thr_EventNum_gt

Logging:

Parameter(s):ITSO_LogfileLite_FileNameITSO_LogfileLite_Pattern


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 ModelCopying 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.

9.2.6 Testing the Resource ModelIn 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 environmentThe 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 User’s 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.


Distributing the profileAfter 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


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:




Figure 9-25 Parameter ITSO_LogfileLite_Pattern

� 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.

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.


Figure 9-26 Event ITSO_LogfileLite_EventNum_too_high

Testing the ITSO_LogfileLite Resource ModelIn 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.


� 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.


Table 9-11 Summary of the useful trace and log files

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>Thread[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 Apache’s access log, as shown in Example 9-20 on page 383.

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.

trace_dmxengine.log This log maintains the detailed behavior of the UNIX ITM Engine, including the internal variable’s condition.

Windows Tmw2k.log This log maintains the detailed behavior of the Windows ITM Engine, including the internal variable’s condition.

trace_ILTManagerForJava.log

This log maintains the detailed behavior of the Windows m12javaProvider, including the internal variable’s condition.


Example 9-20 Sample.log

[root@pacs006 logs]# cat /tmp/sample.loga.b.c.d - - [17/Apr/2003:15:37:08 -0500] "GET /footer.gif HTTP/1.1" 200 968a.b.c.d - - [17/Apr/2003:15:37:41 -0500] "GET /failpage.html HTTP/1.1" 404 310a.b.c.d - - [17/Apr/2003:15:37:42 -0500] "GET /failpage.html HTTP/1.1" 404 310a.b.c.d - - [17/Apr/2003:15:37:42 -0500] "GET /failpage.html HTTP/1.1" 404 310a.b.c.d - - [17/Apr/2003:15:37:43 -0500] "GET /failpage.html HTTP/1.1" 404 310a.b.c.d - - [17/Apr/2003:15:37:43 -0500] "GET /failpage.html HTTP/1.1" 404 310a.b.c.d - - [17/Apr/2003:15:37:44 -0500] "GET /failpage.html HTTP/1.1" 404 310a.b.c.d - - [17/Apr/2003:15:37:44 -0500] "GET /failpage.html HTTP/1.1" 404 310a.b.c.d - - [17/Apr/2003:15:37:44 -0500] "GET /failpage.html HTTP/1.1" 404 310a.b.c.d - - [17/Apr/2003:15:37:44 -0500] "GET /failpage.html HTTP/1.1" 404 310a.b.c.d - - [17/Apr/2003:15:37:45 -0500] "GET /failpage.html HTTP/1.1" 404 310a.b.c.d - - [17/Apr/2003:15:37:58 -0500] "GET / HTTP/1.1" 304 -a.b.c.d - - [17/Apr/2003:15:37:58 -0500] "GET /whole.jpg HTTP/1.1" 304 -a.b.c.d - - [17/Apr/2003:15:37:58 -0500] "GET /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=/tmp/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


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 codeThe following files were created for the purpose of this example.

9.3.1 ITSO_LogfileLite.mofThe 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.


};

9.3.2 ITSO_LogfileLite-wmi.mofThe 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_LogfileLiteIlt | | 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.javaThe 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:


// 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 Classimport 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 Classimport java.util.Vector; // Java Classimport 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(); }


//-------------------------------------------------------------------------- // 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 //--------------------------------------------------------------------------


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);


// 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.


// //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)


// 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"); 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


// 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)


// Process the ITSO_LogfileLite_FileName 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_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;


} }

//-------------------------------------------------------------------------- // //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: " +


"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 //


//-------------------------------------------------------------------------- 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.


// //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. //


//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:


// 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;


// 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.


//---------------------------------------------------------------------- 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.javaThe 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


// 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 com.tivoli.javautils.Trace; // "javautils.jar"import gnu.regexp.*; // GNU REGEXP packageimport java.lang.*; // Java Classimport java.util.*; // Java Classimport 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.


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;


}

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" ) { // If the offset is "-1", this is the first time.

retarray[0] = 0 ; // 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) { ; }


return retarray; }}

9.3.5 ITSO_LogfileLite_RM.jsThe 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//'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''


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>>


// 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>>


// Place your additional intializing code belowSvc.Trace (0, "ITSO_LogfileLite: SetDefaultConfiguration - end" );

return (0);}


// LoggingSvc.Trace (0, "ITSO_LogfileLite: Init - start" );


// 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 )


{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



// Variable Declarationvar curEventNum;

var curFileName;

var hPropTable;var iParameterCount;var iInstanceCount;var idx;var sTraceOut;


//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 );


// Variable type demonstration:Signed Integer 32curEventNum = 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);


}


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.


� Designing the ITSO_ProcessNum Resource Model

� Creating a custom script Resource Model

� ITSO_ProcessNum source code

10


10.1 Designing the ITSO_ProcessNum Resource ModelLet 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.

10.1.1 Design overviewThe 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.

Figure 10-1 Design overview of ITSO_ProcessNum Resource Model

10.1.2 What part of ITM will we use?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.

ITM engine

scripthttpdhttpdhttpdhttpdhttpdhttpdhttpdhttpd

Endpoint

Monitored Server

ProcessNum RM


Figure 10-2 ITM Engine Logical Components

10.1.3 The detailed design of the ITSO_ProcessNum Resource ModelBefore 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 designFirst, 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.



Service Object

ILTILT


JNI


Providers

DM

Cla

ssic

Mon

itor

Pro

bes

Cus

tom

Scr

ipts

JMX ILT

MBeanServer

MBean(s)

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

Chapter 10. Creating a custom script Resource Model 413

Table 10-1 The parameter


Internal designTo 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

Defining the algorithmTo 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.

Parameter Default

Process Name (STRING TYPE) httpd

Indications Default

The number of the process becomes very high > 10

The number of the process becomes high > 5

The number of the process becomes low < 2

Elements Contents

Internal Name ITSO_ProcessNum

Descriptive Name Process number



Dynamic Model none

Events Ev_process_num_becomes_very_highEv_process_num_becomes_highEv_process_num_becomes_low

Thresholds Thr_process_num_becomes_very_highThr_process_num_becomes_highThr_process_num_becomes_low

Parameters Param_proc_name

Logging none

Dependency process_num.sh


Figure 10-3 Flowchart of ITSO_ProcessNum Resource Model

Is the result very high?

End

Start

Log

Read array(i)

Is the result high?

Send event

Is the result low?

Send event

Yes

Read parameters into arrayand set i to 0

i++

Last parameter?

Run process_num.sh script

Send event

No

Yes

Yes

No

No


10.2 Creating a custom script Resource ModelAs 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


10.2.1 Using the wizard to create a custom script Resource Model1. 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/kshPROCESS_NAME=$1ps -A -o "args"|grep -v grep|grep -v $0|grep "$PROCESS_NAME"|wc -l

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 httpd 7

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.


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.

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:

bashtr -d “\015” < input_filename > output_filenamecp output_filename input_filename


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.


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.


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.


Figure 10-8 Saving the Resource Model file

10.2.2 Extending the functions of the Resource ModelYou 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.


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.


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.


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.


Figure 10-12 Changing the event setting

Table 10-4 The event of Ev_process_num_becomes_very_high

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.

Elements Contents

Internal Name Ev_process_num_becomes_very_high.

Attributes NUMERIC: ScriptResult, UpperBound_veryhighSTRING: prev_value, value, relation_delta, Param_proc_name.

Aggregation Setting

Keys Param_proc_name.

Clearing Event Yes.



Yes.

Severity CRITICAL.


Table 10-5 The event of Ev_process_num_becomes_high

Table 10-6 The event definition for Ev_process_num_becomes_low

String Resources

Descriptive Name The number of the process becomes very high.

Message The number of the process becomes very high: Process name is @Param_proc_name@: Process number is @ScriptResult@ and greater than @UpperBound_veryhigh@.

Elements Contents

Internal Name Ev_process_num_becomes_high.

Attributes NUMERIC: ScriptResult, UpperBound_highSTRING: prev_value, value, relation_delta, Param_proc_name.

Aggregation Setting


Clearing Event Yes.



Yes / Yes.

Severity WARNING.

String Resources

Descriptive Name The number of the process becomes high.

Message The number of the process becomes high: Process name is @Param_proc_name@: Process number is @ScriptResult@ and greater than @UpperBound_high@.

Elements Contents

Internal Name Ev_process_num_becomes_low.

Attributes NUMERIC: ScriptResult, LowerBound_lowSTRING: prev_value, value, relation_delta, Param_proc_name.

Aggregation Setting


Clearing Event Yes.



Yes / Yes.

Severity CRITICAL.

Elements Contents


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

String Resources

Descriptive Name The number of the process becomes low.

Message The number of the process becomes low: Process name is @Param_proc_name@: Process number is @ScriptResult@ and less than @LowerBound_low@.

Elements Contents

Elements Value

Internal Name Thr_process_num_becomes_very_high

Descriptive Name Threshold for very high

Default Value 10

Description Threshold for very high


Table 10-8 The threshold definition for Ev_process_num_becomes_high

Table 10-9 The threshold definition for Ev_process_num_becomes_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.

Elements Value

Internal Name Thr_process_num_becomes_high

Descriptive Name Threshold for high

Default Value 5

Description Threshold for high

Elements Value

Internal Name Thr_process_num_becomes_low

Descriptive Name Threshold for low

Default Value 2

Description Threshold for low


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 User’s 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.


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: function VisitTree(Svc)2: {3: var curScriptResult;4: var hashKey;5: var found;6: var OldScriptResult;7: var hPropTable;

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.


8: var ProbeArgCount;9: var ProbeArgIdx;10: var ParamCount;11: var ParamIdx;12: var Different;13: 14: //Define additional parameters15: var NumOfParam;16: var ParamTmp;17: 18: //Count the number of parameters19: NumOfParam = Svc.GetStrParameterCount("Param_proc_name");20: 21: hPropTable = Svc.CreateMap();22: 23: //Start the loop24: for (i = 0; i < NumOfParam ; i++) {25: 26: //Get the parameter27: ParamTmp = Svc.GetStrParameter("Param_proc_name",i);28: 29: //Implementation for the monitor ScriptResult30: Svc.RemoveMapAll(hPropTable);31: 32: //Set the loop id to hashkey33: hashKey = i ;34: 35: //Modify the argument for the custom script36: 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: else43: 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 hPropTable51: Svc.SetMapStrElement(hPropTable,"Param_proc_name",ParamTmp);52: Svc.SetMapNumElement(hPropTable,"UpperBound_veryhigh",Svc.GetThreshold("Thr_process_num_becomes_very_high"));


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 thresholds57: 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 loop74: }75: 76: Svc.DestroyMap(hPropTable);77: 78: return (0);79: 80: }

10.2.3 PackagingThe 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.


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.tarIBM Tivoli Monitoring - Adding new Resource ModelCopying ITSO_ProcessNum.cat msgfile ...Copying ITSO_ProcessNum.cat zipfile ...IBM Tivoli Monitoring - Resource Model utilityParsing 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.

Dependencies Files


Custom Scripts()process_num.sh

Custom Files(s)


Dynamic Model(s):none


ITSO_ProcessNum.js

Message Catalogs


Event(s):Ev_process_num_becomes_very_high

Ev_process_num_becomes_highEv_process_num_becomes_low

Action(s):

Threshold(s):Thr_process_num_becomes_very_high

Thr_process_num_becomes_highThr_process_num_becomes_low

Logging:

Parameter(s):Param_proc_name


10.2.4 Testing the Resource ModelYou 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 environmentTo 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 profileAfter 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.


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.


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.


Figure 10-18 Event I of the ITSO_ProcessNum

Testing the ITSO_ProcessNum Resource ModelIn 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.


� 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 -verboseForwarding 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 Normal

CASE 2 Ev_process_num_becomes_high

CASE 3 Ev_process_num_becomes_very_high

CASE 4 Ev_process_num_becomes_low


Let us summarize our test results:

Case 1: Normal

Description Change the number of the httpd processes to 4 and check that no event is generated.

Procedure Start httpd by setting StartServers to 4 and MinSpareServers to 3 in the httpd.conf.

Result 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 -verboseForwarding 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: Ev_process_num_becomes_high

Description Change the number of the httpd processes to 7 and check that the Ev_process_num_becomes_high is generated.

Procedure Restart httpd by setting StartServers to 7 in the httpd.conf.

Result The Ev_process_num_becomes_high was generated.

The Case 2 results are shown in Example 10-7.



[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


Ev_process_num_becomes_high;modelname="ITSO_ProcessNum";profilename="customscriptRM-PF#pacs007-region";prev_value="5";event_key="Ev_process_num_becomes_high|Param_proc_name=httpd;";param_proc_name="httpd";value=" 8";eventid="1048797190198";relation_delta="-3";severity="WARNING";upperbound_high= 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: Ev_process_num_becomes_very_high

Description Changes the number of the httpd processes to 12 and checks that the Ev_process_num_becomes_very_high is generated.

Procedure Restarts httpd after setting StartServers to 12 in the httpd.conf.

Result The Ev_process_num_becomes_very_high was generated. Then the Ev_process_num_becomes_high was cleared.




[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="customscriptRM-PF#pacs007-region";prev_value="8";event_key="Ev_process_num_becomes_very_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


<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_num_becomes_high|Param_proc_name=httpd;";severity="HARMLESS";distrib_admin="Root_pacs007-region";hostname="pacs006-ep";origin="9.3.5.36";adapter_host="pacs006-ep";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: Ev_process_num_becomes_low

Description Stops the httpd and checks that the Ev_process_num_becomes_low is generated.

Procedure Stops httpd.

Result The Ev_process_num_becomes_low was generated. Then the Ev_process_num_becomes_very_high was cleared.




[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="customscriptRM-PF#pacs007-region";prev_value="11";event_key="Ev_process_num_becomes_low|Param_proc_name=httpd;";param_proc_name="httpd";value=" 0";eventid="1048797700187";relation_delta="11";severity="CRITICAL";lowerbound_low= 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


TMW_Clearing;modelname="ITSO_ProcessNum";profilename="customscriptRM-PF#pacs007-region";eventname="Ev_process_num_becomes_very_high";eventid="1048797430190";event_key="Ev_process_num_becomes_very_high|Param_proc_name=httpd;";slotkey="Ev_process_num_becomes_very_high|Param_proc_name=httpd;";severity="HARMLESS";distrib_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 codeThe following files were created for the purpose of this example.

10.3.1 ITSO_ProcessNum.jsThe 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;


// General info section


//<<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>>


// 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


// 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 valuesfunction 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 herefunction 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 parametersNumOfParam = Svc.GetStrParameterCount("Param_proc_name");


//Start the loopfor (i = 0; i < NumOfParam ; i++) {

//Get the parameterParamTmp = Svc.GetStrParameter("Param_proc_name",i);

//Implementation for the monitor ScriptResultSvc.RemoveMapAll(hPropTable);

//Set the loop id to hashkey


hashKey = i ;

//Modify the argument for the custom scriptcurScriptResult = 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 hPropTableSvc.SetMapStrElement(hPropTable,"Param_proc_name",ParamTmp);

Svc.SetMapNumElement(hPropTable,"UpperBound_veryhigh",Svc.GetThreshold("Thr_process_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 thresholdsif (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);


// End of the loop}

Svc.DestroyMap(hPropTable);

return (0);

}

10.3.2 ITSO_ProcessNum.kshThe 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/kshPROCESS_NAME=$1ps -A -o "args"|grep -v grep|grep -v $0|grep "$PROCESS_NAME"|wc -l


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.

11


11.1 Engine component utilization: OverviewIn 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.

Figure 11-1 Resource Model sub-components for Windows



TMWService

WMI APIs

WMI (CIMOM)


JMX ILTILT


MBeanServer


WM

I P

rovi

der

DLL

s

Resource


Resource

Providers

CO

M O

bjec

ts

DM

Cla

ssic

Mon

itor

Pro

bes

Cus

tom

Scr

ipts

ILT

JNI

BinaryLibrary

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel


Figure 11-2 Resource Model sub-components for Java

11.2 Compiling DMXFile MOF into WorkbenchBefore 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 monitorFollow 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.



Service Object

ILTILT


JNI


Providers

DM

Cla

ssic

Mon

itor

Pro

bes

Cus

tom

Scr

ipts

JMX ILT

MBeanServer

MBean(s)

ResourceModel

ResourceModel

ResourceModel

ResourceModel

ResourceModel

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 fileThe 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 repository1. 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).


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).


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).


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).


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).


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.


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.


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).


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


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 Model1. 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.


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.


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.


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.


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


6. The IBM Tivoli Monitoring Workbench window will now be presented, as shown in Figure 11-21.


11.3.1 Constructing the Resource Model: EventsIn 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


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.



3. Your Workbench should now have two events defined, as shown in Figure 11-24 on page 467.



11.3.2 Constructing the Resource Model: ParametersIn 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.


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.



11.3.3 Constructing the Resource Model: DependenciesIn 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.


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 codeWe 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


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 valuesfunction 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");



return(1); }

for (k=0; k < dimension ; k++) { check [k]= -5 ; cTime [k]= -5 ; mTime [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 herefunction VisitTree(Svc){

Svc.Trace(2,"Start evaluate");var instancesF=0;var i=0;var j=0;var k=0;

var numsize =0;var nummodificationTime = 0;var numchangeTime = 0;var numcrc32 = 0;

var strsize ="";var strnummodificationTime = "";var strnumchangeTime = "";var strnumcrc32 = "";

var strpathName ="";var FileAction="";var TempCmd;var curScriptResult;



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;


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 = 2;}if ((nummodificationTime != mTime[ j] ) && (nummodificationTime !=

-1 )) {mTime[j]= nummodificationTime;if (FileAction =="Restore") {



flagEvent = 2;}

}}if ((numcrc32 != check[j] ) && (numcrc32 != -1)) {

check[j]= numcrc32;if (FileAction =="Restore") {


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 subroutineThis 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.


Init subroutineThe 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 subroutineThis 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.


Part 3 Appendixes

Part 3


Appendix A. Testing a Java Resource Model

This appendix describes how to test a Resource Model from a developer’s 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.

A


ITM Engine tracing and clean-up

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, don’t remove __namespacerm $LCFNEW/Tmw2k/Unix/data/cimom/persistence/classes/root/<mof filenames># removes the ilts and providers classesrm $LCFNEW/Tmw2k/Unix/Classes/com/tivoli/dmunix/ep/ilts/*.classrm $LCFNEW/Tmw2k/Unix/Classes/com/tivoli/dmunix/ep/providers/*.class#removes the javascript filerm $LCFNEW/Tmw2k/Unix/Dec/*.js# removes Resource Modelsrm $LCFNEW/Tmw2k/Unix/data/rm/*.ziprm $LCFNEW/Tmw2k/Rm/*.zip# removes the logsrm $LCFNEW/AMW/logs/*.log

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.


rm $LCFNEW/AMW/logs/*.old# removes the profilesrm $LCFNEW/Tmw2k/Unix/data/profiles/*.dmprf

Push the profile and analyze the log files for possible bugs.

Debugging the Init functionThe 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= Svc.GetStrParameterCount("filenameDifference");dimension2= Svc.GetStrParameterCount("filenameCRC");dimension3= Svc.GetStrParameterCount("driveletter");dimension4= 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

1 The wadminep command has several unsupported options, such as view_directory <directoy-name> and remove_file <file-name>.


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 Verifies whether an event has arrived or not.

wtdumper –d 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 FALSERemoves 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.


Debugging the VisitTree functionThe 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 User’s 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.


Simulating data ProvidersThe 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,


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 loggingAnother 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.


http://www.quadcap.com/home.html

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.


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.

TablesThe tables created on the engine local database follow.

Table A-1 Endpoints

Field name Data type Notes

EID INTEGER Automatically generated number.

HOST_NAME VARCHAR(120)

IP_ADDRESS VARCHAR(20)

ENDPOINT_LABEL VARCHAR(64)

GMT_OFFSET INTEGER Minutes in the range [-720,720].


Table A-2 RmProfiles

Table A-3 Resources

Table A-4 Metrics


CATEGORY VARCHAR(128)

PROFILE VARCHAR(256)

RESOURCE_MODEL VARCHAR(128)

ID BIGINT This is the CRC32 of the key fields [0,2^32-1].

EID INTEGER

INSERT_SEQ INTEGER Automatically generated number used by the ETL1.


RESOURC VARCHAR(128)

CONTEXT VARCHAR(256)

RCID BIGINT

ID BIGINT This is the CRC32 of the key fields [0,2^32-1].

EID INTEGER



NAME VARCHAR(120) Automatically generated number.

RCID BIGINT

MID BIGINT This is the CRC32 of the key fields [0,2^32-1].

STAT VARCHAR(8)

EID INTEGER



Table A-5 Instances

Table A-6 Categories

Table A-7 MetricsData


INSTANCE_KEY VARCHAR(2096)

IID BIGINT This is the CRC32 of the key fields [0,2^32-1].

RCID BIGINT

EID INTEGER



NAME VARCHAR(128)

RCID BIGINT

CID BIGINT This is the CRC32 of the key fields [0,2^32-1].

EID INTEGER



MID BIGINT

METRICVALUE FLOAT

TIMEKEY INTEGER Number of seconds since the epoch.

TIMEKEY_DTTM TIMESTAMP

IID BIGINT

EID INTEGER



Table A-8 CategoriesData


CID BIGINT

CATEGORYVALUE VARCHAR(128)

TIMEKEY INTEGER Number of seconds since the epoch.

TIMEKEYDTTM TIMESTAMP

IID BIGINT

EID INTEGER



Appendix B. Additional material

This redbook refers to additional material that can be downloaded from the Internet as described below.

Locating the Web materialThe 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 materialThe additional Web material that accompanies this redbook includes the following files:

File name Descriptionsg246900.zip Zipped Code Samples

B


ftp://www.redbooks.ibm.com/redbooks/sg246900




System requirements for downloading the Web materialThe following system configuration is recommended:

Hard disk space: 5 MB minimumOperating System: Windows or UNIXProcessor: AnyMemory: Any

How to use the Web materialCreate a subdirectory (folder) on your workstation, and unzip the contents of the Web material zip file into this folder.


acronyms

API Application Programming Interface

CIM Common Information Model

CIMOM CIM Object Management

COM Component Object Model

DLL Dynamic Link Library

DM Distributed Monitoring

DMI Desktop Management Interface

DMTF Desktop Management Task Force

GUI Graphical User Interface

IBM International Business Machines Corporation

IDE Integrated Development Environment

IDL Interface Definition Language

ILT Information Library Type

ITM IBM Tivoli Monitoring

ITMWB IBM Tivoli Monitoring Workbench

ITSO International Technical Support Organization

JDK Java Development Kit

Abbreviations and

© Copyright IBM Corp. 2003. All rights reserved.

JMX Java Management Extension

JNI Java Native Interface

JRE Java Runtime Environment

JVM Java Virtual Machine

LCF Light Client Framework

LCFD Light Client Framework Daemon

M12 Manageability

M9 Management

MCSL Monitoring Collection Specification Language

MDAC Microsoft Data Access Components

MIB Management Information Block

MIF Management Information Format

MOF Managed Object Format

NFS Network File System

NIC Network Interface Card

ODBC Open Database Connectivity

OID Object ID

PAC Proactive Analysis Component

RDBMS Relational Database Management System

RPC Remote Procedure Call

497

SDK Software Development Kit

SNMP Simple Network Management Protocol

TBSM Tivoli Business Systems Manager

TEC Tivoli Enterprise Console

TEDW Tivoli Enterprise Data Warehouse

TMF Tivoli Management Framework

TMR Tivoli Management Region

TSL Touchpoint Service Layer

VB Visual Basic

VBA Visual Basic for Applications

WBEM Web-based Enterprise Management

WMI Windows Management Instrumentation


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 RedbooksFor 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 publicationsThese publications are also relevant as further information sources:

� IBM Tivoli Monitoring Resource Model Reference Version 5.1.1, SH19-4570

� IBM Tivoli Monitoring User’s Guide Version 5.1.1, SH19-4569

� IBM Tivoli Monitoring Workbench User's Guide Version 5.1.1, SH19-4571

Online resourcesThese Web sites and URLs are also relevant as further information sources:

� How to use the Microsoft Script Debugger


� IBM Redbooks


� Java SDK download

http://java.sun.com




http://java.sun.com

� Microsoft Script Debugger


� Microsoft Windows Developer Network


� Microsoft Windows Script Host Information


� Microsoft Windows SNMP download


� Microsoft WMI information


� Mozilla.org Rhino Downloads


� QuadCab


� Regular Expressions for Java


� Rhino


� Rhino Debugger


� Sax Interpreter


� Sax.net


� Tivoli Developer’s Domain

http://www.ibm.com/software/tivoli/info/pa/monitor/index.jsp

� Tivoli Management Extensions for Java (TMX4J) at IBM AlphaWorks


� WBEM Initiatives at DMTF















http://www.ibm.com/software/tivoli/info/pa/monitor/index.jsp



� WMI Providers


� WMI SDK


How to get IBM RedbooksYou 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






Index

Symbols.dmjsws 26.dmws 26/etc/hosts 447/etc/passwd 447

AAction manager 20, 23Active Directory 116ActiveX 448, 471additional variables 429aggregated 18aggregator 71aifIndex 253aiInst 350algorithm 268Analyzer 8, 20–21analyzer component 8Application Programming Interfaces (APIs) 9argument 429asHostnames 252asITSO_LogfileLite_Pattern 349asITSOArrayGui 350AssociateParameterToClass 267, 348, 364, 372AssociateParameterToClass method 346Associations 114

BBAROC 26best practice 68best practices 76

CC++ 116, 129ChangeAction 467, 477CIM 9, 68, 111, 139

name space 31CIM browser 31–32, 343

limitation 32CIM Class 264, 343CIM class 156, 167, 233CIM class property 483

© Copyright IBM Corp. 2003. All rights reserved.

CIM classes 321CIM definition 138, 232–233, 248CIM Name space 211CIM object 251CIM Object Manager (CIMOM) 114CIM properties 249, 344CIM Provider Layer 115CIM Qualifiers 143, 237CIM repository 70, 237CIM schema 114CIM values 336CIMOM 264class

PhysicalDisk 32TMW_PhysicalDisk 31

Class Declarations 115class property 248CLASSPATH 342, 357classType 328clean ITM Engine 482cleanrm.sh 482clearing event 71Collected Instances 216collection 168Collection Test 215COM object 124COM objects 115COM+ architecture 201command

wdmwbcli 62Commenting Java Files 146, 157, 240Commenting MOF Files 143Common Components 121Common Information Model (CIM) 6, 9, 70Compatibility Mode 109compile 342, 357compiled 143, 172Configuring the SNMP Agent 207consecutive holes 71Correlated events 98CPU Resource Model 99create 133, 153, 247, 347cross-platform 201CSL 50

503

curEventNum 374CurrentDiskQLength 35custom ILT 231Custom Methods 154, 158, 247, 251custom numeric monitor 50custom script 411, 416custom string monitor 50Cycle Time 463Cycle time 31cycle time 320, 434cycles 70

Ddata Provider 487data source type

CIM/WMI 50Custom script 50DM Classic Edition Collection 50

debug 223, 258debugging

Resource Model 48Decision Tree 41decision tree 71decision tree script 28, 69, 339, 346, 348, 365, 370, 414, 428DefineClass 264DefineStrParameter 164, 266Dependencies 18–19, 69, 327dependencies 469Description qualifier 237DescriptiveName 467destroy 133, 153, 247, 347dimension 267DiskBytesSec 35distribute 223Distributed Management Task Force, Inc. 112DM collections 127DM custom scripts 127dm_m12.jar 241DMCollectEPLog 484DMI 112dmjsws 58DMLinkJre 376DMTF 112dmws 58DMXFile 449DMXFile.dmjsws 449Dynamic Link Libraries (DLL) 19

dynamic MIB values 235Dynamic Model 8, 28, 34, 42, 162, 321, 477Dynamic Model components 263Dynamic Model elements 41Dynamic Models 69dynamic value 141dynamically plug-able 234

EEmptyParameter 485Endpoint 6engine 3ensureElements method 260ENUM 238Enum 131, 145enumerateInstances 132, 148, 151, 244, 251, 347, 350Enumeration 148Enumeration class 241error code 166Ev_ITSO_LogfileLite_EventNum_too_high 365Ev_LogEvent 325Ev_process_num_becomes_high 430, 439Ev_process_num_becomes_low 441Ev_process_num_becomes_very_high 430, 440Ev_process_num_ksh_httpd_ScriptResult_too_high 423Event aggregator 20–21event aggregator 35, 42Event correlator 20, 22event element

propertiesActions 37Aggregation settings 37Attributes 36Internal name 36Notification 37String resources 37

event elements 34–35, 41EventLog Resource Model 97EventNum 351, 362, 383Events 18–19, 69–70, 379, 436, 464events 18, 370External design 204, 413

FFile Resource Model 101File system Resource Model 103


FileChangeOnly 464FileChangeRestored 465FileName 308FlagFirstTime 477flowchart 339

GGET 238getifDescr 254getifIndex 253getifInOctets 254getifOutOctets 255getifSpeed 254getInstances 251getITSO_Instances 158, 350getITSO_LogfileLiteVar_EventNum 351, 354getITSO_SampleVar_bln 160getITSO_SampleVar_r 160getITSO_SampleVar_si 159getITSO_SampleVar_str 159getITSO_SampleVar_ui 160getITSOAttribute 154, 159, 248, 253–254, 347, 349GetLastModDate 471getmatch 354GetMultipleProperties 348getMultipleProperties 132, 150, 242, 346getNext 257GetNumProperty 373GetPropert 348getProperty 132, 149, 242, 346GetShellRetCode 429GetStrParameter 429GetStrParameterCount 429GetStrProperty 373GNU Regexp Java package 342gnu.regexp package 354gnu-regexp-1.1.1.jar 327

HhashKey 219hashkey variable 429Health Console 19hole 18holes 21, 70hPropTable 219, 328, 332, 430HTML 116httpd 412, 434httpd.conf 439

IIBM AlphaWorks 133IBM HTTP Server 434IBM SNMP Java package 231IBM Tivoli Data Warehouse 4, 6IBM Tivoli Event Console 4IBM Tivoli Monitoring Workbench 4IBM Tivoli Web Health Console 4ifDescr 214, 234, 254ifIndex 214, 234ifIndex class 253ifInOctets 214, 234, 254ifInOctets MIB variable 203ifInOctets property 217ifNumber 256, 259ifOutOctets 202, 214, 234, 255ifOutOctets MIB variable 203ifOutOctets property 217ifSpeed 214, 234, 254ILT 8, 12, 137–138, 486ILT Class 354ILT class 138, 145, 167, 178, 234, 267, 347, 357ILT classes 120ILT code 346, 382ILT developer 156ILT Interface class 147ILT Interface Implementation 148ILT Java Class 239ILT Provider 133ILT Provider Interface 131ILT Providers 176ILT Public Operations (Methods) 148ILT Supported Classes 153ILT template 232ILTInterface 131, 146, 234ILTInterface class 345ILTInterface class interface 241ILTInterface methods 239ILTManagerForJava1.log 12indication generation 42Indications 436indications 18, 70Init 166, 267, 332, 348, 372, 471Init function 484initialization 166initVector 258Installing SNMP Service 206Instance Declarations 115Instance discovery 235

Index 505

Instance initialization 141, 235instance management 250instrumentation 4, 23Instrumentation LIbrary Type (ILT) Providers 123Instrumentation Library Type Interface (ILT) 147Integrated Development Environment (IDE) 25integration point 255Interface Definition Language (IDL) 114Interfaces group 202Internal design 205, 414InternalName 464–465, 467interpreter

Rhino 48, 64Sax 48, 64

interpType 328, 477invokeMethod 132, 152, 246, 347islogging 11, 15ITM Data Warehouse 19ITM Engine 8–9, 68, 111ITM Engine Components 120ITM Engine loader 147, 240ITM Engine log file 167ITM Java engine 238ITSO_ArrayGUI 163, 166, 265ITSO_Hostnames 267ITSO_Lab03-unix.mof 322ITSO_Lab03-wmi.mof 313ITSO_LogfileLite 334ITSO_LogfileLite CIM class 362, 372ITSO_LogfileLite ILT 334, 346ITSO_LogfileLite Provider 346ITSO_LogfileLite.jar 381ITSO_LogfileLite.java 353, 357, 401ITSO_LogfileLite.js 381ITSO_LogfileLite.mof 343, 359, 384ITSO_LogfileLite_FileName 348, 350, 368, 372, 378ITSO_LogfileLite_Pattern 348, 368, 372, 378ITSO_LogfileLite_RM.js 405ITSO_LogfileLiteILT.java 357, 385ITSO_LogfileLite-wmi.mof 343, 381, 385ITSO_ProcessNum 412–413, 432ITSO_ProcessNum.js 438, 442ITSO_ProcessNum.ksh 446ITSO_RMs 139ITSO_Sample 137, 140, 147, 156, 158, 162, 195ITSO_Sample ILT 231ITSO_Sample template 246ITSO_Sample.dmjsws 143, 173

ITSO_Sample.jar 147, 173ITSO_Sample.java 142, 147, 171, 192ITSO_Sample.mof 142, 170, 173, 176ITSO_SampleILT 145, 156–157ITSO_SampleIlt 140, 148ITSO_SampleILT.java 172ITSO_SampleIlt.java 142, 148, 178ITSO_SampleVar_bln 140ITSO_SampleVar_inst 139ITSO_SampleVar_r32 140ITSO_SampleVar_r64 140ITSO_SampleVar_si 159ITSO_SampleVar_si16 140ITSO_SampleVar_si32 140ITSO_SampleVar_si64 140ITSO_SampleVar_si8 140ITSO_SampleVar_str 139ITSO_SampleVar_ui16 140ITSO_SampleVar_ui32 140ITSO_SampleVar_ui8 140ITSO_SNMP_Interface_Bps 202, 221ITSO_SNMP_Interface_Bps.vba 225ITSO_SnmpProbe 234–235, 241, 249, 251, 264ITSO_SnmpProbe CIM class 244ITSO_SnmpProbe class 237, 261ITSO_SnmpProbe ILT 231ITSO_SnmpProbe.dmjsws 237, 274ITSO_SnmpProbe.jar 241, 273–274ITSO_SnmpProbe.Java 292ITSO_SnmpProbe.java 236, 241, 272ITSO_SnmpProbe.mof 236, 242, 270, 274, 277ITSO_SnmpProbeILT 239, 249, 251, 253–254ITSO_SnmpProbeIlt 234, 238, 241ITSO_SnmpProbeILT class 242ITSO_SnmpProbeILT.Java 278ITSO_SnmpProbeILT.java 273ITSO_SnmpProbeIlt.java 236

Jjar 273jar file 357jar files 12, 15, 18Java 8, 12, 15, 129Java class 345Java classes 19, 115, 240Java compiler 171Java Engine 120Java engine 8


Java files 357Java ILT 165, 336Java ILT class 125Java Imports 147, 158, 240, 250Java Management Extensions (JMX) 117, 133Java Native Interface (JNI) 140Java Package 147, 157, 232, 240, 250Java package 173Java package file 273Java pointers 241Java RDBMS 19Java Resource Model 481Java Runtime Environment 376java.util.Enumeration 241java.util.Vector 241javac 171–172, 271–273JavaScript 17–18, 47, 76, 165, 263, 300, 476JavaScript function 266JavaScript Resource Model 417javautils.jar 147JDK 271–273JMX 117JMX Agent 118JMX Architecture 117JMX ILT 123JMX instrumentation 118JMX Manageable Resources 118JNI 156JNI & Native binary libraries 123JNI API 156JRE 305

Kkey property qualifier 145, 239

Llanguage

scripting 47library 238LogEvent 316log-file adapter 305Logger 20, 22Logging 18, 69logging element 41

propertiesContext 41Properties 41Resource 41

logging elements 40logging.properties 11Logical Components 141, 203, 235logical components 15, 68, 120Logical Disk Resource Model 91

MM12 129, 139–140Manageability 8M12 functionality 234M12 interfacing 247M12 layer 251M12 method calls 239M12 Public Operations 239M12 qualifier 145M12 qualifiers 146, 233M12 specification 148, 242, 246M12_Instrumentation 131, 145, 238M12_Instrumentation qualifier 149, 242M12ClassPath 153M12Exception 153M12IdentityElement 153M12JavaProvider 126, 144, 238m12javaProvider 376M12ObjectIdentity 153M12PropertySet 153, 156, 350M12PropertySet class 249, 251Management 8Manageability 129manageability 8Manageability (M12) Model Specification 129Managed Object Format (MOF) 17, 114, 143Managed Object Format (MOF) file 232Managed Objects 116Managed Resource 110–111Management 129Management Application 110management applications 116Management Framework 8management function 8MBean 118MBeans 117MCSL 50MDAC 19Memory Resource Model 84, 100method

SendEvent 36SendEventEx 36

Index 507

Svc.DefineClass 33Svc.DefineEvent 36Svc.DefineThreshold 46Svc.GetModelName 29Svc.GETNUMOFINST 45Svc.GetNumProperty 45Svc.GetNumPropery 45Svc.GetStrProperty 45Svc.GetThreshold 46Svc.LogInst 41, 45Svc.LogInstEx 41Svc.SENDEVENT 46Svc.SendEventEx 36Svc.SetModelName 29SvcSendEvent 36

metric data 19MIB 111, 232MIB data 250MIB fields 249MIB II 256MIB information 233MIB values 232MIB variable 202mib_ii.mib 210MIB-II specification 202Microsoft Access 12Microsoft Access 2000 Jet engine 19, 22Microsoft ActiveX 116Microsoft script debugger 64Microsoft Script Host 124MIF 112MinSpareServers 439MOF 12, 111MOF Compile Wizard 360MOF Compiler 313, 359MOF file 143, 176, 237, 361, 449MOF files 307, 358MOF specification 114MOF syntax 114MOF Usage 114mofcomp 170, 270monitoring algorithm 18, 429MS TCP Loopback Interface 216msg_dmxengine.log 13, 383msg_ILTManagerForJava.log 12multiple parameters 428multiple thresholds 413

Nname space

root/CIMV2 31Namespace 212, 313namespace 115, 233, 359, 453Network Devices 111Network Interface Card Resource Model 87Network Interface Resource Model 102Network Interfaces 244Network RPC/NFS Resource Model 106Non-Standard CIM Qualifiers 130nstalling WMI SNMP 208NUMERIC 418

OObject creation 235object oriented language 259occurrence 70occurrences 21–22offsetarray 348, 351ogging.properties 15OID 232, 261OID structure. 259OIDs 250open database connectivity (ODBC) 116operating system libraries 9

PPAC 147Packaging 169Param_proc_name 435parameter 265, 428Parameters 8, 18, 69, 72, 163, 467parameters 8, 232, 335, 368, 370, 413ParameterSet 153ParameterSetList 153parametric 418Parametric event log Resource Model 89Parametric TCP/IP Ports Resource Model 90pattern matching 338PDU 261PDU class 261Perfmon 45Physical Disk Resource Model 92Physical Managed Objects 111PhysicalDiskModel 27, 32PID 232pragma 126


Process Resource Model 101process_num.ksh 438Processor Resource Model 94Property tables 330Provider 9, 68, 73, 75, 138, 144, 165, 238, 486Provider class 138, 192, 235, 345, 353, 357Provider classes 147Provider code 346Provider instances 154Provider Java Class 156Provider Java classes 233Provider Layer 20, 23Provider layer 9Provider template 176Providers 116, 123public operations (methods) 242

QQED 488QuadCap 488Quadcap 15Qualifiers 130

RRedbooks Web site 501

Contact us xxiregular expression 338, 378relationship diagram 169resource class

Class properties 33Collection info 33Filtering 33property fields 33

Resource Kit 64Resource Model 4, 8, 17

Category descriptive name 30Category internal name 30creating

Empty Resource Model 49recommendation 49Resource Model wizard 48Step-by-step Resource Model 48

Cycle time 31debugging 48Description 30Descriptive name 29Internal name 29Major and minor version 31

properties 29Supported platforms 31

Resource Model JavaScript 195Resource Model Tar File 169, 270, 375Resource Model tar file 221, 432Resource Model threads 44Resource Models 26Resources 9, 123response script

variables 36retrieval 254RFC1213 MIB-II 202Rhino

Debugger 65shell 64Web sites 64

Rhino interpreter 48, 64roll-up 168root/CIMV2 51root/CIMV2 namespace 359rotation function 336

SSax interpreter 48, 64Saxsoft Web site 64Scheduler 20–21scripting

language 47Scripting.FileSystemObject 471ScriptResult 420SDK 341Security Resource Model 104sendEmptyParameter function 485SendEventEx 374, 430sendFileDoesNotExist 486Service Layer 110Service Object API 17Services Resource Model 95Session management 239SetCycleTime 263SetDefaultConfiguration 163–165, 263, 266, 328, 332, 370SetModelName 263SetProfileName 263setProperty 132, 152, 246, 347, 350shell script 165Shell() method 430sHostname 256

Index 509

simulated data Provider 486SMIR 210SNMP 111, 201, 232SNMP capable 265SNMP classes 235SNMP configuration 207SNMP Java package 250SNMP MIB Network Interface 239SNMP Module Information Repository (SMIR) 210SNMP OID values 250SNMP package 235, 255SNMP polling 234, 241SNMP probe 233SNMP Providers 208SNMP query 260SNMP session 242, 256, 258SNMP_RFC1213_MIB_ifTable 213SnmpInterface 239SnmpInterface class 242, 250–251, 253, 260SnmpInterface.Java 300SnmpInterface.java 237, 252, 271SnmpMacro 213SnmpObjectType 213SnmpPDU class 257snmpPole 252, 255snmpPole method 260source code 277sProperty 351Standard CIM Qualifiers 130StartServers 439static value 141Str(curifIndex) 219String object 249string property 163STRING TYPE 428sValue 351Svc.CreateMap() 219Svc.DefineStrParameter 164Svc.Shell method 430syntax 361

TTCP/IP Resource Model 96TEC 325, 464TEC baroc file 63test 481The Common Information Model (CIM) 113Thr_EventNum_gt 367, 374

Thr_ScriptResult_gt 427threshold 18, 70threshold element

propertiesDefault value 39Description 39Descriptive name 39Internal name 39

threshold elements 35, 38, 41threshold setting 427Thresholds 18, 69–70thresholds 335, 370, 413, 434Tivoli Distributed Monitoring 109Tivoli Distributed Monitoring Notice Group 485Tivoli Endpoint 8Tivoli Enterprise Console (TEC) 485Tivoli Enterprise Data Warehouse (TEDW) 218TMW_HighPercentUsage 38TMW_HighProcesses 22TMW_PhysicalDisk 29TMW_PhysicalDiskModel 27TMW_ProcessHighCPU 22TMW_ProcessHoggingCPU 22TMW_SlowPhysicalDrive 35Tmw2k 8tmw2k 70Tmw2k.exe 332Tmw2k.log 11TMWService 8TMX4J 133tools 62top-down methodology 232Touchpoint 6, 8Touchpoint Service Layer (TSL) 129Touchpoint service layer (TSL) 8Trace class 147, 241trace level 382trace logs 19trace_dmxengine.log 13, 147–148, 241, 266, 382, 484trace_dmxeu.log 13trace_dmxntv.log 13trace_ILTManagerForJava.log 12tracing 234trigger condition 419Triggering Condition 218TSL 140


UUNIX MOF file 343updateInterfaces 260updateInterfaces method 257

Vvariable definitions 45VBA 12, 15, 76Vector class 259vector list 258Vector management 239vector management 258vector table 250, 253–254Vector vParam 349–350VisitTree 18, 42, 167, 219, 268, 331–332, 373, 476–477VisitTree function 487VisitTree methods 483VisitTree subroutine 477Visual Basic 17–18, 42, 47, 116

Wwadminep 484WBEM 113WBEM specification 125wbemsnmp.ex_ 209wbemsnmp.exe 209wdmcmd 12, 15, 482wdmlseng 383, 438, 483wdmrm 482wdmtrceng 19, 382, 482wdmwbcli 63Web Health Console 63Web-Based Enterprise Management 113WHERE Clause 33Windows Management Instrumentation (WMI) 6Windows Management Interface (WMI) 115wmftools.jar 327WMI 8, 68WMI Infrastructure 116WMI Management Applications 117WMI MOF compiler wizard 455WMI Performance Monitoring Provider 42WMI Providers 64, 70WMI repository 116WMI SDK 63WMI SNMP Provider 201–202Workbench

CLI 62defined 25three panes 27

WQL filter 33WriteBuffer 156, 249wrmadd 26

XXML 14xmof 126

Index 511

(1.5” spine)1.5”<->

1.998”789 <

->1051 pages

IBM Tivoli M

onitoring Version 5.1.1: Creating Resource M

odels and Providers

®

SG24-6900-00 ISBN 0738453102

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICALINFORMATION BASED ONPRACTICAL 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


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.

Back cover

Ibm tivoli monitoring version 5.1.1 creating resource models and providers sg246900

Technology

Transcript of Ibm tivoli monitoring version 5.1.1 creating resource models and providers sg246900