Universal Agent User’s Guide, V410 - IBMpublib.boulder.ibm.com/tividd/td/ITUniAgent/GC32-9350-00/... · 2004-08-28 · User’s Guide Universal Agent Version 410 GC32-9350-00 July

User’s GuideUniversal Agent

Version 410

GC32-9350-00

July 2004

Candle Corporation100 North Sepulveda Blvd.

El Segundo, California 90245

2 Universal Agent User’s Guide, V410

Registered trademarks and service marks of Candle Corporation: AF/OPERATOR, AF/REMOTE, Availability Command Center, Candle, Candle CIRCUIT, Candle Command Center, Candle Direct logo, Candle eDelivery, Candle Electronic Customer Support, Candle logo, Candle Management Server, Candle Management Workstation, CandleLight, CandleNet, CandleNet Command Center, CandleNet eBusiness Platform, CandleNet Portal, CL/CONFERENCE, CL/SUPERSESSION, CommandWatch, CT, CT/Data Server, CT/DS, DELTAMON, DEXAN, eBA, eBA*ServiceMonitor, eBA*ServiceNetwork, eBusiness at the speed of light, eBusiness Assurance, eBusiness Institute, ELX, EPILOG, ESRA, ETEWatch, IntelliWatch, IntelliWatch Pinnacle, MQSecure, MQView, OMEGACENTER, OMEGAMON, OMEGAMON II, OMEGAMON Monitoring Agent, OMEGAMON Monitoring Agents, OMEGAVIEW, OMEGAVIEW II, PQEdit, Response Time Network, Roma, SitePulse, Solutions for Networked Applications, Solutions for Networked Businesses, TMA2000, Transplex, and Volcano.Trademarks and service marks of Candle Corporation: AF/Advanced Notification, AF/PERFORMER, Alert Adapter, Alert Adapter Plus, Alert Emitter, AMS, Amsys, AutoBridge, AUTOMATED FACILITIES, Availability Management Systems, Business Services Composer, Candle Alert, Candle Business Partner Logo, Candle Command Center/SentinelManager, Candle CommandPro, Candle eSupport, Candle Insight, Candle InterFlow, Candle Managing what matters most, Candle Service Suite, Candle Technologies, CandleNet, CandleNet 2000, CandleNet Conversion, CandleNet eBP, CandleNet eBP Access for S.W.I.F.T., CandleNet eBP Administrator, CandleNet eBP Broker Access for Mercator or MQSI, CandleNet eBP Configuration, CandleNet eBP Connector, CandleNet eBP File Transfer, CandleNet eBP Host Connect, CandleNet eBP Object Access, CandleNet eBP Object Browser, CandleNet eBP Secure Access, CandleNet eBP Service Directory, CandleNet eBP Universal Connector, CandleNet eBP Workflow Access, CandleNet eBusiness Assurance, CandleNet eBusiness Exchange, CandleNet eBusiness Platform Administrator, CandleNet eBusiness Platform Connector, CandleNet eBusiness Platform Connectors, CandleNet eBusiness Platform Powered by Roma Technology, CandleNet eBusiness Platform Service Directory, Candle Vision, CCC, CCP, CCR2, CEBA, CECS, CICAT, CL/ENGINE, CL/GATEWAY, CL/TECHNOLOGY, CMS, CMW, Command & Control, Connect-Notes, Connect-Two, CSA ANALYZER, CT/ALS, CT/Application Logic Services, CT/DCS, CT/Distributed Computing Services, CT/Engine, CT/Implementation Services, CT/IX, CT/Workbench, CT/Workstation Server, CT/WS, !DB Logo, !DB/DASD, !DB/EXPLAIN, !DB/MIGRATOR, !DB/QUICKCHANGE, !DB/QUICKCOMPARE, !DB/SMU, !DB/Tools, !DB/WORKBENCH, Design Network, e2e, eBA*SE, eBAA, eBAAuditor, eBAN, eBANetwork, eBAAPractice, eBP, eBusiness Assurance Network, eBusiness at the speed of light, eBusiness at the speed of light logo, eBusiness Exchange, eBX, End-to-End, eNotification, ENTERPRISE, Enterprise Candle Command Center, Enterprise Candle Management Workstation, Enterprise Reporter Plus, ER+, ERPNet, ETEWatch Customizer, HostBridge, InterFlow, Candle InterFlow, Lava Console, Managing what matters most, MessageMate, Messaging Mastered, Millennium Management Blueprint, MMNA, MQADMIN, MQEdit, MQEXPERT, MQMON, NBX, NC4, NetGlue, NetGlue Extra, NetMirror, NetScheduler, New Times, New Team, New Readiness, OMA, OMC Gateway, OMC Status Manager, OMEGACENTER Bridge, OMEGACENTER Gateway, OMEGACENTER Status Manager, OMEGAMON/e, OMEGAMON Management Center, OSM, PathWAI, PC COMPANION, Performance Pac, Powered by Roma Technology, PowerQ, PQConfiguration, PQScope, Roma Application Manager, Roma Broker, Roma BSP, Roma Connector, Roma Developer, Roma FS/A, Roma FS/Access, RomaNet, Roma Network, Roma Object Access, Roma Secure, Roma WF/Access, Roma Workflow Access, RTA, RTN, SentinelManager, Somerset, Somerset Systems, Status Monitor, The Millennium Alliance, The Millennium Alliance logo, The Millennium Management Network Alliance, Tracer, Unified Directory Services, WayPoint, and ZCopy.Trademarks and registered trademarks of other companies: AIX, DB2, MQSeries and WebSphere are registered trademarks of International Business Machines Corporation. Citrix, WinFrame, and ICA are registered trademarks of Citrix Systems, Inc. Multi-Win and MetaFrame are trademarks of Citrix Systems, Inc. SAP is a registered trademark and R/3 is a trademark of SAP AG. UNIX is a registered trademark in the U.S. and other countries, licensed exclusively through X/Open Company Ltd. HP-UX is a trademark of Hewlett-Packard Company. SunOS is a trademark of Sun Microsystems, Inc. All other company and product names used herein may be trademarks or registered trademarks of their respective owners.

Copyright © July 2004, Candle Corporation, a California corporation. All rights reserved. International rights secured.

Threaded Environment for AS/400, Patent No. 5,504,898; Data Server with Data Probes Employing Predicate Tests in Rule Statements (Event Driven Sampling), Patent No. 5,615,359; MVS/ESA Message Transport System Using the XCF Coupling Facility, Patent No. 5,754,856; Intelligent Remote Agent for Computer Performance Monitoring, Patent No. 5,781,703; Data Server with Event Driven Sampling, Patent No. 5,809,238; Threaded Environment for Computer Systems Without Native Threading Support, Patent No. 5,835,763; Object Procedure Messaging Facility, Patent No. 5,848,234; End-to-End Response Time Measurement for Computer Programs, Patent No. 5,991,705; Communications on a Network, Patent Pending; Improved Message Queuing Based Network Computing Architecture, Patent Pending; User Interface for System Management Applications, Patent Pending.

NOTICE: This documentation is provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by the Government is subject to restrictions set forth in the applicable license agreement and/or the applicable government rights clause.This documentation contains confidential, proprietary information of Candle Corporation that is licensed for your internal use only. Any unauthorized use, duplication, or disclosure is unlawful.

Contents 3

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Adobe Portable Document Format . . . . . . . . . . . . . . . . . . . . . . . . . . 14Documentation Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Candle Customer Service and Satisfaction . . . . . . . . . . . . . . . . . . . . 18

What’s New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Chapter 1. Introducing the Universal Agent . . . . . . . . . . . . . . . . . . . . . . . . 21Understanding the Universal Agent . . . . . . . . . . . . . . . . . . . . . . . . . . 22A Simple Monitoring Scenario. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Chapter 2. Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34What Type of Data Provider Should I Use? . . . . . . . . . . . . . . . . . . . . 35How Many Universal Agents Do I Need?. . . . . . . . . . . . . . . . . . . . . . 37Setting Environment Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Starting the Universal Agent and its Data Providers . . . . . . . . . . . . . . 41

Chapter 3. Creating an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Constructing a Data Definition Metafile . . . . . . . . . . . . . . . . . . . . . . . 45Validating Data Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Activating Metafiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Creating a Metafile Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Versioning of Metafiles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Contents


Chapter 4. About Data Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63About Data Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64File Data Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69API Server Data Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Socket Data Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Post Data Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89HTTP Data Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96SNMP Data Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104WBEM Data Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105ODBC Data Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Chapter 5. Monitoring Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Monitoring Universal Agent Data. . . . . . . . . . . . . . . . . . . . . . . . . . . 122Universal Agent Managed Systems . . . . . . . . . . . . . . . . . . . . . . . . . 123Customer Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126UAGENT Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Universal Agent Situations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Historical Data Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Chapter 6. Introducing the SNMP Emitter . . . . . . . . . . . . . . . . . . . . . . . . 139Understanding the SNMP Emitter . . . . . . . . . . . . . . . . . . . . . . . . . . 140Installing and Integrating the SNMP Emitter . . . . . . . . . . . . . . . . . . 142Using the SNMP Emitter and its Data . . . . . . . . . . . . . . . . . . . . . . . 143

Appendix A. Data Definition Control Statements. . . . . . . . . . . . . . . . . . . . . 149Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150SNMP Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151WBEM Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152APPL Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153NAME Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154INTERNAL Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158SOURCE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162RECORDSET Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168CONFIRM Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173SQL Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174SUMMARY Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Contents 5

ATTRIBUTES Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Metafile Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Appendix B. Attribute Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Defining Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190Exploring Attribute Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . 194Deriving Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198Filtering Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202Sequencing Attribute Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Appendix C. Console Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209Using Console Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215GENERATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216IMPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220LIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221LOADCOMM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222LOADLIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223LOADNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224MNL ADD NODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225MNL REMOVE NODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226REFRESH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227SET. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228SHOW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229SHUTDOWN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231TRAPCNFG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232UNPACK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233VALIDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

Appendix D. Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235Setting Environment Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236Universal Agent and Data Provider Variables . . . . . . . . . . . . . . . . . 237

Appendix E. Problem Determination. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249Universal Agent Problem Determination . . . . . . . . . . . . . . . . . . . . . 250Documents Required for Problem Reporting . . . . . . . . . . . . . . . . . . 253


Appendix F. Migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255Migrating to V410 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Tables 7

Table 1. Symbols in Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Table 2. Universal Agent Data Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Table 3. Preferred Data Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Table 4. Name and Location of Variables File by Platform . . . . . . . . . . . . . . . 39Table 5. Default Location of Metafiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Table 6. Example of Version Numbering. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Table 7. Post Data Provider Message Categories . . . . . . . . . . . . . . . . . . . . . . . 90Table 8. Post Data Provider Environment Variables . . . . . . . . . . . . . . . . . . . . 92Table 9. URL Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Table 10. URL Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Table 11. DPLOG Workspace Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Table 12. Log Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Table 13. ACTION Workspace Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Table 14. Default Values for Event Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191Table 15. Descriptions of Derived Attribute Functions . . . . . . . . . . . . . . . . . . . 200Table 16. Filter Function Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203Table 17. Summary of Console Commands . . . . . . . . . . . . . . . . . . . . . . . . . . 213Table 18. Name and Location of Variables File by Platform . . . . . . . . . . . . . . 236Table 19. Universal Agent Environment Variables . . . . . . . . . . . . . . . . . . . . . . 237Table 20. RAS1 Trace Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Tables


Figures 9

Figure 1. How the Universal Agent Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Figure 2. NTLOG.MDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Figure 3. FTPLIMIT Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Figure 4. Creating a data definition metafile . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Figure 5. Metafile TCPIOQ.MDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Figure 6. Example of Validation Output TCPIOQ.RPT . . . . . . . . . . . . . . . . . . . 50Figure 7. Activating Metafiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Figure 8. Example of a Data Provider Configuration File . . . . . . . . . . . . . . . . . 53Figure 9. Relationship between Data Sources, Metafiles, and Data Providers . . 64

Figure 10. Implementation of API Server Data Provider . . . . . . . . . . . . . . . . . . . 76Figure 11. Socket Data Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Figure 12. KUMPOST Data Definition Metafile . . . . . . . . . . . . . . . . . . . . . . . . . 90Figure 13. Test_Yahoo Situation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Figure 14. Metafile with Derived Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Figures


Preface 9

Preface

The Universal Agent User’s Guide introduces you to the Universal Agent, an agent of OMEGAMON® XE. The Universal Agent enables you to use the monitoring and automation capabilities of the OMEGAMON XE to monitor any type of data you collect.

This guide covers how to

� deploy and configure the Universal Agent

� define your data to the Universal Agent

� send data to the Universal Agent

� use the CandleNet Portal™ to manage your data

P

About This Book


About This Book

Who should read this bookThis guide is designed for those responsible for setting up the Universal Agent and its Data Providers, for preparing and defining the data to send to the Universal Agent, for creating programs or scripts to export data, or for monitoring Universal Agent data using the CandleNet Portal.

The guide assumes a working knowledge of the OMEGAMON XE environment.

This guide is intended to provide the information you need to use the Universal Agent and the OMEGAMON XE to monitor user-defined data. It is designed to complement the online help provided with the Universal Agent and CandleNet Portal, and the topics covered in the Administering OMEGAMON Products: CandleNet Portal.

Documentation set informationCandle® provides a complete set of documentation for the Universal Agent. Each manual in this documentation set contains a specific type of information to help you use the product. Relevant manuals are the

� Universal Agent User’s Guide, V410, UM54-6769

Introduces the features, workspaces, attributes, predefined situations, and take action commands for Universal Agent.

� Universal Agent SNMP Data Provider User's Guide, V410, UM54-6770

Introduces the SNMP Data Provider, enabling you to use the monitoring and automation capabilities of OMEGAMON XE to manage your network resources.

� Universal Agent API/Command Programming Reference Guide, V410, UM53-6771

Explains the procedures for implementing the Universal Agent APIs and provides descriptions, syntax, and return status codes for the API calls and command line interface commands.

Preface 11

Adobe Portable Document Format

� the documentation for CandleNet Portal that came with your Universal Agent product

Provides instructions for using the CandleNet Portal interface to monitor the enterprise.

� the documentation for OMEGAMON XE that came with your Universal Agent product

Provides instructions for setting up the Candle Management Server® (CMS™).

� the installation documentation that came with your Universal Agent product

Provides instructions for installing the product and the framework components.

Where to look for more informationFor more information related to this product and other related products, please see the

� technical documentation CD-ROM that came with your product

� technical documentation information available on the Candle web site at www.candle.com

� online help provided with this and the other related products

Ordering additional documentationTo order additional product manuals, contact your Candle Support Services representative.

We would like to hear from youCandle welcomes your comments and suggestions for changes or additions to the documentation set. A user comment form, located at the back of each manual, provides simple instructions for communicating with the Candle Information Development department. You can also send email to [email protected]. Please include "Universal Agent User’s Guide, V410" in the subject line.

https://www.candle.com/www1/techdocs/red.html

About This Book



Printing this bookCandle supplies documentation in the Adobe Portable Document Format (PDF). The Adobe Acrobat Reader will print PDF documents with the fonts, formatting, and graphics in the original document. To print a Candle document, do the following:

1. Specify the print options for your system. From the Acrobat Reader Menu bar, select File > Page Setup… and make your selections. A setting of 300 dpi is highly recommended as is duplex printing if your printer supports this option.

2. To start printing, select File > Print... on the Acrobat Reader Menu bar.

3. On the Print pop-up, select one of the Print Range options for� All� Current page� Pages from: [ ] to: [ ]

4. (Optional). Select the Shrink to Fit option if you need to fit oversize pages to the paper size currently loaded on your printer.

Printing problems?The print quality of your output is ultimately determined by your printer. Sometimes printing problems can occur. If you experience printing problems, potential areas to check are:� settings for your printer and printer driver. (The dpi settings for both your

driver and printer should be the same. A setting of 300 dpi is recommended.)

� the printer driver you are using. (You may need a different printer driver or the Universal Printer driver from Adobe. This free printer driver is available at www.adobe.com.)

� the halftone/graphics color adjustment for printing color on black and white printers (check the printer properties under Start > Settings > Printer). For more information, see the online help for the Acrobat Reader.

� the amount of available memory in your printer. (Insufficient memory can cause a document or graphics to fail to print.)

For additional information on printing problems, refer to the documentation for your printer or contact your printer manufacturer.

Preface 11


Contacting AdobeIf additional information is needed about Adobe Acrobat Reader or printing problems, see the Readme.pdf file that ships with Adobe Acrobat Reader or contact Adobe at www.adobe.com.

Adding annotations to PDF filesIf you have purchased the Adobe Acrobat application, you can add annotations to Candle documentation in .PDF format. See the Adobe product for instructions on using the Acrobat annotations tool and its features.

http://www.adobe.com

About This Book


Documentation Conventions

IntroductionCandle documentation adheres to accepted typographical conventions for command syntax. Conventions specific to Candle documentation are discussed in the following sections.

Panels and figuresThe panels and figures in this document are representations. Actual product panels may differ.

Required blanksThe slashed-b (!) character in examples represents a required blank. The following example illustrates the location of two required blanks.

!!!!eBA*ServiceMonitor!!!!0990221161551000

Revision barsRevision bars (|) may appear in the left margin to identify new or updated material.

Variables and literals in command syntax examplesIn examples of command syntax for the OS/390, VM, OS/400, and NonStop Kernel platforms, uppercase letters indicate actual values (literals) that the user should type; lowercase letters indicate variables that represent data supplied by the user:

LOGON APPLID (cccccccc)

However, for the Windows and UNIX platforms, variables are shown in italics:

-candle.kzy.instrument.control.file=instrumentation_control_file_name-candle.kzy.agent.parms=agent_control_file_name

Note: In ordinary text, variable names appear in italics, regardless of platform.

Preface 11


SymbolsThe following symbols may appear in command syntax:

Table 1. Symbols in Command Syntax

Symbol Usage

| The “or” symbol is used to denote a choice. Either the argument on the left or the argument on the right may be used. Example:

YES | NOIn this example, YES or NO may be specified.

[ ] Denotes optional arguments. Those arguments not enclosed in square brackets are required. Example:

APPLDEST DEST [ALTDEST]In this example, DEST is a required argument and ALTDEST is optional.

{ } Some documents use braces to denote required arguments, or to group arguments for clarity. Example:

COMPARE {workload} -REPORT={SUMMARY | HISTOGRAM}

The workload variable is required. The REPORT keyword must be specified with a value of SUMMARY or HISTOGRAM.

_ Default values are underscored. Example:

COPY infile outfile - [COMPRESS={YES | NO}]In this example, the COMPRESS keyword is optional. If specified, the only valid values are YES or NO. If omitted, the default is YES.

About This Book


Candle Customer Service and Satisfaction

BackgroundTo assist you in making effective use of our products, Candle offers a variety of easy-to-use online support resources. The Candle Web site provides direct links to a variety of support tools that include a range of services. For example, you can find information about training, maintenance plans, consulting and services, and other useful support resources. Refer to the Candle Web site at www.candle.com for detailed customer service information.

Candle Customer Service and Satisfaction contactsYou will find the most current information about how to contact Candle Customer Service and Satisfaction by telephone or e-mail on the Candle Web site. Go to www.candle.com support section and choose the link to Support Contacts to locate your regional support center.

http://www.candle.com

http://www.candle.com

What’s New 19

What’s New

OverviewIn Version 410, a variety of features improve the usability of the Universal Agent and make it possible to monitor data from additional sources. A new Data Provider monitors data from ODBC-compliant databases. Universal Agent also allows you to automatically generate ODBC metafiles, to collect SNMP MIB data from non-standard ports, and to collect demand-driven data from the API Server Data Provider.

ODBC Data ProviderOpen Database Connectivity (ODBC) is a standard application programming interface for accessing data in relational data sources. The Universal Agent ODBC Data Provider, only available on Windows platforms, allows you to collect data from ODBC-compliant databases using SQL Select statements and stored procedures supported by the particular ODBC source that is being monitored.

Automatic Generation of ODBC MetafilesThe GENERATE command automatically builds a complete and syntactically correct ODBC metafile when given a data source name as input. This new command supports full generation of all tables defined to the specified data source. You can also limit which tables will be generated by selecting user tables, system tables, or views (or some combination of the three) and by specifying a beginning string of characters to pattern match against any of the three table types.

W


SNMP MIB Data Collection from Non-standard PortsCertain vendor SNMP agents may feature special requirements, such as using ports other than the default monitoring port. Universal Agent’s SNMP Data Provider, which acts as an SNMP Manager that polls SNMP agents for MIB data, now supports configuration and polling of SNMP agents using ports other than 161 (the default port).

Demand-Driven Data Collection for the API Server Data ProviderUniversal Agent has traditionally relied on interval-driven data collection (also referred to as sample-driven). Data Providers collect data at fixed intervals for each application table. In this mode, all report, history, and situation processing uses the most recently collected data. The API Server Data Provider now supports interval-driven and demand-driven data collection. Collecting data "on demand" offers fresher data and potentially reduces unnecessary processing overhead.

Introducing the Universal Agent 21

Introducing the Universal Agent

OverviewThis chapter provides a high level introduction to the Universal Agent. It also presents a simple scenario illustrating the steps required to implement monitoring with the Universal Agent using a File Data Provider.

Chapter contentsUnderstanding the Universal Agent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22A Simple Monitoring Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

1

Understanding the Universal Agent



What is the Universal Agent?The Universal Agent is a generic agent of OMEGAMON XE. It can be configured to monitor any data you collect. The data can be viewed in real-time and historical workspaces on CandleNet Portal and managed with CandleNet Portal monitoring situations and automation policies, just like data from other Candle Monitoring Agents.

The Universal Agent extends the performance and availability management capabilities of OMEGAMON XE to applications and platforms for which neither Candle nor other software vendors provide prepackaged solutions. It gives you a single point of management for all your enterprise resources and protects your investment in applications and resources.

What does the Universal Agent offer?The Universal Agent lets you:

� integrate data from virtually any platform and any source—custom applications, databases, systems, subsystems, networks, even POS controllers

� monitor just the data attributes that interest you

� respond quickly to changing monitoring and management scenarios

� be in control of attributes and surfacing of data

How does the Universal Agent work?The Universal Agent gets its data from interfaces called Data Providers. Data Providers enable you to supply data to the Universal Agent in whatever way is most convenient or practical for a particular monitoring scenario—via a sequential file, TCP/IP socket program, API calls, SNMP traps, or console commands.

You create data definitions which describe the source and structure of the data supplied to the Data Providers. The Data Providers relay the data and data definitions you supply to the Universal Agent. The Universal Agent uses the



data from the Data Providers to generate and transmit the files required by the Candle Management Server (CMS) and the CandleNet Portal.

The Universal Agent also:

� monitors and reports the status of Data Providers

� accepts and processes requests from Data Providers

� accepts CandleNet Portal requests for information for workspaces and event monitoring

� manages version control of data definitions

� distributes automation requests to Data Providers

Table 2 lists the Data Providers currently available with the Universal Agent. Figure 1 on page 25 illustrates the relationship between Data Providers, Universal Agents, the CMS, and the CandleNet Portal.

Table 2. Universal Agent Data Providers

Type Description

File Monitors sequential files, such as system or message logs. Provides the most direct, simplest method of collecting data. See “File Data Provider” on page 69.

API Server Listens on a TCP/IP socket for data sent using Universal Agent API calls. Enables you to collect data from resources on remote machines where the Universal Agent API client resides. See “API Server Data Provider” on page 75.

Socket Listens on a TCP/IP socket for data sent using program-to-program communication. Enables you to collect data from remote devices or machines for which no Universal Agent API support is available. See “Socket Data Provider” on page 78.

Post TCP/IP socket application with predefined data. Enables you to send ad hoc notifications such as messages, alerts, and status. See “Post Data Provider” on page 89.



API, Socket, File Set (ASFS) Consolidates three types of Data Providers into a single package, which can be started as a single thread or process

HTTP Allows monitoring of Internet URLs for availability and response time. You can specify URLs to monitor in a startup configuration file or within CandleNet Portal situations. See “HTTP Data Provider” on page 96.

SNMP Provides the functionality of an SNMP manager, including network discovery, trap monitoring, and SNMP queries. Refer to the Universal Agent SNMP Data Provider User’s Guide for more information.

WBEM Allows Windows monitoring of Windows XP, Windows NT, and Windows 2000 systems. See “WBEM Data Provider” on page 105.

ODBC Allows data collection from ODBC-compliant databases using SQL Select statements and stored procedures. See “ODBC Data Provider” on page 115.

Table 2. Universal Agent Data Providers (continued)

Type Description



Data Source

A

Data Source

C

Data Source

B

File Data Provider Socket Data

Provider

API Data Provider

Data Source

D

Universal Agent

network

Figure 1. How the Universal Agent Works

In this illustration, Data Source A is a log file, monitored by a File Data Provider. Data Source B is a program on a remote host that supplies data via a TCP/IP socket to the Socket Data Provider. Data Source C uses the Universal Agent APIs to send data to the API Server Data Provider, as does Data Source D on a remote host.

network



How do I define data to the Universal Agent?You tell the Universal Agent what data you want it to monitor by creating the Universal Agent application. The Universal Agent application consists of one or more attribute groups, each group consisting of one or more attributes. You define the application in a data definition metafile, which is imported by the Universal Agent.

How do I provide data to the Universal Agent?You can supply data to the Universal Agent in whatever way is most convenient and suitable for your needs and environment.

For example, if the data you want to monitor is already in a sequential file, and you decide to use a File Data Provider, you do not need to process the data further. If you want to use a File Data Provider, but your data is not already in a sequential file, you can write a program that preprocesses the raw log file and writes the records to a second, sequential file.

However, if you decide to use either an API Server or a Socket Data Provider to monitor your data, you can retrofit your applications or create a program to issue Universal Agent API calls to forward data directly to the API Server Data Provider, or create programs that send the data to the Socket Data Provider.

What can I do with my data?Once the Universal Agent acquires the data and data definitions you supply, you can:

� View real-time and historical data on demand—Once the CMS has imported your data and data definitions, you can view real-time or historical workspaces for each group of attributes you defined. You can customize the workspaces and export the workspace data to other applications for manipulation and presentation (see “Customer Workspaces” on page 126).

� Set event alerts—You can use the attributes you define to create CandleNet Portal situations that alert you to actual or potential problems that threaten availability or performance of your applications and resources. You can even create complex situations that combine Universal Agent situations with situations you monitor with other Candle monitoring agents (see “Universal Agent Situations” on page 133).



� Program automatic responses to events—You can create policies that respond automatically to critical events by executing system commands or complex activity programs.

� Monitor the status of Data Providers from CandleNet Portal—The Universal Agent provides workspaces that let you monitor the status and operation of its Data Providers and the automated actions they support (see“UAGENT Workspaces” on page 129).

Can I monitor applications on non-supported environments?You can monitor applications on non-supported environments, such as AS/400, provided that the Universal Agent is not required to run on these platforms. For example, SNMP solutions do not require the Universal Agent to run on the platform where the SNMP Agent resides. If an SNMP MIB is not available, then a TCP/IP socket client script or program could be developed on the platform to collect and send data across the network to the Socket Data Provider.

A Simple Monitoring Scenario



OverviewThis simple scenario illustrates the steps required to implement monitoring with the Universal Agent:

1. Selecting the appropriate Data Provider2. Preparing the data source3. Defining the Universal Agent application4. Create monitoring situations and policies using Universal Agent

application attributes

Selecting the Data ProviderYou would like to monitor FTP activity on your Windows NT server, NTSRV1. You would also like to prevent users from making uploads to the server that consume large amounts of disk space.

Since the Windows NT FTP Service can be configured to create a log file, you decide that the simplest solution would be to use the File Data Provider.

Preparing the data sourceYou configure the Windows NT FTP Service to create a log file, specifying its name and characteristics. You decide to have the system automatically open a new log file every month, so the name of the first file is something like IN0204.LOG.

You can make a mental note that you need to change the name of the data source in the SOURCE statement of your data definition metafile every month as the name of the log file changes. Or you can use the new file name pattern feature as described in “Dynamic File Name Support” on page 71.

Defining the Universal Agent applicationYou define an NT Log application by creating the metafile NTLOG.MDL shown in Figure 2 on page 29.



In the metafile, you name the application NTLOG and specify the source of the attribute data as a file named IN0204.LOG, located in C:\WINNT\SYSTEM32\LOGFILES. You define one attribute group, named FTPLOGFILE, and specify the monitoring method as E, for event. You supply the names and characteristics of the 14 attributes you want to monitor. (Refer to “Creating an Application” on page 43 and “Data Definition Control Statements” on page 149 for information on creating metafiles.)

You place the metafile in the Universal Agent working directory on NTSRV1 so that it is loaded automatically at startup. (See “Setting Environment Variables” on page 236 for information on creating a working directory.)

Now you are ready to start the Universal Agent. You want to start just the File Data Provider, so you specify file as the startup parameter when you start the Universal Agent.

Since you have not created a configuration file, the Universal Agent automatically loads NTLOG.MDL from the default directory. (See “Activating Metafiles” on page 51 for information on loading metafiles. See the

Figure 2. NTLOG.MDL

//Appl NTLOG//NAME FTPLOGFILE E//SOURCE FILE C:\WINNT\SYSTEM32\LOGFILES\IN204.LOG Tail//ATTRIBUTES ’,’

ClientAddr D 32ClientName D 32Date D 16Time D 16Service D 32ServerName D 32ServerAddr D 32ElapsedTime C 100000BytesReceived C 100000BytesSent C 100000SrvStatusCode C 100000NTStatusCode C 100000OperationName D 64ObjectName D 256



installation manual for your platform for instructions for starting and stopping an OMEGAMON XE agent, such as Universal Agent.)

Viewing attribute data from FTPLOGFILEThe Navigator provides a physical view of your monitored network, organized by operating system platform, system type, Candle product (agents), and the attribute groups from which the agents can collect information. One of the managed systems has the name NTSRV1:NTLOG00, reflecting the application you defined in the APPL statement in the metafile. You also see a physical mapping of the system within the CNP navigator with the name NTLOG00. (Refer to “Monitoring Applications” on page 121 for information on the naming of managed systems, Customer workspaces, and attributes.) When you open this item representing the application, you see a workspace entry named FTPLOGFILE, representing the attribute group. Click the item to access the workspace. The columns of the workspace correspond to the attributes you defined in the metafile. (Refer to “Customer Workspaces” on page 126 for information on viewing workspaces.)

Creating an automation policyNow that you have defined the NT log attributes to the CMS, you can use them to create a monitoring situation that trips when a file being uploaded is 10MB or more.

Using the CNP Situation editor, you use the attribute BytesReceived to create the following situation, which you distribute to NTSRV1:

NTLFTPLOGFILE00.BytesReceived *GE 10,000,000

Now, whenever a user tries to upload a file of 10MB or more, this situation fires.

Next you create a policy named FTPLimit, which waits for the situation to fire and then

1. sends a message to the user uploading the file (ClientName) that the file exceeds FTP limits and that the Service is being terminated

2. performs the action "Net stop "FTP Publishing Service" to stop the FTP Service



3. notifies the operator on the CNP that the FTP Publishing Service has been stopped

4. restarts the Service if the operator does not take action within 5 minutesThe following figure illustrates the FTPLimit policy. (Refer to the Administering OMEGAMON Products: CandleNet Portal and the CNP online help for instructions on creating situations and policies.)

Figure 3. FTPLIMIT Policy

Action: Net Start “FTP Publishing Service”

ALWAYS

Action: Net send &NTLFTPLOGFILE00.ClientName FTP limit exceeded. Service ended.

ALWAYS

Action: Net Stop “FTP Publishing Service”

ALWAYS

User Choice: “FTP Limit Exceeded” (5 minute timeout)

CHOICETIMEOUT

. . .

Action: Net Start “FTP Publishing Service”

CHOICE



Getting Started 33

Getting Started

OverviewThis chapter deals with setting up the Universal Agent. It addresses the questions of which type of Data Provider you should use and how many Universal Agents you should install. It also discusses setting environment variables to suit your monitoring scenarios and provides instructions for starting and stopping the Universal Agent and its Data Providers.

