agentbuilder6225 user

8/15/2019 AgentBuilder6225 User

1/553

Tivoli ® IBM Tivoli Monitoring Agent Builder Version 6.2.2.5

User’s Guide

SC32-1921-09


2/553


3/553

Tivoli ® IBM Tivoli Monitoring Agent Builder Version 6.2.2.5

User’s Guide

SC32-1921-09


4/553

NoteBefore using this information and the product it supports, read the information in Appendix O, “Notices,” on page 529.

This edition applies to version 6.2.2.5 of IBM Tivoli Monitoring Agent Builder and to all subsequent releases andmodifications until otherwise indicated in new editions.

© Copyright IBM Corporation 2007, 2010.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.


5/553

Contents

Figures . . . . . . . . . . . . . . vii

Tables . . . . . . . . . . . . . . . xi

Chapter 1. Introduction . . . . . . . . 1About IBM Tivoli Monitoring Agent Builder. . . . 1About Eclipse . . . . . . . . . . . . . . 1New in this release . . . . . . . . . . . . 2About this guide . . . . . . . . . . . . . 2

Chapter 2. Getting startedquick-reference guide . . . . . . . . . 3

Chapter 3. Installing the IBM TivoliMonitoring Agent Builder . . . . . . . 5Software requirements . . . . . . . . . . . 5Authorization . . . . . . . . . . . . . . 6Builder installation procedure. . . . . . . . . 6After installing . . . . . . . . . . . . . 11Silent installation . . . . . . . . . . . . 11Uninstalling Agent Builder . . . . . . . . . 12Silent uninstallation . . . . . . . . . . . 13

Chapter 4. Starting the Agent Builder 15Planning and overview . . . . . . . . . . 15Starting the Agent Builder . . . . . . . . . 15

Chapter 5. Creating a basic agent . . . 17

Operating system requirements. . . . . . . . 17Starting the new agent wizard . . . . . . . . 18

Using the icon to start the wizard . . . . . . 18Creating a new file to start the wizard . . . . 18

Creating and defining the agent . . . . . . . 23Naming your agent. . . . . . . . . . . 23Defining initial data source . . . . . . . . 28Selecting key attributes . . . . . . . . . 29Defining additional data sources . . . . . . 30Organizing the agent . . . . . . . . . . 33

Navigator groups . . . . . . . . . . 33Subnodes . . . . . . . . . . . . . 34Moving existing data sources . . . . . . 35

Preparing your agent for modifications or for

regeneration . . . . . . . . . . . . . . 37

Chapter 6. Modifying your agent byusing the IBM Tivoli Monitoring AgentEditor . . . . . . . . . . . . . . . 39IBM Tivoli Monitoring Agent Editor . . . . . . 39

Agent Information page . . . . . . . . . 39General agent information . . . . . . . 40Watchdog information . . . . . . . . . 40Default operating systems . . . . . . . 42Environment variables . . . . . . . . . 43

Generate Agent Wizard link . . . . . . . 45Commit Agent Version link . . . . . . . 45

Data Source Definition page . . . . . . . . 45Runtime Configuration Information page . . . 47Agent XML Editor page . . . . . . . . . 48

Saving your edits and changes . . . . . . . . 49Committing a version of the agent. . . . . . . 49

Steps to commit the agent . . . . . . . . 50Changing a subsequent version of your agent . . 50Changing the product code . . . . . . . . 51

Chapter 7. Editing data source andattribute properties . . . . . . . . . 53Creating attributes . . . . . . . . . . . . 54

Fields and options for defining attributes . . . 55Attribute types . . . . . . . . . . . . 57

String attributes . . . . . . . . . . . 57Numeric . . . . . . . . . . . . . 57Time stamp . . . . . . . . . . . . 58

Numeric attribute options . . . . . . . . 58Specifying an enumeration for an attribute . . . 59

Copying attributes . . . . . . . . . . . . 60Creating derived attributes . . . . . . . . . 61Formula operators and functions . . . . . . . 64Editing derived attributes. . . . . . . . . . 68

Changing the component view . . . . . . . 70Component types . . . . . . . . . . . 70

Attribute component . . . . . . . . . 71Literal component . . . . . . . . . . 73Operator component . . . . . . . . . 74Conditional expression component . . . . 75Function component . . . . . . . . . 76

Common options . . . . . . . . . . . 78Insert . . . . . . . . . . . . . . 78Remove . . . . . . . . . . . . . 79Up one Level . . . . . . . . . . . . 80Edit . . . . . . . . . . . . . . . 80

Formula errors . . . . . . . . . . . . 80Editing attributes . . . . . . . . . . . . 82Removing attributes . . . . . . . . . . . 82Specifying operating systems . . . . . . . . 82

Chapter 8. Monitoring a process. . . . 85

Defining connections for process browsing . . . . 90

Chapter 9. Monitoring a Windowsservice. . . . . . . . . . . . . . . 93Defining connections for service browsing . . . . 97

Chapter 10. Monitoring data fromWindows ManagementInstrumentation (WMI) . . . . . . . 101

© Copyright IBM Corp. 2007, 2010 iii


6/553

Chapter 11. Monitoring a WindowsPerformance Monitor (Perfmon) . . . 107

Chapter 12. Monitoring data from aSimple Network Management Protocol(SNMP) . . . . . . . . . . . . . . 113MIB errors . . . . . . . . . . . . . . 117SNMP MIB Parsing options. . . . . . . . . 118

Chapter 13. Monitoring events from aSimple Network Management Protocolevent sender. . . . . . . . . . . . 121Procedure . . . . . . . . . . . . . . 121Configuration . . . . . . . . . . . . . 125

Chapter 14. Monitoring JavaManagement Extensions (JMX)MBeans . . . . . . . . . . . . . . 129

JMX configuration . . . . . . . . . . . . 144

JMX notifications, monitors, and operations . . . 147 JMX notifications . . . . . . . . . . . 147 JMX monitors . . . . . . . . . . . . 148

Take Action commands for monitors . . . 149 JMX Add String Metric Watcher . . . . 149 JMX Add Gauge Metric Watcher . . . . 150 JMX Add Counter Metric Watcher . . . 151 JMX Delete Metric Watcher. . . . . . 152

Starting and stopping monitors . . . . . 152 JMX operations. . . . . . . . . . . . 153

Take Action command syntax . . . . . . 153Example: Invoke an operation to reset acounter . . . . . . . . . . . . . 153Example: Invoke an action with an argument 153

Running the JMX_INVOKE Take Actioncommand . . . . . . . . . . . . 154

Specific fields for Java Management Extensions(JMX) MBeans . . . . . . . . . . . . . 154

Chapter 15. Monitoring data from aCommon Information Model (CIM) . . 159Steps for monitoring data from a CIM . . . . . 159CIM configuration . . . . . . . . . . . . 162

Chapter 16. Monitoring a log file . . . 163

Chapter 17. Monitoring an AIX Binary

Log. . . . . . . . . . . . . . . . 183Procedure . . . . . . . . . . . . . . 183

Chapter 18. Monitoring a WindowsEvent Log . . . . . . . . . . . . . 187Filtering by event type . . . . . . . . . . 192Filtering by event source . . . . . . . . . 192Filtering by event identifier . . . . . . . . . 194

Chapter 19. Monitoring a commandreturn code . . . . . . . . . . . . 197

Editing a command file definition . . . . . . 207

Chapter 20. Monitoring output from ascript . . . . . . . . . . . . . . . 209

Chapter 21. Monitoring data from JavaDatabase Connectivity (JDBC) . . . . 219Procedure . . . . . . . . . . . . . . 219

JDBC configuration . . . . . . . . . . . 231Stored procedures . . . . . . . . . . . . 233

Samples . . . . . . . . . . . . . . 233call sp_helpdb . . . . . . . . . . . 233call:2 sp_helpdb master . . . . . . . . 233

Oracle stored procedures . . . . . . . . 234

Chapter 22. Monitoring systemavailability using Ping . . . . . . . 235Ping configuration files . . . . . . . . . . 235Procedure . . . . . . . . . . . . . . 236Configuration . . . . . . . . . . . . . 238

Chapter 23. Joining attribute groups 239 Joining two attribute groups . . . . . . . . 240Deleting an attribute group. . . . . . . . . 243Deleting an attribute . . . . . . . . . . . 243Adding an attribute . . . . . . . . . . . 243Reordering attributes . . . . . . . . . . . 243Removing availability filters . . . . . . . . 244

Joined attributes . . . . . . . . . . . . 244

Chapter 24. Creating a navigatorgroup . . . . . . . . . . . . . . . 247

