Hawk Admin

TIBCO Hawk Administrators Guide
Software Release 4.2.1 April 2004
Important Information
SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE. USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THIS DOCUMENT). USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME. This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc. TIB, TIBCO, Information Bus, The Power of Now, TIBCO Adapter, TIBCO Hawk, TIBCO Designer, TIBCO Rendezvous, TIBCO ActiveEnterprise and TIBCO Repository are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries. EJB, J2EE, JMS and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only. This software may be available on multiple operating systems. However, not all operating system platforms for a specific software version are released at the same time. Please see the readme.txt file for the availability of this software version on a specific operating system platform. THIS DOCUMENT IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME. Copyright 1999-2004 TIBCO Software Inc. ALL RIGHTS RESERVED. TIBCO Software Inc. Confidential Information
| iii
Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TIBCO Hawk Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Other TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Third Party Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi xvi xvii xvii
How to Contact TIBCO Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Chapter 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Scalability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Location Transparency and Fault Tolerance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . System Management Over Networks of Any Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Advanced Monitoring Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Flexibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 5 6 6 6 7
Functional Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 The TIBCO Rendezvous System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 TIBCO Hawk Agents and Microagents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Rulebases and Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 TIBCO Hawk Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 AMI Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Console API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Configuration Object API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Event Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Chapter 2 Getting Started with TIBCO Hawk Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

TIBCO Hawk Display Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Starting TIBCO Hawk Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Working with Agent View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Customizing a Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
iv
| Contents
Working with Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sending Agents to a Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Renaming a Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting a Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Finding an Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Canvas View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing Canvas View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding Agents to the Canvas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding Shapes to the Canvas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the Canvas View for Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 21 22 22 23 23 25 25 26 27 29
Working with Rulebase View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Working with Display Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Saving a Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Loading Display Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Setting Preferences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a Command to the Tools Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a Command to the Agent Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying the Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 36 38 41
Chapter 3 Working with TIBCO Hawk Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Viewing Microagents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Invoking a Microagent Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Subscribing to a Microagent Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Creating a Subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Viewing Subscription Results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Viewing Alert Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Suspending Alert Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Clearing Alert Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Console Warning Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 58 60 60
Chapter 4 Monitoring with Rulebases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Default Installation Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Creating a Rulebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Building a Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Specifying a Data Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Defining Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Creating a New Test. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Building a Test Expression. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Contents v
Building Compound Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Using Advanced Test Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Defining Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Using Advanced Action Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Saving a Rulebase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Working with Rulebase Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Saving a Rulebase to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Loading a Rulebase from a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing a Rulebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Copying an Existing Rulebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Removing a Rulebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Distributing a Rulebase to Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sending a Rulebase to Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Removing a Rulebase from Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 89 90 90 91 92 93 93 94
Chapter 5 Managing Your Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Choosing a Configuration Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Using Automatic Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Using Manual Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Configuration Path Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Repository Option. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Saving a Rulebase in a Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sending a Rulebase to a Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Removing a Rulebase from a Repository. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 100 101 103 104 106
Understanding Configuration Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Chapter 6 Using the TIBCO Hawk Event Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AMI Instrumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Persistence of TIBCO Hawk Events using JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Fault Tolerance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 112 113 114
Interpreting Event Service Data Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Executing Commands on Loss of Heartbeat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Using the Event Service for Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Chapter 7 Advanced Rulebase Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Using a Rulebase Map. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 Creating a Rulebase Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 Working with Agent Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 Defining Agent Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 Adding Agents to a Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
vi
| Contents
Mapping Rulebases to Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mapping Groups to External Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Saving a Rulebase Map in a Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Saving a Rulebase Map to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 130 131 133
Including a Rulebase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 Adding Commands to a Rulebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 Specifying Rulebase Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 Executing Rulebase Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Referencing Variables in a Rulebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Referencing External Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Referencing Internal Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Referencing Data Source Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How Variable Substitution Affects Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 139 140 141 141
Overruling a Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Allowing Overruling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Overlapping Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 Using Posted Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 Testing for Non-Zero Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 Counting Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 Working with Schedules and Period Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Schedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Period Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing Schedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Applying Schedules to Rulebase Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Schedule Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Saving a Schedule File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Distributing Schedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Loading Schedules From a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Importing Schedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing Schedule Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 148 149 157 164 166 168 168 168 169 170 171
Automating Rulebase Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Chapter 8 Planning Your Monitoring Strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 Define Problem Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Define Information Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Identify Corrective Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Map Information Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Map Action Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Refine Corrective Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 175 175 176 176 177
Translate Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Contents vii
Transform to Rule Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 Plan Rulebases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 Formulate Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Build and Test Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Refine Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Use Alternate Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 180 180 181
Chapter 9 Performing Common Monitoring Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Monitoring Process Existence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 Identifying Same-Named Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 Using Posted Conditions to Monitor Same-Named Processes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 Monitoring Process Resource Consumption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 Automating Process Resource Consumption Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 Monitoring File System Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Tips on Monitoring File System Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Automating File System Space Monitoring. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Monitoring System Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 Automating System Resource Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 Monitoring Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tips on Monitoring Log File Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Automating Log File Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Monitoring With Pattern Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About Rolling Log Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 192 194 194 194
Monitoring with Custom Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 Tips on Monitoring Custom Scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Automating Custom Script Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 Monitoring AMI Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Chapter 10 Performing Group Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 Interrogating Microagents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 Performing Network Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 Performing Network Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Chapter 11 Program Internationalization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Internationalization Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 Why is Unicode Important? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 Using Japanese Characters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 Japanese Characters in Agents and Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 Japanese Characters in External Variables File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
viii
| Contents
Changing the Encoding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Appendix A Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Appendix B Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 Alerts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 Configuring Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 Error messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 Command Lines and Process Names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 Rulebases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Appendix C TIBCO BusinessWorks and Hawk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TIBCO Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TIBCO Runtime Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TIBCO Domain. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 245 245 245
Integrating with Third Party Management Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Appendix D Using Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Perl5PatternMatch Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 REGEXP Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Appendix E Interpreting TIBCO Hawk Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 Interpreting the TIBCO Hawk Agent Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 Interpreting the TIBCO Hawk Display Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 Interpreting the TIBCO Hawk Event Service Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 Interpreting TIBCO HawkHMA Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258 Viewing Rolling Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Appendix F Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Contents ix
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 Error Code List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .335 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
| Contents
| xi
Figures
Figure 1 Figure 2 Figure 3 Figure 4
TIBCO Hawk System Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Relationship Between Objects in a Rulebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Flow of Rules and Tests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Rolling File Mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
xii
| Figures
| xiii
Tables
Table 1 Table 2 Table 3 Table 4 Table 5 Table 6 Table 7 Table 8 Table 9 Table 10 Table 11 Table 12 Table 13 Table 14 Table 15
Default Agent Alert Level Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Test Operators For Numeric Method Results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Test Operators for Text String Results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Test Operators for Boolean Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Action Types in the Action Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Configuration Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Table Layout for HawkAgentInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Table Layout for HawkAlertClearInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Numeric Representations of Alert Levels in Event.dat Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Mapping Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 Method to Retrieve Information and Perform Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 Perl5PatternMatch Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 Regular Expression Modifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 REGEXP Regular Expression Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 Error Handling Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
xiv
| Tables
| xv
Preface
This manual describes the TIBCO Hawk Enterprise Monitor, a tool for monitoring and managing applications and operating systems. It is intended for systems and network administrators who need to implement TIBCO Hawk software and use TIBCO Hawk Display. This manual also provides useful background information for Console API, Configuration Object API, or Application Management Interface (AMI) programmers who want to learn about TIBCO Hawk system features. This manual assumes you are familiar with TIBCO Rendezvous architecture and the concepts of system monitoring.
Topics
Related Documentation, page xvi How to Contact TIBCO Customer Support, page xviii
xvi
| Related Documentation
Related Documentation
This section lists documentation resources you may find useful.
TIBCO Hawk Documentation

The following documents form the TIBCO Hawk documentation set: TIBCO Hawk Release Notes Contains late-breaking news and information, as well as descriptions of new features, migration paths, and open and closed issues. TIBCO Hawk Installation and Configuration Read this book first. It contains step-by-step instructions for installing TIBCO Hawk software on various operating system platforms. It also describes how to configure the software for specific applications, once it is installed. An installation FAQ is included. TIBCO Hawk Administrators Guide This manual includes basic descriptions of TIBCO Hawk concepts, instructions for using TIBCO Hawk Display, monitoring strategies with examples, a comprehensive FAQ, and a glossary. All books in the documentation set refer to features explained in this book. TIBCO Hawk Programmers Guide All programmers should read this manual. It covers the AMI protocol, AMI messages, the AMI Workbench development tool, and the TIBCO Hawk security framework and its classes. Programmers should then refer to the appropriate language reference for the AMI API. The TIBCO Hawk Application Management Interface (AMI) exposes internal application methods to TIBCO Hawk. TIBCO Hawk AMI C Reference Contains detailed descriptions of each datatype and function in the TIBCO Hawk C AMI API. TIBCO Hawk AMI C++ Reference Contains detailed descriptions of each datatype and function in the TIBCO Hawk C++ AMI API. TIBCO Hawk AMI Java Reference Contains detailed descriptions of each class and method in the TIBCO Hawk Java AMI API. TIBCO Hawk Console API Reference Contains detailed descriptions of each class and method in the TIBCO Hawk Console API, a set of Java interfaces that allow you to manage and interact with TIBCO Hawk agents and monitor alerts generated by these agents. TIBCO Hawk Configuration Object API Reference Contains detailed descriptions of each class and method in the TIBCO Hawk Configuration Object API. TIBCO Hawk Methods Reference A reference to the microagents and methods used by a TIBCO Hawk Agent for system and application monitoring.
Preface xvii
Other TIBCO Product Documentation

You may find it useful to read the documentation for the following TIBCO products: TIBCO Rendezvous software: This is TIBCOs real-time transport layer that is used by TIBCO Hawk. TIBCO Adapter SDK software, including TIBCO AdapterAdministrator and TIBCO Repository: These related products are used to manage TIBCO ActiveEnterprise data and metadata.
Third Party Documentation

You may find the following third-party documentation useful. The Java Language Specification by Gosling, Joy, and Steele
xviii How to Contact TIBCO Customer Support
How to Contact TIBCO Customer Support

For comments or problems with this manual or the software it addresses, please contact TIBCO Support Services as follows. For an overview of TIBCO Support Services, and information about getting started with TIBCO Product Support, visit this site: http://www.tibco.com/services/support/default.jsp If you already have a valid maintenance or support contract, visit this site: http://support.tibco.com Entry to this site requires a username and password. If you do not have a username, you can request one.
|1
Chapter 1
Introduction
This chapter provides an overview of the TIBCO Hawk system. It discusses the architecture and features of TIBCO Hawk product components.
Topics
Overview, page 2 Architecture, page 3 Features, page 5 Functional Components, page 8
| Chapter 1
Introduction
Overview
TIBCO Hawk is a tool for monitoring and managing distributed applications and operating systems. Unlike other monitoring solutions, TIBCO Hawk software uses TIBCO Rendezvous software for all communication and inherits many of its benefits. These benefits include a flexible architecture, enterprise-wide scalability, and location- transparent product components that are simple to configure. TIBCO Hawk is an event-based system built around the concept of a distributed, autonomous smart agent that operates on each managed machine in the network. The software is designed specifically for monitoring distributed systems, so there is no centralized console or frequent polling across the network. With this structure, TIBCO Hawk is able to scale to multi-thousand node global networks without the use of hierarchical managers and has the flexibility to allow individual managed entities to be added or modified without the need to re-configure or re-start any other parts of the system. The work required to monitor applications and systems is performed by TIBCO Hawk agents. An agent can be a rulebase, rulebase map, or schedules object. An agent runs on each node on the network and monitors local conditions. Each agent uses collections of locally loaded rules organized into rulebases to apply monitoring logic. A rulebase tells an agent how to monitor particular application or system resources and what actions to take when specific conditions are detected. TIBCO Hawk includes pre-built rulebases that monitor basic system level parameters, and administrators can build additional rulebases using editors in TIBCO Hawk Display. Rulebases can be selectively loaded to an agent or group of agents on a temporary or permanent basis. The TIBCO Hawk Display application subscribes to alert messages generated by TIBCO Hawk rulebases and presents them in an organized view. Alerts are color-coded to indicate the severity of a reported problem. Clicking on a node displays the error message along with a recent history of problems on the node. TIBCO Hawk Display does not store centralized monitoring intelligence; it simply offers a view of events on your distributed systems. Adding more instances of the Display application requires no additional network overhead or configuration.
Architecture 3
Architecture
The following diagram gives an overview of TIBCO Hawk system architecture. Figure 1 TIBCO Hawk System Architecture
TIBCO Hawk Display
Application
AMI
Agent
TIBCO Rendezvous
Host System (Managed Node) publish/ subscribe
TIBCO Hawk Display publish/subscribe
Application
API
AMI
Host System (Managed Node) Adapter or Gateway
Host System (Managed Node)
TIBCO Hawk Event Service
TIBCO Hawk Event Service
The TIBCO Hawk system is made up of two main components: agents and Console Applications. Agents perform the bulk of the monitoring duties, and Console Applications act as user interfaces for status and configuration (TIBCO Hawk Display), historical event loggers (TIBCO Hawk Event Service), or bridges to other management systems.
| Chapter 1
Introduction
The right side of the diagram shows TIBCO Hawk agents installed on machines to monitor local resources and conditions. Default microagents are used to monitor objects such as operating system performance, processes, log files, application metrics or the status of TIBCO Rendezvous sessions. The left side of the diagram shows how user applications can be instrumented and monitored using TIBCO Hawk agents. In both scenarios, the TIBCO Hawk Application Management Interface (AMI) protocol acts as a gateway between the applications management capabilities and the local TIBCO Hawk agents. An application can be directly instrumented with the AMI protocol to expose its management operations and data. If an application already employs a management interface other than AMI, an AMI adapter can be built to allow the agent to discover and exercise it.
Features 5
Features
As the complexity and size of a distributed network increases, most tools that manage these networks also increase in size and complexity. Many of these tools use a centralized approach for gathering information and performing tasks, making heavy use of polling and point-to-point messaging. The result can be excessive network bandwidth, bottlenecks, and compromised reliability and efficiency of the network. TIBCO Hawk addresses these problems by providing a monitoring solution that is scalable, location transparent, and reliable.
Scalability
A scalable network management tool seeks to minimize network traffic so the least amount of bandwidth is used. Also, to be truly scalable, the bandwidth consumed should not grow proportionately as a distributed network grows. One way TIBCO Hawk achieves scalability is by using TIBCO Rendezvous as the underlying communication layer. This communication is extremely efficient and reliable. A message sent to 100 nodes in the network uses the same network bandwidth as a message sent to 10 nodes. Applications that use TIBCO Rendezvous are inherently scalable. For more information, refer to TIBCO Rendezvous Concepts. TIBCO Hawk agents monitor conditions on their local machines and send alerts over the network only when problems are detected, an approach that has major scalability advantages over a central, dedicated console server. With centralized server-based architectures, monitoring data is collected from remote nodes via network polling or point to point messages to the console generated by simple agents on the devices. After gathering or receiving this information, the console server then makes centralized monitoring decisions. The network bandwidth consumed by polling-based systems grows proportionately with the number of monitored nodes, as does resource utilization on the console machine. Eventually, additional console servers must be employed to scale the system. Using the distributed event-driven monitoring architecture employed by the TIBCO Hawk system, network bandwidth and system resources are conserved by decentralizing and distributing the monitoring load. Another advantage of this method is that alerts are generated only when a problem exists, so under normal conditions minimal network bandwidth is used.
| Chapter 1
Introduction
Location Transparency and Fault Tolerance

A TIBCO Hawk agent runs on each node, where it collects information, applies monitoring logic, and carries out event notification and corrective actions. TIBCO Hawk agents are autonomous because they monitor and perform management tasks independently of TIBCO Hawk Display. TIBCO Rendezvous messages between agents and TIBCO Hawk Display use subject-based addressing, so the physical location of each component is unimportant. Fault-tolerance is built in because agents perform tasks independently of other agents. If one or more agents on the network ceases to function, other agents continue to monitor local data and perform tasks. In the console server model, if the server becomes disabled, all monitoring stops until another console server can be brought on line. Additionally, as all connections are point-to-point, all remote agents must be manually reconfigured to connect to the new server and all polled connections need to be rediscovered. Multiple instances of TIBCO Hawk Display can run without configuration modifications or incurring additional network overhead. The centralized approach to distributed application management usually requires that all configuration and management tasks be performed from a single console. Additional consoles in such systems incur a proportional increase in the network traffic required for monitoring, and often require considerable configuration changes.
System Management Over Networks of Any Size

Using TIBCO Hawk Display, administrators can easily monitor and manage nodes in a large, distributed network using a collective or "follow the sun" approach. Administrators can be in Tokyo, New York and London, each viewing and managing the same group of TIBCO Hawk agents. Each administrator can construct a customized view with his or her own unique Display arrangements. Alerts viewed by the administrators are consistent across all instances of TIBCO Hawk Display and other applications (built with the TIBCO Hawk Console API) in the network.
Advanced Monitoring Logic

TIBCO Hawk provides flexibility in performing monitoring tasks. The rules or policies you create can be very simple or complex. Using advanced features, you can implement solutions like the following: Automatically restart a failed process. Create a series of escalating actions to respond to a continuing or deteriorating problem.
Features 7
Clear an alert when certain criteria are met. Selectively ignore an intermittent condition and respond only after it persists. Take an action when an alert clears, such as sending a stand-down notice to a backup systems administrator who is on call. Switch rules automatically to support different monitoring setups. Create thermostat-like controls to respond to fluctuating conditions. Automatically alter monitoring behavior based on user defined schedules.
Flexibility
A distributed network typically must support multiple platforms and enterprise applications. In such a heterogeneous environment, many different combinations of objects require monitoring and many variations of routine tasks require automation. The TIBCO Hawk environment is flexible enough to support these variations, both internally and through components designed to communicate with external application environments. Administrators can tailor the TIBCO Hawk environment by building custom rules and by automatically executing commands and custom scripts. Programmers can extend TIBCO Hawk by instrumenting applications using the AMI protocol, or by using AMI to build gateways between agents and non-instrumented applications. The Console API also provides a comprehensive interface for communicating with TIBCO Hawk agents, allowing programmers to build customized display applications or sophisticated, multi-level decision-making programs that can draw data across multiple agents. The Configuration Object API allows you to build custom rulebases. Using the Configuration Object API you can also build a custom rulebase editor.
| Chapter 1
Introduction
Functional Components
This section gives a general overview of the functional components of the TIBCO Hawk enterprise monitor.
The TIBCO Rendezvous System

TIBCO Hawk uses TIBCO Rendezvous for all network and intra-machine communications between the various TIBCO Hawk components. It supports both broadcast or multicast network environments. WAN connectivity is provided through the use of the TIBCO Rendezvous routing daemon, which routes messages efficiently and reliably between networks.
TIBCO Hawk Agents and Microagents

In a TIBCO Hawk environment, agents on each local computer perform the monitoring work. Agents use objects called microagents to represent and interact with managed objects. Microagents support methods which are invoked to extract monitoring information and carry out specified tasks. This allows a total de coupling of the management data from the management rules or policies. Microagent methods can be accessed and invoked from TIBCO Hawk Display or Console API applications. They are also used with the agent's powerful rules engine in autonomous monitoring. Microagents are available for managed entities such as log files, custom executables, operating system performance metrics, processes, file systems, event logs, and services. Applications instrumented with AMI are dynamically discovered and represented by microagents, allowing them to be monitored and managed. Each microagent runs within an agent but the managed application it represents can be a separate process. The agent itself is represented by microagents, allowing it to be configured and managed in the same manner as any other managed entity.
Rulebases and Rules

A rulebase is a collection of one or more rules. A rule is a user defined monitoring policy. It specifies a data source in the form of a microagent method, one or more tests that check for conditions, and one or actions to perform if a test is true.
Functional Components 9
With TIBCO Hawk rulebases, you can perform general monitoring tasks and test for very specific conditions. Escalations can be applied to actions to allow for a staged response to a condition. An agent can be configured to initially take corrective actions itself, but if the condition still persists, then call for outside help from administrators. The rulebase editor in TIBCO Hawk Display allows easy construction of simple and complex rules. No scripting is required and an administrator does not need to learn special rule syntax. The rules of a rulebase are typically constructed so that each rulebase focuses on monitoring a particular application or system resource. The rulebases are then assigned to multiple agents with similar monitoring requirements. Configuration options provide flexible mechanisms for distributing rules. Adding a new rulebase to one agent or 1000 agents takes the same amount of time. All rulebase changes are performed dynamically in the agent with no required restart. Schedules can be imposed on the rulebase hierarchy to control when monitoring activity and corrective tasks are performed. In a schedule you can define both inclusion and exclusion periods during which an object can be active. Like rules, schedules can be distributed to multiple agents with similar requirements.
TIBCO Hawk Display

The TIBCO Hawk Display application is the primary means of interacting with managed objects on your network. The main window of the TIBCO Hawk Display graphically represents system behavior with each monitored computer represented by a container icon. You use application menus and dialogs to create, modify and distribute rulebases, which control the monitoring behavior of TIBCO Hawk agents. TIBCO Hawk Display can be run over a regular dial-up line with the same functionality as well as on the network. The TIBCO Hawk Display is not a centralized console server with management logic, but a local window into activity on your network. All TIBCO Hawk Display users view the same managed objects without complicated configuration schemes. Each user can also customize their instance of the TIBCO Hawk Display interface without affecting others. The agent processes themselves are monitored using TIBCO Hawk Display and other Console API-based applications. If an agent stops communicating with the application, it will be detected and appropriate notifications will be made automatically.
10
| Chapter 1
Introduction
AMI Protocol
The TIBCO Hawk Application Management Interface (AMI) is an open, TIBCO Rendezvous-based protocol for instrumenting an application with an extremely powerful management interface. Applications can be monitored and controlled from the inside using the tools of the TIBCO Hawk system in the same way as any other system component. The protocol allows for complete independence between the TIBCO Hawk agents and the managed application with two-way dynamic discovery. Information and action methods within an application are exposed to the agent in the same format as any other microagent. They are available for use within rulebases and for invocation or subscription and Network Query/Action calls from TIBCO Hawk Display and Console API applications. AMI features are as follows: AMI API libraries that implement the protocol are provided in C, C++ and Java. Direct AMI using the TIBCO Rendezvous APIs is also supported in ActiveX, and Perl. AMI can be easily back-fitted into existing applications, even those that do not currently use TIBCO Rendezvous, and expose existing internal application methods to a TIBCO Hawk agent. Third-party applications can be managed by writing an AMI wrapper that interfaces with an API or other mechanism provided by the application for the purpose of managing it.
For more information, see the TIBCO Hawk Programmers Guide.
Console API
The Console API is a comprehensive set of Java interfaces that a programmer can use to interact with TIBCO Hawk agents. TIBCO Hawk Display uses the Console API to monitor and manage agent behavior on your network. Using the Console API, programmers can write custom applications that monitor agent behavior, subscribe to alert messages and invoke microagent methods. For example, a sophisticated load-balancing program could draw information from TIBCO Hawk agents. For more information, see the TIBCO Hawk Console API Reference.
Functional Components 11
Configuration Object API

The TIBCO Hawk Configuration Object API is a Java language interface for writing custom rulebases. Rulebases are used by TIBCO Hawk agents to monitor and manage systems and applications. The Configuration Object API provides classes to define rules, tests and actions. Instances of these classes are put together to define a new rulebase. For more information, see the TIBCO Hawk Configuration Object API Reference.
Event Service
The TIBCO Hawk Event Service is a Console API-based application that records the activity of TIBCO Hawk agents. The Event Service logs all TIBCO Hawk system events such as agent activation and expiration, alerts, clears, and microagent and rulebase changes. It writes entries on these activities to data files, which can be accessed by external applications. It can also execute a user-supplied script to notify system administrators of an expired agent.
12
| Chapter 1
Introduction
| 13
Chapter 2
Getting Started with TIBCO Hawk Display
This chapter demonstrates how to start using the TIBCO Hawk Display, and provides instructions for customizing a Display and setting preferences.
Topics
TIBCO Hawk Display Overview, page 14 Starting TIBCO Hawk Display, page 15 Working with Agent View, page 16 Customizing a Display, page 20 Working with Containers, page 21 Working with Canvas View, page 25 Working with Rulebase View, page 31 Working with Display Files, page 33 Setting Preferences, page 35
14
| Chapter 2
TIBCO Hawk Display Overview

TIBCO Hawk Display is an application for viewing and managing TIBCO Hawk agents on a network. You use TIBCO Hawk Display to discover TIBCO Hawk agents that are running, and to create agents such as rules and schedules that can be stored locally or on the network. TIBCO Hawk Display also allows you to communicate with microagents that respond to instructions on each agent machine. When monitoring or performing management tasks, TIBCO Hawk Display communicates with TIBCO Hawk agents on your network. A TIBCO Hawk agent receives the message and uses a microagent to do the work. Like other TIBCO Hawk product components, TIBCO Hawk Display is location-independent. One or more instances of TIBCO Hawk Display can run on any machine on your network, and each can show the same view of objects and events. TIBCO Hawk Display is also platform-independent, so an instance running on Microsoft Windows XP, for example, can monitor events on all platforms supported by TIBCO Hawk.
Starting TIBCO Hawk Display 15
Starting TIBCO Hawk Display

To start an instance of TIBCO Hawk Display on Microsoft Windows: Select TIBCO Hawk Software>Hawk Display from the Start menu, or double-click Hawk Display in the TIBCO Hawk program group.
To start an instance of TIBCO Hawk Display on UNIX: Type startdisplay at a command prompt. The TIBCO Hawk Display main window displays:
16
| Chapter 2
Working with Agent View

When you start TIBCO Hawk Display, the display is in Agent View. In this viewing mode, each container or object is represented by a standard icon. TIBCO Hawk Display dynamically discovers TIBCO Hawk agents on your network. Newly-discovered agents are grouped by subnet and placed in a container nested under agents, labeled Discovered. At first, the agents container is empty. Its counter displays a value of zero and, on the right, the Discovered counter is also at zero. Both icons are initially green in color to show that no alerts, or warning messages, are in effect. As agents are discovered, the counters increment to reflect the current number of discovered agents:
Monitored network nodes are arranged in a hierarchical tree of containers. Clicking a container in the left panel displays nested items on the right.
Working with Agent View 17
The following figure describes the TIBCO Hawk Display icons:

Create Default Display Save Display to a File Display Preferences About TIB/Hawk Console Warning Messages
Open Display file
Find Agent in a Container
Add new container
Perform Network Query
To see more information about discovered agents, double-click icons to expand the list:
18
| Chapter 2
Icon color also changes, showing the highest level of alert found on discovered agents. An icon can display up to six colors, which are explained in the following table: Table 1 Default Agent Alert Level Colors Default Color
Purple
Alert Level Meaning

The agent was discovered but currently no heartbeat message is being received. The lack of response could mean the agent is not running, the agent machine is down, or a network communication problem exists. At least one high-level alert is active. At least one medium-level alert is active. At least one low-level alert is active. The agent is recovering. At least one alert was active within the last 30 minutes (default), but any active alerts were recently cleared or suspended. No alerts are in effect.
Red Orange Yellow Cyan
Green
Note: You can change alert level colors in the Preferences dialog. For more information, see Setting Preferences on page 35. Each container icon is split horizontally into two equal sections. The upper section represents all agents in the container, and is always a single color. This color reflects the highest level of alert found on any agent.
Number of agents in the container Relative proportion of alert levels on all agents
Highest alert level on any agent
The lower section shows the distribution of each alert level on the network. This section consists of a stacked bar graph that shows the relative proportion of alert states among agents. Each colored segment represents the percentage of agents at a particular alert level. If the lower section is half red and half purple, then 50% of agents on the subnet are at a high level of alert and 50% are not responding. To view multiple windows on the right, right-click on another icon and select New View.
Working with Agent View 19
To control views that are currently displayed, right-click on an icon on the left and select either Activate View to bring it to the front, or Close View to close the window.
You can also view the contents of any agent container in a map-like scheme called Canvas View. This type of diagram can be customized to mimic your network architecture, clarifying relationships between monitored components, and thus making alert conditions easier to interpret. Ease of interpretation translates into a faster response when problems occur. For more information, see Working with Canvas View on page 25. In addition to discovering agents, TIBCO Hawk Display also discovers which rulebases they have loaded. All discovered rulebases are placed in the RuleBases container to form the Rulebase View. For more information, see Working with Rulebase View on page 31. If a Repository exists on your network, a Repository container will also be available. It holds all Repository instances discovered by TIBCO Hawk Display. Repositories can be used to centrally manage the available rulebases. For more information, see Using the Repository Option on page 101.
20
| Chapter 2
Customizing a Display
By default, TIBCO Hawk Display places discovered objects in containers organized by subnet. To create views that reflect the organization of your network, you create custom displays. A custom display has individualized container arrangements and agents organized into logical groups. After customizing a display, you can save it to a file and reload it whenever you start TIBCO Hawk Display.
Working with Containers 21
Working with Containers

Container icons in TIBCO Hawk Display store other icons for agents, Repositories or rulebases. When you start an instance of TIBCO Hawk Display, usually one container is created for each subnet and additional containers are created for top-level items. You can create additional containers for logically organizing agents.
Adding a Container
Default containers group agents by subnet, but you can add custom containers for grouping agents according to location, function, or any other logical criteria. You can also label custom containers to describe their contents. To add a container to a display: 1. Select Edit>Add Container from the TIBCO Hawk Display menu. The Add Container dialog displays. 2. Type a name for the new container and select a parent container from the list.
To place the container at the top level of the hierarchy, select the Agents container. 3. Click OK. The new container displays in the hierarchy. You might want to move agent icons to this container and delete unused default containers. For instructions, see Sending Agents to a Container on page 22 and Deleting a Container on page 23.
22
| Chapter 2
Sending Agents to a Container

After adding a new container, you move agent icons by sending them to the container. You can use this same procedure to nest a container inside another container. To send agents to a container: 1. Arrange TIBCO Hawk Display icons so the agents you want to send are shown in the panel on the right. 2. Right-click on an agent and select Send To from the menu. To select multiple agent icons, use the Control key or click and drag to create a selection box. The Send Selection(s) to Container dialog displays:
This dialog contains the same hierarchical view of your network that is displayed in the left panel of the main window. 3. Click the destination container, for example, New York. 4. Click OK. The agent icons are moved to the destination container, which is now active in Agent View.
Renaming a Container
You can rename custom containers to reflect functional and location clusters on your network. To rename a container: 1. Arrange the TIBCO Hawk Display so the container to rename displays on the right.
Working with Containers 23
2. Right-click on the container and select Edit from the menu. The Edit Container dialog displays.
3. Type the new name, then click OK. The name of the container in TIBCO Hawk Display is modified. You will not be allowed to rename the Discovered container.
Deleting a Container
You can delete empty containers that are no longer needed. For example, you might delete an empty default container after adding and filling new custom containers. To delete a container: 1. Arrange the TIBCO Hawk Display so the container to delete displays on the right. You can only delete empty containers. If the container you want to delete is not empty, double-click to open it, then select the agents inside and send them to another container. 2. When the container is empty, right-click on the container and select Delete from the menu. The container is immediately deleted. If the Discovered container is deleted, it will be re-created upon discovery of a new agent that is not currently located in another container.
Finding an Agent
In elaborate container hierarchies, you can use the Find Host command to locate an agent icon in a container. If default containers are used, this feature is also useful for determining the subnet where the agent is located. To find the container for an agent icon in TIBCO Hawk Display: 1. Select Edit>Find Agent from the TIBCO Hawk Display menu. The Find Agent dialog displays.
24
| Chapter 2
2. Type the name of the agent to locate, then click OK. You can also select an agent name from the dropdown list which saves up to a maximum of 16 previously entered agent names By default agents have the same names as the computers where they run. If the agent icon exists, a dialog displays the name of the parent container and provides you with an option to activate the container in which the agent is found.
3. Click YES if you want to activate the network container.
Working with Canvas View 25
Working with Canvas View

Canvas View is an alternate way to view and work with containers and agents in TIBCO Hawk Display. It provides a customizable map of objects on your network, along with graphics editing capabilities. You can use these features to represent relationships as accurately as possible and quickly interpret network events when they occur. This example demonstrates how to represent objects and relationships on your network using Canvas View.
Accessing Canvas View

To change your display from Agent View to Canvas View: Right-click in an Agent View window with nothing selected and select Canvas View from the menu.
A list of agents on the current node displays:
26
| Chapter 2
This Unmap list displays names of discovered agents that can be added to the canvas.
Adding Agents to the Canvas

1. Click an agent name to highlight it in the list. The cursor becomes a crosshatch shape. 2. Click in the grey canvas area to drop the object. A icon representing the agent is added to the canvas:
The name of the agent is removed from the Unmap list, and the color of its text label reflects the highest alert state on that agent. 3. Add remaining agents in the node to the canvas. When all agents are on the canvas, the Unmap list is removed until you delete an agent icon from the canvas, or load a new display. 4. Modify default agent icon bitmaps to reflect the type of hardware the agent runs on. By default, each agent is represented by a generic operating system icon. To change an icon bitmap, right-click on the icon and select a new icon type from the Image menu:
To specify a custom icon file in GIF format, use the Bitmap menu option. The canvas should look similar to the following:
You can access two separate right-click menus on the canvas. When an object is selected, the menu shown above displays. When no object is selected, a formatting menu for creating and editing objects displays:
Adding Shapes to the Canvas

1. Create a cloud shape to represent the local network by right-clicking on the canvas with nothing selected and selecting Shape>Cloud. The cursor becomes a crosshatch cursor. 2. Click on the canvas to drop the cloud shape. 3. Connect agents to the local network by right-clicking on the canvas with nothing selected and selecting Primitive>Connector. A small red x marks the center of each object when you pass over it with the mouse. Clicking on a mark creates a connector, and dropping it on another connects the two objects. Unlike a line, with a connector you can move either object and they remain attached.
28
| Chapter 2
4. Add a text label to the cloud shape by right-clicking with nothing selected and selecting Primitive>Text. The cursor becomes a crosshatch cursor. Click on the canvas to anchor the text object. 5. Type Local Network or similar text, then click As Label to give the text a white background on the canvas. The Text Properties dialog displays:
6. Click OK. The canvas should look similar to the following:
When you are finished editing and arranging objects, right-click and select Lock to disable the graphics editing features. In Lock mode, icons and the right-click menu behave like the agent icons in Agent View. 7. To return to Agent View, right-click with nothing selected and select View>Agent View from the menu. The changes you made are preserved until you exit TIBCO Hawk Display or load a new view. All graphic objects are saved, including images and shapes with positions, along with any property values you set. To save the Canvas View in a file for reuse, see Saving a Display on page 33.
Changing the Canvas View for Containers

1. Change the icon by right-clicking on the container, selecting Icon and choosing a shape from the Icon Properties menu.
To select a GIF file that contains the image for the icon, first click Browse to bring up the file chooser, navigate to the folder that contains the GIF files and select the GIF file. The file name selected from the file chooser will be added to the icon list. Then select the file from the icon list. 2. Select the position of the stack bar of alert levels:
3. Re-size the icon, enter the size in the width and height field.
30
| Chapter 2
4. Click OK. The canvas should look similar to the following:
Working with Rulebase View 31
Working with Rulebase View

In Agent View and Canvas View, TIBCO Hawk Display shows a container icon for each agent. Rulebase View displays an icon for each unique rulebase running in the network. If the same rulebase is running on multiple agents then all instances of this rulebase are represented by the same icon in Rulebase View. The Rulebase View is orthogonal to that available in the Agents container. If each rulebase is built to monitor a different application then Rulebase View effectively becomes an application-centric view. If a major problem occurs in the network which causes a large percentage of the network nodes to go red in the Agent containers, the user can switch to the Rulebase View to instantly determine which critical applications have been affected. To change TIBCO Hawk Display to Rulebase View: Click the Rulebases icon in the left panel. Individual rulebase icons display on the right:
Like container icons, rulebase icons display a count integer along with colors that represent current and relative alert states.
Highest alert level generated by any instance of the rulebase Number of agents with the rulebase loaded Relative proportion of alert levels for all instances of the rulebase
32
| Chapter 2
The count integer represents the number of agents on the network that have loaded the rulebase. The upper section shows the highest level of alert generated by any instance of the rulebase. The lower section shows the proportion of all alert states for all instances of that rulebase on the network. To view all agents that have loaded the rulebase, right click on an icon and select Show Hosts. To view all alert messages generated by a rulebase, right-click on an icon and select Show Alerts. To be maximally useful, Rulebase View requires that rulebases with the same name are indeed copies of the same rulebase. If TIBCO Hawk Display detects multiple instances of a rulebase with the same name that are otherwise different, it creates unique icons for these different rulebases by appending an integer value to the rulebase name.
Working with Display Files 33
Working with Display Files

You can save a customized view of TIBCO Hawk Display and access it the next time you log in. The display layout and contents are saved in a local file with a .hdp extension. If you exit TIBCO Hawk Display after making changes but without saving the display, some custom settings are lost. Preferences are kept, but custom containers, names, hierarchies, and views such as Canvas View are reset. You can also save to file to make a backup copy before making multiple changes. By opening the saved display, you can easily revert to the previous version. Note: Preference settings are saved separately from the display file.
Saving a Display
1. Select File>Save from the TIBCO Hawk Display menu. 2. Navigate to a folder where you want to save the display file. The default location is your TIBCO Hawk directory. 3. Click in the File name field and type a name for the display file. The .hdp extension is automatically appended to this name. 4. Click Save. All custom settings and changes are saved in the file. To reload this version of the display, select File>Open from the TIBCO Hawk Display menu. The display appears as you saved it. The only change is that all icons temporarily change color to show a broken connection until TIBCO Hawk Display can rediscover them. Any new agents not referenced in the file are placed in the Discovered container.
Loading Display Files

To automatically load a display file, specify its name in the display_file parameter for TIBCO Hawk Display. When you start TIBCO Hawk Display, the file is automatically used. To manually load a display file, select File>Open, select your saved display file, and click OK. Any discovered agents not found in the display file are placed in the Discovered container. To create a new default display, select File>New. In the new display instance, agent icons are placed in the Discovered container, organized by default containers specified in the cluster parameter for TIBCO Hawk Display.
34
| Chapter 2
If you use TIBCO Hawk domains, consider using the domain name as the file name. File names act as labels in the TIBCO Hawk Display title bar.
Setting Preferences 35
Setting Preferences
You can set preferences to customize the appearance and behavior of objects in TIBCO Hawk Display. Preferences are stored in a local file named HawkPreference.properties that is created in a .hawk subdirectory in your user home directory. Different users can have different preference settings. To set preferences: 1. Select Edit>Preferences from the TIBCO Hawk Display menu. The Preferences dialog displays:
2. To change the color agent icons display for any level of alert, right-click on the button corresponding to the alert level. The Color Box dialog displays. 3. Click on the square representing the color you want to use for this alert level, or use the HSB or RGB tabs to specify a custom color. 4. Click OK. 5. To be notified with a beep sound when a certain level of alert is received by TIBCO Hawk Display, click one or more checkboxes next to the alert levels. 6. To specify a custom interval for recovering agents, select a value from the dropdown list. The Recovered to OK interval is the number of minutes a node, or TIBCO Hawk agent, stays in Recovery state before its state automatically changes to OK. This interval exists to create a historical perspective on alert messages by
36
| Chapter 2
notifying you that a problem occurred and was resolved. The default value is 30 minutes. To disable this feature, specify a value of 0. 7. Click OK.
Adding a Command to the Tools Menu

The Tools menu in TIBCO Hawk Display is designed to be customized with your commands. Adding a command to the Tools menu allows you to execute scripts or programs, which in turn could execute Java programs, without leaving the TIBCO Hawk Display environment. For example, you can add a command to launch a related management application. The Tools menu provides you with the option of specifying a system or a Java command. You provide a label for the menu item and a complete command-line syntax, including option switches if required. To add a command to the Tools menu: 1. Click the Tools Menu tab in the Preferences dialog. 2. Click Create.
The Tools Menu Item dialog displays:
3. To add a system command: In the Menu Label field, type an identifying label for the command exactly as it should appear in the Tools menu. In the Command field, type syntax for the command. Type it exactly as you would at the command line. External variables can be used when specifying the system command. For more information on using external variables in a rulebase, see Referencing External Variables on page 139. 4. To add a Java command:
In the Menu Label field, type an identifying label for the command exactly as you want it to appear in the Tools menu. In the Java Class field, type the full path name of the Java class. For the Priority field menu, select the priority at which you want to execute the Java application. It is recommended that the priority be set to normal. Setting the priority of the Java application higher than that of TIBCO Hawk Display will degrade the performance of TIBCO Hawk Display. In the Arguments field, specify the arguments, if any, that are passed to the applications 5. Click OK. The command label is added to the Tools menu in TIBCO Hawk Display, and selecting the menu option executes the command. For considerations on executing commands in your TIBCO Hawk environment, see page 197.
38
| Chapter 2
Adding a Command to the Agent Menu

Adding a command to the Agent menu allows you to associate a custom script or executable with all agent icons. Executing the command executes it on the local agent machine. For example, you can use this feature to telnet to a remote host without opening a separate command window. The command you specify is added to the right-click menu for all agent icons. You provide a label for the command and a command to execute, including agent name and IP address parameters. A Host Commands option is added to the TIBCO Hawk Display right-click menu, and the command label displays as an option. You must right-click on an agent icon in Agent View to view Host Commands. Converting Commands from Previous Releases Commands created prior to the current TIBCO Hawk release will automatically be converted when executed using the current release. If an agent command in a previous release has Append Agent Name checked, the variable ${Internal.Agent Name} will be appended to the command. If an agent command in a previous release has Append Agent IP Address checked, the variable ${Internal. Agent IP Address} will be appended to the command. Adding a Command To add a command to the Agent Menu: 1. Click the Agent tab in the Preferences dialog. 2. Click Create. The Agent Menu Item dialog displays:
3. To add a system command: In the Menu Label field, type an identifying label for the command exactly as it should appear in the Agent Commands menu. For example, specify the name of the remote host to contact as the label. In the Command field, type syntax for the command, such as rlogin or telnet. Type it exactly as you would at the command line, but omit any argument that identifies the local agent. 4. To insert an internal or external variable, click Insert and select the variable. Internal variables available in the Agent Menu are: Agent Name Agent OS Agent IP Address Agent Cluster Agent DNS Agent State External variables are obtained from the variable file specified in the -variable option when Hawk Display is started. In Microsoft Windows, they can also can be specified in the configuration applet. For more information on using internal and external variables in a rulebase, see Referencing Variables in a Rulebase on page 139.
40
| Chapter 2
5. To add a Java command, click on the Java radio button. The Agent Menu Item dialog displays:
In the Menu Label field, type an identifying label for the command exactly as you want it to appear in the Tools menu. In the Java Class field, type the full path name of the Java class. For the Priority field menu, select the priority at which you want to execute the Java application. It is recommended that the priority be set to normal. Setting the priority of the Java application higher than that of TIBCO Hawk Display will degrade the performance of TIBCO Hawk Display. In the Arguments field, specify the arguments, if any, that are passed to the applications. To insert an internal or external variable, click Insert and select the variable. 6. Click OK. The command is added to the right-click menu for all agent icons in TIBCO Hawk Display:
For considerations on executing commands in your TIBCO Hawk environment, see page 197.
Specifying the Browser

The Browser menu allows you to specify the web browser that will be used when accessing the URLs contained in alert text messages. If an alert text contains an URL, clicking on the link will launch a web browser. To specify the web browser: 1. Click the Web Browser tab in the Preferences dialog. 2. In the text entry area enter the full path to the web browser of your choice. For example, C:\Program
Files\Netscape\Communicator\Program\netscape.exe
3. Click OK.
42
| Chapter 2
| 43
Chapter 3
Working with TIBCO Hawk Agents
This chapter discusses how a TIBCO Hawk agent uses microagents to gather and receive information. It also shows how to view alert messages generated by an agent.
Topics
Overview, page 44 Viewing Microagents, page 46 Invoking a Microagent Method, page 49 Subscribing to a Microagent Method, page 52 Viewing Alert Messages, page 56
44
| Chapter 3
Overview
To monitor a system or application on the network using TIBCO Hawk software, you install and run a TIBCO Hawk agent on the host machine. The agent is a process that monitors activity on a particular machine by processing loaded rulebases. It communicates with TIBCO Hawk Display using TIBCO Rendezvous messages. Rather than monitoring through one central console, agent activity is distributed across the entire network. Even though an agent communicates with instances of TIBCO Hawk Display, it operates independently of TIBCO Hawk Display and other agents. TIBCO Hawk agents send regular messages that broadcast their identity and active state. The TIBCO Hawk Display application listens for TIBCO Rendezvous messages from agents and maps the agents it has detected. By default, the interval between messages is 30 seconds and the agent name is the same as the machine where it runs. You can configure these and other parameters using agent startup options. For more information, see TIBCO Hawk Installation and Configuration. The agent interfaces the managed objects on its local machine using microagents. Microagents represent managed objects such as operating system subsystems, agent components, log files, event logs or applications. Each microagent exposes a set of methods to the agent that the agent uses to collect information and take action. A set of default microagents is included when you install TIBCO Hawk software. The complete list varies by operating system, but the following standard microagents are installed on all platforms: The Self microagent gathers version information for the local agent, the security policy in effect, and available microagents. It also activates or deactivates the collection of diagnostics for technical support. The Custom microagent executes any command-line executable that can run on the current agent machine. The microagent can also return text or numeric results from the executable. This microagent is typically used to give a TIBCO Hawk agent access to information it cannot obtain from other microagents. It is a useful tool for extending agent capabilities. The Logfile microagent responds asynchronously each time a new line is added to a log file you specify. You can create tests that search for specific strings in a log file line. For information on using the Logfile microagent with rolling log files, see Monitoring Log Files on page 192. The Process microagent counts instances of a process on the agent machine and gathers process usage statistics.
Overview 45
The FileStat microagent gathers information on a disk file or files on the agent machine. The SysInfo microagent gathers basic information on the operating system, hardware architecture, computer name and IP address of the agent machine. The Rendezvous microagent gathers information on TIBCO Rendezvous daemon activity on an agent machine and on TIBCO Rendezvous licensing. The RuleBaseEngine microagent gathers information about the rulebases and takes actions on rulebases that affect the TIBCO Hawk agent.
For detailed information about these microagents with their methods, arguments and results, as well as descriptions of platform-specific microagents, see the TIBCO Hawk Methods Reference. Each agent provides information about its microagents and associated methods, including method names, arguments and return types. This permits dynamic discovery and use of microagents. Method characteristics and behavior are consistent, regardless of how the method is accessed. Microagent methods can be accessed interactively from TIBCO Hawk Display or through rulebases downloaded to the agent. Chapter 4, Monitoring with Rulebases, shows how to use a method as the data source of a rule. You can also access methods programmatically using the Console API. For more information, see the TIBCO Hawk Console API Reference.
46
| Chapter 3
Viewing Microagents
When you start up an instance of TIBCO Hawk Display, it automatically discovers machines running TIBCO Hawk agents on your network. Container icons are created for each agent, and arranged hierarchically in clusters. By default, agent icons are clustered according to subnets. Each agent has a set of default microagents, platform-specific and platform-independent, that are loaded when the agent is started. If you install and start an adapter or gateway, or instrument an application with AMI, microagents for these objects are dynamically added to the agent. In TIBCO Hawk Display, you can view microagents and their methods for any discovered TIBCO Hawk agents. The following example shows how to get a list of microagents for an agent. It also demonstrates how to view information for the getMicroCO Info() method of the Self microagent. To view microagents for an agent: 1. Arrange the TIBCO Hawk Display window so that your agent icon displays in the panel on the right. 2. Right-click on the agent icon and select Get Microagents. The Microagents, Methods and Arguments dialog displays. The panel on the upper left lists microagents you can access on the current agent.
Viewing Microagents 47
If TIBCO Hawk security is implemented on your system and you do not have access to microagents on this agent, an error dialog similar to the following displays:
3. Click Self to display list of methods and a text description in the panels below. The Self microagent represents the TIBCO Hawk agent itself. Its methods generally provide information about the agent. 4. Click the getMicroAgentInfo method. An argument field and detailed help text display in the dialog:
48
| Chapter 3
Methods can return information about a managed object, take an action that modifies the managed object, or both. The getMicroAgentInfo() method returns the names of microagents currently active on this agent. It takes a test string for microagent name as an optional argument, but if no name is specified it returns a list of all microagents for this agent. Invoking this method without arguments returns a list similar to the microagent list in the dialog. For detailed descriptions of default microagent methods, see the TIBCO Hawk Methods Reference. Clicking Refresh retrieves an updated list of microagents from the agent and displays the current list in the Microagents, Methods and Arguments dialog.
Invoking a Microagent Method 49
Invoking a Microagent Method

You can invoke a microagent method in TIBCO Hawk Display and immediately view the results. Invoking is useful when you want to test a method before using it in a rule, or to check a return value for troubleshooting purposes. Microagent methods perform a wide variety of tasks, and are grouped into categories according to the impact that invoking the method has on a managed system. These categories are used by the TIBCO Hawk agent to display appropriate methods for the current context:
IMPACT_INFO
methods collect data.
IMPACT_ACTION methods make some change to the microagent or the resource
it represents.
IMPACT_ACTION_INFO
methods both collect data and make changes.
Microagent methods can be synchronous or asynchronous. Synchronous methods return data when you invoke them. In automated monitoring, a TIBCO Hawk agent invokes synchronous methods on a user-defined interval. You need to subscribe to asynchronous methods, which return data as it becomes available, such as when a new line is written in a log file. The following steps demonstrate how to invoke a microagent method using the getComponentInfo() method of the Self microagent as an example. The instructions in this section begin in the Microagents, Methods and Arguments dialog. To access this dialog, follow the instructions on page 46. To invoke a microagent method: 1. Click the Self microagent. Methods for this microagent display in the panel below.
50
| Chapter 3
2. Click the getComponentInfo method. A detailed help description displays in the lower panel:
This method returns information about TIBCO Hawk product components installed on the current agent. It takes a text string for component name as an optional argument, but if no name is specified it returns a list of all components on this agent. This method is synchronous, so it returns results when invoked. Depending on the method, invoking an asynchronous method may not return any data. In which case, a warning dialog similar to the following is displayed:
For more information on a specific asynchronous method, see the TIBCO Hawk Methods Reference. 3. Verify that the Invoke radio button is selected at the bottom of the window. 4. Click the Invoke button.
Invoking a Microagent Method 51
The Invocation Results dialog displays the results returned by the method:
Methods can return either a single record with one or more fields, or tabular data with one or more columns and rows. This method returns tabular data with each row corresponding to a separate component. To sort tabular results in the dialog, click on a column header. Shift-click to reverse the sort direction. 5. Click Done to close the window.
52
| Chapter 3
Subscribing to a Microagent Method

To view microagent method results over time, you can subscribe to the method in TIBCO Hawk Display and view results as they are returned. Subscribing provides continuous updates of method results and displays a moving window of the result history. Creating a subscription is useful when you want to test a range of return values before specifying boundaries in a rule, or to identify general patterns of activity.
Creating a Subscription
To subscribe to a microagent method: Note: The instructions in this section begin in the Microagents, Methods and Arguments dialog. To access this dialog, follow the instructions on page 46. 1. Click the Process microagent so that methods and a text description display in the panels below. 2. Click the getInstanceCount method. A detailed help description displays in the lower panel:
This method returns the number of process instances of the specified process on the current TIBCO Hawk agent machine. The method is synchronous, so
Subscribing to a Microagent Method 53
you must specify a time interval for collecting data points. The default interval is 60 seconds. 3. Specify a Data Delivery Interval (how often you want to call the method) of 15 seconds. You can select a value from the dropdown list or type the value. Asynchronous methods do not require a Data Delivery Interval. Asynchronous methods continue to send information as it becomes available until the subscription is ended. 4. In the Process Name, type jre*. The getInstanceCount() method the number of processes instances that begin with the string jre. For more information on using regular expressions in microagent methods, see Appendix D, Using Regular Expressions, on page 247. 5. Verify that the Subscribe radio button is selected at the bottom of the window. 6. Click Subscribe. A Subscription Results window displays:
If the subscription is successful, the status bar contains the message Retrieved Data @ with a timestamp. The results of the subscription will appear in the window at regular intervals (if the method you called was synchronous) or as information becomes available (if the method you called was asynchronous). When new results are retrieved, they replace the previous results in the dialog. Over time, the values will fluctuate in all fields except Instance. To create a historical view of subscription results, see the following section, Viewing Subscription Results.
54
| Chapter 3
7. To end the subscription, click Done to close the subscription results window.
Viewing Subscription Results

You can view the result of a method subscription in a chart or a table. These viewing modes are useful for identifying patterns over time. To view a chart of a subscription, follow the steps beginning on page 52 to subscribe to a microagent method. When the first value is received, a button at the bottom of the Subscription Results window is enabled. If the method result contains only text, the label on the button is History. If the method result contains at least one numerical result field, the button label is Chart. If the table of results in the dialog contains more than one row, each row usually describes one instance in a set one storage device, one process, one application. You can view a graph or history for each of these instances in a separate window. To view a graph or history table for a method subscription: 1. Select the row to chart by clicking on it. 2. Click Chart. A blank Subscription Results dialog displays. You can close other TIBCO Hawk windows if you like, and view only the subscription. 3. Click one or more return parameters in the field list. Subscribed data begins to appear in the chart:
Data points are added dynamically, as they are returned by the method. The chart automatically assigns a range to the Y axis based on the values collected; the X axis always represents time. Only values returned after you click Chart are displayed.
Subscribing to a Microagent Method 55
Since the field to chart is a numeric result field, both Chart View and Tabular View tabs are active. If the result contained only text, you would see a table. Note: You can select a different row in the Subscription Results dialog and view the subscription for that instance at the same time. This allows you to compare data between different agents or microagent methods. For example, if you have two versions of an instrumented application (one with a new, faster algorithm and one with an older algorithm), you can compare performance of the versions. All charts are active for as long as the subscription exists. 4. To change how long the chart retains data before it is discarded, select a new value from the Retention Period dropdown list or type your own. The default value is 5 minutes. If you decrease the retention period, data saved before that period will be lost. 5. Click Tabular View to see a historical table of data.
This is the view displayed when no numeric result fields are returned. The table contains the same information as in the Subscription Results dialog for each data retrieval and for the one instance you chose. 6. When you are finished viewing subscription results, click Done.
56
| Chapter 3
Viewing Alert Messages

Alerts are messages an agent sends to TIBCO Hawk Display when a specified condition occurs. Alerts originate from rulebases that enforce your monitoring logic. In TIBCO Hawk Display, the colors of each agent and container icon summarize alert levels, and the Alert Display window shows alert details for a particular agent or all agents. To view alert messages for an agent: 1. Arrange TIBCO Hawk Display so that the agent to view alerts for appears on the right. 2. Right-click on the agent icon and select Show Alerts from the menu. The Alert Display window displays messages for the selected agent:
Drag border to resize column Drag header to move column Click on any column to sort by that column
The severity of the alert. To set colors, edit Display preferences. Whether this alert has been read and cleared. Cleared is a read-only field. When the alert was generated.
The name of the rulebase that generated the alert.
The text message of the alert, specified in the Action Editor.
The Alert Display shows alert and notification messages. When a test with an Alert or Notification action becomes true, TIBCO Hawk Display receives the message unless advanced options delay it. For more information, see Defining Actions on page 80.
Viewing Alert Messages 57
Each line in the Alert Display represents a single message published by a TIBCO Hawk agent. However, a single condition can generate multiple alert messages and other actions, depending on how the rule is designed. For more information, see Defining Actions on page 80. Note: Only one Alert Display window can be active at a time. If you select Show Alerts for another agent, the window updates to show only messages for the current agent. You can filter alerts that have cleared from the Alert Display by clicking the Active Alerts radio button. For more information on how alerts are cleared, see Clearing Alert Messages on page 60. 3. To see detailed information for an alert message, double-click on any field in the alert row:
58
| Chapter 3
If the Alert Text contains a URL, it is shown as a link. Clicking on this section of the Alert Text will launch the web browser to display the web page. For details on specifying a web browser, see Specifying the Browser, page 41. 4. After reviewing the alert message, click Done. Viewing details for an alert message automatically selects the Read checkbox in the Alert Display. You can also manually select or unselect this field. As the Alert Display continuously updates, this feature helps you track alerts that have already been reviewed. When the Alert Display contains unread alerts that have also not cleared, the icon in the upper right animates. To globally mark all alerts in the window, right-click on this icon and select either Mark All as Read or Mark All as Unread.
These steps describe how to view alert messages for a particular agent. For a more global view of alert messages, you can also display alerts for all agents on your network. To view alerts for all hosts, select View>All Alerts from the TIBCO Hawk Display menu.
Suspending Alert Messages

You can temporarily clear an alert message manually, by suspending it, to prevent it from interfering with other monitoring tasks. For example, if a condition such as process failure is generating a high-level alert with a warning bell and the problem is being worked on, you can suspend the alert until the problem is resolved. Suspension details are added to the properties of the message. These details are visible to you and other TIBCO Hawk Display users, as well as all Console API applications. Suspending an alert message affects only the action that generated the alert. If the condition that generates the alert message also generates another type of action, such as attempting to restart the process, that action is unaffected. Note: These instructions begin in the Alert Display window. For instructions on accessing this window, see Viewing Alert Messages on page 56. To suspend an alert: 1. Open the Alert Detail dialog by double-clicking the alert to suspend. 2. Click Suspend Alert.
The Alert Suspend Window dialog displays:
3. Specify a suspension interval by selecting a value from the dropdown list or typing a different value. The default value is 60 minutes. You can change the default by typing a value and clicking Set as Default. 4. Type a reason for suspension to communicate to other users in the Alert Detail dialog. 5. Click OK. The Cleared checkbox for this alert is checked, and the Alert Detail dialog contains the following information about suspension:
Alert Generated Time - 3:51 PM December 8, 1999 Clear Time - 6:05 PM December 8, 1999 Clear Reason - Suspended By - User eastrue on host asture Suspended For - 10000 minute(s) Reason For Suspension - Sysadmin has been paged
You can also use the RulebaseEngine:suspendAlert method to suspend specific alerts. Refer to the TIBCO Hawk Methods Reference for details. Alert suspension is lifted either when the suspension interval ends or when a user invokes the resumeSuspendedAlerts method of the RuleBaseEngine microagent. For instructions on invoking methods, see Invoking a Microagent Method on page 49. For more information on microagent methods, see the TIBCO Hawk Methods Reference. Once suspended, the alert is cleared. Once cleared, it can be purged from the Alert Display, whether or not the problem condition is resolved. If the condition still exists when the suspension interval ends, the agent generates a new alert message for the condition.
60
| Chapter 3
Clearing Alert Messages

Alerts are cleared when the alert condition, as defined by the rulebase, ceases to exist. Alerts generated by tests on synchronous data sources, which deliver data at fixed intervals, are cleared by default at the first test repetition when the condition no longer holds. Alerts generated by tests on asynchronous data sources, which deliver data when it becomes available, are cleared by default when the test does not evaluate to true for 15 minutes. You can modify this default behavior using advanced test and action properties in the rule. For more information, see Using Advanced Test Features on page 78 and Using Advanced Action Features on page 84. When you create an action that creates an alert, you may find it useful to include text that describes how the alert is cleared. For example, if an alert is raised when free disk space falls below 10% and is cleared only when disk space is above 15%, the alert text could be: "Free disk space is 11.6%; this alert will be cleared when the free disk space exceeds 15%. " Active alerts are kept until cleared, and cleared alerts are purged by TIBCO Hawk Display when a buffer limit is reached. To view purged alerts, you can examine Event Service data files, where all alerts are written as they are raised and cleared. For more information on the TIBCO Hawk Event Service, see Using the TIBCO Hawk Event Service on page 111.
Viewing Console Warning Messages

Items such as such as dissimilar rulebase duplications, rulebase application errors and agent discovery errors are displayed in the Console Warning Window. When TIBCO Hawk Display generates or receives these messages, the Console Warning Messages icon starts animating. Clicking on this icon will stop the animation and
bring the Console Warning Messages window to the foreground. If the Console Warning Messages window is already up and if TIBCO Hawk Display generates a warning or an error message, the window will simply be bought to the foreground. The following figure shows the Console Warning Messages window:
62
| Chapter 3
| 63
Chapter 4
Monitoring with Rulebases
This chapter introduces the concept of a rulebase, a configuration object that allows the TIBCO Hawk agent to manage systems and applications on the network. It contains simple examples that demonstrate the steps for creating rulebases and the rules that contain monitoring logic.
Topics
Overview, page 64 Creating a Rulebase, page 66 Building a Rule, page 68 Defining Tests, page 71 Defining Actions, page 80 Saving a Rulebase, page 88 Working with Rulebase Files, page 89
64
| Chapter 4
Overview
A TIBCO Hawk agent monitors managed objects by processing rulebases, which are named collections of rules that contain management logic. For general monitoring tasks, several default rulebases are installed with TIBCO Hawk software. Using TIBCO Hawk Display, you can create additional rulebases with specialized rules. A rulebase can be loaded on a single agent, on a group of agents, or on every agent in the network. Rules monitor parameters of an operating system, application or other managed object and perform tasks. To simplify administration, rules in a rulebase should be related. Multiple rules in the same rulebase can monitor a particular application or system function. For example, an application rulebase could include one rule for issuing a medium-level alert if disk space or CPU usage exceeds certain thresholds. Another rule could issue a high-level alert and send a pager message to the system administrator if the application process terminates. Rulebases and associated objects have a hierarchical structure. Every rulebase contains rules which are made up of data sources, tests, and actions. The following diagram illustrates the relationships between objects in a rulebase. Figure 2 Relationship Between Objects in a Rulebase
Rulebase
ur ce
Rule Rule Rule Rule
D a at So
Test
Yes
Test Rule Yes Rule Rule Rule Action Action
Action Action Action
Overview 65
Default Installation Directory

The HawkAgent-UNIX.hrb rulebase has a rule that monitors the Hawk.log file. The directory path of Hawk.log is hard-coded to the default install directory, /usr/tibco/hawk. If TIBCO Hawk is installed in a directory other than the default, this rule will fail and send out high alerts for noDataSourceErrors. If TIBCO Hawk is installed in a directory other than the default, you must edit the rule to use the actual directory path of the Hawk.log file.
66
| Chapter 4
Creating a Rulebase
You create rulebases using TIBCO Hawk Display. After creating the rulebase you can save it to a file or distribute it to agents on the network. For more information, see Removing a Rulebase on page 92. To create a new rulebase: 1. In TIBCO Hawk Display, right-click on the agent icon where you want to create the rulebase, and select Get Configuration>Rulebases from the menu.
The Rulebase List For Agent dialog displays. This dialog lists rulebases loaded by the selected agent and provides options for performing rulebase operations:
Opens the selected rulebase for editing Creates a new rulebase Copies the selected rulebase and opens the copy for editing Removes the selected rulebase from the current agent Saves changes on the current agent Sends the selected rulebase to one or more agents or Repositories in a container
2. Click Create.
Creating a Rulebase 67
The Rulebase Editor displays:
3. Type Sample in the Rulebase Name field. The rulebase name must be unique on the agent. 4. Click Create on the toolbar to begin the rule building process. The Rule Editor dialog displays. The Rulebase Editor toolbar can be accessed from all dialogs you access while working with rules. Buttons on the toolbar have the following functions:
Creates a new object and Moves the selected object up or down Copies the selected opens it for editing. The object and opens the in the list of objects. For tests and actions, object type depends on copy for editing. objects higher in the list are processed first. the active dialog. Opens the selected Deletes the selected object. object for editing.
A rulebase must have at least one rule, a rule must have at least one test, and a test must have at least one action. The following section, Building a Rule, contains instructions for specifying a data source, and defining tests and actions in a rule. Rulebase names may contain only numeric digits, underscore ( _ ), hyphen ( - ), or a letter as defined by the UNICODE 2.0 standard. The latest version of the UNICODE specification can be found at www.unicode.org/ucd.
68
| Chapter 4
Building a Rule
Most monitoring tasks consist of periodic checking for some problem condition. When the problem is detected, an alarm is sent or corrective actions are taken. If the application goes down, for example, capture some diagnostics and execute a startup script. If too much disk space is consumed, delete some temporary files. If duplicate processes are running, terminate the most recent one. When you create a rule, you specify this monitoring logic and package it for a TIBCO Hawk agent. The agent can apply the rule again and again without intervention. If a problem occurs, the agent can solve it by taking corrective action, or notify you that the problem requires attention, or both, depending on rule design. Rules consist of data sources, tests, and actions. Data sources are microagent methods that periodically collect or asynchronously return information to an agent. One or more tests are applied to the resulting data set. When a particular test evaluates to true, one or more actions can be triggered. Figure 3 Flow of Rules and Tests
action
data source
test
action
action
Although a rule uses a single data source as input, you can use a posted condition to indirectly use multiple data sources in a test. For more information, see Using Posted Conditions on page 146. These instructions begin in the Rule Editor dialog. To access this dialog, follow the steps beginning on page 66. To create a new rule on an agent, click Edit next to the Data Source field.
Building a Rule 69
The Microagents, Methods and Arguments dialog displays:
This dialog contains a list of microagents you can use as a data source for the rule. TIBCO Hawk default microagents are listed, along with microagents for AMI adapters, gateways and instrumented applications. The Export MAD... button allows you to save the microagent descriptor in its XML representation. For more information on exporting and importing microagent descriptors using their XML representation, please refer to TIBCO Hawk Configuration Object API Reference.
Specifying a Data Source

The data source for a rule is its source of input data, and is always a method of a microagent. When a rule is active, the TIBCO Hawk agent subscribes to the specified method and passes method results to the test. The following example uses the Process microagent as a representative data source. To define the data source of a rule: 1. Click the Process microagent. Methods for the microagent display in the panel below. 2. Click the getProcess method. Fields for method arguments and a data delivery interval display on the right side of the dialog. A detailed text description of the method, including arguments and return values, displays in the lower panel.
70
| Chapter 4
3. In the Process Name field, type rvd.*.
When invoked, the getProcess() method returns information about all running processes. It takes the name of a specific process as an optional argument and with no argument specified, the entire process table is returned. In this case, the method returns all process instances that begin with the string rvd. For more information on using regular expressions in microagent methods, see Appendix D, Using Regular Expressions, on page 247. This is a synchronous method. When the rule is active, the agent subscribes to this method and receives data every 60 seconds, by default. For asynchronous methods, such as Logfile:onNewLine(), no collection interval is required. You can reference both external and internal variables within data source arguments. These must be typed in manually using the correct format, for example, ${Internal.Agent Name} or ${External.HAWK_ROOT}. For more information on referencing external and internal variables, see page 139. 4. Click OK. The rule is now configured to use the getProcess() method of the Process microagent as a data source. The Rule Editor dialog displays getProcess(Name=rvd.*):60 in the Data Source field.
Defining Tests 71
Defining Tests
The data source of a rule provides information about some condition on a managed node. After information is received, one or more tests are applied to evaluate it. Each sample of data from the data source is distributed to all tests in the rule. Each test uses the data to compute a true or false value which is used in determining when to trigger actions. A test is true only when the entire test evaluates to true, not just the test expression. Evaluation intervals for a test depend on the type of data source used by the rule. Synchronous data sources return results to the agent at regularly scheduled intervals, where an asynchronous data source transmits data whenever it becomes available. Test transitions, or changes between values of successive tests, can be one of four types: false to true, true to true, true to false, and false to false. By default, tests on synchronous data sources become true whenever the test expression is true, then become false the first time the test is false. Tests on asynchronous data sources, however, become false by default only after 15 minutes have passed since the last true evaluation.
Creating a New Test

To create a new test in the current rule:
72
| Chapter 4
1. In the Rule Editor dialog, click Create on the toolbar. The Test Editor dialog displays:
The If field is for the test expression, which you create in the Test Builder dialog. You access this dialog by clicking Edit. The Then field is for one or more actions to perform if the test evaluates to true, which you specify in the Action Editor dialog. You access this dialog using toolbar buttons in the Test Editor dialog. 2. Click Edit next to the If field. The Test Builder dialog displays:
A test consists of a test expression and other parameters that determine how and when the test is applied. Tests created in the Test Builder dialog have the following form:
If
<expression is true> then <perform actions>
Defining Tests 73
The first set of angle brackets contains the test expression. It consists of a parameter, a return value of the microagent method used as a data source, and a test operator, such as >=. Test operators you can use in an expression depend on the type of value returned by the microagent method. Numeric, string and Boolean values can all be used as input in a test expression.
Building a Test Expression

The following procedure shows how to build a test expression by specifying a test parameter and test operator in the Test Builder dialog. This example uses the MemUsage microagent method result field and a numeric operator. 1. Click Mem KBytes.)
Usage
to use as the test parameter. (On UNIX, use Virtual
Mem Usage
is one of 10 result fields returned by the getProcess() method, the data source for this rule. The text area in the Microagents, Methods and Arguments dialog displays a short description of each parameter. In the description for this method, you can see that Process Name is a string value, and Mem Usage is an integer.
2. Click the > operator. Only operators that apply to the current parameter are included in the list. Mem Usage is an integer field, so numeric operators are listed. All test operators are described on the following pages. 3. Click in the Greater
than
field and type the number 1000.
4. Click OK to save the test expression. This test now checks for instances of the process rvd using more than 1000 Kilobytes, or 1 MB, of memory when the test is evaluated. If all instances found are using less than 1 MB of memory, no problem condition exists and the test is false. Since getProcess is a synchronous method, the agent evaluates the test every 60 seconds by default. The following tables describe the test operators you can apply to numeric, text and Boolean parameters. Table 2 Test Operators For Numeric Method Results Operator
== ! =
Description
The test expression is true when the value of the test parameter is (equal to, not equal to) the operator value.
At the first test evaluation or during a network query, the Increase, %Increase, Decrease, %Decrease, NetChange, and %NetChange values are zero, since only one data sample is involved.
74
| Chapter 4
Table 2 Test Operators For Numeric Method Results (Contd) Operator

< <= > >= inRange
Description
The test expression is true when the value of the test parameter is (less than, less than or equal to, greater than, greater than or equal to) the operator value.
The test expression is true when the value of the test parameter is between two extremes of a range. Endpoints are included. The test expression is true when the value of the test parameter is outside the range of two operator values. Endpoints are excluded. The test expression is true when the value of the test parameter has increased at least by the operator value between two successive test evaluations. For example, the amount of disk space in use has increased by more than 10 MB in a sample period. The test expression is true when the value of the test parameter increases by at least the operator value as a percentage (the increase divided by the previous value times 100) between two successive test evaluations. For example, the amount of disk space in use has increased by more than 10 percent in a sample period. The test expression is true when the value of the test parameter decreases by at least the operator value between two successive tests. The test expression is true when the value of the test parameter decreases by at least the operator value as a percentage (the decrease divided by the previous value times 100) between two successive test evaluations. The test expression is true when the value of the test parameter increases or decreases by at least the operator value between two successive test evaluations. The operator value specifies the absolute value of the increase or decrease.
outOfRange
Increase
%Increase
Decrease
%Decrease
NetChange
Defining Tests 75
Table 2 Test Operators For Numeric Method Results (Contd) Operator

%NetChange
Description
The test expression is true when the value of the test parameter increases or decreases by at least the operator value as a percentage (the increase or decrease divided by the previous value times 100) between two successive test evaluations. The operator value specifies the absolute value of the percentage increase or decrease. The test expression is true when the specified posted condition exists. This operator displays when a posted condition is selected in the parameter list. PostedConditionExists is equivalent to ${Posted.x} > 0. For more information, see Using Posted Conditions on page 146
postedConditionExi sts
!postedConditionEx ists
The test expression is true when the specified posted condition does not exist. This operator displays when a posted condition is selected in the parameter list. !PostedConditionExists is equivalent to ${Posted.x} == 0 when x is the posted condition name. For more information, see Using Posted Conditions on page 146.
Table 3 Test Operators for Text String Results Operator Equals Description The test expression is true when the value of the test parameter exactly matches the operator value. This is a case-sensitive match. The test expression is true when the value of the test parameter does not exactly match the operator value. This is a case-sensitive match. The test expression is true when the value of the test parameter starts with the operator value. This is a case-sensitive match.
!Equals
StartsWith
76
| Chapter 4
Table 3 Test Operators for Text String Results (Contd) Operator Contains Description The test expression is true when the value of the test parameter contains the operator value. This is a case-sensitive match. The test expression is true when the value of the test parameter does not contain the operator value. This is a case-sensitive match. The test expression is true when a match is found using a regular expression as an operator value. For more information on regular expressions, see Appendix D, Using Regular Expressions, on page 247.
!Contains
Perl5 PatternMatch
Table 4 Test Operators for Boolean Results Operator isTrue isFalse Description The test expression is true when the value of the test parameter is true. The test expression is true when the value of the test parameter is false.
Building Compound Tests

A compound test uses the same operators as a simple test, but allows you to combine multiple expressions using the logical operators AND, NOT, and OR. You can group expressions and insert operators in the compound test editor. The following procedure shows how to build a compound test expression by modifying a simple expression. This example adds a second condition, using the Command microagent method result field and a text string operator, to the sample test expression on page 73. Both conditions in the new test expression must be satisfied for the test to evaluate to true. To build a compound test: 1. In the Test Editor dialog, click Compound. The dialog extends to display a compound test editor. The current text expression is highlighted in the Test Expression field, for example:
If (Command Contains rvd -listen tcp:7474)
This test checks for rvd processes started with specific command options.
Defining Tests 77
2. Click AND to group the highlighted expression and add the AND operator. The compound test editor automatically adds the correct number of parentheses to the expression:
3. In the lower half of the dialog, click the Mem Usage parameter and the > operator. 4. In the Greater than field, type 1000. 5. Click Apply to insert the expression into the highlighted set of parentheses. The compound test now looks like the following:
((Command Contains rvd -listen tcp:7474) AND (Mem Usage > 1000))
This test evaluates to true when the specified rvd process uses more than 1000 Kilobytes, or 1 MB of memory. If the memory threshold is exceeded, the test could trigger an action for restarting the process and notifying the system administrator. For more information, see Defining Actions on page 80. Processes named rvd that were started using different parameters, such as -listen tcp:7475 are unaffected. For more information on uniquely identifying processes, see Identifying Same-Named Processes on page 184. 6. Click OK to save the test, or Undo to cancel the last change.
78
| Chapter 4
Using Advanced Test Features

A test includes the test expression (such as Processes > 10) and any extra conditions, such as counters, timers and additional tests. These advanced options add extra requirements for a test to evaluate as true or false. Note: These instructions begin in the Test Editor dialog. For instructions on accessing this dialog, see Defining Tests on page 71. To access advanced test options: 1. Click Advanced. The Advanced Test Editor dialog displays:
2. To specify a true test counter, type the number of true evaluations in the True Test Counter field. The default value is 1. With a true test counter, the action is triggered only after the test expression has been true for the specified number of test evaluations. For example, to check for consistently high CPU usage and ignore any brief spikes, you could set the true test counter for the test to five. The action is triggered when the test expression (CPU use high) is true for five consecutive test evaluations. 3. To specify a clear condition, click the First False, Clear Timer or Clear Test radio button.
Defining Tests 79
With First False, after the test becomes true, the first time the test expression is false the entire test becomes false. This is the default behavior for a test with a synchronous data source. For Clear Timer, type a wait interval in seconds. After the test becomes true it remains true until this interval has passed without an additional true test. This is the default behavior for a test with an asynchronous data source, and the default wait interval is 900 seconds (15 minutes). For Clear Test, click Edit to specify an extra test expression for clearing the test. After the test becomes true, it becomes false only when the clear test expression becomes true. The clear test uses the microagent method result fields of the data source as input. For example, a test monitors each line in a log file for the string Feed Line Down. If this string is found, an alert is generated. A clear test for the original test checks for a log file line that signals the condition is resolved, such as Feed Line Up. When the clear test evaluates to true, the original alert message is cleared. 4. Click Use schedule to select the name of an existing schedule to apply to this test. By default, the test is always active. Schedules can also be applied to rulebases, rules and actions. For more information, see Working with Schedules and Period Groups on page 148. 5. To specify a clear action, click Create on the toolbar. The Clear Action Editor displays. A clear action is an action that takes place only when a test makes the transition from true to false. After the test becomes true, whenever it becomes false again one or more actions are performed. Clear actions behave like regular actions but do not support advanced options except schedules, and cannot generate alerts. They are useful for sending notifications or all-clear messages. A clear action can reference the same data source variables as the associated test. For more information, see Referencing Data Source Variables on page 141. For instructions on using this dialog, see Defining Actions on page 80. Note: A clear action generated from a test cleared by using clear timer will not have data source parameter variables available to the clear action, since it is a timer and not a data source evaluation creating the clear event. 6. Click a radio button for action type, specify action parameters, then click OK. The clear action is added to the test and its syntax displays in the Advanced Test Editor.
80
| Chapter 4
Defining Actions
Each test has one or more related actions. An action is the consequence of a rule, such as an alert message or a custom script. Whenever the rule receives information from its data source, tests are evaluated. If a test evaluates to true, the related actions are triggered. Once triggered, actions are performed unless advanced options delay or prevent the action. Creating an Alert Message with Variable Substitution The following example shows how to create an alert message with variable substitution as a representative action. These instructions begin in the Test Editor dialog. For instructions on accessing this dialog, see Defining Tests on page 71. To define an action: 1. Click Create on the toolbar. The Action Editor displays:
Defining Actions 81
2. Select an action type from the radio buttons across the top of the dialog. These buttons correspond to the following TIBCO Hawk action types: Table 5 Action Types in the Action Editor Action Type
Alert (default)
Result
Sends an alert message to TIBCO Hawk Display
Usage Notes
In the Message field, type the alert text you want to appear in the Alert Display. You can specify a URL in the Message field. Clicking on the URL will launch a web browser. Specify an alert level: high (default), medium or low.
Execute
Executes a command on the TIBCO Hawk agent machine
In the Execute field, type the entire command line to send to the operating system of the agent machine. For more information on executing commands, see Monitoring with Custom Scripts on page 196.
Notification
Sends a notification message to TIBCO Hawk Display
In the Message field, type the notification text that you want to appear in the TIBCO Hawk Display messages window. You can specify a URL in the Message field. Clicking on the URL will launch a web browser.
Method
Invokes a microagent method on the TIBCO Hawk agent machine
Click Edit next to the Method Invocation field. The microagents window displays methods that take action. Select a microagent and method, specifying any required arguments, then click OK. A text description of the method and arguments display in the Method Invocation field. Specify a message recipient as
Email
Sends an email message.
recipient@domain.com. Specify a subject string,

an SMTP mail server for sending the message, and message text.
Post Condition
Creates a posted condition to use in another rule in the same rulebase
In the Name field, type a label for the posted condition. For more information, see Using Posted Conditions on page 146.
82
| Chapter 4
3. In the Message field, type the following:

Process ${Process Name} is using ${Mem Usage} KBytes
4. You can insert an internal variable, an external variable, or a data source.
Substituting variables in string fields is supported for all action types except Post Condition. For more information on using variables in a rulebase, see Referencing Variables in a Rulebase on page 139. To insert an internal variable, right-click on Insert and select Internal Variable from the menu. Internal variables available in the Agent Menu are: Agent Name Current Test Current RuleBase Current Action Current Rule Condition True Time
To insert an external variable, right-click on Insert and select External Variable from the menu. ${External.<var name>} is inserted in the active string field. Replace <var name> in the syntax string with the name of the external variable defined in the properties file. External variables are obtained from the variable file specified in the option for the rulebase engine (suboption of -M RuleBaseEngine) when the agent is started.
-variable
To insert a data source variable in a string argument, select a variable name from the menu.
Defining Actions 83
Variable syntax is added to the string field at the cursor location. The syntax does not require modification. You can also manually type the syntax ${<return-field-name>} in the string field for an action, where return-field-name is the label for a value returned by the method. The microagent method that returns this field must be the data source for the current rule. You can get more information for specific method return fields by viewing descriptive help text for the method in the Microagents, Methods and Arguments dialog. For instructions on accessing this dialog, see Specifying a Data Source on page 69. 5. Click OK.
84
| Chapter 4
Using Advanced Action Features

Advanced action options add flexibility in timing when an action is performed. For example, using advanced options you can automate problem escalation procedures. To use advanced action features: 1. Click Advanced in the Action Editor dialog. The Advanced Action Editor dialog displays:
2. To specify how actions are performed, click the Once Only, Always, or Maximum Of radio buttons. With Once Only , the first time this action is triggered by a test, the action is performed. On subsequent true evaluations the action is not performed.
Defining Actions 85
The action is not performed again until the test becomes false and then true again. This is the default behavior for all actions. When the associated action creates an alert message, this option helps prevent repetitive and persistent alerts. Substituting variables in alert messages overrules this feature. For more information, see How Variable Substitution Affects Actions on page 141. With Always, the action is performed each time the associated test is evaluated as true, even if the test was true in the last evaluation. You can use this option to provide incremental relief for a condition. For example, if the test condition is a low level of free disk space, the action could execute a script that finds the oldest diagnostic file on the disk and deletes it. Instead of globally deleting all diagnostic files at once, this action can be triggered only when needed. For Maximum of, specify the maximum number of times the action can be performed, no matter how long the associated test continues to remain true. If the test becomes false, the counter is reset. Specify the number of seconds to wait between actions as long as the test is true. The related action can only be triggered at a test evaluation, so the actual interval between actions may be longer than the specified interval. This option is useful when the action executes a paging script. A single page might be lost, but paging at each test evaluation (such as once per minute) is too often. With this option you can send the page every five minutes until it is likely to be received. 3. To escalate a problem, type a wait interval in seconds in the Escalation Period field. The action is not performed the first time the associated test is true, but instead starts an internal timer. When the action is triggered on a test transition from false to true, the timer is started. If the associated test remains true for another evaluation after the specified interval, then the action is performed. You can use an escalation period to respond to continuing or deteriorating conditions. For example, you often run a regular job called Chron Job that takes thirty minutes to complete. To monitor stages of job progress, you could build a test that checks the number of instances of the Chron Job process. If this number
86
| Chapter 4
is equal to one, the test evaluates to true. The test could have a sequence of actions: Action A, with no escalation period, sends the notification "Chron running."
Job
is
Action B, with a 30 minute escalation period, sends the notification "Chron Job should be finishing now." Action C, with a 35 minute escalation period, sends the alert "Chron needs to be checked".
Job
Action D, with a 40 minute escalation period, sends E-mail to the systems administrator with the message "There is a problem with Chron Job". Further escalations could attempt to terminate the job if critical resources are consumed, then notify the system administrator. Actions A through D are all triggered the first time the test is true. However, all but Action A wait until the test is still true when the escalation period is up. In this case, you might add a clear action to the test, notifying an operator that the job Chron Job has finished or been terminated. Since an action is performed only after results from a test evaluation are received (even if the consequence is deferred), an action might not be performed immediately after a test condition becomes true. The delay can be as large as the data source collection interval plus any escalation period. For example, if an action has an escalation period of five minutes but the test is only evaluated every two minutes, it may be from five to seven minutes before the action is performed. 4. To apply a schedule to this action, click Use Schedule and select the name of an existing schedule from the dropdown list. By default, the action is always active. Schedules can also be applied to rulebases, rules and tests. For information, see Working with Schedules and Period Groups on page 148 and Creating Schedules on page 149. 5. To add properties to the rulebase actions, click the Add button in the Properties area. A new table row appears. Normally, when an action is executed, internal properties (such as Rule, DataSource, Test, and so on) are assigned to the action. You can define additional properties for an action here. If an action causes an alert to be generated, these properties (internal and user-defined) are passed to the PostAlertEvent. For user-defined properties in the action, the properties are pre-appended with "Action" in the key. These properties can also be viewed from the Alert Detail Window.
Defining Actions 87
6. You can add properties to rulebase actions in the following ways: Type in the key and value. The key and value must be strings. You can modify, copy and delete keys and values that you have added. For example, all TIBCO BusinessWorks actions in a rulebase require two properties: one named Deployment with the deployment name, and another named ComponentInstance with the name of the component being deployed (should match the name of the component in BusinessWorks Designer). Load a previously-defined template by clicking Template and selecting Load, then select the file to be loaded. 7. If you want to save your new action properties as a template, click Template and select Save, then specify where the file should be created and enter a file name. The template is saved as an XML file, and the extension .xml is added to the filename if not specified. The template can be loaded later. You can also configure a saved template as the default template by clicking Set Default from the Template menu and selecting the appropriate template. When a default template is set, the properties from the default template are loaded to the Advanced Action Editor when an action is being edited. If a property from the default template exists in the current action, the property from the default template is ignored. The default template is on a per-user basis; like the Preferences of the Display, it depends on where the Display is running. For existing rulebases, even if a default template is set, the actions in the rulebase are NOT updated with properties from the default template unless the action is edited using the Advanced Action Editor. 8. Click OK in the Advanced Action Editor, Action Editor, Test Editor, and Rule Editor dialogs. 9. In the Rulebase Editor dialog, click OK. The new rulebase is added to the list of rulebases in the Rulebase List for Agent dialog. For instructions on saving the rulebase, see Saving a Rulebase on page 88.
88
| Chapter 4
Saving a Rulebase
Once the creation of the rulebase is complete, there are several options for you to consider. The option you choose depend on the agent configuration mode. For descriptions of each configuration mode, see Chapter 5, Managing Your Configuration. Send the rulebase back to the agent (Apply Changes). The agent will immediately start performing the monitoring tasks defined in the rulebase. Agents running in Automatic Configuration mode will also store the rulebase in their auto-configuration directory for automatic loading upon startup. Agents running in Manual Configuration mode will not store the rulebase anywhere, and will only perform the monitoring tasks defined in the rulebase for the life of the currently running process.. Send the rulebase to a set of agents (Send To). The set of agents will immediately start performing the monitoring tasks defined in the rulebase. Agents running in Automatic Configuration mode will also store the rulebase in their auto-configuration directory for automatic loading upon startup. Agents running in Manual Configuration mode will not store the rulebase anywhere, and will only perform the monitoring tasks defined in the rulebase for the life of the currently running process. Save the rulebase to a file (Save to File). You can save the rulebase to a file for later distribution to the agents. In Manual Configuration mode with the Configuration Path option, saving to a file is useful for creating a permanent copy of the rulebase. For more information, see Working with Rulebase Files on page 89. In Manual Configuration mode with the Repository option, sending the rulebase to a Repository creates a permanent copy of the rulebase. For more information on Repositories, see Using the Repository Option on page 101. To load the new rulebase at startup, add its name to agent configuration parameters or the rulebase map. For more information, see Using a Rulebase Map on page 122.
Working with Rulebase Files 89
Working with Rulebase Files

When a TIBCO Hawk agent uses a rulebase in memory, the rulebase object consists of a hierarchy of linked objects describing rules and their data sources, tests and actions. Rulebase information can also be stored in a disk file with a .hrb extension. When you save a rulebase file, this information is encoded into text. Results of working with rulebase files depend on the agent configuration mode. For more information, see Chapter 5, Managing Your Configuration.
Saving a Rulebase to a File

You can save a rulebase in a disk file. Rulebase files are useful for backing up rulebases before making changes or storing rulebases before distributing them. For more information, see Sending a Rulebase to Agents on page 93. To save a rulebase to a file: 1. In TIBCO Hawk Display, right-click on the agent with the rulebase and select Get Configuration>Rulebases from the menu. The Rulebase List for Agent dialog displays:
2. Click the rulebase name, then select File>Save To File. The Save Rulebase dialog displays.
90
| Chapter 4
3. Browse to a directory for the rulebase file, then click OK. Do not modify the file name. The rulebase file with a .hrb extension is saved in the specified directory on the TIBCO Hawk Display machine. The file must have the same name as the rulebase.
Loading a Rulebase from a File

You can manually load a rulebase that has been saved to file. To load a rulebase from a file: 1. In TIBCO Hawk Display, right-click on the agent with the rulebase and select Get Configuration>Rulebases from the menu. The Rulebase List for Agent dialog displays. 2. Select File>Load From File. The Open dialog displays. 3. Navigate to the rulebase file and click OK. If a rulebase with this name is not already loaded, it is added to the list. If a rulebase with this name is already loaded on the agent, a dialog displays. Click OK to overwrite the existing rulebase or Cancel to exit the dialog. 4. Click Apply Changes to save the rulebase on the current agent.
The current agent will immediately start performing the monitoring tasks defined in the rulebase. Agents running in Automatic Configuration mode will also store the rulebase in their auto-configuration directory for automatic loading upon startup. Agents running in Manual Configuration mode will not store the rulebase anywhere, and will only perform the monitoring tasks defined in the rulebase for the life of the currently running process. For more information, see Choosing a Configuration Mode on page 98.
Editing a Rulebase
You can modify rules in an existing rulebase on any agent. An agent can load the changes immediately, or the next time it is started. For more information on when changes are loaded, see Sending a Rulebase to Agents on page 93. 1. In TIBCO Hawk Display, right-click on the agent with the rulebase to edit and select Get Configuration>Rulebases from the menu. The Rulebase List for Agent dialog displays. 2. Click the name of the rulebase to modify, then select Edit>Modify or click Modify on the toolbar.
Working with Rulebase Files 91
The Rulebase Editor dialog displays the name of the original rulebase and a list of rules. 3. Double-click the name of a rule to open it for editing. For instructions, see Building a Rule on page 68. 4. When changes are complete, click OK. 5. Click Apply Changes to save the changes on the current agent. The current agent will immediately start performing the monitoring tasks defined in the rulebase. Agents running in Automatic Configuration mode will also store the rulebase in their auto-configuration directory for automatic loading upon startup. Agents running in Manual Configuration mode will not store the rulebase anywhere, and will only perform the monitoring tasks defined in the rulebase for the life of the currently running process. To permanently save the rulebase, it must be saved to a file or sent to a Repository. For more information, see Using the Repository Option on page 101. A rulebase must have the same name as its rulebase file. You can only rename a rulebase or rulebase file using TIBCO Hawk Display.
Copying an Existing Rulebase

If an existing rulebase has some characteristics in common with a rulebase you need to create, you can copy the existing rulebase, edit rules, then save the rulebase with a new name. Copying a rulebase is useful when you use overruling. For more information, see Overruling a Rule on page 143. To copy an existing rulebase: 1. In TIBCO Hawk Display, right-click on the agent with the rulebase to copy and select Get Configuration>Rulebases from the menu. The Rulebase List for Agent dialog displays. 2. Click the name of the rulebase to copy, then select Edit>Derive or click Derive on the toolbar. The Rulebase Editor dialog displays the name of the original rulebase and a list of rules. 3. In the Rulebase Name field, type a name for the new (derived) rulebase. Rulebase names on an agent should be unique. If you send a rulebase to multiple agents after renaming it, duplicate copies of the same rulebase can result. 4. Modify one or more rules, then click OK. For instructions, see Building a Rule on page 68. The new rulebase derived from an existing rulebase displays in the Rulebase List.
92
| Chapter 4
5. Click Apply Changes to save the new rulebase on the current agent machine. The current agent will immediately start performing the monitoring tasks defined in the rulebase. Agents running in Automatic Configuration mode will also store the rulebase in their auto-configuration directory for automatic loading upon startup. Agents running in Manual Configuration mode will not store the rulebase anywhere, and will only perform the monitoring tasks defined in the rulebase for the life of the currently running process. To permanently save the rulebase, it must be saved to a file or sent to a Repository. For more information, see Using the Repository Option on page 101.
Removing a Rulebase
You can remove a rulebase from an agent when the rulebase is no longer needed by selecting the rulebase name and clicking the Delete button on the toolbar. Deleted rulebases cannot be recovered. You should make a backup copy of the files in your configuration source periodically or before and after you make major changes.
Distributing a Rulebase to Agents 93
Distributing a Rulebase to Agents

The previous sections in this chapter show you how to work with a rulebase on one TIBCO Hawk agent, then apply the changes to the local agent. In a distributed monitoring system, other independent TIBCO Hawk agents need copies of the rulebase in order to make decisions. You can use TIBCO Hawk Display to distribute rulebases and rulebase changes in the following ways: Send a rulebase from one agent to many. Sending rulebases across the network lets you install copies of rulebases you intend to use and update distributed rulebases with changes made (and tested) on one machine. Send rulebase changes over your network to a single agent, all agents in a container, or all agents in the network. Remove rulebases from any agent, or from all agents in a container.
Make sure rulebase names in your network are unique. If names are not unique and you send a rulebase across the network, you could replace a different rulebase with the same name. As a general rule, rulebases with the same name should contain identical information, even if they are loaded on different machines. Results of distributing rulebase files depend on the agent configuration mode. For more information, see Chapter 5, Managing Your Configuration.
Sending a Rulebase to Agents

To distribute a rulebase to other agents on your network, you send it to one or more agents. Sending a new or existing rulebase to an agent directs the agent to immediately load the rulebase. To send a rulebase to one or more agents on the network: 1. In TIBCO Hawk Display, right-click on the agent with the rulebase to send and select Get Configuration>RuleBases from the menu. The Rulebase List for Agent dialog displays. 2. Click the rulebase to send to other agents, then click Send Selected To. You can send one rulebase at a time. The Distribute Rulebase To dialog displays. You can also send a rulebase to a Repository, if one exists on your network. For more information, see Sending a Rulebase to a Repository on page 104.
94
| Chapter 4
3. Click an agent to send the rulebase to. To select multiple agents, use the Control or Shift keys. To send a rulebase to every agent on the network, click the Agents container. Warning: If an existing rulebase with the same name exists on the destination agent, it is immediately overwritten with the new rulebase. 4. Click OK. If you selected a single agent, a status dialog displays. If you selected a container, a dialog prompts you to send the rulebase to all agents in the container or only to agents that already have the rulebase. Click All Nodes if you are sending new rulebases, or Update if the rulebases already exist. In Automatic Configuration mode, the sent rulebase is saved both in memory and in a file in the auto-configuration directory on the local machine. In Manual Configuration mode, the sent rulebase is saved in memory only, and the new or modified rulebase is discarded when the agent shuts down. To permanently update rulebase files, manually copy the files to each agent machine or use a Repository. To direct an agent to load the rulebase at startup, modify configuration parameters or add it to the rulebase map. For more information, see Using the Repository Option on page 101.
Removing a Rulebase from Agents

When a rulebase is no longer useful, you can delete it from one or more agents on the network. Modifying an existing rulebase and distributing the new version overwrites the older version of that rulebase, so deleting a rulebase is not necessary to update it. To remove a rulebase from other agents on the network: 1. In TIBCO Hawk Display, right-click on the agent with the rulebase to delete and select Get Configuration>Rulebases from the menu. The Rulebase List for Agent dialog displays. 2. Select the rulebase to delete, then click Delete Selected Rulebase From. The Delete Rulebase From dialog displays. You can also remove a rulebase from a Repository, if one exists on your network. For more information, see Removing a Rulebase from a Repository on page 106. 3. Click the agent to remove the rulebase from. Use the Shift and Control keys to select multiple agents. 4. Click OK.
Distributing a Rulebase to Agents 95
If you select a container that includes the current agent, the rulebase is immediately deleted. If you select all agents in a container, a dialog prompts you to confirm the delete operation. Click OK to delete or Cancel to stop. In Automatic Configuration mode, the rulebase is deleted from memory for each agent, and the rulebase file with the same name is deleted from the auto-configuration directory for each agent. The deletion is permanent. In Manual Configuration mode, the rulebase is deleted only from memory on each agent. To prevent agents from reloading the rulebase at startup, modify configuration parameters or the rulebase map. For more information, see Using a Rulebase Map on page 122. To permanently delete a rulebase, delete the rulebase file from the agent or Repository. For more information, see Removing a Rulebase from a Repository on page 106.
96
| Chapter 4
| 97
Chapter 5
Managing Your Configuration
This chapter describes TIBCO Hawk configuration modes and how configuration objects such as schedules and rulebases are managed. It also explains how to work with configuration objects in a Repository.
Topics
Choosing a Configuration Mode, page 98 Using Automatic Configuration, page 99 Using Manual Configuration, page 100 Understanding Configuration Scenarios, page 108
98
| Chapter 5
Choosing a Configuration Mode

On your network, configuration objects such as schedules and rulebases are retrieved using either manual or automatic configuration. The mode you choose might depend on the number of TIBCO Hawk agents running on your network, and the number and complexity of configuration objects. With manual configuration, you manually configure which rulebases an agent loads by editing the rulebase map or adding them to the -rulebases configuration parameter. For more information, see Using a Rulebase Map on page 122. At startup, the agent searches one or more directories or Repositories to find the specified configuration object. All changes are temporary, until you decide to make them permanent by saving them to a file or a Repository. For more information, see Using the Repository Option on page 101. With automatic configuration, all changes applied to the agent are permanent. In this mode, you automatically specify rulebases for the agent to load at startup by saving and deleting rulebases from the auto-configuration directory.
You specify a configuration mode and other parameters when starting a TIBCO Hawk agent, and the agent searches the configuration source for configuration objects. A configuration source is one or more directories on the agent machine, or one or more Repository names on the network. This section describes how configuration objects are stored and retrieved. For implementation details on Manual or Automatic Configuration modes, see TIBCO Hawk Installation and Configuration. For method descriptions, see the TIBCO Hawk Methods Reference.
Using Automatic Configuration 99
Using Automatic Configuration

Automatic Configuration is the default mode for storing configuration objects. In Automatic Configuration mode, the configuration source is a single directory specified in the -auto_config_dir startup option. The agent locates the automatic configuration directory at startup and loads schedules first, then rulebases. Since all rulebases found are loaded, a rulebase map is not used in Automatic Configuration mode. After an agent is started, in this mode you can load additional rulebases by sending them in TIBCO Hawk Display, or by invoking the RuleBaseEngine:loadRuleBaseFromFile() method. For more information on distributing rulebases, see Sending a Rulebase to Agents on page 93. For more information on specific methods, see the TIBCO Hawk Methods Reference.
100
| Chapter 5
Using Manual Configuration

In Manual Configuration mode, the configuration source is one of the following: One or more directories specified in the config_path parameter One or more Repositories specified in the repository_path parameter
These two options are mutually exclusive. If no path is specified, the current directory is used by default. In Manual Configuration mode, the agent performs the following sequence of tasks to load startup rulebases: 1. At startup, the agent searches the configuration source for schedules, then for a rulebase map. For more information, see Using a Rulebase Map on page 122. 2. The agent searches the configuration source and loads all rulebases specified in the rulebase map. 3. The agent searches the configuration source for any additional rulebases specified in the rulebases command line option and loads them. For more information, see TIBCO Hawk Installation and Configuration. 4. If these rulebases have Include lists of other rulebases, the agent searches the configuration source for included rulebases and loads them. For more information, see Including a Rulebase on page 134. After an agent is started in Manual Configuration mode, you can load additional rulebases by sending them in TIBCO Hawk Display, or by invoking the RuleBaseEngine: loadRuleBase() or RuleBaseEngine:loadRuleBaseFromFile() methods. For more information on RuleBaseEngine() methods, see the TIBCO Hawk Methods Reference. If a rulebase loaded using one of these procedures has an Include list, included rulebases are also loaded.
Using the Configuration Path Option

With the Configuration Path option, the configuration source is one or more directories specified in -config_path. With this option, any rulebases loaded by the agent are not written out to a local cache. The only rulebases an agent loads at startup are those specified in the rulebase map, by the rulebases parameter, and in the Include lists of those rulebases.
Using Manual Configuration 101
Using the Repository Option

With the Repository option, the configuration source is one or more Repositories specified in -repository_path. All agents that use the same Repository load all changes saved to the Repository on startup. A Repository is a network application that distributes configuration objects to agents. Users send new and updated objects to the Repository, and it responds to configuration requests from TIBCO Hawk agents. You specify a Repository for an agent to use with the repository_path parameter, and one or more Repository names. A particular agent on the network hosts each Repository and has a Repository microagent with methods for accessing configuration objects. For more information on setting up a Repository, see TIBCO Hawk Installation and Configuration. For more information on microagents, see the TIBCO Hawk Methods Reference. In addition, you can configure an agent to maintain a backup of configuration objects in local cache with the -repository_cache parameter. This feature is useful for implementing fault-tolerance and for minimizing unnecessary object transfer across the network. Agents compare locally cached rulebases with those stored in the Repository, and retrieve only new or updated objects. If a Repository defined in the -repository_path option for an agent does not respond to a request within 15 seconds, the agent searches the local cache directory for the configuration object.
102
| Chapter 5
When a Repository is started on the network, TIBCO Hawk Display discovers it and creates a Repository container icon.
Right-clicking on a Repository icon provides access to the rulebases, schedules and rulebase map it contains:
For more information on rulebase maps and schedules, see Chapter 7, Advanced Rulebase Features. Note: You cannot move Repository icons from the Repository container, or include them in Canvas View. You create and edit configuration objects in a Repository in a similar manner as for individual agents in Agent View. The following sections describe how to save, send, and remove rulebases in Repositories.
Saving a Rulebase in a Repository

To save a rulebase in a Repository: 1. In TIBCO Hawk Display, right-click on the Repository icon with the rulebase and select Get Rulebases from the menu. The Rulebase List for Repository dialog displays:
2. Using toolbar button commands, create or edit rulebases in the Repository. For instructions on using the Rulebase Editor, see Creating a Rulebase on page 66. Note: To create or edit rules in a rulebase, the agent hosting the Repository must have access to the necessary microagents. If a microagent is not accessible, create or edit rules on an agent that has access, then send the rulebase to the Repository. For more information, see Sending a Rulebase to a Repository on page 104. 3. In the Rulebase Editor dialog, click OK.
104
| Chapter 5
The Rulebase List for Repository dialog displays rulebases in the current Repository. 4. Click Apply Changes to save the rulebase.
Agents that use this Repository load the saved rulebase the next time they are started. To direct agents to load particular rulebases in a Repository, use a rulebase map. For more information, see Using a Rulebase Map on page 122.
Sending a Rulebase to a Repository

You can send a new or modified rulebase to one or more Repositories. The rulebase to send can be on an individual agent or in another Repository. Sending a rulebase to a Repository stores the rulebase in the Repository. Agents that use the Repository load the sent rulebase the next time they are started. From an Agent To send a rulebase from an agent to a Repository: 1. In TIBCO Hawk Display, right-click on the agent icon with the rulebase to send and select Get Configuration>Rulebases from the menu. The Rulebase List for Agent dialog displays. 2. Click the rulebase to send and click Send Selected To. The Distribute Rulebase To dialog displays:
3. Click one or more Repositories to distribute the rulebase to. If an existing rulebase with the same name exists on the destination Repository, it is immediately overwritten. 4. Click OK.
The rulebase is sent to the selected Repository or Repositories. Agents that use the Repository will load the rulebase the next time they are started. From a Repository To send a rulebase from a Repository to one or more other Repositories on the network: 1. In TIBCO Hawk Display, right-click on the Repository icon with the rulebase to send and select Get Rulebases from the menu. The Rulebase List for Repository dialog displays: 2. Click the rulebase to send. 3. Select Rulebase>Send Selected Rulebase To. The Distribute Rulebase To dialog displays:
4. Click one or more Repositories to distribute the rulebase to. 5. Click OK. A status dialog displays:
The rulebase is sent to the selected Repository or Repositories. Agents that use the Repository load the rulebase the next time they are started. You can also use this procedure to send a rulebase from a Repository to one or more agents on the network. In TIBCO Hawk Display, select Get Rulebases for the Repository. Then, follow the remaining steps in this section to send the rulebase to one or more agents. If a rulebase with the same name exists on the agent or agents, it is immediately overwritten.
106
| Chapter 5
Removing a Rulebase from a Repository

You can remove a rulebase from one or more Repositories when the rulebase is no longer needed. To remove the rulebase, you can work either directly in the Repository, or on an agent on the same network. Deleted rulebases cannot be recovered. You should make a backup copy of files in your Repository periodically, or before and after you make major changes. From an Agent If the rulebase to remove is in a Repository on the network and you are working on an agent, use the following procedure. The rulebase to remove must be loaded on the agent. To remove a rulebase on an agent from a Repository on the network: 1. In TIBCO Hawk Display, right-click on the agent icon with the rulebase to remove and select Get Configuration>Rulebases from the menu. The Rulebase List for Agent dialog displays. 2. Click the rulebase to remove and select Rulebase>Delete Selected Rulebase From. The Delete Rulebase From dialog displays:
3. Click one or more Repositories to delete the rulebase from. Use the Shift and Control keys to select multiple Repositories. 4. Click OK. A status dialog displays:
The rulebase is deleted from the selected Repository or Repositories. However, the rulebase remains on the agent. You can also use this procedure to remove a rulebase in a Repository from one or more other Repositories on the network. In TIBCO Hawk Display, select Get Rulebases for the Repository to work in. Then, follow the remaining steps in this section to remove the rulebase from a Repository or Repositories on the network. From a Repository These steps describe how to remove a rulebase from the current Repository. You can also remove a rulebase in a Repository from another Repository on the network. The Repository you work in must have the rulebase to remove. For more information, see From an Agent on page 106. To remove a rulebase from a Repository: 1. In TIBCO Hawk Display, right-click on the Repository icon with the rulebase to remove and select Get Rulebases from the menu. The Rulebase List for Repository dialog displays. 2. Click the rulebase to remove and select Edit>Delete, or click the Delete toolbar button. The rulebase is immediately removed from the list. 3. Click Apply Changes. The rulebase is deleted from the current Repository.
108
| Chapter 5
Understanding Configuration Scenarios

Complicated scenarios can result from the various rulebase tasks and configuration modes. Table 6 describes some of these scenarios and their consequences in Manual and Automatic Configuration modes. Table 6 Configuration Scenarios Action
Specify startup rulebases.
Manual Configuration
You specify one or more directory paths or Repositories for the TIBCO Hawk agent to find rulebases to load at startup. You can explicitly state the names of additional rulebases the TIBCO Hawk agent should load, as well as a rulebase map. The rulebase exists only in memory. You must explicitly save the rulebase to a file or Repository if you want it to exist after the agent process ends. The agent does not load the rulebase at startup unless you add the rulebase name to the rulebase map, the explicit list of startup rulebases, or an Include list. The changes are applied only to the copy of the rulebase in memory. You must explicitly save your changes to a rulebase file or Repository to save them after the agent process ends.
Automatic Configuration
You specify an auto-configuration directory, and the TIBCO Hawk agent loads all files in that directory at startup.
Create a rulebase and send it to an agent.
The rulebase is created in memory and also copied to a file in the auto-configuration directory. Because the file is in the auto-configuration directory, it is reloaded at startup.
Change a rulebase and apply the change to an agent.
The rulebase is changed in memory, and the rulebase file in the auto-configuration directory is changed.
Rename a rulebase and apply the change to an agent.
The name is changed only in memory. You must explicitly save the rulebase to a file or Repository to save the new name after the agent process ends. To load the rulebase with the new name on startup, you must modify the rulebase map, explicit list of startup rulebases, or Include list. The rulebase is deleted only from memory. The rulebase file is not deleted, and it will be reloaded at startup if it is specified in the rulebase map, explicit list of startup rulebases, or Include list.
The name is changed in memory, the old rulebase file (with the old name) has been deleted, and the new rulebase file has been saved (with the new name) in the auto-configuration directory. The rulebase is deleted from memory, and the rulebase file is deleted from the autoconfiguration directory.
Delete a rulebase and apply the change to an agent.
Understanding Configuration Scenarios 109
Table 6 Configuration Scenarios (Contd) Action Send a rulebase across the network to an agent. Manual Configuration The rulebase is copied to memory only on the machine you send it to. To make the change permanent, you must copy the rulebase file to that machine or send it to a Repository; then modify the rulebase map, explicit list of startup rulebases, or Include list. You delete the rulebase from memory only on that machine. To permanently remove a rulebase from multiple agents you must remove it from the rulebase map, explicit list of startup rulebases, and Include lists.
The agent searches the list of configuration path directories or Repositories for rulebases with the specified name.
Automatic Configuration The rulebase is copied to memory on the machine you send it to, and copied to a file in that agents auto-configuration directory. Because the file is in the autoconfiguration directory, it is reloaded at startup. You delete the rulebase from memory; you also delete the rulebase file in the agents auto-configuration directory; and it is not reloaded at startup.
The method invocation fails.
Delete a rulebase across the network for an agent that has this type of configuration.
Load a rulebase using the
RuleBaseEngine: loadRuleBase()
method. Manually copy a rulebase file into the auto-configuration directory. Nothing will happen, and the rulebase is not loaded at startup. Not applicable.
In all configuration modes, you can also load rulebases manually using the RuleBaseEngine:loadRuleBaseFromFile() method, or unload using RuleBaseEngine:unloadRuleBase() method. These methods do not affect the list of rulebases loaded at startup.
110
| Chapter 5
| 111
Chapter 6
Using the TIBCO Hawk Event Service
This chapter describes the role of the TIBCO Hawk Event Service, a separate process that collects information about TIBCO Hawk agents. Representative entries in Event Service data files are given, as well as practical usage information.
Topics
Overview, page 112 Interpreting Event Service Data Files, page 116 Executing Commands on Loss of Heartbeat, page 118 Using the Event Service for Integration, page 119
112
| Chapter 6
Overview
The TIBCO Hawk Event Service is a separate process that collects information about TIBCO Hawk agents. Because it runs independently from other TIBCO Hawk processes, the Event Service can detect and report the event if an agent process should fail. The main tasks of the Event Service are: Record events reported by agents in text files or relational databases using JDBC Detect and respond to agent termination Asynchronously notify using AMI
For instructions on installing and starting the TIBCO Hawk Event Service, see TIBCO Hawk Installation and Configuration.
AMI Instrumentation
The Event Service is implemented as an AMI microagent, which allows users to be asynchronously notified on instances of agent activation, expiration, alerts generated and alerts cleared by Hawk Agents on a particular Hawk domain. The microagent COM.TIBCO.hawk.microagent.HawkEventService exposes the following asynchronous methods:
_onUnsolicitedMsg onAgentAlive onAgentExpired onAlert onClear onMicroAgentChange onRulebaseChange
For more information on these methods, see the TIBCO Hawk Methods Reference.
Overview 113
Persistence of TIBCO Hawk Events using JDBC

All alerts generated and cleared by TIBCO Hawk Agents across the network, as well as agent activation and expiration events, are written to a relational database using JDBC. Data is stored in two separate tables, created automatically at startup (if they are not already present in the specified database):
HawkAgentInfo. The events onAgentAlive, onAgentExpired,
onMicroAgentAdded, onMicroAgentRemoved, onRulebaseAdded onRulebaseRemoved
and
add rows to this table.
HawkAlertClearInfo. Events onAlert and onClear add rows to this table.
The layouts for these tables are shown below. Table 7 Table Layout for HawkAgentInfo Column Name Hawk_Domain Agent_Name Agent_Domain Agent_IP_Address Agent_StartTime Event_Time Event_Type Data Type VARCHAR(128) VARCHAR(128) VARCHAR(128) VARCHAR(64) VARCHAR(128) VARCHAR(128) VARCHAR(32) Can be: onAgentAlive onAgentExpired onMicroAgentAdded onMicroAgentRemoved onRuleBaseAdded onRuleBaseRemoved MicroAgentID Rulebase VARCHAR(128) VARCHAR(128) Description
Table 8 Table Layout for HawkAlertClearInfo Column Name Hawk_Domain Data Type VARCHAR(128) Comments
114
| Chapter 6
Table 8 Table Layout for HawkAlertClearInfo (Contd) Column Name Agent_Name Agent_Domain Agent_IP_Address AlertID Event_Time Event_Type Alert_State Data Type VARCHAR(128) VARCHAR(128) VARCHAR(128) INTEGER VARCHAR(128) VARCHAR(32) VARCHAR(32) Can be onAlert or onClear Can be: NO_ALERT ALERT_LOW ALERT_MEDIUM ALERT_HIGH Alert_Text Rulebase RuleName Test Alert_Properties Clear_Reason VARCHAR(1024) VARCHAR(128) VARCHAR(512) VARCHAR(512) VARCHAR(512) VARCHAR(256) "NA" for a clear "NA" for a clear "NA" for a clear "NA" for an alert event "NA" for a clear Comments
Fault Tolerance
You will normally run the TIBCO Hawk Event Service on a single system in a TIBCO Hawk managed network. However, multiple instances of the TIBCO Hawk Event Service can run on separate machines for fault tolerance. Fault tolerance is implemented using TIBCO Rendezvous Fault Tolerance (TRFT). Each instance of a TIBCO Hawk Event Service process joins a fault tolerant group named HawkEventService:hawkdomain, where hawkdomain is the value of the -hawk_domain command line option.
Overview 115
To rank the members of a group, Rendezvous fault tolerance software sorts the members by weight. Weight is assigned using the -ft command line option. The member with the highest weight receives rank 1 (so it outranks all other members); the member with the next highest weight receives rank 2; and so on. When two or more members have the same weight, Rendezvous fault tolerance software ranks them in a way that is opaque to programs. Refer to TIBCO Rendezvous documentation for details regarding fault tolerance.
116
| Chapter 6
Interpreting Event Service Data Files

When running, the Event Service records: All alerts generated and cleared by TIBCO Hawk agents across the network, as well as changes in agent alert level (represented as icon colors in TIBCO Hawk Display) All instances of agent activation and expiration Add and remove operations for microagents and rulebases
It records these events in data files named Event.dat, located in the directory defined in the -eventdir agent startup option. Data files contain event monitoring information, while separate log files named Event.log record the state of the Event Service itself. For more information on Event Service log files, see Interpreting the TIBCO Hawk Event Service Log on page 257. The TIBCO Hawk Event Service creates rolling data files using the same mechanism as TIBCO Hawk log files. It also uses the same default values for file location, number and size. For more information on configuring these settings, see Interpreting the TIBCO Hawk Agent Log on page 255. Sample Alert Message The following entry shows a sample alert message logged in an Event Service data file:
ALERT_RECEIVED : alert={ agent={ host-name=cricket, dns=none, host-ip=123.123.123.123, network-ip=123.123.123.0 }, alert-id=58, rulebase=Mail, alert-state=75, alert-text=%processor time >= 25, time-received=Thu Sep 24 09:03:56 EDT 1998 }, at Thu Sep 24 09:03:56 EDT 1998
The dns field has a value of none unless an agent domain is specified. The alert-id field is a numeric identifier for the alert that is unique across host-name and dns combinations. If a single condition generates multiple alerts, the alert messages have the same alert-id value. Agent State Change Entries Event Service data files contain the following types of entries for agent state changes:
AGENT_ALIVE : agent={ host-name=ultrahawk1, dns=none, host-ip=160.101.246.16, network-ip=160.101.246.0 }, alert-state=75, at Sat Dec 18 11:40:36 EST 1999
Interpreting Event Service Data Files 117
AGENT_EXPIRED : agent={ host-name=jaguar, dns=none, host-ip=123.123.123.123, network-ip=123.123.123.0 }, at Thu Sep 24 09:04:00 EDT 1998 ALERT_CLEARED : agent={ host-name=protege, dns=none, host-ip=123.123.123.123, network-ip=123.123.123.0 } alert-id=35, reason=test evaluated to FALSE, at Thu Sep 24 09:04:03 EDT 1998 AGENT_STATE_CHANGE : agent={ host-name=cricket, dns=none, host-ip=123.123.123.123, network-ip=123.123.123.0 }, new-alert-state=0, at Thu Sep 24 09:04:27 EDT 1998 AGENT_REINITIALIZED : agent={ host-name=jaguar, dns=none, host-ip=123.123.123.123, network-ip=123.123.123.0 }, alert-state=75, at Thu Sep 24 09:06:09 EDT 1998
In agent entries, alert levels are represented numerically. To find the text equivalent, use the following table to translate the value of the alert-state field: Table 9 Numeric Representations of Alert Levels in Event.dat Files Numeric Value
0 25 50 75
Alert Level
Notification Low Medium High
Microagent and Rulebase Event Entries Event Service data files contain the following types of entries for microagent and rulebase events:
MICROAGENT_ADDED : AgentID={ host-name=boxter, dns=none, host-ip=160.101.246.18, network-ip=160.101.246.0 }, MicroAgentID=COM.TIBCO.hawk.hma.Network, at Sat Dec 18 11:50:38 EST 1999 MICROAGENT_REMOVE : AgentID={ host-name=boxter, dns=none, host-ip=160.101.246.18, network-ip=160.101.246.0 }, MicroAgentID=COM.TIBCO.hawk.hma.FileSystem, at Sat Dec 18 11:50:36 EST 1999 RULEBASE_ADDED : AgentID={ host-name=pchawk1, dns=none, host-ip=160.101.246.11, network-ip=160.101.246.0 }, rulebase=cricket, state=75, at Sat Dec 18 11:50:36 EST 1999 RULEBASE_REMOVE : AgentID={ host-name=boxter, dns=none, host-ip=160.101.246.18, network-ip=160.101.246.0 }, rulebase=System, at Sat Dec 18 11:50:36 EST 1999
118
| Chapter 6
Executing Commands on Loss of Heartbeat

If the heartbeat of a TIBCO Hawk agent is not received for some time, the Event Service can call a command-line script or executable. Loss of heartbeat usually means that the agent process has terminated or network communication has been interrupted. A script could send an e-mail or pager message, providing notification even when no agent or instance of TIBCO Hawk Display is running. The default setting is to execute no script. To execute a command on loss of agent heartbeat, you provide the fully-qualified name of an executable file in the Script File field on the Event Service tab of the Configuration Tool. In the script, specify the name of a binary file that performs the notification task. To qualify the notification message, Event Service can provide the following arguments in this order: 1. Agent name (usually the name of the machine where the agent is installed) 2. IP address of the machine where the agent runs For example, for an agent running on Microsoft Windows, a script named sendpage.bat might contain the following lines:
@echo off rem Usage - sendpage.bat <agentname> <agent_ipaddress> send_page.exe %1 %2 exit
For considerations on executing commands in your TIBCO Hawk environment, see Tips on Monitoring Custom Scripts on page 197. You could also call a script that logs into the machine and checks for the existence of an agent process before sending notification.
Using the Event Service for Integration 119
Using the Event Service for Integration

In addition to storing a record of events, the TIBCO Hawk Event Service is a useful tool for exchanging information between TIBCO Hawk agents and other monitoring products. If an external application can read and parse log files, you can notify it of TIBCO Hawk events. Configure the application to read the Event Service data files and parse log entries, using pattern matching techniques to locate headings for particular event types. This method of exchanging information is easier to manage and generates less network traffic than using SNMP traps or executing scripts on the remote machine. More significantly, if a TIBCO Hawk agent process terminates, the Event Service can notify the external application. Any mechanism that relies on the TIBCO Hawk agent to exchange data with external applications cannot provide this type of notification.
120
| Chapter 6
| 121
Chapter 7
Advanced Rulebase Features
This chapter describes some advanced TIBCO Hawk rulebase features and shows how to use them.
Topics
Using a Rulebase Map, page 122 Working with Agent Groups, page 124 Including a Rulebase, page 134 Adding Commands to a Rulebase, page 136 Referencing Variables in a Rulebase, page 139 Overruling a Rule, page 143 Using Posted Conditions, page 146 Working with Schedules and Period Groups, page 148 Working with Schedule Files, page 168 Automating Rulebase Management, page 172
122
| Chapter 7
Using a Rulebase Map

A rulebase map is a configuration object that maps rulebases to TIBCO Hawk agents on your network. It directs TIBCO Hawk agents or groups of agents on your network to load particular rulebases at startup. For example, using a rulebase map you can instruct an agent to load a rulebase designed specifically for the operating system where it runs. To efficiently manage agent configuration, an entire enterprise should use the same rulebase map. Configuration objects access the rulebase map using the same configuration source they use to access rulebases. Note: Rulebase maps are supported only when running in Manual Configuration mode. For more information, see Choosing a Configuration Mode on page 98. When creating a rulebase map, you typically group agents on your network according to rulebase requirements. Then you map individual rulebases to agents and groups of agents and save the rulebase map. Agents in Manual Configuration mode load the rulebase map when started to determine which rulebases they require. Agents then proceed to load these rulebases, if they exist in the configuration source.
Creating a Rulebase Map

You create and save a rulebase map using TIBCO Hawk Display. Agents running in Manual Configuration mode with the Repository or Configuration Path options can use the rulebase map the next time they are started. When creating a rulebase map, rulebases do not have to exist yet, but rulebase names must be defined for mapping purposes. TIBCO Hawk software provides an empty default rulebase map as a template, which you can customize. To create or edit a rulebase map, do one of the following: Right-click on a Repository icon and select Get Rulebase Map. Right-click on an agent icon and select Get Configuration>Rulebase Map.
Using a Rulebase Map 123
The Rulebase Map from Repository or Rulebase Map from Agent dialog displays:
The left column is for rulebase names. The right column is for agents and groups of agents that should load the rulebase. To create mappings in this dialog, see Mapping Rulebases to Agents on page 127. You can perform most rulebase map operations using toolbar commands.
Adds a new mapping to the rulebase map
Edits the Deletes the Saves the rulebase Sends the rulebase map selected selected map in the current map to one or more Repositories on the network mapping mapping Repository
Copies the selected mapping and opens the copy for editing
In this dialog, the default mode is to map rulebases to agents or groups. To map agents or groups to rulebases, select View>Agent/Groups to Rulebases Mapping. Then follow the mapping steps on page 127, selecting a single agent or group from the dropdown list and assigning rulebases. To map groups to rulebases, select View>Groups to External Command Mapping. Then follow the mapping steps on page 135, selecting a group from the dropdown list and assigning commands.
124
| Chapter 7
Working with Agent Groups

Agent groups are sets of TIBCO Hawk agents on the same network with similar rulebase needs. Groups are more efficient when mapping rulebases to agents in a rulebase map. Instead of assigning a rulebase to every individual agent that needs it, you can assign it once to the group. Every rulebase map can have two types of groups: user-defined and automatic. Automatic groups, defined for you in TIBCO Hawk software, consist of operating system groups and the ALL group. The ALL group includes every agent on your network. The set of operating system groups includes one group for each operating system represented in the ALL group. For example, a network where TIBCO Hawk agents run on Solaris and Microsoft Windows XP has Solaris and Microsoft Windows XP operating system groups, and an ALL group. You can also define groups using the Rulebase Map Group Editor in TIBCO Hawk Display. User-defined groups are optional, and can include any combination of individual agents and other agent groups. For example, a user-defined group might include one or more automatic groups. All group names begin with a plus (+) character. Operating system groups are named ++<OS>, where OS is the name of the operating system. The ALL group has the name ++.
Defining Agent Groups

To define a new agent group: 1. In the Rulebase Map from Agent dialog, select Edit>Group from the menu. The Rulebase Map Group Editor dialog displays.
Working with Agent Groups 125
2. With Groups to Agents/Groups Mapping selected in the dropdown list, click the Create button on the toolbar.
In this dialog, you can select a single group and add multiple agents or agent groups. This mode is useful for adding multiple agents to a new group. The Group Definition dialog displays:
TIBCO Hawk agents on the network and automatic groups display in the column on the right. You can also select an individual agent to add to several groups by selecting Hosts to Groups from the dropdown list. This mode is useful for adding a
126
| Chapter 7
new agent to multiple groups. For instructions, see Adding Agents to a Group. 3. Click in the Group field and type a name for the new group of agents. The Group dropdown list contains existing groups for editing. The list does not contain the ALL group, since all agents automatically belong to this group. 4. Click the name of an agent or group to add to the new group in the Host/Group Available list. Note: Agents in a group should have similar rulebase requirements.
5. Click Add to move it to the Includes list. The agent or group name displays on the left. If the group is not displayed in the Host/Group Available list, use the Add button below the Includes list to add it. If this name is invalid, the agent generates an error when it is started. 6. Add other agents and groups to this group for rulebase distribution. To remove group from the Includes list, click it and then click Remove. 7. Click OK.
Adding Agents to a Group

Adding agents to groups allows you to add individual agents to one or more agent groups. You should add agents to groups that consist of agents with similar rulebase requirements. For instructions on creating groups, see Defining Agent Groups on page 124. To add an agent to an agent group: 1. In the Rulebase Map Group Editor dialog, select Agent to Groups Mapping from the dropdown list. The Group Definition dialog displays groups defined on this agent in the column on the right. 2. Select the name of an agent to assign to a group from the dropdown list. 3. Click the name of a group for the agent in the Group Available list. 4. Click Add to move it to the In Group list The group name displays on the left. If the group is not displayed in the Group Available list, use the Add button below the In Group list to add it. If this name is invalid, the agent generates an error when it is started. 5. Add this agent to other groups for rulebase distribution.
To remove a group name from the In Group list, click it and then click Remove. 6. Click OK.
Mapping Rulebases to Agents

After defining any agent groups, you map rulebases to agents and groups of agents. Mapping a rulebase to a single agent directs the agent to load that rulebase when it is started. Mapping a rulebase to a group of agents directs all agents in the group to load the rulebase when started. For more information on agent groups, see Working with Agent Groups on page 124. These instructions begin in the Rulebase Map from Repository or Rulebase Map from Agent dialog. For instructions on accessing these dialogs, see Creating a Rulebase Map on page 122. In both dialogs, the default mode is to map rulebases to agents or groups. To map agents or groups to rulebases, select View>Agents/Rulebase to Agents/Groups Mapping. Then use the following steps as a guide, selecting a single agent or group and adding rulebases. To map a rulebase to an agent or group: 1. Select Edit>Create from the menu, or click the Create button on the toolbar.
128
| Chapter 7
The Rulebase to Agents/Groups Mapping dialog displays:
2. Select the rulebase to map from the dropdown list. All rulebases discovered by TIBCO Hawk Display are included in the list. If the rulebase does not exist yet, click in the Rulebase field and type the name. 3. On the right, click the name of an agent or group you want to assign the rulebase to, then click Add to move it to the Use By list.
The agent or group name displays on the left. You can add an agent that has not been discovered or a group that is not yet defined by clicking the Add... button below the Use By list. The Add Host/Group to list dialog displays:
Type names of agents or groups, separating multiple entries with carriage returns, then click OK. If a name is invalid, the agent generates an error when it is started. For instructions on creating groups, see Defining Agent Groups on page 124. 4. Add more agents and groups until all agents that should load this rulebase are listed. To remove an agent or group from the Use By list, click it and then click Remove.
130
| Chapter 7
5. Click OK. The dialog displays the rulebase name with agents and groups that will load it at startup:
6. Add other mappings to complete the rulebase map. When the rulebase map is complete, you must save it in a configuration source so that agents on your network can use it. To save the rulebase map, you can save it in a file or a Repository. You can also send a rulebase map to one or more Repositories on the network.
Mapping Groups to External Commands

An external command is an alternative or a complimentary mechanism to rulebase maps for identifying the rulebases to be loaded. You can map external commands to a group or a single agent. The output of the external command must return a list of rulebase names, which are the additional rulebases that will be loaded. An agent can use multiple such external commands, the results of which are merged into one list with the duplicates removed. For more information on executing external commands, see Tips on Monitoring Custom Scripts on page 197 To map agents or groups to rulebases, select View>Group to External Command Mapping . Then use the following steps as a guide, selecting a single agent or group and adding external commands. To map an external command to an agent or a group:
1. Select Edit>Create from the menu, or click the Create button on the toolbar. The Groups External Command Mapping dialog displays:
2. Select an existing group from the drop-down list or type in a new group name. 3. Type in the external command name. 4. Click OK. 5. Highlight the Group to External Command Mapping created in the previous step and Select Map>Property. The dialog displays:
6. Click Use groups external command mapping to generate Rulebase list. 7. Click OK.
Saving a Rulebase Map in a Repository

To give agents using the Repository option access to the rulebase map, save it in a Repository. You can also send the rulebase map to one or more Repositories on the network. To save a rulebase map in a Repository:
132
| Chapter 7
In the Rulebase Map from Repository dialog, click Apply Changes to save the rulebase map.
To send a rulebase map to one or more Repositories on the network: 1. In the Rulebase Map from Repository or Rulebase Map from Agent dialog, click Send To, or select Map>Send To from the menu. The Distribute Rulebase Map dialog displays:
2. Click one or more Repositories to send the rulebase map to. Use the Shift and Control keys to select multiple Repositories. 3. Click OK. A status dialog displays:
The rulebase map is sent to the selected Repository or Repositories. Agents that use these Repositories use the rulebase map the next time they are started.
Saving a Rulebase Map to a File

To give agents using the Configuration Path option access to the rulebase map, save it to a file. When you save the rulebase map file in a configuration path directory, agents can use the rulebase map at startup. Saving to files is also useful for backing up a rulebase map before making changes or for storing a rulebase map when it is not being used. The default file name is rbmap.hrm. Note: These instructions begin in the Rulebase Map from Repository or Rulebase Map from Agent dialog. For instructions on accessing these dialogs, see page 122. To save a rulebase map to a file: 1. Select File>Save To File. The Save dialog displays:
2. Browse to a local or mapped directory for the rulebase map file, then click OK. Do not modify the file name. The rulebase map file, rbmap.hrm, is saved in the specified directory. If this directory is specified in the config_path parameter for an agent, the agent uses the rulebase map the next time it is started.
134
| Chapter 7
Including a Rulebase
A rulebase can specify other rulebases to automatically load when it is loaded by an agent. This feature is useful for maintaining modular rulebase sets. For example, if rulebase A should always be loaded with rulebase B, then rulebase B can have A as a member of its include list. You can use include lists to load rulebases when an agent starts or after it is running. However, after making updates, you should always manually distribute included rulebases using the Send To feature. An agent loads an included rulebase only if it is not already loaded. For example, an agent loads rulebase B and included rulebase A when it starts. If you modify both rulebases, then distribute the updated rulebase B to other agents, the new version of rulebase A is not reloaded because this rulebase already exists on the agent. For more information, see Sending a Rulebase to Agents on page 93. Similarly, included rulebases remain loaded on the agent when the parent rulebase is removed. To remove included rulebases, either delete them manually using TIBCO Hawk Display or invoke the RuleBaseEngine:unloadRuleBase() method. For more information, see the TIBCO Hawk Methods Reference. Note: Include lists are supported only when running in Manual Configuration mode. For more information, see Choosing a Configuration Mode on page 98. To include a rulebase in another rulebase: 1. Arrange TIBCO Hawk Display so that the agent with the parent rulebase displays on the right. 2. Right-click on the agent icon and select Get Configuration>Rulebases. The Rulebase List dialog displays. 3. Click the parent rulebase name, then click Edit. The Rulebase Editor dialog displays. 4. Click Advanced.
Including a Rulebase 135
The Advanced Rulebase Editor dialog displays.
5. Click the Create toolbar button in the Include List section. The Include Rulebase dialog displays:
6. Type the name of an existing rulebase to include. 7. Click OK. The Include List displays the name you typed. 8. Repeat steps 5 through 7 to include more rulebases. 9. Click OK. 10. To immediately apply these commands to the agent, click Apply Changes in the Rulebase List dialog. The include list is saved in memory on the current TIBCO Hawk agent. To permanently save rulebase changes, save the rulebase to a file or Repository. For more information on Repositories, see Using the Repository Option on page 101.
136
| Chapter 7
Adding Commands to a Rulebase

You can add commands or scripts to a rulebase, then execute the command from the Get Commands menu for an agent. When you select Get Commands for an agent, a list of all commands from all rulebases currently loaded on the agent displays. The command is executed using the Custom:execute() microagent method on that agent. This feature allows you to organize scripts and utilities for individual nodes, and to execute them from your TIBCO Hawk environment. You execute commands by selecting a menu option in TIBCO Hawk Display, so starting new windows and manually typing command syntax are not required. Since each node with a TIBCO Hawk agent can have a customized set of scripts or other executables supporting the applications running on that node, adding commands to a rulebase can make these utilities accessible to users without requiring them to manually log on. This is especially useful for nodes that exist outside a firewall. Any command can be added to a rulebase, but rulebase commands are typically related to the resources or activity the rulebase monitors. For example, if a rulebase is monitoring the httpd daemon, the commands could execute scripts such as: start_httpd or kill_httpd. To add commands to a rulebase, first you specify the command syntax in a rulebase and save it on one or more agents. Then you can execute the command on an agent using TIBCO Hawk Display.
Specifying Rulebase Commands

To add a command to an agent and add it to the Commands list: 1. Arrange TIBCO Hawk Display so that the agent with a rulebase that you want to add commands to displays on the right. 2. Right-click on the agent icon and select Get Configuration>Rulebases. The Rulebase List dialog displays. 3. Click the rulebase name, then click Edit. The Rulebase Editor dialog displays. 4. Click Advanced.
Adding Commands to a Rulebase 137
The Advanced Rulebase Editor dialog displays.
5. Click the Create toolbar button in the Command List section. The Command dialog displays:
6. Type a command or the name of a script to execute. You can specify an absolute or relative path. To specify multiple commands, separate them with a semicolon (;) delimiter. 7. Click OK. The Commands List displays the string you typed. 8. Repeat steps 5 through 7 to add more commands. 9. Click OK.
138
| Chapter 7
10. To save rulebase commands, do one or both of the following: To immediately apply rulebase commands to an agent, click Apply Changes in the Rulebase List dialog. To permanently save rulebase commands with the rulebase, save the rulebase to a file or Repository. For more information on Repositories, see Using the Repository Option on page 101. A command can now be executed on the agent where it is saved from TIBCO Hawk Display running on any machine in the network. For considerations on executing commands in your TIBCO Hawk environment, see page 197.
Executing Rulebase Commands

To execute a command or script associated with a rulebase: 1. Click an agent icon in TIBCO Hawk Display. 2. Right-click on the icon and select Get Commands from menu. The <agent> Commands dialog displays.
3. Double-click the command or name of the script to execute. You can also click to select it, then click Execute. 4. Click Close to close the dialog.
Referencing Variables in a Rulebase 139
Referencing Variables in a Rulebase

You can reference several kinds of variables in a rulebase. By referencing variables, the rulebase can adapt to changes on multiple machines. For example, not all machines store log files or temporary files in the same directory. Also, rulebases used on multiple platforms need to accommodate subtle differences in how path names are expressed. You can use variables rather than specifying this information manually. When an action contains variable substitution, a new alert is generated each time the test is true and the value of the variable changes. Variable substitution is most useful for values that are either slowly changing, very important, or both. Variable substitution affects the performance of rulebase processing. Therefore, you should reference a variable only when it provides a clear benefit.
Supported Types of Variables
The following types of variables are supported in a TIBCO Hawk rulebase: External, such as user-defined variables Internal, such as the name of a test in a rule Data source, such as a microagent method result field (Data source variables can be referenced in actions only)
Referencing these variables outside of a rulebase is not supported.

Order of Evaluation
Variable types are listed the order they are evaluated by an agent. However, nested variables can change the evaluation order. For example, if an external variable is nested inside an internal variable, the internal variable is evaluated first, followed by the nested variable.
Referencing External Variables

External variables are variables defined by a user on the machine where the TIBCO Hawk agent runs. First, you define the variable values in a properties file on the local machine. Then you specify the variable file using the -variable option when starting Hawk Agent. Then you can reference the external variable in a rulebase. For more information on agent startup parameters, see TIBCO Hawk Installation and Configuration. After variable values are defined and the properties file is specified to the agent, you can reference external variables in a rulebase using the following syntax:
${External.<variable-name>}
140
| Chapter 7
where variable-name is the name of an environment variable defined in the properties file. The file uses a standard Java property file format, with one line per variable defined. Each entry is a name-value pair in the following format:
<variable-name>=<value>
For example, to use a variable for c:\tibco\hawk, you would specify in the file: HAWK_ROOT=c:\\tibco\\hawk. Also, due to the Java file path separator format, HAWK_ROOT=c:/tibco/hawk will also work properly on Microsoft Windows. You can reference external variables in string arguments of actions and in data source method string arguments. For example, the Hawk Services sample rulebase provides a rule for sending a high-level alert. Without variable substitution, the text of the alert is generic. With variable substitution, the alert includes information specific to the generating condition. Restrictions In Microsoft Windows, the following restrictions apply to external variables: The variables file to support External variables in the agent must conform to the Java properties file format. Variables and variable names cannot include spaces or any of the following characters: equals sign (=), period (.), or forward slash(\). Any special characters must be escaped to be evaluated properly.
On UNIX systems, the env command outputs environment values in the correct format.
Referencing Internal Variables

Internal variables refer to elements of the current rulebase. This type of variable is defined internally by the TIBCO Hawk agent, and requires no properties file. Values are assigned to variables when the rule is processed. Like external variables, internal variables can be referenced in string arguments of methods used as a rules data source or in string arguments of actions. You can manually type internal variable syntax in the string argument of a method, or, for action arguments, TIBCO Hawk Display provides a dropdown list of internal variables.
Manually entering variables
To manually enter internal variables, specify the variable using the following syntax:
${Internal.<variable>}
where <variable> can be Agent
Name, Agent IP Address,
or so on.
Referencing Variables in a Rulebase 141
The variables will be substituted with the appropriate value before the command is executed. For example, the command Telnet ${Internal.Agent Name} will be executed as Telnet kimyou if the command is executed for agent kimyou from the Agent View.
Referencing Data Source Variables

Data source variables are TIBCO Hawk variables that represent the return fields of a microagent method. The method must be used as the data source of the current rule. You can reference data source variables only in actions. For example, the Hawk Services sample rulebase provides a rule for monitoring an event log and sending a high-level alert message when an error is written to the log. The Alert action type used in this rule allows you to specify a text string for the alert message. In this example, the text string is:
Hawk Agent : ${nextLine}
where ${nextLine} is the text of the error message in the log. nextLine is a label for values returned by the microagent method that gets information from the log file. Without variable substitution, you could include only static text, such as High level alert or a similar string, in the alert message.
How Variable Substitution Affects Actions

Action text strings can include variable references, where you include pertinent information from the data source in the alert text. For example, the alert text:
Disk space on ${Instance} is at ${% Free Space}%
might display as:

Disk space on C: is at 10.2%
when generated. Or, if you call a script named ClearTempFiles.exe in an action whose data source provides information on disk partitions, you could specify the following command syntax:
ClearTempFiles.exe ${Instance}
and the agent will insert the name of the logical drive into the command line.
142
| Chapter 7
Variable substitution can cause duplicate actions. If an action raises an alert with a variable reference, a new alert is generated at each test evaluation when the text message is different until the alert is cleared, even if the action that raises the alert was configured to take place only once. For example, the following four alerts were all created by one action, due to recent changes in the amount of disk space:
For seven minutes, the disk space was around 84.6% Then for less than one minute, disk space was around 84.5% And since then it has been around 84.39%. The alert is still active because disk space is still below 90%.
Overruling a Rule 143
Overruling a Rule
When designing rules in a rulebase, you look for similar requirements among groups of agents. Rulebases can then be distributed to these groups to perform common tasks. If some agents in a group have slightly different rulebase requirements than others, you can use overruling to compensate for small discrepancies. Minimal configuration changes are required. Overruling is a way to set precedence among similar rules. For example, a group of machines on a network all run the TIBCO Rendezvous daemon, rvd. You build and distribute a generic rulebase with a rule to check that the rvd process does not consume more than 2 MB of memory and monitors the various Host Status advisory messages for the sessions. However, two machines in this group are servers with more memory running large TIBCO Rendezvous applications. They can handle heavier loads than the other machines. For the server machines, instead of using a totally separate rulebase, you can preserve the common functionality of the Host Status advisory monitoring in the original rulebase, but add a second rulebase containing only one rule with a higher memory threshold that also has a higher precedence than the same rule in the original rulebase. The first rulebase is loaded on all agents, but you load the second only on the two servers. Since the rule on the two servers has a higher precedence, the higher threshold rule is used and the lower threshold rule in the original rulebase is disabled. Note: Rule names are automatically assigned and guaranteed unique in a rulebase. For rules to overlap, they must be defined in different rulebases loaded on the same agent.
Allowing Overruling
You allow overruling for two or more rules with identical names and then assign precedence to each rule. When the agent processes the rules, only the rule with the highest precedence is enforced. The first step is to modify the existing rule to allow overruling. To allow overruling: 1. In the Rule Editor dialog, click the name of the generic rule, then click Advanced. For instructions on accessing this dialog, see Building a Rule on page 68.
144
| Chapter 7
The Advanced Rule Editor displays:
2. Click the Allow Over Ruling radio button. 3. Select a precedence value from the dropdown list. A value of 1 specifies lowest precedence and 10 specifies highest precedence. For the generic rule, specify a lower value than the overlapping rule. 4. Click OK. When you allow overruling, the rule is active only when its precedence value is greater than that of all other rules with the same name loaded on the agent. If two rules with the same name also have the same precedence value, both rules are enforced. 5. Click Apply Changes to save the overrule settings. 6. If other agents need the generic rulebase, click Send To. For more information, see Distributing a Rulebase to Agents on page 93. Allowing overruling controls when the rule is active. If overruling is not allowed for a rule, the rule is always enforced. For example, if two rules with identical names exist in different rulebases but do not allow overruling, these rules are always active.
Overlapping Rules
To define an overlapping rule: 1. In a new or different existing rulebase on the same agent, create a rule that has exactly the same name as the generic rule. For rule names to be identical, rules must use the same microagent method as a data source, and specify the same arguments and data collection intervals. For instructions, see Building a Rule on page 68. 2. Specify one or more tests and actions for the overlapping rule. You can modify test and action definitions to address the different requirements of an agent subset. For example, you might specify a higher
Overruling a Rule 145
threshold or issue a lower-level alert when a certain condition occurs. For more information, see Defining Tests on page 71 and Defining Actions on page 80. 3. Edit the advanced rule properties to allow overruling and to give this rule a higher precedence value than the generic rule. For instructions, see Allowing Overruling on page 143. Note: If two or more rules with the same name allow overruling and have the same precedence value, all rules with the highest value are active. 4. Click Apply Changes to save the overrule settings. 5. If other agents need to overrule the generic rulebase, distribute the overlapping rulebase. For more information, see Distributing a Rulebase to Agents on page 93.
146
| Chapter 7
Using Posted Conditions

A posted condition is an internal status message, similar to an alert message. Posted conditions are the result of actions in a rule, and can pass status information to other rules in the same rulebase. Each rule uses only a single data source for input, so the posted condition serves as a link between rules with different data sources. This allows you to test for conditions in more than one managed object.
Testing for Non-Zero Values

Posted conditions have integer values assigned internally by a TIBCO Hawk agent. When a rulebase is loaded, values are set to 0 until the action is performed. Performing the action creates the posted condition and gives it a non-zero value, signifying that the condition exists but has not yet cleared. Although the value is internal, a test in another rule can check the posted condition for existence or non-zero values. Posted conditions that can be used in a test are listed along with other parameters in the Test Builder dialog. For example, a rule could check CPU utilization every 60 seconds. If the CPU is greater than 80% utilized when the test is evaluated, a Post Condition action named SystemTooBusy is performed and its integer value becomes non-zero. Another rule in the rulebase retrieves the process table every 60 seconds. This rule contains the following compound test to identify processes consuming more than 50% of the CPU when total usage exceeds 80%:
((%CPU>50) AND (SystemTooBusy>0))
If this test evaluates to true, an alert message that includes the PID for the process is generated. Results from multiple data sources are required to perform this monitoring task.
Counting Results
You can also use posted conditions to count the number of results returned by the microagent method. Some microagent methods return tabular data when invoked. If the method returns a table of results, an instance of the associated test is generated for every row of the table. The actual value of a posted condition is the number of associated test instances that evaluated to true. You can use this relationship to count the number of rows in the table that match some condition. A non-zero value means that at least one row in the table matched the test condition. The value of the posted condition is the exact number of rows that matched the test condition.
Using Posted Conditions 147
For example, a software virus spawns multiple copies of a common process such as a web browser. The virus uses the SYSTEM account to accomplish this, which is not the normal account for a web browser. To check for the presence of this virus on your network you could create several tests and use a posted condition. The first rule could retrieve the process table, and use a compound test to check for more than one copy of the browser process running as SYSTEM.
If ((name=="netscape") AND (user=="SYSTEM"))
When the test evaluates to true, a posted condition named SystemBrowser is created. The second rule tests the value of the posted condition. It does not require data from a microagent, but uses a token data source: the microagent method Self:getUptime():10. This method returns the number of seconds the agent has been running every 10 seconds. The actual data retrieved from the data source is discarded, but every 10 seconds this method triggers a test for SystemBrowser>1. When the test evaluates to true, a high-level alert is generated.
148
| Chapter 7
Working with Schedules and Period Groups

A schedule is a configuration object that defines when a rulebase, rule, test or action is active. You define a schedule using TIBCO Hawk Display and save the schedule information in a file. Then you can send the schedule to one or more TIBCO Hawk agents or Repositories, and apply the schedule to rulebase objects.
Schedules
In a schedule, you specify the times during which a particular monitoring activity is in effect by defining inclusion periods and exclusion periods. An inclusion period consists of specific times when an object can be active. For example, you might have a rulebase that should be used only during business hours, so you create a schedule with an inclusion period of Mondays through Fridays, 9 AM to 5 PM. The schedule may also define exclusion periods, or times when the object must not be active, such as between 12:00 PM and 12:59 PM for lunch. A schedule is active (or "in-schedule") during inclusion periods only if no exclusion period applies. In this example, the schedule is in-schedule at 11:30 AM on Tuesday mornings. It is out-of-schedule an hour later at 12:30 PM and back in-schedule at 1 PM. The schedule is out-of-schedule at all times on Saturdays and Sundays. Using schedules is described in the next section.
Period Groups
A period group defines a set of related dates or times. For example, a period group named Holiday may include all of the holidays within a year. Period groups are stored together with the schedules of an agent or repository in a schedule file. Using period groups is described in Creating Period Groups on page 157.
Rulebase Objects
Rulebase objects are related through a hierarchy. A schedule applied to one node in the hierarchy also affects all nested objects. For more information, see Overview on page 64.
Tasks
This section provides information on the following tasks: Creating Schedules, page 149 Testing Schedules, page 164 Applying Schedules to Rulebase Objects, page 166
The next section, Working with Schedule Files on page 168, describes tasks associated with schedule files.
Working with Schedules and Period Groups 149
Creating Schedules
You define schedules in TIBCO Hawk Display, then send schedules to agents and Repositories on your network. Menu commands and toolbar buttons allow you to perform operations on a schedule object. To create a schedule: 1. In Agent View, click the icon for the agent where you want to create the schedule. In Repository View, click the Repository icon. 2. Right-click on the icon and select Get Configuration>Schedules. The Schedules from Agent or Schedules from Repository dialog displays the schedules defined for this agent or Repository. If there are no existing schedules, the list is empty.
Create Copy Modify Delete
150
| Chapter 7
3. Click Create to create a new schedule. Alternatively, to edit an existing schedule, doubleclick on the schedule name in the list or select it and click Modify.
Apply Changes
The Schedule Editor displays:
Set the time zone
Click here to create inclusion periods
Click here to create exclusion periods
4. Click in the Name field and type a name for the schedule object. This name must be unique within the Schedules list and cannot contain spaces. 5. Set the appropriate time zone by clicking on the dropdown menu in the upper right corner. The list of time zones is obtained from the Java virtual machine. If a custom time zone is needed, it can be specified as GMT-/+hh:mm where hh and mm are in relation to GMT. (For example, GMT-5:00.) If no time zone is specified, the local time zone is used. 6. To define inclusion periods, click the Create button on the upper toolbar.
152
| Chapter 7
The Schedule Period dialog displays:
For a schedule to be valid, you must select at least one interval in each category in the Schedule Period dialog: Time of Day, WeekDay of Week, Day of Month, and Month. If one or more categories has no selections, the schedule is not used. 7. Select one or more Time of Day intervals. There are four pre-defined intervals in the Schedule Editor: All Day 12:00 AM to 11:19 PM AM 12:00 AM to 11:59 AM PM 12:00 PM to 11:59 PM 9 to 5 9:00 AM to 4:59 PM By default, the 9 to 5 interval is displayed when the Schedule Period dialog opens. You can select a different pre-defined interval by clicking on the Time
of Day button in the upper right corner. The selected interval displays in the Time of Day field and in the Start and End fields. (Clicking on a pre-defined interval also resets the Start and End times to the selected interval.)
Click to display drop-down list
To create a custom interval, click in either the Start or End field. The Edit Interval frame displays.
Click to create a new interval Click to delete a selected interval Click to display time in 24-hour format
Click to apply changes
Click the up and down arrows in the Edit Interval frame to change the start and end times. You can also double-click in a field to type a number. When the desired times are displayed, click Apply to save the interval and close the Edit Interval frame. To add another interval, click the Add button. Another set of Start and End intervals are added. If an interval is selected when you click Add, the new interval is placed after the selected interval. If no interval is selected when you click Add, the new interval is placed before the existing intervals. By default, the new interval is the largest possible interval that can be specified. You can click in these fields to modify the interval, if desired.
154
| Chapter 7
To delete an interval, click in the Start or End field and then click the Delete button. You can have as many intervals as desired, but the intervals cannot overlap in time and cannot span more than 24 hours. For example, if the first interval starts at 12:00 AM, the last interval must end at 11:59 PM or earlier. If you try to add an interval when no time is available, a beep will sound. For example, the following dialog shows three intervals created: midnight to 8:59 AM, 9:00 AM to 4:59 pm, and 5:00 PM to 11:59 PM. In this example, no more intervals can be created because the existing intervals span 24 full hours; there is no available time that is not already part of an interval.
8. Select the days of the week and weeks in the month for the interval.
Click to display drop-down list
There are five pre-defined sets of days available in the WeekDay of Month drop-down list, although you can also click an individual day to select it: Weekday Mondays through Fridays Weekend Saturdays and Sundays Select All Every day Toggle Selection Selects the days that are currently not selected, and unselects the selected days Unselect Unselects all days There are five weeks available, selected by clicking the appropriate box: First The first occurrence in the month of the checked day(s) Second The second occurrence in the month of the checked day(s) Third The third occurrence in the month of the checked day(s) Fourth The fourth occurrence in the month of the checked day(s) Last The last occurrence in the month of the checked day(s). As Example 1, the following dialog shows the first and third Mondays in the month are selected:
Example 2, below, shows the last Saturday of every month is selected:
9. Select the dates of the month for the schedule. There are three pre-defined sets of dates: Select All The first through the last date of the month Toggle Selection Selects the dates that are currently not selected, and unselects the selected dates Unselect Unselects all dates
156
| Chapter 7
You can also select Last to indicate the final day of the month. The last day of the month may be the 28th, 29th, 30th, or 31st, depending on the month and if the year is a leap year. By default, all dates are selected when the Schedule Period dialog is opened.
The WeekDay of Month and Day of Month selections must overlap in order for a day to be selected. For example, Example 1 of the previous step shows the first and third Mondays of each month selected. Because these days fall on a different date each month, the selected Days of Month would have to include the 1st through 22nd in order to make sure the first and third Mondays fell on selected dates. In Example 2 of the previous step, the selected Days of Month would have to include the 22nd through the 31st to ensure the last Saturday fell on a selected date. 10. Select the Month to be included. There are seven pre-defined sets of months: First Quarter January through March Second Quarter April through June Third Quarter July through September Fourth Quarter October through December Select All All twelve months Toggle Selection Selects the months that are currently not selected, and unselects the selected months Unselect Unselects all months
In the following example, January, February and March are selected.
11. When the inclusion period is completely defined, click OK. The Schedule Period dialog closes and the Schedule Editor displays. 12. If it is necessary to define an exclusion period, click the Create button in the lower toolbar in the Schedule Editor dialog. Then repeat this procedure from step 7 to step 11, selecting the times, days, dates and months that the schedule should not include. For example, to create a schedule of 9:00 AM to 11:59 AM and 1:00 PM to 4:59 PM, you can define an inclusion period of 9:00 AM to 4:59 PM, then add an exclusion period of 12:00 PM to 12:59 PM. 13. In the Schedule Editor, click OK. The Schedule Editor closes and the Schedules from Agent or Schedules from Repository dialog appears, with the name of the new schedule listed. At this point the schedule definition is stored in cache on the current machine. 14. In the Schedules from Agent or Schedules from Repository dialog, click Apply Changes. This updates the Schedules on the corresponding agent or in the Repository. When the Schedules is updated on the Agent, the schedule will take effect immediately.
Creating Period Groups

Period groups are useful when you use a set of periods regularly in defining schedules. It also eases the maintenance of those schedules because you can make a change in the period group and have it automatically reflected in all the schedules that use it. For example, you can create a period group for Holidays and use it in any schedule that is affected by holidays, such as a work schedule or a delivery schedule. If any holidays change or are added throughout the year, you only need to update the Holidays period group. All schedules that use the Holidays period group will get the updated list of holidays.
158
| Chapter 7
Period groups can be added to an inclusion or exclusion period. When used in the inclusion or exclusion period, a period group is in-schedule only if all of its periods are in-schedule. Otherwise, a period group is out-of-schedule. When a period group is added to the list, the periods in the period group are listed indented below the period group name in the list. The period group in the inclusion or exclusion list cannot be derived but can be edited or deleted from list. Periods in a period group in the list cannot be added or be deleted. 1. In the Schedules from Agent or Schedules from Repository dialog, click the Period Groups tab to display the current period groups.
2. Click Create to create a new period group. Alternatively, to edit an existing period group, doubleclick on a name in the list or select the name and c lick Modify. The Period Group Editor displays:
3. Click in the Name field and type a name for the period group, such as Holidays. This name must be unique within the Period Group list and cannot contain spaces.
4. Click Create. The Schedule Period dialog opens, as described in Creating Schedules on page 149.
160
| Chapter 7
5. Set the schedule of the first item in the period group. For example, you might set Whole Day; 1st Sun-Sat; 1 - 7; Jan to schedule every January 1. Click OK when you are finished. For a schedule to be valid, you must select at least one item in each inclusion category: Time of Day, WeekDay of Week, Day of Month, and Month. If one category is left undefined, the schedule is not used. The Period Group Editor contains the first scheduled item, such as:
6. In the Period Group Editor, click Create again to create the next scheduled item. Continue until all scheduled items are created. For example, if you are creating a Holidays period group, the list may look like this:
7. Click OK. The Period Group Editor closes and the Schedules from Agent or Schedules from Repository dialog appears, with the name of the new period group listed. At this point the period group definition is stored in cache on the current machine. 8. In the Schedules from Agent or Schedules from Repository dialog, click Apply Changes. This applies the period group to the current agent and allows you to use it.
9. To apply the period group to a schedule, display the existing schedules by clicking the Schedules tab.
162
| Chapter 7
10. Doubleclick on a schedule to display the Schedule Editor for that schedule. Note that the Add Period Group option is now available.
11. Include or exclude the period group: To include the period group in the existing schedule, click the Add Period Group button on the upper toolbar. To exclude the period group, click the Add Period Group button on the lower toolbar. In this example, the period group Holidays is excluded from the WorkSchedule schedule.
12. Select the appropriate period group from the Select Period Group dialog and click Add.
13. The period group is added to the existing schedules in the Include Periods or Exclude Periods frame. The scheduled items in the period group are indented under the period group name. In this example, the scheduled items in the
164
| Chapter 7
Holidays period group are listed under the name Holidays in the Exclude Periods frame. The existing 2-week exclusion period in June is retained.
14. In the Schedule Editor, click OK. The Schedule Editor closes and the Schedules from Agent or Schedules from Repository dialog appears. At this point the changes to the schedule definition are stored in cache on the current machine. 15. In the Schedules from Agent or Schedules from Repository dialog, click Apply Changes. This applies the schedule change.
Testing Schedules
After creating a schedule, you can test it dynamically before applying it to rulebase objects. Testing allows you to specify a time and date, then determine which schedules are in-schedule or out-of-schedule at that particular time. To test a schedule: 1. Select Schedules>Test Schedules.
The Test Schedule dialog displays:
2. Select the name of a schedule to test from the dropdown list. By default, all schedules are tested. 3. Type a date to test in the Date field. The test will indicate whether each schedule is in-schedule on the selected date. The format is mm/dd/yyyy and the default value is the current date. 4. Type a time to test in the Time field. The test will indicate whether each schedule is in-schedule at the selected time. The time is in a 24-hour format of hh:mm where hh is 00 to 24 and the default value is the current time. 5. Click Test.
166
| Chapter 7
The Test Schedule dialog displays the results of the test. Schedules that will be in-schedule at the specified date and time are marked with a check in the In column as shown:
The example above indicates that on Thursday, March 25, 2003, at 13:30, two schedules (Spring and WorkSchedule) are in-schedule, meaning any rulebases that use those schedules will be active on that date and time. The schedules November, Saturdays and Weekends are out-of-schedule, meaning any rulebases that use those schedules will not be active on March 25, 2003 at 13:30. 6. Click Close to close the Test Schedule dialog.
Applying Schedules to Rulebase Objects

After defining a schedule in the Schedule Editor dialog, you can apply it to any rule, test or action in a rulebase. Rulebase objects are related through a hierarchy, so a schedule you apply to one object also affects objects below it in the hierarchy. For example, when you apply a schedule to a rulebase, its inclusion and exclusion periods affect all rules, tests and actions defined in that rulebase. You apply schedules in the Advanced Rulebase, Rule, Test and Action editors. This example shows how to apply a schedule to a test. To apply a schedule to a test: 1. In the Test Editor, click Advanced.
The Advanced Test Editor dialog displays:
2. Click the Use schedule radio button, and select a schedule name from the dropdown list. The dropdown list includes all schedules defined for this agent. It also contains entries for specifying the inverse of an existing schedule. For example, if you defined Schedule1, then both Schedule1 and !Schedule1 are options in the list. 3. Click OK. The test is configured to use inclusion and exclusion periods defined in the schedule.
168
| Chapter 7
Working with Schedule Files

This section discusses the following tasks: Saving a Schedule File, page 168 Distributing Schedules, page 168 Loading Schedules From a File, page 169 Importing Schedules, page 170 Viewing Schedule Properties, page 171
All tasks in this section begin in the Schedules From Agent dialog. For instructions on accessing this dialog, see page 149.
Saving a Schedule File

All schedules used by an agent are stored together in a single configuration file, Schedules.hsf. This file is saved in either a configuration directory or in the Repository. To save a new or modified schedule in Schedules.hsf: 1. Click the name of the schedule to save and select File>Save to File. The Save Schedule dialog displays. 2. Browse to the location of your Schedules.hsf file, then click Save. The current schedule is added to your existing Schedules.hsf file.
Distributing Schedules
Typically, you work with schedules on an agent or in a Repository, then send all schedules to other agents and Repositories on the network. Since schedules are stored together in a single file, you distribute all schedules in a single operation. To distribute all schedules on an agent: 1. Select Schedules>Send To, or click the Send To toolbar button.
Working with Schedule Files 169
The Distribute Schedules To dialog displays:
2. Double-click containers in the dialog until the destination agent or Repository displays. 3. Click one or more destination agents or Repositories. Use the Shift and Control keys to select multiple items. 4. Click OK. A status dialog displays:
Loading Schedules From a File

You can load a set of schedules stored in a schedule file. Loading schedules from a file is useful for editing a stored set of schedules, or for distributing schedules that were previously backed up from an agent or Repository. To load schedules from a file: 1. Select File>Load from File. The File dialog displays. 2. Browse to the location of your Schedules.hsf file, then click Open. The set of schedules defined in the specified Schedules.hsf file is opened in TIBCO Hawk Display for editing.
170
| Chapter 7
You can replace existing schedules on an agent or in a Repository with the set loaded from a file. This allows you to manually to refresh changes without restarting an agent. To replace schedules on the current agent or in the current Repository, click Apply Changes. To replace schedules on a different agent or Repository, click Send To. For instructions, see Distributing Schedules on page 168.
Importing Schedules
When you send schedules, any existing schedules on the destination agent or in the destination Repository are overwritten. You can also import schedules from a schedule file. Importing gives you the option to merge or replace schedules with the same name. A new set of schedules is created, and can be sent to an agent or Repository, or saved to a file. For example, you can get schedules from a Repository, import schedules from a file, then send the new set of schedules back to the Repository. If schedules with unique names exist in the file, they are added to the new set of schedules. Any schedules in the Repository with unique names are preserved. To import schedules from a schedule file: 1. Select Schedules>Import Schedules. The Open dialog displays. You can import local files and files on mapped or mounted network drives. 2. Browse to the location of the Schedules.hsf file to import, then click Open. If a schedule to import has the same name as an existing schedule in the current set, the following prompt displays:
3. Click Yes to replace the current schedule or Yes All to replace all same-named schedules with those in the imported file. Click No to preserve the current schedule, or No All to preserve all existing schedules and import only schedules with unique names.
Working with Schedule Files 171
4. To save schedule changes, do one of the following: Click Apply Changes to replace the original schedules retrieved from a file, agent or Repository with the new set of schedules. Click Send To to send the new set of schedules to an agent or Repository on the network. For instructions, see page 132.
Viewing Schedule Properties

You can view property information for schedules in a Repository or loaded on an agent. To view schedule properties: 1. Select Schedules>Property from the menu. The Schedules Properties dialog displays:
This dialog displays information about when the schedule was created and last modified. It also contains a field for optional descriptive text. 2. Click OK.
172
| Chapter 7
Automating Rulebase Management

Using the following methods you can automate the volume of monitoring activity at any time:
RuleBaseEngine:loadRuleBase() RuleBaseEngine:loadRuleBaseFromFile() RuleBaseEngine:unloadRuleBase()
These methods allow you to create management rulebases that operate above other rulebases. For detailed method descriptions, see the TIBCO Hawk Methods Reference. For example, an important application that requires monitoring runs only on demand. One rulebase monitors the application, then a management rulebase controls when the first rulebase is loaded and unloaded. The management rulebase contains one rule that uses the instance count for the application process as its data source. The test checks for at least one instance of the application process. If the process exists, a Method action loads the rulebase that monitors the application. When no instances of the application exist, this test evaluates to false and a clear action unloads the monitoring rulebase. You could also create a rulebase called General and build routine rules to check on disk space, CPU utilization, collision rates on network interface cards, and so on. When a serious condition occurs, one of the rules in the general rulebase loads a rulebase called Extreme_Network_Analysis. This rulebase tests more frequently, explains in more detail, and applies more severe consequences to the serious condition. This rulebase could be developed by a network expert and may start up detection tools to perform detailed analysis. Running this extreme analysis rulebase even when no problem exists would generate an unnecessary amount of network traffic. However, during a crisis it provides the logic and information needed to resolve the problem. When the dangerous condition is over, the general health rulebase can unload the extreme analysis rulebase and return the monitoring level to normal.
| 173
Chapter 8
Planning Your Monitoring Strategy
This chapter describes how to analyze situations on your network that could be monitored using TIBCO Hawk software. It also explains how to translate monitoring requirements into elements of a TIBCO Hawk rulebase.
Topics
Overview, page 174 Define Problem Areas, page 175 Translate Requirements, page 178 Formulate Rules, page 180
174
| Chapter 8
Overview
This chapter helps you identify the ways TIBCO Hawk software can help monitor and manage your distributed systems and applications. To create a monitoring strategy, you need to identify the potential sources of problems and analyze how they can be prevented. Most monitoring tasks can be automated, but you must identify the unique situations that occur on your network. If you are new to monitoring, this chapter will help you define a strategy. If you already have a monitoring strategy, reading this chapter will help you refine it.
Define Problem Areas 175
Define Problem Areas

The first step in any monitoring strategy is to consider issues with resource contention or other problems that have occurred in the past. Make a list of questions you would like to answer about your network systems and applications, problems you would like to solve, and situations you would like to avoid. For example: Be notified when an internal application metric exposed through AMI is in a problem state. Be notified when critical processes fail or consume too many system resources, such as memory or CPU cycles. Be notified when disk space is low, or when it is decreasing at some critical rate. Gain more control over processes that slow down the system. Avoid multiple servers going down on the same day. Be notified when important messages appear in log files or event logs.
When the list is complete, assign a priority to each item. Decide which improvements provide the greatest benefit to your enterprise, then rank items in order of importance.
Define Information Requirements

For each item you choose to focus on, define the information that is required to answer the question, solve the problem, or avoid the situation. For example, to gain more control over processes that slow the system, you might track the number of processes are running on each server, or measure system response time.
Identify Corrective Actions

Identify actions that could fix or avoid the problems you defined. If the problem is slow servers, for example, a corrective action might be Terminate redundant or low-priority processes.
176
| Chapter 8
Map Information Requirements

The next step is to map information requirements to microagent methods. Evaluate TIBCO Hawk microagent methods and their results, both platform-independent and platform-specific. Consider methods that return data: IMPACT_INFO and IMPACT_ACTION_INFO. Often analogous methods for each operating system return similar information. If possible, match each information need to a microagent method result field. A key requirement is that you specify one information source per item. You might also need to redefine questions or conditions to fit available options. For example, to solve the problem of the system running slowly, choose the most appropriate metric: CPU utilization, file reads per minute, or the number of simultaneously running processes. Usually one source provides the best answer. If multiple operating systems exist on your network, a separate mapping might be required for each operating system. If a piece of information is not provided by default TIBCO Hawk microagents, look for alternate ways of providing the information to a TIBCO Hawk agent through an AMI gateway to an application, or by retrieving data from custom scripts. If a third-party application is business-critical, consider instrumenting it using the TIBCO Hawk Application Management Interface (AMI).
Map Action Requirements

After information requirements are fulfilled by microagent methods, you map action requirements to microagent methods. Consider TIBCO Hawk microagent methods of type IMPACT_ACTION or IMPACT_ACTION_INFO to learn about available actions. If possible, map each required action to a microagent method. If an action cannot be performed by TIBCO Hawk action methods, look for alternate ways to perform it. You can call custom executables or reach directly into an application using AMI (or by writing an AMI gateway to an application). At this point, you can also define practical meanings for low, medium and high alert levels. For example, high-level alerts might be reserved for actions that require intervention by the system administrator, or for maintenance tasks that take more than 30 minutes to complete.
Define Problem Areas 177
Refine Corrective Actions

Define timing and circumstances for corrective actions. Define when a question needs to be answered or a problem solved. How often and under what circumstances does a solution need to occur? What are the potential causes of the problem? How quickly does the information change? Does it build over hours, or happen all at once? How often does it happen? What are the symptoms? Is there a fault-tolerant backup for a critical application? Define when a problem is considered resolved. Define a resolution for each problem: what signals that balance is restored? What is adequate? What is normal?
178
| Chapter 8
Translate Requirements
After monitoring requirements are defined, you can translate them into TIBCO Hawk terms. For each item, create a mapping table with a structure similar to the following table. To find TIBCO Hawk equivalents, refer to the TIBCO Hawk Methods Reference, and consult task and action tables in Chapter 4, Monitoring with Rulebases. Table 10 Mapping Table Column
Information to gather
Sample Contents
The microagent and method to invoke, the script or command to execute, a manual procedure, or the AMI method to call. Include any arguments the method requires and any return values. Include all means of solving the problem. Every sixty seconds, or whenever a log file entry is made, or whenever a message is received from a managed application through AMI. When the disk space falls below ten percent, when the server load is twice normal, when the AMI message contains the word "error". If multiple circumstances apply, include them all.
How often to gather the information Conditions that define the question, problem, or situation Actions for TIBCO Hawk to take
Raising an alert, calling a microagent method, executing a script that pages the system administrator, triggering an email action, modifying an application through its management interface. Include all actions you want to take. When the value returns inside a reasonable range, when the error message no longer exists (for how long?), when the instrumented application returns an acceptable value.
When resolution occurs
Transform to Rule Elements

Transform the table entries into TIBCO Hawk rule elements using the following equivalents: Information a microagent, method and arguments in a rules data source How often a data delivery interval in a rules data source Conditions each test in a rule Actions each tests actions
Translate Requirements 179
Resolution how a test is cleared (a clear test or other option)
Use the default rulebases supplied with the TIBCO Hawk software as examples. You can also copy these rulebases to use as the basis for new rules. A data source includes a microagent method, its arguments, and a data delivery interval (for synchronous methods). The data source is used for all tests and actions in the rule. Since the first field in your table corresponds to a microagent method and the second field corresponds to a data delivery interval, all items in the list with the same entries in the first and second columns can be grouped together in the same rule. Some items in the list might become tests in a common rule. For example, items that depend on the same "under what circumstances" information could be separate actions in the same test.
Plan Rulebases
Analyze your monitoring rules, tests and actions, then group them into sets based on function or location. For example, group together rules that: Monitor a particular application Perform a particular system function, such as process management Monitor separate operating systems into one set for each operating system
Following these guidelines is particularly important for taking advantage of Rulebase View. For more information, see Working with Rulebase View on page 31. Rules that remain after others are grouped into sets might belong to a base set for all agents. For identification purposes, rulebase names should reflect the functions they perform.
180
| Chapter 8
Formulate Rules
With requirements defined and translated into TIBCO Hawk equivalents, you can encapsulate monitoring logic in TIBCO Hawk rulebases.
Build and Test Rules

In TIBCO Hawk Display, create a new rulebase and then build each rule with a data source, tests and actions. If overlap exists between your requirements and default TIBCO Hawk rulebases, try copying and modifying an existing rulebase. Consider simulating the situation in a test, such as starting several copies of a process and observing a TIBCO Hawk agent terminate all but one process. Use this technique to verify that the rule performs as planned. Another way to test rules is to use network query and action and invoke methods that imitate the action of the rule. For more information, see Chapter 5, Managing Your Configuration.
Refine Rules
After rulebases are built and performing roughly as designed, you can fine-tune them as follows: Increase rule efficiency by considering ways to faster and better respond to monitored conditions. Advanced testing and action options might be more efficient. Consider using different metrics, or changing thresholds. Maximize the information content of messages by using variable substitution to add information from a data source to your alerts and notifications. Consider other monitoring options such as building your own scripts, or instrumenting an application with an AMI interface. Increase the automation of your monitoring effort as you see possibilities to automate tasks you now do yourself. For example, using escalation to automate a scaled response to a continuing problem can eliminate the need for intervention. Adding a true test counter to a test can reduce the number of false alarms.
Formulate Rules 181
Use Alternate Methods

You might already have developed scripts or executable programs that monitor critical functions. You can incorporate these programs into your TIBCO Hawk environment using the execute, executeForNumber() and executeForString() methods of the Custom microagent. Examine your current monitoring solution to identify tasks that can be fully automated using TIBCO Hawk software. Some monitoring tasks performed by scripts may be easier to perform using TIBCO Hawk agents and rulebases. For example, if you use a script that checks for process existence on a UNIX system, the script probably executes the ps command every so often. Using the Process microagent is a more efficient way to do this because it does not have to start a new process each time the process table is checked.
182
| Chapter 8
| 183
Chapter 9
Performing Common Monitoring Tasks
This chapter describes how to apply TIBCO Hawk features in a practical environment and contains strategies for performing some of the most common monitoring tasks.
Topics
Monitoring Process Resource Consumption, page 187 Monitoring File System Space, page 189 Monitoring System Resources, page 191 Monitoring Log Files, page 192 Monitoring with Custom Scripts, page 196 Monitoring AMI Applications, page 199
184
| Chapter 9
Monitoring Process Existence

Monitoring the existence of a process might be the most important type of application-level monitoring activity, especially when a business relies on the continuous operation of one or more critical applications. You could build a test that checks if a named process exists, but a more useful type of test could count the number of process instances that are running. This type of test detects not only if a process has stopped but also if too many instances are running. To determine the current number of instances of a uniquely-named process, invoke a microagent method that returns process count with the name of the process passed as an argument. For example, to count how many instances of the TIBCO Rendezvous daemon are running, specify rvd as the argument to the method. To retrieve the number of process instances: Microsoft Windows: Use the Performance microagent and the ProcessCount() method with the name of the process as an argument, and check the Instance Count result field. You can also use the following UNIX procedure: UNIX: Use the Process microagent and the getInstanceCount() method, and check the Process Count result field.
When specifying the data collection interval for the microagent method, consider the relative importance of the process. If the specified process is not running, a zero value is returned. You can automate process existence monitoring by building a rule with the following tests: 1. Restart the process if the number of instances is zero. 2. Terminate redundant processes if the number of instances is greater than one. Other methods, such as Performance:Process() on the Microsoft Windows platform and Process:getProcess() on UNIX also retrieve process information. However, these methods are restricted to information on running processes. For example, if you call the Process:getProcess() method with the argument anApp, and no applications with the process name anApp are running, the method returns no data.
Identifying Same-Named Processes

If processes have the same name, additional steps are required to distinguish process instances. To uniquely identify an instance of a running process, do one of the following:
Monitoring Process Existence 185
For Java processes started with a script, specify the -D argument to tag the process name. For example:
jre -DTIBHawk=agent
This syntax labels the jre process as a TIBCO Hawk agent process. Specifying this option does not affect the ability of the tagged process to run. In TIBCO Hawk Display, you can then use the Process microagent and getInstanceCountbyCommand() method to test for a command name that includes the string specified as a tag or label. If multiple processes are started with different command line options, use the method and pass the name of the command used to start the process as an argument. Then use REGEXP to match a command-line option or other unique pattern in the command name.
Process:getInstanceCountbyCommand()
If many command line arguments were used, specify Process:getProcess() and build a compound test that checks the command name for option switch combinations, such as:
If (((Command Contains -a) AND (Command Contains -b) AND (Command Contains -c)))
If the application is instrumented with an AMI interface, use the method Self:getMicroAgentInfo() and specify the internal application name used in AMI description methods as an argument. The Count field of the result shows how many instances of the application are communicating with the TIBCO Hawk agent.
After uniquely identifying the instance, you can use a posted condition to count the number of running instances.
Using Posted Conditions to Monitor Same-Named Processes

This section shows how to use a posted condition to count running processes with identical names. Most microagent methods that count processes require the name of the process as an argument. REGEXP pattern matching syntax might not be sufficient to uniquely identify processes with the same name. In this case, use a test expression to identify the process instance and create a posted condition. A second test evaluates the posted condition as a process count. For more information, Using Posted Conditions on page 146. The following example counts instances of a Java process that has been tagged using the -D startup option. However, to identify the process you could use any of the procedures listed on page 184.
186
| Chapter 9
In a rule that uses a posted condition to count process instances, the data source could be any method that returns process name. The following method, getProcess(Process Name=jre.exe):60 checks for a process named jre.exe every 60 seconds. A test expression could check for instances of the jre process with the label MB=Example. For example:
If (Command Contains DMB=Example)
When the test evaluates to true, a Post Condition action type is performed. Specify a name for the posted condition that is unique in the current rulebase. An action that posts a condition named Java_Example has the following syntax:
Then postCondition(conditionName=${Posted.Java_Example})
In this rule, the posted condition value acts as a counter for the number of running processes labeled MB=Example. The value is incremented each time this test evaluates to true. If the value is zero, no process labeled MB=Example exists. After the action is performed, the next step is to check the value of the posted condition with a test in the same rulebase. Since no input from a data source is required, use the Self:getUbptime microagent method as a token data source. Every 60 seconds, this method triggers a test that gets the value of the posted condition. For example, a test expression that checks a posted condition for process existence might look like the following:
If (${Posted.Java_Example}==0)
An action could send a high-level alert message to notify the system administrator and then execute a restart script. To perform these tasks, the test that checks the posted condition might include the following action syntax:
Then sendAlertHigh(alertMsg=MB Example is not running. Trying restart...) execute(command=engine.bat -n Example example_sheet.mb
Monitoring Process Resource Consumption 187
Monitoring Process Resource Consumption

There are many reasons to monitor the amount of computer resources used by a particular process, including: Preventing system slowdowns by identifying resource gluttons and identifying ways to reduce their resource usage. Flagging system-stressing applications such as those printing very large files or running demanding batch processes during peak business hours. Testing for memory leaks in applications under development. Scheduling backups and batch processes when they will impact users the least.
The Performance:Process() method on the Microsoft Windows platform, and the Process:getProcess() method on UNIX give you information about each running process. Monitoring processes for Java applications requires several additional steps. For more information, see Overview on page 174. To test for memory usage by a process: Microsoft Windows: Use the Performance microagent and the Process() method, and check the Virtual Bytes or Working Set result field. UNIX: Use the Process microagent and the getProcess() method, and check the Virtual KBytes or %Memory result field.
To test for CPU usage by a process: Microsoft Windows: Use the Performance microagent and the Process() method, and check the %Processor Time result field. UNIX: Use the Process microagent and the getProcess() method, and check the %CPU result field.
For more information on the result fields returned by the and Process:getProcess() methods, see the TIBCO Hawk Methods Reference and the reference documentation for your operating system.
Performance:Process()
Automating Process Resource Consumption Monitoring

To automate monitoring of process resource consumption, create a test based on a numeric threshold of memory or CPU cycles. For example, you might create a rule that tests if an application uses more than 10 or 20 megabytes of memory. This condition might indicate a memory leak, and you might want to restart the application.
188
| Chapter 9
You could also test to determine if any process (except the system idle process) consumes more than 50 percent of the CPU time. When this condition occurs, you could send an alert message to TIBCO Hawk Display, and if the process continues to consume too much CPU time you could escalate to another action. To monitor resources consumed by Java processes or other processes with identical names, build a compound test. Use Process:getProcess() as the rule data source with the name of the process passed as an argument. The test might look like the following:
If ((Command equals <processname>) and (Virtual KBytes>10000))
Monitoring File System Space 189
Monitoring File System Space

In terms of priority, monitoring file space is only slightly less important than monitoring the smooth operation of crucial applications. Without enough free file space, few applications are able to work as planned. To test for free disk space: Microsoft Windows: Use the Performance microagent and the LogicalDisk() method, and check the % Free Space or Free Megabytes result field. The PhysicalDisk() method does not return free disk space because it may differ for partitions within a physical drive. UNIX: Use the Filesystem microagent and the getByPartition() or getByMountPoint() method, and check the % Free or KBytes Free result field. The getByPartition() and getByMountPoint() methods return the same information, but differ in the argument you specify to get information for one file system. To determine mount points and partitions on the file system you want to monitor, invoke the microagent method with no arguments. This retrieves mount point information. In the Mount Point result field, find the file system you want to monitor and use the mount point information provided.
Tips on Monitoring File System Space

The microagent methods described in this section gather information about a file system on the machine where they are invoked. You can also gather information about the file system on a remote machine by performing a network query. For more information, see Performing Network Queries on page 206. To automate monitoring tasks, you can place a rulebase on the remote machine with rules for monitoring the state of the file system. Using TIBCO Hawk Display, you can edit and manage this rulebase from anywhere in the network, but it must reside on the remote machine.
Automating File System Space Monitoring

You can measure the amount of free space on a file system to detect several different conditions. If the data source of a rule retrieves the amount of free disk space, you could check for each condition in a separate test. For example: Threshold value. If the amount of free disk space is below a critical value, a test might include actions that free up space as well as actions that raise alerts.
190
| Chapter 9
You could create a series of tests with different thresholds that respond more and more strongly to the situation. Significant change. If the amount of free disk space has dropped significantly since the last test evaluation, look for a destructive process. For example, you could use the test operator %Decrease, to check for a decrease in free space greater than 10 percent between two test evaluations. If the amount of free disk space has gone up significantly since the last test evaluation, it could indicate a serious system malfunction or an unauthorized user deleting files. Use the %Increase test operator on a data source that provides information on free disk space to detect this type of change.
Monitoring System Resources 191
Monitoring System Resources

Two useful system metrics for monitoring system resources are CPU utilization and free memory. If either of these metrics is compromised, the system is probably not running optimally and requires attention. To monitor CPU utilization: Microsoft Windows: Use the Performance microagent and the System method, and check the %Total Processor Time result field. UNIX: Use the System microagent and the getCpuInfo method, and check the % System Time or % User Time result field. You could also check the % Time Idle field for low values.
To monitor overall memory usage: Microsoft Windows: Use the Performance microagent and the Memory method, and check the Committed Bytes or % Committed Bytes in Use result field. To check swap file usage, use the Performance:Paging File() method and check the % Usage and % Usage Peak result fields. UNIX: Use the System:getSwapInfo method and check the % test for swap file usage.
Used
field to
Automating System Resource Monitoring

CPU usage and memory usage tend to exhibit different behaviors, requiring slightly different strategies to automate their monitoring. CPU usage tends to fluctuate widely as processes demand power to carry out tasks then release it later. You should try to avoid false alarms from short spikes in CPU usage and build tests that respond only to prolonged surges. To circumvent false alarms, implement a true test counter. For more information, see Using Advanced Test Features on page 78. Memory usage tends to grow as it fluctuates, especially when many applications are running on a system. For example: If a process leaks memory the problem will deteriorate over time. Users can start multiple processes and leave them running. Processes can spawn other processes and neglect to terminate them. To automate memory monitoring, a series of actions that respond to dwindling free memory is the best solution.
192
| Chapter 9
Monitoring Log Files

Reading log files is a convenient way to access information from applications that do not provide APIs or other tools for integration. In the TIBCO Hawk system you access log files by calling the Logfile microagent method onNewLine(), then passing the onNewLine() method the name of the log file you want to track. This microagent exists for all platforms. The onNewLine method returns a text string as each new line is appended to the log file. Create the log file before you specify it in the method. If the log file does not exist, an error is generated. You can test the onNewLine() method by repeatedly typing a command-line echo statement that appends a line to a text file. Microsoft Windows: Open a DOS window and execute the following command:
C:\> echo "sample text" >> c:\temp\test.log
UNIX: Type the following command:

%> echo "sample text" >> /tmp/test.log
Execute this command once, then start a subscription to Logfile:onNewLine(). Now you can toggle between the command window and Subscription Results dialog in TIBCO Hawk Display. Each time you execute the command manually, the new line is displayed in TIBCO Hawk Display. This exercise demonstrates how an agent can access application-generated log file entries.
Avoid Line Feed Characters
If TIBCO Hawk alert or notification messages contain line feed characters, a log file parser will not be able to properly evaluate the TIBCO Hawk Event Service file, Event.dat. The line feed characters are usually derived from parameter variable substitution from the following microagents:
Logfile:onNewLine ${nextLine} Custom::executeForString|Number, ${returnString|Number}
Avoid using line feed characters in alert or notification messages. If line feed characters cannot be avoided, use the Console API to evaluate alerts and notifications containing line-feeds. You can also use the Hawk 4.1 Event Service microagents in lieu of directly reading Event.dat.
Tips on Monitoring Log File Entries

You can use both external and internal variables to specify the log file to monitor.
Monitoring Log Files 193
When using external variables, if the -variables file for an agent contains the entry LOGDIR=/usr/logs, and you specify:
${External LOGDIR}/xyz.log
as the name of the log file, the agent will resolve the path to:
/usr/logs/xyz.log
For more information on using external variables in a rulebase, see Referencing External Variables on page 139. Internal variables can be used in a similar fashion. For example, if the name of the Microsoft Windows host machine where the agent runs is protege and you specify the name of the log file as
C:\${Internal. Agent Name}.log
the agent will resolve the path to :

C:\protege.log
For more information on using internal variables in a rulebase, see Referencing Internal Variables on page 140. You can use embedded back-quoted strings to specify the logfile to monitor. The agent will execute the command in the back-quoted string and use the resulting string to evaluate the logfile name. If you specify the logfile name as:
/opt/tibco/logs/application.`date +%m%d%y`.log
the agent will resolve the path to

/opt/tibco/logs/application.111500.log
The agent will re-evaluate these expressions every 300 seconds by default. The -evalRate parameter for the agent can be used to modify this value. You can use the Logfile:reEvaluateLogFileNames() method to force the agent to re-evaluate all the log file names that it is currently monitoring. The agent will generate DataSource errors if it is unable to evaluate the value of the back-quoted string. For more information on -evalRate and the other logfile microagent parameters parameter, see TIBCO Hawk Installation and Configuration. The Logfile:onNewLine() method can read rolling log files. When an application writes rolling log files, it fills a series of files with logs, rolling the oldest file out of the queue when the current file is filled. The onNewLine method can track a series of files used in this manner, as long as the file in current use always has the same name. For more information, see Viewing Rolling Log Files on page 259. When monitoring log files with data or process ID values appended to the file name, soft link the actual name to a fixed name and specify the fixed name as the name argument in Logfile:onNewLine().
194
| Chapter 9
Automating Log File Monitoring

Since the Logfile:onNewLine() method is asynchronous, a TIBCO Hawk agent can receive additions to a log file and respond to them in real time. You can test for conditions in a log file line by searching through the text of the line for words such as "error," "repeated login failures," or "not responding." If an important word or phrase is found, the test can include an action that passes on the line text as an alert text (by using the variable substitution ${nextLine}). You can also take other actions, such as notifying a system administrator. If a log file entry is created when a problem is resolved as well as when it occurs, you can use a clear test to clear the original alert message. For example, a market data feed handler might produce a message "Line Down" and another message "Line Up." A client application might log a lost connection to its server with a "Connection Lost" entry and when the connection is reestablished a "Connection Established" entry is created. Since a clear timer of 900 seconds (15 minutes) is the default clear condition for asynchronous data sources, 15 minutes could elapse before you are notified that the problem has been resolved. Using a clear test to respond to the stand-down log entry eliminates this delay.
Monitoring With Pattern Files

The Logfile:onNewLineWithPatternFile allows you to specify a pattern file to use while monitoring a specified log file. Each line in the pattern file contains a severity level and a pattern specified using the Perl5PatternMatch syntax. A negative severity level means that all lines that match the pattern can be ignored. All other severity levels (positive and 0) indicate that the lines that match the corresponding pattern are of interest. For more information on using the Perl5PatternMatch syntax, see Perl5PatternMatch Syntax on page 248. When a new entry is added to the logfile being monitored, the Logfile:onNewLineWithPatternFile method will attempt to find a match by comparing it sequentially to every pattern in the pattern file. If a matching pattern is found and if the associated severity level is not negative, the logfile entry along with the severity level and the matched pattern is returned to the rule subscribing to this data source. If a matching pattern is not found the logfile entry, a severity level of 0, and an empty pattern is passed to the rule.
About Rolling Log Files

The Logfile microagent can monitor rolling log files. An application using rolling log files writes its log messages to a log file. You pass the name of the log file as an argument to the Logfile:onNewLine() method in a rules data source. While a rule with this data source is active, the TIBCO Hawk agent detects additions to the named file.
Monitoring Log Files 195
If the application writing the log file reaches a file size threshold, it usually proceeds in one of the following ways: The application copies the contents of the named file to another file and empties out the named file. For example, the contents of myapp.log are copied to myapp1.log, and the next log file entry is written over the existing contents of myapp.log, truncating the file. Note: Because of file blocking restrictions, this method is particularly recommended for agents running on Microsoft Windows. The application renames the file and create a new, empty file with the same name. For example, myapp.log is renamed to myapp1.log, and a new myapp.log is created.
In either case, the current file suddenly decreases in size, usually down to one line. The TIBCO Hawk agent detects the change and assumes that all lines in the named file are now new log records, which it reads and processes according to rule logic.
196
| Chapter 9
Monitoring with Custom Scripts

If you work in a UNIX environment you probably have many scripts files that contain commands to execute. If you work in Microsoft Windows environment you probably have many batch files that perform similar tasks. With TIBCO Hawk software, you can call scripts and retrieve a string or number using the Custom microagent. The Custom microagent is identical on all platforms and has the following methods: The execute() method calls the named script and ignores any output. This method is normally used for actions. The executeForString() method calls the named script and returns a string with the field name resultString. If your script returns multiple lines, the TIBCO Hawk agent concatenates the lines into a single string. This method is normally used as a data source for a rule. The executeForNumber() method calls the named script and returns both a double (resultDouble) and an integer (resultInteger). Your script can only return one number: either an integer or a floating-point number. Any extra numbers returned will cause an error. The agent truncates a double to produce the integer value. This method is normally used as a data source for a rule.
You can test Custom microagent behavior by creating the following simple scripts: Microsoft Windows: Create the following batch files:
testReturningString.bat @echo off echo This is a test. testReturningNumber.bat @echo off echo 12.5
UNIX: Create the following scripts (substituting your shell for csh if necessary):
testReturningString.csh #!/bin/csh echo This is a test. testReturningNumber.csh #!/bin/csh echo 12.5
After creating the scripts, start TIBCO Hawk Display and invoke the Custom: executeForNumber() or executeForString() method to call each script. The Invocation Results dialog displays the text or number echoed from the script. You can test further by modifying the scripts and making the invocation again to simulate a changing value. This procedure is also useful for experimenting with rule logic. For more information, see Invoking a Microagent Method on page 49.
Monitoring with Custom Scripts 197
You can call any command-line executable, not just scripts, from your TIBCO Hawk environment. To receive results from an executable application, send the text or number to stdout.
Tips on Monitoring Custom Scripts

All shell scripts called from your TIBCO Hawk environment must define the shell, for example #!/bin/csh. All .bat files called from your TIBCO Hawk environment must begin with the line @echo off to prevent the shell from exiting prematurely. Environment variables are not supported in any of the Custom:execute methods. If you need to use environment variables, define them as External Variables in agent startup options. For more information, see TIBCO Hawk Methods Reference. Executing a long command line using Custom::execute may fail because some operating system shells limit the size of command lines that can be passed to them. The length of command line supported varies by platform. To work around this, put the long command line into a script and call the script from the Custom::execute method. When you call an executable using one of the execute methods of the Custom microagent, you cannot use redirection (|), multiple command (;) or append characters (> and >>). You can create a separate script that includes a command with these characters, then call that script from the microagent method. On Microsoft Windows, you can call a DOS shell command from the Custom:execute(), executeForNumber() and executeForString() methods by adding cmd /c before the argument to the method. For example:
cmd /c "echo hello"
If you call the Custom: executeForString() method with this argument, the invocation results window displays "hello" as the result. If a Custom::execute is performed, the TIBCO Hawk agent does not wait for the return value and the parent process persists in stdout or stderr. These processes do not terminate or time out and eventually use up the system resources. To avoid this, redirect stdout and stderr to NUL. For example: On Microsoft Windows, where 1 is stdout, and 2 is stderr:
c:\<process>.bat 1 > NUL 2 > NUL
On Unix:
<process> > /dev/null
198
| Chapter 9
On UNIX, quoted strings with embedded blanks cannot be passed as command arguments to UNIX shell scripts by means of the Custom::execute, Custom::executeForNumber and Custom::executeForString methods. The Java Virtual Machine (JVM) parses these strings as blank delimited tokens and passes them as separate arguments. To work around this, utilize a shell script as the executable. Pass all arguments that do not contain spaces first. Then use the "shift" shell command and a wildcard argument variable, "$*", to pass the space containing argument at the end.
Automating Custom Script Monitoring

You could use a custom script to monitor data that is stored in a database. The database has no AMI interface and is not represented by the TIBCO Hawk default microagent methods. The script to execute could contain SQL statements for retrieving data, such as messages about system events. The next step is to create a rule with the Custom microagent and the executeForString() method and pass the name of the SQL script as an argument. In the rule you specify a data collection interval of 10 minutes, and in the test, check for returned strings that contain the string Error. An action calls a second script which includes the error message text in an alert message. A custom script called from a rulebase should return as quickly as possible, since it blocks the agent from taking further action while the script is running. If a custom script does not return in 10 seconds, the agent terminates script execution. For scripts that require more than 10 seconds to execute, redirect the output to a log file and monitor the log file using TIBCO Hawk software.
Monitoring AMI Applications 199
Monitoring AMI Applications

Applications instrumented with AMI are represented by microagents on TIBCO Hawk agents. Monitoring your AMI application is very similar to using default microagents, with the following exceptions: The AMI application must be running for you to interact with its microagents or build rules using its method as a data source. Start the AMI application first, so you can interact with it in TIBCO Hawk Display. You can send asynchronous, unsolicited messages from your AMI application to a TIBCO Hawk agent, but you cannot send alerts directly from an AMI application to TIBCO Hawk Display. To generate an alert from an AMI message, build a rule in a rulebase that detects the specific message and raises an alert. Like custom scripts, methods in AMI-instrumented applications that carry out actions should return control to the TIBCO Hawk agent as quickly as possible. To monitor the internal ability of an application to respond to queries, build a rule that monitors the existence of the AMI application microagent. Use the Self:getMicroAgentInfo() method and pass the fully qualified microagent name as an argument. The test should specify Count==0.
For more information on instrumenting applications with AMI, see the TIBCO Hawk Programmers Guide.
200
| Chapter 9
| 201
Chapter 10
Performing Group Operations
This chapter describes how to interrogate and perform tasks on multiple remote TIBCO Hawk agents using TIBCO Hawk Display. It includes information on interrogating microagents over a network, as well as performing network queries and actions.
Topics
Overview, page 202 Interrogating Microagents, page 204 Performing Network Queries, page 206 Performing Network Actions, page 212
202
| Chapter 10
Overview
Group operations allow you to detect and solve problems on the network from any location. Using TIBCO Hawk Display, you can explicitly solicit information from multiple TIBCO Hawk agents, then take action based on the results. Group operations include: Network query querying one or more agents on the network to determine where particular conditions exist. Network query with a test applying a test to query results in the same manner as in a rulebase. Network action performing an action on one or more agents on your network.
Network query and action allow you to combine identical tasks you might perform on individual agents and implement them dynamically in a single operation. The query or action is performed by invoking microagent methods, using multiple instances of the same microagent distributed across the network. Querying several agents can be a useful tool for determining thresholds when building tests in rules. You might first decide to test a potential threshold value through a query before committing the rule to a rulebase. Similarly, using a network action you can experiment with the effects of a particular action. Network query and action are useful both as interactive tools, and for researching and testing how rules should be built. The following table summarizes the different methods you can use to retrieve information and carry out tasks using TIBCO Hawk Display. Table 11 Method to Retrieve Information and Perform Tasks Retrieving Information Now
On One Computer invoke a microagent method
Performing Tasks Now

invoke a microagent method
Over Time
subscribe to a microagent method
Over Time
build a rulebase that takes an action at repeated intervals
Overview 203
Table 11 Method to Retrieve Information and Perform Tasks (Contd) Retrieving Information Now
On Multiple Computers perform a network query
Performing Tasks Now

perform a network action
Over Time
subscribe to microagent methods on multiple agents, or build a rulebase that sends alert messages, distribute it to other agents, and view all of the alerts at once
Over Time
build a rulebase that takes an action at repeated intervals and distribute it to other agents
204
| Chapter 10
Interrogating Microagents
When you interrogate microagents, you invoke a method interactively on any agent on your network and view the result locally in TIBCO Hawk Display. The microagent method can return information, or take an action on an agent or managed application, or both. For example, if you have an application instrumented using the AMI protocol, you can modify the value of writable variables exported by the application. In this example, you invoke a method to get information about a mount point on a remote UNIX machine. Although interrogating microagents is not a group operation, this example illustrates the manual process of invoking microagent methods individually on multiple agents. Network query and network action can replace invoking methods in this manner. The remaining sections in this chapter demonstrate how to perform network queries and network actions. To interrogate a microagent on a TIBCO Hawk agent: 1. In TIBCO Hawk Display, click the icon for the agent you want to interrogate. 2. Right-click on the agent icon and select Get Microagents from the menu. The Microagents, Methods and Arguments dialog displays:
Similar to defining the data source of a rule, requesting information from an agent on a single node requires you to specify a microagent, method, and
Interrogating Microagents 205
optional method argument. The microagent objects reside inside each machine's local agent, and expose methods for performing tasks. 3. Click the File System microagent. This microagent provides access to file system statistics. 4. Click the getBy MountPoint() method. This method provides profile information for one or more mount points on the remote machine. In this example, you retrieve information about all mount points on the remote machine, so the Mount Point field remains blank. You could also specify the name of a remote mount point as an argument and retrieve information for only that point. 5. Click Invoke. 6. Click OK. The results of the method invocation display:
Using this method to interrogate agents on your network is one way to obtain information about disk space usage on remote machines. However, the most efficient way to obtain information from multiple agents is to perform a network query.
206
| Chapter 10
Performing Network Queries

Network query is a powerful feature because you can communicate with multiple TIBCO Hawk agents at one time. By performing a network query, you can ask multiple agents on your network any question you can ask an individual agent. Agents can be grouped by container or by the response to a prior question. The query is broadcast using TIBCO Rendezvous software to every agent on your network, but only specific agents on the target list process the query and respond. A network query has some of the same structural elements as a rule. However, parameters are specified dynamically, not stored in a rulebase. In TIBCO Hawk Display, you specify a data source for the query, which is a microagent method with optional arguments. You can also specify an optional test to filter the result set. Network query tests differ from rulebase tests in the following ways: Tests are optional Only one test per query is allowed A test has no associated actions
For network queries that include a test, compound test syntax can extend its capabilities. For example, after querying a list of agents for a certain condition, you could apply a second condition to refine the list. Using compound test operators, you can specify complex logical criteria. For more information, see Building Compound Tests on page 76. The following example performs a network query by invoking the Performance:LogicalDisk method on a remote agent. It includes a test that checks % Free Space parameter to determine if available disk space is less than or equal to 10% of total disk resources. To query remote agents on the network:
Performing Network Queries 207
1. Select Network>Network Query from the TIBCO Hawk Display menu. The Network Query/Network Action window displays:
2. To add one or more agents to the target list, click Add.
208
| Chapter 10
The Get Hosts From dialog displays a list of discovered agents. Click to expand containers until a list of individual agents displays:
3. Click the agent or container of agents to add as a target, then click OK. The selected agents display in the target list. To add all the agents on your network, click All. The target list displays all currently discovered agents. To remove an agent, click it in the list of targets and click Delete. To remove all the agents from the list, click Clear. 4. In the target list, click the name of an agent that has the microagent you want to use for the query, and verify that the Network Query radio button is selected. Note: Selecting a platform-specific microagent in a multi-platform environment generates an error returned from those agents that do not support that particular microagent. 5. Click Edit next to the Data field. TIBCO Hawk Display looks up microagents and methods for the selected agent, and displays them in the Microagent Descriptors dialog. These descriptors are used as a template for performing the network query. For instructions on using this dialog, see Invoking a Microagent Method on page 49. 6. Click the Performance microagent and LogicalDisk() method, then click OK. The text LogicalDisk(LogicalDisk=) displays in the Data field. This method returns disk usage statistics for the target agents. You can add a test to filter results of the method invocation. To add a test to a network query, click Edit next to the Test field.
The Network Query Test Editor dialog displays. Specify test parameters so that the dialog looks like the following:
A test is applied to microagent method results for every agent in the target list. Like tests in a rule, only a true or false value is returned. This test expression returns all agents where the amount of free disk space is less than or equal to 10 percent. For instructions on building test expressions, see Defining Tests on page 71. Advanced test options, such as clear timers and clear tests, are not supported for group operations. Tests make a network query more efficient, since the reply is small: true or false. For example, to find out about free disk space: The high-impact method is to query all agents for statistics on disk space on all mounted hard drives. The low-impact method is to first issue a query with a test to identify agents where free disk space is less than 10 percent. Then, issue a query with no test to agents that responded with a true value. In this case you retrieve over the network only the few data sets that are significant. 7. Click OK. 8. Click Send Query. While agents are queried, the message Waiting for hosts to reply displays in the status bar. It might take several seconds for all agents in the target list to respond. When this message disappears, the query is complete.
210
| Chapter 10
The results of the network query display in the lower half of the dialog:
The Reply section contains three tabbed panels: Success, Error, and Timeout. The Success panel displays agents that received the query and responded successfully. For network queries with no test, a list of agents responding to the query displays. Click any agent name in the list to view query results. Results can be a simple value or a table with result records (rows) and result fields (columns). The name of the microagent that was invoked is shown above the table of results. For network queries with a test, two lists display: the True Host List contains agents that returned a true value, and the False Host List contains agents that returned a false value. Clicking on an agent name in either list, displays the name of the microagent that was invoked. The Error panel displays agents that could not process the query. Click an agent in the list to view the error text returned. The TimeOut panel displays agents that did not respond, usually due to a network problem.
On any tab, clicking Sort sorts the list of agents by name. Sorting agents by name is useful for navigating a large results list. You can make any agents that replied the subject of a second query or a network action. Under any list of agents in the reply section, clicking Make Targets replaces agents on the target list with the current list of agents. Your next query or action is sent only to those agents. For example, to test a rule before adding it to a rulebase you could make the True Host List into targets, create a network action, and specify the action you expect to take as a result of a true test. 9. Click Done to close the Network Query/Network Action dialog.
212
| Chapter 10
Performing Network Actions

A network action is similar to a network query, except instead of gathering information you specify an action to perform on one or more remote agents. The action can be any task a microagent method of type IMPACT_ACTION or IMPACT_ACTION_INFO can perform. Examples of tasks you might perform as a network action include loading rulebases, starting and stopping processes, or executing custom scripts. Note: Since performing a single network action can have a widespread effect, use this powerful feature with caution. To perform a network action: 1. Follow the steps beginning on page 207 for accessing the Network Query/Network Action dialog and specifying a list of target agents. 2. Click Make Targets to add agents that tested true during the network query to the target list for a network action. 3. In the target list, click the name of the agent with the microagent method to invoke. 4. Click the Network Action radio button. 5. Click Edit next to the Action field. The Microagent Descriptors dialog displays, listing only methods that perform an action (IMPACT_ACTION and IMPACT_ACTION_INFO). 6. Click the Custom microagent and the executeForNumber() method. 7. Type the full path of a script to execute, such as cleanup.bat, in the Command field, then click OK. This might be a script that deletes core and temporary files on the local machine.
Performing Network Actions 213
The microagent and method names display in the Action field:
8. Click Send Action. The Reply section contains three tabbed panels: Success, Error, and Timeout. The Success panel displays agents that successfully executed the network action. Click any agent in the list to see the name of the microagent that was invoked. The Error panel displays agents that could not execute the action. Click an agent in the list to view the error text returned. The TimeOut panel displays agents that did not respond, usually due to a network problem. On any tab, clicking Sort sorts the list of agents by name. Sorting agents by name is useful for navigating a large results list. For example, to test a rule before adding it to a rulebase you could make the True Host List into targets, create a network action, and specify the action you expect to take as a result of a true test. 9. Click Done to close the Network Query/Network Action dialog.
214
| Chapter 10
Network query and action are interactive tools, so conditions you identify and solve in this manner might return without warning. If a particular network query repeatedly yields a true host list, you should consider formalizing query and action steps in a rulebase. The rulebase could contain a single rule to check for disk space usage greater than 90 percent, then call the cleanup script. A second action could notify you by E-mail that the script was run. You could distribute this rulebase to all agents, or just agents with a pattern of high disk space usage. For more information, see Chapter 4, Monitoring with Rulebases.
| 215
Chapter 11
Program Internationalization
This chapter describes Unicode and how to use it in TIBCO Hawk
Topics
Internationalization Support, page 216 Japanese Characters in Agents and Repositories, page 219 Changing the Encoding, page 220
216
| Chapter 11
Internationalization Support
Computers were originally designed to support only characters of the English language: numbers, some symbols, and control characters. The 7-bit ASCII character set represented these characters. Because a computer understands only a sequence of bits, a set of seven bits was used to encode different characters. For example, the letter "A" is represented by bit pattern "1000001" which is 65 in decimal. Similarly, the letter "1" is represented by bit pattern "0110001" which is decimal 49. International Language Support When the ASCII character set was extended to support all western European languages, another bit was added creating 128 more spaces. This 8-bit or 1-byte character set is ISO-8859-1 (or Latin1). In ISO-8859-1, the most significant bit is set to represent the additional 128 slots, and most of them are used to encode Western European characters. When the most significant bit is not set, the eight bits still represent ASCII characters. Thus ASCII is a subset of this extended character sets. Because one byte was not sufficient to include the Eastern European characters, a separate encoding or character set, called ISO-8859-2 (or Latin2) was created, which is not compatible with ISO-8859-1. Other ISO 8859 series character sets were also invented to handle a larger selection of languages. Again, all of these ISO-8859 character sets are superset of and backward compatible with ASCII. However, the code spaces provided by 1 byte (or 8 bits) are not enough for representing the tens of thousands of characters used in languages such as Chinese, Japanese and Korean (CJK). Thus, multibyte character sets were developed, together with the corresponding encoding methods for each character sets. These include those locale-independent encodings such as ISO-2022, EUC, and locale-dependent encodings like Shift_JIS (Japanese), GB2312 (Simplified Chinese), Big5 (Traditional Chinese), and so on. Geographic Independence At this time, computer networks are independent of geographic locations. Even though language data could be exchanged between computers supporting different character sets, its visualization and correct interpretation is only possible when the destination system is configured with the same character set as the source system. With so many existing different character sets installed in systems of different locales, it is difficult for the above to be accomplished. Thus, a uniform character set and encoding is necessary, which is Unicode.
Internationalization Support 217
Unicode Basics Unicode is a way to represent characters of all known languages of the world, which are defined in a character set named UCS (Universal Character Set). It provides a unique code point for every character regardless of platform, program or language. The advantage of Unicode is that characters from the world's major scripts are uniformly supported. Thus applications running on different platforms with different locales can exchange information without misinterpretation, as long as they follow this uniform character set. Locale Locale is the information for a specific combination of language, territory (cultural data), and codeset. Examples are en_US.ASCII, ja_JP.Shift_JIS, etc. Normally, an operating system is started with a particular locale. Normally, an operating system is started with a particular locale. UCS, Unicode and UTF-8 UCS is the abbreviation for Universal Character Set, which is specified by International Standard ISO/IEC 10646. UCS contains the characters of almost all the world's major scripts. Unicode is a standard that defines a character code set (UCS, or Universal Character Set, defined in ISO/IEC 10646) that assigns a unique code point (scalar value) to each character of almost all the world's major languages. The Unicode standard also includes a series of character encodings that represent each of these code points, such as UTF-8, UTF-16 (UCS-2), UTF-32, etc. For more information about Unicode, refer to Unicode Consortium's official web site: www.unicode.org. UTF-8 denotes Unicode Transformation Format 8 bit, a common Unicode encodings that serializes a Unicode scalar value as a sequence of one to four bytes. The purpose of the transformation encoding is that the data represented this way can be passed reliably through single byte environments. UTF-8 is popular for data exchange between applications and protocols such as HTTP, XML, MIME, and SOAP. One nice feature of UTF-8 is that it is backward compatible with ASCII.
218
| Chapter 11
Why is Unicode Important?

Companies wanting to deploy globally must be able to support the various languages of those countries. Business data of global companies may be exchanged among their computer systems located in different countries with different locales. Unicode facilitates using all languages in practically all computer environments. It allows text data to be exchanged and viewed through many different systems without corruption.
Using Japanese Characters 219
Using Japanese Characters

The information in this section applies to configurations using Japanese characters on Microsoft Windows platforms.
Japanese Characters in Agents and Repositories

When TIBCO Hawk Display runs on an English machine, it cannot discover or display agents and repositories that have data containing Japanese characters. Therefore, if you have a mixed environment of Japanese and non-Japanese machines, you must run TIBCO Hawk Display on a Japanese machine. This allows TIBCO Hawk Display to see all the machines and the repositories. It is recommended that the UTF-8 encoding be used throughout in this type of mixed environment.
Japanese Characters in External Variables File

If your external variables file contains Japanese characters, you must use the included native2ascii utility to convert the file before starting the agent. The native2ascii utility is in the JDK bin directory. The utility is not available in the JRE. To convert the external variables file: 1. Open a command prompt window. 2. Run the native2ascii utility, providing the input file and output file as arguments. For example, to convert an external variables file named abc.var to xyz.var, type:
native2ascii abc.var xyz.var
3. Before starting the agent, use the Configuration Utility to specify xyz.var as the variables file to use for the Agent. Alternatively, specify xyz.var as a value to the -variables option in the Agent's configuration file. Rulebase names may contain only numeric digits, underscore (_), hyphen (-), or a letter as defined by the UNICODE 2.0 standard. The latest version of the UNICODE specification can be found at www.unicode.org/ucd.
220
| Chapter 11
Changing the Encoding

The default encoding used by TIBCO Hawk is UTF-8. This encoding works for all locales and should not need to be changed. The character encoding used by TIBCO Hawk on Microsoft Windows is configured by the Codepage and Character Encoding configuration parameters in the Configuration Utility. The Codepage configuration option indicates the desired character encoding to be used by the HMA. This value is specified using Microsoft Windows code page values. The Character Encoding configuration option indicates the desired character encoding to be used by the Agent, Display, and Event Service. This value is specified using the Java Character Encoding identifier.
These two configuration options must be compatible. Refer to the TIBCO Hawk Installation and Configuration manual for complete details on the Codepage and Character Encoding configuration parameters.
| 221
Appendix A
Troubleshooting
This section contains troubleshooting information.
Topics
Troubleshooting, page 222
222
| Appendix A
Troubleshooting
Troubleshooting
A message similar to the following appears in the Microsoft Windows Event Log:
2002 Sep 13 09:01:31:035 GMT -8 HawkHMA Info [Application] HWKHMA-007012 PdhGetFormattedCounterValue for object PhysicalDisk and instance _Total and counter Split IO/Sec failed with error 0x800007D8.
Code
0x8000078D8 0x8000078D6
Text
A counter with a negative value was detected. A counter with a negative denominator was detected.
Resolution The Microsoft Windows Performance API is driven by a set of Microsoft Windows and third-party extension DLLs, which implement the various performance objects and associated counters. These extension DLLs may occasionally return counter values that cause mathematical errors in performance statistics calculations. These messages are reported by the Microsoft Windows Performance API. These messages are reported by HMA for information purposes and do not have any adverse effect on functionality. They are not caused by HMA. They are caused by bugs or design flaws in the associated extension DLL.
| 223
Appendix B
Frequently Asked Questions
This appendix presents answers to some commonly asked questions about TIBCO Hawk.
Topics
General, page 224 Installation, page 226 Alerts, page 227 Configuring Agents, page 228 Error messages, page 231 Command Lines and Process Names, page 235 Methods, page 237 Rulebases, page 239 Versions, page 242
224
| Appendix B
General
Is there a way to monitor the size of a file using TIBCO Hawk software? Use FileStat:getFileStatus(filename) as a datasource in your rulebase. Platform: Not Specified Version: All Why does TIBCO Hawk Display always show the primary interface IP address? Only the IP address of the primary interface can be obtained from within a Java program. Thus, the TIBCO Hawk agent always publishes the primary IP address of the machine as part of its heartbeat message. If the agent is started on an interface other than the primary interface, the TIBCO Hawk Display will still only display the primary interface IP address. What is $HAWK_ROOT? On Unix, $HAWK_ROOT is an environment variable you set during TIBCO Hawk installation which specifies the directory in which TIBCO Hawk is installed. On Microsoft Windows, this information is not stored as an environment variable, but this name is used in the documentation to refer to the TIBCO Hawk installation directory. The TIBCO Hawk Microsoft Windows installation program stores this information in the Microsoft Windows registry. Platform: Not Specified Version: All Why doesn't my Java AMI application show up in my process table? If you are using the Java Runtime Environment (JRE) to run your Java application, the process shows up as a "jre" or "java" process, not as the name of your application. If you want to test for the presence of your application you may use getInstanceCountByCommand method. Platform: Not Specified Version: All
General 225
Why cant I start a browser from TIBCO Hawk Display on UNIX? Launching a web browser (like Netscape) from the "Tools" menu of the TIBCO Hawk display will not work on UNIX systems that use the Common Desktop Windowing Environment (CDE). To launch a browser, enclose the browser command within a shell command and launch the shell command, as shown below.
#! /bin/csh setenv XFILESEARCHPATH netscape $*
226
| Appendix B
Installation
Does a machine on which I am using TIBCO Hawk Display need to run the TIBCO Hawk services (HMA, agent and event service)? No, it does not as long as you are not interested in monitoring that host. If you are not sure whether you will want to use the services, install them but set them to Manual startup. Platform: Not Specified Version: All
Alerts 227
Alerts
How can I isolate the alerts for one agent into their own log file? You can track information specific to one agent, microagent or application by writing this information to a log file in an action that is part of a rule. To do this, set up a rule that retrieves specific information (such as free disk space), give it a test that always evaluates to true, and write the important information to a log file. For example, you might create a rule with the data source Performance: LogicalDisk: percent free Space (Microsoft Windows) or filesystem: getByPartition: percent free (Unix) to be collected every five minutes. The rule might have a test such as percent free != -1 which would always be true. The test might have an action such as echo logfile.dat (which would be prefixed in Microsoft Windows with cmd /c). This would append information on free disk space to a specific log file. Platform: Not Specified Version: All How do I stop the unnecessary alarms from a remote machine? When you are running TIBCO Hawk Display on Microsoft Windows with a remote TIBCO Rendezvous session, the agent on the remote machine may generate unnecessary alarms when it discovers the HMA on the Microsoft Windows machine. To avoid this, in the host machine services startup parameters, set the TIBCO Hawk agent and HMA services to "Manual". Why did the log parser fail? If TIBCO Hawk alert or notification messages contain line feed characters, a log file parser will not be able to properly evaluate the TIBCO Hawk Event Service file, Event.dat. The line feed characters are usually derived from parameter variable substitution from the following microagents:
Logfile:onNewLine ${nextLine} Custom::executeForString|Number, ${returnString|Number}
Avoid using line feed characters in alert or notification messages. If line feed characters cannot be avoided, use the Console API to evaluate alerts and notifications containing line-feeds. You can also use the Hawk 4.1 Event Service microagents in lieu of directly reading Event.dat.
228
| Appendix B
Configuring Agents
How do I know if the agent is running on the machine? You may use TIBCO Hawk Display to discover the agent, or you may check to see if the JVM process (Java or JRE) for the agent is running on the machine. On UNIX: Immediately following "startagent", if you do not see any stderr messages, review the <HAWK_ROOT>/log/Hawk.log file to verify if the agent is initializing and communicating with the HMA and other AMI applications, and loading the rulebases correctly. On Microsoft Windows: check the Processes table in Task Manager for tibhawk.exe or the status for TIBCO Hawk service in the Microsoft Windows Services Manager.
Platform: Not Specified Version: All Do I need to run both the HMA and the agent? Yes, the HMA provides system-specific microagents that could be used in monitoring system resources such as cpu utilization, disk space usage, or process instance count. The agent provides its own set of non-platform-specific microagents which allows the execution of custom scripts or programs and log file monitoring. Platform: Not Specified Version: All How do I access and make use of the HMA microagents? You may interact with the HMA microagents through TIBCO Hawk Display or Console API applications. You may create rulebases for the agent by using the HMA microagents and their methods in combination with each other. Platform: Not Specified Version: All
Configuring Agents 229
How do I notify someone if the agent dies? Use event service and provide it with a script to send an e-mail (or page) to an administrator. When an agent's heartbeat is not received by the event service, it will execute the script specified at start-up, providing it with two arguments (first argument being the hostname of the dead agent and the second argument being the dead agent's IP address).You may create the script to accept one or both arguments. Platform: Not Specified Version: All How can I create my own microagents? By instrumenting the TIBCO Hawk Application Management Interface (AMI) in your application. There are several ways to do this: Use the AMI API (available in C, C++ or Java) with or without the TIB/Adapter SDK. Use the TIB/Adaptor SDK alone. Use the TIB/Rendezvous API to implement AMI in your application. Use the Microagent plugin.
Please refer to the TIBCO Hawk Programmer's Guide for further details. The sample AMI API code provided in <HAWK_ROOT>/samples/ami_api may help you in understanding the concepts and getting started. Platform: Not Specified Version: All When I bring up the display, I see the agent on my machine but not on others. What's wrong? Check whether you used the same RV session parameters for the TIBCO Hawk agent and display for your machine as for the others on your network. Your display will only receive TIBCO Hawk agent heartbeats and alert messages from agents on the same subnet. Check for a Hawk domain mismatch. If you have agents on different subnets, use multicast or configure and run an RVRD pair to route TIBCO Hawk messages across the subnets. Platform: Not Specified Version: All
230
| Appendix B
In the TIBCO Hawk Display, some agents on the network repeatedly turn purple and then return to a green color. What does this mean? Purple means the expected heartbeat from that agent has not been received. Green means the heartbeat has been received and is OK. If the agent alternates between purple and green, there may be network-related issues, including congestion, a faulty connection, etc. In TIBCO Hawk 4.1, you can lengthen the heartbeat interval of that Agent, which will increase the heartbeat grace period. Platform: Not Specified Version: All How do I keep the agent from exiting when I log off? Normally, an agent exits when a user logs off the desktop. To prevent the agent from exiting, add the -Xrs option to the agent's JVM command line (JRE 1.3.1 only). This is done in the Hawk Configuration utility Advanced Configuration dialog.
Error messages 231
Error messages
When I try to open a Solaris rulebase on a Microsoft Windows machine, I get the message "Invalid Microagent ... Unable to construct Test Editor" Some microagents (such as self and rendezvous) are platform-independent and are used on all operating systems. Others, such as performance (Microsoft Windows) and file system (Unix), are platform-specific, meaning they are specific to one operating system. Rules can use methods of either platform-independent or platform-specific microagents as data sources. When editing a rulebase, all of the microagents used within that rulebase must be loaded locally in the agent (or the repository's host agent) used as the editing platform. Otherwise, the agent will not have access to the necessary descriptors. Platform: Not Specified Version: All When you open a rulebase loaded by an agent, you can look at all of its rules. However, you cannot choose a data source that is unavailable to that agent, and you cannot edit tests that rely on unavailable data sources. Why? If you want to examine or change rules whose data sources are not available from the machine on which you are using the TIBCO Hawk Display, interact with an agent located on a machine on which the data sources are available. For example, if you have Microsoft Windows and Solaris machines in your network and you want to examine a Solaris rulebase from a Microsoft Windows machine, select an agent running on a Solaris machine, choose 'Get RuleBases', and examine or change the rules there. Platform: Not Specified Version: All Why is the Application Event Log full of performance DLL errors? Under certain conditions the TIBCO Hawk Performance Microagent can cause the Application Event Log to fill rapidly with messages similar to:
"The open procedure for service "htpps4.1" in DLL e:\netscape\server\bin\htps\nsctr.dll failed. Performance data for this service will not be available. Status code returns DWORD0 1008".
232
| Appendix B
This error occurs whenever a Microsoft Windows service's performance DLL (service htpps4.1 in this case) fails to load. Each failed load also causes the application (Hawk HMA) to leak memory. The problem lies in the Microsoft Windows performance counter libraries. To fix this problem, rename the DLL listed in the error message. Platform: Microsoft Windows 2000 Version: All I get errors on my Microsoft Windows system despite trying approaches listed in the troubleshooting section of the TIBCO Hawk Installation and Configuration Guide. What should I do? Please note that any changes made to the Microsoft Windows environment and registry requires the machine to be rebooted, otherwise none of the changes will propagate to the Microsoft Windows Services. Reboot and try the operation again. Platform: Microsoft Windows Version: All The Microsoft Windows Performance API reports errors regarding counter values that cause mathematical errors in performance statistics calculations. The Microsoft Windows Performance API is driven by a set of Microsoft Windows and third-party extension DLLs, which implement the various performance objects and associated counters. These extension DLLs may occasionally return counter values that cause mathematical errors in performance statistics calculations. These errors are reported by the Microsoft Windows Performance API. For example: Error Code
0x8000078D8 0x8000078D6
Error Text
A counter with a negative value was detected. A counter with a negative denominator was detected.
These errors are reported by HMA for information purposes. The errors are not caused by HMA. They are caused by bugs or design flaws in the associated extension DLL. Platform: Microsoft Windows Version: All
Error messages 233
Why do I get an error when I call a method of my instrumented application? Check that the message descriptions in your _describeMethods return messages that match up exactly with the messages returned by your methods. If the identifiers do not match up, an error will result. Use the AMI WorkBench to interact with your application for preliminary testing. Examine the error messages you receive when you call the method. Please refer to AMI reference manual for details. Platform: Not Specified Version: All What is a JIT Compiler Not Found error? On some platforms the JRE executable will generate the following warning message. This warning does not affect the execution of TIBCO Hawk software and can be ignored.
"Warning: JIT compiler "none" not found..."
What does a NoDataSource error mean? This type of error means that a rule attempted to obtain information from a data source that did not exist at the time of the rule evaluation and the specified information could not be obtained. If the data source is a HMA microagent method, check to see that the HMA process is running. When the operating system starts, make sure your HMA process starts before your TIBCO Hawk agent process. If the HMA process is running, there may be some reason why the communication between the agent and the HMA is upset. If the data source is a log file, check to see that the log file has not been renamed or moved. If the data source is an instrumented application, check to see if the application is running.
Rules that operate on applications instrumented with AMI can only work when the application is running. Platform: Not Specified Version: All
234
| Appendix B
Why can I not start a TIBCO Hawk Display even though the TIBCO Hawk Agent and HMA services have started successfully? In Microsoft Windows, if a User variable is defined in the environment, it will supersede any items defined in the System variables. So if there is a User CLASSPATH or PATH defined, it will need to augmented to include the proper references to tibrvj.jar and ..\tibrv\bin to support TIBCO Hawk Display. Platform: Microsoft Windows Version: All
Command Lines and Process Names 235
Command Lines and Process Names

I cant use a quoted string as a command argument in UNIX. On UNIX, quoted strings with embedded blanks cannot be passed as command arguments to UNIX shell scripts by means of the Custom::execute, Custom::executeForNumber and Custom::executeForString methods. The Java Virtual Machine (JVM) parses these strings as blank delimited tokens and passes them as separate arguments. To work around this, utilize a shell script as the executable. Pass all arguments that do not contain spaces first. Then use the "shift" shell command and a wildcard argument variable, "$*", to pass the space containing argument at the end. I'm trying to execute a command line using custom: execute, and it won't work -- but when I shorten the command line it works. What should I do? This is a known problem because some operating system shells limit the size of command lines that can be passed to them. To get around this problem, write a script with the long command line, and call that script from the custom:execute method. Platform: Not Specified Version: All Why can't I match long process names?
ProcessCount method
When using the process:getProcess method (UNIX) or performance: (Microsoft Windows), you may find that process names longer than a certain length cannot be matched exactly. This limit on process names comes from the operating system functions used to collect this information. There are several workarounds to the limitation of process names: Only specify process names that are less than 14 characters.
abcdefghijklmn
Use regular expressions to match process names. For example, to find process you might search for the regular expression abcdef.* .
Invoke the Process::getProcess method with no arguments to view the supported process name length. Use the Process::getIntancesByCommand method to match on the process's Command string.
236
| Appendix B
Use the Process microagent.
The full command is not returned by my operating system. What do I do? In the Process::getProcess and Process::getInstanceCountbyCommand methods, the full command may not be returned. The command is truncated to between 55 and 80 characters, depending upon the operating system, and contains the same information as the ps -ef utility. To get the full command, use a script that utilizes the UCB ps utility (for example, /usr/ucb/ps -auxww | grep -c mycommand) in conjunction with Custom::executeForNumber(). How do I find out how many characters are supported by my operating system? Some operating system shells limit the size of command lines or process names. For example, in the Microsoft Windows performance monitor, process names returned by the Process and ProcessCount methods of the Performance microagent are truncated to 14 characters. In UNIX, the ps command often has a similar limit. To find out how many characters are supported in an operating system, invoke the process method from the microagent's window with no arguments. Use Process:getInstanceCountByCommand() instead of /ucb/ps (/ucb/ps is very resource-intensive). This will return the process names given by the operating system, and you can see how many characters will be recognized when you specify a process name.
Methods 237
Methods
When I start a GUI process with the method custom:execute in Microsoft Windows environment, the process will only run in the background. How can I cause such a process to run in the foreground? To start a process you want to run in the foreground, create a utility that the TIBCO Hawk agent can invoke with custom:execute and pass it the process you want to execute in the foreground. This utility will be responsible for setting all the permissions required to start and display the GUI application. Custom: execute run in the foreground on a system wide basis by changing how the TIBCO Hawk agent service is configured. Follow these steps: 1. Select Start--Settings--Control Panel, then double-click Services. 2. Choose the TIBCO Hawk service and click Startup. 3. In the Service window that appears, click the System Account radio button in the Log On As panel. 4. Check the Allow Service to Interact with Desktop check box. All processes spawned by the TIBCO Hawk agent will now be in the foreground. Platform: Not Specified Version: All I call a script using the method custom: executeForNumber (executeForString), but the microagent terminates the script before it is finished because it takes too long. What should I do? Here are a few possibilities. Note that your script has to return within 10 seconds. If the script collects information over an interval of time, you can split the functionality of the script into multiple scripts and call them using a set of actions with increasing escalation periods. The script can spawn an application instrumented with AMI that collects the information and returns it to the rulebase asynchronously. You can then create a rule that responds to the asynchronous information. The script can spawn a process that writes information to a log file, and you can create a rule that responds to additions to the log file.
Platform: Not Specified Version: All
238
| Appendix B
Why do I get a negative ID Process or ID Thread number? When subscribing to Process/Thread methods on the performance microagent, the ID Process or ID Thread column may display a negative number other than -1. This is not an error; the negative number signifies that this particular instance of Process/Thread no longer exists and this row will be taken out in the next subscription interval. In this case, -1 as a Process ID is reserved for Process instance _Total, and -1 as a Thread ID is resolved for Thread instance _Total/_Total.
Rulebases 239
Rulebases
How many rules can you have in a rulebase? How many rulebases can you load onto an agent? How many alerts can you generate? There is no theoretical limit to the number of rules you can have in a rulebase or the number of rulebases a TIBCO Hawk agent can process. However, you may experience a practical limit in terms of memory use, speed, and operating system limitations such as the maximum number of open files per process. Platform: Not Specified Version: All If I use one rulebase across many computers, can I disable some rules on some computers? You might think that turning on and off rules would be a good way to adapt a rulebase for use on many slightly different computers. However, it presents a problem. If you could disable rules on individual agents, any rulebases distributed across the network would remove those differences, because the rulebases would still have the same names. One of the most important parts of planning your monitoring effort is deciding how rules will be organized into rulebases and how rulebases will be distributed over your network. Rulebases can range from very general (e.g. all_computers) to very specific (e.g. important_app). You will probably find that you end up with a set of rulebases you can mix and match to meet the specific needs on each computer. So if you need to tailor rulebases to specific computers, we suggest that you first look at what functions those computers are performing and how those functions can be organized into rulebase distributions. If you find that you have completely individual needs for each computer, the best approach is to design a rulebase with a unique name that corresponds to that computer. Platform: Not Specified Version: All What rulebases are available with the TIBCO Hawk monitoring software? The TIBCO Hawk software provides OS-specific rulebases for the platforms supported by it, as well as agent and RV rulebases. You can find all these rulebases stored under <HAWKROOT>/samples/rulebases where < HAWKROOT > is the root directory where the TIBCO Hawk software is installed.
240
| Appendix B
Platform: Not Specified Version: All Do you have rulebases for monitoring other TIBCO products, such as adaptors? Most rulebases ship with the products themselves and not with the standard TIBCO Hawk package. You may contact your TIBCO project manager or account executive for additional rulebase requirements. Platform: Not Specified Version: All If the TIBCO Hawk Display is not running, will my rulebases still work? Yes they will, as long as a TIBCO Hawk agent that has loaded them is running. TIBCO Hawk agents load the rulebases when they start up, and they run independently of the TIBCO Hawk Display. You only use the TIBCO Hawk Display startup. See the TIBCO Hawk Installation and Administrator's Guide for more details. Platform: Not Specified Version: All Why does the Posted Condition display as PostedConditionExist? In the Rulebase Test Editor, if PostedCondition is specified as ${Posted.x} > and saved, it will be displayed by the Test editor as PostedConditionExist when you reopen the rulebase. Both of these represent the same expression. Similarly, ${Posted.x} == 0 will be displayed as !PostedConditionExist. When I use the external variable such as ${External.testvar}in rulebase action type execute or method:Custom:Execute on Microsoft Windows platform, while variable file is specified as for example: testvar=c:\temp\abc.bat, it does not work. What's wrong? In the Microsoft Windows environment, when you specify the variable file which contains a directory path, instead of specifying
testvar=c:\temp\abc.bat 0
you should use forward slash or another backward slash to escape the '\', such as:
testvar=c:/temp/abc.bat
or
Rulebases 241
testvar=c:\\temp\\abc.bat
And this would solve the problem. Platform: WinNT Version: 4.x
242
| Appendix B
Versions
How do I find out which version of the TIBCO Hawk software I'm running? There are several ways: In <HAWK_ROOT>, check the readme.txt file. In the Hawk Display menu, go to Help, then About... . Use Self:getReleaseVersion().
Platform: Not Specified Version: All How do I know which version of JRE I'm using? Type in one of the following commands. The system will respond with the version number.
jre -version java -version
The JRE version is also logged in Hawk.log at agent startup.
Platform: Not Specified Version: All
| 243
Appendix C
TIBCO BusinessWorks and Hawk
This section discusses the use of Hawk with BusinessWorks.
Topics
Overview, page 244 Components, page 245 Integrating with Third Party Management Systems, page 246
244
| Appendix C
Overview
BusinessWorks is built using proven TIBCO technologies including TIBCO Rendezvous and TIBCO Hawk. In particular, the distributed monitoring and management architecture of BusinessWorks is heavily based on Hawk 4.0.1 release. Although BusinessWorks users do not need to know or understand how Hawk works or is used, users who need to integrate BusinessWorks environment with an existing Hawk-managed environment or for integration with a third-party Enterprise Management System may find some pointers useful in this document. You will be able to use the Hawk Display to monitor both BusinessWorks TRA and Hawk Agents concurrently and review or edit any rulebases created by BusinessWorks deployment via TIBCO Designer. It is not recommended that you modify any of the BusinessWorks deployment files manually including the rulebases. You will not be able to use the TIBCO Administrator to monitor Hawk Agents. It is recommended that you modify the Hawk domain name of the Hawk Agent and Display to that of the TIBCO (BusinessWorks) domain name. This will allow your Display to monitor the TRA and the Hawk Agents concurrently. Do not change the Hawk domain name used in the TRA by editing the tra.tra file. Using TIBCO Hawk You will be able to use the Hawk Display to monitor both BusinessWorks TRA and Hawk Agents concurrently and review or edit any rulebases created by BusinessWorks deployment via TIBCO Designer. It is not recommended that you modify any of the BusinessWorks deployment files manually including the rulebases. You will not be able to use the TIBCO Administrator to monitor Hawk Agents. It is recommended that you modify the Hawk domain name of the Hawk Agent and Display to that of the TIBCO (BusinessWorks) domain name. This will allow your Display to monitor the TRA and the Hawk Agents concurrently. Do not change the Hawk domain name used in the TRA by editing the tra.tra file.
Components 245
Components
TIBCO Administrator
BusinessWorks is the first TIBCO product to use TIBCO Administrator, a browser-based GUI for monitoring and managing deployed processes in the domain. Future TIBCO products may also support the use of TIBCO Administrator and the concept of the TIBCO domain. The domain is a collection of machines and software components used for business process integration. In terms of physical process, every domain has an Administration Server that provides a data store for all the domain resource information as well as project data. The Administration Server consists of a repository server and two servlets running on Tomcat application server. The servlets are built using Hawk Console API to interact with TIBCO Runtime Agents running on every machine in the domain.
TIBCO Runtime Agent

TIBCO Runtime Agent or TRA is a Hawk Agent with a special microagent added to deploy, monitor, and manage BusinessWorks processes. This is why you will find TIBCO Runtime Agent (Hawk Agent) and TIBCO Microagent (HMA) as pre-requisite components installed on every machine in the BusinessWorks domain if you were to use a Hawk 4.0 or a later Display to monitor the TIBCO Runtime Agent. TIBCO Microagent's microagents are the same as the ones in HMA's microagents.
TIBCO Domain
The domain name specified for BusinessWorks is used as the Hawk domain name in the subject name used for Administration Server to TRA communication. In other words, if you want to monitor TRAs in the local network, you will need to specify the domain name in the Hawk domain field of the Hawk Display configuration. For example, if the domain name of your domain is "staging", you may use tibrvlisten and listen on "_HAWK.staging.>" for these messages. The default RV sessions are the same as those for Hawk, which are service 7474, and daemon tcp:7474.
246
| Appendix C
Integrating with Third Party Management Systems

Since TRA is built using Hawk, all the events including alerts and heartbeats are in Hawk 4.0 format. This allows users to take advantage of Hawk Event Service to capture all TRA events into Event.dat, a flat file. This file can then be used by any third party management system for integration. In addition to this generic integration technique, one may also use vendor-specific adapters such as the Hawk Tivoli Adapter, or standards-based adapter such as the Hawk SNMP adapter. The SNMP adapter will allow TRA events to be filtered and forward as SNMP traps to HP/OpenView as well as other SNMP-based management consoles. BusinessWorks process engine and administration server do not have SNMP built-in. One will not be able to monitor these components directly via SNMP, however, the monitoring of these components are possible via Hawk and then if required through the Hawk SNMP Adapter.
| 247
Appendix D
Using Regular Expressions
This appendix describes the types of regular expressions you can use when specifying arguments of a microagent method or specifying a matching pattern in a character string. TIBCO Hawk software supports two types of regular expression syntax: Perl5PatternMatch for pattern matching in a rulebase, and REGEXP for matching in microagent arguments.
Topics
Perl5PatternMatch Syntax, page 248 REGEXP Syntax, page 250
248
| Appendix D
Perl5PatternMatch Syntax
This section describes Perl5PatternMatch syntax for pattern matching of test parameters. Perl5PatternMatch is an operator you can use to build tests in a rule. This operator searches for a pattern in a text string based on the coded instructions you specify. A regular expression has the form
[m]/pattern/[i][m][s][x]
The forward slashes surround the text pattern to match, and the letters in square brackets are optional modifiers. The following table shows some of the basic elements of Perl5PatternMatch regular expressions. For more information on using Perl5PatternMatch, see:
www.perl.com/reference/query.cgi?regexp
Table 12 Perl5PatternMatch Regular Expressions Element . ^ $ * + ? \w \W [a-z] [A-Z] Description

matches any single character anchors the match to the start of a line or piece of text anchors the match to the end of a line or piece of text matches zero or more of the last character matches one or more of the last character matches zero or one of the last character matches any alphanumeric character matches any non- alphanumeric character matches a lower-case character within a range matches an upper-case character within a range
Example
f.t matches fit î matches it
and fat
but not ti
^$ matches
only empty text
it* matches it
and i but not ia
it+ matches it
but not ip
it? matches i
or it but not itt
a\w matches at a\W matches a+
but not a+ but not at
[a-d] matches c
but not p
[A-D] matches C
but not c or P
Perl5PatternMatch Syntax 249
Table 12 Perl5PatternMatch Regular Expressions (Contd) Element \d Description

matches any digit
Example
a\d matches a2 /^\d\d/
but not at
matches any string that starts with 2 digits but not a2 but not 5
\D [0-9] \n, \t
matches any non-digit matches any digit within a range matches a new line character or tab character
a\D matches at
[1-4] matches 2
one\ttwo matches one <tab> two
Table 13 shows the available modifiers of a regular expression. Table 13 Regular Expression Modifiers Modifier
i m s x
Function
Do case-insensitive pattern matching. Treat the string as multiple lines. Treat the string as a single line. Use extended regular expressions.
250
| Appendix D
REGEXP Syntax
This section describes REGEXP syntax for pattern matching of method arguments for the FileStat, Process, and Performance microagents. REGEXP uses the following special characters:
* + ? . | ( ) + ^ $ [ ] - < > \ &
Table 14 shows some of the basic elements of REGEXP regular expressions. For more information on using REGEXP, type the following at a UNIX command line:
man regexp
Table 14 REGEXP Regular Expression Elements Element

.
Description
matches any single character except an end-of-line character anchors the match to the start of a line or piece of text when specified at the start of a regular expression matches any single character except an end-of-line character or the characters in brackets. The following characters are interpreted literally:
.*[ \
Example
f.t matches fit
and fat
î matches it
but not ti
[âbcd]
[^.tm] matches all characters except an end-of-line character or ., t, or m.
[abcd]
matches any single character in the brackets. The following characters are interpreted literally: .*[ \
[]aeiou] matches all occurences of vowels as well as the ] character. The ] is matched literally when it is the first character in the string. ^$ matches
anchors the match to the end of a line or piece of text matches zero or more of the last character matches one or more of the last character matches zero or one of the last character matches the following special character literally
only empty text
it* matches it
and i but not ia
it+ matches it
but not ip
it? matches i
or it but not itt
\$ matches $ and \wh*t?\ matches wh*t?
REGEXP Syntax 251
Table 14 REGEXP Regular Expression Elements (Contd) Element

\\
Description
matches the most-recently specified regular expression matches a lower-case character within a range matches an upper-case character within a range matches any digit within a range matches the beginning of a string, or a string following a character other than a letter, digit, or underscore. The first matching character must be a letter, digit, or underscore. matches the end of a string, or a string preceding a character other than a letter, digit, or underscore. The first matching character must be a letter, digit, or underscore. matches exactly _m occurrences of the regular expression, where _m is a positive integer less than 256
Example
[a-z]
[a-d] matches c
but not p
[A-Z]
[A-D] matches C
but not c or P
[0-9] \<
[1-4] matches 2
but not 5
\_cat< matches _category and _catalog, as well as @_category and @_catalog
\>
\gory> matches category and allegory, as well as {category} and {allegory}
\{_m\}
s*n\{5\} matches exactly 5 occurences of s*n, which could be instances of sun, son, sin and
so on. \{_m,\} matches at least _m occurrences of the regular expression, where _m is a positive integer less than 256 matches from _m through _n occurrences of the regular expression, where _m and _n are positive integers less than 256 matches the same set of characters matched by the enclosed regular expression
[abc]\{5\} matches 5 or more occurences of [abc], which could be instances of a, b, or c. \Error<\{15,25\} matches the 15th through 25th occurrences of strings that start with Error
\{_m,_n\}

See following row.
252
| Appendix D
Table 14 REGEXP Regular Expression Elements (Contd) Element

\_n
Description
matches the same set of characters matched by an expression enclosed by  earlier in the same expression. Begins with the _n-th occurrence of $ counting from the left.
Example
^\(.*$\1$ matches
a line consisting of two repeated appearances of the same string
| 253
Appendix E
Interpreting TIBCO Hawk Log Files
This appendix describes the types of log files that can be created on machines running TIBCO Hawk product components. Representative log file entries are shown, along with an explanation of the rolling log file mechanism.
Topics
Overview, page 254 Interpreting the TIBCO Hawk Agent Log, page 255 Interpreting the TIBCO Hawk Display Log, page 256 Interpreting the TIBCO Hawk Event Service Log, page 257 Interpreting TIBCO HawkHMA Log Files, page 258 Viewing Rolling Log Files, page 259
254
| Appendix E
Overview
TIBCO Hawk log files record specific TIBCO Hawk events as they occur to provide a permanent record of changes and to help you troubleshoot problems. This feature is built in and cannot be disabled. However, you can specify where and how log files are written. Depending on installed components, the following types of log files are created on each machine running a TIBCO Hawk product component:
Hawk.log,
which records information about the TIBCO Hawk agent which records information about the TIBCO Hawk Display
Display.log,
application
Event.log,
which records information about the TIBCO Hawk Event Service. and Hawk_HMA.log , which records information about
Hawk_<microagent>.log
microagent activities On Microsoft Windows systems you can have the log entries written to the Microsoft Windows application event log rather than a separate log file. In that case, select the Application Log in Microsoft Windows Event Viewer to view log entries. By default, log files are saved in your $HAWK_ROOT/log directory, maximum file size is 1024 kilobytes, and the maximum number of files is five. You can modify these settings by specifying LogService agent startup parameters. For more information, see TIBCO Hawk Installation and Configuration.
Interpreting the TIBCO Hawk Agent Log 255
Interpreting the TIBCO Hawk Agent Log

The TIBCO Hawk Agent log, Hawk.log, includes information on: Starting or stopping microagents and AMI applications Managing rulebases (loading, unloading, saving, deleting, using rulebases) Starting and stopping subscriptions to microagent methods using TIBCO Hawk Display
Following are some representative lines in an agent log file:

INFO : Initialized log service at Tue Aug 25 12:07:34 EDT 1998 INFO : Adding MicroAgent: COM.TIBCO.rendezvous:0 at Tue Aug 25 12:07:55 EDT 1998 INFO : Using C:\TIBCO\hawk\AUTOCO~1\ as the auto-config directory, at Tue Aug 25 12:08:06 EDT 1998 INFO : 1998 Adding Rulebase HawkAgent-WinNT at Tue Aug 25 12:08:06 EDT
INFO : Activating Rulebase HawkAgent-WinNT, at Tue Aug 25 12:08:06 EDT 1998 EVENT : Subscription Requested for: COM.TIBCO.Spot:0:getColor:( ):60 ERROR : NoValidDataSource for MicroAgent name: COM.TIBCO.performance, instance: null, Method name: Processor, Arguments: ( ), interval: 60 at RBEngine::Hawk->RuleBase::WinNT_Server->Rule::MicroAgent name: COM.TIBCO.performance, instance: null, Method name: Processor, Arguments: ( ), interval: 60->NoValidDataSource::MicroAgent name: COM.TIBCO.performance, instance: null, Method name: Processor, Arguments: ( ), interval: 60, at Thu Sep 03 18:19:52 EDT 1998 INFO : Removing MicroAgent: COM.TIBCO.eventlog:0 at Tue Aug 25 18:20:22 EDT 1998
256
| Appendix E
Interpreting the TIBCO Hawk Display Log

The TIBCO Hawk Display log, Display.log, includes information on: Agent activation and deactivation Agent alert state changes Actions taken by TIBCO Hawk Display, such as purging duplicate and cleared alerts
Do not rely on this log as an auditing tool for TIBCO Hawk agents. Although the Display log tracks some agent state changes, it is maintained only when the TIBCO Hawk Display application is running. Changes in agent state not detected by TIBCO Hawk Display are excluded from the log file. For a complete record of agent states, view the TIBCO Hawk Event Service data files. For more information, see Interpreting Event Service Data Files on page 116. Following are some representative lines in a Display log file.
INFO : Initialized log service at , at Wed Aug 26 12:51:19 EDT 1998 INFO : Resources Directory is C:\TIBCO\hawk\resource\, at Wed Aug 26 12:51:19 EDT 1998 INFO : Agent Dead - jaguar, at Tue Aug 25 12:55:59 EDT 1998 INFO : CheckRecovery activated., at Tue Aug 25 12:57:24 EDT 1998 INFO : Agent State Changed from recovered to OK - cuda, at Tue Aug 25 12:57:24 EDT 1998 INFO : Agent Alive - jaguar, at Tue Aug 25 12:57:59 EDT 1998 INFO : Purged 214 cleared messages, at Fri Aug 28 14:00:46 EDT 1998 INFO : Number of remaining outstanding alerts - 102, at Fri Aug 28 14:00:46 EDT 1998
Interpreting the TIBCO Hawk Event Service Log 257
Interpreting the TIBCO Hawk Event Service Log

The TIBCO Hawk Event Service log, Event.log, includes information on starting and stopping the TIBCO Hawk Event Service. This type of file tracks the status of the Event Service itself, not the monitored events recorded in Event.dat. Following are some representative lines in a typical event service log file.
INFO : Initialized log service at Wed Oct 25 12:42:30 PDT 2000 INFO : Java Virtual Machine(JVM) version - 1.3.1, vendor - Sun Microsystems Inc. ## Wed Oct 25 12:42:30 PDT 2001
258
| Appendix E
Interpreting TIBCO HawkHMA Log Files

The TIBCO Hawk HMA process creates log files for each microagent, such as Hawk_Process.log. The HMA process also creates a Hawk_HMA.log file for microagent-generic errors. You control the size and level of detail in HMA log files using the setTraceLevel() and setTraceParameters() methods. These standard methods are included for default platform-specific microagents, and can be added when instrumenting an application using the AMI protocol. Following are some representative lines in an HMA log file for the Services microagent:
2000/01/21 22:58:56.358 PROGRAM:tibhawkhma VERSION:3.0.0_Final DATE:Fri 01/21/2000 2000/01/21 22:58:56.358 Options in effect: -rvd_session 7475 ; tcp:7475 -logdir C:/program files/TIBCO/hawk/Log -logmaxsize 1024 -logmaxnum 5 WARNING 2000/01/21 23:03:18.355 OpenService failed for service "NoSuchService". WIN32 error 1060 (0x424): The specified service does not exist as an installed service. ERROR 2000/01/21 23:05:18.137 ControlService failed for service "Browser". WIN32 error 1052 (0x41C): The requested control is not valid for this service. WARNING 2000/01/21 23:05:45.587 StartService failed for service "Browser". WIN32 error 1056 (0x420): An instance of the service is already running. ERROR 2000/01/21 23:06:49.020 OpenService failed for service "Bad\Service\Name". WIN32 error 123 (0x7B): The filename, directory name, or volume label syntax is incorrect.
The first line identifies the AMI application, and the second identifies command line options in effect. Remaining lines are warnings and errors generated by the AMI application.
Viewing Rolling Log Files 259
Viewing Rolling Log Files

TIBCO Hawk uses a rolling log file mechanism to manage log file space. When one file has reached a maximum size, it is closed and renamed, and a new log file with the same name is started. When the number of files of a particular type exceeds a maximum, log entries roll over to reuse the oldest log file. Using the LogService agent startup parameters, you can specify the maximum size of a log file before the next file is started, and how many log files of each type to keep. For more information, see TIBCO Hawk Installation and Configuration. For example, Figure 4 shows the current TIBCO Hawk Event Service data file Event.dat, accompanied by five filled data files. In this example, the maximum size of a data file is set to 1024 K (it is shown rounded) and the maximum number of data files is set to five. When the current data file Event.dat is filled, the most recent data file (Event1.dat) is renamed to Event2.dat, and so on, rotating Event5.dat out of the list. Then the current data file, Event.dat, is renamed to Event1.dat and new messages are written to the new Event.dat. Figure 4 Rolling File Mechanism
This is the Event Service data file, where event information is written.
In this example, Event Service data file options are: maximum number of files: 5 maximum file size: 1024 K
When Event.dat is full, this file drops out of the list and Event4.dat is renamed to Event5.dat
260
| Appendix E
| 261
Appendix F
Error Codes
This appendix lists error codes for all TIBCO Hawk components.
Topics
Introduction, page 262 Error Code List, page 263
262
| Appendix F
Error Codes
Introduction
Error handling techniques provide an efficient way to track down the cause of a problem. The techniques allows you to track the state of a business object as it moves from its source to its destination. Error messages are standardized to a particular format. Each message is divided into a number of fields, which are explained in the next table: Table 15 Error Handling Fields Field Name MessageCode Explanation Unique code for the message. For example:
HWKAMI-000001
Description Category Role
Informative text message explaining the trace message. Name of the component which generated the message. Role of the trace message: Error Unrecoverable errors. If an error of this type is not addressed, the component may continue with the next operation or may stop altogether. Warning An abnormal condition was found, but it does not prevent processing to be performed. Special attention from an administrator is recommended. Information A significant processing step was reached and it has been logged for tracking or auditing purposes. Debug Debug mode should not be used unless directed by TIBCO Support.
Resolution
Suggested solution to resolve the problem.
Error Code List 263
Error Code List

HWKAMI-000001 Role Category Resolution HWKAMI-000002 Role Category Resolution HWKAMI-000003 Role Category Resolution HWKAMI-000004 Role Category Resolution
Unable to create AMI error due to memory allocation failure. Error. TIBCO Hawk AMI API Insufficient memory available for process. Insufficient memory to process request. Error TIBCO Hawk AMI API Insufficient memory available for process. Specified AMI error handle is invalid. Error TIBCO Hawk AMI API Programming error. AMI error handle passed to function is null. Specified AMI error handle is invalid or corrupted. Error TIBCO Hawk AMI API Programming error. AMI error handle passed to function is invalid, corrupted or was previously destroyed. Required argument not specified (null). Error TIBCO Hawk AMI API Programming error. Null value specified for a required function argument. Invalid argument specified. Error TIBCO Hawk AMI API Programming error. Invalid value specified for a function argument. Specified AMI session handle <handle value (hex)> is invalid. Error TIBCO Hawk AMI API Programming error. AMI session handle passed to function is null. Specified AMI session handle <handle value (hex)> is invalid or corrupted. Error TIBCO Hawk AMI API
HWKAMI-000005 Role Category Resolution HWKAMI-000006 Role Category Resolution HWKAMI-000007 Role Category Resolution HWKAMI-000008 Role Category
264
| Appendix F
Error Codes
Resolution
Programming error. AMI session handle passed to function is invalid, corrupted or was previously destroyed. Specified AMI method handle <handle value (hex)> is invalid. Error TIBCO Hawk AMI API Programming error. AMI method handle passed to function is null. Specified AMI method handle <handle value (hex)> is invalid or corrupted. Error TIBCO Hawk AMI API Programming error. AMI method handle passed to function is invalid, corrupted or was previously destroyed. Specified AMI subscription handle <handle value (hex)> is invalid. Error TIBCO Hawk AMI API Programming error. AMI subscription handle passed to function is null. Specified AMI subscription handle <handle value (hex)> is invalid or corrupted. Error TIBCO Hawk AMI API Programming error. AMI subscription handle passed to function is invalid, corrupted or was previously destroyed. Specified AMI parameter list list handle <handle value (hex)> is invalid. Error TIBCO Hawk AMI API Programming error. AMI parameter list list handle passed to function is null. Specified AMI parameter list list handle <handle value (hex)> is invalid or corrupted. Error TIBCO Hawk AMI API Programming error. AMI parameter list list handle passed to function is invalid, corrupted or was previously destroyed. Specified AMI parameter list handle <handle value (hex)> is invalid. Error TIBCO Hawk AMI API Programming error. AMI parameter list handle passed to function is null. Specified AMI parameter list handle <handle value (hex)> is invalid or corrupted.
HWKAMI-000009 Role Category Resolution HWKAMI-000010 Role Category Resolution
HWKAMI-000015 Role Category Resolution HWKAMI-000016
Error Code List 265
Role Category Resolution
Error TIBCO Hawk AMI API Programming error. AMI parameter list handle passed to function is invalid, corrupted or was previously destroyed. Specified AMI parameter handle <handle value (hex)> is invalid. Error TIBCO Hawk AMI API Programming error. AMI parameter handle passed to function is null. Specified AMI parameter handle <handle value (hex)> is invalid or corrupted. Error TIBCO Hawk AMI API Programming error. AMI parameter handle passed to function is invalid, corrupted or was previously destroyed. TIBCO Rendezvous error <error number> <error text>. Error TIBCO Hawk AMI API The specified TIBCO Rendezvous error occurred. Refer to TIBCO Rendezvous documentation. Received invocation request for unknown AMI method <method name>. Error TIBCO Hawk AMI API An agent (e.g. TIBCO Hawk Agent or Console API application) has invoked a non-existent method on this AMI session. Contact TIBCO Support for assistance. Method <method name> does not have a parameter named <parameter name>. Error TIBCO Hawk AMI API Programming error. Parameter function called for non-existent parameter. Check the method creation code to insure that the specified parameter was actually added to the method. Failed to add object to linked list. Error TIBCO Hawk AMI API Link list add failed due to insufficient memory available for process. TIBCO Rendezvous error <error number> occurred attempting to get value for argument <argument name> of method <method name>. <error text>. Error
HWKAMI-000019 Role Category Resolution
HWKAMI-000022 Role Category Resolution HWKAMI-000023 Role
266
| Appendix F
Error Codes
Category Resolution
TIBCO Hawk AMI API The specified TIBCO Rendezvous error occurred when attempting to get argument value. Refer to TIBCO Rendezvous documentation. <method name> invocation received for unknown subscription with context <context number> and reply subject <subject name>. Error TIBCO Hawk AMI API Internal error. Contact TIBCO Support for assistance. Attempt made to announce an AMI session which is already announced. Error TIBCO Hawk AMI API Programming error. An AMI session cannot be announced while it is currently announced. Attempt made to stop an AMI session which has not been announced. Error TIBCO Hawk AMI API Programming error. An AMI session cannot be stopped if it is not currently announced. Unable to request ami heartbeat: <com.tibco.rv.TibrvException> Error Application TIBCO Hawk Agent A TIBCO Rendezvous error has occurred. Consult the TIBCO Rendezvous documentation. Unable request ami refresh: <com.tibco.rv.TibrvException> Error Application TIBCO Hawk Agent A TIBCO Rendezvous error has occurred. Consult the TIBCO Rendezvous documentation. Unable to get CONTEXT field in AMI reply message for <microagent_id>, <com.tibco.rv.TibrvException> Error Application TIBCO Hawk Agent A TIBCO Rendezvous error has occurred. Consult the TIBCO Rendezvous documentation. COM.TIBCO.hawk.agent.mafactories.AmiMsgFormatError <error> Error
HWKAMI-030104 Role
Error Code List 267
Category Resolution
Application TIBCO Hawk Agent An AMI message is incorrectly formatted. Consult the documentation for the AMI instrumented application. Unknown message type received for <microagent_id> Error Application TIBCO Hawk Agent Contact TIBCO Support. Received asynchronous data message for non-existent subscription in : <microagent id> Warning Application TIBCO Hawk Agent Contact TIBCO Support Unable to process AMI reply message in: <microagent_id>, <com.tibco.rv.TibrvException> Error Application TIBCO Hawk Agent A TIBCO Rendezvous error has occurred. Consult the TIBCO Rendezvous documentation. Async method control msg reply contained non-empty RETURN field, Async method may have sent data to incorrect reply-subject Warning Application TIBCO Hawk Agent Contact TIBCO Support <microagent_id>:COM.TIBCO.hawk.agent.mafactories.AmiMsgFormatError <error> Error Application TIBCO Hawk Agent An AMI message is incorrectly formatted. Contact the vendor of the AMI instrumented application. <microagent_id>:COM.TIBCO.hawk.talon.MicroAgent Exception <error> Error Application TIBCO Hawk Agent An error has been received from an AMI instrumented application. Consult the documentation for the AMI instrumented application. Unable to stop subscription: <com.tibco.rv.TibrvException>
HWKAMI-030105 Role Category Resolution HWKAMI-030106 Role Category Resolution HWKAMI-030107 Role Category Resolution
HWKAMI-030111 Resolution Role Category Resolution
HWKAMI-030112
268
| Appendix F
Error Codes
Error Application TIBCO Hawk Agent A TIBCO Rendezvous error has occurred. Consult the TIBCO Rendezvous documentation. stopSubscription called for non-existent subscription : <subscription> in <microagent id> Warning Application TIBCO Hawk Agent Contact TIBCO Support Method <name> returned tabular data but INDEX was not specified. Ignoring all but first RETURNS field Error Application TIBCO Hawk Agent An AMI instrumented application is returning tabular data for a method that was not described to return tabular data. Contact the vendor of the AMI instrumented application. Multiple startup announcement messages received for <microagent id> Warning Application TIBCO Hawk Agent Contact TIBCO Support Unable to process AMI announcement message: <com.tibco.rv.TibrvException> Error Application TIBCO Hawk Agent A TIBCO Rendezvous error has occurred. Consult the TIBCO Rendezvous documentation. Unable to process AMI announcement message: <ami_msg_format_error> Error Application TIBCO Hawk Agent An AMI message is incorrectly formatted. Contact the vendor of the AMI instrumented application. Announced AMI application <application name> did not respond to first heartbeat request. Presumed dead. Warning Application TIBCO Hawk Agent Contact TIBCO Support
Error Code List 269
Discovering methods. AMI App: <name>, exception: <com.tibco.rv.TibrvException> Error Application TIBCO Hawk Agent A TIBCO Rendezvous error has occurred. Consult the TIBCO Rendezvous documentation. Timed out waiting for reply to _describeMethods. AMI App: <name> Error Application TIBCO Hawk Agent Contact TIBCO Support. Unable to process AMI _describeMethods reply: <ami_msg_format_error> Error Application TIBCO Hawk Agent An AMI message is incorrectly formatted. Contact the vendor of the AMI instrumented application. Unable to process AMI _describeMethods reply: <exception> Error Application TIBCO Hawk Agent Contact TIBCO Support. Creating AMI microagent <name>, <COM.TIBCO.hawk.talon.MicroAgentException>; Error Application TIBCO Hawk Agent Contact TIBCO Support. Creating AMI microagent <name>, <com.tibco.rv.TibrvException>; Error Application TIBCO Hawk Agent Contact TIBCO Support. Adding discovered AMI microagent <name>, <exception>; Error Application TIBCO Hawk Agent Contact TIBCO Support. Unable to process AMI stop message: <com.tibco.rv.TibrvException> Error Application TIBCO Hawk Agent
HWKAMI-030508 Role Category Resolution HWKAMI-030509 Role Category Resolution HWKAMI-030510 Role Category Resolution HWKAMI-030511 Role Category Resolution HWKAMI-030512 Role Category
270
| Appendix F
Error Codes
Resolution
A TIBCO Rendezvous error has occurred. Consult the TIBCO Rendezvous documentation. Unable to process AMI stop message: <ami_msg_format_error> Error Application TIBCO Hawk Agent An AMI message is incorrectly formatted. Contact the vendor of the AMI instrumented application. Unable to remove AMI microagent <name>, <COM.TIBCO.hawk.talon.MicroAgentException> Error Application TIBCO Hawk Agent Contact TIBCO Support. Unable to send announcement request: <com.tibco.rv.TibrvException> Error Application TIBCO Hawk Agent A TIBCO Rendezvous error has occurred. Consult the TIBCO Rendezvous documentation. Internal error, AMI Microagent not successfully removed <name> Error Application TIBCO Hawk Agent Contact TIBCO Support. Unable to remove <name>, <COM.TIBCO.hawk.talon.MicroAgentException>; Error Application TIBCO Hawk Agent Contact TIBCO Support. Unable to process AMI unsolicited msg: <com.tibco.rv.TibrvException> Error Application TIBCO Hawk Agent A TIBCO Rendezvous error has occurred. Consult the TIBCO Rendezvous documentation. Unable to process AMI unsolicited msg: <ami_msg_format_error> Error Application TIBCO Hawk Agent An AMI message is incorrectly formatted. Contact the vendor of the AMI instrumented application.
HWKAMI-030516 Role Category Resolution HWKAMI-030517 Role Category Resolution HWKAMI-030519 Role Category Resolution
Error Code List 271
AmiTibrvService dispatch thread was interrupted: <java.io.InterruptedException> Warning Application TIBCO Hawk Agent Contact TIBCO Support AmiTibrvService dispatch thread caught exception: <com.tibco.rv.TibrvException> Error Application TIBCO Hawk Agent A TIBCO Rendezvous error has occurred. Consult the TIBCO Rendezvous documentation. AmiTibrvService dispatch thread caught exception: <java.lang.Throwable> Error Application TIBCO Hawk Agent Contact TIBCO Support. Unknown message template ID specified. Error TIBCO Hawk HMA Internal error. Attempt to lookup an unknown error message. Contact TIBCO Support for assistance. Trace function <function name> failed with error <error number> <error text> Error TIBCO Hawk HMA TIBCO Hawk HMA tracing function failed for the specified reason. If resolution is not obvious from the error description then contact TIBCO Support for assistance. PROGRAM: NAME <program name> VERSION <version> DATE <build date> Information TIBCO Hawk HMA Used to log product name, version and build date. TIBCO Rendezvous error <error number> <error text>. Error TIBCO Hawk HMA The specified TIBCO Rendezvous error occurred. Refer to TIBCO Rendezvous documentation. Insufficient memory to process request. Error
HWKAMI-030523 Role Category Resolution HWKHMA-001000 Role Category Resolution
HWKHMA-001001 Role Category Resolution
HWKHMA-001002 Role Category Resolution HWKHMA-001003 Role Category Resolution
HWKHMA-001004 Role
272
| Appendix F
Error Codes
Category Resolution HWKHMA-001005 Role Category Resolution
TIBCO Hawk HMA Insufficient memory available for process. Null or invalid argument specified. Error TIBCO Hawk HMA An invalid value was specified for a command line option. Refer to TIBCO Hawk documentation for command line description. TIBCO Hawk HMA initialization completed successfully. Information TIBCO Hawk HMA Execution of TIBCO Hawk HMA terminated successfully. Information TIBCO Hawk HMA Execution of TIBCO Hawk HMA failed. Error <error number> occurred on thread <thread ID (hex)> at line <line number> in file <file name>. <error text>. Error TIBCO Hawk HMA Wrapper used to report errors with thread ID, file name, and line number. Actual error could be any of the errors documented for the TIBCO Hawk HMA. Directory specified, <directory name>, is invalid. <error text>. Error TIBCO Hawk HMA An invalid directory name was specified. If resolution is not obvious from the error description then contact TIBCO Support for assistance. File specified, <file name>, is invalid. <error text>. Error TIBCO Hawk HMA An invalid file name was specified. If resolution is not obvious from the error description then contact TIBCO Support for assistance. Function <function name> failed for file <file name>. OS error <error number> <error text>. Error TIBCO Hawk HMA An error occurred for the specified file function. If resolution is not obvious from the error description then contact TIBCO Support for assistance.
HWKHMA-001007 Role Category HWKHMA-001008 Role Category HWKHMA-001009 Role Category Resolution
Error Code List 273
An option specified is invalid. Error TIBCO Hawk HMA An invalid command line option was specified. Refer to TIBCO Hawk documentation for command line description. Invalid value specified for option <option name>. Error TIBCO Hawk HMA An invalid value was specified for a command line option. Refer to TIBCO Hawk documentation for command line description. Value missing for option <option name>. Error TIBCO Hawk HMA No value was specified for a command line option. Refer to TIBCO Hawk documentation for command line description. Error processing specified TIBCO Hawk HMA command line. Error <error code>: <error test>. Error TIBCO Hawk HMA The specified error was encountered processing the specified command line. Refer to TIBCO Hawk documentation for command line description. OPTIONS RVD_SESSION<rendezvous parameters> TRACELEVEL<trace level> LOGDIR<log directory> LOGMAXSIZE<maximum log size> LOGMAXNUM<maximum log number> Information TIBCO Hawk HMA Used to log specified command line options to the TIBCO Hawk log files. TIBCO Hawk HMA microagent <microagent name> initialization completed successfully. Information. TIBCO Hawk HMA Error <error number> occurred on thread <thread ID (hex)> at line <line number> in file <file name>. <error text>. Error TIBCO Hawk HMA Wrapper used to report errors with thread ID, file name, and line number. Actual error could be any of the errors documented for the TIBCO Hawk HMA.
HWKHMA-001020
Role Category Resolution HWKHMA-001021 Role Category HWKHMA-001023 Role Category Resolution
274
| Appendix F
Error Codes
Function <function name> failed. OS error <error number> <error text>. Error TIBCO Hawk HMA An error occurred for the specified function. If resolution is not obvious from the error description, contact TIBCO Support for assistance. Stopping TIBCO Hawk HMA in response to a <signal name> signal. Information TIBCO Hawk HMA Unable to install signal handler for signal <signal name>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. Internal error. Unable to obtain TIBCO Hawk HMA configuration. <error text>. Error TIBCO Hawk HMA Unable to obtain configuration for TIBCO Hawk HMA. If resolution is not obvious from the error description, contact TIBCO Support for assistance. This asynchronous method does not support synchronous invocation. Error TIBCO Hawk HMA Attempt was made to synchronously invoke an asynchronous method. Specific method does not support synchronous invocation. Unknown microagent name, <microagent name>, specified in option <option name>. Error TIBCO Hawk HMA Invalid microagent name was specified in command line option. Refer to TIBCO Hawk documentation for command line description. TIBCO Hawk HMA microagent <microagent name> has been disabled via disable command line option. Information TIBCO Hawk HMA Internal HMA event <event name> received. Information TIBCO Hawk HMA
HWKHMA-001026 Role Category HWKHMA-001027 Role Category Resolution HWKHMA-001028 Role Category Resolution
HWKHMA-001031 Role Category HWKHMA-001032 Role Category
Error Code List 275
HWKHMA-001033 Role Category HWKHMA-001034 Role Category HWKHMA-001035 Role Category Resolution HWKHMA-001036 Role Category Resolution HWKHMA-001037 Role Category Resolution
HMA restart event received for microagent <microagent name>. Information TIBCO Hawk HMA HMA restart event processed for microagent <microagent name>. Information TIBCO Hawk HMA Unknown internal HMA event, <event name>, received. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. Attempt to increase default thread stack size failed. Function <function name> returned error <Error code> Error TIBCO Hawk HMA Internal error. Contact TIBCO Support for assistance. TIBCO Hawk HMA signal handling for signal <signal name> has been disabled via command line option. warning TIBCO Hawk HMA This message logs the fact that the HMA has been configured via command line option -disable to ignore the specified signal. This disables the default HMA signal handling for that signal. Unable to set signal disposition for signal <signal name>. Error TIBCO Hawk HMA The HMA was unable to set the default signal handling for the specified signal. The default signal handling will not be in effect. Contact TIBCO Support for assistance. This instance of microagent <microagent name> has a stop request pending. Restart ignored. Error TIBCO Hawk HMA If a restart method invocation is made against a microagent already in the process of restarting then this error is generated. You cannot restart a microagent which is being stopped by a previous restart invocation. Internal error. Unable to obtain service name.
HWKHMA-002000
276
| Appendix F
Error Codes
Role Category Resolution HWKHMA-002001 Role Category Resolution HWKHMA-002002 Role Category Resolution HWKHMA-002003 Role Category Resolution HWKHMA-002004 Role Category Resolution HWKHMA-002005 Role Category Resolution HWKHMA-002006 Role Category Resolution HWKHMA-002007 Role Category Resolution
Error TIBCO Hawk HMA Contact TIBCO Support for assistance. Internal error. Unable to obtain service startup parameters. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. Internal error. Unable to parse service startup parameters. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. Internal error. Unable to obtain service start type. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. Internal error. Invalid service start type specified. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. Internal error. Unable to obtain service control command code. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. Internal error. Unable to construct discovery reply. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. Internal error. OpenSCManager failed. WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. Internal error. Unable to allocate memory for services array. Error
HWKHMA-002008 Role
Error Code List 277
Category Resolution HWKHMA-002009 Role Category Resolution HWKHMA-002010 Role Category Resolution HWKHMA-002011 Role Category Resolution HWKHMA-002012 Role Category Resolution
TIBCO Hawk HMA Insufficient memory available to process. Contact TIBCO Support for assistance. Internal error. Unable to construct Windows NT service configuration message. Error TIBCO Hawk HMA Insufficient memory available to process. Contact TIBCO Support for assistance. Internal error. Unable to construct Windows NT service status message. Error TIBCO Hawk HMA Insufficient memory available to process. Contact TIBCO Support for assistance. Internal error. Unable to allocate memory for services enumeration. Error TIBCO Hawk HMA Insufficient memory available to process. Contact TIBCO Support for assistance. Internal error. GetServiceDisplayName failed for service "<service name>". WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. Internal error. QueryServiceConfig failed for service "<service name>". WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. Internal error. EnumServicesStatus failed. WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. StartService failed for service "<service name>". WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA
HWKHMA-002015 Role Category
278
| Appendix F
Error Codes
Resolution
This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. OpenService failed for service "<service name>". WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. ControlService failed for service "<service name>". WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. QueryServiceStatus failed for service "<service name>". WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. ChangeServiceConfig failed for service "<service name>". WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. Conversion from UNICODE to UTF8 failed. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. Internal error. Unable to obtain process virtual base address. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. Unable to retrieve process command line for this Microsoft Operating System version. Please contact TIBCO Hawk technical support.
HWKHMA-002022 Role Category Resolution HWKHMA-003000 Role Category Resolution HWKHMA-003001
Error Code List 279
Role Category Resolution HWKHMA-003002 Role Category Resolution
Error TIBCO Hawk HMA Contact TIBCO Support for assistance. Internal error. EnumProcesses failed. WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. Unable to retrieve process count. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. Function getprocs returned a process with a PID of 0. Process was skipped. Information TIBCO Hawk HMA HMA could not load NTDLL.DLL.Check path environment variable. TIBCO Hawk HMA Error HMA process could not load ntdll.dll. Make sure that PATH environment variable contains path which points to ntdll.dll. Could not locate entry point for function NtQueryInformationProcess in dll NTDLL.DLL. 'Parent Process ID' column for all processes are set to -1. TIBCO Hawk HMA Error Contact TIBCO Support for assistance Failure to obtain kernel stats for network interface <interface name>. Error TIBCO Hawk HMA Make sure TIBCO Hawk HMA is running with root permission. If not resolved then contact TIBCO Support for assistance. Failed to read kernel stats for network interface <interface name> errno <errno>. Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance.
HWKHMA-003003 Role Category Resolution HWKHMA-003004 Role Category HWKHMA-003005 Category Role Resolution
HWKHMA-003006 Category Role Resolution HWKHMA-004000 Role Category Resolution
280
| Appendix F
Error Codes
Failure to obtain kernel stats for network-related statistics <error text>. Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. get_lanstats returned error <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. get_lanstats on <id> returned <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. Unable to obtain statistics for interface name <interface name>. Warning. TIBCO Hawk HMA Statistics unavailable. No resolution necessary. <function name> socket(AF_INET,SOCK_DGRAM,0) returned [<socket>] errno[<error number] [<error text>] Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. <function name> ioctl(<socket>, <ioctl function id>,) returned [<ioctl rc>] errno[<error number] [<error text>] Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. <function name> ioctl(<socket> NIC[%d] returned [<ioctl rc>] errno[<error number] [<error text>] Warning. TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance.
Error Code List 281
lseek(<file handle>, <seek operation>, <seek position>) returned [<return code>] errno[<error number] [<error text>] Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. read(<file handle>, <buffer address>, <buffer size>) returned [<return code>] errno[<error number] [<error text>] Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. <function name> Can not open /dev/kmem file errno[<error number] [<error text>] Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. If "access denied" is indicated then make sure TIBCO Hawk HMA is running with root permission. <function name> knlist lookup on symbol [<symbol name] failed - res[<return code>] errno[<error number] [<error text>]. Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. <function name> malloc failed with errno <error number> <error text>. Error TIBCO Hawk HMA Insufficient memory available for process. Unexpected implementation of kernel stats for network interface <interface name>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. get_lanstats returned no info on interface <interface name>. Error
HWKHMA-004023 Role Category Resolution HWKHMA-004024 Role Category Resolution HWKHMA-004026 Role
282
| Appendix F
Error Codes
Category Resolution HWKHMA-004027 Role Category Resolution HWKHMA-004028 Role Category Resolution
TIBCO Hawk HMA Contact TIBCO Support for assistance. get_lanstats returned no info on interface <interface name>, nmid <nmid>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. Can not open /dev/kmem file errno[<error number] [<error text>] Error TIBCO Hawk HMA Make sure TIBCO Hawk HMA is running with root permission. If not resolved then contact TIBCO Support for assistance. Function <function name> failed for file <file name>. OS Error <OS error code> <OS error text>. TIBCO Hawk HMA Error Make sure that file indicated by error message exist at given location. Invalid record format encountered in file <file name>. TIBCO Hawk HMA Error Contact TIBCO Support for assistance. Failed to open /dev/dlpi. errno = <error number> errormessage = <error text> TIBCO Hawk HMA Error Make sure that file indicated by error message exist at given location. No Physical Point of Attachment. Network statistics not available. TIBCO Hawk HMA Error Contact TIBCO Support for assistance. <interface name> interface is attached on PPA number <PPA number>. TIBCO Hawk HMA Information putmsg stream function failed for primitive <primitive name> errno = <error number> and errormessage = <error text>. TIBCO Hawk HMA
HWKHMA-004029 Category Role Resolution HWKHMA-00 4030 Category Role Resolution HWKHMA-004031 Category Role Resolution HWKHMA-004032 Category Role Resolution HWKHMA-004033 Category Role HWKHMA-004034 Category
Error Code List 283
Role Resolution HWKHMA-004035 Category Role Resolution HWKHMA-004036
Error Contact TIBCO Support for assistance. getmsg stream function failed with errno = <error number> and errormessage = <error text>. TIBCO Hawk HMA Error Contact TIBCO Support for assistance. Name Of Driver: <driver name>, PPA Number assigned to LAN interface: <interface number>, NMID No: <nmid number>, Card Instance Number: <card instance number>, Media Access Control: <media access control>. TIBCO Hawk HMA Information Total Number of valid PPAs currently installed in system is <total ppa number>. TIBCO Hawk HMA Information Failed to retrieve proper control code for primitive <primitive name>. TIBCO Hawk HMA Error Contact TIBCO Support for assistance. Error attaching PPA number: <ppa number>. TIBCO Hawk HMA Error Contact TIBCO Support for assistance. Failed to get required control message. Expected Primitive: <primitive number>, Primitive in error : <primitive error>, DLPI error code: <dlpi error code>, UNIX error code: <unix error code> TIBCO Hawk HMA Error Contact TIBCO Support for assistance. Received Wrong Primitive. Expected Primitive: <primitive number>, Received Primitive: <primitive number>. TIBCO Hawk HMA Error Contact TIBCO Support for assistance. Received only data portion of the message. Failed to receive control portion of the
Category Role HWKHMA-004037 Category Role HWKHMA-004038 Category Role Resolution HWKHMA-004039 Category Role Resolution HWKHMA-004040
Category Role Resolution HWKHMA-004041 Category Role Resolution HWKHMA-004042
284
| Appendix F
Error Codes
Category Role Resolution HWKHMA-004043 Category Role Resolution HWKHMA-004044 Category Role Resolution HWKHMA-005000 Role Category Resolution
message TIBCO Hawk HMA Error Contact TIBCO Support for assistance. No message found in stream. May be system call was interrupted. TIBCO Hawk HMA Error Contact TIBCO Support for assistance. Failed to get Network Statistics for PPA: <ppa number>. TIBCO Hawk HMA Error Contact TIBCO Support for assistance. kstat_open() returned null, errno <error number> <error text>. Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. kstat_read() returned error, errno <error number> <error text>. Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. kstat_lookup() on %s returned null, errno <error number> <error text>. Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. kvm_open() returned error, errno <error number> <error text>. Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. kvm_nlist() returned error, errno <error number> <error text>. Error TIBCO Hawk HMA
HWKHMA-005004 Role Category
Error Code List 285
Resolution
This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. kvm_read() returned error, errno <error number> <error text>. Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. Can't open <file name> <error text>. Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. Can't knlist <error text>. Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. Failure to fseek <error text>. Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. Failure to read <error text>. Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. pstat_getdynamic() returned <return code>, errno <error number> <error text>. Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. malloc failed with errno <error number> <error text>. Error TIBCO Hawk HMA Insufficient memory available for process.
286
| Appendix F
Error Codes
pstat_getvminfo returned <return code>, errno <error number> <error text>. Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. pstat_getstatic() returned <return code>, errno <error number> <error text>. Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. ERROR returning from system swapctl function SC_LIST errno <error number> <error text>. Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. Failed to get host address for specified network parameter. Error TIBCO Hawk HMA Invalid network parameter specified in Rendezvous microagent network parameter. Refer to TIBCO Hawk Method Reference manual. hma_getHostAddr() returned <error code> for network <network parameter> and daemon <daemon parameter>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. RV transport key not found for RV advisory message: <message text>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. <function name>: received advisory message with subject: <subject name> message: <message text>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. <function name>: Failed to allocate context.
HWKHMA-006001 Role Category Resolution HWKHMA-006002 Role Category Resolution HWKHMA-006003 Role Category Resolution HWKHMA-006004
Error Code List 287
Role Category Resolution HWKHMA-006005 Role Category Resolution HWKHMA-006006 Role Category Resolution HWKHMA-006007 Role Category Resolution HWKHMA-006008 Role Category Resolution HWKHMA-006009 Role Category Resolution HWKHMA-006010 Role Category Resolution HWKHMA-006011 Role Category Resolution HWKHMA-006012 Role Category
Error TIBCO Hawk HMA Contact TIBCO Support for assistance. <function name>: Failed to allocate host status context. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. <function name>: Failed to get host name. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. <function name>: Failed to get host entry for <host name>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. <function name>: Failed to register context. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. <function name>: Unable to deregister context. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. Error getting value for argument <argument name>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. Failed to send unsolicited message: <message text>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. Failed to send pending RVD.DISCONNECTED advisory message. Error TIBCO Hawk HMA
288
| Appendix F
Error Codes
Resolution HWKHMA-006013 Role Category Resolution HWKHMA-006014 Role Category Resolution HWKHMA-006015 Role Category Resolution HWKHMA-006016 Role Category Resolution HWKHMA-006017 Role Category Resolution HWKHMA-006018 Role Category Resolution HWKHMA-006019 Role Category Resolution HWKHMA-006020 Role Category
Contact TIBCO Support for assistance. Failed to send async data on advisory message <subject name>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. <function name>: Unable to parse RV version: <version>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. <function name>: Unable to get field <field name> due to RV error: <RV error text>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. The argument "HMA_N_INTERVAL" is less than 90 seconds. It has been changed to the default value of 90 seconds. Warning TIBCO Hawk HMA Interval argument must be 90 seconds or greater. <function name>: Failed to create RV timer due to RV error: <RV error text>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. <function name>: Failed to create RV listener because of RV error: <RV error text>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. <function name>: setUpRvAdvisoryMonitoring failed. <error text> Error TIBCO Hawk HMA Contact TIBCO Support for assistance. createRvdTransport failed. <error text> Error TIBCO Hawk HMA
Error Code List 289
Resolution HWKHMA-006021 Role Category Resolution HWKHMA-006022 Role Category Resolution HWKHMA-006023 Role Category Resolution HWKHMA-006024 Role Category Resolution HWKHMA-006025 Role Category Resolution HWKHMA-006026 Role Category Resolution HWKHMA-006027 Role Category Resolution HWKHMA-006028 Role Category Resolution
Contact TIBCO Support for assistance. tibrvEvent_CreateListener failed. RV error: <RV error text>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. util_ListCreate failed with error <error code>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. util_ListFindObj failed with error <error code>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. util_ListAdd failed with error <error code>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. Unable to create new RV transport because the internal buffer limit has been exceeded. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. Required tibrvTransport argument is null. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. Unable to create RV parameter key. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. tibrvTransport_Create failed for '<session>' '<network>' '<daemon>'. RV error: <RV error text>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance.
290
| Appendix F
Error Codes
HWKHMA-006029 Role Category HWKHMA-006030 Category Role Resolution HWKHMA-006031 Category Role Resolution HWKHMA-007000 Role Category Resolution HWKHMA-007003 Role Category Resolution
Sending unsolicted message: <message text>. Information TIBCO Hawk HMA No RV daemon status was received in the last reporting interval. TIBCO Hawk HMA Error Make sure that RVD is running on the system. Unable to determine RV daemon statistics because some daemon status information were missing in the last reporting interval. TIBCO Hawk HMA Error Make sure that RVD is running on the system. PdhOpenQuery failed with error <error code>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. Object <object name> has no counters. Ignoring object. Warning TIBCO Hawk HMA Object encountered with no defined counters so no data can be returned. Object is being ignored. No action required. No open query for this subscription. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. PdhCollectQueryData for method <method name> instance <instance name> failed with error <error code>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. Object <object name> has been removed. Warning TIBCO Hawk HMA Performance object was removed by system and is no longer available. No action required.
HWKHMA-007005 Role Category Resolution HWKHMA-007006 Role Category Resolution HWKHMA-007007 Role Category Resolution
Error Code List 291
HWKHMA-007008 Role Category Resolution HWKHMA-007009 Role Category Resolution HWKHMA-007010 Role Category Resolution HWKHMA-007011 Role Category Resolution HWKHMA-007012 Role Category Resolution HWKHMA-007013 Role Category Resolution HWKHMA-007014 Role Category Resolution HWKHMA-007015 Category Role
PdhEnumObjectItems for object <object name> failed with error <error code>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. PdhEnumObjects failed with error <error code>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. PdhAddCounter for counter <counter name> failed with error <error code>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. PdhCollectQueryData for object <object name> and instance <instance name> failed with error <error code>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. PdhGetFormattedCounterValue for object <object name> and instance <instance name> and counter <counter name> failed with error <error code>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. PdhRemoveCounter for object <object name> and instance <instance name> and counter <counter id> failed with error <error code>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. PdhCloseQuery for object <object name> and instance <instance name> failed with error <error code>. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. Failed to get instance and counter information for method <methodname>. Ignoring method : <method name> TIBCO Hawk HMA Information
292
| Appendix F
Error Codes
Resolution
Specified Object (Method) does not contain any Counter and Instance Information. Skipping this Object(Method) from announcing it as a method during discovery process. Found duplicate counter name: <counter name> for method: <method name>. Ignoring method: <method name>. TIBCO Hawk HMA Information Specified Object contains duplicate counter name. Skipping this Object from announcing as method during discovery process. PdhLookupPerfNameByIndex failed with Pdh status code: <status code> <method name> TIBCO Hawk HMA Error Contact TIBCO Support for assistance. Key must be specified. Error TIBCO Hawk HMA Registry microagent key argument is a required argument. Entry must be specified. Error TIBCO Hawk HMA Registry microagent entry argument is a required argument. Value must be specified. Error TIBCO Hawk HMA Registry microagent value argument is a required argument. Invalid system key name. Error TIBCO Hawk HMA Registry microagent key argument specified is invalid or non-existent. Invalid key path. Error TIBCO Hawk HMA Registry microagent key path argument specified is invalid or non-existent.
HWKHMA-007016 Category Role Resolution
HWKHMA-007017 Category Role Resolution HWKHMA-008000 Role Category Resolution HWKHMA-008001 Role Category Resolution HWKHMA-008002 Role Category Resolution HWKHMA-008003 Role Category Resolution HWKHMA-008004 Role Category Resolution
Error Code List 293
RegOpenKeyEx failed for key <key name>. WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. RegFlushKey failed for key <key name>. WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. RegCloseKey failed for key <key name>. WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. RegQueryValueEx failed for key <key name> entry <entry name>. WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. RegEnumValue failed for key <key name>. WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. SubKey must be specified. Error TIBCO Hawk HMA Registry microagent subkey argument is a required argument. Specified key <key name> already exists. Error TIBCO Hawk HMA
HWKHMA-008014 Role Category Resolution HWKHMA-008015 Role Category
294
| Appendix F
Error Codes
Resolution HWKHMA-008016 Role Category Resolution
Attempt to create an existing key was made. RegEnumKeyEx failed for key <key name>. Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. RegCreateKeyEx failed for key <key name>. WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. RegSetValueEx failed for key <key name> entry <entry name> value <value>. WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. RegSetValueEx failed for key <key name> entry <entry name> value <value>. WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. Value for key <key name> entry <entry name> is not of type <type name>. Error TIBCO Hawk HMA Registry microagent value specified is not the specified type. Check actual registry entry for correct data type. Root key specified is invalid. Error TIBCO Hawk HMA An invalid system root key was specified. See method reference for correct system key values. RegFlushKey failed for key <key name>. WIN32 error <error code> (<error code hex>): <error text>
HWKHMA-008022
Error Code List 295
Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. RegCloseKey failed for key <key name>. WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. ExpandEnvironmentStrings failed for key <key name> entry <entry name> TIBCO Hawk HMA Error Contact TIBCO Support for assistance. Unable to retrieve source parameter. Error TIBCO Hawk HMA EventLog microagent source argument is a required argument. CreateEvent failed. WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. OpenEventLog failed for <event log name> event log. WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. beginthread failed for <event log name> event log monitoring thread. System reports error <error number> <error text>. Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance.
HWKHMA-008024 Category Role Resolution HWKHMA-009002 Role Category Resolution HWKHMA-009003 Role Category Resolution
296
| Appendix F
Error Codes
RegOpenKeyEx failed for key "<key name>". WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. RegQueryValueEx failed for value "<value name>" under key "<key name>". WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. RegCloseKey failed for key "<key name>". WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. ExpandEnvironmentStrings failed. WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. LoadLibraryEx failed for library "<library name>". WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. FormatMessage failed for event <event ID> of event source "<source name>". WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance.
Error Code List 297
Message file name of event source "<source name>" exceeds maximum size of <maximum size> characters. Error TIBCO Hawk HMA Contact TIBCO Support for assistance. RegisterEventSource failed for event source "<source name>". WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. ReportServiceEvent failed for event source "<source name>". WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. DeregisterEventSource failed for event source "<source name>". WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. <event log name> event log overrun. <event count> events lost. Warning. TIBCO Hawk HMA Due to extreme system load the EventLog microagent was unable to process new event log entries before they were discarded. This error is sent as an unsolicited message in order for rulebases to respond to this loss of events. <event log name> event record <record number> exceeded maximum size. Record skipped. Error TIBCO Hawk HMA A single event log entry exceeded the maximum size and was skipped. This error is sent as an unsolicited message in order for rulebases to respond to this skipped event. <event log name> event monitoring thread shutdown due to errors encountered. Error
HWKHMA-009016 Category Resolution
HWKHMA-009018 Role
298
| Appendix F
Error Codes
Category Resolution
TIBCO Hawk HMA The dedicated processing thread encountered an unrecoverable error and has shutdown. This error is sent as an unsolicited message in order for rulebases to respond to this thread shutdown. Failed to get description for event <record number> in source "<source name>". Error <error number> <error text>. Error TIBCO Hawk HMA This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. WaitForMultipleObjects failed. WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA Internal error. Contact TIBCO Support. WaitForMultipleObjects returned unexpected value <return code>. Error TIBCO Hawk HMA Internal error. Contact TIBCO Support. WaitForSingleObject failed. WIN32 error <error code> (<error code hex>): <error text> Error TIBCO Hawk HMA Internal error. Contact TIBCO Support. WaitForSingleObject returned unexpected value <return code>. Error TIBCO Hawk HMA Internal error. Contact TIBCO Support. NotifyChangeEventLog failed for <event log name> event log. TIBCO Hawk HMA Error This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. All attempts to reopen <event log name> event log have failed. TIBCO Hawk HMA Error
HWKHMA-009021 Role Category Resolution HWKHMA-009022 Role Category Resolution HWKHMA-009023 Role Category Resolution HWKHMA-009024 Role Category Resolution HWKHMA-009025 Category Role Resolution
HWKHMA-009026 Category Role
Error Code List 299
Resolution
The EventLog microagent in the HMA attempts to reopen a Microsoft Windows event log should its existing event log handle become invalid. This can happen if the event log is manually cleared from the Microsoft Windows Event Viewer for example. The microagent makes three (3) attempts to reopen the event log. If all three retries fail this error message is logged and also sent as an unsolicted message to the associated Hawk Agent. The event log monitoring thread is then terminated. This error indicates a serious problem with the Windows Event Log facility. If the Microsoft Windows Event Viewer does not provide a reason for this failure then contact TIBCO Support for assistance. ReadEventLog failed for <event log name> event log. TIBCO Hawk HMA Error This error will also contain the OS specific error description. If resolution is not obvious from the error description then contact TIBCO Support for assistance. The <event log name> event log has changed (e.g. cleared) between read operations. Possible loss of events. Re-opening event log. TIBCO Hawk HMA Warning This message is logged and sent as an unsolicted message to the associated Hawk Agent whenever the EventLog microagent detects that a Microsoft Windows event log has been modified by another application. The most common occurrence of this is when an event log is manually cleared via the Microsoft Windows Event Viewer. When the event log is cleared it is impossible for the microagent to get any deleted events beyond the ones it has already read so that events may have been lost. When monitoring a Microsoft Windows event log your rulebase should subscribe to the EventLog:: _onUnsolicitedMsg method so it will receive notification of this condition. All attempts to resync <event log name> event log after overrun have failed. TIBCO Hawk HMA Error This message is logged and sent as an unsolicted message to the associated Hawk Agent whenever the EventLog microagent fails in all attempts to resynchronize with the Microsoft Windows Event Log after an overrun condition. Under extreme load the EventLog microagent may not be able to process new event log events before they are aged out (deleted). When an overrun is detected the EventLog microagent logs and sends an unsolicted message to the associated Hawk Agent indicating the condition and the count of lost events. It then attempts to resynchronize (catch-up) with the event log. When monitoring a Microsoft Windows event log your rulebase should subscribe to the EventLog:: _onUnsolicitedMsg method so it will receive notification of this condition.
300
| Appendix F
Error Codes
Event category specified, <event category number>, is invalid. Category value must be between 0 and 65535 inclusive. TIBCO Hawk HMA Error Specify an event category between zero and 65353 inclusive. A zero indicates "no category". Reading variables file <variable file name> java.io.FieNotFoundException Error Application TIBCO Hawk Agent Make sure that the variables file is readable and is in the proper Java properties format. Reading variables file <variables file name> java.io.SecurityException Error Application TIBCO Hawk Agent Make sure that the variables file is readable and is in the proper Java properties format. Reading variables file <variables file name> java.io.IOException Error Application TIBCO Hawk Agent Make sure that the variables file is readable and is in the proper Java properties format. Reading variables file <variables file name> java.lang.Exception Error Application TIBCO Hawk Agent Make sure that the variables file is readable and is in the proper Java properties format. Can not determine current working directory from system property user.dir Please specify config path. Error Application TIBCO Hawk Agent Java Virtual Machines System Property "user.dir" has to be set correctly. No variables have been loaded Warning Application TIBCO Hawk Agent Make sure that the variables file is readable and is in the proper Java properties format.
HWKAGT-010201 Role Category Resolution
HWKAGT-010205 Role Category Resolution HWKAGT-010207 Role Category Resolution
Error Code List 301
HWKAGT-010208 Role Category Resolution HWKAGT-010209 Role Category Resolution HWKAGT-010210 Role Category Resolution
config path directory <path> does not yet exist. Warning Application TIBCO Hawk Agent Make sure that the specified configuration path exists config path <path> is not a directory. Warning Application TIBCO Hawk Agent Make sure that the specified configuration path is a directory config path directory <path> can not be read. Warning Application TIBCO Hawk Agent Make sure that the specified configuration path is readable and it contains TIBCO Hawk configuration files java.io.IOException Error Application TIBCO Hawk Agent An internal error occurred while waiting to read the output from the executed command. Contact TIBCO Support java.io.IOException Error Application TIBCO Hawk Agent An internal error occurred while executing the requested command. Contact TIBCO Support A process is blocking, killing it Warning Application TIBCO Hawk Agent Contact TIBCO Support The process <cmd> timed out. It was terminated. Warning Application TIBCO Hawk Agent Try executing the command from a command prompt and report the results to TIBCO Support Duplicate ami_rvd_transport parameters. Ignoring ami_rvd_transport <service> <network> <daemon> Warning Application TIBCO Hawk Agent
HWKAGT-010406 Role Category Resolution HWKAGT-010407 Role Category Resolution
HWKAGT-010502 Role Category
302
| Appendix F
Error Codes
Resolution HWKAGT-010503 Role Category Resolution HWKAGT-010902 Role Category Resolution
Check the command line arguments and remove all duplicates The rvd_transport and ami_rvd(s)_transport parameters match. Ignoring ami_rvd(s)_transport <service> <network> <daemon> Warning Application TIBCO Hawk Agent Check the command line arguments and remove all duplicates enableLogging() invoked without type Error Application TIBCO Hawk Agent Invoke the method "enableLogging() again after specifying a valid value for argument "Type" enableLogging() invoked with invalid type Error Application TIBCO Hawk Agent Invoke the method "enableLogging() again after specifying a valid value for argument "Type" disableLogging() invoked without type Error Application TIBCO Hawk Agent Invoke the method "disableLogging() again after specifying a valid value for argument "Type" disableLogging() invoked with invalid type Error Application TIBCO Hawk Agent Invoke the method "disableLogging() again after specifying a valid value for argument "Type" activateClass() invoked without class name Error Application TIBCO Hawk Agent Contact TIBCO Support deactivateClass() invoked without class name Error Application TIBCO Hawk Agent Contact TIBCO Support COM.TIBCO.hawk.microagent.Repository: Fatal error: no repository name
HWKAGT-010906 Role Category Resolution HWKAGT-010907 Role Category Resolution HWKAGT-011001
Error Code List 303
Role Category Resolution HWKAGT-011004 Role Category Resolution HWKAGT-011006 Role Category Resolution HWKAGT-011007 Role Category Resolution HWKAGT-011008 Role Category Resolution HWKAGT-011009 Role Category Resolution HWKAGT-011012 Role Category Resolution HWKAGT-011013 Role
Error Application TIBCO Hawk Agent Contact TIBCO Support Initialization of -repository_dir failed: <COM.TIBCO.hawk.agent.source.SourceException> Error Application TIBCO Hawk Agent Contact TIBCO Support COM.TIBCO.hawk.microagent.Repository: Failed to load rulebase <rulebase name>. Exception: <SourceException> Warning Application TIBCO Hawk Agent Contact TIBCO Support COM.TIBCO.hawk.microagent.Repository: Failed to load rulebase <rulebase name>. Exception: <SourceTimeoutException> Warning Application TIBCO Hawk Agent Contact TIBCO Support COM.TIBCO.hawk.microagent.Repository: Failed to load rulebase <rulebase name>. Exception: <SourceException> Warning Application TIBCO Hawk Agent Contact TIBCO Support COM.TIBCO.hawk.microagent.Repository: Failed to load rulebase <rulebase name>. Exception: <SourceTimeoutException> Warning Application TIBCO Hawk Agent Contact TIBCO Support COM.TIBCO.hawk.microagent.Repository: Failed to load schedules. Exception: <SourceException> Warning Application TIBCO Hawk Agent Contact TIBCO Support COM.TIBCO.hawk.microagent.Repository: Failed to load schedules. Exception: <SourceTimeoutException> Warning
304
| Appendix F
Error Codes
Category Resolution HWKAGT-011014 Role Category Resolution HWKAGT-011015 Role Category Resolution HWKAGT-011016 Role Category Resolution HWKAGT-011017 Role Category Resolution HWKAGT-011022 Role Category Resolution HWKAGT-011023 Role Category Resolution HWKAGT-011024 Role Category Resolution
Application TIBCO Hawk Agent Contact TIBCO Support COM.TIBCO.hawk.microagent.Repository: Failed to load rulebase map <rulebase map name>. Exception: <SourceException> Warning Application TIBCO Hawk Agent Contact TIBCO Support COM.TIBCO.hawk.microagent.Repository: Failed to load rulebase map <rulebase map name>. Exception: <SourceTimeoutException> Warning Application TIBCO Hawk Agent Contact TIBCO Support COM.TIBCO.hawk.microagent.Repository: Failed to load rulebase map <rulebase map name>. Exception: <SourceException> Warning Application TIBCO Hawk Agent Contact TIBCO Support COM.TIBCO.hawk.microagent.Repository: Failed to load rulebase map <rulebase map name>. Exception: <SourceTimeoutException> Warning Application TIBCO Hawk Agent Contact TIBCO Support COM.TIBCO.hawk.microagent.Repository: Failed to start request listener. Exception: TibrvException <> Error Application TIBCO Hawk Agent Contact TIBCO Support COM.TIBCO.hawk.microagent.Repository: Exiting on Fatal error Error Application TIBCO Hawk Agent An internal error has occurred. Contact TIBCO Support COM.TIBCO.hawk.microagent.Repository: Fatal error: Duplicate repository(<name>) detected. Error Application TIBCO Hawk Agent Contact TIBCO Support
Error Code List 305
HWKAGT-011027 Role Category Resolution HWKAGT-011028 Role Category Resolution HWKAGT-011030 Role Category Resolution HWKAGT-011034 Role Category Resolution HWKAGT-011036 Role Category Resolution HWKAGT-011038 Role Category Resolution HWKAGT-011039 Role Category Resolution HWKAGT-011042 Role Category
COM.TIBCO.hawk.microagent.Repository: Failed to send ping reply. Error Application TIBCO Hawk Agent Contact TIBCO Support COM.TIBCO.hawk.microagent.Repository: Configuration type <type> not a valid type. Error Application TIBCO Hawk Agent Contact TIBCO Support COM.TIBCO.hawk.microagent.Repository: Failed to send <type> inventory. Error Application TIBCO Hawk Agent Contact TIBCO Support COM.TIBCO.hawk.microagent.Repository: Configuration Type <type> not valid. Error Application TIBCO Hawk Agent Contact TIBCO Support COM.TIBCO.hawk.microagent.Repository: Failed to send <type> object <name>. Error Application TIBCO Hawk Agent Contact TIBCO Support COM.TIBCO.hawk.microagent.Repository: Failed to retrieve rulebase <rulebase name>. Exception: <SourceException> Warning Application TIBCO Hawk Agent Contact TIBCO Support COM.TIBCO.hawk.microagent.Repository: Failed to retrieve rulebase <rulebase name>. Exception: <SourceTimeoutException> Warning Application TIBCO Hawk Agent Contact TIBCO Support addRuleBase() invoked without RulebaseXML parameter Error Application TIBCO Hawk Agent
306
| Appendix F
Error Codes
Resolution
This internal error occurred while adding (or updating) a rulebase in the repository. Contact TIBCO Support addRuleBase() invoked without RulebaseXML parameter Error Application TIBCO Hawk Agent This internal error occurred while adding (or updating) a rulebase in the repository. Contact TIBCO Support <Pattern file access or pattern retrieval error message> Error Application TIBCO Hawk Agent Make sure that the "patternfile" argument specified to "onNewLineWithPatternFile" method is correct and the file contains at least one valid Perl5 pattern Unable to evaluate logfile name: <filename with embedded quotes> Warning Application TIBCO Hawk Agent Make sure that the file name with embedded back quotes is correct <file name> does not yet exist. Will try reopening it later Warning Application TIBCO Hawk Agent Make sure that the file name does exist and has proper read permission <file name> has been truncated. Warning Application TIBCO Hawk Agent The file being monitored has been over written by some other application java.io.IOException Error Application TIBCO Hawk Agent An internal error occurred while trying to read additional data from the logfile being monitored. Contact TIBCO Support java.io.IOException Error Application TIBCO Hawk Agent An internal error occurred while trying to close the logfile being monitored. Contact TIBCO Support
HWKLMA-070401 Role Category Resolution
HWKLMA-070402 Role Category Resolution HWKLMA-070403 Role Category Resolution HWKLMA-070602 Role Category Resolution HWKLMA-070604 Role Category Resolution
Error Code List 307
java.io.IOException Error Application TIBCO Hawk Agent An internal error occurred while waiting to read the output from the executed command. Contact TIBCO Support A process is blocking, killing it Warning Application TIBCO Hawk Agent Contact TIBCO Support The process <cmd> timed out. It was terminated. Warning Application TIBCO Hawk Agent Contact TIBCO Support getAlertIDForClear found _currentAlertID=0 : <path> Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. Attempted activation of already active node: <path> Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. Internal rbengine error, sendAlert invoked with state of NONE Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. DataSourceError with <datasource name>: <error> at, <path> Warning Application TIBCO Hawk Agent Contact TIBCO Support DataSourceError Cleared for <datasource name> at <path> Warning Application TIBCO Hawk Agent This message merely indicates that a previous data source error has now cleared. MAX_DATA_ELEMENTS exceeded, discarding data for rule <rule>
HWKLMA-070906 Role Category Resolution HWKLMA-070907 Role Category Resolution HWKRBE-040101 Role Category Resolution HWKRBE-040102 Role Category Resolution HWKRBE-040103 Role Category Resolution HWKRBE-040302 Role Category Resolution HWKRBE-040303 Role Category Resolution HWKRBE-040401
308
| Appendix F
Error Codes
Error Application TIBCO Hawk Agent Data is being produced at a rate faster than the rule can process it. Usually due to a temporarily overloaded machine. Contact TIBCO Support if this error persists. removing orphaned child at <path> Error Application TIBCO Hawk Agent Rulebase engine encountered inconsistent data from microagent. Contact TIBCO Support. cant create child: <reason> at <path> Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. cant create child: <reason> at <path> Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. invalid data type received at <path> Error Application TIBCO Hawk Agent The rule at path received an unsupported data type from the microagent. Contact TIBCO Support. getAlertIDForClear found currentAlertID=0 : <path> Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. NoValidDataSource for <rule> at <path> Error Application TIBCO Hawk Agent A valid data source does not exist for the rule. Instantiate a valid data source or modify the rulebase to use available data sources. RBEngine timer dispatch thread caught exception: <com.tibco.rv.TibrvException> Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support.
HWKRBE-040402 Role Category Resolution
HWKRBE-040403 Role Category Resolution HWKRBE-040404 Role Category Resolution HWKRBE-040405 Role Category Resolution
HWKRBE-040501 Role Category Resolution HWKRBE-040502 Role Category Resolution
Error Code List 309
HWKRBE-040902 Role Category Resolution HWKRBE-040903 Role Category Resolution HWKRBE-041202 Role Category Resolution HWKRBE-041206 Role Category Resolution HWKRBE-041303 Role Category Resolution HWKRBE-041304 Role Category Resolution HWKRBE-041306 Role Category Resolution HWKRBE-041309 Role Category Resolution HWKRBE-041311
RBEngine timer dispatch thread caught exception: <java.lang.Throwable> Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. RBEngine timer dispatch thread interrupted: <java.io.InterruptedException> Warning Application TIBCO Hawk Agent Contact TIBCO Support Attempted activation of already active node: <path> Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. Processed clear for non-existent alert. ID:<id> Reason:<reason> Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. initializing subscription for rule <name> Error Application TIBCO Hawk Agent Contact TIBCO Support. Attempted activation of already active node: <path> Error Application TIBCO Hawk Agent Contact TIBCO Support. while canceling subscription for rule <rulename>, <exception> Error Application TIBCO Hawk Agent Contact TIBCO Support. onSubscriptionPending, data source <data_source_instance> already exists. Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. initializing subscription for rule: <rulename>, microagent: <microagent name>, <exception>
310
| Appendix F
Error Codes
Role Category Resolution HWKRBE-041312 Role Category Resolution HWKRBE-041314 Role Category Resolution HWKRBE-041315 Role Category Resolution HWKRBE-041317 Role Category Resolution HWKRBE-041318 Role Category Resolution HWKRBE-041319 Role Category Resolution HWKRBE-041321 Role Category Resolution
Error Application TIBCO Hawk Agent Contact TIBCO Support. onSubscriptionError, data source <method_name>: <data_source_instance> not registered. Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. onData, data source <method_name>: <data_source_instance> not registered. Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. onData, subscription and data have inconsistent microagent id, subscription: <id>, data: <id> Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. Rule datasource error for rule <path> exception: <COM.TIBCO.hawk.talon.MicroAgentException> Warning Application TIBCO Hawk Agent Contact TIBCO Support onRoleError, data source <method_name>: <data_source_instance> not registered. Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. adding DataSourceNode <method name>, <exception> Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. onErrorCleared, data source <method_name>: <data_source_instance> not registered. Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support.
Error Code List 311
HWKRBE-041324 Role Category Resolution HWKRBE-041325 Role Category Resolution HWKRBE-041401 Role Category Resolution HWKRBE-041407 Role Category Resolution HWKRBE-041408 Role Category Resolution HWKRBE-041410 Role Category Resolution HWKRBE-041413 Role Category Resolution HWKRBE-041414 Role Category Resolution HWKRBE-041415 Role
adding DataSourceNode <method name>, <exception> Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. adding NoValidDataSourceNode <exception> Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. Attempted activation of already active node: <path> Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. cant evaluate test: <exception>, At: <path> Error Application TIBCO Hawk Agent Unable to evaluate test for stated reason. cant evaluate test: <exception>, At: <path> Error Application TIBCO Hawk Agent Unable to evaluate test for stated reason. Couldnt launch clear timer: <reason> Error Application TIBCO Hawk Agent Unable to launch timer for stated reason. Unable to evaluate action: <action>, <exception> Error Application TIBCO Hawk Agent Unable to evaluate action because of stated error. clear action is not of type ActionNode <type> Error Application TIBCO Hawk Agent Illegally formatted rulebase file. Unable to evaluate action: <action>, <exception> Error
312
| Appendix F
Error Codes
Category Resolution HWKRBE-041416 Role Category Resolution HWKRBE-041601 Role Category Resolution HWKRBE-041602 Role Category Resolution
Application TIBCO Hawk Agent Unable to evaluate action because of stated error. Unable to reset timer: <reason> Error Application TIBCO Hawk Agent Unable to restart timer for stated reason. Scheduler registering node <node> with schedule <scheduleName> node already registered. Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. Schedule <schedule name> is not loaded Warning Application TIBCO Hawk Agent Try loading the schedules file (schedules.hsf) using TIBCO Hawk Displays Schedules Editor Invalid arguments for Scheduler.deregister(), node:<node>, scheduleName:<scheduleName> Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. Scheduler deregistering node <node>. Schedule <scheduleName> not in active list. Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. Scheduler deregistering node <node> with schedule <scheduleName>, node not found. Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. Schedule <schedule name> is no longer loaded Warning Application TIBCO Hawk Agent Contact TIBCO Support
HWKRBE-041603 Role Category Resolution HWKRBE-041604 Role Category Resolution HWKRBE-041605 Role Category Resolution HWKRBE-041608 Role Category Resolution
Error Code List 313
In Scheduler.evaluateSchedules() - node <node> threw exception <exception> in response to inSchedule() call. Deregistering node from scheduler."); Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. InterruptedException in Scheduler sleep <exception> Error Application TIBCO Hawk Agent Contact TIBCO Support if this error persists. Ignoring includes list of <rulebase name>. Include lists are not supported in auto config mode. Warning Application TIBCO Hawk Agent Edit the <rulebase name> and remove all the included rulebase lists Error purging <config_file>: <exception> Error Application TIBCO Hawk Agent Unable to purge config_file from local cache. If resolution is not obvious from the error description then contact TIBCO Support for assistance. Error examining inventory of source <config_source>: <exception> Error Application TIBCO Hawk Agent Unable to examine config_source inventory. If resolution is not obvious from the error description then contact TIBCO Support for assistance. Error purging <schedules name>: <exception> Error Application TIBCO Hawk Agent Unable to purge config_source inventory cache. If resolution is not obvious from the error description then contact TIBCO Support for assistance. Error examining inventory of source <config_source>: <exception> Error Application TIBCO Hawk Agent Unable to examine config_source inventory. If resolution is not obvious from the error description then contact TIBCO Support for assistance. Error purging <rulebase name>: <exception> Error
HWKRBE-041714 Role
314
| Appendix F
Error Codes
Category Resolution
Application TIBCO Hawk Agent Unable to purge config_source inventory cache. If resolution is not obvious from the error description then contact TIBCO Support for assistance. Error examining inventory of source <rulebase name>: <exception> Error Application TIBCO Hawk Agent Unable to examine config_source inventory. If resolution is not obvious from the error description then contact TIBCO Support for assistance. Corrupt rulebase <rulebase name> from <config source>, name of the rulebase does not correspond to the name of config object. Warning Application TIBCO Hawk Agent Contact TIBCO Support Error loading rulebase <name> from <config_source>: <exception> Error Application TIBCO Hawk Agent Unable to load named rulebase from named config_source. Check configuration according to exception or contact TIBCO Support. Config object is of incorrect type: <config_object>, expected <type> Error Application TIBCO Hawk Agent Contact TIBCO Support. Requested config object <name> not found in config source Error Application TIBCO Hawk Agent Unable to locate config object in config source. Insure that it exists. Error loading <config object name> from <config source>, <SourceException> Warning Application TIBCO Hawk Agent Contact TIBCO Support Error loading <config object name> from <config source>, <SourceTimeoutException> Warning Application TIBCO Hawk Agent Contact TIBCO Support
HWKRBE-041717 Role Category Resolution HWKRBE-041719 Role Category Resolution
Error Code List 315
HWKRBE-041724 Role Category Resolution HWKRBE-041725 Role Category Resolution HWKRBE-041727 Role Category Resolution HWKRBE-041731 Role Category Resolution HWKRBE-041734 Role Category Resolution HWKRBE-041736 Role Category Resolution HWKRBE-041737 Role Category Resolution HWKRBE-041739 Role Category Resolution
Error loading <config object name> from <config source>, <java.lang.Exception> Warning Application TIBCO Hawk Agent Contact TIBCO Support Config object <config object name> was retrieved from an emergency source: <source name> Warning Application TIBCO Hawk Agent Make sure that the specified config object exists in the config source directory Config object is of incorrect type: <name>, expected Schedules.hsf Error Application TIBCO Hawk Agent Unable to locate Schedules.hsf in config source. Insure that it exists. Config object is of incorrect type: <name>, expected rbmap.hrm Error Application TIBCO Hawk Agent Unable to locate rbmap.hrm in config source. Insure that it exists. Config object is of incorrect type: <name>, expected Schedules.hsf Error Application TIBCO Hawk Agent Unable to locate Schedules.hsf in config source. Insure that it exists. Error finding rulebase: <exception> Error Application TIBCO Hawk Agent Unable to examine auto-config directory. Check path and permissions. Corrupt rulebase <rulebase name> from <config source>, name of the rulebase does not correspond to the name of config object. Warning Application TIBCO Hawk Agent Contact TIBCO Support Error loading rulebase <name> from <config_source>: <exception> Error Application TIBCO Hawk Agent Unable to load named rulebase from named config_source. Check configuration according to exception or contact TIBCO Support.
316
| Appendix F
Error Codes
Config object is of incorrect type: <name>, expected COM.TIBCO.hawk.config.rbengine.rulebase.Rulebase Error Application TIBCO Hawk Agent Unable to locate rbmap.hrm in config source. Insure that it exists. Rulebase <name> found in inventory but unable to retrieve Error Application TIBCO Hawk Agent Unable to retrieve named rulebase from config source. Check permissions. Invoking method <exception> Error Application TIBCO Hawk Agent Contact TIBCO Support. loadRuleBase() may not be invoked when agent is in auto-config mode. Use loadRuleBaseFromFile() instead. Error Application TIBCO Hawk Agent The loadRuleBase() method of the RBEngineMicroAgent was used under conditions when it is not permitted. Use the loadRuleBaseFromFile() method instead. loadRuleBase() invoked without rulebase name Error Application TIBCO Hawk Agent Modify method invocation to include a rulebase name. Corrupt rulebase <rulebase name> from <config source>, name of the rulebase does not correspond to the name of config object. Warning Application TIBCO Hawk Agent Contact TIBCO Support RuleBase file not found: <name> Error Application TIBCO Hawk Agent Insure that the named rulebase file exists. loadRuleBaseFromFile() invoked without rulebase name Error Application TIBCO Hawk Agent
HWKRBE-041746 Role Category Resolution HWKRBE-041748 Role Category Resolution HWKRBE-041752 Role Category Resolution HWKRBE-041753 Role Category
Error Code List 317
Resolution HWKRBE-041755 Role Category Resolution HWKRBE-041757 Role Category Resolution HWKRBE-041758 Role Category Resolution HWKRBE-041759 Role Category Resolution
Modify method invocation to include a rulebase name. unloadRuleBase() invoked without rulebase name Error Application TIBCO Hawk Agent Modify method invocation to include a rulebase name. sendMail: messageNotDelivered. Error Application TIBCO Hawk Agent Unable to deliver email. Check email server or sendMail method invocation. sendMail: messagePartiallyDelivered. Error Application TIBCO Hawk Agent Unable to deliver email. Check email server or sendMail method invocation. Send Mail Exception: <exception> Error Application TIBCO Hawk Agent Unable to deliver email. Check email server or sendMail method invocation as per exception or contact TIBCO Support. setSchedules() invoked without SchedulesXML parameter Error Application TIBCO Hawk Agent Contact TIBCO Support. Error saving schedules in auto-config: <exception> Error Application TIBCO Hawk Agent Check auto-config path or permissions. Error deleting rulebase: <exception> Error Application TIBCO Hawk Agent Check auto-config path or permissions. addRuleBase() invoked without RulebaseXML parameter Error Application TIBCO Hawk Agent Contact TIBCO Support.
318
| Appendix F
Error Codes
HWKRBE-041765 Role Category Resolution HWKRBE-041766 Role Category Resolution HWKRBE-042301 Role Category Resolution HWKRBE-042302 Role Category Resolution HWKRBE-042701 Role Category Resolution HWKRBE-043301 Role Category Resolution HWKRBE-043302 Role Category Resolution HWKRBE-043303 Role Category Resolution
Error saving rulebase <name> in auto-config: <exception> Error Application TIBCO Hawk Agent Check auto-config path or permissions. updateRuleBase() invoked without rulebase Error Application TIBCO Hawk Agent Contact TIBCO Support. Arbitrable node <node> threw exception <exception> in response to wonArbitration() call. Deregistering node from Arbiter. Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. Arbitrable node <node> threw exception <exception> in response to wonArbitration() call. Queued for deregistration from Arbiter. Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. Alert suspension thread interrupted, terminating thread. Error Application TIBCO Hawk Agent Contact TIBCO Support if this error persists. Fatal error in <thread_name> thread:<exception> Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. SubscriptionMultiplexer error: null event received Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. Unchecked exception thrown in SubscriptionMultiplexer thread while processing SubscribeEvent for sub: <subscription>, microagent:<id>, exception: <exception> Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support.
Error Code List 319
HWKRBE-043304
Role Category Resolution HWKRBE-043305
Unchecked exception thrown in SubscriptionMultiplexer thread while calling onSubscriptionError() for handler: <subscription>, microagent:<id>, exception: <exception> Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. Unchecked exception thrown in SubscriptionMultiplexer thread by method Subscription.cancel() for sub: <subscription>, microagent:<id>, exception: <exception> Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. Unchecked exception thrown in SubscriptionMultiplexer thread while processing MAAddedEvent for sub: <subscription>, microagent:<id>, exception: <exception> Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. Unchecked exception thrown in SubscriptionMultiplexer thread while calling onSubscriptionError() for handler: <subscription>, microagent:<id>, exception: <exception> Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. SubscriptionMultiplexer error: Unknown event type. Error Application TIBCO Hawk Agent Internal error, contact TIBCO Support. stopSubscription call failed for <microagent_id>::<subscription> Error Application TIBCO Hawk Agent Contact TIBCO Support. Inconsistent microagent state for method subscription <subscription> Error Application TIBCO Hawk Agent Contact TIBCO Support.
Role Category Resolution HWKRBE-043309 Role Category Resolution HWKMAG-020310 Role Category Resolution HWKMAG-020313 Role Category Resolution
320
| Appendix F
Error Codes
HWKMAG-020314 Role Category Resolution HWKCON-220601 Role Category Resolution HWKCON-220602 Role Category Resolution HWKCON-220603 Role Category Resolution HWKCON-220604 Role Category Resolution HWKCON-220605 Resolution Role Category Resolution HWKCON-220606 Role Category Resolution HWKCON-220607 Role Category
Attempt to remove MicroAgent more than once, <microagent_id> Error Application TIBCO Hawk Agent Contact TIBCO Support. RemoteAccessServer dispatch thread caught exception: <com.tibco.rv.TibrvException> Error Application TIBCO Hawk Agent Contact TIBCO Support RemoteAccessServer dispatch thread caught exception: <java.lang.Throwable> Error Application TIBCO Hawk Agent Contact TIBCO Support RemoteAccessServer processRequest thread caught exception: <java.lang.Throwable> Error Application TIBCO Hawk Agent Contact TIBCO Support RemoteAccessServer.processRequest(), request type= <type> <java.lang.Throwable> Error Application TIBCO Hawk Agent Contact TIBCO Support Processing groupOp error reply: <COM.TIBCO.hawk.talon.MicroAgent Exception> Error Application TIBCO Hawk Agent Contact TIBCO Support Processing groupOp error reply: <java.lang.Exception> Error Application TIBCO Hawk Agent Contact TIBCO Support Sending reply: <java.lang.Exception> Error Application TIBCO Hawk Agent
Error Code List 321
Resolution HWKCON-220608 Role Category Resolution HWKCON-220609 Role Category Resolution HWKCON-220610 Role Category Resolution HWKCON-220611 Role Category Resolution HWKCON-220701 Resolution Role Category Resolution HWKCFG-120901 Role Category Resolution HWKCFG-131101 Role Category Resolution HWKCFG-110101 Role
Contact TIBCO Support processing pingRequest: <java.lang.Exception> Error Application TIBCO Hawk Agent Contact TIBCO Support processing commitRequest: <com.tibco.rv.TibrvException> Error Application TIBCO Hawk Agent Contact TIBCO Support processing refreshRequest: <com.tibco.rv.TibrvException> Error Application TIBCO Hawk Agent Contact TIBCO Support RemoteAccessServer dispatch thread was interrupted: <java.io.InterruptedException> Warning Application TIBCO Hawk Agent Internal error, contact TIBCO Support DuplicateAgent Check dispatch thread caught exception: <exception> Error Application TIBCO Hawk Agent Make sure there is only one agent running with the same startup parameters. RBMap::toXML() - Unable to write to output stream.\n Exception: <java.io.IOException> Error Application TIBCO Hawk Agent Contact TIBCO Support Failed to convert rulebase <rulebase name> ... Error Application TIBCO Hawk Agent Contact TIBCO Support MicroAgentDescriptorReader - Unable to read DataDescriptor.\n Exception: <java.lang.Exception> Error
322
| Appendix F
Error Codes
Category Resolution HWKDIS-274404 Role Category Resolution
Application TIBCO Hawk Agent Contact TIBCO Support <COM.TIBCO.hawk.hawkeye.Error ExceptionEvent.getMessage()> Error Application TIBCO Hawk Display An internal error occurred in the TIBCO Hawk Console API. Contact TIBCO Support. <COM.TIBCO.hawk.console.hawkeye.WarningExceptionEvent.getConsoleWarni ng().getMessage()> Warning Application TIBCO Hawk Agent The warning exception event should provide additional details Unable to locate container - <container> Error Application TIBCO Hawk Display An error occurred while locating container when moving a container. Verify that the name of the container to be moved is valid. Reading variables file <file name> <java.io.FileNotFoundException> Error Application TIBCO Hawk Display An error occurred while reading the specified variables file. If the resolution is not obvious from the exception description then contact TIBCO Support. Reading variables file <file name> <java.io.SecurityException> Error Application TIBCO Hawk Display An error occurred while reading the specified variables file. If the resolution is not obvious from the exception description then contact TIBCO Support.
HWKDIS-274405 Role Category Resolution HWKDIS-271604 Role Category Resolution
HWKDIS-270502 Role Category Resolution
HWKDIS-270503 Role Category
Reading variables file <file name> <java.io.IOException> Error Application TIBCO Hawk Display An error occurred while reading the specified variables file. If the resolution is not obvious from the exception description then contact TIBCO Support. Reading variables file <file name> <java.lang.Exception> Error Application TIBCO Hawk Display
Error Code List 323
Resolution
An error occurred while reading the specified variables file. If the resolution is not obvious from the exception description then contact TIBCO Support. Unable to load variables from file <file name> Warning Application TIBCO Hawk Agent Make sure that the variables file is readable, it contains at least one valid variable and is in the proper Java properties format Unable to openDisplay Display file - <fileName> Error Application TIBCO Hawk Display An error occurred while reading the specified display file. This message is followed by a message with detail reason for the failure. Unable to openDisplay - <exception> Error Application TIBCO Hawk Display An error occurred while opening a display file. If the resolution is not obvious from the exception description then contact TIBCO Support.
Unable to initialize TIBCO Hawk Display : <COM.TIBCO.hawk.console.hawkeye.ConsoleInitializationException> Error Application TIBCO Hawk Display An error occurred while initializing TIBCO Hawk Display. If the resolution is not obvious from the exception description then contact TIBCO Support for assistance. Unable to initialize TIBCO Hawk Display : <java.lang.Throwable> Error Application TIBCO Hawk Display An error occurred while initializing TIBCO Hawk Display. If the resolution is not obvious from the exception description then contact TIBCO Support for assistance. Unable to reinitialize TIBCO Hawk Display : <COM.TIBCO.hawk.console.hawkeye.ConsoleInitializationException> Error Application TIBCO Hawk Display An error occurred while reinitializing TIBCO Hawk Display. If the resolution is not obvious from the exception description then contact TIBCO Support for assistance.
324
| Appendix F
Error Codes
Unable to reinitialize TIBCO Hawk Display : <java.lang.Throwable> Error Application TIBCO Hawk Display An error occurred while reinitializing TIBCO Hawk Display. If the resolution is not obvious from the exception description then contact TIBCO Support for assistance. Unable to find <key> in HawkGui.properties ... Error Application TIBCO Hawk Display The specified key is not found in the HawkGui.properties file. The HawkGui.properties may be corrupted or of invalid version. Verify that the version HawkGui.properties is supported. Unable to find <key> in HawkGui.properties ... Error Application TIBCO Hawk Display The specified key is not found in the HawkGui.properties file. The HawkGui.properties may be corrupted or of invalid version. Verify that the version HawkGui.properties is supported. Unable to locate node in tree - <node> Error Application TIBCO Hawk Display An error occurred while locating the specified node in the display tree. Contact TIBCO Support. Unable to locate parent node of - <node name> Error Application TIBCO Hawk Display Internal error. Contact TIBCO Support. Unable to locate node in tree - <node name> Error Application TIBCO Hawk Display Internal error. Contact TIBCO Support. Unable to locate container - <container name> Error Application TIBCO Hawk Display Internal error. Contact TIBCO Support. Unable to find container Discovered
HWKDIS-271602 Role Category Resolution HWKDIS-271603 Role Category Resolution HWKDIS-271604 Role Category Resolution HWKDIS-271605
Error Code List 325
Error Application TIBCO Hawk Display The default container Discovered is not found in the Display. A default Discovered will be created. Retry the operation. If the error persist, contact TIBCO Support. Varying versions of same rulebase <rulebase name> detected on agent <agent name> Error Application TIBCO Hawk Display Multiple rulebases with the specified name is found on different agents. Some of the rulebases may be out of date. Replace out of date rulebases with the most up to date version. Unable to open display file: <file name> - Error <java.io.FileNotFoundException> Error Application TIBCO Hawk Display TIBCO Hawk Display is unable to open the specified display file. If the resolution is not obvious from the exception description then contact TIBCO Support. Unable to open display file: <file name> - Error <java.io.StreamCorruptedException> Error Application TIBCO Hawk Display TIBCO Hawk Display is unable to open the specified display file. If the resolution is not obvious from the exception description then contact TIBCO Support. Unable to open display file: <file name> - Error <java.lang.Exceptin> Error Application TIBCO Hawk Display TIBCO Hawk Display is unable to open the specified display file. If the resolution is not obvious from the exception description then contact TIBCO Support. Unsupported resources version: <version> Error Application TIBCO Hawk Display The properties file is of different version. Check or re-install Hawk to ensure that HawkGui.properties and Display are of the same version. Missing resources file HawkGui.properties ... exiting Error Application TIBCO Hawk Display
326
| Appendix F
Error Codes
Resolution
The HawkGui.properties file is not found in the resource directory. Check or re-install Hawk to ensure that HawkGui.properties is at the proper location. Image Directory not found... Error Application TIBCO Hawk Display The image directory is not found. Check or re-install Hawk to ensure that HawkGui.properties is at the proper location. Unable to send config object. - Error <COM.TIBCO.hawk.talon.MicroAgentException> Error Application TIBCO Hawk Display An error occurred while sending rulebases or schedule to multiple agent. If the resolution is not obvious from the exception description then contact TIBCO Support for assistance. ERROR: building method invocation while performing network query/action: <exception message> Error Application TIBCO Hawk Display An error occurred while performing network query/action. The exception message should provide more details about the error. ERROR: performing network query/action: <exception message> Error Application TIBCO Hawk Display An error occurred while performing network query/action. The exception message should provide more details about the error. ERROR: parsing results while performing network query/action: <exception message> Error Application TIBCO Hawk Display An error occurred while performing network query/action. The exception message should provide more details about the error. Unable to retrieve Micro Agents from - <hostname>. - Error: <java.lang.Exception> Error Application TIBCO Hawk Display An error occurred while performing network query/action. The exception message should provide more details about the error.
Error Code List 327
Failed to invoke java command: <toolCommand>; Exception <java.lang.Exception> Error Application TIBCO Hawk Display An error occurred while invoking the specified tool command. This message is followed by a message that displays an exception that describes the error. Verify that the Java class specified is valid and the classpath for the class is included in CLASSPATH. Failed to load resources from input stream ... Error Application TIBCO Hawk Display An error occurred while loading resource such as an icon. Verify that the resources path is valid. Error saving preferences to resources file <file name>. Error Application TIBCO Hawk Display An error occurred while saving preferences to the resource file. The path of the file may be invalid or the file may have read-only access. Failed to invoke java command: <toolCommand>; Exception <java.lang.Exception> Error Application TIBCO Hawk Display An error occurred while invoking the specified tool command. This message is followed by a message that displays an exception that describes the error. Verify that the Java class specified is valid and the classpath for the class is included in CLASSPATH. IllegalAccessException: <error text> Error Application TIBCO Hawk Display An error occurred when loading the class specified for the menu command. Hawk may not have access to the definition of the class because the class is a public class. The message is followed by a message that indicates the Java class in error. IllegalArgumentException: <error text> Error Application TIBCO Hawk Display
328
| Appendix F
Error Codes
Resolution
An error occurred when loading the class specified for the menu command. Hawk may not have access to the definition of the class because the class is a public class. The message is followed by a message that indicates the Java class in error. InvocationTargetException: <error text> Error Application TIBCO Hawk Display An exception is thrown by the main or the constructor of the class specified for the menu command. The message is followed by a message that indicates the Java class in error. ExceptionInInitializerError: <error text> Error Application TIBCO Hawk Display An error occurred during static initialization of the class specified for the menu command. The message is followed by a message that indicates the Java class in error. Unable to save rulebase <rulebase name> to file <file name> Error Application TIBCO Hawk Display A error occurred while saving rulebase to a local file system. If the resolution is not obvious from the exception description then contact TIBCO Support. Unable to save Rulebase - <file name> \n <java.lang.Exception> Error Application TIBCO Hawk Display A error occurred while saving rulebase to a local file system. If the resolution is not obvious from the exception description then contact TIBCO Support. Unable to add rulebase - <rulebase name>; Exception: <java.lang.Exception> Error Application TIBCO Hawk Display A error occurred while sending the rulebase to the agent. If the resolution is not obvious from the exception description then contact TIBCO Support. Unable to add rulebase - <rulebase name>; Exception: <COM.TIBCO.hawk.talon.MicroAgentException> Error Application TIBCO Hawk Display A error occurred while sending the rulebase to the agent. If the resolution is not obvious from the exception description then contact TIBCO Support.
Error Code List 329
Unable to update rulebase - <rulebase name>; Exception: <java.lang.Exception> Error Application TIBCO Hawk Display A error occurred while sending the rulebase to the agent. If the resolution is not obvious from the exception description then contact TIBCO Support. Unable to update rulebase - <rulebase name>; Exception: <COM.TIBCO.hawk.talon.MicroAgentException> Error Application TIBCO Hawk Display A error occurred while sending the rulebase to the agent. If the resolution is not obvious from the exception description then contact TIBCO Support. Unable to unload rulebase - <rulebase name>; Exception: <java.lang.Exception> Error Application TIBCO Hawk Display A error occurred while unloading the rulebase from the agent. If the resolution is not obvious from the exception description then contact TIBCO Support. Unable to unload rulebase - <rulebase name>; Exception: <COM.TIBCO.hawk.talon.MicroAgentException> Error Application TIBCO Hawk Display A error occurred while unloading the rulebase from the agent. If the resolution is not obvious from the exception description then contact TIBCO Support. Unable to send rulebase; Exception: <COM.TIBCO.hawk.talon.MicroAgentException> Error Application TIBCO Hawk Display A error occurred while sending the rulebase to the agent. If the resolution is not obvious from the exception description then contact TIBCO Support. Unable to retrieve rulebase <rulebase name> from <agent or repository name>; Exception: <java.lang.Exception> Error Application TIBCO Hawk Display A error occurred while retrieving the rulebase from the agent (or the repository). If the resolution is not obvious from the exception description then contact TIBCO Support. Unable to load Micro Agent Descriptors from - <host name>; Exception <java.lang.Exception>
HWKDIS-332912
330
| Appendix F
Error Codes
Error Application TIBCO Hawk Display A error occurred while trying to load microagent descriptors from the agent. If the resolution is not obvious from the exception description then contact TIBCO Support. Unable to clone rulebase for - <rulebase name>; Exception <java.lang.Exception> Error Application TIBCO Hawk Display Internal Error Contact TIBCO Support. Unable to export Micro Agent Descriptors from - <host name>; Exception <java.lang.Exception> Error Application TIBCO Hawk Display A error occurred while trying to export microagent descriptors to the agent. If the resolution is not obvious from the exception description then contact TIBCO Support. Unable to retrieve Micro Agents from - <agent name>; Exception <java.lang.Exception> Error Application TIBCO Hawk Display An error occurred while retrieving micro agents from the specified agent. The exception message should provide more details about the error. Unable to execute command - <command string> Error Application TIBCO Hawk Display An error occurred while executing the specified command in the command file for Tekmon support. Verify that the command is a valid command. Unable to retrieve schedules from - <host or repository name>. - Error <java.lang.Exception> Error Application TIBCO Hawk Display An error occurred while retrieving schedules from either the agent or repository. The exception message should provide more details about the error. Unable to send Schedules; Exception - <java.lang.Exception> Error Application TIBCO Hawk Display
HWKDIS-331301 Role Category Resolution HWKDIS-332901 Role Category Resolution
Error Code List 331
Resolution
An error occurred while sending schedules to either the agent or repository. The exception message should provide more details about the error. Missing -datadir and JDBC command line options. TIBCO Hawk events will not be persistent Warning Application TIBCO Hawk Event Service Specify missing command line options if TIBCO Hawk events needs to be written to file or database. Setting data destination failed. Exiting !! Error Application TIBCO Hawk Event Service Make sure that the directory specified for -datadir command line option has write permission java.lang.NumberFormatException Error Application TIBCO Hawk Event Service Check command line options and verify that they are all correct java.lang.UnsupportedEncodingException Error Application TIBCO Hawk Event Service Check command line option -characer_encoding and verify that it is valid java.lang.Exception Error Application TIBCO Hawk Event Service Contact TIBCO Support Failed to create FT TibrvRvdTransport - <com.tibco.tibrv.TibrvException> Error Application TIBCO Hawk Event Service Check the TIBCO Rendezvous session -rvd_session command line option and verify that it is valid Exception joining fault tolerance group - <com.tibco.tibrv.TibrvException> Error Application TIBCO Hawk Event Service Check the TIBCO Rendezvous fault tolerant -ft command line option and verify that it is valid
HWKEVT-390101 Role Category Resolution
HWKEVT-390106 Role Category Resolution HWKEVT-390107 Role Category Resolution HWKEVT-390108 Role Category Resolution HWKEVT-390110 Role Category Resolution
332
| Appendix F
Error Codes
Unable to create RV session for AMI communication <com.tibco.tibrv.TibrvException> Error Application TIBCO Hawk Event Service Check the TIBCO Rendezvous session -ami_rvd_session command line option and verify that it is valid JDBC Driver is unable to insert a record for "onAgentAlive" event. <java.sql.SQLException> Error Application TIBCO Hawk Event Service Contact JDBC driver vendor for more info JDBC Driver is unable to insert a record for "onAgentExpired" event. <java.sql.SQLException> Error Application TIBCO Hawk Event Service Contact JDBC driver vendor for more info JDBC Driver is unable to insert a record for "onAlert" event. <java.sql.SQLException> Error Application TIBCO Hawk Event Service Contact JDBC driver vendor for more info JDBC Driver is unable to insert a record for "onClear" event. <java.sql.SQLException> Error Application TIBCO Hawk Event Service Contact JDBC driver vendor for more info JDBC Driver is unable to insert a record for "onMicroAgentChange" event. <java.sql.SQLException> Error Application TIBCO Hawk Event Service Contact JDBC driver vendor for more info JDBC Driver is unable to insert a record for "onRulebaseChange" event. <java.sql.SQLException> Error Application TIBCO Hawk Event Service Contact JDBC driver vendor for more info
HWKEVT-390802 Role Category Resolution HWKEVT-390803 Role Category Resolution HWKEVT-390804 Role Category Resolution HWKEVT-390805 Role Category Resolution HWKEVT-390806 Role Category Resolution HWKEVT-390807 Role Category Resolution
Error Code List 333
HWKEVT-390808 Role Category Resolution HWKEVT-390809 Role Category Resolution HWKEVT-390810 Role Category Resolution
JDBC Driver is unable to create table "HawkAgentInfo". <java.sql.SQLException> Error Application TIBCO Hawk Event Service Contact JDBC driver vendor for more info JDBC Driver is unable to create table "HawkAlertClearInfo". <java.sql.SQLException> Error Application TIBCO Hawk Event Service Contact JDBC driver vendor for more info JDBC Driver is unable to close connection. <java.sql.SQLException> Error Application TIBCO Hawk Event Service Contact JDBC driver vendor for more info
334
| Appendix F
Error Codes
| 335
Glossary
A
action. An object in a TIBCO Hawk rulebase that carries out a consequence: it sends a notification or alert, executes a command line, calls a microagent method, creates a posted condition, or sends email. An action is always related to a test (called its "parent" test), which can have any number of associated actions. active alert. An alert which has been raised and not cleared. advanced action features. Optional specifications that define when an action carries out its consequence based on the changing true or false evaluation of the actions parent test. See once only, always, maximum of X times, and escalation period. advanced test options. Optional specifications that affect the true or false state of a test based on the true or false evaluation of its test expression. See true test counter, first false, clear timer, clear test, and clear action. agent. A TIBCO Hawk autonomous process that monitors applications and systems activity. Usually one agent is installed on each computer on a network. Agents monitor by processing rulebases, which hold the logic that determines how monitoring and management will take place. Users interact with agents through TIBCO Hawk Display. An agent also uses a microagents process called the HMA process to collect data. See microagent and HMA. Agent View. The default hierarchical view of your network in TIBCO Hawk Display, with an icon for each agent. See also Canvas View.
alert. A text message posted by a TIBCO Hawk agent as a consequence of processing an action in a rulebase. Places the agent in a state of alert with regard to the monitored resource: high-level, low-level, or warning. The alert is said to be raised when the agent enters the alert state, after which the alert is active until it is cleared. An agent can have many simultaneously active alert states relating to different monitored resources. Alert states are detected and displayed by all running instances of TIBCO Hawk Display and logged by the TIBCO Hawk Event Service. Contrast with notification. alert state. The condition where an alert exists once it has been raised: active or cleared. always. A mode of action operation where the action carries out its consequence each time its parent test evaluates to true. Compare once only. AMI. See Application Management Interface. AMI Workbench. An application for invoking TIBCO Hawk microagent methods dynamically. Programmers can use the AMI Workbench to test method invocations. application. A program with which users interact. Typically distinct from systems software, which underlies application programs. See also process. API. Application Programming Interface. Application Management Interface. An agreement on procedures and TIBCO Rendezvous message formats used to instrument an application with a management interface. An AMI interface makes selected
336
| Glossary
methods of the application accessible to a TIBCO Hawk agent or other manager for the purpose of monitoring and managing the application. asynchronous. A type of microagent method. Asynchronous methods return data as it becomes available. Compare synchronous. auto-discovery. A process by which TIBCO Hawk Display detects TIBCO Hawk agents and updates to reflect the current state of agents on the network. This process continues as long as TIBCO Hawk Display is running. Also performed by the TIBCO Hawk Event Service. automatic configuration. A mode of TIBCO Hawk rulebase management where the local TIBCO Hawk agent is responsible for maintaining file copies of rulebases the user changes in memory. All rulebases in an auto-configuration directory are loaded at startup, and new or changed rulebases are saved there by the agent. Contrast manual configuration. auto-configuration directory. A directory from which all rulebase files are loaded at agent startup and to which file copies of changed rulebases are written by the TIBCO Hawk agent. with graphics editing capabilities. See also Agent View and Rulebase View. clear action. An action that takes place when the evaluation of its parent test changes from true to false. So called because an alert which might have been raised by an action when the test became true will be cleared when the test becomes false. A test can have any number of clear actions (in addition to its primary list of actions, which are triggered when the test becomes true). clear test. A test object whose true or false value is used to determine when its parent test will become false. If an alert was raised (by an action related to the test) when the parent test became true, the alert is cleared only when the clear test becomes true. A test can have only one clear test. clear timer. An advanced testing option that specifies a time period during which a test will remain true as long as its test expression has not evaluated to false. A clear timer of 15 minutes is the default behavior for tests with asynchronous data sources. configuration file. A file that customizes an application by setting definitions or parameter values at run-time. configuration path option. An option in manual configuration mode that uses a configuration path, and a list of rulebase file names. Only named rulebases are loaded at agent startup, and the agent saves no new or changed rulebases to files. See configuration path. Contrast Repository option. consequence. The activity performed by a TIBCO Hawk agent when it carries out the instructions specified by an action that is part of a rulebase. Includes sending alerts and notifications, executing commands, and invoking microagent methods. console. A centralized monitoring application that resides at one point in a network and
B
broadcast message. Messages addressed (by subject name) to any and all interested applications on the network. Compare point-to-point message.
C
Canvas View. An alternate way to view and work with agents in TIBCO Hawk Display. Provides a customizable map of your network
Glossary 337
monitors by collecting data on other points in the network. consumer. Any application that receives data. Also called a subscriber or listener. Compare producer. container. A graphical icon in the TIBCO Hawk Display main window used to organize TIBCO Hawk agents into meaningful categories for examining alerts and distributing rulebases.
distributed system. Data processing where distributed applications cooperate. drilling down. Opening containers in TIBCO Hawk Display to expose TIBCO Hawk agents and other nested containers. Used to discover the location of problems reported by color-coded alert states of container icons.
E D
data delivery interval. 1. The time period between retrieval of data samples to be used as a data source for test evaluations during rulebase processing by TIBCO Hawk agents. 2. The time period between retrieval of data samples to be used as a data source for user interaction by subscription to TIBCO Hawk microagent methods. data source. The information used by a TIBCO Hawk agent to evaluate all tests in a single rule. Consists of a microagent method, any arguments, and a data delivery interval (if the method is synchronous). dead agent. A TIBCO Hawk agent with which TIBCO Hawk Display or TIBCO Hawk Event Service cannot communicate, usually because the agent process is not running or because of a communications error. The TIBCO Hawk Event Service logs detection of dead agents and can execute a script when an agent dies. display file. A hdp file where the TIBCO Hawk Display application stores a custom container organization. distributed application. An application where component programs are distributed across two or more computers on a network. escalation period. The period of time following the false-to-true transition of an actions parent test during which the action cannot carry out its consequence. See also problem escalation. event. A discrete occurrence such as the arrival of an operating system signal, an I/O condition, or a timer interrupt. Event Service. A process that collects information about TIBCO Hawk agents. The Event Service writes this information to rolling data files. execution. A possible action consequence where the TIBCO Hawk agent passes a command line to the operating system to be carried out.
F
false host list. A list of agents that responded with a false value to a network query which included a test. Compare true host list. fault tolerance. The ability of a system or component to continue to operate correctly despite hardware or network malfunction. field. See result field. first false. An advanced testing option that specifies that a test will evaluate to true only until the first time its test expression evaluates to
338
| Glossary
false. Default behavior for tests with synchronous data sources. the agent should load at the same time. If rulebase A has rulebases C, D, and E in its include list, then an agent that loads rulebase A also loads rulebases C, D, and E.
H
hdp file. See display file. hsf file. See schedule. heartbeat. A periodic status message broadcast by a TIBCO Hawk agent. The heartbeat message tells interested applications that the agent is operating. high-level alert. An alert used to indicate a highly dangerous condition. HMA. A process used by a TIBCO Hawk agent to collect data. Most microagents included within the HMA process are specific to a particular operating system and/or hardware platform, but not all. For example, the Rendezvous microagent is included in the HMA process but is platform-independent. host. The computer on which a software process runs.
J
JRE. Java Runtime Environment.
L
load balancing. A situation where client requests are divided between two or more server processes. location transparency. A situation where an interacting application need not be aware of the physical location of another application (e.g., its IP address) when exchanging data. low-level alert. An alert used to indicate an important but not dangerous condition.
M I
IMPACT_ACTION method. A TIBCO Hawk microagent method that takes some action affecting a resource managed by the microagent and does not return any information. IMPACT_ACTION_INFO method. A TIBCO Hawk microagent method that takes some action affecting a resource managed by the microagent and also returns data. IMPACT_INFO method. A TIBCO Hawk microagent method that returns data. include list. An advanced feature of rulebases. A rulebase can have a list that of other rulebases
manual configuration. A TIBCO Hawk configuration mode where the user maintains disk versions of configuration objects. manual configuration path. A list of directories or Repositories (separated by colons in UNIX or semicolons in Windows) which directs a TIBCO Hawk agent to locations of rulebase files to load at agent startup. A list of rulebase files must also be specified if manual configuration is used. Also used to search for rulebases specified with the RuleBaseEngine:loadRuleBase method. maximum of x times, no sooner than every y minutes. A mode of action operation intermediate between the once only and always
Glossary 339
options where the action carries out its consequence on some true test evaluations after the first true test evaluation, but not on every one. For example, paging a systems administrator at least every five minutes and no more than three times. Compare always, once only. MB. Megabytes. medium-level alert. An alert used to indicate a mildly dangerous condition. method. A function that can be performed by a TIBCO Hawk microagent. method call. Invocation of a microagent method. microagent. An object used by a TIBCO Hawk agent to collect information and carry out tasks, usually relating to one type of managed resource or one managed application.
O
once only. A mode of action operation where the action carries out its consequence only the first time its parent test evaluates to true. Using variable substitution can affect this behavior. Compare always. operator value. A text, numerical or Boolean value to which the value of a test parameter is compared in order to determine the true or false evaluation of a test expression.
P
parameter. See test parameter. Perl5PatternMatch. A type of regular expression syntax. Use in test expressions in a TIBCO Hawk rulebase. See also regular expression. point-to-point message. A message addressed (by inbox name) to a single destination. To send a point-to-point message, the sending application must know the inbox name of the destination endpoint. Compare broadcast message. posted condition. An internal alert message to other rules in the same rulebase. Posted conditions are created and assigned a value when a Post Condition action is triggered in a rulebase. preferences. Customization settings that affect the appearance and behavior of objects in TIBCO Hawk Display. Preferences are stored locally on each machine, in a file named HawkPreference.properties. problem escalation. A process where a TIBCO Hawk agent responds flexibly to a continuing or worsening condition by carrying out a series of actions depending on how long the condition has existed. See also escalation period.
N
network action. A method invocation sent from TIBCO Hawk Display to multiple TIBCO Hawk agents on a network where the method takes some action. network query. A method invocation sent from TIBCO Hawk Display to multiple TIBCO Hawk agents on a network where the method returns some information. A test may optionally be applied to the result of the invocation, in which case only a true or false value is retrieved from each agent. notification. A text message posted by a TIBCO Hawk agent as a consequence of processing an action in a rulebase. Detected and displayed by any listening TIBCO Hawk Display application or TIBCO Hawk Event Service. Contrast with alert.
340
| Glossary
process. A program in execution by a computer. Includes applications, system software, and support processes used by either of these types of programs. May contain one or more executable threads. See also application. producer. Any application that sends messages. Compare consumer. publish. To send messages, addressed by subject name, to any number of anonymous subscribers. Compare subscribe. publish-subscribe. A communications paradigm that includes entities which publish data and entities that subscribe to data. maps to the Repository, where they can be accessed by all agents. Agents use Repositories specified in the command line option repository_list. The -name option assigns each Repository a name when it is started. Multiple Repositories can be provide fault-tolerance, load balancing, or both. See also rulebase map. Repository option. An option in manual configuration mode that uses one or more Repositories, and a list of rulebase file names. Rulebases in the Repository are loaded at agent startup, and the agent saves no new or changed rulebases to files. See Repository and manual configuration mode. Contrast configuration path option. request. A message that asks for service, either from a specific server, or from one or more anonymous servers. To send a request. result field. One item of data returned by a microagent method as a portion of its complete result.
Q
query. See network query.
R
record. See result record. recovering agent. A TIBCO Hawk agent on which an alert has recently been cleared. REGEXP. A type of regular expression syntax. Use in method arguments in a TIBCO Hawk rulebase. See also regular expression. regular expression. A character string used for pattern matching. Use Perl5PatternMatch in test expressions, and REGEXP in method arguments. reply. A point-to-point message sent in response to a request, usually containing the desired information or confirming that the desired service has been performed. To send a reply to a requestor. Repository. An application on the network that serves configuration objects to agents. Users send updated rulebases, schedules and rulebase
result record. One in a series of similar sets of data returned by a microagent method. rolling log file. When an application writes to a rolling log file it follows this scheme. When one log file has reached a maximum size, it is closed and renamed, and a new log file with the same name is started. When the number of files of a particular type exceeds a maximum, log entries roll over to reuse the oldest log file. routing daemon. A TIBCO Rendezvous daemon process that connects multiple networks by routing messages across network boundaries. Systems administrators configure the routing daemon and arrange for it to run on each network. rule. A set of monitoring activities that use a common source of information. A rule has three parts: a data source, one or more tests, and one or more actions.
Glossary 341
rulebase. A configuration object that contains one or more rules. Rules define information sources monitored by the agent, conditions under which the agent acts, and actions to take when the conditions exist. See rule. rulebase map. A configuration object that maps rulebases to TIBCO Hawk agents and Repositories on your network. You can define groups of agents to streamline distribution. Rulebase View. An alternate way to view your network in TIBCO Hawk Display, with an icon for each rulebase. See also Agent View and Canvas View.
T
target list. In a TIBCO Hawk network query or action, a list of TIBCO Hawk agents to whom a microagent method invocation is sent. test expression. A statement which when evaluated will be true or false based on the value of a test parameter. test operator. An operation which is to be applied to a the value of a test parameter in order to determine if the test expression is true or false. test parameter. Data to be examined in order to determine if a test expression is true or false. Can be a microagent method result field or the value of a posted condition. test. An object that can have a true or false value. Operates on a data source in a rulebase as part of a rule. Used by a TIBCO Hawk agent to determine conditions under which actions should be taken when monitoring a resource. Consists of a test expression and additional attributes that affect the overall true or false value of the test. Also referred to as a test object. thread. One of a group of independently-executing tasks within a process. Threads in the same process share virtual address space, global variables and operating system resources. TIBCO Hawk domain. A name used to separate machines into independent, isolated environments for monitoring systems and applications. TIBCO Rendezvous daemon. A process that manages TIBCO Rendezvous message traffic on one computer in a network. TIBCO Rendezvous routing daemon. A TIBCO Rendezvous daemon process that connects multiple networks by routing messages across network boundaries. Systems administrators
S
schedule. A configuration object that controls when a rulebase object is active or inactive. Schedules can be applied to rulebases, rules, tests, and actions. They stored in a single Schedules.hsf file on each agent machine. subject. A user-meaningful name for identifying data objects. Subjects are hierarchical so that data can be grouped in meaningful ways. For example, the subject names _LOCAL._HAWK.AMI.START and _LOCAL._HAWK.AMI.DISCOVER differ only in their last element (START or DISCOVER, the messages specific role in the AMI discovery process), so all other elements are identical. Compare publish. subject-based addressing. A message addressing technique that uses subject names to denote messages destinations, decoupling producers from consumers. synchronous. A type of microagent method. Synchronous methods return data whenever it is requested. Compare asynchronous.
342
| Glossary
configure the routing daemon and arrange for it to run on each network. timeout. The condition where a process with which communication has been attempted has not responded within a preset period of time. true host list. A list of agents that responded with a true value to a network query which included a test. Compare false host list. true test counter. An advanced test option which specifies the number of times a test expression must evaluate to true before the entire test evaluates to true.
U
unsolicited message. A message sent from an application (usually an application instrumented with a TIB/Hawk Application Management Interface) to a TIBCO Hawk agent asynchronously. Can be of three types: information, warning, and error. Can be detected by TIBCO Hawk agents processing rulebases.
V
variable substitution. A method of instructing a TIBCO Hawk agent to insert information available into action text when the action is performed. Types of variables that can be referenced include environment variables, elements of the current rulebase and microagent method result fields.
TIBCO Software Inc. End User License Agreement 343
TIBCO Software Inc. End User License Agreement

READ THIS END USER LICENSE AGREEMENT CAREFULLY. BY DOWNLOADING OR INSTALLING THE SOFTWARE, YOU AGREE TO BE BOUND BY THIS AGREEMENT. IF YOU DO NOT AGREE TO THESE TERMS, DO NOT DOWNLOAD OR INSTALL THE SOFTWARE AND RETURN IT TO THE VENDOR FROM WHICH IT WAS PURCHASED. RETURNS BY THE ORIGINAL PURCHASER WITHIN THIRTY (30) DAYS OF THE PURCHASE DATE WILL RECEIVE A FULL REFUND. Upon your acceptance as indicated above, the following shall govern your use of the Software except to the extent all or any portion of the Software (a) is subject to a separate written agreement, (b) includes a separate "click-on" license agreement as part of the download or installation process, or (c) is provided by a third party under the terms set forth in an Addenda at the end of this Agreement, in which case the terms of such addenda shall control over inconsistent terms with regard to such portion(s). License Grant. The Software is the property of TIBCO or its licensors and is protected by copyright and other laws. While TIBCO continues to own the Software, TIBCO hereby grants to Customer a limited, non-transferable, non-exclusive, license to use the number of Permitted Instances set forth in the Ordering Document, in machine-readable, object code form and solely for Customer's internal business use. Restrictions. Customer agrees not to (a) make more copies than the number of Permitted Instances plus a reasonable number of backups; (b) provide access to the Software to anyone other than employees, contractors, or consultants of Customer; (c) sublicense, transfer, assign, distribute to any third party, pledge, lease, rent, or commercially share the Software or any of Customer's rights under this Agreement (for the purposes of the foregoing a change in control of Licensee is deemed to be an assignment); (d) use the Software for purposes of providing a service bureau, including, without limitation, providing third-party hosting, or third-party application integration or application service provider-type services, or any similar services; (e) use the Software in connection with ultrahazardous activities, or any activity for which failure of the Software might result in death or serious bodily injury to Customer or a third party; or (f) directly or indirectly, in whole or in part, modify, translate, reverse engineer, decrypt, decompile, disassemble, make error corrections to, create derivative works based on, or otherwise attempt to discover the source code or underlying ideas or algorithms of the Software. Beta and Evaluation Licenses. Notwithstanding the foregoing, if the Software is being provided for demonstration, beta testing, or evaluation purposes, then Customer agrees (a) to use the Software solely for such purposes, (b) that the Software will not be used or deployed in a production environment, and (c) that such use shall automatically terminate upon the earlier of thirty days from the date Customer receives the right to install the Software, or Customer's receipt of notice of termination from TIBCO. Technical Support. Provided Customer has paid applicable support fees (not included with Software fees unless separately listed), TIBCO shall provide support for generally available TIBCO Software on an annual basis commencing on the Purchase Date, as follows ("Support"): Customer shall designate at TIBCO's support website https://support.tibco.com/eSupport/newuser.html, the number of technical support contacts permitted under the level of Support purchased (contacts are changeable upon 48-hours prior written notice to TIBCO). Each contact may contact TIBCO for problem resolution during TIBCO's published support hours corresponding to the level of Support fees paid. Upon notice from a contact of a Software problem which can be reproduced at a TIBCO support facility or via remote access to Customer's facility, TIBCO shall use reasonable efforts to correct or circumvent the problem according to its published support objectives. TIBCO reserves the right to make changes only to the most currently available version. TIBCO will use reasonable efforts to support the previously released version of the Software for a maximum of six months. TIBCO shall have no obligation to support the Software (i) for use on any computer system running other than the operating system software for which the Software is approved (as set forth in the Software documentation) and licensed hereunder, or (ii) if Customer has modified or authorized a third party to modify the Software. TIBCO shall have no obligation to modify any version of the Software to run with any new versions of any operating system, or any other third party software or hardware. If Customer purchases Support for any Software, Customer must purchase the same level of Support for all copies of the Software for which it is licensed. Support may be extended for one-year periods on the anniversary of each Purchase Date at the standard amounts set forth in its price list, for as long as TIBCO offers Support. Customer may reinstate lapsed support for any then currently supported Software by paying all Support fees in arrears and any applicable reinstatement fee. Upgrades, patches, enhancements, bug fixes, new versions and/or new releases of the Software provided from time to time under Support shall be used only as replacements to existing Permitted Instances, and shall not be deemed to increase that number, and use thereof shall be governed by the terms of this Agreement, except for the first paragraph of the Limited Warranty and any right of return or refund. Consulting Services. Customer may request additional services ("Services") either in an Ordering Document, or by a separate mutually executed work order, statement of work or other work-request document incorporating this Agreement (each, a "Work Order"). Unless otherwise expressly agreed to in a Work Order, all Services and any work product therefrom shall be (a) performed on a time and materials basis, plus meals, lodging, travel, and other expenses reasonably incurred in connection therewith, (b) deemed accepted upon delivery, and (c) exclusively owned by TIBCO (except for confidential information of Customer identified to TIBCO in the Ordering Document), including all right, title and intellectual property or other right or interest therein. Each Work Order is intended to constitute an independent and distinct agreement of the parties, notwithstanding that each shall be construed to incorporate all applicable provisions of this Agreement. Specific to TIBCO training services, additional information regarding courses, registration, restrictions or limitation can be found at TIBCO's website at http://www.tibco.com/services/education under Education Programs. Fees for Services shall be due and payable in United States dollars net 30 from the date of TIBCO's invoice. Limited Warranty. If Customer obtained the Software directly from TIBCO, then TIBCO warrants that for a period of thirty (30) days from the Purchase Date: (i) the media on which the Software is furnished will be free of defects in materials and workmanship under normal use; and (ii) the Software will substantially conform to its published specifications. This limited warranty extends only to the original Customer hereunder. Customer's sole and exclusive remedy and the
344
| TIBCO Software Inc. End User License Agreement

entire liability of TIBCO and its suppliers under this limited warranty will be, at TIBCO's option, repair, replacement, or refund of the Software and applicable Support fees, in which event this Agreement shall terminate upon payment thereof. This warranty does not apply to any Software which (a) is licensed for beta, evaluation, testing or demonstration purposes for which TIBCO does not receive a license fee, (b) has been altered or modified, except by TIBCO, (c) has not been installed, operated, repaired, or maintained in accordance with instructions supplied by TIBCO, (d) has been subjected to abnormal physical or electrical stress, misuse, negligence, or accident, or (e) is used in violation of any other term of this Agreement. Customer agrees to pay TIBCO for any Support or Services provided by TIBCO related to a breach of the foregoing on a time, materials, travel, lodging and other reasonable expenses basis. If Customer obtained the Software from a TIBCO reseller or distributor, the terms of any warranty shall be as provided by such reseller or distributor, and TIBCO provides Customer no warranty with respect to such Software. EXCEPT AS SPECIFIED IN THIS LIMITED WARRANTY, THE SOFTWARE, SUPPORT AND SERVICES ARE PROVIDED "AS IS", ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS, AND WARRANTIES INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTY OR CONDITION OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, SATISFACTORY QUALITY OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE, ARE HEREBY EXCLUDED TO THE EXTENT ALLOWED BY APPLICABLE LAW. NO WARRANTY IS MADE REGARDING THE RESULTS OF ANY SOFTWARE, SUPPORT OR SERVICES OR THAT THE SOFTWARE WILL OPERATE WITHOUT ERRORS, PROBLEMS OR INTERRUPTIONS, OR THAT ERRORS OR BUGS IN THE SOFTWARE WILL BE CORRECTED, OR THAT THE SOFTWARE'S FUNCTIONALITY OR SERVICES WILL MEET CUSTOMER'S REQUIREMENTS. NO TIBCO DEALER, DISTRIBUTOR, AGENT OR EMPLOYEE IS AUTHORIZED TO MAKE ANY MODIFICATIONS, EXTENSIONS OR ADDITIONS TO THIS WARRANTY. Indemnity. If Customer obtained the Software from TIBCO directly, then TIBCO shall indemnify Licensee from and against any final judgment by a court of competent jurisdiction, including reasonable attorneys' fees, that the unmodified TIBCO Software infringes any patent issued by the United States, Canada, Australia, Japan, or any member of the European Union, or any copyright, or any trade secret of a third party; provided that TIBCO is promptly notified in writing of such claim, TIBCO has the exclusive right to control such defense and/or settlement, and Licensee shall provide reasonable assistance (at TIBCO's expense) in the defense thereof. In no event shall Licensee settle any claim, action or proceeding without TIBCO's prior written approval. In the event of any such claim, litigation or threat thereof, TIBCO, at its sole option and expense, shall (a) procure for Licensee the right to continue to use the TIBCO Software or (b) replace or modify the TIBCO Software with functionally equivalent software. If such settlement or modification is not commercially reasonable (in the reasonable opinion of TIBCO), TIBCO may cancel this Agreement upon sixty days prior written notice to Licensee, and refund to Licensee the unamortized portion of the license fees paid to TIBCO by Licensee based on a five-year straight-line depreciation. This Section states the entire liability of TIBCO with respect to the infringement of any Intellectual Property rights, and Licensee hereby expressly waives any other liabilities or obligations of TIBCO with respect thereto. The foregoing indemnity shall not apply to the extent any infringement could have been avoided by use of the then-current release. Limitation of Liability. EXCEPT AS PROVIDED UNDER INDEMNITY OR RESULTING FROM A BREACH OF CONFIDENTIALITY (THE "EXCLUDED MATTERS"), IN NO EVENT WILL EITHER PARTY BE LIABLE FOR ANY LOST DATA, LOST REVENUE, LOST PROFITS, DAMAGE TO REPUTATION, BUSINESS INTERRUPTION, OR ANY OTHER INDIRECT, INCIDENTAL, CONSEQUENTIAL, SPECIAL, PUNITIVE, EXEMPLARY OR ANY SIMILAR TYPE DAMAGES ARISING OUT OF THIS AGREEMENT, THE USE OR THE INABILITY TO USE THE SOFTWARE, OR THE PROVISION OF ANY SUPPORT OR SERVICES, EVEN IF A PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. EXCEPT FOR THE EXCLUDED MATTERS, IN NO EVENT SHALL A PARTY BE LIABLE TO THE OTHER, WHETHER IN CONTRACT, TORT (INCLUDING ACTIVE OR PASSIVE NEGLIGENCE), BREACH OF WARRANTY, CLAIMS BY THIRD PARTIES OR OTHERWISE, EXCEED THE PRICE PAID BY CUSTOMER UNDER THE APPLICABLE ORDERING DOCUMENT. THE FOREGOING LIMITATIONS SHALL APPLY EVEN IF THE ABOVE-STATED REMEDY OR LIMITED WARRANTY FAILS OF ITS ESSENTIAL PURPOSE. BECAUSE SOME STATES OR JURISDICTIONS DO NOT ALLOW LIMITATION OR EXCLUSION OF CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATION MAY NOT APPLY TO CUSTOMER. Confidentiality. "Confidential Information" means the terms of this Agreement; all information marked by the disclosing party as proprietary or confidential; any provided software, related documentation or related performance test results derived by Licensee; and any methods, concepts or processes utilized in provided software or related documentation. Confidential Information shall remain the sole property of the disclosing party and shall not be disclosed to any non-Authorized User without the prior written consent of the disclosing party. If Confidential Information is communicated orally, such communication shall be confirmed as "Confidential" in writing within thirty days of such disclosure. The parties agree to protect the Confidential Information of the other in the same manner it protects the confidentiality of similar information and data of its own (and at all times exercising at least a reasonable degree of care). Except with respect to the Software, items will not be deemed Confidential Information if (i) available to the public other than by a breach of an agreement with TIBCO, (ii) rightfully received from a third party not in breach of any obligation of confidentiality, (iii) independently developed by one party without use of the Confidential Information of the other; (iv) known to the recipient at the time of disclosure (other than under a separate confidentiality obligation); or (v) produced in compliance with applicable law or court order, provided the other party is given reasonable notice of the same. Both parties agree to indemnify the other for any damages the other may sustain resulting from their unauthorized use and/or disclosure of the other's Confidential Information. Such damages shall include reasonable expenses incurred in seeking both legal and equitable remedies. To the extent required by law, at Customer's request, TIBCO shall provide Customer with the interface information needed to achieve interoperability between the Software and another independently created program, on payment of TIBCO's applicable fee. Customer agrees to observe obligations of confidentiality with respect to such information. Export. Software, including technical data, is subject to U.S. export control laws, including the U.S. Export Administration Act and its associated regulations, and may be subject to export or import regulations in other countries. Customer agrees to comply strictly with all such regulations and agrees to obtain all necessary licenses to export, re-export, or import Software.
TIBCO Software Inc. End User License Agreement 345
Government Use. If the Customer is an agency, department, or other entity of the United States Government ("Government"), the use, duplication, reproduction, release, modification, disclosure or transfer of the Software, or any related documentation of any kind, including technical data or manuals, is restricted in accordance with Federal Acquisition Regulation ("FAR") 12.212 for civilian agencies and Defense Federal Acquisition Regulation Supplement ("DFARS") 227.7202 for military agencies. The Software is commercial computer software and commercial computer software documentation. Use of the Software and related documentation by the Government is further restricted in accordance with the terms of this Agreement, and any modification thereto. Orders. An Ordering Document shall be deemed accepted only by issuance of a TIBCO invoice and solely for purposes of administrative convenience. None of the terms of the Ordering Document (other than the Software product name, number of Permitted Instances, level of Support, description of Services, and fees due in connection therewith) shall apply for any reason or purpose whatsoever, regardless of any statement on any Ordering Document to the contrary, unless countersigned by an officer of TIBCO. This Agreement constitutes the entire agreement between the parties with respect to the use of the Software, Support and Services, and supersedes all proposals, oral or written, and all other representations, statements, negotiations and undertakings relating to the subject matter hereof. All orders of Software, Support or Services by Customer from TIBCO shall be deemed to occur under the terms of this Agreement (with or without reference to this Agreement), unless expressly superseded by a signed written Agreement between the parties. Software shall be delivered electronically (unless physical shipment is specifically set forth in an Ordering Document), and such delivery shall occur upon e-mail of download information to Licensee at the email address set forth in the Ordering Document or as otherwise provided by Customer to TIBCO. Physical deliveries (if applicable) of Software and documentation which typically accompanies the Software on delivery shall be on CD-ROM, FOB TIBCO, and delivery shall occur by depositing the CD-ROM with TIBCO's overnight carrier (at no charge to Customer). Term and Termination. Support or Services may be terminated: (a) by either party upon a default of the other, such default remaining uncured for fifteen days from written notice from the non-defaulting party; (b) upon the filing for bankruptcy or insolvency of the other party, (c) by either party upon prior written notice at least sixty days prior to the end of any annual Maintenance period; or (d) by Licensee (for Services), upon ten days prior written notice. Termination of Support or Services shall not terminate this Agreement. Customer may terminate this Agreement in its entirety at any time by destroying all copies of the Software. Upon termination of this Agreement in its entirety, for any reason, Customer must cease using and return or destroy all copies of the Software. Customer's obligation to pay accrued charges and any fees due as of the date of termination, as well as the sections entitled "Confidentiality", "Limited Warranty" and "Limitation of Liability" shall survive any such termination. Authority. You hereby represent and warrant that you have full power and authority to accept the terms of this Agreement on behalf of Customer, and that Customer agrees to be bound by this Agreement. General. Fees on the Ordering Document (all to be paid on the latter of thirty days from Invoice by TIBCO or the date set forth in the Ordering Document) do not include sales, use, withholding, value-added or similar taxes, and Customer agrees to pay the same, excluding therefrom taxes related to TIBCO's income and corporate franchise tax. Customer agrees to pay all reasonable costs incurred (including reasonable attorneys' fees) in collecting past due amounts under this Agreement. Except as set forth in the Section entitled
"Limited Warranty" all fees paid under or in connection with this Agreement are non-refundable and no right of set-off exists. All payments of fees due shall be made in U.S. dollars, net 30 from Purchase Date, or, for any other amounts coming due hereafter, net 30 from TIBCO's invoice. A service charge of one and one-half percent per month will be applied to all invoices that are not paid on time. Licensee agrees to pay all sales, use, value-added, withholding, excise and any other similar taxes or government charges, exclusive of TIBCO's income taxes. No delay in the performance of any obligation by either party, excepting all obligations to make payment, shall constitute a breach of this Agreement to the extent caused by force majeure. Customer hereby grants TIBCO and its independent auditors the right to audit Customer's compliance with this Agreement. If any portion of this Agreement is found to be void or unenforceable, the remaining provisions shall remain in full force and effect. This Agreement shall be governed by and construed in accordance with the laws of the State of California, United States of America, as if performed wholly within the state and without giving effect to the principles of conflict of law. The state and/or federal courts in San Francisco, California, USA, shall have exclusive jurisdiction of any action arising out of or relating to this Agreement. The United Nations Convention on Contracts for the International Sale of Goods is excluded from application hereto. If any portion hereof is found to be void or unenforceable, the remaining provisions of this Agreement shall remain in full force and effect. Definitions. In connection with this Agreement, the following capitalized terms shall have the following meaning: "Agreement" means this End User License Agreement; "Connection" for the TIBCO Software product TIBCO Enterprise for JMS - Full Edition means a TIBCO Enterprise for JMS client connection to the TIBCO Enterprise for JMS server for the purpose of sending or receiving messages and for the purposes of the TIBCO Software products TIBCO SmartSockets and TIBCO SmartMQ software products, a Connection means any network protocol link established with such TIBCO Software (directly or indirectly) to any other entity, including but not limited to software, firmware or hardware; "Customer" means the original purchaser or licensee of the Software and any permitted successors and assigns; "Developer" means one user/developer of a TIBCO Software product for use in Development; "Development" means used for software development purposes only; "Enterprise" means an unlimited number of Permitted Instances for a period of one year from the Purchase Date (unless otherwise set forth in the Ordering Document), at which time existing licenses convert to perpetual and Customer may not thereafter deploy additional Permitted Instances, and in any event, shall (during the one-year unlimited deployment period) exclude any entity which acquires, is acquired by, merged into, or otherwise combined with Customer. Customer hereby agrees to provide TIBCO with notice of the number of Permitted Instances deployed at the end of such one-year period within thirty days thereafter; "Fab" means unlimited use for shop-floor manufacturing applications at a Site; "Workstation" shall mean a single end-user computer that is generally intended to be accessed by one person at a time; "Ordering Document" means any purchase order or similar document or agreement requesting Software, Support or Services; "Permitted Instance(s)" means the number of copies of Software running on a Server Instance, Workstation, User, or Development basis, on a designated Platform, as set forth in an Ordering Document, including, without limitation, Enterprise, Site and Fab licensing; "Platform" means the operating system set forth in an Ordering Document; "Purchase Date" means the date the Ordering Document is accepted by TIBCO; "Server Instance" means a computer with 1 CPU (unless otherwise set forth in the Ordering Document) performing common services for multiple machines; "Site" means an unlimited number of Permitted Instances at a specific physical address set forth in the Ordering Document (or, in the absence of any address, at Customer's corporate headquarters);
346
| TIBCO Software Inc. End User License Agreement

"Software" means the software products listed in an Ordering Document (except as provided in the second paragraph hereof), in whole and in part, along with their associated documentation; "TIBCO" means TIBCO Software Inc.; and "Named User" means the number of named users with access to the Software. Special Product Provisions. TIBCO BusinessPartner: Customer may sublicense to third parties ("Partners") up to the total Number of Copies of TIBCO BusinessPartner, provided that for every such sublicense, the Number of Copies Customer is licensed to use shall be reduced by the same number, and provided further that prior to delivery of TIBCO BusinessPartner to a Partner, such Partner agrees in writing (a) to be bound by terms and conditions at least as protective of TIBCO as the terms of this Agreement, (b) that TIBCO BusinessPartner be used solely to communicate with Customer's implementation of TIBCO BusinessConnect, and (c) for such Partner to direct all technical support and Maintenance questions directly to Customer. Customer agrees to keep records of the Partners to which it distributes TIBCO BusinessPartner, and to provide TIBCO the names thereof (with an address and contact name) within sixty days of the end of each quarter. Third Party Software: Use of any other third-party software identified by its company and/or product name or otherwise designated in Licensee's Ordering Document (collectively "Third Party Software") is subject solely to the terms and conditions of the click-wrap or shrink-wrap license agreement included with the Third Party Software products, and for which TIBCO shall be an intended third-party beneficiary of same. TIBCO shall have no obligation whatsoever in connection with the Third Party Software (including, without limitation, any obligation to provide maintenance or support) and the provision of Third Party Software is accomplished solely as an accommodation and in lieu of Customer purchasing a license to Third Party Software directly from the third party vendor. Embedded/Bundled Products: Some TIBCO Software embeds or bundles other TIBCO Software (e.g., TIBCO InConcert bundles TIBCO Rendezvous). Use of such embedded or bundled TIBCO Software is solely to enable the functionality of the TIBCO Software licensed on the Cover Page, and may not be used or accessed by any other TIBCO Software, or for any other purpose. Open Source Software: If Licensee uses Open Source software in conjunction with the TIBCO Software, Licensee must ensure that its use does not (i) create, or purport to create, obligations of use with respect to the TIBCO Software, or (ii) grant, or purport to grant, to any third party any rights to or immunities under TIBCO's intellectual property or proprietary rights in the TIBCO Software. You also may not combine the TIBCO Software with programs licensed under the GNU General Public License ("GPL") in any manner that could cause, or could be interpreted or asserted to cause, the TIBCO Software or any modifications thereto to become subject to the terms of the GPL. Copyright (c) 1994-2003 TIBCO Software Inc. ALL RIGHTS RESERVED.
Third Party Software License Agreements 347
Third Party Software License Agreements

The following are the software licenses for the Third Party Software provided in connection with the software. Copyright (c) 2000 The Apache Software Foundation. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment: "This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear. 4. The names "Apache" and "Apache Software Foundation" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact apache@apache.org. 5. Products derived from this software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation. THIS SOFTWARE IS PROVIDED `ÀS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ==================================================== ================ This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation. For more information on the Apache Software Foundation, please see <http://www.apache.org/>. Portions of this software are based upon public domain software originally written at the National Center for Supercomputing Applications, University of Illinois, Urbana-Champaign.
The Apache Software License, Version 1.1 Copyright (c) 2001 The Apache Software Foundation. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment: "This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear. 4. The names "Crimson" and "Apache Software Foundation" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact apache@apache.org. 5. Products derived from this software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation. THIS SOFTWARE IS PROVIDED `ÀS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ==================================================== This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation and was originally based on software copyright (c) 1999, Sun Microsystems, Inc., http://www.sun.com. For more information on the Apache Software Foundation, please see <http://www.apache.org/>.
Perl5 API 1.2 The Apache Software License, Version 1.1
348
| Third Party Software License Agreements
| 349
Index
A
accessing Action Editor 80 Advanced Rule Editor 143 Advanced Rulebase Editor 134 Alert Detail window 57 Canvas View 25 Repository View 102 Rule Editor 67 Rulebase Editor 67 Rulebase View 31 Action Editor, accessing 80 actions advanced options 84 clear 79 clearing 60 creating 80 escalating 85 network 212 specifying variables in 139 substituting variables in 141 adding agents to Canvas View 26 containers 21 tools menu commands 36 advanced action options 84 rule options 143 rulebase options 134 test options 78 Advanced Action Editor, accessing 84 Advanced Rule Editor, accessing 143 Advanced Rulebase Editor, accessing 134 Advanced Test Editor, accessing 78 Agent View 16
agents 255 auto-discovery 16 default icon colors 16 finding 23 performing actions on multiple 212 querying multiple 206 querying remote 206 removing rulebases from Repositories 106 retrieving rulebases on 66 rulebase map groups 124 sending rulebases to 93 sending rulebases to Repositories from 104 sending to containers 22 using a rulebase map 127 viewing alerts for 56 viewing icons for 17 viewing log files 255 Alert Detail window, accessing 57 Alert Display description of 56 filtering alerts from 57 viewing details in 57 alerts adding sound to 35 changing default colors 35 clearing 60 marking all 58 suspending 58 viewing for a rulebase 31 viewing for an agent 56 viewing purged 60 AMI description 10 monitoring instrumented applications 199 role in applications monitoring 4 arguments, method specifying 70 using regular expressions in 250 arguments, method, specifying 70
350
| Index
asynchronous methods clearing actions from 60 description 49 using in a rule 70 auto-discovery 16 Automatic Configuration mode consequences of 108 description 99 automating file system space monitoring 189 log file monitoring 194 process existence monitoring 187 process resource consumption monitoring 187 system resource monitoring 191 configuration modes Automatic 99 Manual 100 overview 98 scenarios 108 containers adding 21 deleting 23 finding agents in 23 renaming 22 sending agents to 22 copying rulebases 91 creating actions 80 rulebase maps 122 rulebases 67 rules 68 schedules 149 tests in a rule 71 customer support xviii
B
Boolean test operators 76
C
Canvas View accessing 25 adding agents to 26 adding shapes to 27 lock mode 28 character encoding 220 charts, viewing subscriptions as 54 clear actions, specifying 79 clear conditions, specifying 79 clear test option 79 clear timer option 79 clearing alert messages 60 codepage configuration 220 command line length 235, 236 commands adding to a rulebase 136 adding to Tools menu 36 executing on loss of heartbeat 118 compound tests 76
D
data delivery interval, specifying 53 data files, Event Service 116 data source variables 141 data sources example 69 See also methods, microagent specifying in a rule 68 deleting containers 23 rulebases 92, 94 deriving rulebases 91
E
email, sending with actions 81 encoding 220 escalating actions 85 evaluation intervals, test 71
Index 351
Event Service log, TIBCO Hawk 257 Event.log 257 executing commands from an agent icon 40 in a rulebase 136 on loss of heartbeat 118 on the Tools menu 37 expressions building test 72 using regular 248, 250 external variables 139 referencing in a rulebase 139, 140
.hsf files 168
I
identifier, character encoding 220 identifying same-named processes 184 IMPACT_ACTION methods, definition of 49 IMPACT_ACTION_INFO methods, definition of 49 IMPACT_INFO methods, definition of 49 including rulebases 134 in-schedule 165 internal variables 140 intervals data delivery 53 recovered to OK 35 test evaluation 71 invoking methods interactively 49 remotely 204
F
false host list 210 file systems, monitoring space in 189 files loading display 33 loading rulebases from 90 rulebase 89 rulebase map 134 saving display 33 saving rulebase maps in 133 saving rulebases in 89 finding agents in containers 23 first false option 79
L
limit on command line length 235, 236 limit on process line length 235 loading display files 33 rulebase files 90 rulebase map files 134 rulebases using methods 172 lock mode, Canvas View 28 log files monitoring 192 TIBCO Hawk agent 255 TIBCO Hawk Display 256 TIBCO Hawk HMA 258 TIBO Hawk Event Service 257
G
group operations, performing 202 groups, agent 124
H
Hawk.log 255 Hawk_HMA.log 258 .hrb files 89 .hrm files 133
352
| Index
M
Manual Configuration mode Configuration Path option 100 consequences of 108 overview 100 Repository option 101 marking alerts 58 memory usage, testing 73 methods, microagent asynchronous 49 invoking interactively 49 invoking remotely 204212 referencing in actions 141 results of 51 subscribing to 52 synchronous 49 types of 49 using to load rulebases 172 microagent methods See methods, microagent microagents default platform-independent 44 interrogating remote 204 refreshing list of 48 using methods in a rule 49 monitoring AMI applications 199 file system space 189 log files 192 process resource consumption 187 system resources 191 with custom scripts 196
O
operators, test specifying 73 specifying values for 73 overruling allowing in a rule 143 description 143 overlapping rules for 144
P
Period Groups 148 Perl5PatternMatch syntax 248 test operator for 76 Post Condition, action type 81 posted conditions counting result sets 146 creating with actions 81 description 146 monitoring processes with 185 test operators for 75 testing values 146 preferences adding tools menu commands 36 setting options 35 problem escalation 85 process line length 235 processes identifying same-named 184 monitoring in a rule 70 monitoring resources for 187 monitoring with posted conditions 185
N
network actions 212 network queries adding tests to 208 definition 206 sending 206 viewing results of 210 numeric test operators 73
Q
queries, network 206 querying multiple agents 206
Index 353
R
recovered to OK interval 35 refreshing microagent list 48 REGEXP syntax 250 regular expressions elements 250 modifiers 249 Perl5PatternMatch 248 REGEXP 250 using in method arguments 250 using in tests 248 removing rulebases from agents 94 rulebases from Repositories 106 renaming containers 22 Repositories accessing objects in 102 definition of 101 removing rulebases from 106 removing rulebases from other 107 saving rulebases in 103 sending rulebases to 104 sending rulebases to other 105 viewing icons in TIBCO Hawk Display 102 Repository View, accessing 102 resources monitoring process consumption 187 monitoring system 191 Rule Editor, accessing 67 Rulebase Editor, accessing 67 rulebase map assigning rulebases in 127 creating 122 defining agent groups 124127 definition 122 loading from file 134 saving to file 133 Rulebase View, accessing 31
rulebases adding commands to 136 applying schedules to 148, 166 automating management 172 copying 91 creating 67 deleting 94 deleting from an agent 92 deriving 91 description 64 including 134 loading from files 90 mapping to agents 127 overruling rules in 143 referencing internal variables in 140 removing from a Repository 107 removing from an agent 92 removing from other agents 94 retrieving for an agent 66 saving in a Repository 103 saving on an agent 88 saving to files 89 sending from agent to Repository 104 sending to a Repository 104 sending to agents 93 sending to other Repositories 105 viewing alerts for 31 rules allowing overruling for 143 creating 68 description 64, 68 overlapping 144 overruling 143 specifying a data source 68 using to monitor processes 70
S
saving display files 33 rulebase maps to files 133 rulebases to files 89 scenarios, configuration 108
354
| Index
schedules applying 166 creating 149 definition 148 testing 164 scripts executing from Tools menu 36 monitoring with 196 Sending 22 sending agents to containers 22 email with actions 81 rulebases 93 rulebases to a Repository 104 rulebases to agents 93 specifying data delivery intervals 53 external variables in actions 82 true test counters 79 starting TIBCO Hawk Display 15 subscribing to methods 52 subscriptions comparing multiple 55 creating 52 viewing charts of 54 viewing tables of 55 support, contacting xviii suspending alerts 58 synchronous methods clearing actions from 60 description 49 specifying data delivery intervals for 53 using in a rule 70 syntax data source variable 141 external variable rulebase 139 internal variable 140 Perl5PatternMatch 248 REGEXP 250 system resources, monitoring 191
T
Tabular View 55 technical support xviii Test Builder, accessing 72 Test Editor, accessing 71 testing rule boundaries 52 schedules 164 tests adding to network queries 208 advanced options 78 Boolean operators 76 compound 76 creating in a rule 71 description 71 evaluation intervals 71 numeric operators 73 scheduling 79 specifying clear actions for 79 specifying clear conditions for 79 specifying expressions in 72 true test counters 79 using posted conditions in 146 using regular expressions in 248 TIBCO Hawk Display accessing Canvas View 25, 26 accessing Rulebase View 31 adding containers in 21 changing views of 17 default icon colors 16 finding agents in 23 loading from a file 33 organizing agents 22 saving customized views 33 saving in a file 33 starting 15 viewing log files 256
Index 355
TIBCO Hawk Event Service executing commands with 118 integrating with 119 interpreting data files 116 numeric alert levels in 117 overview 112 viewing log files 257 viewing purged alerts 60 TIBCO Hawk HMA log files 258 Tools menu, adding commands to 36 true host list 210 truncated process names 235
V
variables effect on actions 141 referencing data source 141 referencing external 139 referencing internal 140 specifying in actions 139 viewing alert messages 56 alerts for an agent 56 log files 255 Repository icons 102 rulebase icons 31
356
| Index

Hawk Admin

Загружено:

Сведения о документе

Исходное описание:

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Hawk Admin

Загружено:

Авторское право:

Доступные форматы

TIBCO Hawk Administrators Guide

Software Release 4.2.1 April 2004

How to Contact TIBCO Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii

Chapter 2 Getting Started with TIBCO Hawk Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Chapter 3 Working with TIBCO Hawk Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Chapter 4 Monitoring with Rulebases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

TIBCO Hawk Administrators Guide

Chapter 5 Managing Your Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Understanding Configuration Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Chapter 6 Using the TIBCO Hawk Event Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Chapter 7 Advanced Rulebase Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Automating Rulebase Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Chapter 8 Planning Your Monitoring Strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Translate Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Chapter 9 Performing Common Monitoring Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Chapter 10 Performing Group Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Chapter 11 Program Internationalization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

TIBCO Hawk Administrators Guide

Appendix A Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Appendix B Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

Appendix C TIBCO BusinessWorks and Hawk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

Integrating with Third Party Management Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

Appendix D Using Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Appendix E Interpreting TIBCO Hawk Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

Appendix F Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

TIBCO Hawk Administrators Guide

TIBCO Hawk Administrators Guide

TIBCO Hawk Administrators Guide

Figure 1 Figure 2 Figure 3 Figure 4

TIBCO Hawk Administrators Guide

TIBCO Hawk Administrators Guide

TIBCO Hawk Administrators Guide

TIBCO Hawk Administrators Guide

TIBCO Hawk Administrators Guide

TIBCO Hawk Documentation

TIBCO Hawk Administrators Guide

Other TIBCO Product Documentation

Third Party Documentation

TIBCO Hawk Administrators Guide

xviii How to Contact TIBCO Customer Support

How to Contact TIBCO Customer Support

TIBCO Hawk Administrators Guide

TIBCO Hawk Administrators Guide

TIBCO Hawk Administrators Guide

TIBCO Hawk Display

Host System (Managed Node) publish/ subscribe

TIBCO Hawk Display publish/subscribe

Host System (Managed Node) Adapter or Gateway

Host System (Managed Node)

TIBCO Hawk Event Service

TIBCO Hawk Event Service

TIBCO Hawk Administrators Guide

TIBCO Hawk Administrators Guide

TIBCO Hawk Administrators Guide

Location Transparency and Fault Tolerance

System Management Over Networks of Any Size

Advanced Monitoring Logic

TIBCO Hawk Administrators Guide

TIBCO Hawk Administrators Guide

The TIBCO Rendezvous System

TIBCO Hawk Agents and Microagents

Rulebases and Rules

TIBCO Hawk Administrators Guide