Chapter contentsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34What Type of Data Provider Should I Use? . . . . . . . . . . . . . . . . . . . . . . . . 35How Many Universal Agents Do I Need? . . . . . . . . . . . . . . . . . . . . . . . . . 37Setting Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Starting the Universal Agent and its Data Providers . . . . . . . . . . . . . . . . . 41

2

Introduction


Introduction

OverviewImplementing the Universal Agent involves three tasks:

� setting up and configuring the Universal Agent

� defining Universal Agent applications

� monitoring data on the CandleNet Portal

This chapter deals with the first task, setting up the Universal Agent. It addresses some of the questions you need to answer in order to configure the Universal Agent to monitor your data effectively. Subsequent chapters address defining your data to the Universal Agent by creating Universal Agent applications and monitoring your data on the CNP.

Setting up the Universal AgentSetting up the Universal Agent involves:

� selecting the types of Data Provider you want to use

� deciding how many Universal Agents you want to install

� setting environment variables

Getting Started 35

What Type of Data Provider Should I Use?


OverviewThe decision about which type of Data Provider to use to monitor your data rests primarily upon two considerations: the type of data you want to monitor and where the data is located.

What type of data do you want to monitor?If your data is available in a sequential file on an operating system supported by the Universal Agent, the File Data Provider offers the simplest, most direct means of monitoring your data.

Even if your data is not already in a sequential file, you may be able to create an extraction program to export the data from the native source to a sequential file, or to modify your application to direct data to a file, and still use a File Data Provider.

If your data cannot be easily exported to a sequential file, or the data source is on a platform that the Universal Agent does not support, you can use the Socket Data Provider or API Data Provider. If you are monitoring SNMP traps or the status of SNMP-enabled resources, you can use the SNMP Data Provider.

Where is your data?The possibility of using the File Data Provider or the choice between the API Server or Socket Data Provider can depend upon the platform where your data source resides.

The File Data Provider must reside on the same platform as the file it monitors, or be capable of logically mapping to the file across the network as if the file were local. Even when data resides in a sequential file, you cannot use a File Data Provider to monitor it if it is located on an operating system that the Universal Agent does not support.

To use the Universal Agent APIs, you need to install the Universal Agent API dynamic link library for the platform you plan to develop on. This run-time library, which is part of what is called the API client package, is not available on all platforms. To use the Socket Data Provider, however, the only



requirement is that your platform have a TCP/IP stack with a socket interface, which will be true in almost all cases.

What type of programming is required?Since the Universal Agent APIs encapsulate many of the details of dealing with TCP/IP sockets, it is easier to use the API Server Data Provider than the Socket Data Provider. If you have a choice between the Socket and the API Server Data Provider, you should probably choose the API Server Data Provider. But if your data resides on a platform not supported by the API client package, such as OS/390, then the Socket Data Provider is the right choice.

Table 3. Preferred Data Providers

Data Source Preferred Data Provider

Log files File

Ad hoc notifications such as messages, alerts, and status information

Post

Application internals (supported API client platform)

API Server

Application internals (nonsupported API client platform) using TCP/IP

Socket

Any combination of the following:� log files� application internals (supported API

client platform)� application internals (nonsupported API

client platform)

API, Socket, File Set (ASFS)

Internet or Intranet URLs HTTP

Relational Databases ODBC

SNMP MIB data SNMP

WMI data WBEM

Getting Started 37

How Many Universal Agents Do I Need?


OverviewTheoretically, you can run as many Universal Agents as you wish. How many you should actually use depends upon the source of your data and what type of Data Provider you are going to use to monitor it, as well as various site-specific considerations such as network traffic and departmental control.

One Universal Agent or many?A File Data Provider must execute on a machine where your files are available locally. This means that if you want to monitor application log files on 20 different machines, you need to install 20 Universal Agents, one on each host— unless the remote files are available via some networking scheme like NFS on UNIX.

The other Data Providers (Post, Socket, API Server, HTTP, ODBC, SNMP, and WBEM) are distributed Data Providers. That is, they do not have to execute in the same location as their data sources. So if you plan to monitor data that is not accessible from a file, you can start just one Universal Agent, which can receive data sent from any machine in your enterprise. You may, however, choose to use more than one Universal Agent for reasons such as limiting network traffic or allowing data about resources managed by different departments to be monitored by different Universal Agents.

How many Universal Agents can I run on the same host?You can run as many Universal Agents as you wish on a given host. However, this is usually not necessary because one Universal Agent can monitor data from multiple sources. (For more information, see “Running Multiple Instances of a Data Provider” on page 65.) For example, with the ASFS Data Provider a single Universal Agent can monitor multiple files, multiple API clients, and multiple socket clients.



How many Data Providers can I start with one Universal Agent?When you start the Universal Agent, by default it starts the ASFS Data Provider. You can override the default startup configuration by specifying any or all of the Data Providers as arguments of the startup command. (For startup command and arguments, consult the installation guide for your platform.) You can also change the default startup using the environment variable KUMA_STARTUP_DP.

KUMA_STARTUP_DP uses the same arguments as the startup command, separated by commas. For example:

KUMA_STARTUP_DP=POST,SNMP

would only start the Post and SNMP Data Providers.

Getting Started 39

Setting Environment Variables


OverviewThe Universal Agent and its Data Providers support a number of environment variables which specify values for locations, ports, working directories, and the like. Unless you specify otherwise, the default values for these variables are in force. After you have installed the Universal Agent, you may want to override the defaults for some of these variables. At a minimum, you should set the working directory (see “Setting the working directory” below).

Appendix D, “Environment Variables” on page 235, contains a table listing the environment variables for the Universal Agent and its Data Providers.

Name and location of environment variables fileTo change the default values, you must enter (or, in some cases, uncomment) the appropriate variable and the desired value in a environment variables file. The name and location of the variables file differs by platform.

Table 4 contains the name and location of the environment variables file on each of the supported platforms.

Editing the environment variables fileYou can edit the environment variables file directly using a text editor.

Note: Stop the agent before configuring Universal Agent or editing um.config. If you don’t stop the agent, the new configuration is wiped out, and the previous values are again placed in um.config.

On Windows you can also edit the KUMENV file using Manage Candle Services.

Table 4. Name and Location of Variables File by Platform

Platform Location Name/Member

UNIX Candle/config/ um.config

Windows Candle\cma\ KUMENV



Editing KUMENV on Windows using Manage Candle Services

To edit KUMENV using Manage Candle Services:

1. From the Start button, select Programs > Candle Command Center > Manage Candle Services.The Manage Candle Services dialog appears.

2. Right-click the Universal Agent, then select Advanced > Edit ENV file . . .KUMENV is opened in Notepad.

3. Edit or add the variables you wish to specify.

4. Save the changes and close Notepad.

Setting the working directoryThe working directory is where the Universal Agent looks for configuration files and where it places its working files. On Windows, a separate directory, named work, is created for you and the variable KUM_WORK_PATH preset to specify candle\cma\work directory as the working directory. On UNIX, a separate directory, named work, is created for you and the variable KUM_WORK_PATH preset to specify CANDLE/architecture/um/work directory, where architecture is the operating system and version. For example:

/Candle/sol283/um/work

indicates the Solaris 2.8 32-bit platform.

You can use KUM_WORK_PATH to specify whatever directory you like.

Getting Started 41

Starting the Universal Agent and its Data Providers


OverviewOn UNIX and Windows you start the Universal Agent using Manage Candle Services. UNIX platforms also offer a command line interface for configuring, starting, and stopping the Universal Agent.

By default, when you start the Universal Agent, the consolidated (ASFS) Data Provider is started as well. You may specify different or additional Data Providers to start when you start the Universal Agent by changing the startup parameters or by setting the environment variable KUMA_STARTUP_DP.

Specifying Data ProvidersCandle recommends that you specify which Data Providers you wish to start when you start the Universal Agent by setting KUMA_STARTUP_DP to specify one or more of the following arguments.

� ASFS to start the consolidated Data Provider

� APIS to start the API Server Data Provider

� FILE to start the File Data Provider

� HTTP to start the HTTP Data Provider

� ODBC to start the ODBC Data Provider

� POST to start the Post Data Provider

� SOCK to start the Socket Data Provider

� SNMP to start the SNMP Data Provider

� WBEM to start the WBEM Data Provider

For example, if you specify

KUMA_STARTUP_DP=ASFS,SNMP

the consolidated API, Socket and File Data Providers and SNMP Data Providers will be activated when you start the Universal Agent. However, on Windows and UNIX you may also use the same arguments as startup parameters when you start the Universal Agent.



Specifying startup parameters on WindowsTo specify startup parameters on Windows:

1. From the Start button, select Programs > Candle Command Center > Manage Candle Services.

2. In the Manage Candle Services window, right-click the Universal Agent, then select Change Startup Parms from the pop-up menu.

3. Enter the parameters in the entry field, separated by commas, then click OK.The startup parameters you specify using this dialog are not persistent; they do not remain in effect when the agent is restarted.

Specifying startup parameters on UNIXIf you want to start the Data Provider manually (instead of through KUMA_STARTUP_DP), you must start the Universal Agent from a command line and specify the Data Provider you wish to start as parameters in a start command string. For example:

CandleAgent -o SNMP start um

If you are starting the HTTP Data Provider on an alternate instance of UA named Test (which was previously configured), you would enter this command string:

CandleAgent -o HTTP -p Test start um

Creating an Application 43

Creating an Application

OverviewThis chapter describes how to create the Universal Agent application which defines the data that you want to manage. It covers how you

� construct a data definition metafile

� validate your metafile

� import the metafile to the Universal Agent

� create a metafile server

This chapter also explains how version numbers are assigned to metafiles and how the version numbers of metafiles affect the naming of managed systems, workspaces, and attributes on CandleNet Portal.

Chapter contentsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Constructing a Data Definition Metafile . . . . . . . . . . . . . . . . . . . . . . . . . . 45Validating Data Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Activating Metafiles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Creating a Metafile Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Versioning of Metafiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

3

Introduction


Introduction

What is an Universal Agent application?An Universal Agent application defines the data you want to manage to OMEGAMON XE. Each Universal Agent application consists of a data definition specification, or metafile, for one or more groups of data attributes.

From the standpoint of OMEGAMON XE, an application is anything you define it to be in your metafile. For example, you could create a metafile with an application name of HOSTRESOURCES. This metafile could have three attribute groups, representing network, system, and applications resources.

Note that you do not need to create applications if you are using the SNMP Data Provider. Candle creates them for you from standard Management Information Bases (MIBs) or from any MIB that you supply.

How do I create an Universal Agent application?You create an application by constructing a metafile, which specifies:

� the name of the application

� the name of each of the groups of attributes that comprise the application

� the source or sources of the data in each group

� the names and characteristics of the attributes

� (optionally) help for the application, each attribute group, and each attribute

The key to creating useful Universal Agent applications is placing related attributes into groups and placing related groups of attributes into individual Universal Agent applications.


Constructing a Data Definition Metafile


OverviewA metafile is a plain text file. It contains the following control statements in the order shown (if present):

� SNMP—(For SNMP Data Providers only) Introduces the data definition for Candle-provided SNMP MIB applications. (SNMP TEXT introduces the data definition for user-defined SNMP applications.)

� WBEM—(For WBEM Data Providers only) Introduces the data definition for Candle-provided or user-defined WBEM applications

� APPL—Specifies the name to be used by OMEGAMON XE for the application

� NAME—Defines the name of an attribute group, the type of data being collected, and the period for which the data is valid

� INTERNAL—Provides for data redirection between attribute groups as a way to perform additional processing

� SOURCE—Defines the location of the data being collected� RECORDSET —(For File Data Providers only) Defines the set of records

from which the Data Provider is to extract data� CONFIRM—(For Socket Data Providers only) Specifies the requirements

for data acknowledgment� SQL—(For ODBC Data Providers only) Defines the Select statement or

stored procedure to be used for collecting relational data� SUMMARY—Defines the requirements for gathering the frequency of data

input during monitoring� ATTRIBUTES—Introduces the attribute definitions and specifies the

attribute delimiters in the data string You can use any text editor to create a metafile. Appendix A, “Data Definition Control Statements” on page 149 contains the definitions and syntax of the command statements. Figure 5 on page 46 illustrates a small metafile named TCPIOQ.MDL, which defines a socket application named UXnet.



Figure 4. Creating a data definition metafile

Figure 5. Metafile TCPIOQ.MDL

Naming metafilesThere are no restrictions on the names of metafiles. You can use any name supported by the platform on which the file resides. It is good practice to give the file the same name as the application.

//APPL

//NAME

//SOURCE

//ATTRIBUTES

.

You create a data definition metafile to define the attributes you want to monitor. In the metafile, you name the application and attribute data groups to which the attributes belong. You also identify the sources of the data, specify what type of data is being monitored, and define the help text for your application, attribute groups, and attributes.

TCPIOQ.MDL

//APPL UXnet @sample application for socket DP//NAME TCPioQ E @attribute group for sample DP

application//SOURCE SOCK UNIX1//SOURCE SOCK UNIX2//ATTRIBUTESLocalApplAddress D 24 @address of local applicationTargetApplAddress D 24 @address of target applicationSendQueueSize C 65000 @TCP/IP send queue sizeRecvQueueSize C 65000 @TCP/IP receive queue size



Creating help for applications, attribute groups, and attributesIn your metafile you can define help for the application, each of its attribute groups, and each attribute in a group. The help you define for each attribute group displays in the Situation editor when you select an Attribute group. The help you define for each attribute displays as you mouseover the table column headings that represent each attribute.

For the SNMP Data Provider, help is created automatically from the descriptions of attributes in the MIB. See Figure 5 on page 46 for examples of help definitions in a metafile and “Data Definition Control Statements” on page 149 for information about the @helptext parameter.

Storing metafilesBy default, the Universal Agent looks for metafiles in the directory indicated in Table 5.

You can change the location using the variable KUMP_META_PATH. For example, you may want to store all your metafiles in one directory. The environment variable KUMP_META_PATH enables you to redirect the metafile search from the default directory to a specified location. The local KUMP_META_PATH specification does not override the KUMP_META_PATH specification for the metafile server (see “Creating a Metafile Server” on page 55).

You can override the KUMP_META_PATH definition by using a console command and the fully qualified metafile name. For example, if you use the console command VALIDATE to validate a metafile (see next section), you can enter:

kumpcon validate c:\ua\test\my_metafile.mdl

If you have many metafiles, you may want to create subdirectories in the directory designated by KUMP_META_PATH. When you use a console

Table 5. Default Location of Metafiles

Platform Location

Windows candle\cma\metafiles

UNIX $CANDLEHOME/$ARCH/um/metafiles



command that refers to a metafile in one of the subdirectories, you can use a relative path when you specify the metafile name. For example:

kumpcon validate .\subdirectory_name\mymetafile.mdl


Validating Data Definitions


OverviewCandle supports a console command VALIDATE, which invokes the same data validation subroutine that the Universal Agent uses at runtime. It is useful to run the validation program against a newly developed or modified metafile so that you can quickly identify and correct syntactical and specification errors before you activate it.

VALIDATE reads the metafile and produces detailed validation messages. It also creates a data specification report showing the exact application definition in effect. The report has the same file name as the metafile, with the extension rpt. For example, if you run the program on the metafile tcpioq.mdl,a file named tcpioq.rpt is created.

Running the validation programTo run the metafile validation program, from any console interface enter:

kumpcon validate metafile_name

You can enter the fully qualified metafile name to either override the KUMP_META_PATH definition or identify a metafile located in a private directory:

kumpcon validate c:\ua\test\my_metafile.mdl

If you have created subdirectories in the directory specified by KUMP_META_PATH, you can use a relative path to refer to the metafile:

kumpcon validate .\subdirectory_name\metafile_name

Sample validation ouputFigure 6 on page 50 shows the validation output for an application named UXnet, defined in the metafile named TCPIOQ.MDL.



Figure 6. Example of Validation Output TCPIOQ.RPT

Application Name: UXnet; Definition Metafile Name: E:\Candle\CMA\KUM\MDL\TCPIOQ.MDLAttribute Group: TCPioQType: Event data Total number of SOURCEs: 2SOURCE is SOCKET UNIX1Total Attributes: 4Attribute delimiter is Space CharacterLocalApplAddress Display Type Size 24TargetApplAddress Display Type Size 24SendQueueSize Counter Type Size 4RecvQueueSize Counter Type Size 2SOURCE is SOCKET UNIX2Total Attributes: 4Attribute delimiter is Space CharacterLocalApplAddress Display Type Size 24TargetApplAddress Display Type Size 24SendQueueSize Counter Type Size 4RecvQueueSize Counter Type Size 4Total Attribute Groups: 1


Activating Metafiles


OverviewTo manage application data correctly, the Universal Agent must activate the appropriate metafiles. Metafiles can be activated in any of three ways:

� dynamically via a console command

� through a configuration file

� automatically at startup

In deciding which method to use to activate a metafile, you should attempt to strike a balance between flexibility, ease of use, maintainability, and the reduction of errors caused by implicit actions and defaults.

Activating metafiles with console commandsYou can activate metafiles dynamically using the IMPORT and REFRESH commands. (Refer to “Console Commands” on page 209 for a discussion of the Universal Agent command line interface.) You would use this method if you have created a new metafile and want to import it, or you have modified an active metafile and you want to refresh it, without having to restart the Universal Agent.



Figure 7. Activating Metafiles

Activating metafiles with a configuration fileKUMPCNFG is a plain text file which contains the names of the metafiles that an Universal Agent should load at start-up time. You would use this method when you want the Universal Agent to automatically load specific metafiles at start-up time.

Guidelines for updating configuration files

Observe the following guidelines when updating a configuration file to include a new metafile:

� The name of the configuration file must be KUMPCNFG. On systems where files are case-sensitive, the name must be specified in all uppercase characters.

� One or more metafile names can appear in a single file record, separated by a space or you can specify one metafile per file record.

� Except when strictly necessary, use only unqualified metafile names in the configuration file.

� Any file record that starts with an asterisk (*) is treated as a comment and ignored. In the example shown in Figure 8 on page 53, only the metafiles mymeta, appl1.mdl, appl2, and CustInq.txt are loaded by the Universal Agent.

KUMPCNFG Candlehome/... IMPORT Command

At start up, the Universal Agent checks to see if any metafiles are specified in a configuration file, KUMPCNFG. If there is no configuration file, the Universal Agent loads the appropriate metafiles from the metafiles directory. You can also use the IMPORT and REFRESH console commands to import new and revised definitions at any time.

//APPL//NAME//SOURCE//ATTRIBUTES

TCPIOQ.MDL

UniversalAgent



Location of the configuration file

The Universal Agent uses the value specified for the variable KUMP_INIT_CONFIG_PATH as the location of its configuration file. If no value is specified for KUMP_INIT_CONFIG_PATH, the Universal Agent uses its default working directory or the directory specified by KUM_WORK_PATH. (See “Setting the working directory” on page 236 for a discussion of the default working directory and KUM_WORK_PATH.) The path specification may be case-sensitive on some operating systems.

Figure 8. Example of a Data Provider Configuration File

Sharing configuration files

A KUMPCNFG file can be shared by multiple Universal Agent/Data Provider threads. In other words, the same KUMPCNFG file could contain Socket DP metafiles, File DP metafiles, SNMP DP metafiles, ODBC DP metafiles and WBEM DP metafiles.

Every Data Provider loads all the metafiles specified in KUMPCNFG, but each Data Provider only begins monitoring metafiles belonging to its defined data type and ignores the others. For example, a File Data Provider does not start to monitor in-bound socket connections, and an API Server Data Provider does not spawn threads for monitoring log files. Similarly, the SNMP Data Provider only loads SNMP MIB metafiles, and non-SNMP Data Providers only load non-SNMP metafiles. Consequently, aside from the extra storage allocated to each Data Provider for the internal data definition control blocks, there is no danger of management conflicts among Data Providers. Of course, if you start the API, Socket, and File Set (ASFS) Data Provider, all applicable monitoring for all three DP types starts at once.

mymeta appl1.mdl appl2CustInq.txt*Payroll



Activating metafiles automaticallyAn alternative way to activate metafiles is to place them in the working directory (see “Setting the working directory” on page 236). At startup, if the Universal Agent finds no configuration file, it automatically loads any files of the following types that it finds in its working directory:

� files with the standard default file extension .MDL

� files without any file extension whose names do not start with KUM

� files without any file extension that are not CCC attribute files or catalogs

You would use this method if, at startup time, you want to load every metafile you have created in your metafiles directory. But if a KUMPCNFG file exists, even if it contains no records or valid entries for any metafiles, automatic loading of metafiles is disabled.

You can override the default working directory by using the variable KUMP_META_PATH to specify an alternative directory. When a KUMP_META_PATH is specified, the Universal Agent loads all files in the specified directory. Candle recommends that you organize your metafiles in a dedicated directory and use the environment variable KUMP_META_PATH to point to that directory.


Creating a Metafile Server


OverviewIn an enterprise, an application may be supported by several Universal Agents at various locations. To ensure consistent definitions through the enterprise and to reduce the complexity of managing and maintaining the Universal Agents, you may want to store metafiles in a single location. It is also a good practice to regularly back up your metafiles since they represent an important part of your enterprise management system.

The centralized metafile server facility enables you to designate one or more Universal Agents as a metafile server. Client Universal Agents can retrieve the metafiles they require from the designated server at run time rather than maintaining local copies.

For example, the Engineering department might designate an Universal Agent running on machine ENG1 as the metafile server. The Finance department selects machine FIN4 as the metafile server. All the Universal Agents in the Engineering department download required metafiles from the Universal Agent on ENG1, while all the Universal Agents in the Finance department retrieve necessary metafiles from the Universal Agent on FIN4. The rest of the Universal Agents in the company may be set up to use the metafile server running on MIS9.

Designating a metafile serverYou use the environment variable KUMP_META_SERVER to specify the name of the host of the Universal Agent that you want to use as the server:

KUMP_META_SERVER=hostname

The presence of the environment variable indicates to the Universal Agent that it should use a centralized metafile server. If this environment variable is not set, the Universal Agent operates in standalone mode and looks for its required metafiles locally. If the host name specified by KUMP_META_SERVER cannot be resolved to a TCP/IP address, the metafile server feature is disabled and the Data Provider loads metafiles from the local metafile location.



Storing server metafiles The metafiles for the server must be stored in the Universal Agent default working directory or in the location identified by the KUMP_META_PATH or KUM_WORK_PATH environment variables. (See the discussion earlier in “Activating Metafiles” on page 51 for a discussion of KUMP_META_PATH and “Setting the working directory” on page 236 for a discussion of KUM_WORK_PATH.)

Determining server and client roles on the same hostWhen an Universal Agent starts up and discovers that KUMP_META_SERVER is set to the name of its own host, it makes the following determination:

� If it is the first Universal Agent initialized on this machine, it immediately takes the role of metafile server.

� If it is not the first Universal Agent initialized on this machine, it assumes that the metafile server has already started and it takes the role of metafile client, as would any Universal Agent started elsewhere in the enterprise.

Synchronization of metafile server and clientIf an Universal Agent determines at startup that KUMP_META_SERVER is not set to the name of its own host, it assumes the role of client and immediately attempts to establish a connection to the designated metafile server.

If the connection is successful, the Universal Agent sets up the necessary internal management structure and continues startup processing. If the connection is unsuccessful, either because of network problems or because the Universal Agent metafile server has not started, it schedules periodic connection retries and completes initialization.

Communication between metafile client and server may be disrupted during normal operation for a variety of system or network reasons. If communication is disrupted, the client automatically falls back to standalone mode and schedules periodic retries until the connection to the server can be re-established. Log messages are issued that clearly identify the status of the metafile service. You can monitor the messages in the DPLOG workspaces (see “UAGENT Workspaces” on page 129).



Overriding the central metafile definitionOn occasion you may need to override a data definition metafile, perhaps while you are testing an application upgrade or editing the specifications. You can accomplish this easily by making the new application metafile available locally to the Universal Agent. The Universal Agent always checks for the existence of a local copy of the required metafile before attempting to download it from the metafile server.

Versioning of Metafiles



OverviewVersioning of metafiles makes it possible for you to identify the level of your metafile. It also allows you to run different versions of a metafile on different machines. For example, you might want to install a new version of an operating system on your test machine and monitor data that the older version of the operating system does not provide. You can modify your metafile to monitor the new system statistics and run the new version on the test machine while still using the older version on your other machines.

Incrementing version and modification numbersMetafiles are assigned both version and modification numbers. When you first import a metafile into the Universal Agent, it is assigned a version number of 0 and a modification number of 0. Subsequently, each time you change the metafile and refresh it on the Universal Agent, either the version number (major changes) or the modification number (minor changes) is incremented by one, depending upon the type of change you make.

Reversioning of managed systems, workspaces, and attribute groupsThe Universal Agent appends the version number of the metafile to the names of managed systems, managed system list, customer workspaces, and attribute groups that they define. When the version number of a metafile changes, the managed systems, managed system lists, workspaces, and attribute groups based on the previous version number go offline and new ones with the new version number come online (see Table 6 on 59 and “Monitoring Applications” on page 121).

You cannot simply restart situations distributed to a previous version of a managed system. This is why version number changes are considered major changes. You must create new situations or modify the old ones to use the new attribute group names, then distribute the situations to the new versions of the managed systems or the managed system list. You also need to update any existing policies to reference the new version number. For this reason, Candle recommends that you attempt to make changes that affect only modification number (see below), so that you do not need to makes changes



to your existing situations, managed objects, and automation policies.This is why modifications are considered minor changes.

Changes that do not affect modification or version numberYou can make the following changes without changing the modification or version number of the metafile:

� the TTL value

� the location or source of the data (SOURCE statement)

� the data type from P, S, or K to any of P, S, or K

� the delimiter specified in the ATTRIBUTE statement

� a change to the RECORDSET statement

� a change to the CONFIRM statement

� a change to an attribute’s FILTER parameters

� a change to the SQL statement

Changes that affect modification number (minor changes)The following changes cause the modification number to be incremented:

� adding a new attribute to the end of the attribute list for an attribute group

� adding a new attribute group at the end of the metafile

� adding, removing, or changing help text� atomizing an existing attribute

Table 6. Example of Version Numbering

Name Version 1 Version 2

managed system ENG1:UL300 ENG1:UL301

managed system list *CUSTOM_UL300 *CUSTOM_UL301

customer workspace UL300 UL301

attribute group SYSLOG00 SYSLOG01



Changes that affect version number (major changes)The following changes cause the version number to be incremented:

� renaming an existing attribute

� changing the type of an attribute

� changing the length of an attribute

� changing the name of an attribute group

� adding a new attribute anywhere other than the end of a list of existing attributes

� changing the order of attributes

� changing a data type from E to P, S, or K

� changing a data type from P, S, or K to E

� changing the name of an existing attribute group

� adding a new attribute group anywhere other than the end of a metafile

Resetting version numbersCandle provides two cleanup scripts that allow you to reset the version number of your metafiles to 0.

� um_cleanup.bat (for Windows)

� um_cleanup for (UNIX)

These scripts do not affect the actual metafiles: the next time the metafiles are imported or activated, their applications will come back online, but all versions will be at 0.

Before you run one of these scripts, you must manually delete the existing Universal Agent managed systems from the CMW.

After you run the cleanup script, you must recycle the CMS and restart the Universal Agent to implement the new version 0.



Manually deleting managed systems (CMW only)

To delete the existing managed systems:

1. Stop the Universal Agent so all its managed systems go offline.

2. From the CMW Main window, open the Managed System folder.

3. Highlight all the Universal Agent managed systems, then from the Edit pull-down menu select Remove Managed System.

Note: You can delete managed systems manually only within CMW. CNP will reflect the changes you make.

Running the cleanup program

You must run the cleanup script four times: once to clean out the Universal Agent work files from the working directory; a second time to clean out the CMS catalog and attribute files; a third time to clean up the CMW attribute files, and a fourth time to remove the CNPS ODI files.

To run the cleanup script, enter the following in a command window on the appropriate machine:

um_cleanup candle CCC_component [work_directory]

where:

candle is the directory where theUniversal Agent is installed

ccc_component is one of four values: UA CMSCMWCNPS

Note: each of these four values should be capitalized (e.g. UA, not Ua or ua).

work_directory is the work directory, if not the default candle\cma\work. This optional parameter applies only if the second argument is UA.



About Data Providers 63

About Data Providers

OverviewThis chapter discusses the characteristics of Data Providers you need to take into account when you create metafiles to define Universal Agent applications or develop programs to send data to the Universal Agent.

Chapter contentsAbout Data Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64File Data Provider. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69API Server Data Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Socket Data Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Post Data Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89HTTP Data Provider. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96SNMP Data Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104WBEM Data Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105ODBC Data Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

4




OverviewData Providers are the data interfaces of the Universal Agent. They collect data from monitored files or from client programs and load and validate data definition metafiles, then pass the information to the Universal Agent. A given Data Provider may support multiple Universal Agent applications concurrently.

Figure 9 illustrates the relationship between Data Providers and data sources, metafiles, and an Universal Agent.

Types of Data ProvidersThe Universal Agent supports a variety of Data Providers: File, API Server, Socket, Post, HTTP, SNMP, WBEM, and ODBC. This chapter describes all but one of these Data Providers and their characteristics. The SNMP Data Provider is discussed in the Universal Agent SNMP Data Provider User’s Guide.

Figure 9. Relationship between Data Sources, Metafiles, and Data Providers

//APPLB

//NAME

//SOURCE

//ATTRIBUTES

Data Source

B

Data Source

A

Data Source

C

//APPLA

//NAME

//SOURCE

//ATTRIBUTES

Data ProviderUniversal

Agent



Environment variablesRefer to Appendix D, “Environment Variables” on page 235, for a discussion of how to specify the environment variables discussed in this chapter.

Running Multiple Instances of a Data Provider

Overview

You can run multiple instances of a particular Data Provider type on a single system by configuring multiple instances of Universal Agent. To distinguish the Data Providers, the Universal Agent prefixes an instance name parameter to the managed system name.

Advantages

Running multiple Data Providers of the same type on the same system offers a variety of advantages, including the ability...

� to run a test and production Universal Agent on the same machine. The test Universal Agent could be used to verify new maintenance, as well as environment variable and metafile changes before migrating the changes to the production Universal Agent.

� to create specialized Universal Agents for logical grouping purposes (for example, to monitor discrete portions of your network).

� to balance workloads, if the volume of data being collected is overloading a single Universal Agent.

� to connect multiple Universal Agents to different CMS’s.

Instance names

For each Data Provider that comes online, a primary (or “non-instance”) copy of Universal Agent assigns a managed system name of the form: hostnameDPTYPEdp:UAGENT00 that comes on-line for each Universal Agent Data Provider that is started. In order to run multiple instances of the same Data Provider type on the same machine, the resulting Universal Agent-generated managed system name uses an instance name parameter as a prefix to guarantee uniqueness.



The naming conventions include:

The instance name is suffixed to all configuration and run-time files in the Universal Agent work directory (for example, KUMPCNFG_TEST, KUMATBLS_INST1 or KUMPURLS_PROD). KUMPCNFG should be suffixed by the instance name.

The configuration and run-time files for the primary Universal Agent remain as before, without a suffix. The primary Universal Agent does not have an instance name prefix in its managed system names, nor does it have an instance name suffix in its configuration files.

There can only be one primary copy of Universal Agent configured and active at a time. However, multiple additional copies—each with a unique instance name—can run concurrently with or without the primary Universal Agent active.

Running multiple Data Providers of the same type

To create a new non-primary instance of Universal Agent:

1. Right-click Candle Universal Agent in the Manage Candle Services dialog.

2. Select Create Instance.The Create Instance panel displays.

3. Enter a short instance name (in the three-to-six character range, whenever possible).

Multiple instance configuration on UNIX

For information on configuring multiple instances of Universal Agent on UNIX, see Installing Candle Products on UNIX.

Heartbeat Probe instname:hostname:UA

Data Provider instname_hostnameDPTYPEdp:UAGENT00

Application instname_hostname:applicationVV



A note on truncation