Chapter 25. Creating subnodes. . . . 251Monitoring the same data from different sources 251Monitoring multiple types of information . . . . 252Data Providers in subnodes . . . . . . . . 253Status of subnodes . . . . . . . . . . . 253Creating subnodes when creating an agent . . . 255

Creating a subnode as the first component of anagent from a Data Source Location page in theNew Agent Wizard . . . . . . . . . . 255Creating a subnode from the Data Sources treein the New Agent Wizard . . . . . . . . 259Creating a subnode in the Agent Editor . . . 263Subnode configuration . . . . . . . . . 264

Configuring a subnode . . . . . . . . 265

Overriding custom configuration . . . . . 266Selecting subnode configuration properties 267Advanced subnode configuration. . . . . 267Configuring a subnode from the commandline . . . . . . . . . . . . . . . 270Windows data sources . . . . . . . . 276Script data sources . . . . . . . . . 277

Chapter 26. Configuring an agent. . . 279Customizing configuration . . . . . . . . . 279

iv IBM Tivoli Monitoring Agent Builder: User’s Guide


7/553

Changing configuration properties using the AgentEditor . . . . . . . . . . . . . . . . 287Configuring a Windows remote connection . . . 290Configuring a Secure Shell (SSH) remoteconnection . . . . . . . . . . . . . . 291

Chapter 27. Testing and debugging

your agent . . . . . . . . . . . . 293Testing an agent . . . . . . . . . . . . 293Installing the agent locally . . . . . . . . 293Creating the package to use on systems that arenot local . . . . . . . . . . . . . . 295Installing the package . . . . . . . . . 296

After you install the agent . . . . . . . . . 297Configuring and starting the agent . . . . . . 297Results after generating and installing the agentwith the Agent Builder . . . . . . . . . . 297

New files on your system . . . . . . . . 297Changes in the Manage IBM Tivoli MonitoringServices window . . . . . . . . . . . 300Changes in the Tivoli Enterprise Portal . . . . 301

Uninstalling an agent. . . . . . . . . . . 304Removing an agent using the Tivoli EnterprisePortal . . . . . . . . . . . . . . . 304Removing an agent without using TivoliEnterprise Portal . . . . . . . . . . . 304

Windows systems . . . . . . . . . . 304Command . . . . . . . . . . . 304Uninstallation script . . . . . . . . 304

UNIX systems . . . . . . . . . . . 304Clearing the agent from the Tivoli Enterprise Portalafter removing the agent . . . . . . . . . 304

Chapter 28. Creating workspaces,Take Action commands, andsituations . . . . . . . . . . . . . 307Creating situations, Take Action commands, andqueries . . . . . . . . . . . . . . . 307Creating workspaces . . . . . . . . . . . 307

Chapter 29. Importing applicationsupport files . . . . . . . . . . . . 313Exporting and importing server definitions . . . 313

Chapter 30. Packaging your agent . . 319Generating the Installer Project . . . . . . . 319

Chapter 31. Creating the SolutionInstaller image . . . . . . . . . . . 323Creating a CD from which the agent can beinstalled . . . . . . . . . . . . . . . 324

Installing the agent . . . . . . . . . . 324

Chapter 32. Event filtering andsummarization . . . . . . . . . . . 333Controlling duplicate events . . . . . . . . 334Viewing event filtering and summarization in theTivoli Enterprise Portal . . . . . . . . . . 335

Chapter 33. Troubleshooting . . . . . 341Gathering product information for IBM SoftwareSupport . . . . . . . . . . . . . . . 341Agent Builder trace logging . . . . . . . . 341

Agent Builder trace logging overview . . . . 342Trace log location . . . . . . . . . . . 342Trace log format . . . . . . . . . . . 342

Trace log example . . . . . . . . . . . 343Logging configuration . . . . . . . . . 344Configuration options . . . . . . . . 344

IBM Java Logging Toolkit . . . . . . 344Output window . . . . . . . . . 345

Environment variables . . . . . . . . . . 346Understanding informational, warning, and errormessages . . . . . . . . . . . . . . . 352

Product messages . . . . . . . . . . . 352Agent Builder messages . . . . . . . . . 353

Agent trace logging . . . . . . . . . . . 384Overview of log file management . . . . . 385Examples of trace logging . . . . . . . . 385Principal trace log files . . . . . . . . . 386

Example for using trace logs . . . . . . . 387Setting RAS trace parameters . . . . . . . 389Objective . . . . . . . . . . . . . 389Background Information . . . . . . . . 389Before you begin . . . . . . . . . . 389After you finish . . . . . . . . . . 389Procedure . . . . . . . . . . . . 390

Problem classification. . . . . . . . . . . 391Troubleshooting: Agent Builder . . . . . . 391Troubleshooting: agents . . . . . . . . . 401Troubleshooting: Solution Installer . . . . . 419

Support information . . . . . . . . . . . 420

Appendix A. Sharing project files . . . 423

Appendix B. Command-line options 427List of commands . . . . . . . . . . . . 427generatelocal . . . . . . . . . . . . . 429generatemappingfile . . . . . . . . . . . 430generateSIPackage . . . . . . . . . . . . 431generatezip . . . . . . . . . . . . . . 432

Appendix C. Preparing to createworkspaces and situations for TivoliUniversal Agent applications. . . . . 433Setting the Application Tag. . . . . . . . . 433

Appendix D. Attributes reference . . . 435Availability node . . . . . . . . . . . . 435Performance Object Status node . . . . . . . 440Thread Pool Status attribute group . . . . . . 446Event log attribute node . . . . . . . . . . 449Log File Summary. . . . . . . . . . . . 451AIX Binary Log attribute group . . . . . . . 453Monitor and Notification attribute groups . . . . 457Counter Notifications. . . . . . . . . . . 457Gauge Notifications . . . . . . . . . . . 460Registered Monitors . . . . . . . . . . . 462

Contents v


8/553

String Notifications . . . . . . . . . . . 463SNMP Event attribute groups . . . . . . . . 466

JMX Event attribute groups. . . . . . . . . 467Ping attribute group . . . . . . . . . . . 469Discovery attribute groups . . . . . . . . . 471Take Action Status attribute group . . . . . . 473

Appendix E. Packaging a TivoliUniversal Agent Application Solutionwith the Agent Builder . . . . . . . 477Packaging the Tivoli Universal Agent applicationsupport files. . . . . . . . . . . . . . 477Packaging a Tivoli Universal Agent application . . 477Installing the Tivoli Universal Agent applicationand support files . . . . . . . . . . . . 478Remote Deployment of a Tivoli Universal AgentApplication . . . . . . . . . . . . . . 479

Appendix F. Creating value-addsolutions for existing agents. . . . . 483

Creating a new Solution Installer project . . . . 483Adding your value-add solution to a SolutionInstaller project . . . . . . . . . . . . . 486

Appendix G. Upgrading custom IBMTivoli Monitoring v5.x resourcemodels to IBM Tivoli Monitoring v6.2agents . . . . . . . . . . . . . . 495

Appendix H. ICU regular expressions 497Replacement text . . . . . . . . . . . . 500Flag options . . . . . . . . . . . . . . 501

Appendix I. Non-agent bundles . . . . 503Creating a file bundle . . . . . . . . . . 503

Remote Deploy Bundle Editor. . . . . . . 505Adding commands to the bundle. . . . . . . 507Adding prerequisites to the bundle . . . . . . 508Adding files to the bundle . . . . . . . . . 509Generating the bundle . . . . . . . . . . 510

Creating deployable bundles for TivoliNetcool/OMNIbus probes . . . . . . . . . 511

Appendix J. Dynamic file namesupport . . . . . . . . . . . . . . 513Dynamic file name syntax . . . . . . . . . 513Regular expression file-name patterns . . . . . 515

Appendix K. SNMP trap configuration 517SNMP trap configuration file, trapcnfg . . . . . 517

Using the HP OpenView trapd.conf file . . . 517Types of records . . . . . . . . . . . 517

Defaults for the trapcnfg file . . . . . . . . 518Supported categories . . . . . . . . . . 518Supported statuses . . . . . . . . . . 519Supported source IDs . . . . . . . . . 519

Appendix L. Take Action commandsreference . . . . . . . . . . . . . 521About Take Action commands. . . . . . . . 521

More information about Take Action commands 521Special Take Action commands . . . . . . . 521SSHEXEC action . . . . . . . . . . . 522

Appendix M. Documentation library 523IBM Tivoli Monitoring library . . . . . . . . 523

Documentation for the base agents . . . . . 524Related publications . . . . . . . . . . . 525Other sources of documentation . . . . . . . 525

Appendix N. Accessibility . . . . . . 527Using assistive technologies . . . . . . . . 527Magnifying what is displayed on the screen . . . 527Documentation in accessible formats . . . . . 527

Using alternative text . . . . . . . . . . . 527

Appendix O. Notices . . . . . . . . 529Trademarks . . . . . . . . . . . . . . 531

Index . . . . . . . . . . . . . . . 533

vi IBM Tivoli Monitoring Agent Builder: User’s Guide


9/553

Figures

1. InstallAnywhere window . . . . . . . . 62. Agent Builder language selection window 7

3. Install: Introduction page . . . . . . . . 84. Install: Software License Agreement page 85. Install: Choose Install Folder page . . . . . 96. Install: Pre-installation Summary page . . . 107. Install: Installing IBM Tivoli Monitoring Agent

Builder page . . . . . . . . . . . . 108. Install: Install Complete page . . . . . . 119. Create New Agent icon . . . . . . . . 18

10. Starting the wizard with the File > New >IBM Tivoli Monitoring Agent option . . . . 19

11. Starting the wizard with the File > New >Other option . . . . . . . . . . . . 20

12. Select a wizard page . . . . . . . . . 2113. Selecting the agent icon . . . . . . . . 22

14. Welcome window . . . . . . . . . . 2315. Project page . . . . . . . . . . . . 2416. G eneral Information page . . . . . . . . 2517. Agent Information page . . . . . . . . 2618. Agent Initial Data Source page . . . . . . 2819. Select key attributes page . . . . . . . . 3020. Data Source Definition page: defining

additional monitors . . . . . . . . . . 3121. D ata Source Location page . . . . . . . 3222. Subnodes in the Navigator tree . . . . . . 3523. Move existing data sources . . . . . . . 3624. Currently Defined Data Sources page . . . . 3725. Agent Information page . . . . . . . . 4026. Agent Information page: Watchdog

Information . . . . . . . . . . . . 4127. Agent Information page: Default Operating

Systems . . . . . . . . . . . . . . 4328. Agent Information page: Environment

Variables section . . . . . . . . . . . 4429. Environment Variable Information window 4430. Data Source Definition page . . . . . . . 4731. Runtime Configuration Information page 4832. Agent XML Editor page . . . . . . . . 4933. Updating the agent version after commit 5134. Agent Product Code change . . . . . . . 5135. Agent support files invalidated . . . . . . 5236. Attribute Information page . . . . . . . 5537. String attribute type. . . . . . . . . . 57

38. Numeric attribute type . . . . . . . . . 5839. Defining enumeration for an attribute. . . . 6040. Copy Attribute window . . . . . . . . 6041. Adding an attribute . . . . . . . . . . 6142. Attribute Information page . . . . . . . 6243. Attribute Information page with Derived

Attribute Details tab open . . . . . . . . 6344. Derived Formula Editor window (default) 6945. Derived Formula Editor view with formula

hierarchy tree view . . . . . . . . . . 7046. Edit the Selected Attribute page. . . . . . 7147. Edit the Selected Attribute page with error 72

48. Edit the Selected Function page with warning 7349. Edit the Selected Literal page . . . . . . 74

50. Edit the Selected Operator page. . . . . . 7551. Edit the Selected Operator page (for aconditional operator) . . . . . . . . . 76

52. Edit the Selected Function page . . . . . . 7753. Insert window example . . . . . . . . 7854. Insert window example for getenv function 7955. Remove function and its Arguments page 7956. Empty formula example . . . . . . . . 8057. Parsing error example . . . . . . . . . 8158. Insert window for fixing a formula manually 8259. Operating systems where the agent is to run 8360. A dding a server process . . . . . . . . 8561. Process Monitor page . . . . . . . . . 8662. Browse the list of currently running processes 87

63. Search for a process . . . . . . . . . . 8864. Process Monitor page example . . . . . . 8965. Select a connection type or connection

template for process browsing . . . . . . 9066. Edit connection properties for Tivoli Enterprise

Portal Server Managed System . . . . . . 9167. Adding a Windows service monitor . . . . 9368. Service Monitor page . . . . . . . . . 9469. Browse the list of all services defined in the

system . . . . . . . . . . . . . . 9570. Search for a service . . . . . . . . . . 9671. Service information . . . . . . . . . . 9772. Select a connection type or connection

template for service browsing . . . . . . 98

73. Edit connection properties for Tivoli EnterprisePortal Server Managed System . . . . . . 99

74. Adding WMI data . . . . . . . . . . 10175. WMI Information page . . . . . . . . 10276. List of classes with their associated attributes 10377. Optionally specifying WMI search options 10378. WMI Information page completed . . . . 10479. WMI shown on Data Source Definition page

in the Agent Editor . . . . . . . . . 10580. Global Windows Data Source Options

window . . . . . . . . . . . . . 10681. Adding Perfmon data . . . . . . . . . 10782. Perfmon Information page . . . . . . . 10883. Browsing for Performance Monitor objects 109

84. Performance Monitor Search window 10985. Perfmon Information page with Object Name 11086. Global Windows Data Source Options

window . . . . . . . . . . . . . 11087. Perfmon Data Source Definition . . . . . 11288. Adding SNMP data . . . . . . . . . 11389. Simple Network Management Protocol

Information page . . . . . . . . . . 11490. List of objects . . . . . . . . . . . 11591. Selecting an object . . . . . . . . . . 11692. SNMP Data Source Definition . . . . . . 11793. MIB Parsing window . . . . . . . . . 118

© Copyright IBM Corp. 2007, 2010 vii


10/553

94. Adding SNMP events . . . . . . . . . 12195. Simple Network Management Protocol Event

Information window . . . . . . . . . 12296. SNMP MIB Browser window . . . . . . 12497. S elect key attributes page . . . . . . . 12598. Runtime Configuration page . . . . . . 12699. Adding JMX data . . . . . . . . . . 130

100. JMX Information page . . . . . . . . 131101. JMX Agent-Wide options window. . . . . 132102. JMX Browser with no connection selected 133103. JMX Connection Selection page . . . . . 134104. JMX connection templates . . . . . . . 135105. JMX connection properties . . . . . . . 136106. Java Management Extensions (JMX) Browser

window . . . . . . . . . . . . . 138107. JMX Information page . . . . . . . . 140108. JMX Agent-Wide Options window . . . . 141109. New attribute group in Agent Editor 142110. JMX Agent-Wide Options window . . . . 143111. Runtime Configuration tab of the Agent

Editor . . . . . . . . . . . . . . 144112. JMX Agent-Wide Options page . . . . . 148113. Attribute Information page . . . . . . . 154114. Adding CIM data . . . . . . . . . . 159115. Common Information Model (CIM)

Information page . . . . . . . . . . 160116. Common Information Model (CIM) Class

Browser window . . . . . . . . . . 161117. Adding a log file . . . . . . . . . . 163118. Log File Information page . . . . . . . 164119. X ML Browser window . . . . . . . . 165120. Advanced Data Source Properties page, File

Information tab . . . . . . . . . . . 166121. Advanced Data Source Properties page,

Record Identification tab . . . . . . . . 169

122. Advanced Data Source Properties page, EventInformation tab . . . . . . . . . . . 170123. Parse Log window . . . . . . . . . . 172124. Attribute Information page . . . . . . . 174125. Advanced Log File Attribute Information

page . . . . . . . . . . . . . . 176126. Add Filter window . . . . . . . . . 177127. A dd Filter example 1 . . . . . . . . . 179128. A dd Filter example 2 . . . . . . . . . 180129. Adding data from a command . . . . . . 184130. Binary Log Information page . . . . . . 185131. Adding a Windows Event log . . . . . . 188132. Windows Event Log page . . . . . . . 189133. Windows Event Log Bookmark Settings

window . . . . . . . . . . . . . 190134. Global Windows Data Source Optionswindow . . . . . . . . . . . . . 191

135. Windows Event Log page . . . . . . . 192136. Event Source window . . . . . . . . . 193137. Event Log Source Browser window . . . . 193138. Windows Event Log window . . . . . . 194139. Event Identifier window . . . . . . . . 195140. Windows Event Log window . . . . . . 196141. Adding data from a command . . . . . . 197142. Command Return Code page . . . . . . 198143. Command Information window . . . . . 199

144. Return Code Definition window: Return codetype. . . . . . . . . . . . . . . 200

145. Return Code Definition window: Return codevalue . . . . . . . . . . . . . . 200

146. Messages window . . . . . . . . . . 201147. Message Definition window . . . . . . 202148. Return Code Definition window completed 202149. Command Information window completed 203150. Return Code Definition window: Message