Manage Candle Services offers a context menu-driven dialog where you can enter a instance name of 1-20 characters. However, Universal Agent limits an entire managed system name (instance prefix + hostname + application name + version suffix) to 32 characters. To preserve the integrity of the managed system name, the instance name prefix gets truncated from the left. For example, the truncation of the instance name ABCDEFGHIJKLMNOP would result in a managed system name of DEFGHIJKLMNOP_hostname:appnameVV. Therefore, it is highly recommended that you choose short instance names to avoid managed system name truncation.

Sending a console command to an alternate instance

To make a program or console connection to an alternate Universal Agent instance, you must specify the KUMP_DPCONSOLE_PORT environment variable. In order to target the correct Universal Agent, use the UAGENT DPLOG report. It provides the port numbers of the Socket and API listeners, and the Console port (for kumpcon commands). If the Data Provider Console port number is no longer visible as a result of the amount of messages being written to the DPLOG, the number can also be found by searching for DP CONSOLE PORT in the kumras1_instancename.log.

By default, the target Universal Agent will be the primary and use console port 7700. To prevent you from issuing commands against the wrong Universal Agent when a non-primary Universal Agent is being accessed via the console interface, the prompt for the target Data Provider displays the Instance Name next to each Data Provider.

The Take Action interface will not have this ambiguity problem. When distributing an action such as URL Add or Manage Start, the list of available managed system names includes the Instance Name prefix.

Running multiple instances of SNMP Data Providers

Even with multiple instance support, you cannot run two full-function SNMP Data Providers on the same system. Only one process can acquire the reserved SNMP trap listening port 162. This is an SNMP restriction, not a Universal Agent restriction. The first Universal Agent that activates the SNMP Data Provider acquires port 162 (assuming there is not another non-Universal Agent SNMP Manager or trap listener already active). Any subsequent



Universal Agent that activates the SNMP Data Provider will fail to open the trap listening port, but will still be able to perform other SNMP Data Provider functions, such as collecting MIB data. The failure to acquire the trap listening port is logged in the UA RAS1 log and in the SNMP Data Provider UAGENT DPLOG report.

Note that if you're using an alternate instance of Universal Agent as your SNMP trap receiver, you will need to copy or rename the trapcnfg file in the work directory so that it has the instance name suffix. For example, if your alternate instance is called "SNMP", then copy trapcnfg to trapcnfg_SNMP.

Conflicts between duplicate applications

Do not run the exact same application in two different Universal Agents. Through the use of suffixed configuration files, it is relatively easy to maintain a different set of Universal Agent applications for the multiple Universal Agents you run. However, nothing prevents you from activating the exact same application in two different Universal Agents. For example, you could monitor the same log file, the same URLs, etc. In some cases, this will be merely wasteful and inefficient. In other cases, duplicate monitoring could cause problems, particularly if you run different versions of the same-named application.


File Data Provider

File Data Provider

OverviewThe File Data Provider monitors data residing in a sequential text file. It offers the simplest, most direct way of using the Universal Agent to monitor data with OMEGAMON XE.

Location of Data ProviderFile Data Providers must reside on the same host as the files they monitor, or the files must appear to the Data Provider to be residing on the local machine. The operating system may remove the “remoteness” of a file from the running Data Provider by implementing a network file system or mapping a remote machine's resource to a local device.

Note that if the File Data Provider is monitoring a file on a remote system through the use of logical drive mapping, the userid/account associated with UA must have sufficient authority to open and read the file on the remote system. In some cases this may require, for example, reconfiguring the UA Windows service with something other than the default "LocalSystem" account. The Windows Control Panel Services applet allows you to configure a different account for a particular service. In this scenario, you could change UA's account from "LocalSystem" to an Administrator ID that is authorized on your LAN to access files on the remote system.

File sampling frequencyThe File Data Provider samples a monitored file periodically for new records. The sampling frequency is determined as follows:

� For event type data, the File Data Provider samples data every 15 seconds or at the rate (in seconds) specified by the KUMP_DP_EVENT environment variable.

� For polled, sampled, and keyed data, the sampling frequency is derived from the time-to-live (TTL) value specified in the data definition metafile, divided by the sample factor. The default TTL is 300 seconds and the default sample factor is 5. You can control the sampling frequency for

File Data Provider


polled and sampled data using the KUMP_DP_SAMPLE_FACTOR environment variable and the TTL. If no override is defined, the File Data Provider samples data every 60 seconds (300 divided by 5).

The maximum default sample frequency is 5 minutes (300 seconds). You can override this default using the KUMP_DP_SAMPLE_FACTOR variable. For example, if a metafile specifies the TTL as 3600 seconds, the sampling frequency is 3600 divided by 5, or 720 seconds. The sample frequency actually enforced is 300, the default maximum. However, if you specify the KUMP_DP_SAMPLE_FACTOR as 10, the sample frequency is 360. The maximum override takes place only if no user specification is defined.

The File Data Provider also enforces a minimum sampling frequency. The minimum default sampling frequency of 30 seconds is substituted if the TTL divided by the sampling factor results in a sampling frequency of less than 1 second. For example, in the case of a TTL equal to 180 and a KUMP_DP_SAMPLE_FACTOR equal to 360, the file is actually sampled every 30 seconds. If the specified frequency is overridden, a metafile definition validation warning message is issued which identifies the minimum sample interval in effect.

Special File Extracting RoutinesMany operating systems, networks, and applications maintain useful information in files suitable for monitoring by a File Data Provider. However, if your data is not already in a sequential file, you can create an extraction program to export the data from the native source to a sequential file so the File Data Provider has access to it.

For example, the Windows Event Log cannot be read easily as a sequential file. However, you can develop an extractor program using the Win32 Event Log APIs to access Event Log records. The program would obtain the records through the appropriate APIs, then write the records to a sequential file monitored by the File Data Provider.

Multiple Record InputThe File Data Provider supports multiple record input. For example, the data for the first two attributes in an attribute group may reside in one file record, the data for the third and fourth attributes in a second record, and the data for


File Data Provider

a fifth attribute in a third record. Or the data in five records can be concatenated and treated as a single attribute for the purposes of monitoring.

You can define record sets consisting of a fixed number of records, or of a variable number of records identified by a delimiter pattern. See “RECORDSET Statement” on page 168 for details.

Dynamic File Name SupportThe //SOURCE statement (see “SOURCE Statement” on page 162) defines a fixed monitoring application file. An application program often creates its output file based on specific criteria such as day, week, or month naming conventions or on files reaching their defined size and rolling over to a new file. In cases like these, you can specify a monitoring file name pattern in the //SOURCE statement as

//SOURCE FILE file-name-pattern-spec

instead of the actual file name. The File Data Provider inspects all files in the designated path location, seeking files that match the defined pattern. The File Data Provider always manages the most current matching file, based on whichever matching file has the highest number or date/time value. The appropriate file is determined by file name, instead of by file creation or modification date. The # sign defines the position of the numeric character within the file name.

Note: The file name and pattern may be case-sensitive on a case-sensitive operating platform.

The following examples illustrate file name pattern specification:

{########}.abc Matches numeric file names of length 8 and the file extension .abc, such as 10252002.abc or 10262002.abc. File 10262002.abc is monitored because 10262002 is greater than 10252002.

{########}.* Matches numeric file names of length 8 and ignores the file extension. Examples include 20021025.log, 20021101.log, and 10252002.abc. File 20021101.log is monitored because 20021101 is the largest number.

File Data Provider


Follow these guidelines to establish file name patterns:

� Use an asterisk (*) to ignore file extensions. . This means that only the first part of the file name is checked and the second part, which must be present, will be ignored.

� If a specific file extension is defined, then only files with the same extension are considered.

� Use braces {} to enclose the numeric part of the file name pattern.

� Use a pound sign to indicate each numeric element of a file name.

� Use a question mark to exclude each element of the naming convention that does not serve as search criteria in determining the appropriate file name.

� The total number of pound signs and question marks enclosed in braces is significant. It must match the portion of file name exactly. For example, the pattern AA{####} instructs Universal Agent to look for file AA0001, AA0002, AA0003, etc. File names, such as AA001 or AA00001, are not considered.

� The exact file name pattern, the constant and the numeric parts, must match the file name exactly. For example, the pattern AA{###} instructs Universal Agent to check file AA101, AA102, AA204, etc. File names, such as XAA101, AA222X and AA55555, are not considered.

{######??}.abc Matches numeric file names of length 8 and ignores the last two positions in the file name. Examples include 02110100.abc, 02110101.abc, and 02110202.abc. File 02110202.abc is monitored.

IN{######}.log Matches file names starting with IN followed by six numerals and the file extension .log. Examples include IN021001.log, IN021002.log, and IN021004.log. File IN021004.log is monitored.

PS{###}FTP.txt Matches file names starting with PS followed by three numerals, followed by FTP, and the extension .txt. Examples include PS001FTP.txt, PS005FTP.txt, and PS010FTP.txt. File PS010FTP.txt is monitored.


File Data Provider

To precisely specify a file name consisting of date components (year, month, and day), use the capital letters Y, M, and D. This naming convention enables Universal Agent to determine the candidate file without errors. Y, M, and D must appear within braces; otherwise they are treated as literals.

Examples include:

The File Data Provider periodically checks for new files that match the defined file pattern in the target path location. When a newer file that matches the pattern is detected, the File Data Provider automatically switches application monitoring to the new file. The File Data Provider re-examines the possible monitoring file when the:

� initial File Data Provider starts up.

� currently managed file no longer exists (possibly renamed or deleted).

� existing file contents have changed (possibly rewritten).

� check interval has expired. The default interval is 10 minutes. It can be changed to a longer or shorter interval value by specifying the environment variable

KUMP_DP_FILE_SWITCH_CHECK_INTERVAL=seconds

The File Data Provider issues a DPLOG message notifying you that the active monitored file has switched from the current file to the new file.

Pre-allocated File SpaceAn application program may pre-allocate a file with a specific size and manage the file records in this pre-allocated file space based on a special algorithm. The Microsoft Internet Information Server log is an example of this type of file.

{YYYYMMDD}.log Specifies candidate files with names such as 20020930.log or 20021015.log.

{MMDDYY}.log Specifies files with names such as 101102.log or 110102.log.

{DDMMYYYY}.log Specifies possible files with names such as 01092002.log. or 15082002.log.

MY{YYDDD}.log Specifies files with names such as MY02202.log, MY00010.log or MY02350.log.

File Data Provider


The common technique of tailing a file by examining the end-of-file file record pointer location for newly added records becomes ineffective because the end-of-file pointer location does not change. The file size remains unchanged until the application program allocates the next file space increment. Using the common file I/O function to read a file record also proves problematic because it always returns a valid file record pointer until reaching the pre-allocated file size.

The keyword tailbyrecord specified on the //SOURCE statement (see “SOURCE Statement” on page 162)

//SOURCE FILE file-name tailbyrecord

instructs the File Data Provider to use a special method in handling the managed file. The File Data Provider tracks physical file records in a pre-allocated file and examines the record contents for validity. In this case, the File Data Provider is monitoring a file’s logical EOF instead of its physical EOF for newly added file records.

Note: The tailbyrecord keyword can be specified for all files including “non” pre-allocated file space files. However, this is less efficient than the standard approach of simply monitoring the file location pointers.


API Server Data Provider


OverviewThe Application Programming Interface Server (APIS) Data Provider supports API client functions. The Data Provider and the Universal Agent APIs enable you to easily develop scripts and C/C++ programs that send data to the Universal Agent. They also support a command line interface which implements a subset of the API functions.

See Universal Agent API/Command Programming Reference Guide for complete information on the Universal Agent APIs and supported commands.

Invoking the APIsThe Universal Agent APIs can be invoked in the following ways:

� program function calls

You can develop or modify C/C++ programs that invoke the API functions directly as subroutines.

� script file calls

You can develop or modify script or batch files that call the API command line interface programs.

� manual commands

You can enter API commands directly from a system console. This method is particularly useful because it allows you to send data or create events whenever the need arises. For example, Customer Support might receive an urgent call from a critical customer site. The customer service representative could enter an API command with accompanying text. The command would cause a situation to become true and the on-duty action team to be notified.



The API client packageThe Data Provider API client package consists of:

� a library containing the binary executables of the API functions

� a C header file

� a set of command line interface programs

The client package was developed in standard C language and requires only a common C runtime environment and TCP/IP with a socket interface. It does not create added programming complexity or dependency for the calling program.

Figure 10. Implementation of API Server Data Provider

API ServerData Provider

Transport Network

Data Source

APIRuntimeDynamicLibrary

APIConsole Commands



Data Source



Calling programsC/C++ calling programs instrumented with the Universal Agent APIs rely upon API services provided by the runtime dynamic library. The programs may reside locally with the API Server Data Provider or they may execute at a remote location.

The Universal Agent API/Command Programming Reference Guide contains the minimum program requirements and procedures for implementing the API functions and provides descriptions, syntax, and return status codes for the API calls, as well as a sample API program.

API console commandsThe API console commands are console interface programs that call the API functions. They use the same API runtime dynamic library as the API functions, so they can be invoked either from the console of the local system or from the console of a remote machine.

The Universal Agent API/Command Programming Reference Guide contains descriptions of the console commands.

Specifying the host of the API Server Data ProviderThe default mode of the API client assumes that the APIS Data Provider resides on the same system. If the APIS Data Provider is running on a remote system, you must set the environment variable KUMP_API_DPAPI_HOST to the host name of the APIS Data Provider.

Specifying the listening port for the API Server Data ProviderThe default listening port for the APIS Data Provider is 7600. If this port is already in use, or you would prefer that a different port be used, you can set the environment variable KUMP_API_DPAPI_PORT to the preferred port. If you set this variable for the APIS Data Provider, or if this variable was automatically reassigned as a result of starting an alternate instance of UA, you must set the same variable on the API client side. You can check the APIS Data Provider UAGENT DPLOG report to verify the correct listening port number.

Socket Data Provider



OverviewThe Socket Data Provider enables the Universal Agent to manage data on platforms where it cannot be installed by implementing program-to-program communication using the socket transport paradigm. Figure 11 illustrates the role of Socket Data Provider.

Figure 11. Socket Data Provider

Data Source

Data Source

Data Source

Data Source


UniversalAgent

TCP/IP

Network

Open System A

Open System B

Open System C

Open System D



Contacting the Socket Data ProviderA sending program, also referred to as a socket client program, contacts the Socket Data Provider in either of two ways:

� opening a TCP socket and connecting it to the host of the Socket Data Provider, or

� opening a UDP socket and sending data to the host address of the Socket Data Provider.

Note that most scripting languages, such as REXX and Perl, offer socket APIs for collecting and sending data, so the sending program can be implemented in a wide variety of ways, not just in a high-level language like C++ or Java.

Changing the default listening portBy default, the Socket Data Provider listens on port 7500. If socket port 7500 is unavailable or you would prefer that the Data Provider use another port or if this variable was automatically reassigned as a result of starting an alternate instance of UA, set the environment variable KUMP_DP_PORT to the correct listening port.

You can check the Socket Data Provider’s UAGENT DPLOG report after the Socket Data Provider has started to verify that the status message clearly identifies the appropriate listening port number for TCP, UDP, or both.

Host name and TCP/IP address translationHost name and TCP/IP address translation are critical to the operation of the Socket Data Provider. The machine on which the Socket Data Provider resides must be properly configured to use network name service for resolving host names and translating TCP/IP network addresses. If the host name specified in the SOURCE statement of a data definition metafile cannot be resolved, the SOURCE statement is ignored (refer to “SOURCE Statement” on page 162).

Multiple host machinesRunning a Socket Data Provider on a multiple host machine (a machine with more than one network interface) requires special consideration. Generally, a system resolves its own host name to the first installed network interface. If



you prefer that Data Provider traffic use another interface, you can set the environment variable KUMP_DP_HOSTNAME to the preferred host name.

Associating data sources with metafilesThe Socket Data Provider associates a sending program with the appropriate metafile using the socket address of the program. The association is accomplished in one of two ways:

� metafile SOURCE statement� explicit metafile specificationNote that the managed system for the socket application does not come on-line to CCC until the socket client program has connected to the Socket Data Provider and the metafile association has occurred.

Association by metafile SOURCE statement

You can specify one or more SOURCE statements for each attribute group (NAME statement) in a metafile. For a Socket Data Provider, the location field of the SOURCE statement specifies the origin of the sending program in the form of an Internet dot decimal address or a resolvable host name, followed optionally by a port number. For example, FIN1[4500] identifies data originating from host FIN1 at port 4500.

If the host name is specified for the location but it cannot be resolved to an address, the SOURCE statement is ignored. If the port number is omitted, data originating from any port on that host is acceptable. For example, specifying only the address 198.210.37.147 permits a program bound to any port on host 198.210.37.147 to connect to a Data Provider.

In general, the port number is needed if a Data Provider manages multiple programs from the same host supplying data for multiple attribute groups. For example, in the following example

//APPL NCARPT//NAME Overview P 900//SOURCE SOCK JOHN//SOURCE SOCK BOB//ATTRIBUTES ‘;'

.

.

.



the Universal Agent application NCARPT has only one attribute group and it is the only active application supplying data to a Socket Data Provider. A socket program from either host JOHN or host BOB can import data to the Socket Data Provider. There is no need to specify port numbers, since no ambiguity can arise.

However, if the application NCARPT includes more than one attribute group, as in the following example, port definitions are necessary.

//APPL NCARPT//NAME Overview P 900//SOURCE SOCK JOHN//SOURCE SOCK BOB //ATTRIBUTES ‘;'

.

.

.//NAME RedEvent E//SOURCE SOCK JOHN[1001]//SOURCE SOCK BOB[2001]//ATTRIBUTES ‘ '

.

.

.//NAME RunStat P 120//SOURCE SOCK JOHN[1002]//SOURCE SOCK BOB[2002]//ATTRIBUTES ‘""'

.

.

.In this example, the attribute group Overview is validated as in the previous example. Input for the attribute group RedEvent can be identified with the program bound to port 1001 from host JOHN or port 2001 from host BOB. Similarly, data for attribute group RunStat can be received from the programs bound to port 1002 and 2002 on hosts JOHN and BOB, respectively.

When multiple active programs are known to a Socket Data Provider and input from different programs is possible from the same host, port numbers are required to associate data with Universal Agent attribute groups, as illustrated in the examples below:



//APPL NCASYS//NAME Process P 60//SOURCE SOCK ENG1[4500]//SOURCE SOCK ENG2[4500]//SOURCE SOCK MIS2[4500]//ATTRIBUTES ‘@'

.

.

.//APPL NCANET//NAME ALERT E//SOURCE SOCK ENG1[3301]//SOURCE SOCK ENG2[3301]//SOURCE SOCK ENG3[3301]//SOURCE SOCK TEST1[3301]//SOURCE SOCK TEST2[3301]//SOURCE SOCK TEST3[3301]//ATTRIBUTES ‘ '

.

.

.The association of programs by ports method is not very flexible and generally requires planning and attention. The alternative is to use explicit metafile specification.

Association by explicit specification

The method of explicit association defines the following rules:

� The first data record received by the Socket Data Provider from a remote program must contain an explicit Universal Agent application association record starting at offset zero. Any remaining data in the record is not examined and is ignored. The association record starts with two slashes, followed by the name of the metafile. For example:

//myAppl

You do not need to be concerned with the possible differences in character code representation between the program host and the host of the target Data Provider. The Data Provider will automatically detect the need for code translation even though no metafile or SOURCE statement is yet known.



� The metafile must be available to the Socket Data Provider locally or it must be retrievable from a centralized metafile server.

� If the metafile defines an application that includes only one attribute group, the SOURCE statement is optional.

� If the application includes more than one attribute group, SOURCE statements are required and their specification must not result in ambiguity.

For example, a program from host MVSA contacts the Socket Data Provider on machine FIN1. The first data record received by the Data Provider specifies the metafile JOBCNTL.mdl. The Data Provider loads the metafile (if it has not already been loaded) and discovers that there is no SOURCE statement definition. The application NCAJOB includes only one attribute group, PartList. Therefore, the Data Provider can readily associate the connecting program with the attribute group PartList of application NCAJOB.

Metafile: JOBCNTL.mdl//APPL NCAJOB//NAME PartList P 900//ATTRIBUTES

.

.

.If the application NCAJOB contained more than one attribute group, a SOURCE statement would be necessary, but only to the extent of preventing ambiguity within the scope of the application NCAJOB.

Extending the same example, the application NCAJOB now includes three attribute groups: PartList, Order, and Schedule. Nevertheless, the Data Provider can quickly determine and associate the socket connection from host MVSA with the attribute group Schedule of the application NCAJOB.

Metafile: JOBCNTL.mdl//APPL NCAJOB//NAME PartList P 900//ATTRIBUTES

.

.

.



//NAME Order P 1200//SOURCE FILE Daily.ord TAIL//ATTRIBUTES

.

.

.//NAME Schedule E//SOURCE SOCK MVSA//ATTRIBUTES

.

.

.As noted above, the explicit association method is less rigid and easier to use than the SOURCE statement method. In addition, it is unaffected by other active programs known to the Socket Data Provider at the same time because, by explicitly specifying a metafile, the scope of resolution has been narrowed to only one metafile definition.

It is also important to note that if you do not send the //metafile_name record, the Socket Data Provider does not load the metafile. You must load the metafile as described in “Activating Metafiles” on page 51.

Formatting a socket buffer for transmissionThe program sending data to a Socket Data Provider must format the data buffer according to the metafile definitions. The order of values in the sending buffer must match the order of attributes defined in the metafile and the record delimiter used must be the one specified in the metafile.

For example, if your metafile has three attributes, your sending buffer should have the value for the first attribute as the first token in the buffer, the value for the second attribute as the second token, and the value for the third attribute as the third token. If your ATTRIBUTE statement specifies a delimiter of ";", your sending buffer must place a semicolon (;) between each value token.

Timing out UDP communication provides no state information to either sender or receiver. When UDP communication is used, the Socket Data Provider employs the following rules for determining the state of the sending program:



� For polled, sampled, and keyed data, the Socket Data Provider times out the sending program after five TTL intervals without receiving data and notifies OMEGAMON XE that the managed system is off-line.

� For Event data, the Socket Data Provider waits indefinitely for program input.

End of inputAt the conclusion of a data input session, the sending program can choose one of two ways of ending the session and allowing the Data Provider to indicate off-line status to OMEGAMON XE:

� The program sends the Data Provider the transaction end message shown below as a single record, indicating the normal end of a session:

//END-DP-INPUT

� The program closes the TCP socket, which results in detection of connection termination by the Data Provider.

Programs that use a UDP socket but omit sending the transaction end message, time out after five TTL intervals, as discussed above. Programs that send Event type data must send the transaction end message or they will remain on-line to OMEGAMON XE until system shutdown or until the program contacts the Data Provider again.

Character code translation

The use of socket transport presupposes that the sending program resides on a host other than the host where the Socket Data Provider is running. Therefore, it is possible that the data representation of the sending program differs from that of the Socket Data Provider. The Data Provider must be able to detect the difference and handle translation between the two representations.

The necessity of character code translation is indicated in one of two ways:

� specification of the code type in the SOURCE statement of the metafile

� explicit metafile association



Specifying code type in metafile SOURCE statements

The optional parameter code-type in the SOURCE statement is valid only for sources of the SOCK type. This parameter defines the character code type of the host of the sending program as either ASCII or EBCDIC. The default is ASCII. If the code type of the host of the sending program differs from the code type of the host of the Socket Data Provider, the Data Provider translates the data it receives into the character data type of its own local host.

As an example, if a socket client program is running on an OS/390 platform and it is communicating with the Socket Data Provider on AIX, then you must include the 'E' parameter on the socket metafile SOURCE statement to signify that the sending system is using EBCDIC, for example

//SOURCE SOCK MVSA E

Using an explicit association record

The Socket Data Provider checks the first data record it receives from a new sending program for an explicit application association record. If a record is found and the metafile is successfully loaded, the code type of the connecting program has been determined and verified. If the specification of code type in the metafile SOURCE statement does not agree with the code type determined at runtime, the value determined at runtime overrides the SOURCE statement definition.

If you do not use explicit metafile association, you must make sure that the correct code type for the host of the sending program is specified in the SOURCE statement or make certain that the program and the Socket Data Provider run on machines of like architecture.

TCP Outage DetectionTCP is a connection-oriented transport protocol: connecting session partners immediately detect session disconnections caused by a partner disconnecting or a network outage. However, if a connecting partner system experiences a power outage, its session partner cannot detect the interruption because there is no session disconnect notification from either the connecting partner or the network service.

The environment variable KUMP_TCP_OUTAGE_WINDOW makes it possible for the Socket Data Provider to detect such system outages. When an



outage is detected, a Managed System off-line notification is immediately presented on the CandleNet Portal.

The default value for this variable is 180 seconds. This enables the Universal Agent to detect any connecting session outage within a three-minute window.

You can increase detection window period by setting KUMP_TCP_OUTAGE_WINDOW to a value higher than 180, or decrease the window by setting a value lower than 180. If you do not need outage detection, you can disable this feature by specifying a value of 0. (Table 18 on 236 gives the name and location of the variables file by platform.)

You should investigate the characteristics of your monitored applications and your network configuration before changing the default setting. A longer value delays notification of session outages. A shorter value increases the Universal Agent processing overhead.

Delay of TCP disconnection notificationThe Socket Data Provider immediately detects the disconnection of the client program’s TCP session. However, it may be desirable to delay notification of OMEGAMON XE in order to provide adequate opportunity for processing of the received data.

By default, the TCP disconnection notification is be withheld until the time-to-live interval (TTL) has expired (see “NAME Statement” on page 154 for more information on TTL). For example, an attribute group has a specified TTL of 180 seconds (3 minutes). The Socket Data Provider will not notify OMEGAMON XE that the socket client program has disconnected until three minutes after it has detected the TCP session disconnection.

To disable delay of TCP notification, set the environment variable KUMP_TCP_DISCONNECT_BY_TTL to No.

Data acknowledgmentYou may wish to have the Socket Data Provider acknowledge receipt of data from a socket client program. This enables both the socket program and the Data Provider to detect communication problems immediately and initiate corrective procedures. You can specify the acknowledgment requirement using the CONFIRM statement. See “CONFIRM Statement” on page 173 for further information.



Limitations of the Socket Data ProviderBecause the Socket Data Provider is intended to extend system and application management to unfamiliar platforms using common tools with a minimum investment in programming efforts, it is subject to a number of limitations.

UDP programming is simpler than TCP. However, keep the following points in mind in choosing UDP or TCP because the choice effects overall recoverability, error detection, and delay in notifying OMEGAMON XE.

Limited error detection

A minimal protocol is defined between the Socket Data Provider and the sending program. This makes it easy to develop an Universal Agent application with minimal logic and programming complexity. However, error detection and recovery is limited because no status is exchanged between a sending program and a Data Provider, unless you use the CONFIRM feature (see “CONFIRM Statement” on page 173).

Use of TCP enables both the application and the Data Provider to detect connectivity problems immediately and to initiate a problem recovery procedure. With UDP, the parties can rely only upon problem time-outs for status.

Use of character format for numerical data

The Socket Data Provider and the sending program may reside on machines of different architecture with different internal representations of data. Therefore, the program must send numerical data in character format instead of in the machine's binary representation.

Copy mode not supported

The Socket Data Provider does not support blocks of sample data such as the COPY mode for files or the dp_BeginSample and dp_EndSample API calls, since there is no defined protocol between a Socket Data Provider and a sending program to implement this logical construct.

Action requests not supported

The Socket Data Provider has no means of sending action requests to its client programs.


Post Data Provider

Post Data Provider

OverviewPost Data Providers provide a convenient means of sending ad hoc notifications such as messages, alerts, and status to OMEGAMON XE. Each Post Data Provider can be customized to fill a specific use. For example, with a minimum of additional programming an application can send processing status to OMEGAMON XE using a TCP/IP socket. A customer service representative can execute a basic command script file and send inquiry messages to a Help Desk. System operators can quickly invoke a console command when they observe abnormal events to notify the network control center.

The Post Data Provider is implemented as a TCP/IP socket application with a predefined metafile. It listens on both TCP and UDP protocol ports 7575 or any port specified by the environment variable KUMP_POST_DP_PORT. Any program can quickly open a socket and send messages, alerts, or status to a Post Data Provider on demand. You can also develop simple Java applications that help you send ad hoc messages or use the command line interface program KUMPSEND provided with the Universal Agent.

Default configurationThe default characteristics of the Post Data Provider are defined in the data definition metafile KUMPOST shown in Figure 12 on page 90.

The name of the application defined by KUMPOST is MAS (Messages, Alerts, Status) and the name of the attribute group is dpPost. The application collects polled data with a time-to-live of one hour. There are five attributes in the group, delimited by semicolons (;). The values for the first three attribute values are automatically supplied by the Post Data Provider. The attribute values for Post_Text and Post_Category are obtained from an application or from a console command using the KUMPSEND program.

Post Data Provider


Figure 12. KUMPOST Data Definition Metafile

Message categoriesThere are ten predefined post message categories, shown in Table 7. The meaning of each category is determined by your data and local usage guidelines.

Table 7. Post Data Provider Message Categories

Category Description

I Information

O Operation

P Application

S System

N Network

A Alerts

C Critical

W Warning

R Reset

D Detail

//APPl MAS//NAME dpPost P 3600//ATTRIBUTES ';'Post_Time TPost_Origin D 32Post_Ack_Stamp D 26Post_Text D 512Post_Category D 16


Post Data Provider

Acknowledgment stampThe Post Data Provider generates an acknowledgment stamp to uniquely identify each message received from an application. The stamp is returned to the sending application only if the application is connected to the Post Data Provider by a connection-oriented TCP socket. For UDP sockets, the stamp is internally associated with the received message, but it is not returned. Using the acknowledgment stamp, all Post Data Provider messages can be quickly tracked and identified while in the system.

The stamp

AAAAAAAATTTTTTTTTTTTCSSSSS

is comprised of four parts where:

AAAAAAAA is the origin of themessage

TTTTTTTTTTTT is the local time of message arrival

C is the message category

SSSSS is the message one complement check sum

Customizing the Post Data Provider with metafilesLike all other Universal Agent applications, the MAS application can be modified through a metafile. However, the following restrictions apply to the MAS application.

� The name of the metafile must be KUMPOST.

� The attribute delimiter, if specified, must be a single delimiter.

� The first three attributes must be specified exactly as shown in Figure 12 on page 90. Their names, data types, specifications, and order cannot be changed.

You can specify an application name, attribute group name, data type, and time-to-live that are most appropriate to your site and you can define additional attributes after the mandatory first three. However, the KUMPSEND program (see “The KUMPSEND program” on page 94) works only with the five default attributes. If you define additional attributes you must develop your own program to format and send the added values to the Data Provider.

Post Data Provider


Customizing the Post Data Provider runtime specificationsA number of the run time specifications for the Post Data Provider can be configured using environment variables. Table 8 lists these variables and gives descriptions of their function.

For example, you may find that the Post Data Provider satisfies most of your requirements. However, you would like the name of the Data Provider managed system to reflect your specific area of interest. You can override the application and attribute group names using the variables KUMP_POST_APPL_NAME and KUMP_POST_GROUP_NAME:

KUMP_POST_APPL_NAME=SYSTEM

KUMP_POST_GROUP_NAME=HelpDesk

The names of the managed system and the Application workspace entry now become sourcename:SYSTEM00 and SYSTEM00, and the name of the report becomes HelpDesk for easy identification and grouping of alerts and messages. (See “Monitoring Applications” on page 121 for discussions of the naming of managed systems and workspaces.)

You might also start another Post Data Provider with a different set of specifications:

KUMP_POST_APPL_TTL=7200

KUMP_POST_APPL_NAME=BOB

Table 8. Post Data Provider Environment Variables

Environment Variable Description

KUMP_POST_DP_PORT Overrides the default Post Data Provider listening port

KUMP_POST_APPL_NAME Overrides the application name defined in the KUMPOST metafile

KUMP_POST_GROUP_NAME Overrides the name of the attribute group defined in the KUMPOST metafile

KUMP_POST_APPL_TTL Overrides the time-to-live value of the attribute group

KUMP_POST_CATEGORY Redefines default post categories or adds new ones.


Post Data Provider

KUMP_POST_GROUP_NAME=GENERAL

The associated Customer report, named BOBGENERAL, contains common inquiries and messages to Bob, but they are deleted automatically after two hours (7200 seconds).

You can also add to, redefine, or remove the default category definitions. A maximum of 16 message categories is possible. For example:

KUMP_POST_CATEGORY=(X=Experimental)

adds the category X to the Post Data Provider.

KUMP_POST_CATEGORY=(P=Programming)

redefines category P from Application to Programming.

KUMP_POST_CATEGORY=(D=)

removes category D.

KUMP_POST_CATEGORY=(X=Experimental,P=Programming,D=)

specifies all three of the previous definitions in one statement.

Any predefined category that is not explicitly redefined or removed remains unchanged.

Data Provider-supplied dataThe data transferred between the sending program and the Post Data Provider are the values for the attributes defined by the KUMPOST metafile. The values for the first three attributes—Post_Time, Post_Origin, and Post_Ack_Stamp—are supplied by the Post Data Provider. A program needs to send values for only the remaining attributes. In the case of the default metafile, this means sending attribute values for only Post_Text and Post_Category.

For example, the data stream received by a Post Data Provider sent by an irate user to the help desk might consist of only an inquiry, listed as critical:

Please help! System has been down for over an hour and I can’t do any work;c

Post Data Provider


The KUMPSEND programThe KUMPSEND program provides a command line interface to the Post Data Provider. This program works in conjunction with the five predefined attributes. If you add more attributes to the application or you alter the sequence of attributes, you must develop a new companion program for interacting with the Post Data Provider via command line.

The KUMPSEND program receives requests by examining keyword oriented input parameters. The syntax for the KUMPSEND command is:

kumpsend msg=”text” [cat=category] [dp=dp_hostname] [port=dp_listening_port] [ack=Y|N]

where

msg is the message to be sent to the Data Provider, enclosed in double quotes (““)

cat is the category of the message. The default categories are shown in Table 7 on 90.

dp is the host name of the Data Provider. The default is the local host.

port is the port on which the target Data Provider is listening. The default is 7575.

ack indicates that an acknowledgment is required from the Data Provider. The default is N.

For example, to send the information status message, “Hello World! I am ready to go.” to the Post Data Provider at ENG1 without requesting an acknowledgment, enter:

KUMPSEND msg="Hello World! I am ready to go."dp=ENG1

To send an alert message to and request acknowledgment from the Post Data Provider on host ENG1, enter:

KUMPSEND msg="Router NY-TC1 packet discard rate exceeds threshold"dp=atlantis cat=a ack=yes

You can display help for keywords by entering a question mark (?) with the command:

KUMPSEND ?


Post Data Provider

Sending data to the Post Data ProviderCommunication between the sending program and the Post Data Provider is straightforward.

Using a UDP Socket

The sending program opens a UDP socket and sends the attribute value string to the Post Data Provider. No reply should be expected.

Using a TCP Socket

The sending program:

1. opens a TCP socket and binds it to any local port2. establishes a TCP session by connecting the TCP socket to the Post Data

Provider3. sends the attribute value string to the Data Provider4. waits to receive an acknowledgment stamp from the Data Provider5. closes the TCP socket

HTTP Data Provider


HTTP Data Provider

OverviewThe Universal Agent HTTP Data Provider allows you to monitor the availability and response time of selected URLs. The HTTP DP runs as a separate Data Provider. You can specify URLs to monitor in the startup configuration file, within situations, or via the Take Action option.

Starting the HTTP Data ProviderStart the HTTP Data Provider using the same method you would use to start other Data Providers. In the following example, the KUMA_STARTUP_DP parameter starts the HTTP Data Provider.

KUMA_STARTUP_DP=HTTP

In the next example, the KUMA_STARTUP_DP parameter starts the HTTP Data Provider in conjunction with the ASFS and SNMP Data Providers.

KUMA_STARTUP_DP=ASFS,SNMP,HTTP

HTTP Data Provider managed system namesOnce HTTP monitoring becomes active, it is represented by two CCC Managed Systems, one for the INTERNET application with the following Managed System name:

host-name:INTERNET00

and one for the HTTP DP itself:

host-nameHTTPdp:UAGENT00

Note: No metafiles can be created for the HTTP DP. Therefore, no applications besides INTERNET can be used with this data provider.


HTTP Data Provider

Monitoring a URLYou can start monitoring any URL in one of three ways:

1. by including the target URLs in the DP startup URL initialization file KUMPURLS

2. by creating OMEGAMON XE situations based on the INTERNET table3. by using the Take Action option, URL Add

1. URL initialization file

KUMPURLS lists initial monitoring URLs and must reside in the product installation WORK directory. If this file does not exist or is empty, then URL monitoring can only be started via OMEGAMON XE situations or through Take Action. The default URL sampling interval is 300 seconds for URLs defined in this file. An example of KUMPURLS follows.

*****************************************************

** List of initial monitoring URLs. **

*****************************************************

www.candle.com

http://www.etrade.com/cgi-bin/gx.cgi/AppLogic%2bHome

http://moneycentral.msn.com/investor/home.asp

Note: The http:// prefix is optional. In addition, there is currently no support for monitoring secure socket URLs beginning with the https:// prefix.

2. OMEGAMON XE situations

You can also construct situations using the URL attribute in the INTERNET table for monitoring any target URL. If the URL is not already being monitored as a result of its presence in the KUMPURLS file, then monitoring for it will begin. If it already exists in KUMPURLS, the situation will still be valid, but a second monitoring instance for the URL will not be created. The only required attribute when creating a situation to monitor a URL is the URL name itself. It must begin with the http:// prefix.

HTTP Data Provider


In the following example, the Test_Yahoo situation monitors Yahoo's WEB home location. It raises an alert when the average response time exceeds 3000 milliseconds (3 seconds).

Figure 13. Test_Yahoo Situation

The Test_Yahoo situation interval defines the URL monitoring sample frequency. If the Test_Yahoo situation interval is less than 60 seconds, it will be reset in the Managed URLs table to 60 because that is the minimum sampling interval allowed for URLs. Stopping the situation stops the specific target URL monitoring.

If multiple URLs are monitored as a result of CCC situations and those situations are activated all at once, then you might see User ID values of _Z_INT36863000 substituted for one or more of your situation-started URLs. The _Z_INT36863000 substitution results from the CMS "DUPER" feature which optimizes the activation of multiple situations. If this User ID substitution has occurred for a URL and you are attempting to remove the


HTTP Data Provider

URL via the URL Remove dialog, specify _Z_INT36863000 in the dialog. To avoid situation name substitution, you must disable the CMS DUPER feature. This can be accomplished by specifying the CMS_DUPER=N environment variable in your CMS's KBBENV file.

3. Take Action

You can also specify URLs to monitor via a Take Action option called URL Add. When this option is selected, a dialog allowing you to specify the following parameters displays.

URL: a parameter (required) representing the URL itself (which can be entered with or without the http:// prefix). If not filled in, the Alias Name defaults to blank, the Status Interval to 300 seconds, the User ID to TAKE_ACTION, and the Cache Percentage to 0%.

URLaliasName: a parameter (optional) that can be specified to associate a more meaningful name to a URL.

StatusInterval: a parameter (optional) representing the elapsed time in seconds between samples (also referred to as the sampling interval). If multiple URLs are being monitored, a different status interval can be specified for each one.

ID: a parameter (optional) representing the User who started monitoring the URL.

� For URLs monitored as a result of a CCC situation, the User ID is the situation name.

� For URLs specified in KUMPURLS, the default User ID is INITCNFG.

� For URLs specified in this Take Action dialog, the default User ID is TAKE_ACTION. However, a different User ID value can also be specified. The User ID in this context is also referred to as the URL owner.

HTTP Data Provider


ObjCache%: a parameter (optional) that can be used to refine response time measurements. If you know roughly what percentage of your web pages are cached, then specify that value for ObjCache%. The UA HTTP DP will factor the cache percentage into its calculations of URL response time. For example, if you specify 50% for ObjCache% and there are 20 objects embedded in the web page, then only 10 of the objects will be downloaded (reducing the response time value).

After filling in the information and closing the dialog, the URL Add action should be assigned to the destination Managed System associated with the Universal Agent INTERNET application. Monitoring will begin immediately for the new URL. Availability and response time data for the URL will become viewable in CNP as soon as the new URL's Status Interval time period has elapsed. The URL will also be added to the KUMPURLS configuration file so that it will continue to be monitored across Universal Agent restarts.

There is a corresponding Take Action option called URL Remove, which permits immediate stopping of monitoring for a particular URL. The removed URL is also deleted from the KUMPURLS configuration file. The URL Remove dialog only requests the URL and User ID values. Note that the User ID value must match what was specified for the URL when monitoring began or the Remove action will fail. After filling in the information and closing the dialog, the URL Remove action should be assigned to the destination Managed System associated with the Universal Agent INTERNET application.

URL attributesThe Universal Agent HTTP Data Provider automatically registers the INTERNET application. This application contains two table definitions that appear in the INTERNET reports: Managed URLs and URL Objects.


HTTP Data Provider

Managed URLs

The Managed URLs table includes the following attributes, which are available to CCC situations using URL monitoring:

Table 9. URL Attributes

Attribute Name Type Size Description

Average Response Time ms

Integer Long Average URL page response time in milliseconds

Current Response Time ms

Integer Long Current URL page response time in milliseconds

HTTP Version Character 8 Version (HTTP 1.0 or 1.1) of the web server used at the target URL’s web site

ISP Character 64 Name of the Internet Service Provider (ISP) being used

Maximum Response Time ms

Integer Long Maximum observed URL page response time in milliseconds

Page Objects Integer Long Total number of additional objects associated with the monitored page

Page Size Integer Long Page size in bytes of the URL page received

Page Title Character 256 Page title extracted from the received URL page

Server Type Character 64 Type of web server used at the target URL’s web site

Status Character 64 Current sample URL status (OK or status description)

Status Interval Integer Long Elapsed time (in seconds) between status samplingss for the target URL

Status Timestamp Character 32 Current status sample timestamp

HTTP Data Provider


The calculations which are performed to determine attribute values such as Average Response Time and Maximum Response Time are based upon the concept of a "sample set". If a URL has been monitored for days, thousands of sampling statistics may have been obtained for it. However, only the most recent statistics are needed in reporting, for example, Average Response Time. In fact, including response time measurements from days or hours before could end up skewing the average. So the HTTP DP maintains a table, known as a sample set, of the most recently obtained samples and uses only those values to calculate response time statistics.

The sample set size is determined by a URL's Status Interval value. A small Status Interval will lead to a big sample set, and a large Status Interval will lead to a small sample set. Sample sets can range anywhere from 3 to 15 (3 if the Status Interval is 5 minutes, and 15 if the Status Interval is 1 minute), but they are always based on the last 15 minutes of sampling data.

The ISP name can be specified in a text file called ISP.ID located in the Universal Agent product installation WORK directory. If the file does not exist, a default ISP value of "LAN" is used.

Total Object Size Integer Long Total number of bytes downloaded for the associated page objects

Total Samples Taken Integer Long Total number of samples taken for this URL since monitoring began

URL Character 512 Target URL (must be in the format of http://)

URL Alias Character 32 User-specified alias for the URL

User Name Character 32 User ID that initiated the monitoring for the target URL

Table 9. URL Attributes (continued)



HTTP Data Provider

URL Objects

The second INTERNET table, URL Objects, includes the following attributes:

The URL Objects table contains a separate URL entry for each embedded object, such as the .gif and .jpg files that might be used in the web site listed in the Managed URLs report. When you need to monitor the response time and availability of specific objects within a web site, review the contents of the URL Objects table.

Table 10. URL Objects


Object Name Character 512 Embedded object within target URL

Object Size Integer Long Size of embedded object within target URL

URL Character 512 Target URL (must be in the format of http://)

SNMP Data Provider


SNMP Data Provider

OverviewThe SNMP Data Provider brings the functionality of an SNMP manager to OMEGAMON XE—including network discovery, trap monitoring, SNMP queries, and SET operations.

With the SNMP Data Provider, the Universal Agent can monitor any industry standard Management Information Base (MIB) or any MIB you supply. Candle creates Universal Agent applications for you by converting the MIBs into data definition metafiles. You can then monitor any MIB variable as an attribute. You can also create your own customized SNMP applications to monitor multiple attribute tables and even multiple MIBs.

In addition, Candle supplies a special application, SNMP-MANAGER, which allows you to view workspaces on your network topology and any SNMP traps that have been forwarded to the Universal Agent. You can use the attributes defined in the applications to create monitoring situations and policies in CandleNet Portal.

For further information, refer to the Universal Agent SNMP Data Provider User’s Guide.


WBEM Data Provider

WBEM Data Provider

OverviewSeveral years ago, the Distributed Management Task Force (DMTF) adopted a standardized data model called the Common Information Model (CIM). Microsoft has implemented the CIM schema as the Windows Management Instrumentation (WMI) feature. WMI offers a wealth of information about Windows machines that the WBEM Data Provider collects and reports to the Candle Data Server.

The WBEM Data Provider, used in conjunction with the OMEGAMON XE for Windows Management Web Service, allows you to monitor the availability and performance of the system components that comprise your Windows NT, Windows 2000, and Windows XP environments. The WBEM Data Provider, for example, allows you to

� determine if a logical partition on your hard drive is low on space. Use the attributes FreeSpace, Size, and DriveType from the WIN32_LOGICALDISK group. FreeSpace indicates how much space is left in bytes. Size indicates the size in bytes. In order to get the information for logical partitions only, look for drives that have a value of Local_Disk under DriveType.

� address maintenance concerns on your network. Use the attribute HotFixID from the WIN32_QUICKFIXENGINEERING group. This attribute lists all Microsoft fixes that have been applied to a system.

� review all Windows services that are set to start automatically and are not running. Use the WIN32_BASESERVICE group to identify a service that a user has manually stopped. StartMode lists all services that are set to start at boot time with a value of Auto. Any service that is not running has a value of Stopped under State.

Data available via the WBEM Data Provider includes account and base service information, printer details, and performance statistics associated with processors, BIOS, page file usage, processes, logical disks, network adapters, QFE, and operating systems.

WBEM Data Provider


Starting the WBEM Data Provider

Overview

The WBEM Data Provider runs as a separate thread of the Universal Agent. You start the WBEM Data Provider, either manually or automatically, when you start the Universal Agent.

For the WBEM DP to collect data, you must also install and run the OMEGAMON XE for Windows Management Web Service. The WBEM DP requests data from this web service on behalf of one or more WBEM metafile applications, and it is the web service that makes the actual WMI query calls to the Windows machines being monitored.

Starting the WBEM Data Provider automatically

To have the WBEM Data Provider (or any other Data Provider) start automatically when you start the Universal Agent, use the environment variable KUMA_STARTUP_DP. See “Environment Variables” on page 235 for details on setting variables.

Starting the WBEM Data Provider manually on Windows

To start the WBEM Data Provider when you start the Universal Agent, specify WBEM as a startup parameter in the Manage Candle Services dialog:

1. If necessary, stop the Universal Agent.

2. Right-click the Universal Agent, then select Change Startup Parms from the pop-up menu.

3. Type WBEM in the field, then click OK.

Starting the WBEM Data Provider manually on UNIX

If you want to start the Data Provider manually (instead of using KUMA_STARTUP_DP), you must start the Universal Agent from a command line and specify WBEM as a parameter in start command string. For example:

CandleAgent -o WBEM start um


WBEM Data Provider

Stopping the WBEM Data ProviderThe WBEM Data Provider is stopped automatically when you stop the Universal Agent.

WBEM Manager applicationCandle provides an application called WBEM Manager that is automatically activated when the WBEM Data Provider is started. This application provides a single workspace, named WBEM Status. The WBEM Status workspace provides the following information on all monitored WBEM applications:

� Origin Node

� Application Name

� Attribute Group Name

� Monitor Agent Information

� Monitor Interval

� Timestamp

� Last Status

This workspace can assist you with troubleshooting your Windows monitoring. For example, if your CNP workspaces are empty (unpopulated), review the Last Status column of the WBEM Manager workspace to identify the potential problem. The Last Status column displays error strings, error codes, and other diagnostic data.

See the Universal Agent online Help for an overview of the WBEM Status workspace and for descriptions of the attributes associated with this application.

Windows Monitoring applicationsCandle provides three WBEM metafiles that can be used to monitor Windows enviroments:

� a Windows NT monitoring application – WinNT.mdl

� a Windows 2000 monitoring application – Win2K.mdl

� a Windows XP monitoring application – WinXP.mdl

WBEM Data Provider


These three metafiles are installed into the metafiles WBEM subdirectory.

The Candle-provided applications, or specialized variations of these applications that you create, can be used to monitor a wide variety of elements within your Windows environment, including user accounts, basic input/output services (BIOS), network adapters, printer activity, processes, and processors. For a complete description of the attribute groups and default workspaces associated with the Candle-provided Windows monitoring applications, see the Universal Agent online Help.

Creating custom WBEM applications

Overview

The Candle-provided WBEM metafiles are a comprehensive collection of Windows monitoring attributes, but are not intended to be used as is. Although you can monitor Windows systems using one or more of the three default applications available with Universal Agent, to effectively monitor your environment, you should create custom WBEM applications. A custom WBEM application allows you to monitor the availability and performance of your system based on those components that are of importance to you. You can tailor Universal Agent WBEM to your mission.

Creating custom WBEM metafiles also allows you to efficiently monitor your Windows environment. For example, the Win32_Account attribute group in the Candle-provided WBEM metafiles lets you status every configured user on the machine being monitored. By default, the application collects Win32_Account information every fifteen minutes. However, this information rarely changes. A custom WBEM metafile that omits the Win32_Account attribute group would allow you to eliminate the network traffic associated with continually gathering this relatively static user information.

When creating custom WBEM applications, remember that you...

� can only include application groups (and their attributes) that exist in the default metafile.

� can eliminate individual attributes or even entire groups when constructing a new metafile.

� cannot add or rename attribute groups or attributes.

� cannot have two applications active with the same application name.


WBEM Data Provider

Step 1: Copy a Candle-provided metafile

Copy the Candle-provided metafile associated with the system you are monitoring (Windows NT, Windows 2000, or Windows XP).

Step 2: Save the custom metafile with a unique name

Save the custom metafile that you are preparing to edit/create with a unique name. For example, save it under the name

myWBEM.mdl

It does not need to be saved in the metafiles WBEM subdirectory, although that is the logical place to store all of your custom WBEM metafiles. Be sure that the first three characters of the WBEM application name, as specified on the //APPL statement, are unique among all Universal Agents connected to a particular CMS.

Step 3: Select the attributes you want to monitor

Determine which attribute groups and attributes are not appropriate for your management scenarios. Delete the attribute groups and attributes that you do not want to include.

Two additional rules apply to WBEM metafiles:

� The metafile must include //WBEM as the first statement.

� In each attribute group, the first two attributes must be:

Agent_Info D 128Agent_Name D 64 KEY ATOMIC

“Example” on page 110 shows a sample metafile.

Step 4: Validate the metafile

Run the console command VALIDATE. Review the output report for any warning or error messages and modify the metafile as necessary.

Step 5: Import the metafile to the Universal Agent

Make the metafile available to the Universal Agent either by including its name in the Universal Agent initialization file, KUMPCNFG, and restarting UA or by using the console IMPORT command.

WBEM Data Provider


Example

The following is an example of a custom application metafile.

//WBEM

//APPL WMIexample

//NAME WIN32_PROCESS K 3600

//ATTRIBUTES

Agent_Info D 128

Agent_Name D 64 KEY ATOMIC

Name D 32 KEY ATOMIC

ExecutablePath D 256

MaximumWorkingSetSize C 999999

MinimumWorkingSetSize C 999999

ProcessId C 999999

PageFaults C 999999

Collecting data

Overview

In order for your WBEM application workspaces to display data and for your situations to evaluate data, you must perform these three tasks:

1. Install the OMEGAMON XE for Windows Management Web Service on a Windows XP Professional machine.

2. Activate at least one WBEM metafile.

3. Issue the WBEM Start option of the Take Action feature to target a particular Windows node for data collection.You must initiate data collection by telling the WBEM Data Provider the node to monitor, the location of the OMEGAMON XE for Windows Management Web Service, the sampling interval, and the attribute group name. You do this using the WBEM Start option of the Take Action feature.

Once you have initiated data collection, you do not need to start it again each time you start the WBEM Data Provider. The Data Provider maintains a


WBEM Data Provider

persistent state between restarts. If the name of your WBEM application changes, you must restart the monitoring.

Accessing the Take Action feature

CandleNet Portal lets you interact directly with your applications and operating system through the Take Action feature. Take Action has a text box for entering your own system command, or you can choose from a list of predefined commands. It also has a list of systems on which to effect the command.

You can invoke the Take Action feature from several places:

You have the choice to select a predefined command or enter a command yourself. You can also create and save commands so you can select them from the list of defined commands.

Starting data collection

To use the Take Action feature to start collecting data:

1. Select the Navigator item associated with the application or system on which you want to execute the command.

2. Right-click the Navigator item or row in a table view.

3. Select Take Action from the popup menu.

4. Select WBEM Start from the Name list.The Edit Argument Values window appears.

5. In the Edit Argument Values window:

Take Action view Add a Take Action view to a workspace so you can access the feature from that workspace at any time.

Situation Add a Take Action command to a situation that executes when the situation becomes true.

From the Navigator Send a Take Action command to a system associated with the selected workspace.

From a row in a table view

Send a Take Action command to a system associated with the selected row.

WBEM Data Provider


— for MonitorNode, specify the IP address of the node to monitor.

— for WBEMService, specify the IP address/hostname of the machine where the OMEGAMON XE for Windows Management Web Service is running.

— for StatusInterval (optional), specify the sampling interval in seconds (if left blank, defaults to 300).

— for attrGroup (optional), specify the attribute group name (if left blank, defaults to all attribute groups within the WBEM metafile).

— for Userid, enter an Administrator ID for the monitored node.

— for Password, enter the password for the Administrator ID.

6. Click OK.To stop data collection, you must issue a Take Action > WBEM Stop command.

Note: The WBEM Data Provider does not always render data during the initial interval after the WBEM Start action. In those cases, “No Completed Status” displays in the Last Status column for some attributes. The Data Provider is functioning properly (and the status will eventually display “OK”).

Stopping data collection

To use the Take Action feature to stop collecting data:

1. Select the Navigator item associated with the application or system on which you want to execute the command.

2. Right-click the Navigator item or row in a table view.

3. Select Take Action from the popup menu.

4. Select WBEM Stop from the Name list.The Edit Argument Values window appears.

5. In the Edit Argument Values window:— for MonitorNode, specify the IP address of the node to monitor.

— for WBEMService, specify the IP address/hostname of the machine where the OMEGAMON XE for Windows Management Web Service is running.


WBEM Data Provider

— for attrGroup (optional), specify the attribute group name (if left blank, defaults to all attribute groups within the WBEM metafile).

6. Click OK.You can browse the WBEM Status workspace at any time to see a list of the applications and attribute groups for which data is being collected on a particular host.

7. After closing the dialog, distribute the action to the WBEM application managed system associated with the WBEM metafile being used.

Windows monitoring workspaces

Overview

CandleNet Portal presents a set of workspaces for every application you monitor. Each workspace corresponds to an attribute group. In the workspaces, you see information from WBEM agents for which you have initiated data collection.

The Candle-provided Windows monitoring applications offer a variety of default workspaces. These default workspaces allow you to monitor the availability and performance of your Windows NT, Windows 2000, and Windows XP environments.

Component workspaces

The Windows monitoring workspaces include:

� Win32_Account� Win32_BaseService� Win32_BIOS� Win32_ComputerSystem� Win32_LogicalDisk� Win32_NetworkAdapter� Win32_OperatingSystem� Win32_PageFileUsage� Win32_Printer� Win32_Process

WBEM Data Provider


� Win32_Processor� Win32_QuickFixEngineeringFor a complete description of the workspaces and their component attributes, see the Universal Agent online Help.

The Agent_Name attribute

Each workspace contains a special purpose attribute, Agent_Name. Since you can specify more than one host from which you want to collect data, you can receive multiple rows of data, one from each WBEM agent host. The Agent_Name column links the row of data to its specific agent. In workspaces, therefore, the Agent_Name attribute is used to identify the originating host name for a particular row. In situations, the Agent_Name attribute is useful in limiting situation evaluation to a particular host.

Accessing the Windows monitoring workspaces

To access the Windows monitoring workspaces:

1. Double-click the application-level item in the Physical view of the Navigation tree.The workspace items appear below the application item.

2. Select (highlight) the item representing the workspace you want to view.The default workspace displays.


ODBC Data Provider

ODBC Data Provider

OverviewOpen Database Connectivity (ODBC) is a standard application programming interface for accessing data in relational data sources. The Universal Agent ODBC Data Provider allows you to collect data from ODBC-compliant databases using SQL Select statements and stored procedures supported by the particular ODBC source that is being monitored.

The ODBC DP runs as separate Data Provider. It is only available on Windows platforms. You specify the ODBC data source, table(s), and SQL Select information through parameters and statements in UA metafiles. The tables and columns in the ODBC data source become attribute groups and attributes in the associated metafile. Any valid SQL Select statement or stored procedure that retrieves column data from one or more tables or views can be specified in an ODBC metafile.

ODBC allows you to collect data from a remote data source without having to install any additional software on the remote system. The ODBC driver software handles all of the network connectivity issues. As a result, the ODBC DP can be running on one box while it's simultaneously collecting data from multiple remote database systems in your network. Any ODBC data source that you can configure on the Windows machine where the ODBC DP is running is eligible for monitoring.

Starting the ODBC Data ProviderThe ODBC Data Provider is started in the same way as other Universal Agent Data Providers. In the following example, the KUMA_STARTUP_DP environment variable specifies that the ODBC DP should be started along with the ASFS DP:

KUMA_STARTUP_DP=ASFS,ODBC

ODBC Data Provider


Sample ODBC MetafilesThe following two examples illustrate the parameters and statements specific to ODBC metafiles:

Example 1

//APPL NWIND

//NAME EMPLOYEES K 300 Interval=60

//SOURCE ODBC nwind

//SQL select * from employees

//ATTRIBUTES

EmployeeID N 8 KEY ATOMIC

LastName D 32

FirstName D 32

Title D 32

TitleOfCourtesy D 16

BirthDate D 24

HireDate D 24

Address D 32

City D 32

Region D 32

PostalCode D 32

Country D 32

HomePhone D 32

Extension D 16

Notes D 128

ReportsTo N 4

Modes of collecting table data

ODBC table data can be collected in interval-driven or demand-driven mode. The default is demand-driven, which signifies that data is only collected if a situation request or report request is issued for the table. This example uses interval-driven collection, indicated by the Interval=60 parameter on the //NAME statement, which means that data will be collected for this table every 60 seconds. If the Interval=nn parameter is omitted, demand-driven collection is in effect.


ODBC Data Provider

Parameters and statements

//NAME statement

The //NAME statement also specifies "K 300", indicating that this is a keyed table and its data has a TimeToLive value of 300 seconds. It is generally a good idea for ODBC metafiles to use keyed tables because (1) it prevents the same retrieved rows from being added multiple times whenever the SQL Select statement is executed, and (2) most ODBC tables have one or more indexed columns which logically correspond to KEY attributes in the UA metafile.

//SOURCE statement

The //SOURCE statement supports an "ODBC" parameter to specify that it is an ODBC metafile. This is a required parameter for all ODBC metafiles. The presence of this parameter means that other Data Providers will bypass loading the metafile and only the ODBC DP will load and activate it. Following the "ODBC" parameter, you must include the ODBC data source name, "nwind" in this example. It is the same name that you configured in the ODBC Data Sources applet. Note that this data source must have already been configured-it is not automatically done so by the ODBC DP. If the data source is not accessible across the network or if the ODBC DP cannot connect to it because of missing or incorrect userid/password credentials, the associated managed system will not come online. If the data source name contains any embedded blanks, it must be surrounded by single quotes.

//SQL statement

Each ODBC metafile requires a valid //SQL statement for every //NAME statement. It can be either an SQL Select statement or a stored procedure name. In the example above, all columns and rows are being selected from the Employees table in the Microsoft Access Northwind database, which has been configured as "nwind". This metafile specifies that every 60 seconds, the "select * from employees" SQL statement will be executed against the nwind database.

ODBC Data Provider


//ATTRIBUTES statement

In ODBC metafiles, the attributes listed under the //ATTRIBUTES statement must match column names defined in the ODBC table that is being accessed. You do not need to include an attribute for every column in the table. You also do not need to list the attributes in the same sequence as the columns appear in the ODBC table. However, the attributes that you do include must have a matching column name (case does not matter). In other words, you cannot rename an attribute in the metafile so that it no longer matches its corresponding column. You are free to add derived attributes and other UA-specific attributes, such as a LocalTimeStamp.

Usage Notes� In ODBC metafiles, the attribute delimiter is not used because each

column value is retrieved separately. Therefore, it does not matter what you specify for the delimiter value on the //ATTRIBUTES statement.

� Changes to the //SOURCE and //SQL statements can be implemented dynamically via the UA refresh command without changing the version number of the ODBC metafile application.

� Although this example uses the ODBC data source name, nwind, as the application name on the //APPL statement, it is not a requirement that the two names match.

Example 2

Here is another example to illustrate additional features of ODBC metafiles:

//APPL CNPS

//NAME spt_server_info K 300 AddTimeStamp

//SOURCE ODBC cnps user=sa pswd= maxrows=50

//SQL select * from spt_server_info where attribute_id > 2

//ATTRIBUTES

attribute_id N 8 KEY ATOMIC

attribute_name D 64

attribute_value D 64

*

//NAME sp_helpdb K 300

//SOURCE ODBC cnps user=sa pswd=


ODBC Data Provider

//SQL proc=sp_helpdb master

//ATTRIBUTES

name D 32 KEY ATOMIC

db_size D 32

owner D 32

dbid C 999999

created D 20

status D 64

//NAME statement

The absence of the Interval= parameter indicates that these two tables use demand-driven data collection. The spt_server_info table includes an "AddTimeStamp" parameter, which will insert a LocalTimeStamp column in the spt_server_info report.

//SOURCE statement

The SQL Server "cnps" data source requires a userid/password combination to connect. So both of these //SOURCE statements include "user=" and "pswd=" parameters. The "sa" userid does not have an associated password, so the "pswd=" parameter value is left blank.

By default, a maximum of 100 rows are returned for each ODBC table in a metafile. To increase or decrease this value for a particular table, you can include a maxrows=nn override on the //SOURCE statement. The default can be globally changed with the KUMP_ODBC_MAX_ROWS environment variable. The maxrows=50 specified for the spt_server_info table means that if more than 50 rows are returned from the Select statement, only the first 50 rows will be used for reporting and situation evaluation.

//SQL statement

The first //SQL statement in Example 2 shows how you can include a Where clause to filter which rows will be returned. You should use Where clause filtering in your ODBC metafiles when possible. It's more efficient because fewer rows are retrieved. And most of the time only certain rows from the data source are of interest for situation evaluation purposes, so it makes sense to issue qualified SQL Select statements that only retrieve the rows you wish to evaluate in your situations.

ODBC Data Provider


The sp_helpdb table in Example 2 illustrates the use of stored procedures. Instead of a Select statement, the //SQL statement can specify the name of a stored procedure, which must be preceded by the "proc=" keyword. If there are any input parameters to the stored procedure, they must be blank-separated tokens after the stored procedure name. In this example, "master" is the only parameter being supplied to the sp_helpdb procedure.

The two metafile examples above assume a one-to-one relationship between UA attribute groups and SQL tables, but this is not a requirement. SQL joins are supported. An //SQL statement could select columns from 10 different tables and store the retrieved values in attributes belonging to a single UA attribute group. The only requirement is that the retrieved columns have matching attribute names; however, the columns do not all have to come from the same table.

Automatic Generation of ODBC MetafilesTo save the effort of manually creating ODBC metafiles, it is possible to automatically generate a complete, syntactically correct ODBC metafile from a given data source name. See the description of the GENERATE command in “GENERATE” on page 216.

Monitoring Applications 121

Monitoring Applications

Overview

This chapter discusses how to use CandleNet Portal to monitor your Universal Agent applications. It covers

� the naming of Universal Agent managed systems, workspaces, and attribute groups

� Customer workspaces for monitoring Universal Agent applications

� UAGENT workspaces for monitoring the operational status of Data Providers and the actions they support

� creating situations and automation policies for Universal Agent applications

� collecting historical data

Chapter contentsMonitoring Universal Agent Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Universal Agent Managed Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Customer Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126UAGENT Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Universal Agent Situations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Historical Data Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

5

Monitoring Universal Agent Data


Monitoring Universal Agent Data

OverviewWith CandleNet Portal you can monitor data from an Universal Agent just as you can data reported by Candle OMEGAMON Monitoring Agents. You can

� view real-time and historical workspaces for every attribute group you monitor

� monitor the operational status of Data Providers

� create situations using the attributes you defined

� create policies to automate responses to events on your monitored systems


Universal Agent Managed Systems


OverviewEach Universal Agent and each application monitored by an Universal Agent is represented on CandleNet Portal as a managed system. The name assigned to a managed system enables you to identify the location of the data, the corresponding Universal Agent application, and the version of the metafile. When the version number of the metafile changes, a new managed system comes online and the old one goes offline.

Managed system namesWhen an Universal Agent is started, it appears in the Navigator view as:

hostname:UA

where hostname is the name of the host on which the Universal Agent was started.

Each monitored Universal Agent application appears as:

instname_sourcename:applnameVV

where:

instname is the name of instance of UA if a non-primary copy of UA is being started.

sourcename identifies the location of the data. For File, WBEM, ODBC, HTTP, and SNMP Data Providers, sourcename is the host of the Data Provider. For other Data Providers (Socket, Post, API Server), the source name is the network location of the client sending the data. For example, if a Socket Data Provider is running on host PRDSRV1 and a socket client program is sending it data from host newyork, the source name component of the managed system name is newyork.

applname is the name of the application defined in the metafile

VV is the version number of the metafile



For example, if a File Data Provider is running on machine FIN1 supporting an Universal Agent application and attribute group defined as

//APPL LOGS

//NAME SYSLOG E

//SOURCE FILE /syslog

and this is the first version of the metafile, the name of the managed system for the attribute group would be FIN1:LOGS00.

Truncation of managed system namesIf the length of the entire managed system name exceeds 32 characters, the source name is truncated from the right to a maximum of 9 characters. If an instance name is being used, it will be truncated from the left until the total managed system name length equals 32 characters.

Managed system version numbersEach managed system is assigned a version number. The version number takes the form

AA-VV.RR.MM

where

AA is the first two characters of the Universal Agent application name

VV is the version number of the Universal Agent (the current release is version 04)

RR is the version number of the metafile

MM is the modification number of the metafile

Managed system version changesWhen the version number (RR) of a metafile changes, the following occurs (see “Versioning of Metafiles” on page 58 for changes that cause the version of a metafile to change):

1. managed systems with the previous version number go offline2. managed systems with the new version number come online3. managed system list entries appear with the new version number



4. any running situations distributed to previous versions of the managed systems are automatically stopped.

The names of workspaces and attribute groups will also change (see “Application names” on page 127 and “Attribute and attribute group names” on page 134).

Important. You cannot simply restart situations distributed to a previous version of a managed system. You must create new situations or edit the existing ones to use the new attribute group names and distribute them to the new versions of the managed systems. The same applies to policies. For this reason, Candle recommends that you attempt to make changes that change only the modification number and not the version number. Refer to “Versioning of Metafiles” on page 58 for a list of changes that do not affect version number.

When the modification number (MM) of a data definition metafile changes the following occurs:

1. managed systems containing the previous version number go offline2. managed systems containing the new version number come online You do not have to recreate and redistribute existing situations or policies when the modification number changes. You need to change an existing situation only if you wish to use a newly added attribute as one of its predicates.

Customer Workspaces


Customer Workspaces

OverviewThe CNP incorporates a workspace for each attribute group defined in a metafile. You access Universal Agent workspaces from the Attribute group level of the Navigator view. The Navigator offers a high level view of your monitored enterprise. It can show the enterprise in two ways: as a physical mapping of systems and applications, or as a logical view of entities such as the sales and payroll departments. The Physical and Business tabs at the bottom of the Navigator enable you to switch between these views.

Physical

The default Navigator view is physical, with these levels:

� Enterprise is at the highest level. It encompasses all the systems in your organization where Candle monitoring agents are installed.

� Operating platform is the operating system the computer is running on, such as OS/390 or Windows.

� System is the name of the computer or MVS image where Candle monitoring agents are installed.

� Agent is the Candle monitoring agent installed on the system. If the agent name is dimmed it means the agent is offline.

Some Candle monitoring products have both agents and subagents (MQSeries and SAP R/3, for example). In such cases another level is added to subsume the subagents in the managing agent's folder.

Some Candle agents are grouped into one folder, particularly those that may have multiple agents of the same type on the same system (such as CICSplex, MQSeries, and Universal Agent).

� Attribute group is the category of attributes the agent is monitoring. An attribute group is made up of several or many individual attributes, each of which can be used as a column in a table, a data series in a chart, or as a condition in a situation. You may see some attribute groups consolidated under one title, with multiple workspaces available.


Customer Workspaces

Business

OMEGAMON DE comes with a Navigator business view, which groups agents into managed objects. The managed objects and the managed systems they represent are defined in the CNP.

Click the Business tab to see the Navigator business view. This view of the Navigator reflects the hierarchy of managed objects. The assigned overview object appears as the top level in the business view. Any managed objects in the overview object appear in the next level.

Application namesThe name of the application takes the form:

application_nameVV

where VV is the version number of the metafile in which the application is defined.

Workspace namesThe names of the Customer Workspaces correspond to the attribute groups for that application. You select the managed system for which you want to view a workspace when you open the workspace for that attribute group.

Customizing workspace contentsYou can customize the contents of Customer workspaces just as you can the contents of other workspaces. You can:

� create customized workspaces that contain data for only a subset of managed systems or attributes

� sort columns on the basis of the value of the entries

� include or exclude data according to criteria you specify

� change the order of columns in the workspace

Consult Administering OMEGAMON Products: CandleNet Portal and the CNP online help for instructions on customizing your workspaces.

Customer Workspaces


Accessing help for applications, attribute groups, and attributesIf help has been defined in the Universal Agent application metafile for an application, attribute group, or attribute (see “Creating help for applications, attribute groups, and attributes” on page 47), you can access it as follows:

� For information about a particular attribute group, select the attribute group name in the Situation editor.

� For information about the columns (representing attributes) in the workspaces, mouseover the column headings that represent each attribute.


UAGENT Workspaces

UAGENT Workspaces

OverviewEvery Data Provider registers a special purpose application, UAGENT, at startup. UAGENT contains two attribute groups: DPLOG and ACTION.

The purpose of the DPLOG attribute group is to surface processing information for a particular Data Provider. The purpose of the ACTION attribute group is to provide information about the processing of automated actions from situations and policies.

Since each Data Provider appears as a managed system, you can develop situations and policies for it, just as you can for any other managed system. This enables you to manage all the Data Providers in an enterprise from the CNP and achieve dynamic self-monitoring of Universal Agent runtime operations. However, you cannot use automation or TakeAction on the ACTION attribute group.

UAGENT managed system namesManaged system names for the UAGENT applications are constructed similarly to the managed system names for Universal Agent applications. They take the following form:

instname_hostnameDPtype:UAGENTVV

where:

instname is the instance name of UA if a non-primary copy is being started.

hostname is the name of the host on which the Data Provider resides

dpType is the type of Data Provider (for example, FILEdp, SOCKdp, ODBCdp, HTTPdp, or ASFSdp)

VV is the version number of the metafile

For example, the managed system name of a File Data Provider running on a system named ENG1 would be ENG1FILEdp:UAGENT00.

UAGENT Workspaces


DPLOG workspaceThe DPLOG workspace is similar to a system console log. It provides a detailed audit trail for the Data Provider. The log workspace contains six columns, described in Table 11 on page 130.

Table 11. DPLOG Workspace Columns

Column Name Description

DP Time The local time in 16 character format: CYYMMDDHHMMSSmmm(where 1 = 21st century)

DP Log Category The category of the log entry. The log categories currently implemented are described in Table 12.

DP Log Text Detailed log descriptions

DP Name The name of the Data Provider. Same as the managed system name.

DP Type The type of Data Provider, such as File, Socket, Post, API Server

DP Version The current version number of the Data Provider

Table 12. Log Categories


SYSTEM Entries pertinent to general Data Provider operations such as startup, shutdown, thread activities, operational status with the Universal Agent, and periodic system statistics.

ERROR Entries relating to significant error conditions such as unrecoverable file I/O, execution environment errors, configuration definition errors, and internal processing errors.

WARNING Messages for noncritical situations such as application data definitions not defined or an application already registered with the Universal Agent, or circumstances where default actions were taken or default values were supplied during normal processing.


UAGENT Workspaces

INFO Detailed audit trails of processing activities. They represent general Data Provider status and work requests, such as console commands received and processing results, application definition activities, and reasons for delay in monitoring a file.

APIINFO Informational log entries pertinent to API Data Provider activities. Examples: dp_Define, dp_Redefine, dp_BeginInput, dp_EndInput API calls.

APICOMM Communication activities between the API Data Provider and the client programs such as dp_OpenSession and dp_CloseSession API calls.

SNMPINFO Informational messages related to interactions with the SNMP Data Provider. Examples: Trap configuration definitions loaded, MIB data collection start request, or SNMP network management started

METAINFO Informational messages related to interactions with the centralized Data Provider metafile server. Examples: processing of a metafile request by the server, outcome of a metafile retrieval

METACOMM Communication activities between Data Provider metafile client and the Data Provider metafile server. Examples: Data Provider metafile client successfully connected to the server, connection failure and status of automatic retry, or disconnection detected by either party.

SOCKCOMM Communication activities related to Socket Data Providers. Examples: new TCP connection accepted, new UDP partner recognized, connection abandoned due to configuration mismatch, or UDP partner timed out due to inactivity

Table 12. Log Categories


UAGENT Workspaces


ACTION workspaceThe ACTION workspace contains seven columns. These columns are described in Table 13. You can create situations and policies based on ACTION attributes just as you can with any other workspace attributes.

Table 13. ACTION Workspace Columns

Column Description

Action ID Internally generated action sequence number used to track the action activities and progress.

Action Type Identifies the type of action. Currently the only valid value is Automation.

Action Owner The name of the object (situation or policy) that initiated the action

Action Node The name of the managed system that is processing the action

Action Name The name of the command, program, script, etc. to process

Action Parms The parameters to pass to the action name

Action Status The status of the action request from the CCC to the Data Provider:� Success� Failure

Action Results The first 256 characters of the output of the action processing


Universal Agent Situations


OverviewThis section covers information specific to creating Universal Agent situations. Please refer to Administering OMEGAMON Products: CandleNet Portal or the online Help provided with CandleNet Portal for detailed instructions on creating situations.

What is a situation?A situation is a logical expression involving one or more system conditions. Situations are used to monitor the condition of systems in your network. You can manage situations from CandleNet Portal by using the situation editor.

What is a predefined situation?The Candle agents you use to monitor your system environment are shipped with a set of predefined situations that you can use as-is or modify to meet your requirements.

Predefined situations contain attributes that check for system conditions common to many enterprises. Using predefined situations can improve the speed with which you can begin using the OMEGAMON XE products. You can examine and, if necessary, change the conditions or values being monitored by a predefined situation to those best suited to your enterprise.

Note: Candle suggests that, if you choose to modify a predefined situation, you first make a copy to ensure fallback if necessary.

Using situations You manage situations from CandleNet Portal using the Situation editor. Using the Situation editor you can

� create a situation

� save a situation

� display a situation

� edit a situation



� start, stop, or delete a situation

� investigate the event workspace for a situation

When you open the Situation editor, its left frame initially lists the situations associated with the Navigator item you selected. When you click a situation name or create a new situation, the right frame of the Situation editor opens to provide you with the following information about the situation or to let you further define that situation:

Attribute and attribute group namesThe attributes that you have defined appear in the Select Attribute window which appears when you place a predicate object into the workspace of the Situation editor. The name of the attribute group name is the same as the workspace that contains data from that group. The names of the attributes in the group are the same as the column headings in the workspace.

Creating situations with attributes from different groupsYou can only create situations that use attributes from the same attribute group. If you want to use attributes from different groups in your situation, you must create another situation and embed it in the first. Alternatively, you might consider creating a new group that contains all the attributes you want to include in the situation.

Condition See, add to, and edit the condition being tested

Distribution See the systems to which the situation is assigned and assign the situation to systems

Expert Advice Write comments or instructions to be read in the event workspace

Action Specify a command to be sent to the system.

You can also enter take action commands by adding a take action view to a workspace, selecting Take Action from the pop-up menu for an item in the Navigator’s physical view, or creating take action commands and saving them for later use.

Until Reset a true situation when another situation becomes true or a specified time interval elapses



Distributing situations to managed systemsAfter you create a situation, you distribute it to the managed systems on which you want it to run. You can distribute the situation to any managed system whose name contains the application name. For example, if the name of the attribute group is UL3SYSLOG00, you can distribute the situation to any managed system whose name takes the form hostname:UL300.

You can always distribute your situation to the *CUSTOM_AAARR Managed System List, where

AAA is the name of the application

RR is the version number of the metafile

but Candle recommends using specific system names for better performance.

Monitoring interval and time-to-live valueIf an application attribute group is defined as event (E) type data in the metafile NAME statement, you do not need to specify a monitoring interval for situations using attributes from that group. If the attribute group is of the sampled (S), polled (P), or keyed (K) data type, you need to take the time-to-live (TTL) value into consideration when you set the monitoring interval.

You specify a TTL to indicate how long the data provided by Data Providers should be considered valid for evaluation. The TTL value you specify affects both how situations are evaluated and what you see in the Customer workspaces.

When you create a situation and distribute it to a managed system, it gets evaluated by the Universal Agent. The Universal Agent ignores any data rows that have an expired TTL —that is, where the age of the data is greater than the TTL. This means that if you specify a small TTL relative to your situation sampling interval, your situation may not raise when you think it should. To avoid this, choose a situation sampling interval smaller than your TTL or increase your TTL.

The Universal Agent emits data for situation evaluation as long as the TTL has not expired. If the situation monitoring interval is shorter than the TTL, the situation remains raised for the duration of the TTL.



A sample set is one sample of data that consists of multiple rows of data. For example, if you are using the File Data Provider and you specify Copy mode in your SOURCE statement, you are indicating that your samples will consist of multiple rows of data, because of the nature of Copy mode processing. That is, every time the File Data Provider samples the log file it emits a sample set consisting of all records in the log file.

The Universal Agent treats the sample set as one sample. This means that the TTL you specify applies to the entire sample set. Once the TTL expires, none of the individual rows making up the sample set will be available for workspaces or for situation evaluation.


Historical Data Collection


OverviewYou can use the facilities of CandleNet Portal’s historical data collection function to store and save the data being collected by your Universal Agent agent or agents. The historical data collection function permits you to specify

� the attribute group or groups for which data is to be collected

� the interval at which data is to be collected

� the interval at which data is to be warehoused (if you choose to do so)

� the location (either at the agent or at the CMS) at which the collected data is to be stored

Information about using the Historical Data Collection function can be found in the CandleNet Portal online Help and in the Historical Data Collection Guide for OMEGAMON XE and CandleNet Command Center.



Introducing the SNMP Emitter 139

Introducing the SNMP Emitter

OverviewThis chapter provides an introduction to the Universal Agent SNMP Emitter. In addition, it includes instructions for installing and integrating the SNMP Emitter. A discussion of establishing parameters and using SNMP Emitter data concludes the chapter.

Chapter contentsUnderstanding the SNMP Emitter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Installing and Integrating the SNMP Emitter . . . . . . . . . . . . . . . . . . . . . . 142Using the SNMP Emitter and its Data . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

6

Understanding the SNMP Emitter



What is the SNMP Emitter?Increasingly, system administrators face the challenge of managing information in distributed, heterogeneous environments with multiple focal points and different management tools. The SNMP Emitter is an interface between OMEGAMON XE and third-party SNMP managers like HP OpenView, NetView, Tivoli, and CA-Unicenter.

The SNMP Emitter, also referred to as the SNMP Activity Agent, integrates information from Candle management products with data from third-party products on a single workstation. It sends event data monitored by Candle products to a third-party manager.

This is the preferred way of integrating best-of-breed solutions like OMEGAMON XE into the large-scale frameworks.

What does the SNMP Emitter offer?The SNMP Emitter:

� Simplifies system and application management - you can view alerts from applications, operating systems, and resources across your computing environment from a single focal point of your choice.

� Enhances system performance and availability - you can correlate information from different management tools to more effectively manage your networked systems.

� Increases efficiency - by sharing access to information, you can troubleshoot system problems more effectively. By using situations, you can ensure that you receive only those alerts you consider important.

� Provides flexibility - administrators and operators can use the management tools they are most familiar with to monitor information, regardless of where it is collected.

Which platform supports the SNMP Emitter?The SNMP Emitter is supported on all Universal Agent-supported platforms.



Which protocol does the SNMP Emitter support?The SNMP Emitter sends traps in SNMP Version 1 format.

How does the SNMP Emitter work?The SNMP Emitter uses native operating system services to communicate events to a designated SNMP management application running on any host. It has no dependencies on any operating system SNMP services and can co-exist with other operating system SNMP services. When an event occurs—that is, when the status of a situation monitored by an OMEGAMON XE product changes from False to True—the CMS collects and stores information about the event. If a Universal Agent policy with the SNMP Emitter exists, an SNMP trap is forwarded to a designated SNMP manager.

SNMP Emitter environment variablesYou designate the host(s) to receive the traps in one of two ways:

� an environment variable named KUMP_TRAP_DESTINATION

� the Trap Destination parameter in the SNMP Emitter’s policy definition

An SNMP trap contains an SNMP community name, which an SNMP manager can choose to use. By default, this is the public community name. You can change this default name to another name via environment variable KUMP_TRAP_EMIT_COMMUNITY.

KUMP_TRAP_DESTINATION

� No default

� Defines the hostname(s) where SNMP managers are running. Multiple hostnames must be separated by commas.

KUMP_TRAP_EMIT_COMMUNITY

� Default is <public>

� Defines the community name for which the SNMP manager is configured.

Installing and Integrating the SNMP Emitter


Installing and Integrating the SNMP Emitter

Installing the SNMP EmitterTo install the SNMP Emitter:

1. Install the Universal Agent. The SNMP Emitter feature is fully integrated into the Universal Agent installation, and the SNMP Emitter starts automatically when the Universal Agent is started.

2. The SNMP Emitter’s catalog file kum.cat needs to be located in your hub CMS’s RKDSCATL directory.

3. The SNMP Emitter’s attribute file kum.atr needs to be located in your hub CMS’s ATTRLIB directory. If you have an MVS-based CMS, then you need to install the KUMATR and KUMCAT files into your RKANDATV PDS.

4. The SNMP Emitter’s ODI file dockum needs to be located in your CandleNet Portal Server’s CNPS directory.

Note: There is no required connection or dependency between the SNMP Data Provider and the SNMP Emitter. In other words, you can use the SNMP Emitter without activating the SNMP Data Provider. You can also use the SNMP Emitter to emit traps for other agent products besides the Universal Agent.

Integrating the SNMP Emitter into third-party solutionsThe traps sent out by the SNMP Emitter need to be integrated into an SNMP manager and its console. Examples of SNMP managers are HP OpenView or IBM NetView. To enable these solutions to interpret the trap information (multiple fields) properly you must announce its structure. The structural information is stored in the files CANBASE.MIB and CANSYSSG.MIB, distributed with the Universal Agent product.These files are located in the $CANDLEHOME/$ARCH/um/mib directory on UNIX platforms and the \candle\cma directory on Windows platforms. However, announcing the information to the specific SNMP manager is different for each manager. Please refer to your SNMP Manager's manuals for information on how to accomplish this task.


Using the SNMP Emitter and its Data


Establishing SNMP Emitter parametersThe SNMP Emitter is accessed from within the CNP workflow editor. Create the OMEGAMON XE situations you wish to monitor first. With your situations in place, you can create one or more policies where the initial activity is the situation evaluation and a subsequent activity is the SNMP_Event activity. When you select the SNMP_Event icon from the workflow components "Emitter activities" tab, you are prompted for the following parameters in the Emitter Settings dialog:

1. Emitter target - Select any Universal Agent DP managed system from the dropdown box. We recommend you select one of the DP managed systems associated with the UAGENT application. These all have managed systems called:

instname_hostNamedpName:UAGENT00

where instname is the instance name of UA if a non-primary copy is running, hostName is the DNS host name where the DP is running and dpName is the Data Provider name (for example, ASFS or SNMP).

2. Severity - Select from the predefined list: � Cleared

� Indeterminate

� Warning (default)

� Minor_error

� Critical

� Major

3. Category - Select from the predefined list: � Threshold_Events (default)

� Network_Topology_Events

� Error_Events

� Status_Events



� Node_Configuration_Events

� Application_Alert_Events

� All_Category_Events

� Log_Only_Events

� Map_Events

� Ignore_Events

4. TrapDestination - Enter one or more IP addresses/host names to receive the traps. If a host name is used, it must be a resolvable DNS name. If more than one entry is specified, you must separate them by commas (for example, Granite, 10.60.152.53, athens).As an alternative approach, you can specify the enviroment variable KUMP_TRAP_DESTINATION in the Universal Agent environment variables file. This variable follows the same format and rules as TrapDestination. If the TrapDestination parameter is left at _DEFAULT, then the alerts are sent to the hostname(s) identified via KUMP_TRAP_DESTINATION.

Note: You do not need to specify both the TrapDestination parameter in the Emitter Settings dialog and the KUMP_TRAP_DESTINATION environment variable. Either can be specified. If both are specified, the TrapDestination parameter takes priority. As a usage recommendation, specifying the TrapDestination parameter in the Policy definition allows for more granularity if there's a need to send different traps to different SNMP managers. But if the destination is always the same group of one or more IP addresses, and you have to create many policies, then it's more convenient to set the KUMP_TRAP_DESTINATION environment variable in UA and leave the policy TrapDestination values as _DEFAULT.

5. Attributes - Select attributes associated with the situation being monitored from the second pop-up window. A maximum of 10 attributes can be selected. The values from the attributes you select are forwarded as part of the SNMP trap in the variable binding list.

6. The default radio button selection, "Invoke emitter once for each data row", can be left as is.

7. After you've filled in the Emitter Settings dialog, click OK to save your selections.



8. Distribute the policy to a managed system that is of the same type as the managed system to which the policy's situation was distributed. For example, if the situation was for the Candle Windows agent and was distributed to one of its related managed systems, then the policy needs to also be distributed to a managed system associated with the Candle Windows agent.

Using SNMP Emitter dataViewing SNMP Emitter data varies from one SNMP management application to another. To help your SNMP management application interpret the data, we supply an SNMP Management Information Base (MIB) file. Following is the trap description using the standard MIB TRAP-TYPE macro.

candleEvent TRAP-TYPE

ENTERPRISE candle-Alert-MIB

VARIABLES {

sitName,

sitCurrStat-OriginNode,

sitCurrStat-LocalTimeStamp,

sitCurrStat-Severity,

sitCategory,

sitCurrStat-Predicates,

sitAttributeList

}

DESCRIPTION

“An OMEGAMON XE situation threshold was exceeded. This trap was generated by the Candle Universal Agent SNMP Emitter in response to a situation threshold being exceeded.”

::= 8

You will always see this data in your trap's variable binding list. What you see for the sitAttributeList often varies and depends on which attributes you select when editing the SNMP Emitter's parameters in the policy editor. A complete description of these variables is in the CANSYSSG.MIB file. This MIB file depends on the CANBASE.MIB file, so you need both.



If you want to integrate OMEGAMON XE into another 3rd-party SNMP Manager product, use these two MIB files and follow the instructions of that particular product.

Appendices 147

Appendices


Data Definition Control Statements 149

Data DefinitionControl Statements

OverviewThis appendix contains the descriptions and syntax for the control statements used to create a data definition metafile.

Appendix contentsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150SNMP Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151WBEM Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152APPL Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153NAME Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154INTERNAL Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158SOURCE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162RECORDSET Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168CONFIRM Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173SQL Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174SUMMARY Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176ATTRIBUTES Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Metafile Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

A

Introduction


Introduction

The command statements described in this appendix are used to create the data definition metafile that defines an Universal Agent application. Some of the statements are used only for specific Data Providers.

If present, the statements must appear in the metafile in the following order:

//SNMP or //WBEM

//APPL

//NAME

//INTERNAL

//SOURCE

//RECORDSET

//CONFIRM

//SQL

//SUMMARY

//ATTRIBUTES


SNMP Statement

SNMP Statement

DescriptionThis statement introduces the data definition for a customized SNMP application and is only used for the SNMP Data Provider. It must precede the APPL statement that names the application.

Syntax//SNMP TEXT

ParameterThe SNMP statement must contain the parameter TEXT.

WBEM Statement


WBEM Statement

DescriptionThis statement introduces the data definition for a WBEM application and is only used for the WBEM Data Provider. It must precede the APPL statement that names the application.

Syntax//WBEM TEXT

ParameterUnlike the SNMP statement, the TEXT parameter is optional.


APPL Statement

APPL Statement

DescriptionThe APPL statement specifies the name used by the OMEGAMON XE for your Universal Agent application. A metafile data definition always defines a complete application.

� Only one APPL statement may be written per metafile.

� The APPL name must be unique. If two different metafiles include application definitions with the same APPL name, even though the content is different, the second metafile is not loaded.

Syntax//APPL applname [@help text]

Parametersapplname is the name of the Universal Agent application you want to monitor.

� An application name must contain at least 3, but not more than 20 characters.

� The first 3 characters must be unique in an enterprise.

This is a very important point to remember. Activating two UA metafiles with the same first 3 characters in their //APPL statement will lead to unpredictable results, such as empty reports and frequent application version changes (if the two metafiles have different attributes, attribute groups, etc.).

� The application name cannot start with the character K, which is reserved for Candle products.

help text (optional) defines the help text for this application.

� The text must be preceded by the ‘at’ (@) sign.� The text must not exceed 245 characters.� Commas (,) are converted to spaces in help text.

NAME Statement


NAME Statement

DescriptionA NAME statement defines the name of an attribute group, the type of data being collected, and the period for which the data is valid.

� There must be at least one, and up to 64, NAME statements in a metafile.

� Each NAME statement must be followed by its associated SOURCE statement (if any) and ATTRIBUTES statements.

Syntax//NAME attribute-group-name method [time-to-live][AddSourceName][AddTimeStamp][Interval=][@help text]

ParametersThe following parameters are positional: attribute-group-name, method, and time-to-live. If specified, they must appear in the sequence shown above. The parameters are separated by a space.

attribute-group-name is the name of an attribute group. The name identifies a set of data definitions.

� An attribute group name can contain up to 32 characters.

� This parameter is required.

method specifies the nature of the data. Four modes are supported:

P Polled (default). Polled data becomes available periodically and only the latest set of values is available for situation monitoring and reporting.

S Sampled. Sampled data behaves in the same way as polled data except that more than one set of attribute data values may be available for use.

E Event. Event data occurs unpredictably and is reported as it becomes available.


NAME Statement

K Keyed. Keyed data behaves in the same way as sampled data, but allows you to correlate events. Up to five attributes in each group can be designated as key attributes.

For example, an application checks machine status such as CPU utilization and network data traffic rate every 30 seconds. This is polled or sampled data. Network alerts or console messages, which occur at unpredictable intervals, are event data.

time-to-live (TTL) (optional) defines the time interval for which data can be considered valid by the Universal Agent. Sample data should be available well before the expiration of its published TTL interval. After the TTL interval, the data should be discarded or a new sample should have already arrived.

� TTL is specified in seconds.

� The default TTL is 300 seconds.

� In general, the specification of the TTL in the metafile should be greater than the frequency at which a program exports data. For example, if a program provides data samples every minute, the TTL can be specified as 90 seconds. This value allows the Universal Agent to always maintain a current sample of data. If the TTL is less than the interval of data availability, the Universal Agent discards the data before the new sample has arrived and has no data.

� Operationally, the TTL determines the delay before the status of a data source changes from on-line to off-line on CandleNet Portal. For example, an Universal Agent application supplies data to the OMEGAMON XE using a TCP socket and specifies a TTL of 30 minutes. If the client program closes the socket and disconnects from the Data Provider at 3:30 P.M., the off-line status is not reported to the OMEGAMON XE until 4:00 P.M. The same delay applies to applications supplying data to an API Server Data Provider using the API call dp_EndInput.

� For keyed data, the TTL serves an additional purpose. Key attributes are identified as candidates for correlation if the difference between the arrival of their last data values and their new data values is less than the TTL.

� You must specify a TTL even for Event data for any application which uses a TCP socket connection when KUMP_TCP_DISCONNECT_BY_TTL=Yes (the default).

AddSourceName (optional) instructs the Universal Agent to add the attribute DataSourceName to the defined attribute group for File, API, and

NAME Statement


Socket Data Providers. This attribute contains the name of the node from which the data originates. For example, if a socket client program is running on machine PROD1 and connecting to the Universal Agent at HQ1, the DataSourceName is PROD1.

invisible attribute group (optional) refers to a definition used solely to filter or redirect data. This data is typically used by the Data Provider for input application data manipulation. Precede the attribute group name with a ~ symbol to make it invisible:

//NAME ~attribute-group-name method [time-to-live] [AddSourceName] [@help text]

An invisible attribute group is not part of the customer application from the CMS, CandleNet Portal, and end user perspective. By defining an attribute group as invisible, you can “hide” unneeded attribute definitions, icons, and workspaces.

timestamp insertion (optional) allows you to insert a timestamp attribute. Application data often must be correlated with other data based on timestamps. For example, application events are often related to specific network activities or an operating system status. Although application input data frequently does not include a time attribute field, Universal Agent supports the automatic insertion of a LocalTimeStamp attribute when requested. The metafile //NAME statement AddTimeStamp keyword

//NAME Attribute-group-name method [time-to-live] [AddTimeStamp] [@help text]

enables this feature.

If you prefer a more traditional YYYY/MM/DD HH:MM:SS uuu format, you can specify

AddTimeStamp=YearMonth

on the //NAME statement and this will generate a 24-byte LocalTimeStamp attribute.

The Universal Agent generates a standard 16-byte timestamp for the LocalTimeStamp attribute dynamically at runtime. The format is CYYMMDDhhmmssuuu, where C specifies the century and uuu specifies the milliseconds.


NAME Statement

Interval (optional) specifies the sampling interval in seconds that should be used for ODBC table data collection, for example:

//NAME EMPLOYEES K 300 Interval=60

help text (optional) defines the help text for this attribute group.

� The text must be preceded by the ‘at’ (@) sign.� The text must not exceed 245 characters.� Commas (,) are converted to spaces in help text.

INTERNAL Statement


INTERNAL Statement

DescriptionData redirection is very useful for application data that contains variable data types, such as a transaction log file that includes several types of data records, or for application data that is too complex to construct a single attribute group definition to handle reliably. In addition, data redirection can be used in situations where data is received once, but redirected to multiple targets to be manipulated differently, such as different attribute filters, summarization intervals, or summarization keys. The //INTERNAL statement defines the data redirection source or target attribute group(s). The redirected application data is identified by symbolic-name, which must be unique for all currently active applications. Application data can be redirected from one application attribute group to other application attribute groups.

Syntax//INTERNAL [INPUT | OUTPUT] symbolic-name

Parameters

OUTPUT statement

The INTERNAL OUTPUT statement defines the source of the data redirection. There can be only one source attribute group per redirection identified by the symbolic name. All application data sources are supported such as file, socket, or API. The attribute group data becomes eligible for redirection after passing all defined attribute filters.

INPUT statement

The INTERNAL INPUT statement defines the target of the data redirection. Having multiple target attribute groups from one redirected source output is supported. However, a target attribute group cannot itself be the source of another redirection.

The Universal Agent redirects data for an attribute group exactly as if it arrived from a standard data source such as file, socket, API program, or SNMP. All Universal Agent features and services are available, including attribute filters.


INTERNAL Statement

In the following example, the claim details log file is read once. The file records are redirected to two subsequent attribute group definitions, ClaimInquiry and ClaimRequest, for further processing.

//NAME TransactionLog e//SOURCE FILE /users/Claim/DETAILS.log//INTERNAL OUTPUT ClaimDetailRec//ATTRIBUTES ','RecData R 4096*//NAME ClaimInquiry e AddTimeStamp//INTERNAL INPUT ClaimDetailRec//ATTRIBUTES ','RecType D 1 -FILTER={MATCH(0,3)}ClaimID C 9999ClaimType C 99CustomerSSN D 9. . . . .. . . . .. . . . .*//NAME ClaimRequest e//INTERNAL INPUT ClaimDetailRec//ATTRIBUTES ','RecType D 1 -FILTER={MATCH(0,2)}CustomerName D 64CustomerSSN D 9CustomerAddr D 100. . . . .. . . . .. . . . .

In the following example, the internet server log is first processed by attribute group WEB_W3C_Log. It selects data by excluding file records without client location or request content, or with no data transferred. The selected file records are then passed to attribute groups Error_STAT and DataTransfer_STAT.

The Error_STAT is only interested in error codes greater than 200 and a few selected attributes. All other attributes are defined as SKIP type so that they will not be visible to the end-user.

INTERNAL Statement


The DataTransfer_STAT attribute group shows the bytes exchanged between the client and the server. It is only interested in client identity, request, and the bytes count.

Two additional derived attributes are defined to show the total byte count and the percentage of input data of the total data count. These derived attributes are TotalBytes and PercentReceived.

//NAME WEB_W3C_Log e//INTERNAL OUTPUT InternetLog//ATTRIBUTES ','ClientLocation D 32 -FILTER={MATCH(0,-)}ClientUserName D 32 Date D 12Time D 12Service D 32ComputerName K 64ServerAddress D 32RequestElapsedTime C 99999999 BytesReceived C 99999999 –FILTER={NUMBER<=(0,0)}BytesSend C 99999999 ServiceStatus C 99999999 WindowsStatus C 99999999OperationName D 32OperationObject D 256 -FILTER={MATCH(0,-)}RequestParameters D 256*//NAME Error_STAT e//INTERNAL INPUT InternetLog//ATTRIBUTES ','ClientLocation D 32 SkipField1 KDate D 12Time D 12Service D 32SkipField2 KSkipField3 KSkipField4 KSkipField5 KSkipField6 KServiceStatus C 99999999 –FILTER={NUMBER=(0,200)}WindowsStatus C 99999999


INTERNAL Statement

OperationName D 32OperationObject D 256RequestParameters D 256*//NAME DataTransfer_STAT e//INTERNAL OUTPUT InternetLog//ATTRIBUTES ','ClientLocation D 32 SkipField1 KDate D 12Time D 12Service D 32SkipField1 KSkipField2 KSkipField3 KBytesReceived C 99999999BytesSend C 99999999TotalBytes (BytesReceived + BytesSend)PercentReceived (BytesReceived % TotalBytes) SkipField4 KSkipField5 KSkipField6 KOperationObject D 256*

SOURCE Statement


SOURCE Statement

DescriptionThe SOURCE statement defines the location and characteristics of the data being collected.

� When the SOURCE statement is specified, it must follow immediately after the NAME statement.

� Each SOURCE statement specifies one source.

� The SOURCE statement is not required for Data Providers that use the Universal Agent APIs.

� The SOURCE statement is not required for Socket Data Providers if the metafile has only one group of attributes that are reported via socket. However, if the SOURCE statement is omitted, the sending program must use an explicit application association record that identifies the corresponding metafile.

Syntax //SOURCE type location [file-mode] [code-type] [user=] [pswd=][maxrows=][ManagedSystemName=]

ParametersAll parameters are positional. If specified, they must appear in the sequence shown above.

type specifies the form of the data source.

FILE indicates that the data source is a local file.

ODBC indicates that the data source is a relational table.

SOCK specifies data that arrives via a TCP/IP socket. A NAME statement may have multiple sock sources.

location

� For sources of the type FILE, location is the file name.

– The file name may be case-sensitive on some operating systems. Specify the name according to the requirements of the target system.


SOURCE Statement

– If the file exists in a directory other than the one where the Data Provider resides, the file name must be fully-qualified. That is, it must include the full path.

– Symbolic parameter and script file variable cannot be substituted.

– If the fully qualified file name contains any embedded blanks, enclose it in single quotes.

� For sources of the type SOCK, location is the internet dot decimal address or a resolvable host name, optionally followed by a port number. For example, sp2n03[4500] identifies a data source from host sp2n03, port 4500.

– If the port number is omitted, the first connecting application is assumed. In general, the port number is needed only if there are multiple sources for the same application from the same host.

– If host name is specified for the location but cannot be resolved to an address, the SOURCE statement is ignored.

� For sources of the type ODBC, location is the data source name.– It must be already have been configured in the ODBC Data Sources

applet on the Windows machine where the ODBC Data Provider is running.

– If the data source name contains any embedded blanks, enclose it in single quotes.

file-mode (optional) specifies either COPY, TAILBYRECORD, or TAIL monitoring mode. If this parameter is not specified, TAIL mode is the default.

COPY indicates that the file is acting as a communication medium. Each time the file is polled or sampled, the entire contents of the file are read as multiple rows of data. If the file contents are not cleared, the same file records will be input again. The COPY mode is invalid for the Event data type. This mode is also not appropriate for the Key data type because it nullifies the Key behavior of correlating data rows. The COPY mode requires that the log file have a minimum of two rows of data (because it operates in block mode and needs a beginning and end record). Otherwise, CNP will not display the data.

SOURCE Statement


TAILBYRECORD indicates that the file is cumulative but that the end-of-file mark doesn't change. Instead, the record count is checked at each sampling interval to determine when new records have been added.

TAIL indicates that the file is cumulative. Each time the file is read, only new records added to the end of the file are read for input.

When monitoring a file in TAIL mode, the File Data Provider behaves as follows:

� If file records are deleted from the monitored file (that is, the total file size is reduced), the File Data Provider assumes that the monitored file has been recreated and begins processing from the beginning of the file.

� If the content of the first file record has changed in any way, the File Data Provider assumes that the monitored file has been recreated and begins processing from the beginning of the file.

� If the monitored file does not exist at Universal Agent startup time and is later created, the File Data Provider processes the monitored file from the beginning.

� Copying a cumulative application file to an existing file currently being monitored does not cause any change in the monitoring. If the copied file is not a cumulative file of the monitored file, the Data Provider begins processing from the beginning of the file.

� The File Data Provider experiences a brief delay in recognizing that a monitored file has been recreated or copied. For event data, the delay is the interval set by environment variable KUMP_DP_EVENT or the default of 15 seconds. For sampled data, the delay is the TTL divided by the sample factor defined by environment variable KUMP_DP_SAMPLE_FACTOR or the default sample factor of 5. For example, a delay of up to 3 minutes (180 seconds) should be expected for a monitored file with a TTL of 900 secords.

code-type (optional) specifies the character code page of the source data. The default is ASCII:

A ASCII

E EBCDIC

� The code-type parameter is valid only for the SOCK source type. It is ignored for all other source types.


SOURCE Statement

� If the code-type of the source differs from its own data representation, the Data Provider translates the application data it receives into the character data type of the local machine.

user (optional) specifies a userid that will connect to the ODBC data source. This parameter is only valid for the ODBC source type. It is ignored for all other source types. If multiple userids have been defined to the data source, choose a userid with sufficient authority to perform the table selects specified on the //SQL statement.

pswd (optional) specifies the password that is to be used with the associated user= parameter when connecting to the ODBC data source. This parameter is only valid for the ODBC source type. It is ignored for all other source types. The pswd= parameter must be preceded by a user= parameter, for example

//SOURCE ODBC 'Candle Data Warehouse' user=sa pswd=candle

database (optional) indicates a specific database context for the user/pswd to connect to. This parameter is only required for those database products that support multiple database associations for a single data source. If you wish to connect to a database context other than the default, then you should supply this parameter, for example:

//SOURCE ODBC cnps user=sa pswd=candle database=pubs

server (optional) specifies the name of the server that is to be used with the associated database= parameter. Again, this parameter is only necessary if the default database/server connection is not appropriate for the user tables you wish to access.

maxrows (optional) specifies the maximum number of rows that will be processed by the ODBC DP after executing the Select statement or stored procedure listed on the //SQL statement. For example,

//SOURCE ODBC cnps user=Admin pswd=xyz maxrows=1000

tells the ODBC DP to process up to 1000 rows for this attribute group. The default maxrows value is 100. It can be changed globally with the KUMP_ODBC_MAX_ROWS environment variable. The maxrows parameter is only valid for the ODBC source type. It is ignored for all other source types.

If more rows than the maxrows limit are returned from the metafile's SQL Select statement, only the first nnn rows up to that limit will be used for reporting and situation evaluation. This is an important point to remember. If

SOURCE Statement


you have a situation against an ODBC table that isn't firing when it should, it could mean that the row or rows which would cause the situation to fire happen to come after the maxrows limit. The solution to the problem is either (1) increase the maxrows value for that particular table by using maxrows=nnn-or change it globally via KUMP_ODBC_MAX_ROWS-so that maxrows is big enough to handle the expected number of returned rows, or (2) use a more qualified Where clause in the Select statement so that the number of returned rows will fit within the current maxrows limit.

The disadvantage of increasing maxrows to a very high number in order to handle large volumes of returned SQL table data is the increased system overhead caused by storing all of these rows in memory until their time-to-live value has expired. So a balance needs to be achieved between setting maxrows high enough to process all rows of interest, and low enough to not place an unnecessary memory and CPU burden on the ODBC DP.

ManagedSystemName (optional) enables you to specify multiple sources for FILE type data, uniquely identifying each. For example, the metafile definition

//APPL MVS

//NAME SYSTEM

//SOURCE FILE abc.log tail ManagedSystemName=Boston

//SOURCE FILE xyz.log tail ManagedSystemName=Chicago

//SOURCE FIlE mno.log tail ManagedSystemName=LosAngeles

results in the creation of three managed systems:

Boston:MVS00

Chicago:MVS00

LosAngeles:MVS00

A maximum of 128 ManagedSystemName source statements can be specified.

You cannot have two identical ManagedSystemName values in the same attribute group. In other words, the following metafile would be incorrect:

//APPL MVS

//NAME SYSTEM


SOURCE Statement

//SOURCE FILE abc.log tail ManagedSystemName=Boston

//SOURCE FILE xyz.log tail ManagedSystemName=Boston

In order to keep the multiple file sources unique, the ManagedSystemName values must be unique.

RECORDSET Statement


RECORDSET Statement

DescriptionThe RECORDSET statement, which is for File Data Providers only, enables the File Data Provider to extract attribute data from multiple records. The statement specifies:

� a delimiter pattern that indicates the end of a record set� the maximum number of records that comprise the record set, or � the maximum number of records that comprise the record set and a rule

for identifying either the beginning or end of the record set

SyntaxFormat A: end-of-record delimiter pattern

//RECORDSET ‘delimiter_pattern’

Format B: maximum number of records in set

//RECORDSET maximum_number_of_records

Format C: maximum number of records and identification rule

//RECORDSET maximum_number_of_records NEW(offset,== | !=,comparison_string)

or

//RECORDSET maximum_number_of_records END(offset,== | !=,comparison_string)

Parametersdelimiter pattern specifies the pattern for the end of a record set. The delimiter must be enclosed by single quotes (‘ ‘). Data exceeding the defined attribute size is truncated to the defined size.

The end-record-set delimiter record is used only to delimit a record set and is discarded. It should not contain valid attribute data.


RECORDSET Statement

Example 1 shows the definition for an attribute group named ERRORLOG, using the record set delimiter. In this case, the Data Provider reads and concatenates all file records until it encounters 1) a record containing the specified delimiter pattern (ten dashes), or 2) the end-of-file condition.

//NAME ERRORLOG E//SOURCE FILE c:\error.log tail//RECORDSET ‘----------’//ATTRIBUTES NONEError_Message R 2048

Example 2 shows the definition of an attribute group named CONSOLELOG, in which a semicolon (;) delimits the attributes. In this example, the Data Provider reads multiple records to extract the values for the five defined attributes until it

� encounters the end-record-set pattern� fills all five attributes, or� reaches the end-of-file condition.

//NAME CONSOLELOG E//SOURCE FILE c:\console.log tail//RECORDSET ‘----------’//ATTRIBUTES ‘;’Message_Date D 12Message_Time D 8Message_ID D 8Message_Text D 512Message_Action D 512

maximum_number_of_records indicates the maximum number of records that the Data Provider should read in a record set.

In example 3, the attribute group APPLALERT contains only one attribute of the type Record. The Data Provider reads and concatenates all file records up to a maximum of 4 or until it reaches the end of the file, whichever comes first.

//NAME APPLALERT E//SOURCE FILE c:\alert.log tail//RECORDSET 4//ATTRIBUTES NONEAlert_Description R 2048

RECORDSET Statement


In Example 4, the Data Provider uses the attribute delimiter (a blank space) to extract values for the seven attributes by reading file records until it

� has read four records� has filled all seven attributes, or� reaches the end of the file.

//NAME NETALERT E//SOURCE FILE c:\net.log tail//RECORDSET 4//ATTRIBUTES ' 'Alert_Date D 12Alert_Time D 8Alert_ID D 16Alert_Type C 99Alert_Severity C 99Alert_Origin D 64Alert_Text D 256

maximum records and identification rule specifies both the maximum number of records in the record set and a rule for identifying the beginning or end of the set. The identification rule defines the offset in a file record, the comparison operator (equal [==] or not equal [!=]), and the comparison string. The delimiting record is treated as part of the record set and is not discarded.

The keyword NEW indicates a rule for beginning a record set. In this case, the Data Provider processes file records from the current file position up to, but not including the record that satisfies the comparison criterion, or until

� the specified maximum number of records has been processed� all attributes have been filled, or� the end of the file is reached.The keyword END indicates a rule for the end of a record set. In this case, the Data Provider processes records from the current file position up to and including the file record that satisfies the comparison criterion, or until

� the specified maximum number of records has been processed� all attributes have been filled, or� the end of the file is reached.In the data definition in example 5, a record set consists of from one to twenty file records and each new record set is identified by a nonblank at offset 0. Thus, in the monitored file shown, each new record set begins with the date.


RECORDSET Statement

Since there is no attribute delimiter, all the records until the next date are read into the attribute Status_Record.

//NAME STATUS_LOG E//SOURCE FILE c:\status.log tail//RECORDSET 20 NEW(0,!=, )//ATTRIBUTES NONEStatus_Record R 2048

Sat Jun 29 18:47:41 2002Msg #UM12751 Entering UPDATE Mode

Sat June 29 18:47:41 2002Msg #UM1202E Error in parameter fileFIX: See additional messages.(0,2) STATUS.DATNo such file or directory

Sat Jun 29 18:47:42 2002Msg #KA3129E Error occurred while testing for remoteinitiationMsg #KA1709E Error occurred during a GET ALLOCATE verbThere was an error checking for a remote request ofUPDATE functions.FIX: (OS/2 or Windows) Verify that you have configuredfor remotely attachable programs correctly.Primary return code = f0040000

Missing attribute delimitersFor multiple record input, the File Data Provider is programmed to accommodate missing or omitted attribute delimiters at the beginning or the end of a record. For the following application:

//APPL NewClass//NAME PHYSICS101 K//RECORDSET 4//ATTRIBUTES ';'First_Name D 24 KEYLast_Name D 24 KEYGrade D 1Telephone D 14

RECORDSET Statement


the following records are acceptable:

Bob;Smith;B;(555) 323-1919Susan;BarberB(555) 323-2346;JackThomasA(555) 323-5656

If an attribute definition specifies both beginning and ending delimiters, as in the following definition:

//APPL NewClass//NAME CHILD_PSYCHOLOGY221 K//SOURCE FILE c:\psy221.log//RECORDSET 4//ATTRIBUTES '@;'First_Name D 24 KEYLast_Name D 24 KEYGrade D 1Telephone D 14

the following file records are acceptable:

Bob;@Smith;@B;@(555) 323-1919Susan;@Barber@B(555) 323-2346;JackThomasA(555) 323-5656


CONFIRM Statement

CONFIRM Statement

DescriptionThe CONFIRM statement provides a vehicle for specifying data acknowledgment requirements and is for Socket Data Providers only. This statement must appear after the attribute group NAME statement and before the ATTRIBUTES statement.

Syntax//CONFIRM confirmation_type

Parametersconfirmation_type specifies the type of confirmation required, which can be:

SIZE The Data Provider acknowledges receipt of data by returning the data length as a 32-bit unsigned integer, in network byte order.

SEQ The Data Provider acknowledges receipt of data by returning the data record sequence number as a 32-bit unsigned integer, in network byte order. For each new TCP connection or new UDP exchange, the sequence number starts from one and wraps accordingly.

Xnn The Data Provider acknowledges receipt of data by sending the specified hexadecimal character nn, for example, X70.

‘message’ The Data Provider acknowledges receipt of data by sending the specified message character string. The message must be enclosed in single quotes: ‘Data received.’

If the client program and the Data Provider are on dissimilar machines, the Data Provider translates the message into the format of the system of the client before transmission.

SQL Statement


SQL Statement

DescriptionThe SQL statement tells the ODBC Data Provider what table data to select from the data source specified on the //SOURCE statement. One //SQL statement is required for every //SOURCE ODBC statement.

Syntax//SQL [Select statement] [proc=stored procedure]

ParametersSelect statement specifies an SQL Select of any type or form that is supported by the data source being accessed, for example,

//SQL Select * from sysxlogins

Although this example uses a simple Select statement, there is nothing to prevent you from exploiting additional SQL features, such as ORDER BY, GROUP BY, nested Selects, built-in functions, and so on. You can select individual columns as well as columns from multiple tables. As long as the ODBC driver supports the feature-and in most cases the drivers support all of the standard SQL query syntax-then it can be used in an ODBC metafile.

The Universal Agent metafile parser does not examine the contents of the //SQL Select statement for possible syntax errors. Whatever string is contained on the statement gets passed to the ODBC driver, and it is the driver software that does the work of parsing the statement and preparing it for execution. One consequence of this approach is that if there are any syntax errors in the //SQL Select statement, they will not be detected until the ODBC metafile has been imported and the first attempt to execute the statement is made by the ODBC DP. At that time, the syntax errors will be written to the Universal Agent RAS1 log. Therefore, it is a good idea when possible to test the Select statement through an SQL ad hoc query tool or command line utility before inserting it into the metafile.


SQL Statement

proc=stored procedure specifies a stored procedure that performs an SQL Select against the data source being accessed.

� If the stored procedure name contains any embedded blanks, it must be surrounded with single quotes.

� If there are input parameters to the stored procedure, they must be blank-separated tokens after the stored procedure name.

SUMMARY Statement


SUMMARY Statement

DescriptionThe //SUMMARY statement defines the requirements for gathering the frequency of data input during monitoring. At a minimum, the requirements include a defined interval and if appropriate, defined sort keys.

The resulting output attribute group consists of timestamp, interval, key attributes, and occurrence (total count). Attributes that are not defined as key attributes are not included in the output attribute group.

Only one //SUMMARY statement is allowed per //NAME statement. This statement should appear after the //NAME statement and before the //ATTRIBUTES statement.

Syntax//SUMMARY [interval]

attribute-name attribute-type maximum-size SKEY=n

ParametersThe summary of data occurrence is particularly useful in situations where the frequency of input is more important than the input data details. For example, when the Universal Agent is monitoring alerts received from a device, all alerts are of some significance. However, it is the total number of alerts received in a period of time that may indicate problems.

Use the filtering option (Accept Filters or Reject Filters) to limit the scope of the summary. The summarization takes place after the input data is filtered.

The application data must include the LocalTimeStamp attribute. If the data does not include this timestamp attribute, then it could be added by using the AddTimeStamp keyword specified in the //NAME statement. Otherwise, the Universal Agent automatically inserts it at runtime. The LocalTimeStamp attribute value and the interval defined in the //SUMMARY statement trigger the summarization process.

Attributes that are not defined as key attributes are not included in the output. This does not mean that detail application attributes are not available. You can define an attribute group with or without filters for detail monitoring of


SUMMARY Statement

application data. And you can redirect the application data to one or more additional attribute groups for summary using various attributes as sort keys.

The interval parameter specifies the summarization period in seconds. The minimum interval value is 60 (1 minute) and the maximum interval value is 86400 (1 day). The default of 300 is used if an interval is not specified.

Any attribute (display or numeric) can be a summarization sort key. An attribute group can include either no sort keys or sort keys representing all attributes in the attribute group. The SKEY=n keyword identifies an attribute as a summarization sort key. The n sequence number specifies the sort order (such as 1, 2, 3 for sorting first, second, and third).

An attribute group without a sort key definition is summarized by LocalTimeStamp interval only. The output consists of one row of data per interval. An attribute group with sort keys is summarized by the LocalTimeStamp interval and breaks on each sort key. Its output includes as many rows as there are unique sort key combinations per summary interval.

Example 1The following metafile specifies an hourly request summary:

//APPL eLog//NAME ServerLog e//INTERNAL OUTPUT InternetLog//ATTRIBUTES*-------------------------------------------** Apache Server Log Record Format Layout **-------------------------------------------*ClientLocation D 256ClientUserName D 32Authorized_User K 32Date_Time DL 20Time_Zone K 5Request D 256 DLM='' –FILTER={MATCH(0,-)}ServiceStatus C 999BytesReceived C 99999999Referral D 256 DLM='/"'Browser D 256 DLM='""'Service D 32ServerName D 256RequestParameters D 256

SUMMARY Statement


BytesSent C 99999999RequestElapsedTime C 99999999*//NAME RequestSummary e//INTERNAL INPUT InternetLog//SUMMARY 3600//ATTRIBUTESLogRecord R 2048

The log records are redirected to the attribute group RequestSummary, which counts the number of records per hour. Log records without request information (-) are immediately rejected. The actual attributes that are presented for the RequestSummary attribute group include:

� LocalTimeStamp: the CT timestamp indicating the beginning of a summary interval

� Interval_Unit: as defined on //SUMMARY statement (3600)� Occurrences: the summary count

Example 2The following attribute group metafile definition shows an internet server log summary of an error status greater than 400 by request. Note that the bad requests (-) were already rejected on input.

//NAME RequestErrorStatus e//INTERNAL INPUT InternetLog//SUMMARY 86400//ATTRIBUTESClientLocation D 256ClientUserName D 32Authorized_User K 32Date_Time DL 20Time_Zone K 5Request D 256 SKEY=2 DLM=''ServiceStatus C 999 SKEY=1–FILTER={NUMBER>=(0,400)}BytesReceived C 99999999Referral D 256 DLM='/"'Browser D 256 DLM='""'Service D 32ServerName D 256RequestParameters D 256


SUMMARY Statement

BytesSent C 99999999RequestElapsedTime C 99999999*

The Universal Agent accumulates input log record data during the summarization interval. At the end of an interval, the accumulated data is sorted based on defined sort key(s), and then summarized. The following are the output attributes:

� ServiceStatus: the input status value� Request: the input request attribute value� LocalTimeStamp: the CT timestamp indicating the beginning of a

summary interval� Interval_Unit: as defined on //SUMMARY statement (86400)� Occurrences: the summary count

The output attributes of an attribute group that have been summarized always consist of key attributes, LocalTimeStamp, Interval, and Occurrences. Attributes that are not defined as key attributes are not included in the output.

Example 3You only need to define the metafiles in as much detail as necessary to correctly extract the key attributes for summarization. The abbreviated attribute group definition that follows results in the same output as the previous example:

//NAME RequestErrorStatus e//INTERNAL INPUT InternetLog//SUMMARY 86400//ATTRIBUTESPlaceHolder1 K 4PlaceHolder2 K 4PlaceHolder3 K 4

PlaceHolder4 K 4PlaceHolder5 K 4Request D 256 SKEY=2 DLM=''ServiceStatus C 999 SKEY=1 –FILTER={NUMBER>=(0,400)}*

If more input data fields are defined than attributes the Universal Agent stops interpreting input data at the last defined attribute. A timestamp is automatically inserted.

SUMMARY Statement


Total Counts for a summarizing IntervalApplication data frequently includes count fields such as the number of events, number of processes, and bytes sent or received. It is very useful to show total result counts for a summarizing interval. Any numeric attribute field can be totaled by specifying SKEY=SUM keyword parameter.

//SUMMARY [interval]

attribute-name attribute-type maximum-size SKEY=SUM

Example 4In the following example, the sent and received byte counts are totaled by ClientLocation each hour.

//NAME DataTransferByLocation e//INTERNAL INPUT InternetLog//SUMMARY 3600//ATTRIBUTESClientLocation D 256 SKEY=1PlaceHolder1 K 4PlaceHolder2 K 4Date_Time DL 20PlaceHolder3 K 4PlaceHolder4 K 4 DLM=''PlaceHolder5 K 4BytesReceived C 99999999 SKEY=SUMPlaceHolder6 K 4 DLM='/"'PlaceHolder7 K 4 DLM='""'PlaceHolder8 K 4PlaceHolder9 K 4PlaceHolder10 K 4BytesSent C 99999999 SKEY=SUMPlaceHolder11 K 4*

Note that special attribute delimiters are needed for interpretation of input data, even though the data contents are of no consequence. The attribute group outputs the following attributes:

� ClientLocation: the location information, such as address or node name� BytesReceived: the sum of this attribute value during this interval� BytesSent: the sum of this attribute value during this interval


SUMMARY Statement

� LocalTimeStamp: the CT timestamp indicating the beginning of a summary interval

� Interval_Unit: as defined on //SUMMARY statement (3600)� Occurrences: the summary count (number of records summarized)

Creating new attributesDerived attributes allow you to create new attributes based on existing defined attributes, including internal summarization attributes and results. The following attributes can be used to create derived attributes:

� _Occurrences: the summary count� _Interval_Unit: the defined summarization interval � Numeric attribute summarization result: a numeric attribute defined with

SKEY=SUM

Example 5The following example expands the previous metafile definition by specifying attributes for RequestsPerSecond, TotalBytesTransfer, BytesTransferPerSecond, and BytesTransferPerRequest for each client location:

//NAME DataTransferByLocation e//INTERNAL INPUT InternetLog//SUMMARY 3600//ATTRIBUTESClientLocation D 256 SKEY=1PlaceHolder1 K 4PlaceHolder2 K 4Date_Time DL 20PlaceHolder3 K 4PlaceHolder4 K 4 DLM=' 'PlaceHolder5 K 4BytesReceived C 99999999 SKEY=SUMPlaceHolder6 K 4 DLM='/"'PlaceHolder7 K 4 DLM='""'PlaceHolder8 K 4PlaceHolder9 K 4PlaceHolder10 K 4BytesSent C 99999999 SKEY=SUMPlaceHolder11 K 4*

SUMMARY Statement


RequestsPerSecond (_Occurrences / _Interval_Unit)*TotalBytesTransfer (BytesReceived + BytesSent) *BytesTransferPerSec (TotalBytesTransfer / _Interval_Unit)*BytesTransferPerReq (TotalBytesTransfer / _Occurrences)


ATTRIBUTES Statement


DescriptionThe ATTRIBUTES statement introduces the attribute definitions. It also allows specification of attribute delimiters in the data string. Each record that follows the ATTRIBUTES statement contains one attribute definition.

An attribute group may contain a maximum of 63 attributes, unless the KIB_MAXCOLS environment variable (which can be set to a maximum of 127) overrides it.

Syntax//ATTRIBUTES [delimiter-string]

Parametersdelimiter-string identifies optional delimiter characters that separate attribute data in input.

� Delimiter characters must be enclosed by single quotes. For example, ‘;’ indicates that the attribute fields in a data record are separated by a semicolon, as in the following example. Three single quotes (‘’’) indicate that the attribute fields are separated by a single quote. Leading, trailing, or in-between space characters are not removed.John;Doe;System Analyst;Engineering

� With single delimiters, the delimiter of the last attribute in the file record (Engineering in the preceding example) is optional and can be omitted, since the end-of-record indicator serves the same purpose as the delimiter.

� A double delimiter specification, such as ‘””’, indicates that the attribute fields are enclosed by beginning and ending delimiters.“John” “Doe” “System Analyst” “Engineering”

The beginning and ending delimiters need not be the same character. For example, you can specify the attribute delimiters as ‘$?’ for the file:

$John? $Doe? $System Analyst? $Engineering?

� With double delimiters, both beginning and ending delimiters are required for each attribute, including the last attribute in the data record. John Doe System_Analyst Engineering



� The keyword TAB specifies the horizontal tab character as the attribute delimiter://ATTRIBUTES TAB

� The special keyword NONE indicates that no delimiters are used://ATTRIBUTES NONE

If NONE is used, the attribute data values are retrieved by field offset and the defined attribute data length. No interpretation or data conversion is made to the data values. You must make certain that the data value types and sizes exactly match the attribute specification in the application metafile. If the data definition for the previous example used previously is the following:

//ATTRIBUTES NONEFirst-Name D 12Last-Name D 12Job D 20Department D 16

the data record should be:

John[8 spaces]Doe[9 spaces]System Analyst[6 spaces] Engineering[5 spaces]

The non-delimited data input also supports additional binary short- and long-integer data types. The data is copied directly from input records to memory. Therefore, it is important to ensure that the sending application and the Data Provider execute on machines with like system architectures, since integer size and its internal memory data representation are not interpreted.

� If no delimiter is specified, the attributes are assumed to be separated by a space. In this case, the data value can contain no spaces, as in System Analyst in the preceding example.

� The attribute specific delimiter feature allows you to override the attribute group delimiter when extracting a particular attribute data value. The attribute delimiter(s) is defined on the //ATTRIBUTES statement. The defined delimiters apply to all attributes in the attribute group. However, the application data is not always uniformly delimited.



For example, the following application specification

//APPL XYZ//NAME TransationLog e//ATTRIBUTESClientName D 32Date_Time DL 20Time_Zone D 5Transaction D 256TransactionSize C 99999999

is not able to handle the following sample log data:

dyang [01/Sep/2002:02:06:31 -0700] "GET /CCC99.html" 5914

Attributes are, in general, delimited by space characters. The attribute Transaction, in this example, is enclosed by double quotes. By defining the attribute Transaction with the attribute specific begin and end delimiters,

Transaction D 256 DLM=’””’

you can correctly parse the sample log data record (as GET /CCC99.html).

For all delimiter specifications, both single or begin and end delimiters are supported and should be enclosed by single quotes. There is no restriction on attribute-specific delimiters within an attribute group. In fact, you can define specific attribute delimiters for each attribute in a group.

Metafile Examples


Metafile Examples

OverviewThis section provides examples illustrating metafiles created according to the guidelines presented in the previous sections. For information about creating attribute definitions, see “Attribute Definitions” on page 189.

Metafile example 1This example illustrates an API Data Provider application named UXstat, comprised of one attribute group, UXsysSta. UXsysSta contains 22 attributes, using polled data with a TTL of 150 seconds. No SOURCE statement is required in this data definition because the data is sent using APIs.

//APPL UXstat @help text//NAME UXsysSta p 150 @help text//ATTRIBUTES SystemName D 16 @help textOSversion D 16 @help textPendingIOwaitRate C 100000 @help textIOstartRate C 100000 @help textIOcompleteRate C 100000 @help textAvgWaitThreadQueueSize C 4096 @help textAvgRunThreadQueueSize C 4096 @help textAvgNumbActivePageFrames C 100000 @help textAvgNumbFreePageFrames C 100000 @help textPageInRate C 65000 @help textPageOutRate C 65000 @help textDevInterruptRate C 65000 @help textSystemCallRate C 65000 @help textThreadContentSwitchRate C 65000 @help textAvgUserCPUPercent C 100 @help textAvgSystemCPUPercent C 100 @help textAvgIdleCPUPercent C 100 @help textAvgWaitCPUPercent C 100 @help textUDPpktInRate C 100000000 @help textUDPpktOutRate C 100000000 @help textTCPpktInRate C 100000000 @help textTCPpktOutRate C 100000000 @help text


Metafile Examples

Metafile example 2This second metafile example illustrates the definition of data extracted from a log file for an application named SysEvent. It consists of a single attribute group named ConLog, which uses event data collected in the TAIL mode.

//APPL SysEvent @help text//NAME ConLog E @help text//SOURCE FILE e:\system\event.log TAIL//ATTRIBUTES MessageID D 12MessageNumb C 999999MessageType D 1ProcessNumb C 9999TimeMonth D 3TimeDay C 31 TTimeYear C 9999TimeHour C 24TimeMinute C 60TimeSecond C 60MessageText D 100

Metafile Examples


Attribute Definitions 189

Attribute Definitions

OverviewThis appendix contains the description, syntax, and parameters for the attribute definitions used in creating a data definition metafile. It explores characteristics of attribute definitions that can enhance performance monitoring when creating a data definition metafile. In addition, this appendix discusses how to derive and filter attributes, and how to sequence attribute definitions.

Appendix contentsDefining Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190Exploring Attribute Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194Deriving Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198Filtering Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202Sequencing Attribute Definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

B

Defining Attributes


Defining Attributes

DescriptionAttribute definitions specify the name of the attribute, its type, and its maximum size. The order of the definitions must match the sequence of the data fields in the data record.

Syntaxattribute-name attribute-type maximum-size [KEY] [ATOMIC] [@help text]

Parametersattribute-name specifies the name of an attribute.

� Attribute names may contain up to 200 characters.

� Only alphanumeric, dash (-), underscore (_), and asterisk (*) characters are valid. An invalid character is automatically replaced by an underscore.

attribute-type Valid attribute types are:

S Switch. Boolean 0 or 1.

G Gauge. Positive or negative integer.

C Counter. Positive integer.

A Average. Data to be averaged over all collections.

D DisplayString. Series of characters.

N DisplayNumeric. Series of numeric characters.

T Time. The format is CYYMMDDHHMMSSmmm (where C=1 for the 21st century).

R Record. Read entire record until carriage control/linefeed character.

Z Last. Ignore specified delimiter and treat all input data from the current position to end of input data record as one field.

K Skip. Input positional field. Of no interest and should be skipped.


Defining Attributes

# Delta value. Presents the value of the attribute as the difference between samples. For example, if the value for sample 1 is 100 and for sample 2 is 120, the delta is 20.

% Percentage of change. Presents the value of the attribute as the difference between samples expressed as a percentage. For example, if ReceiveCount is defined as % data type, and the value for sample 1 is 100 and for sample 2 is 120, the percentage of change is 20.

? Rate of change. Presents the value of the attribute as the delta per second between samples. For example, if ReceiveCount is defined as ? data type, the value for the first sample is 100, the value for the second sample is 120, and the elapsed time between samples 1 and 2 is 5 seconds, the rate of change 4 per second.

If no value is given for an attribute when the data is sampled, a default value is assumed. The default value for an attribute type depends upon the method of data collection. For polled, sampled, and keyed data, the default value assumes the previous sample data value. The default values for event data are shown in Table 14.

Table 14. Default Values for Event Data

Attribute Type Default Value

S (Switch) 0

G (Gauge) 0

C (Counter) 0

A (Average) No change from current average

D (DisplayString) Space character

N (DisplayNumeric) 0

T (Time) Current time

R (Record) Not applied

Z (Last) Space character

K (Skip) Not applied

Defining Attributes


maximum-size specifies the maximum expected size of the data.

� For DisplayString, this parameter specifies the maximum number of bytes of the attribute. The maximum size allowed for a DisplayString is 2048 bytes.

� For numerical attributes such as Counter and Gauge, this parameter specifies the maximum expected data value.

For example, an attribute for CPU utilization in percentages could have a maximum of 100. A counter attribute for the total number of packets received might expect a maximum value of 1,000,000 packets per system implementation.

KEY (optional) indicates that an attribute is a key attribute. This only applies if the sample method in the NAME statement is specified as K.

The Universal Agent uses key attributes to determine whether multiple events have the same cause. Key attributes help correlate data rows with identical keyed attribute values. As the Universal Agent receives data rows for keyed attribute data, it checks to see if it already has a data row with matching values for keyed attribute. If so, the new data row replaces the existing one. Furthermore, the replacement occurs only if the time difference between the new data row and the existing data row is less than the specified TTL.

� Up to five attributes may be designated as key attributes.� If no attribute is designated as key, the Universal Agent uses the first

attribute as the key attribute.ATOMIC (optional) Universal Agent allows you to atomize attributes in your metafiles. Atomizing an attribute permits the use of the display item option during situation definition. The display item option allows you to

� generate separate events for a single true condition� easily display the value that caused the situation to become true.For example, if process_cpu > 10 percent represents a situation, a situation could be raised for one or more processes on a machine. If only one situation event is raised, the “responsible” process is ambiguous. In different intervals, different processes could be causing the problem.

If you atomize the situation using the display item option for the process_cpu attribute, separate situation events would be raised and reset for each process that caused the situation to be true. This feature can greatly reduce the number of situation definitions.


Defining Attributes

To activate the feature, add the keyword "Atomic" to the right of the attribute you wish to atomize in your Universal Agent metafile.

Note: "Atomic" can be specified in upper or lower case.

For example, the following statements represent attributes within a File DP metafile:

EmployeeName D 20 Atomic

EmployeeExt N 4

EmployeeID D 8

The "EmployeeName" attribute is atomized. "Atomic" is similar to the "Key" keyword in that it must follow the size specification. You can include both "key" and "atomic" for the same attribute. It doesn't matter which comes first, but there must be at least one blank separating them.

Note: Adding the "atomic" keyword to an existing attribute only causes a minor version change in the associated UA application.

Several Universal Agent-provided attributes in the SNMP Data Provider SNMP-MANAGER application and in the HTTP Data Provider INTERNET application are atomized by default. This enables situations referencing those attributes to use the display item capability.

Note: Although there is no limit to the number of attributes you can atomize in a metafile, only one display item attribute can be specified per situation.Pure numeric attributes such as counters and gauges are not eligible to use the "atomic" keyword.

help text (optional) defines the help that appears when the cursor is moved over a column heading within a table view.

� The text must be preceded by the “at” (@) sign.� The text may not exceed 245 characters.� Commas (,) are converted to spaces.

Exploring Attribute Characteristics



IntroductionA variety of attribute characteristics can be used to enhance performance monitoring. These characteristics include

� attribute duplication� invisible attributes� left/right truncation� support for enumeration

Duplication of attributesWithin an attribute group (as defined by a NAME statement), duplicate attributes are not allowed. The following procedures handle duplicate attributes.

Attributes of same name and type. Subsequent attributes are deleted and the validation message KUMPV15W identifies the deleted attribute. Attribute size helps determine whether attributes are duplicates. If two attributes have the same name and same type, but differ in size, the Universal Agent keeps the attribute with the larger size. For example, in the following attribute definitions:

InventorySum C10000

.

.

.

InventorySum C 9999

the definition InventorySum C 9999 will be deleted.

Attributes of same name but different type. A sequence number is appended to the duplicate attributes and the warning message KUMPV16W indicates that the attribute name has changed. For example, the following attribute definitions:

InventorySum D 12...



InventorySum C 10000

will be modified to:

InventorySum D 12...InventorySum2 C 10000

Note: Unique attribute definitions may become duplicate attributes if the name is truncated.

Invisible attributes-attribute-name attribute-type maximum-size

An attribute may be used as an intermediary to derive other attributes or may be of no use when output. Nevertheless, it must be defined in a metafile because it is part of the input application data, or perhaps serves as a placeholder. Removing this attribute from the output, however, reduces attribute group complexity and simplifies its use.

The ClientAddress, Date, Time, and Date_Time attributes listed in the following example become invisible when output. Note that there cannot be any blank spaces between the hyphen and the attribute name.

//NAME RequestErrorStatus e//INTERNAL INPUT InternetLog//SUMMARY 86400//ATTRIBUTES-ClientAddress D 256ClientLocation (ipAddressToName = ClientAddress)ClientUserName D 32Authorized_User K 32-Date D 10-Time D 10-Date_Time (Date + Time)LocalTimeStamp (CandleTimeStamp = Date_Time)Time_Zone K 5Request D 256 SKEY=2DLM=' 'ServiceStatus C 999 SKEY=1

–FILTER={NUMBER>=(0,400)}BytesReceived C 99999999Referral D 256 DLM='/"'



Browser D 256 DLM='""'Service D 32ServerName D 256RequestParameters D 256BytesSend C 99999999RequestElapsedTime C 99999999*

The attributes ClientLocation and LocalTimeStamp provide information in a format suitable for output without any information loss. See “Derived attribute functions” on page 199 for more information about this example.

Left truncation of display attributesBy default, a display type attribute whose data size exceeds the defined data size is truncated from the right. For example, an attribute data value of ABCDEFGHIJK for attribute definition

TestName D 8

results in a data value of ABCDEFGH. The same attribute defined using the left truncation specification DL

attribute-name DL maximum-size

results in a data value of DEFGHIJK.

Enumeration supportFor numeric type attributes, you can specify enumeration strings that make reading the data values much easier. The specification

enumString(numeric_value)

can include as many numeric values as you want within the ENUM{ } block. A blank space after the "{" and another before the "}" are required. The enumeration must come before the "@" for the help text.

For example,

ifOperStatus C 999999 ENUM{ up(1) down(2) } @The interface status

specifies enumeration strings of up and down.

Once you specify an enumeration list, the enumeration strings appear in the CandleNet Portal workspace instead of the raw integer values. Exceptions



include integer values without an associated enumeration. You can also code CandleNet Portal situations to compare the enumeration string instead of the raw value.

Deriving Attributes


Deriving Attributes

IntroductionYou can define attributes which are derived from other attributes using the following specification:

attribute_name (attribute_1 operator attribute_2)

The supported operators are:

Both of the attributes in the formula must be numeric. They can be either input or derived. See Figure 14 on page 198 for examples.

Figure 14. Metafile with Derived Attributes

Operator Meaning

- attribute_1 minus attribute_2

+ attribute_1 plus attribute_2

* attribute_1 multiplied by attribute_2

/ attribute_1 divided by attribute_2

% attribute_1 divided by attribute_2 times 100

//APPL NewType//NAME NewTable K 3600//SOURCE FILE c:\test.log//ATTRIBUTES ‘;’Item_Name D 24 KEYWidth C 1000000Depth C 1000000Difference (Width - Depth)Sum (Width + Depth)Area (Width * Depth)Factors (Width / Depth)Percent (Width % Depth)Height C 1000000Volume (Area * Height)


Deriving Attributes

Derived attributes as real numbersDerived attributes often prove more useful if displayed as real numbers rather than as integers. For example, derived attributes such as RequestsPerSecond or BytesTransferPerSecond may result in numbers too small to be shown as an integer. If only 100 requests were received in an interval of 3600 seconds, then the result is 0.03. This number is rounded to zero for an integer attribute. To display output values as real numbers, use the following format:

attribute-name REAL(derive attribute formula)

The REAL keyword specifies that the attribute output value displays as a floating point number with up to three decimal point precision.

Derived attribute string concatenationattribute-name (character_attribute_1 + character_attribute_2)

The derived attribute feature dictates that input attributes must be numeric attributes. The exception to this rule is character string concatenation. Both input attributes are character type attributes joined by the plus (+) operator.

For example, if an attribute group contains the attribute Date and the attribute Time, it may be convenient to combine them into one attribute Date_Time for use. If the Date attribute has the value “Sep 15, 2002 ” and the Time attribute contains “10:31:21” then the resulting Date_Time attribute is “Sep 15, 2002 10:31:21”.

Derived attribute functionsattribute-name (function = from_derive attribute_name)

Derived attribute functions are Universal Agent defined functions that operate on input attribute values. The results as derived attribute values. This function modifies or reformats a given attribute so that its value becomes more intuitive for display. It can also be used to reformat an unconventional format into a standard form to improve comparisons or data correlation.

Deriving Attributes


The following table includes descriptions of derived attribute functions.

Table 15. Descriptions of Derived Attribute Functions

Function Name Description Input Type

ipAddressToName Convert decimal form ip address to host name. If the address cannot be resolved, then the host name shown is the input decimal ip address.

Display

CandleTimeStamp Convert free form date and time input character string into standard 16 digit CT time stamp.

Display

NetWareTimeToText Convert special NetWare hexadecimal time value to standard display time format.

Display

UTCtoLocalTime Convert Coordinated Universal Time to local time in standard 16 digit timestamp.

Integer

UTCtoGMT Convert Coordinated Universal Time to GMT time in standard 16 digit timestamp.

Integer


Deriving Attributes

The following example includes derived attribute functions:

//NAME RequestErrorStatus e//INTERNAL INPUT InternetLog//SUMMARY 86400//ATTRIBUTESClientAddress D 256ClientLocation (ipAddressToName = ClientAddress)ClientUserName D 32Authorized_User K 32Date D 10Time D 10Date_Time (Date + Time)LocalTimeStamp (CandleTimeStamp = Date_Time)Time_Zone K 5Request D 256 SKEY=2DLM=' 'ServiceStatus C 999 SKEY=1

–FILTER={NUMBER>=(0,400)}BytesReceived C 99999999Referral D 256 DLM='/"'Browser D 256 DLM='""'Service D 32ServerName D 256RequestParameters D 256BytesSend C 99999999RequestElapsedTime C 99999999*

Filtering Attributes



IntroductionTo control the amount of data you see from workspaces, you can specify criteria for data to be included or excluded. This feature is known as “filtering” attributes. Filtering attributes can enhance performance of your solution by reducing the amount of data the Universal Agent processes.

Syntaxattribute-name attribute-type maximum-size +FILTER={filter1 OR|AND filter2 OR|AND filter3}

attribute-name attribute-type maximum-size -FILTER={filter1 OR|AND filter2 OR|AND filter3}

DescriptionA maximum of three filters can be defined for an attribute. Attribute filters must be logically connected entirely by OR operators or by AND operators, but not by a combination of OR and AND operators. The first two examples

attribute-name attribute-type maximum-size +FILTER={filter1 OR filter2 OR filter3}

attribute-name attribute-type maximum-size +FILTER={filter1 AND filter2 AND filter3}

are supported. The following example is not supported:

attribute-name type size +FILTER={filter1 OR filter2 AND filter3}

Every attribute in an attribute group can have its own filter definition. The Accept Filter (+FILTER) specifies that the application data should be accepted for input. The Reject Filter (-FILTER) specifies that the application data should be excluded. Accept filter specifications and reject filter specifications must be enclosed by braces { }. An accept filter and a reject filter on the same attribute is not supported.

Note that -FILTER, +FILTER, SCAN, MATCH, NUMBER, and the logical operators OR and AND must be capitalized.

Each filter specification must be defined in the following format:



filter-function( data-offset, filter-value )

The filter-function consists of character string functions and number functions. The character string functions are used for filter definition against character types of attribute data, such as Display-Type or Record-Type. The number functions work with numeric attribute data, such as Counter-Type.

The filter-function must include two positional operands, data-offset and filter-value, enclosed in parentheses. The data-offset defines the offset from the beginning of attribute data where comparison should be made against the filter-data. For number filter functions, the positional data-offset parameter cannot be omitted, but must be zero.

The table below summarizes the characteristics of various filter functions.

Table 16. Filter Function Characteristics

Function DescriptionAttribute

TypeData

OffsetFilter Value

SCAN Check for filter character string occurrence in the attribute string starting from offset position to the end of attribute data string or up to maximum defined attribute size.

D,R,T,Z,N 0<=max size

Characters

MATCH Check for exact match of filter character string occurrence in the attribute string starting from offset position.

D,R,T,Z,N 0<=max size

Characters

NUMBER=

Compare attribute value equal to filter value.

A,C,G,?,#,%

0 Numeric

NUMBER>

Compare attribute value greater than filter value.

A,C,G,?,#,%

0 Numeric

NUMBER<

Compare attribute value less than filter value.

A,C,G,?,#,%

0 Numeric

NUMBER>=

Compare attribute value greater than or equal to filter value.

A,C,G,?,#,%

0 Numeric

NUMBER<=

Compare attribute value less than or equal to filter value.

A,C,G,?,#,%

0 Numeric



Note that for the File Data Provider in COPY monitoring mode, the first record in a file that is being monitored starts a block of records. Thus, it always appears in the report, whether or not it should have been eliminated by the filter. For complete description of file-mode, see “SOURCE Statement” on page 162.

Example 1

The Universal Agent File Data Provider monitors a file for customer sign-on activities. The attribute filter performs early filtering by accepting file records containing the character string Processing Signon or FIRST TIME SIGNON only.

//APPL ABC//NAME SignOn S 900//SOURCE FILE f:\IB.log tail//ATTRIBUTES Date D 4Time D 8Message Z 256 +FILTER={SCAN(0,Processing

Signon) OR SCAN(0,FIRST TIME SIGNON)}

Example 2

The Universal Agent monitors application transactions. The application program outputs a dash character whenever a customer provides an invalid transaction request. The attribute filter rejects all input data with transaction attribute “-“ in order to remove invalid application records.

//NAME Transaction_Stat e//ATTRIBUTES ','CustomerName D 256CustomerAddress D 32Date D 12Time D 12TransactionNmae D 256 -FILTER={MATCH(0,-)}TransactionParametersD 256



Example 3

The Universal Agent monitors an internet server log for internet server request status codes greater than 400.

//NAME Status_Stat e//ATTRIBUTESClientLocation D 256ClientUserName D 32Authorized_User K 32Date_Time DL 20Time_Zone K 5Request D 256ServiceStatus C 99999999 +FILTER={NUMBER>=(0,400)} BytesReceived C 99999999Referral D 256Browser D 256

Sequencing Attribute Definitions



IntroductionThe definition sequence of an attribute group defines the order in which the Universal Agent extracts input application data. This sequence is also the order of data presented to other CT components. The Universal Agent assigns a new application definition version number when the attribute sequence changes (for example, when new attributes have been added or existing attributes deleted).

Syntaxattribute-name attribute-type maximum-size SEQ=n

DescriptionWhen you define an attribute sequence, attribute definitions will match the application data as delivered to the Universal Agent. The Universal Agent can also present a consistent attribute sequence to the CT components.

The input sources from different applications can be used as a single application. For instance, the WEB server logs from an Apache server or Netscape server or Microsoft IIS contain similar information. However, the log record layouts are different. Without the attribute sequence definition, three metafiles of three unique application names are needed. Each metafile contains similar attributes, sequenced in the order corresponding to the specific WEB server log file format. The three applications require a considerable amount of work to create CCC situations and policies and, as a result, increase the complexity of application management.



The following example represents a metafile definition for an Apache server log and an MS IIS log. They appear as the same application eLog when you use an attribute sequence definition.

//APPL eLog//NAME ServerLog e//ATTRIBUTES*-------------------------------------------** Apache Server Log Record Format Layout **-------------------------------------------*ClientLocation D 256 SEQ=1ClientUserName D 32 SEQ=2Authorized_User K 32Date_Time DL 20 SEQ=3Time_Zone K 5Request D 256 SEQ=9DLM=' 'ServiceStatus C 99999999SEQ=8 BytesReceived C 99999999SEQ=6Referral D 256 SEQ=12DLM='/"'Browser D 256 SEQ=13DLM='""'Service D 32 SEQ=4ServerName D 256 SEQ=5RequestParameters D 256 SEQ=10BytesSend C 99999999SEQ=7RequestElapsedTime C 99999999SEQ=11*

//APPL eLog//NAME ServerLog e//ATTRIBUTES ','*-------------------------------------------** Microsoft IIS W3C Log Record Format Layout**-------------------------------------------*ClientLocation D 256 SEQ=1ClientUserName D 32 SEQ=2Date_Time D 20 SEQ=3Service D 32 SEQ=4ComputerName K 64ServerName D 256 SEQ=5RequestElapsedTime C 99999999SEQ=11BytesReceived C 99999999SEQ=6BytesSend C 99999999SEQ=7



ServiceStatus C 99999999SEQ=8 WindowsStatus K 99999999OperationName K 8Request D 256 SEQ=9RequestParameters D 256 SEQ=10PadParm2 K 8PadParm3 K 8PadParm4 K 8PadParm5 K 8Referral D 256 SEQ=12Browser D 256 SEQ=13

In the following example, the application program added three new attributes. By using an attribute sequence definition, version change is avoided.

Old application data definition:

//APPL DTY//NAME ConsoleMessage e//ATTRIBUTEs ‘;’MessageID D 12MessageSeverity C 99MessageCategory C 99MessageDescription Z 255

New application data definition:

//APPL DTY//NAME ConsoleMessage e//ATTRIBUTEs ‘;’MessageOrigin D 80 SEQ=5MessageID D 12 SEQ=1MessageSeverity C 99 SEQ=2MessageCategory C 99 SEQ=3MessageAction D 80MessageStatus D 16MessageDescription Z 255 SEQ=4

An attribute that does not include a sequence definition appears after attributes with sequence specifications in the order as defined in the metafile. In the example above, the attribute MessageAction appears after attribute MessageOrigin and is followed by the attribute MessageStatus.

Console Commands 209

Console Commands

OverviewThis appendix contains descriptions and syntax of the console commands you can use with the Universal Agent Data Providers.

Appendix contentsUsing Console Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210DELETE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215GENERATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216IMPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220LIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221LOADCOMM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222LOADLIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223LOADNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224MNL ADD NODE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225MNL REMOVE NODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226REFRESH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228SHOW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229SHUTDOWN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231TRAPCNFG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232UNPACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233VALIDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

C

Using Console Commands



Overview The Console Command Interface lets you control the operational configuration of an Universal Agent dynamically. This service is particularly useful since it enables the Universal Agent to support applications without interruption when new applications come online or attributes change. You invoke the interface using the KUMPCON program.

In addition, you have the option of issuing console commands from CandleNet Portal. To issue commands from CandleNet Portal, right-click an Universal Agent managed sytem and select the Take Action... option. For more information about TakeAction commands, see Administering OMEGAMON Products: CandleNet Portal or the online Help for Universal Agent.

The console commands are summarized in Table 17, “Summary of Console Commands,” on page 213 and discussed in greater length in the following sections. Commands that are available via TakeAction are tagged with an asterisk (*).

Invoking the console command interface on WindowsYou invoke the console commands from the command line by invoking the program KUMPCON:

KUMPCON command [parameter]

You can also call the kumpcon program from inside a script, which can be useful for automating frequently performed tasks. For the KUMPCON program to run, it must be able to find its shared libraries. On Windows, the shared libraries reside in the same directory as the KUMPCON program so it has no trouble locating them. You can obtain a list of valid console commands by entering:

KUMPCON ?

You can enter a command in abbreviated form. For example, you can enter the DELETE command as either DELETE or D and the SHOW command as SHOW or SHO. Both uppercase or lowercase characters are allowed. The program converts all input command characters to uppercase for validation.



Invoking the console command interface on UNIXOn UNIX platforms, you cannot run the KUMPCON program directly. Instead use the um_console shell script, which serves as a wrapper around KUMPCON. The um_console script sets the correct environment variables so that KUMPCON can find the shared libraries it needs to execute.

On Unix, enter:

um_console -h $CANDLEHOME

Note: The -h parameter is required if you have not previously set the $CANDLEHOME environment variable.

Call um_console without specifying a console command. After the script invokes the KUMPCON program, you will be prompted for a command:

Enter console command <Application name or Metafile name or file name>

Specifying metafile and application names in commandsWhen specifying a metafile, you must use exactly the same name you used when the metafile was first defined to the Universal Agent. For instance, if a metafile was imported to the Universal Agent using its fully-qualified name, you must use the fully-qualified name in other console commands. Conversely, if a metafile was first defined to the Universal Agent using an unqualified name, the unqualified file name must be used on all other commands.

Some console commands will accept the Universal Agent application name as an input parameter instead of the metafile name. In those cases, the name of the application is case-sensitive and must exactly match the name of the application as specified in the APPL statement in the metafile.

If you have created subdirectories in the working directory, you can refer to a metafile or an application using a relative path:

kumpcon import .\SNMP\standard\RFC1213_mib-2.mdl

Multi-interface systemsIf you run KUMPCON on a host with multiple interfaces and you have configured the Universal Agent to use a particular interface via environment variable KUM_DCH_HOSTNAME, you need to set environment variable



KUMP_API_DPAPI_HOST to the same value if you are sending commands to the ASFS or APIS Data Provider.

Sending console commands to an alternate UA instanceThe console command interface to a non-primary UA requires you to specify the KUMP_DPCONSOLE_PORT environment variable in order to target the correct UA. By default, the target UA will be the primary and it will use console port 7700. To prevent you from accidentally issuing commands against the wrong UA when a non-primary UA is being accessed via the console interface, the prompt for the target DP displays the Instance Name next to each DP. The following figure shows how setting KUMP_DPCONSOLE_PORT to 8700 (you can determine the correct console listening port to use by checking the UAGENT DPLOG workspace), in this example associated with INST2, causes the INST2 DPs to be listed so that you will know which UA you are accessing:

Note that the Take Action interface does not have this ambiguity problem. When distributing an action such as Import or Refresh, the list of available managed system names includes the Instance Name prefix so you will always be able to select the appropriate DP.



Table 17. Summary of Console Commands

Console Command Description

DELETE* Removes a defined application data specification

GENERATE Builds a complete and syntactically correct ODBC metafile when given a data source name as input

IMPORT* Loads and initializes an application data definition

LIST List currently defined applications

LOADCOMM* Loads and initializes the agent community name table, KUMSCOMM

LOADLIST* Loads managed node lists (hot lists)

LOADNAME* Loads and initializes the network symbolic name table, KUMSNAME

MNL ADD NODE* Adds an entry into a managed node list

MNL REMOVE NODE* Removes an entry from a managed node list

REFRESH* Re-initializes an application data definition

SET Allows you to redirect console commands to an Universal Agent running on a host other than the host on which you issue the commands

SHOW Displays application data definition details

SHUTDOWN* Initiates normal shutdown procedure

TRAPCNFG* Instructs the SNMP Data Provider to refresh the SNMP trap configuration file



* These commands are available via a TakeAction selection.

UNPACK Unpacks the input SNMP metafile and outputs the identical uncompressed version of the metafile in the same input metafile location.

VALIDATE Instructs the Universal Agent to validate the specified metafile

Table 17. Summary of Console Commands (continued)

Console Command Description


DELETE

DELETE

DescriptionThe DELETE command removes a defined application from the Universal Agent repository. If the application is active, the Universal Agent disconnects the connection to the application and "unregisters" it. Any CCC managed systems associated with the application that are online go offline. The name of the metafile is automatically removed from the KUMPCNFG configuration initialization file so that the application will not be activated the next time UA is restarted.

SyntaxKUMPCON DELETE [application-name | metafile-name]

ParametersYou can specify either the name of the Universal Agent application (specified in the APPL statement in the data definition metafile) or the name of the metafile.

GENERATE


GENERATE

DescriptionThe GENERATE command automatically builds a complete and syntactically correct ODBC metafile when given a data source name as input. This command supports full generation of all tables defined to the specified data source. You can also limit which tables will be generated by selecting user tables, system tables, or views (or some combination of the three) and by specifying a beginning string of characters to pattern match against any of the three table types.

The GENERATE command does not support metafile creation for stored procedures. You can execute this command even when Universal Agent is not running. GENERATE is only accessible on Windows and only through the kumpcon console interface (not via Take Action).

SyntaxKUMPCON GENERATE dataSourceName user=userid pswd=password

ParametersdataSourceName indicates the specific name of the configured data source that will be used to create the ODBC metafile. This parameter is required. If the data source contains any embedded blanks, it must be surrounded with single quotes. user is the userid what will connect to the ODBC data source. If no user/password combination is required for this particular data source, then the user= parameter can be omitted from the GENERATE command. pswd is the password associated with the userid connecting to the ODBC data source. If specified, the user and pswd values will be inserted into every //SOURCE statement in the generated ODBC metafile.

ExamplesThe following examples illustrate ways of invoking GENERATE:

KUMPCON GENERATE nwind

This command generates a metafile in the metafiles directory called nwind.mdl that contains every table and column in the nwind data source.

KUMPCON GENERATE cnps user=sa pswd=abcdef


GENERATE

This command generates a metafile in the metafiles directory called cnps.mdl that contains every table and column in the cnps data source. The "user=" and "pswd=" parameters are required to connect to that data source.

After the console input is accepted, you can indicate whether to include user tables, system tables, and/or views via the menu options and prompts depicted in the following figure.

By entering a menu option (or options) other than "4) All of the above", you can build a more focused and targeted metafile. You can also pattern match on a beginning string in the table name, for example, all system tables starting with "sys". An important benefit of generating specific tables, instead of all tables, for an ODBC data source is that it can sometimes significantly reduce the time it takes for metafile generation to complete.

Certain database products, such as SQL Server and Sybase, allow you to connect to one of several databases associated with a particular data source. If you're generating a metafile for one of these database products, you will be prompted to enter a specific database to use. Note that each database context may have a different set of user tables associated with it. If you wish to generate a metafile for a non-default database context, you should reply Y to the prompt, enter the name of the database and, optionally, the name of a specific server associated with that database. If the default database context is adequate, then you can skip this prompt.

GENERATE uses the data source name to determine the output metafile name. If a metafile by that name already exists in the $CANDLEHOME\cma\metafiles directory, you are prompted as to whether you want to replace it.

GENERATE


UsageThe resulting generated metafile provides a good first step towards creating a useful ODBC metafile, but most likely will require some changes. After KUMPCOM GENERATE completes, the following areas in the metafile should be reviewed for possible modification:

� The first three characters of the //APPL name may need to be changed to make them unique. No other UA applications with those same first three characters should connect to the same CMS.

� A default maximum of 64 tables is allowed in a metafile. Full generation of an ODBC data source can result in hundreds or even thousands of //NAME statements. The metafile may need to be divided.

� A default maximum of 63 attributes is allowed in a single table. This maximum can be increased to 127 with KIB_MAXCOLS. However, that still might not be enough if there are more columns in the SQL table.

� The preceding two issues could require that unwanted tables and attributes be removed.

� The attribute data types and maximum sizes might not be exactly what you want, so they should be reviewed for correctness.

� The default “Select * from &tableName” may not be appropriate. Perhaps a more qualified Select statement with specific columns listed or with Where clause filtering should be used instead.

� Review any attribute defined as KEY, which corresponds to an indexed column in the SQL table. Note that each KEY attribute in every data row must have a non-blank, non-NULL value or the row won't be sent to the data server. If the table you are monitoring will occasionally be missing values for a KEY attribute, then the KEY designation should be removed.

� By default, each //NAME statement uses the SQL table name as its attribute group name. You may want to change some or all of these to more meaningful names.

� Check any numeric attributes that you plan to use for comparison purposes in situations or for creating derived attributes. These must be defined with one of the true numeric attribute types, such as 'C' for Counter. If a numeric attribute is generated, for example, as attribute type 'N', then it will be treated as a display string type value instead of as an integer, and your greater than/less than situation comparisons won’t work as expected.

� You may want to insert optional UA metafile features, such as filters, derived attributes, AddTimeStamp, attribute help text, etc.


GENERATE

� A maxrows=nnn parameter override may be necessary, if the default value is inadequate.

� The default time-to-live value of 300 seconds may not be appropriate.

After making changes to the generated metafile, you should run VALIDATE against it to make sure there are no errors or warning messages to correct.

IMPORT


IMPORT

Description

The IMPORT command adds an application to the Universal Agent repository. If the metafile is successfully imported, the name of the metafile is automatically added to the KUMPCNFG configuration initialization file. Subsequently, the metafile is loaded automatically when the agent is restarted.

SyntaxKUMPCON IMPORT metafile-name

Parameters� You must specify a metafile name.� The metafile must exist and be accessible to the Data Provider.


LIST

LIST

DescriptionThe LIST command displays a list of metafiles currently known by the Universal Agent.

SyntaxKUMPCON LIST

ParametersThis command requires no input parameters. Any specified parameter is ignored.

Output The output of the LIST command may look like the following:

No application defined

or

Active application definitions:

vmstat.mdl

TCPioQ.mdl

CustInq.mdl

LOADCOMM


LOADCOMM

DescriptionThe LOADCOMM command instructs the SNMP Data Provider to reload the KUMSCOMM file. The KUMSCOMM file matches host names to SNMP community names.

SyntaxKUMPCON LOADCOMM


LOADLIST

LOADLIST

DescriptionLoads the SNMP Managed Node list (also known as Hot List).

SyntaxKUMPCON LOADLIST managed_node_list_name

Parametersmanaged_node_list_name is the name of the file in which the hot list is defined.

LOADNAME


LOADNAME

DescriptionThe LOADNAME command instructs the SNMP Data Provider to reload the KUMSNAME file. The KUMSNAME file defines symbolic names for networks.

SyntaxKUMPCON LOADNAME


MNL ADD NODE

MNL ADD NODE

DescriptionAdds a network resource to a managed node list

SyntaxKUMPCON MNL Add Node LIST=managed_node_list_name NODE=node_name

Parametersmanaged_node_list_name is the name of an existing SNMP Managed Node List file. node_name is the resource name to be added to the list. See the Universal Agent SNMP Data Provider User’s Guide for details.

MNL REMOVE NODE


MNL REMOVE NODE

DescriptionRemoves a network resource from a managed node list

SyntaxKUMPCON MNL Remove Node LIST=managed_node_list_name NODE=node_name

Parametersmanaged_node_list_name is the name of an existing SNMP Managed Node List file. node_name is the resource name to be removed from the list. See the Universal Agent SNMP Data Provider User’s Guide for details.


REFRESH

REFRESH

DescriptionThe REFRESH command performs the combined functions of the DELETE and IMPORT commands.

SyntaxKUMPCON REFRESH metafile-name

Parameters� You must specify a metafile name.� The metafile must exist and be accessible to the Universal Agent.

SET


SET

DescriptionYou can run the KUMPCON program on a different host than the Universal Agent. By default KUMPCON assumes that it is to communicate with the Universal Agent on the same host. To direct your commands to the Universal Agent on a different host, issue the SET command. You will then be prompted for the command you wish to issue on the remote host.

You need to issue SET every time you want to issue a KUMPCON command to a remote host.

SyntaxKUMPCON SET hostname

ParametersYou must specify the host name of the machine to which you want to direct the command.


SHOW

SHOW

DescriptionThe SHOW command displays the details of an Universal Agent application data definition.

SyntaxKUMPCON SHOW [application-name | metafile-name]

Parameters You can specify either the name of the application or the name of the metafile.

MessagesThe SHOW command output may look like the following:

Metafile name entered not defined

or

Console input accepted.

MetaFile: vmstat.mdl Application: UXstatusGroup: UXsysSta Poll Data TTL=15SOURCE: API -

SystemName Display TypeMax Size 16OSversion Display TypeMax Size 16

PendingIOwaitRate Counter TypeIOstartRate Counter Type

OcompleteRate Counter TypeAvgWaitThreadQueueSi Counter TypeAvgRunThreadQueueSiz Counter TypeAvgNumbActivePageFra Counter TypeAvgNumbFreePageFrame Counter Type

PageInRate Counter TypePageOutRate Counter Type

DevInterruptRate Counter TypeSystemCallRate Counter Type

ThreadContentSwitchR Counter TypeAvgUserCPU% Counter Type

SHOW


AvgSystemCPU% Counter TypeAvgIdleCPU% Counter TypeAvgWaitCPU% Counter Type

UDPpktInRate Counter TypeUDPpktOutRate Counter TypeTCPpktInRate Counter Type

TCPpktOutRate Counter Type


SHUTDOWN

SHUTDOWN

DescriptionThe SHUTDOWN command instructs the Universal Agent to initiate the termination procedure. The Universal Agent disconnects all application connections and performs "unregistration" for each active application. If you do not specify IMMED, you will be prompted for which Data Provider you wish to stop.

SyntaxKUMPCON SHUTDOWN [IMMED]

ParametersIMMED or I (optional) initiates immediate shutdown of one or all Data Providers without further prompts or confirmation.

TRAPCNFG


TRAPCNFG

DescriptionThe TRAPCNFG command instructs the SNMP Data Provider to refresh the SNMP trap configuration file.

SyntaxKUMPCON TRAPCNFG


UNPACK

UNPACK

DescriptionThe Universal Agent SNMP MIB metafiles are distributed in compressed format. This is intended to prevent inadvertent modification of supported product parts. Frequently, you might need to create your own versions of vendor or standard metafiles or tailor the existing vendor metafiles to accommodate local management needs and preference. The compressed SNMP metafiles make the local customization process very cumbersome.

The unpack command unpacks the input SNMP metafile and outputs the identical uncompressed version of the metafile in the same input metafile location. Unpack can be executed even when the Universal Agent is not active.

For example, to unpack metafile Novell_nwServer.mdl located in directory \candle\cma\metafiles\snmp\vendor using the unpack console command will result in creation of text file Novell_nwServer.txt in the same directory.

SyntaxKUMPCON U metafile-name

Parametersmetafile-name is the name of the metafile you want to unpack

VALIDATE


VALIDATE

DescriptionThe VALIDATE command instructs the Universal Agent parser and syntax checker routines to validate the specified metafile. These same routines are invoked at runtime so it is useful to run VALIDATE before activating a new or changed metafile. The VALIDATE command can be executed even when the Universal Agent is not active. An application metafile validation report, with an .rpt extension, is saved in the same directory where the metafile is located.

Note: To validate a metafile, you must use the KUMPCON program or um_console script on Unix. This is because the validation must be performed on the host where your metafiles reside.

SyntaxKUMPCON VALIDATE metafile-name

Parameters metafile-name is the name of the metafile you want to validate

Environment Variables 235

Environment Variables

OverviewThis appendix documents the environment variables for the Universal Agent and its Data Providers.

Appendix contentsSetting Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236Universal Agent and Data Provider Variables . . . . . . . . . . . . . . . . . . . . . 237

D




OverviewThe environment variables for the Universal Agent and its Data Providers allow you to override default values for locations, ports, working directories, and the like.

Name and location of variables fileUnless otherwise specified, default values of Universal Agent variables are in force. To change the default values, you must enter the appropriate variable and the desired value in a variables file. The name and location of the variables file differs by platform.

Table 18 contains the name and location of the variables file on each of the supported platforms.

Setting the working directoryThe working directory is where the Universal Agent looks for metafiles and configuration files and where it places its working files. By default, the working directory is the directory in which the Universal Agent binary is executed. On Windows, a separate directory, named work, is created for you and the variable KUM_WORK_PATH preset to specify candle\cma\work directory as the working directory. On UNIX, a separate directory, named work, is created for you and the variable KUM_WORK_PATH preset to specify candlehome/architecture/um/work directory, where architecture is the operating system and version. For example:

/candle/hp11/um/work

You can use KUM_WORK_PATH to specify whatever directory you like.

Table 18. Name and Location of Variables File by Platform

Platform Location Name/Member

UNIX Candle/config/ um.config

Windows Candle\cma\ KUMENV


Universal Agent and Data Provider Variables


The following table presents the variables for the Universal Agent and each of its Data Providers.

Table 19. Universal Agent Environment Variables

Environment Variable Description Default Example

KUM_WORK_PATH Sets the default working directory for the Universal Agent

Directory where Universal Agent is executed

Candle/cma/work

KUM_UMC Controls the sending of SNMP trap and network information to the Universal Message Console

Yes No

Universal Agent

KUMA_DCH_PORT Overrides the agent’s default data clearinghouse port

1919 6134

KUMA_GENERATE_ODI Controls generation of object definition (ODI) files needed to use the Universal Agent with CandleNet Portal

YES NO

KUMA_INIT_CONFIG_PATH Specifies the location of the Universal Agent configuration file if somewhere other than the same directory

local directory \candle\cma\kum\

KUMPCNFG

KUMA_MAX_EVENT_ENTRIES Controls the maximum number of rows of event data in a CandleNet Portal workspace

100 500



KUMA_WRITE_OPTLOG Controls the writing of action data to the CandleNet Portal Operations Log

Y N

KUMA_STARTUP_DP Overrides the default startup of the ASFS Data Provider.

ASFS API,POST

All Data Providers

KUMP_DPCONSOLE_PORT Overrides the default listening port for receiving console commands. Must be specified if sending a console command to an alternate instance of Universal Agent.

7700 8700

KUMP_DCH_HOST Directs the Data Provider to an Universal Agent residing somewhere other than the same host as the DP

Same host as Data Provider

fin1

KUMP_INIT_CONFIG_PATH Specifies the location of the Data Provider configuration file if somewhere other than the startup directory

local directory /candle/meta

server/

KUMP_META_PATH Specifies the location of the Data Provider metafiles if somewhere other than the startup directory

local directory /candle/metafiles

KUMP_META_SERVER Directs the Data Provider to use a centralized metafile server

No metafile server

fin1

Table 19. Universal Agent Environment Variables (continued)




KUMA_ATOMIC_SITUATIONS Identifies specific atomized attributes within situations for use in suppressing duplicate actions in successive sampling intervals.

Enable this feature by adding the variable to your UA configuration file (um.ini on UNIX platforms).

Use the following format: KUMA_ATOMIC_SITUATIONS=sitname1:#,sitname2:#,...

where each entry consists of a Sitname:AttributeColumnNumber pair. If you specify more than one situation, they must be comma separated. Each atomized situation name must be followed by a colon delimiter, which in turn is followed by the column number of the atomic attribute used by the situation.

Note that the column number equates to the numeric sequence of the attribute in the UA metafile.

None CICS_Abend:2





File Data Provider

KUMP_DP_SAMPLE_FACTOR For polled data, sets the sampling factor, which together with the time-to-live value determines the sampling frequency

5 10

KUMP_DP_EVENT Sets the sampling frequency for Event data, in seconds

2 5

KUMP_FILE_EXIST_WAIT Specifies that the Data Provider should terminate the monitoring thread if it detects that the file is absent or empty

NO YES


KUMA_REPORT_REQUEST_EXPIRATION

Used to establish the amount of time, in seconds, to wait for a response to a demand-driven report request. When the request times out, the last available rows for that table will be displayed.

15 30

KUMP_API_BYPASS_VAL Bypasses parameter validation for API calls

NO YES

KUMP_API_DPAPI_HOST Identifies the host of the API Server if not the same as the client

same host as API client

atlantis

KUMP_API_DPAPI_PORT Overrides the API Server default listening port

7600 5028





KUMP_API_TRANSPORT Elects one of three modes of communication between the API client and the server

TCP/IP IPC

KUMP_API_REQUEST_WAIT Governs how long the API client waits for a reply to a request to the API Server Data Provider (in seconds)

30 60

KUMP_API_VERBOSE Toggles detailed trace for API client

NO YES


KUMP_DP_HOSTNAME Sets the preferred host name (network interface) on a multiple host machine if the Data Provider resides on another machine

name of the first installed

network interface

fin1

KUMP_DP_PORT Overrides the default Socket Data Provider listening port

7500 5028

KUMP_TCP_DISCONNECT_BY_TTL

Governs whether or not the Universal Agent delays notifying OMEGAMON XE that a TCP disconnection has occurred until the TTL has expired

YES NO

KUMP_TCP_OUTAGE_WINDOW

Controls the length of time the Universal Agent has to detect a network or system power outage causing a lost connection from a socket client program

180 90

Post Data Provider





KUMP_POST_DP_PORT Overrides the default Post Data Provider listening port

7575 5028

KUMP_POST_APPL_NAME Overrides the application name defined in the KUMPOST metafile

MAS MSG

KUMP_POST_GROUP_NAME Overrides the name of the attribute group defined in the KUMPOST metafile

dpPost messages

KUMP_POST_APPL_TTL Overrides the time-to-live value of the attribute group

3600 1800

KUMP_POST_CATEGORY Redefines default post categories or adds new ones

see “Post Data Provider” on page 89

see “Post Data Provider” on page 89

SNMP Data Provider

KUMP_SNMP_NETDATA_TTL Controls the frequency at which the network discovery and management reports are updated. A shorter interval increases the rate of network discovery messages and overall network load,but ensures that the reports reflect the current network resource status more closely.

14400 seconds

12200





KUMP_SNMP_MANAGE_LOCAL_NETWORK

Serves as a switch indicating whether or not to manage the local network. Set the value to “No” to automatically disable management of the local network.

Yes No

KUMP_SNMP_NET_DISCOVERY

Serves as a switch indicating whether or not to perform discovery of network resources. If set to “No,” the SNMP Data Provider will have knowledge of only default gateways and routers and the local network segment the DP is part of: the ROUTER workspace will show data only for the default gateways and routers, and the NETSUMMARY workspace will show only data for the local network.

Yes No





KUMP_SNMP_NET_DISCOVER_ENTERPRISE

Serves as a switch indicating whether or not network discovery should determine the status of the entire enterprise network. This variable is meaningful only if KUMP_SNMP_NET_DISCOVERY is set to “Yes.” If this variable is set to “No,” several of the attributes in the NETSUMMARY workspace will show a value of zero for networks other than the SNMP DP’s local network.

No Yes

KUMP_SNMP_NET_COMMUNITY

Specifies the enterprise-wide default community name for SNMP agents

Public Candle

KUMP_SNMP_MONITOR_TRAP Serves as a switch indicating whether or not monitoring of SNMP network traps is required

Yes No

KUMP_SNMP_TRAP_CONSOLE_SEV

Controls which traps are forwarded to the Universal Message Console, on the basis of their severity

≥ 2 ≥ 3

KUMP_SNMP_TRAP_PORT Specifies an installation- specific trap destination port that the SNMP Data Provider must monitor in addition to the standard trap listening port 162.

None 1952





KUMP_SNMP_TRAPCNFG_FILE Specifies the name of the configuration files where installation-specific traps are defined

TRAPCNFG traps.cfg

KUMP_SNMP_TRAPCNFG_CATEGORY

Specifies the keyword in the trap configuration file that signals the SNMP trap category definitions.

CATEGORY

KUMP_SNMP_TRAPCNFG_SEVERITY

Specifies the keyword in the trap configuration file indicating the definitions of the SNMP trap severities

SEVERITY Importance

KUMP_SNMP_TRAPCNFG_SOURCEID

Specifies a keyword in the trap configuration file indicating the definitions of SNMP agent source types

SOURCEID Source

KUMP_SNMP_TRAPCNFG_STATUS

Specifies a keyword in the trap configuration file indicating the definitions of SNMP trap status

STATUS CurrStat

KUMP_SNMP_TRAP_VERBOSE Acts as a switch to enable or disable verbose debugging messages which help in daemon problem determination

No Yes

KUMP_SNMP_CHECK_CONFIG_INTERVAL

Specifies the base discovery window (BDW), in seconds.

1800 3600

KUMP_SNMP_DEBUG_DISCOVERY_ROUTE

Used to debug router discovery processing

No Yes





KUMP_SNMP_DEBUG_DISCOVERY_ENTERPRISE

Used to debug the general network discovery processing

No Yes

KUMP_SNMP_DEBUG_DISCOVERY_NETWORK

Used to debug the discovery of resources within a network.

No Yes

KUMP_SNMP_DEBUG_MIB_MANAGER

Used to debug the MIB data collection request flow

No Yes

KUMP_SNMP_DEBUG_MIB_IO Used to debug SNMP Protocol Data Unit (PDU) processing

No Yes

KUMP_ENV_SNMP_DEBUG_TRAP

Used to debug SNMP trap reception and processing logic

No Yes

HTTP Data Provider

KUMP_URL_OUTPUT_STAT Used to output URL statistics to a CSV file for EXCEL spreadsheet analysis. The CSV file will be named URLSTATS.csv and it will be located in the Universal Agent product installation WORK directory.

No Yes

KUMP_URL_MAX_REPLY_WAIT Used to establish the wait time for a URL reply. If the default of 45 seconds results in frequent “Timeout occurred” status messages, set a higher value.

45 60





KUMP_URL_OUTPUT_HTML Used to download the HTML file associated with the URL being monitored to a subdirectory within the Universal Agent WORK directory. The name of the subdirectory will match the URL name.

No Yes

KUMP_HTTP_PROXY_USERIDKUMP_HTTP_PROXY_PASSWORD

Used for proxy servers to establish userid/password validation before external web sites can be accessed. Specify the two variables to allow the HTTP DP to perform proxy authentication.

<none> Admin for User ID

candle for Password

KUMP_HTTP_DEBUG Used to help diagnose a URL monitoring problem. Candle Customer Support may ask you to provide detailed tracing of the HTTP DP component and send the generated UA RAS1 log.

No Yes

ODBC Data Provider

KUMA_REPORT_REQUEST_EXPIRATION

Used to establish the amount of time, in seconds, to wait for a response to a demand-driven report request. When the request times out, the last available rows for that table will be displayed.

15 30





KUMP_ODBC_MAX_ROWS Used to globally specify the maximum number of rows to return for each ODBC table in a metafile.

100 50

KUMP_ODBC_DEBUG Used to help diagnose an ODBC monitoring problem. Candle Customer Support may ask you to provide detailed tracing of the ODBC DP component and send the generated UA RAS1 log.

N Y



Problem Determination 249

Problem Determination

OverviewThis appendix contains tips for troubleshooting problems frequently encountered by new users and specifies the documents required for reporting problems to Candle support.

Appendix contentsUniversal Agent Problem Determination. . . . . . . . . . . . . . . . . . . . . . . . . 250Documents Required for Problem Reporting. . . . . . . . . . . . . . . . . . . . . . 253

E

Universal Agent Problem Determination



OverviewThe operation of the Universal Agent depends entirely on correct application data definitions, environment variables, and CMS and CandleNet Portal set-up. In general, most problems are caused by incorrectly formatted data or data interpretation. Therefore, start the process of problem determination with the Data Provider and proceed to other OMEGAMON XE components on the basis of the discovered scenarios. Data Provider problems are usually reproducible because the input data (that is, the file in question or the application data that was input) can easily be preserved and examined.

Preliminary problem determinationFollow the procedure below to perform preliminary problem determination.

� Validate your metafiles using the console command VALIDATE. Review the validation messages and report. Resolve all identified errors and warnings. Since the Universal Agent calls the same validation subroutines when it loads a metafile, it encounters the same problems as the KUMPCON VALIDATE program.

� Verify that the first three characters of the application name defined in the APPL statement of the metafile are unique throughout the enterprise.

� Verify that the sequence of data fields on the data record matches the listed sequence of attributes in the metafile. In addition, make sure that the attribute type and the maximum data value size correspond to the actual application data values.

� Verify that the actual data fields are delimited exactly as specified in the delimiter specification of the ATTRIBUTES statement. If the delimiter is specified as NONE, make certain that defined attribute value sizes exactly match the data values on the application data record.

� For FILE Data Providers, verify that only one file source (SOURCE FILE statement) is specified for each attribute group (NAME statement) or that you have used ManagedSystemName to distinguish the sources.

� For SOCK Data Providers, verify that you have the correct socket source host name (SOURCE SOCK) specified for the application.



� Add the application metafile to the initialization configuration file for automated operation. If you do not use automated operation, make certain that issuing the IMPORT console command is part of standard operating procedure.

� Determine if the application metafiles are located in the same directory as the Universal Agent start-up process. If not, be sure to set the environment variable KUMP_META_PATH to the correct location. If you do not have many metafiles, put them all in one directory and let the Universal Agent automatically load them all at start up.

� Be familiar with the default values supplied by the Universal Agent for each attribute data type if you do not always provide all attributes on every input data record.

� Examine the UAGENT DPLOG report in CNP. It usually contains important messages that give clear indications concerning Data Provider operation and the data source disposition.

RAS1 error tracingProblems related to logic or processing require that the Universal Agent internal trace identify the source of the problem. The Universal Agent uses the Candle building block RAS1 trace and supports the following trace classes:

ERROR detects processing errors and warning conditions. This is the default trace option.

STATE monitors general behavioral changes during execution

FLOW monitors the flow of Universal Agent execution and all function enters and exits

OUTPUT monitor responses from the Universal Agent to Data Providers.

METRICS monitor storage allocations and frees

DETAIL monitors detailed changes during execution, including data values

ALL all trace classes. Captures everything.

To request the trace, set the KBB_RAS1 environment variable.

The default is ERROR tracing only. To obtain a trace for problem determination, set the KBB_RAS1 environment variable for the desired trace



classes before starting the Universal Agent or add the setting to the Universal Agent start-up script file.

Table 20. RAS1 Trace Settings

For this type of problem Set the trace to

General problem detection KBB_RAS1=ERROR (UNIT:kum ERROR STATE OUTPUT) ^>ua.log

Unpredictable or unknown problem KBB_RAS1=ERROR (UNIT:kum ALL) ^>ua.log


Documents Required for Problem Reporting


For problem reporting, you may be asked to collect and include the following documentation:

� data definition metafile� monitored application file as specified on the SOURCE FILE

statement, if applicable� appropriate Universal Agent RAS1 trace output � description of the operation scenario that led to the problem� incorrect output, such as CandleNet Portal screen prints or a description of

what you observed, if applicable



Migration 255

Migration

OverviewThis Appendix explains migration from V350 to V400 to V410 of the Universal Agent.

F

Migrating to V410


Migrating to V410

OverviewMigrating to Universal Agent Version V410 from a previous version is a simple matter. You should be aware of the following issues:

� All of your existing Universal Agent metafiles and configuration work files are reusable, as is, in UA410.

� There are no migration utilities or special conversion tools that you need to run.

� A migration to UA410 does require that you recompile and relink any C/C++ API client programs you may have written. You should update your API client program development environment with the UA410 API client package. You should also copy the UA410 KUMPAPI DLL or shared library to the directory or path where your client program runs.

Migration processFollow these steps to migrate from a previous version:

1. Backup all of your critical UA files: metafiles, configuration files that you have customized (such as KUMPCNFG, KUMPURLS, TRAPCNFG, KUMSMIBI, etc.). If you have set special environment variables in KUMENV or um.ini/um.config, then you should back up those files, as well.

2. Uninstall Universal Agent V350 or V400. This will remove all of the previous version's binaries, registry entries, etc.

3. Install Universal Agent V410.

4. Restore any metafiles that you wish to reuse.

5. Restore any customized configuration files that you wish to reuse.

6. Review KUMENV and um.ini/um.config, in case you wish to update the KUMA_STARTUP_DP list or if you have any special environment variable setttings to restore from your backup copy.Note that on UNIX, you should configure UA410 and specify the DPs you wish to start.

7. Bring up Universal Agent V410.

8. Verify that all of your UA monitoring applications come online.

Glossary 257

Glossary

A

agent An executable file that gathers and distributes information about system parameters. There is always one agent per managed system.

attribute A discrete characteristic or piece of information, or a property of that information, such as type, source, or severity, for a managed system. CNP users use attributes to create situations.

C

Candle Command Center (CCC) A client-server implementation whose environment includes:

� a server known as the Candle Management Server (CMS)

� a client, which can be:

– CandleNet Portal, a Java-based user interface for viewing and monitoring your enterprise network

– an OMEGAMON II product using a 3270 terminal session

� agents that collect and distribute data to a CMS

Candle Management Server (CMS) The host data management component in an OMEGAMON XE environment that runs on the hub

machine, sends out requests to, and receives data from, managed systems having an OMEGAMON monitoring agent or alert adapter installed, and sends the information it receives to CandleNet Portal.

CandleNet Portal The user interface component of OMEGAMON XE. It provides a view of your enterprise from which you can drill down to more closely examine components of your systems environment. Its application window consists of a Navigator that shows all the systems in your enterprise where Candle agents are installed, and a workspace that includes table and chart views of system and application conditions.

Customer workspace A workspace for a user-defined attribute group. See also: Customer Reports Folder

D

data definition metafile A text file that defines the attributes you want to monitor and the source of the attribute data.

Data Provider Candle-provided data extractor for a specific type of data source. Examples of Universal Agent Data Providers are: File, Socket, HTTP, SNMP, Post. A single Universal Agent can support multiple Data Providers


concurrently, and a single Data Provider can monitor multiple applications.

data provider console A facility that permits you to dynamically control the Data Provider using commands.

data source Indicates the source of the data coming into a Data Provider

E

event A change in the status of a situation you are monitoring.

M

managed object A visual representation, typically an icon, of one or more situations being monitored on one or more managed systems. As the status of a situation changes, the appearance of a managed object icon on your workstation changes.

managed system Any system, such as UNIX, Windows, or MVS, that OMEGAMON XE is monitoring.

P

policy A collection of activities that provides the capability of automating responses to events or routine operator tasks.

S

situation A logical expression involving one or more system conditions (attributes) that are of the form

If - system condition - compared to - value - is true

An example of a situation isIF - CPU usage - GT - 90% - TRUE

IF and TRUE appear in every situation. The expression “CPU usage GT 90%” is the situation predicate.

U

Universal Agent A generic monitoring agent that can monitor any user-defined data and make it available to a CMS for evaluation. Each Universal Agent managed application is represented as an OMEGAMON XE managed system.

W

workspace Displays of data from managed systems. The data may be real-time or historical. Users filter the displays and produce charts.The monitoring characteristics of an Universal Agent can be dynamically tailored at runtime.

Index 259

Index

AACTION workspace 132activating metafiles

automatically 54using a configuration file 52using console commands 53with console commands 51

address translation 79Adobe Portable Document Format 18Adobe portable document format 14Agent_Info attribute 109Agent_Name attribute 109, 114API Server Data Provider 75–77

calling programs 77console commands 77overview 75specifying host 77specifying port 77

APPL statement 153ASFS Data Provider 37associating data sources with metafiles

explicit association 82–84SOURCE statements 80–82

attribute definitions 190–195attribute group

data redirection 168invisible 156

attributesdefining 190–195derived 198duplicate 194enumeration support 196filtering 202–205invisible 195key 192left truncation 196selecting 134

sequencing definitions 206–208ATTRIBUTES statement 118, 183–195automation policy 30

CCandle Customer Service and

Satisfaction 18Candle web site 13character code specification

association record 86in SOURCE statements 86

cleanup programs 60client programs

for Socket Data Provider 79configuration file

creating 52location 53sharing 53

CONFIRM statement 173console command interface, invoking on

UNIX 211console command interface, invoking on

Windows 210console commands 209–234

DELETE 215GENERATE 216IMPORT 220LIST 221LOADCOMM 222LOADNAME 224MNL ADD NODE 225MNL REMOVE NODE 226REFRESH 227sending 67SET 228SHOW 229SHUTDOWN 231

D


specifying names in 211summary 210TRAPCNFG 232UNPACK 233using 210–214VALIDATE 234

Consolidated Data Provider, see ASFS Data Provider

control statements 149–187APPL 153attribute definitions 190–195ATTRIBUTES 183–195CONFIRM 173NAME 154–157RECORDSET 168–172SNMP 151SOURCE 162–167SQL 174SUMMARY 176–182

custom WBEM applicationscreating 108example 110

customer support 18Customer workspaces 126–128

creating help for 128customizing contents 127names 127overview 126

customizing workspace contents 127

Ddata acknowledgment 87data collection 110

starting 111stopping 112

data definitions see metafilesData Providers 63–120

API Server 75–77ASFS 37environment variables for 65File 69–74HTTP 96–103

ODBC 115–120Post 89–95running multiple instances 65SNMP 104Socket 78–88types 64WBEM 105

data redirectionINPUT statement 158OUTPUT statement 158overview 168

DELETE console command 215deleting managed systems 61derived attributes 198disconnection notification 87documentation set information 12DPLOG workspace 130duplicate applications 68duplicate attributes 194dynamic file name support 71–73

Eediting variables 39environment variables 235–248

location of 39, 236setting 39, 236

FFile Data Provider 69–74

multiple record input 70overview 69required location 69sampling frequency 69special extracting routines 70

GGENERATE command 120GENERATE console command 216generating metafiles 120

Index 261

H

Hhelp

creating 47viewing 128

help text, defining 193historical data collection 137HTTP Data Provider 96–103

monitoring a URL 97overview 96URL attributes 100

IIMPORT console command 220importing metafiles 109INPUT statement 158instance names 65INTERNAL statement 158

Kkey attributes 192KUM_DCH_HOST_NAME 211KUMA_STARTUP_DP 38, 41, 106, 115KUMDPLOG 56KUMENV 40KUMENV file 39, 236KUMP_API_DPAPI_HOST 77, 212KUMP_API_DPAPI_PORT 77KUMP_DP_EVENT 69KUMP_DP_HOSTNAME 80KUMP_DP_PORT 79KUMP_DP_SAMPLE_FACTOR 70KUMP_DPCONSOLE_PORT 67KUMP_INIT_CONFIG_PATH 53KUMP_META_PATH 54, 56KUMP_META_SERVER 55, 56KUMP_POST_DP_PORT 89KUMP_TCP_DISCONNECT_BY_TTL 87KUMP_TCP_OUTAGE_WINDOW 86KUMPCNFG 52

example 53location 53

sharing 53KUMPCON program 210KUMPOST metafile 91KUMPSEND program 91, 94

LLIST console command 221LOADCOMM 222LOADNAME 224location field (in SOURCE statement) 80

MManage Candle Services 42managed system

names 96managed system list 135managed systems

deleting 61names 123–124overview 123version changes 124–125version numbers 124

MAS application 91metafile server 55–57

designating 55determining client/server roles 56overriding definition 57overview 55storing metafiles 55synchronization with client 56

metafilesactivating 51–54associating with data sources 80–84creating 45–48examples 186–187naming 46resetting version number of 60storing 47, 56validating 49versioning of 58–61

migrating to V400 255

N


MNL ADD NODE console command 225MNL REMOVE NODE console

command 226modification number 59modifying metafiles 58–61monitoring interval 135–136monitoring Universal Agent

applications 121–137multi-interface systems 211multiple host machines 79multiple record input 70

NNAME statement 117, 119, 154–157notification of disconnection 87

OODBC Data Provider 115–120

data collection 116generating metafiles

automatically 120sample metafile 116, 118starting 115

outages 86OUTPUT statement 158

PPDF files, adding annotations 15policy, automation 30Post Data Provider 89–95

acknowledgment stamp 91configuring runtime specifications 92–93customizing 91default configuration 89–90environment variables 92message categories 90overview 89product-provided data 93sending data to 95

printing problems 14

RRECORDSET statement 168–172REFRESH console command 227resetting version numbers 60

Sscenario 28–31SET console command 228SHOW console command 229SHUTDOWN console command 231Situation editor 133situations 133–136

definition 133distributing 135overview 133predefined 133selecting attributes 134setting monitoring interval 135–136using 133

SNMP Data Provider 64, 104SNMP emitter 139–146

environment variables 141establishing parameters 143installing 142integrating 142overview 139platform support 140protocol 141using data 145

SNMP statement 151Socket Data Provider 78–88

address translation 79associating sources with metafiles 80–84changing default port 79character code translation 85–86contacting 79end of input 85formatting buffers 84limitations 88name and address translation 79on multiple host machines 79

Index 263

T

overview 78timing out 84

SOURCE statement 117, 119, 162–167SQL statement 117, 119, 174startup parameters

UNIX 42Windows 42

storing metafiles 47storing server metafiles 56SUMMARY statement 176–182

Ttailbyrecord 74TCP 79, 88TCP outage detection 86timestamp insertion 156time-to-live (TTL) interval 69, 135–136,

155TRAPCNFG 232truncation 67TTL, see time-to-live interval

UUAGENT application 129UDP 79, 84, 85, 88um.config file 39um_cleanup 60um_cleanup.bat 60Universal Agent API client package 76Universal Agent APIs, invoking 75Universal Agent applications

creating 44definition 44monitoring 121–137

Universal Agent applications see also metafiles

Universal Agent managed systems 123–125UNPACK console command 233

VVALIDATE command 109

VALIDATE program 234description 49running 49sample output 50

validating metafiles 49variables file

location 39, 236name of 39, 236

variables, editing 39version number

incrementing 58, 60resetting 60

versionsof managed systems 124of metafiles 58–61

WWBEM Data Provider 105

starting 106stopping 107

WBEM Manager application 107windows monitoring applications 107working directory, setting 40, 236workspace

ACTION 132DPLOG 130

W