text . . . . . . . . . . . . . . . 205151. Messages window . . . . . . . . . . 205152. Return Code Definition window . . . . . 206153. Command Return Code page completed 207154. Import Command File window . . . . . 208155. Adding data from a script . . . . . . . 210156. Command List page . . . . . . . . . 211157. Command Information window for a script 212158. Test Command window . . . . . . . . 213159. Environment Variables window . . . . . 214160. Environment Variable window. . . . . . 215161. Attribute Information page . . . . . . . 216162. Agent Editor Data Source Definition page 217163. Adding JDBC data . . . . . . . . . . 220164. J DBC Information page . . . . . . . . 221165. JDBC Browser window . . . . . . . . 222166. Database Connection Wizard: JDBC

Connections page . . . . . . . . . . 223167. Database Connections Wizard: Connection

Properties page . . . . . . . . . . . 224168. Java Database Connectivity (JDBC) Browser

window . . . . . . . . . . . . . 226169. Test Command window . . . . . . . . 227170. J DBC Information page . . . . . . . . 228171. Data Source Definition page Attribute Group

Information . . . . . . . . . . . . 229

172. Runtime Configuration Information page,Configuration for Java Virtual Machine (JVM) 229173. Attribute Information page . . . . . . . 230174. Adding Ping data . . . . . . . . . . 236175. Ping Information window . . . . . . . 237176. Adding existing data sources . . . . . . 239177. Attribute Group Information window 243178. Locating source attribute information 244179. Selecting the initial source of monitoring data

for a new agent . . . . . . . . . . . 247180. Providing the navigator group name and help

text . . . . . . . . . . . . . . . 248181. Selecting the first source of monitoring data 249182. Subnodes monitoring different systems 251

183. Subnode types in Navigator tree . . . . . 252184. Monitoring multiple subnode instances of thesame subnode type . . . . . . . . . 254

185. Example: data collection in a subnode 255186. Data Source Location page - Creating a

subnode . . . . . . . . . . . . . 256187. Subnode Information page . . . . . . . 257188. Initial Subnode Data Source page . . . . . 258189. Subnode Configuration Overrides page 259190. Data Source Definition page . . . . . . 260191. Defining a new subnode . . . . . . . . 261192. Initial Subnode Data Source page . . . . . 262

viii IBM Tivoli Monitoring Agent Builder: User’s Guide


11/553

193. Subnode Configuration Overrides page 263194. Agent Editor Data Source Definition page 264195. Subnode Configuration Overrides window 265196. Overriding custom configuration . . . . . 266197. Select Configuration Section window 267198. Override configuration drop-down lists 268199. Sections to override . . . . . . . . . 269200. SNMP Version 1 Properties expanded 270201. Configuration property definitions in the

Agent Builder . . . . . . . . . . . 271202. Top section with agent-level configuration for

the Agent Cfg property . . . . . . . . 272203. Main section with the agent-wide default

value for the Overridable Cfg property. . . 273204. Example Subnode section page with no

subnode . . . . . . . . . . . . . 274205. Example Subnode section page with two

subnode instances defined . . . . . . . 275206. Windows Management Instrumentation

(WMI) Information page . . . . . . . . 276207. Global Windows Data Source Options 277208. Insert Configuration Property button on the

Log File Information page . . . . . . . 280209. Initial Configuration Properties window 281210. Runtime Configuration Property window 282211. Configuration Property Default Values

window . . . . . . . . . . . . . 284212. Adding a configuration property choice 284213. New configuration property displayed 285214. Adding a second property to an existing

section . . . . . . . . . . . . . . 286215. Property inserted into the log file name 287216. Runtime Configuration tab in the Agent

Editor . . . . . . . . . . . . . . 288217. Editing a configuration section in the Agent

Editor . . . . . . . . . . . . . . 289218. Editing a configuration property in the AgentEditor . . . . . . . . . . . . . . 290

219. Generate agent icon . . . . . . . . . 293220. Generate agent menu option . . . . . . 294221. Create a compressed file to install on another

system . . . . . . . . . . . . . . 295222. Manage IBM Tivoli Monitoring Services

window . . . . . . . . . . . . . 300223. Nodes for attribute groups you defined 301224. Availability node . . . . . . . . . . 302225. Performance Object Status node . . . . . 303226. Event log node . . . . . . . . . . . 303227. Setting the sysadmin user ID . . . . . . 309

228. Setting the sysadmin user ID (continued) 309229. Setting the sysadmin user ID (continued) 310230. Setting workspace properties . . . . . . 311231. Setting workspace properties (continued) 311232. Importing application support files . . . . 314233. Importing situations . . . . . . . . . 315234. Selecting situations. . . . . . . . . . 316235. Select Take Action commands . . . . . . 317236. Importing queries . . . . . . . . . . 317

237. G enerate Agent Wizard . . . . . . . . 320238. Solution Installer Project Information 321239. Component Information . . . . . . . . 322240. Solution Installer Image Information . . . . 323241. Welcome screen . . . . . . . . . . . 327242. Enter directory . . . . . . . . . . . 327243. Select components . . . . . . . . . . 328244. Tivoli Enterprise Monitoring Server

verification . . . . . . . . . . . . 329245. Select applications . . . . . . . . . . 329246. Verification for versions of IBM Tivoli

Monitoring prior to Fix Pack 1 . . . . . . 330247. Verification for IBM Tivoli Monitoring v6.2

Fix Pack 1 and higher . . . . . . . . . 331248. Advanced Log File Attribute Group

Information page, Event Information tab . . 335249. Historical view and cache view when event

filtering or summarization is not enabled . . 336250. Historical view and cache view when Only

send summary events is selected . . . . . 337251. Historical view and cache view when Send

all events is selected . . . . . . . . . 338252. Historical view and cache view when Send

first event is selected . . . . . . . . . 339253. Historical view and cache view when Event

threshold is selected . . . . . . . . . 340254. IBM Java Logging Toolkit . . . . . . . 345255. Importing files . . . . . . . . . . . 423256. Importing files (continued) . . . . . . . 424257. Importing files (continued) . . . . . . . 425258. I nstaller flow exception . . . . . . . . 479259. Configuring the Tivoli Universal Agent 480260. MDL file name . . . . . . . . . . . 481261. C reating new project . . . . . . . . . 484262. IBM Tivoli Monitoring Add-On . . . . . 485

263. Naming the project . . . . . . . . . 486264. I mporting support files . . . . . . . . 487265. Import add-on files . . . . . . . . . 488266. Affinities list . . . . . . . . . . . . 489267. I mporting support files . . . . . . . . 490268. Importing situations . . . . . . . . . 491269. Importing situations (continued) . . . . . 492270. Importing queries . . . . . . . . . . 493271. Import Take Action commands. . . . . . 493272. Select a wizard window . . . . . . . . 503273. New Remote Deploy Project window 504274. Remote Deploy Bundle Information window 505275. Remote Deploy Bundle Editor . . . . . . 506276. Command window . . . . . . . . . 507

277. New Prerequisite window . . . . . . . 508278. Adding files to the bundle or generating a bundle from the Navigator tree . . . . . 509

279. Import Bundle Files window . . . . . . 510280. Generate Final Remote Deploy Bundle

window . . . . . . . . . . . . . 511281. Examples of configuration record types 2 and

3 . . . . . . . . . . . . . . . . 518

Figures ix


12/553

x IBM Tivoli Monitoring Agent Builder: User’s Guide


13/553


14/553

xii IBM Tivoli Monitoring Agent Builder: User’s Guide


15/553

Chapter 1. Introduction

This chapter provides an overview of the IBM® Tivoli® Monitoring Agent Builder.

About IBM Tivoli Monitoring Agent Builder

IBM Tivoli Monitoring Agent Builder is a set of tools used for creating agents,installation packages for the created agents, and value-add solutions for existingagents.

Creating agents

Using the IBM Tivoli Monitoring Agent Builder, you can quickly create, modify,and test an agent. Agents collect and analyze data about the state and performanceof different resources, such as disks, memory, CPU, or applications. The Buildercreates a data provider that you can use to monitor three types of data:

AvailabilityProcess and service availability and command return codes

Windows Event LogSpecific information from the Windows Event Log

External Data SourcesData from external sources such as Windows Management Instrumentation(WMI), Performance Monitor (Perfmon), Simple Network ManagementProtocol (SNMP), SNMP Events, Secure Shell (SSH), Internet ControlMessage Protocol (ICMP) ping, Java Management Extensions (JMX),Common Information Model (CIM), external scripts, log files, and JavaDatabase Connectivity (JDBC).

Creating installation packages for agents

You can package agents for easy distribution by using the Solution Installer orcompressed image.

Creating value-add solutions for existing agents

Another feature of the installer is the ability to package and distribute value-addextensions for existing agents. This provides the ability to develop new situations,queries, and workspaces for an existing IBM Tivoli Monitoring V6.x agent. Forexample, if you have insight into how the retail industry uses IBM DB2® for anin-store database, you can create customized workspaces and situations that canthen be given or sold to companies in this industry.

About Eclipse

The IBM Tivoli Monitoring Agent Builder is an Eclipse application for the Eclipse3.4.1 platform, an open source framework for the construction of powerfulsoftware development tools and rich desktop applications. Leveraging the Eclipseplug-in framework to integrate technology on the desktop can save technologyproviders time and money for focusing effort on delivering differentiation andvalue for their offerings. Eclipse is a multi-language, multi-platform, multi-vendorsupported environment that an open source community of developers built and

© Copyright IBM Corp. 2007, 2010 1


16/553

provided royalty-free by the Eclipse Foundation. Written in the Java language,Eclipse includes extensive plug-in construction toolkits and examples, and can beextended and run on a range of desktop operating systems including Windows,Linux, QNX, and Macintosh OS X. To see full details about Eclipse and the EclipseFoundation, go to http://www.eclipse.org.

New in this releaseFor version 6.2.2.5 of the IBM Tivoli Monitoring Agent Builder, the followingenhancements have been made since version 6.2.2.4:

v Log Monitoring now supports monitoring of AIX® binary error logs through theerrpt command.

v On restarting, agents can now process Windows Event Log events that weregenerated while the agent was shut down.

About this guide

This guide describes how to use the IBM Tivoli Monitoring Agent Builder softwareto create, modify, debug, and package agents for use with IBM Tivoli Monitoring

products. This book explains concepts that agent developers, systemadministrators, and application administrators must know to use the IBM TivoliMonitoring Agent Builder product and its integration into the Tivoli environment.

2 IBM Tivoli Monitoring Agent Builder: User’s Guide

http://www.eclipse.org/http://www.eclipse.org/


17/553

Chapter 2. Getting started quick-reference guide

This chapter provides quick-reference tables of the procedures you can performwith IBM Tivoli Monitoring Agent Builder. The two main objectives for using the

Agent Builder (creating agents and creating value-add solutions by creatingadditional workspaces and situations to enhance one or more existing agents) arelisted in the information later in this section. The following tables also includecross-references to the locations of additional information about the procedures.The procedures are listed in a suggested order, but do not have to be followed inthis order.

The following table contains the procedures for creating agents:

Table 1. Quick-reference information for creating agents

Goal Refer to

1. Learn the preparation steps for creating an agent:

v Review basic concepts about the Agent Builderand Eclipse.

v Ensure that your environment meets requirementsfor software and authorization.

v Install the Agent Builder.

v Obtain a basic understanding of the types of datathat the agent can monitor.

v Organize data within the agent.

v Chapter 1, “Introduction,” on page 1

v “Software requirements” on page 5v “Authorization” on page 6

v “Builder installation procedure” on page 6

v “Planning and overview” on page 15

v “Defining initial data source” on page 28

v Chapter 24, “Creating a navigator group,” on page 247

v Chapter 25, “Creating subnodes,” on page 251

2. Learn how to create an agent using the AgentBuilder wizard.

v Chapter 4, “Starting the Agent Builder,” on page 15

v Chapter 5, “Creating a basic agent,” on page 17

3. Learn how to test and debug your created agent and

the availability of your monitors.

v Chapter 27, “Testing and debugging your agent,” on

page 293v Appendix B, “Command-line options,” on page 427

v Chapter 33, “Troubleshooting,” on page 341

v “Preparing your agent for modifications or forregeneration” on page 37

v Chapter 6, “Modifying your agent by using the IBMTivoli Monitoring Agent Editor,” on page 39

4. Learn how to remove an agent that you created withthe Agent Builder.

v “Uninstalling an agent” on page 304

5. Learn how to create workspaces and situations foryour agent.

v Chapter 29, “Importing application support files,” onpage 313

v Chapter 28, “Creating workspaces, Take Action

commands, and situations,” on page 307

6. Learn how to package your agent. v Chapter 30, “Packaging your agent,” on page 319

v Chapter 31, “Creating the Solution Installer image,” onpage 323

The following table contains the procedures for creating other functions:



18/553

Table 2. Quick-reference information for other functions

Goal Refer to

1. Learn how to create custom workspaces, situations,and queries.

v Chapter 28, “Creating workspaces, Take Actioncommands, and situations,” on page 307

2. Learn how to package your value-add solution. v Appendix F, “Creating value-add solutions for existingagents,” on page 483

3. Learn how to build custom bundles. v Appendix I, “Non-agent bundles,” on page 503



19/553

Chapter 3. Installing the IBM Tivoli Monitoring Agent Builder

Table 3 shows some guidelines for installation and running the IBM TivoliMonitoring Agent Builder.

Note: For information about installing or modifying an agent, see “Testing anagent” on page 293.

Table 3. Guidelines for installation and configuration

Goal Refer to

Verify that your environment meets thesoftware requirements.

“Software requirements” on page 5

Ensure that you have appropriateauthorization.

“Authorization” on page 6

Software requirementsTo install the Agent Builder, you must first install and have running one of thefollowing operating systems:

v AIX 5.2 ML10 x86 (32-bit) or later

v AIX 5.3 ML5 x86 (32-bit) or later

v AIX 6.1

v AIX 7.1

v Red Hat Enterprise Linux 4.0 + U2 x86 (32-bit) or later

v Red Hat Desktop Linux 4.0 + U2 x86 (32-bit) or later

v Red Hat Enterprise Linux 5.0 x86 (32-bit)

v Red Hat Enterprise Linux 5.0 x86-64 (64-bit)v Red Hat Enterprise Linux 6.0 x86 (32-bit)

v SUSE Linux Enterprise Server 9 Sp1 x86 (32-bit) or later

v SUSE Linux Enterprise Server 10 x86 (32-bit)

v SUSE Linux Enterprise Server 10 x86-64 (64-bit)

v SUSE Linux Enterprise Server 11 x86 (32-bit)

v SUSE Linux Enterprise Server 11 x86-64 (64-bit)

v Windows Server 2000

v Windows 2000 Advanced Server

v Windows Server 2003 EE x86 (32-bit)

v

Windows Server 2003 SE x86 (32-bit)v Windows Server 2003 Data Center x86 (32-bit)

v Windows Server 2003 EE x86-64 (64-bit)

v Windows Server 2003 SE x86-64 (64-bit)

v Windows Server 2003 Data Center x86-64 (64-bit)

v Windows XP Professional

v Windows Server 2008 Data Center x86 (32-bit)

v Windows Server 2008 EE x86 (32-bit)

v Windows Server 2008 SE x86 (32-bit)



20/553

v Windows Server 2008 Data Center x86-64 (64-bit)

v Windows Server 2008 EE x86-64 (64-bit)

v Windows Server 2008 SE x86-64 (64-bit)

v Windows Server 2008 R2 Data Center x86-64 (64-bit)

v Windows Server 2008 R2 EE x86-64 (64-bit)

v Windows Server 2008 R2 SE x86-64 (64-bit)

v Windows 7 x86 (32-bit)

v Windows 7 x86-64 (64-bit)

See “Operating system requirements” on page 17 for information about theoperating systems supported by the agents created by the Agent Builder.

Authorization

Before you can run IBM Tivoli Monitoring Agent Builder, you must haveAdministrator authorization for the following reasons:

v Ability to ensure a consistent running environment for the Agent Builder andthe agents designed with it.

v Ability to access parts of the operating system, which requires Administratorauthorization. The Agent Builder is installed on a development system and isdesigned for developers who require this type of access.

Builder installation procedure

Before installing the IBM Tivoli Monitoring Agent Builder, uninstall any previousversions. No data is lost when you uninstall.

To install the IBM Tivoli Monitoring Agent Builder:

1. Insert the IBM Tivoli Monitoring Agent Builder V6.2.2.5 DVD.

2. Run the executable for your operating system to start the installation:

v setup.bat

v setup.sh

Note: Run the installation program from the same user ID from which youintend to run the Agent Builder.

The following windows are displayed:

Figure 1. InstallAnywhere window



21/553

In the Tivoli Monitoring Agent Builder window select your language, and clickOK.

On the Introduction page (Figure 3 on page 8), click Next.

Figure 2. Agent Builder language selection window

Chapter 3. Installing the IBM Tivoli Monitoring Agent Builder 7


22/553

3. On the Software License Agreement page (Figure 4), click I accept the terms inthe license agreement, and click Next.

4. On the Choose Install Folder page (Figure 5 on page 9), click one of thefollowing options:

Figure 3. Install: Introduction page

Figure 4. Install: Software License Agreement page



23/553

v Next to install the Agent Builder to the directory specified in the WhereWould You Like to Install? field

v Restore Default Folder to install the Agent Builder in a default directory

v Choose to select a different directory

Note: The directory name you choose for the Agent Builder should not contain

the following characters, because having these characters in the directorypath prevents the agent builder from launching:!#%;

5. On the Pre-Installation Summary page (Figure 6 on page 10), click Install.

Figure 5. Install: Choose Install Folder page



24/553

6. On the Installing IBM Tivoli Monitoring Agent Builder page (Figure 7), you canclick Cancel if you want to cancel the installation. If you want to continueinstalling, wait for the Install Complete page (Figure 8 on page 11) to bedisplayed. And then, click Done.

Figure 6. Install: Pre-installation Summary page

Figure 7. Install: Installing IBM Tivoli Monitoring Agent Builder page



25/553

After installing

On Windows systems, after the Agent Builder is installed, there is an option addedto the Start menu and an Agent Builder icon is added to your desktop.

On UNIX systems, after the Agent Builder is installed, the Agent Builderexecutable is named Install_Location/agentbuilder.

The log files for the Agent Builder installation are in the following locations:install_dir/IBM_Tivoli_Monitoring_Agent_Builder_InstallLog.xml (Windows)install_dir/IBM_Tivoli_Monitoring_Agent_Builder_InstallLog.xml (Linux,AIX)

The log is not written until you click Done, because the log file traces actualinstallation.

Silent installation

You can also install the product by using a silent installation method. The silentinstallation options file, installer.properties, is included on the installationmedia at the root of the installation directory. You must modify this file to meetyour needs.

Start the silent installation by running the following command:

setup.[bat | sh] -i silent -f path/installer.properties

Where path is a fully qualified path to the installer.properties file (including thedrive letter or UNC path name on Windows). The value you choose for pathcannot contain spaces.

Figure 8. Install: Install Complete page



26/553


27/553

Silent uninstallation

You can also use the silent uninstallation method. Start the silent uninstallation byrunning the following command:

INSTALL_DIR/uninstall/uninstaller[.exe] -i silent



28/553



29/553

Chapter 4. Starting the Agent Builder

This chapter helps you use the Agent Builder to start the wizards.

Planning and overview

The IBM Tivoli Monitoring Agent Builder provides a wizard that can help youcreate an agent. Before you run the wizard, ensure that you make the followingplanning decisions:

v The project name (see “Naming your agent” on page 23)

v The types of monitoring data that you want your agent to collect (see “Defininginitial data source” on page 28)

Creating your agent involves several steps:

1. Starting (launching) the Agent Builder

2. Creating an agent

3. Defining one or more types of data for your agent to monitor. When youindicate the types of data (availability, log events, or external data sources) thatyou want the agent to collect, the wizard guides you through the process of configuring each of the data collection methods.

4. Testing your agent (see Chapter 27, “Testing and debugging your agent,” onpage 293)

5. Optionally add workspaces, situations and queries (see Chapter 29, “Importingapplication support files,” on page 313)

6. Packaging your agent (see Chapter 30, “Packaging your agent,” on page 319and Chapter 31, “Creating the Solution Installer image,” on page 323)

Note: The Agent Builder does not build language packs, so the text that isdisplayed in the Tivoli Enterprise Portal is in the language you use when building the agent.

Starting the Agent Builder

Start (launch) the Agent Builder by typing the following information on thecommand line:

Windows: Install_Location\agentbuilder.exe. Or, go to either Start > AllPrograms > IBM Tivoli Monitoring > Agent Builder or click the Agent Builderdesktop icon.

All other supported operating systems: Install_Location/agentbuilder

Note: When you initially run the Agent Builder, you are prompted for the locationof your Workspace directory. The files that create your agents are saved inthat directory. You can designate any directory as your workspace.



30/553



31/553

Chapter 5. Creating a basic agent

This chapter helps you use the Agent Builder to create a basic agent. The followingtopics are covered:

v “Operating system requirements”

v “Starting the new agent wizard” on page 18

v “Creating and defining the agent” on page 23

– “Naming your agent” on page 23

– “Defining initial data source” on page 28

– “Organizing the agent” on page 33

v “Preparing your agent for modifications or for regeneration” on page 37

Operating system requirements

The agents created by the Agent Builder are supported on all of the operating

systems supported by the OS monitoring agents, except z/OS® and i5/OS®, asfollows:

v AIX

v HP-UX

v Linux

v Linux on System z®

v Solaris

v Windows

For a more detailed list that includes version numbers, refer to the User's Guidesfor the IBM Tivoli Monitoring Operating System agents (OS agents).

To run your monitoring agent, install the appropriate OS agent on the samecomputer where your monitoring agent will run. Install IBM Tivoli MonitoringV6.2 or later in your environment. IBM Tivoli Monitoring does not have to be onthe same computer as your monitoring agent.

Note: Agent Builder browsers operate on the data sources and informationaccessible from the system on which the Agent Builder is run. Ensure thatyou run the Agent Builder on either of the following types of systems:

v A system that is running on the same level as the operating system andmonitored applications for which you are developing the agent

v A system that connects to one that is running on the same level as theoperating system and monitored applications for which you are

developing the agent

Note: To be able to extract workspaces, situations, or queries with IBM TivoliMonitoring, or to remotely browse processes or services with IBM TivoliMonitoring, you must install a Tivoli Enterprise Portal Server on the samesystem as the Agent Builder. An alternative is to set the followingenvironment variable in the cq.ini file: for any IBM Tivoli Monitoring V6.2.2or later: KFW_ALLOW_OLD_STYLE_AGENT_BUILDER=Y See 392 for additionalinformation.



32/553

Starting the new agent wizard

To start the wizard and create the agent, you can use either of the followingmethods:

v Use the Create New Agent icon on the toolbar.

v Use the File option on the top menu bar.

Note: You might not see the wizard from the new menu if you are not using theResource or IBM Tivoli Monitoring perspective in Eclipse. The IBM TivoliMonitoring perspective opens when you end the wizard, and the problemsview opens by default as well.

Using the icon to start the wizardClick the Create New Agent icon (which resembles a pencil) on the top menu(Figure 9).

The Welcome window (Figure 14 on page 23) for creating an agent is displayed.

Creating a new file to start the wizardSelect one of the following ways to create a new file:

v File > New > IBM Tivoli Monitoring Agent

v File > New > Other

Using File > New > IBM Tivoli Monitoring Agent to start thewizardFor the first of these methods, select File > New > IBM Tivoli Monitoring Agent(Figure 10 on page 19). The Welcome window is displayed.

Figure 9. Create New Agent icon



33/553

Using File > New > Other to start the wizardFor the second of these methods, use the following steps:

1. From the Main Menu, select File > New > Other (Figure 11 on page 20).

Figure 10. Starting the wizard with the File > New > IBM Tivoli Monitoring Agent option

Chapter 5. Creating a basic agent 19


34/553

2. When the Select a Wizard page is displayed (Figure 12 on page 21),double-click the IBM Tivoli Monitoring Wizards folder of wizard options.

Figure 11. Starting the wizard with the File > New > Other option



35/553


36/553

The Welcome window (Figure 14 on page 23) for creating an agent is displayed.

Figure 13. Selecting the agent icon



37/553

Creating and defining the agent

After selecting a method to start the wizard (see “Starting the new agent wizard”on page 18), use the following procedures and options to create and define theagent:

1. Name your agent.

2. Define the data monitoring types by choosing one or more data monitoringcategories and data sources for your new agent to monitor.

3. Selecting key attributes4. Organize the data sources for the agent.

Naming your agentThe agent name that you designate is displayed in the Tivoli Enterprise Portalwhen you are ready to run the agent.

Use the following steps to name your agent:

1. After starting the wizard by any of the methods, click Next in the Welcomewindow (Figure 14) to display the New IBM Tivoli Monitoring Agent Project

Figure 14. Welcome window



38/553

page (Figure 15), where you can type a project name for the folder that iscreated in the Eclipse workspace to hold the necessary files for generating theagent.

Notes:

a. The Location field affords an opportunity to navigate to a directory that isnot the default directory for storing the project contents. If you want to

put or use the project contents in another directory, clear the check boxnext to the Use default field and click Browse to navigate to yourpreferred directory.

b. The Working Set function is an optional Eclipse feature that you can use toadd resources to working sets. You can change how the Eclipse NavigatorView displays resources by adding them to various working sets. See theEclipse help for more information.

2. After you type the project name, click Next to see the General Informationpage (Figure 16 on page 25).

Figure 15. Project page



39/553

The project name is displayed in the Display name field. This name is

displayed in the Tivoli Enterprise Portal.3. Type the copyright statement that you want to use for your new agents in the

Copyright field (Figure 17 on page 26). This statement must meet your legalrequirements for copyrights. This copyright statement is inserted into all of the files that are generated for the agent and can be edited when needed.After you supply the statement once, the Agent Builder remembers yourcopyright statement and displays it in the copyright area each time that youstart the wizard to create a new agent. For example, you might use thefollowing format and contents: Copyright ABC Corp 2009. All rightsreserved. If you are unsure what information you want to supply about thecopyright, contact your enterprise legal department.

4. Select the operating systems for which you want your agent to be built.

Note: An agent can be deployed on a 64-bit operating system as a 32-bitprocess if the 32-bit version of that operating system is selected and the64-bit version of that operating system is not selected.

5. Click Next to display the Agent Information page (Figure 17 on page 26).

Figure 16. General Information page



40/553

6. If you want to change the name of the agent, type a new name in the Servicename field. The service name is the name of the service created on Windowsand is also the name of the service that is displayed in the Manage TivoliMonitoring Services window. The name of the service is Monitoring Agent forName, where Name is any name you choose consisting of letters, numbers,spaces, and underscores.

7. In the Product code field, type the registered product code for your newagent. A range of product codes is reserved for use with the Agent Builder.The allowed values are K00-K99, K{0-2}{A-Z}, and K{4-9}{A-Z}. These valuesare for internal use only and are not intended for agents that are to be sharedor sold.

If you are creating an agent to be shared with others, you must send a note [email protected] to reserve a product code. The request for a product codemust include a description of the agent to be built. A product code is thenassigned, registered and returned to you. When you receive the 3-letterproduct code, you must modify the Agent Builder so that you can use thenew product code.

8. In the Company identifier field, type an alphabetic string that uniquely

identifies the organization developing the agent ("IBM" is reserved.). A goodcandidate for this field can come from your company's URL. For example,from a mycompany.com URL, use the text mycompany.

9. In the Agent identifier field, type an alphabetic string that uniquely identifiesthe agent being developed (for example, DISKMON might be the string for anagent that monitors disk usage). You can use the product code for the agentidentifier.

Note: The combined length of the Agent identifier field and the Companyidentifier field cannot exceed 11 characters.

Figure 17. Agent Information page



41/553

By default, Agent Builder sets the Agent identifier to be the same as theProduct code.

10. In the Version field, type a 3-digit number that identifies the agent version inthe format VRM, where:

V = Version

R = Release

M = ModificationIn the agent editor, a patch level field is available when you need to release afix for an agent, but you do not want to update the version.

11. If you want your agent to support multiple instances, select the Supportmultiple instances of this agent check box.

Some applications can be configured to run multiple instances of theapplication on a system at the same time. When building agents for thesetypes of applications, it is often desirable to separate the management of eachof the application instances so that the IBM Tivoli Monitoring user knowswhen there are problems with one of the application instances. A similarcondition happens if you are building an agent that uses the JMX or SNMPdata provider. Because a data monitor like JMX or SNMP can be used to

monitor remote systems, it is possible to install the agent on one system andmonitor several other systems at the same time. Each of these remote systemscan be represented separately in IBM Tivoli Monitoring and each can havedifferent configuration values for communication. To do this, select theSupport multiple instances of this agent check box, which causes the AgentBuilder to create a "template" agent. After the agent is installed, you can createand configure an instance of the agent for each instance of the monitoredapplication.

12. In the Minimum ITM Version field, select the minimum version of IBM TivoliMonitoring that the agent requires. Table 4 provides the reasons to use eachlevel.

Table 4. Minimum version of IBM Tivoli Monitoring required by the agent

IBM Tivoli Monitoringlevel Reason to use this level

V6.2 By selecting 6.2, the resulting agent will run on IBM TivoliMonitoring, version 6.2 or later, but Subnode ConfigurationOverrides must be defined when the agent is built and otherfeatures listed below will not be available to the agent. (See“Configuring a subnode” on page 265). The default value is6.2.

V6.2.1v The generated agent requires a minimum IBM Tivoli

Monitoring version of 6.2.1 to run successfully, and youcannot install on a version earlier than 6.2.1 Figure 17 onpage 26. If you select 6.2.1, you can "Allow any

configuration property to be overridden in any subnode",(See Allow any configuration property to be overriddenin any subnode in “Advanced subnode configuration” onpage 267.)

v This version has 64-bit numeric attribute support.

v This version includes support for different defaultconfiguration values for Windows and for UNIX andLinux. See Default Value for more information.



42/553

Defining initial data sourceAfter entering the Agent Information, click Next on the Agent Information page(Figure 17 on page 26) to display the Agent Initial Data Source page (Figure 18) soyou can define the first monitor.

After you select one of the Monitoring Data Categories and one of the DataSources, and click Next, the wizard guides you through the process of definingand configuring any of the data collection types that you specify. You begin withthe Agent Initial Data Source page to define data monitoring types by specifyingthe monitoring data categories and the data sources that your new agent is tomonitor. For detailed information about each data source, use the chapters in thisuser's guide depending on the type of data you want to monitor:

v Server process monitoring category

– Process

– Windows service

v Data from a server monitoring category

– WMI

– Perfmon

– SNMP

– SNMP Events

– JMX

Figure 18. Agent Initial Data Source page



43/553

– CIM

– JDBC

v Network management data

– Ping

v Logged data monitoring category

– Log File

– Windows Event Log

v Command or script monitoring category

– Command return code

– Output from a script

v Existing data sources monitoring category

– Join two data sources

v Data source groupings monitoring category

– Subnode Definition

– Navigator group

After you define the initial monitor, you can define additional monitors from theData Source Definition page, the last page of the New Agent Wizard. See “Definingadditional data sources” on page 30.

If you decide to add one or more of the monitoring types after you finish thewizard, use the following information to add them using the Agent Editor:Chapter 6, “Modifying your agent by using the IBM Tivoli Monitoring AgentEditor,” on page 39.

If you have created a new data source that might return more than one data row,you are prompted to select key attributes, see “Selecting key attributes.” When youfinish defining all of your monitors, click Finish, and then generate and installyour new agent. See “Testing an agent” on page 293.

Selecting key attributesWhen an attribute group can return more than one data row, each row representsan entity that is being monitored. Each time monitored data is sampled, IBM TivoliMonitoring needs to a match a row to the entity that is being monitored and toprevious samples for that entity. This matching is done with key attributes. One ormore attributes in the attribute group can be identified as key attributes. These keyattributes, when taken together, distinguish one monitored entity from another, anddo not change from one sample to the next when referring to the same monitoredentity.

Rate and delta attributes are calculated by comparing the current sample to the

previous sample, and identical key attributes ensure that the agent is comparingvalues for the same monitored entity. Similarly, the summarization and pruningagent summarizes samples that have identical key attributes.

After you have specified the details about your new data source (using theinformation in “Defining initial data source” on page 28), if it is possible formultiple data rows to be returned by the data source, the Agent Builder promptsyou to select key attributes on the Select key attributes page (Figure 19 on page 30).

Note: If the browser detected key attributes, those attributes are marked as keyattributes and the Select key attributes page is not displayed.



44/553

On the Select key attributes page, do one of the following steps:

v Click Produces a single data row if this attribute group can return only one row.If this option is selected, no key attributes are necessary because only onemonitored entity is ever reported in this attribute group.

v Click one or more attributes from the list that are the key attributes for thisentity. To select more than one attribute, hold down the Ctrl key.

Defining additional data sourcesAfter you define the initial monitor, you can define additional monitors from theData Source Definition page, by selecting the agent, navigator group, or subnode,and then clicking Add to Selected, or right-clicking on the agent, and selectingAdd Data Source as shown in (Figure 20 on page 31).

Note: You can also add additional monitors after you complete the New AgentWizard. See (Chapter 6, “Modifying your agent by using the IBM TivoliMonitoring Agent Editor,” on page 39), for information on adding monitors

using the Agent Editor. An advantage of using the Agent Editor is that itallows you to save incremental changes as you make them.

Figure 19. Select key attributes page



45/553

When you add a monitor using the Agent Editor Data Source Definition page, theData Source Location page is displayed (Figure 21 on page 32). This page is the

same as the Agent Initial Data Source page (Figure 18 on page 28) except for thename of the page.

Figure 20. Data Source Definition page: defining additional monitors



46/553

After you select one of the Monitoring Data Categories and one of the Data

Sources, and click Next, the wizard guides you through the process of definingand configuring any of the data collection types that you specify. You begin withthe Agent Initial Data Source page to define data monitoring types by specifyingthe monitoring data categories and the data sources that your new agent is tomonitor. For detailed information about each data source, use the chapters in thisuser's guide depending on the type of data you want to monitor:

v Server process monitoring category

– Process

– Windows service

v Data from a server monitoring category

– WMI

– Perfmon

– SNMP

– SNMP Events

– JMX

– CIM

– JDBC

v Network management data

– Ping

v Logged data monitoring category

Figure 21. Data Source Location page



47/553

– Log File

– Windows Event Log

v Command or script monitoring category

– Command return code

– Output from a script

v Existing data sources monitoring category

– Join two data sources

v Data source groupings monitoring category

– Subnode Definition

– Navigator group

Click Finish to add the new data source to the Data Source Definition page.

Organizing the agentYou can organize the data sources for the agent in the following ways:

v Navigator groups

v

Subnodes

A navigator group is a way of grouping data sources in the Tivoli EnterprisePortal. By default, a separate navigation item is created in the Tivoli EnterprisePortal under your agent for each data source that you define. A query is associatedwith that navigator item so a default workspace displays the data collected by thatdata source in a simple table view. If a data source is placed inside a navigatorgroup, a separate navigator item is no longer displayed under the agent.Workspaces that are created for the navigator group might display viewsconstructed from all of the data sources contained in the navigator group. Inaddition to the information in this section (“Navigator groups”), see Chapter 24,“Creating a navigator group,” on page 247 for additional information aboutnavigator groups.

A subnode is a portion of an agent that can be replicated as necessary, dependingon the application or enterprise being monitored. In addition to the information inthis section (“Subnodes” on page 34), see Chapter 25, “Creating subnodes,” onpage 251 for additional information about subnodes.

Navigator groupsNavigator groups are generally used to group several related data sources togetherso that workspaces can be created that show views of the related data sources. Youmight be able to collect file system data from more than one data source. It can beuseful to create one workspace that shows views of all file system data from thosedifferent data sources.

Navigator groups are also a good way to "hide" data sources. You might decidethat certain metrics collected from 2 data sources are most useful if the datasources are joined to create a combined, third data source. You want to see onlythe data combined in the Joined datasource. You can create a navigator group thatcontains all three data sources and create a workspace that contains views todisplay only the combined data source. The two original data sources areeffectively hidden from view in the Tivoli Enterprise Portal. See Chapter 23,“Joining attribute groups,” on page 239 for information about joining data sources.



48/553

Note: When you group data sources in a navigator group, IBM Tivoli Monitoringdoes not associate a query with the navigator group. It is assumed that youdefine a default workspace for the navigator group to display the datasources in a useful format.

The following criteria apply to navigator groups:

v A navigator group can be defined in the base agent or in a subnode.

v A navigator group cannot contain another Navigator group.

SubnodesYou can build a single agent that accomplishes the following tasks by usingsubnodes:

v Monitors each instance of an application running on a system instead of havingto use separate instances of the agent, one for each application instance.

v Monitors several different remote systems instead of having to use separateinstances of the agent, one for each remote system.

v Monitors several different types of entities from one agent instead of having to build and deploy several different agents.

v

Displays an additional level in the Tivoli Enterprise Portal physical Navigationtree allowing additional grouping and customization.

v Defines additional Managed System Lists allowing another level of granularitywith situations.

An agent developer defines subnode types in the Agent Builder. Each type mustcorrespond to a different type of entity that an agent can monitor. Attribute groupsand attributes are added to the subnode type that describes the entity that is beingmonitored. When the agent is deployed and configured, one or more instances of each subnode type can be created. Each instance of a subnode must correspond toan instance of an application, a remote system, or whatever entity the subnodetype was designed to monitor. All subnode instances of a single subnode type haveattribute groups and workspaces that have an identical form, but have data that

comes from the particular entity that is being monitored.

The number of subnodes of each type is determined when the agent is configured.Some configuration data can apply to the agent as a whole, but other configurationdata applies to only a single subnode. Configure each subnode differently from theother subnodes, at least slightly, so that they do not monitor the exact same entityand display the exact same data.

A subnode is displayed within the agent in the physical Navigation tree in theTivoli Enterprise Portal. Workspaces display the data defined by a subnode andsituations can be distributed to one or more instances of a subnode. A managedsystem list is automatically created that contains all instances of the subnode, justlike the Managed System List that is created for an agent.

Because the agents built using the Agent Builder create the subnode instances based on configuration values, these subnodes have the same life span as theagent. There is still just one heartbeat performed for the agent, not a separateheartbeat for each subnode. Defining monitoring for a number of systems orapplication instances using subnodes instead of agent instances can significantlyincrease the possible scale of the IBM Tivoli Monitoring environment.



49/553

Adding or removing a subnode requires reconfiguring the agent, which involvesstopping and restarting it. For this reason, it can be good practice to define theagent as a multi-instance agent as well, so that you can manage portions of yourenvironment separately.

Along with attribute groups in subnodes, an agent can define agent-level attributegroups that reside outside of a subnode. In the Tivoli Enterprise Portal Navigator

tree, a subnode type is displayed under the agent name, and subnode instances aredisplayed under a subnode type. Subnodes are identified by a Managed SystemName (MSN) just like agents, for example 94:Hill.cmn.

For example in the Navigator tree in Figure 22, "Watching Over Our Friends" is anagent with three entities (Boarders, Common Areas, and Kennel Runs) and twosubnode types (Common Area and Kennel Run). Two of these entities havesubnode types defined for them (Common Area and Kennel Run). A subnode isnot required for the third entity (Boarder), which is represented by a single row ina table at the base agent level. The Common Area subnode type has 3 subnodeinstances: 94:Hill:cmn, 94:Meadow:cmn, and 94:Tree:cmn representing threecommon areas in the kennel. The Kennel Run subnode type has four subnodeinstances: 94:system1:run, 94:system2:run, 94:system4:run, and 94:system5:run

representing four kennel runs.

Moving existing data sourcesIf you create a navigator group or a subnode after you have created some attributegroups, and you want some of the existing attribute groups to be moved into thenewly-created navigator group or subnode, use the following procedure:

Figure 22. Subnodes in the Navigator tree



50/553

1. Begin creating a navigator group or subnode as described in Chapter 24,“Creating a navigator group,” on page 247 or Chapter 25, “Creating subnodes,”on page 251.

v On the Data Source page, click Existing data sources in the Monitoring DataCategories area (Figure 23).

v In the Data Sources area, click Move existing data sources in the DataSources area.

v Click Next.

2. On the Currently Defined Data Sources page, select one or more data sources(Figure 24 on page 37).

Figure 23. Move existing data sources



51/553

3. Click Finish.

The data source or data sources selected are moved into the new navigator groupor subnode.

Note: Once a subnode or navigator group has been created, you can moveattribute groups into it from the Data Sources tab of the Agent Editor, by

dragging them from their original location to the navigator group orsubnode in the navigation tree.

Preparing your agent for modifications or for regeneration

To modify an existing agent definition, double-click the itm_toolkit_agent.xml fileto launch the IBM Tivoli Monitoring Agent Editor (see Chapter 6, “Modifying youragent by using the IBM Tivoli Monitoring Agent Editor,” on page 39).

If you installed your agent prior to making modifications, you can uninstall theexisting agent before installing the new one, or you can install the new agentdirectly over the existing agent without uninstalling it. To uninstall the existingagent first, see the procedure in (“Uninstalling an agent” on page 304), thenregenerate and install the agent again as you did initially. If you choose to installover the existing agent, follow the steps in (Chapter 27, “Testing and debuggingyour agent,” on page 293).

If you have changed the version number of your agent, when you install the newversion, files in your IBM Tivoli Monitoring installation that contain the oldversion number are overwritten, except for the file containing your agent'sconfiguration requirements (named according to the format:

product_code_dd_long_version.xml.) For example, for an agent with the product codeof 19 and the version of 6.2.3, the file is called 19_dd_062300000.xml along with the

Figure 24. Currently Defined Data Sources page



52/553

remote deployment bundle for your agent. Both of these are added to the systemalongside the old versions rather than replacing them.



53/553

Chapter 6. Modifying your agent by using the IBM TivoliMonitoring Agent Editor

This chapter covers the following topicsv “IBM Tivoli Monitoring Agent Editor”

v “Saving your edits and changes” on page 49

v “Committing a version of the agent” on page 49

IBM Tivoli Monitoring Agent Editor

This section describes how to open the IBM Tivoli Monitoring Agent Editor andhow to use the Editor pages to change your c

agentbuilder6225 user

Documents