Hawk Admin

TIBCO Hawk™

Administrator’s GuideSoftware Release 4.2.1April 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

TIBCO Hawk Administrator’s Guide

| iii

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviTIBCO Hawk Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviOther TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiThird Party Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

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

Chapter 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Scalability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Location Transparency and Fault Tolerance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6System Management Over Networks of Any Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Advanced Monitoring Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Flexibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Functional Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8The TIBCO Rendezvous System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8TIBCO Hawk Agents and Microagents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Rulebases and Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8TIBCO Hawk Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9AMI Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Console API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Configuration Object API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Event 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Adding a Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Sending Agents to a Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Renaming a Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Deleting a Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Finding an Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Working with Canvas View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Accessing Canvas View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Adding Agents to the Canvas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Adding Shapes to the Canvas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Changing the Canvas View for Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Working with Rulebase View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Working with Display Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Saving a Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Loading Display Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Setting Preferences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Adding a Command to the Tools Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Adding a Command to the Agent Menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Specifying the Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

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

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Viewing Microagents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Invoking a Microagent Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Subscribing to a Microagent Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Creating a Subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Viewing Subscription Results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Viewing Alert Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Suspending Alert Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Clearing Alert Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Viewing Console Warning Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

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

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Default Installation Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Creating a Rulebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Building a Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Specifying a Data Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Defining Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Creating a New Test. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Building a Test Expression. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73


Contents | v

Building Compound Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Using Advanced Test Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Defining Actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Using Advanced Action Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Saving a Rulebase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Working with Rulebase Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Saving a Rulebase to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Loading a Rulebase from a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Editing a Rulebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Copying an Existing Rulebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Removing a Rulebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Distributing a Rulebase to Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Sending a Rulebase to Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Removing a Rulebase from Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

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

Choosing a Configuration Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Using Automatic Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Using Manual Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Using the Configuration Path Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Using the Repository Option. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Saving a Rulebase in a Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Sending a Rulebase to a Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Removing a Rulebase from a Repository. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

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

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

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112AMI Instrumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Persistence of TIBCO Hawk Events using JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Fault Tolerance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Creating a Rulebase Map. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Working with Agent Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Defining Agent Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Adding Agents to a Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126


vi | Contents

Mapping Rulebases to Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Mapping Groups to External Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Saving a Rulebase Map in a Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Saving a Rulebase Map to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Including a Rulebase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Adding Commands to a Rulebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Specifying Rulebase Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Executing Rulebase Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Referencing Variables in a Rulebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Referencing External Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Referencing Internal Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Referencing Data Source Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141How Variable Substitution Affects Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Overruling a Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143Allowing Overruling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143Overlapping Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

Using Posted Conditions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146Testing for Non-Zero Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146Counting Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Working with Schedules and Period Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148Creating Schedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149Creating Period Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Testing Schedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164Applying Schedules to Rulebase Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Working with Schedule Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168Saving a Schedule File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168Distributing Schedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168Loading Schedules From a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Importing Schedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Viewing Schedule Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

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

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

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Define Problem Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175Define Information Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175Identify Corrective Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175Map Information Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Map Action Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Refine Corrective Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

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


Contents | vii

Transform to Rule Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Plan Rulebases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Formulate Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180Build and Test Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180Refine Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180Use Alternate Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

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

Monitoring Process Existence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Identifying Same-Named Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Using Posted Conditions to Monitor Same-Named Processes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Monitoring Process Resource Consumption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Automating Process Resource Consumption Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Monitoring File System Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Tips on Monitoring File System Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Automating File System Space Monitoring. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Monitoring System Resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191Automating System Resource Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Monitoring Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192Tips on Monitoring Log File Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192Automating Log File Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194Monitoring With Pattern Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194About Rolling Log Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Monitoring with Custom Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196Tips on Monitoring Custom Scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197Automating 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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216Why is Unicode Important? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

Using Japanese Characters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219Japanese Characters in Agents and Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219Japanese 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245TIBCO Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245TIBCO Runtime Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245TIBCO Domain. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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


x | Contents


| xi

Figures

Figure 1 TIBCO Hawk System Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Figure 2 Relationship Between Objects in a Rulebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Figure 3 Flow of Rules and Tests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Figure 4 Rolling File Mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259


xii | Figures


| xiii

Tables

Table 1 Default Agent Alert Level Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Table 2 Test Operators For Numeric Method Results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Table 3 Test Operators for Text String Results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Table 4 Test Operators for Boolean Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Table 5 Action Types in the Action Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Table 6 Configuration Scenarios. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Table 7 Table Layout for HawkAgentInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Table 8 Table Layout for HawkAlertClearInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Table 9 Numeric Representations of Alert Levels in Event.dat Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Table 10 Mapping Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Table 11 Method to Retrieve Information and Perform Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

Table 12 Perl5PatternMatch Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

Table 13 Regular Expression Modifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

Table 14 REGEXP Regular Expression Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

Table 15 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 DocumentationThe 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 Administrator’s 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 Programmer’s 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 DocumentationYou may find it useful to read the documentation for the following TIBCO products:

• TIBCO Rendezvous™ software: This is TIBCO’s 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 DocumentationYou 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


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

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.

TIB

CO

Ren

dezv

ous

TIBCO HawkEvent Service

Host System(Managed Node)


TIBCO Hawk Display

Adapteror Gateway

AMI

TIBCO Hawk Display

AMIApplication

publish/subscribe

Agent

Application API


publish/subscribe

TIBCO HawkEvent Service



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

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



Location Transparency and Fault ToleranceA 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 SizeUsing 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 LogicTIBCO 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.

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



Functional Components

This section gives a general overview of the functional components of the TIBCO Hawk enterprise monitor.

The TIBCO Rendezvous SystemTIBCO 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 MicroagentsIn 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 RulesA 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 DisplayThe 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.



AMI ProtocolThe 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 Programmer’s Guide.

Console APIThe 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 ServiceThe 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.




| 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 Getting Started with TIBCO Hawk Display

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:



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 agent’s 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:

To see more information about discovered agents, double-click icons to expand the list:

CreateDefaultDisplay

SaveDisplay to

a File

OpenDisplay file Find Agent in a

Container

DisplayPreferences

About TIB/Hawk

Console WarningMessages

Add newcontainer

Perform NetworkQuery



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:

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.

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.

Table 1 Default Agent Alert Level Colors

Default Color Alert Level Meaning

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

Red At least one high-level alert is active.

Orange At least one medium-level alert is active.

Yellow At least one low-level alert is active.

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

Green No alerts are in effect.

Note: You can change alert level colors in the Preferences dialog. For more information, see Setting Preferences on page 35.

Highest alert level

Relative proportion of on any agent

alert levels on all agents

Number of agents in the container


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.



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



Sending Agents to a ContainerAfter 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 ContainerYou 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.

Deleting a ContainerYou 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 AgentIn 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.

You will not be allowed to rename the Discovered container.



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



This Unmap list displays names of discovered agents that can be added to the canvas.

Adding Agents to the Canvas1. 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 Canvas1. 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.



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



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 levelRelative proportion of

generated by any

alert levels for all instances

Number of agents with the rulebase loaded

instance of the of the rulebaserulebase



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.

Saving a Display1. 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.

Note: Preference settings are saved separately from the display file.



• 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



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

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.

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.



Adding a Command to the Agent MenuAdding 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.



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




| 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


• 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 Working with TIBCO Hawk Agents

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.



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:



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.

To invoke a microagent method:

1. Click the Self microagent. Methods for this microagent display in the panel below.

The instructions in this section begin in the Microagents, Methods and Arguments dialog. To access this dialog, follow the instructions on page 46.



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.

5. Click Done to close the window.

To sort tabular results in the dialog, click on a column header. Shift-click to reverse the sort direction.



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 SubscriptionTo subscribe to a microagent method:

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

Note: The instructions in this section begin in the Microagents, Methods and Arguments dialog. To access this dialog, follow the instructions on page 46.


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.



7. To end the subscription, click Done to close the subscription results window.

Viewing Subscription ResultsYou 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.

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.

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.



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:

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.

Whether this alert has beenread and cleared. Cleared is a read-only field.

When the alertwas generated.

The name of the rulebase that generated the alert.

The text messageof the alert, specifiedin the Action Editor.

The severity of the alert.To set colors, edit Displaypreferences.

Drag border to resize column

Drag header to move column

Click on any column to sort by thatcolumn


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.

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:

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.



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

To suspend an alert:

1. Open the Alert Detail dialog by double-clicking the alert to suspend.

2. Click Suspend Alert.

Note: These instructions begin in the Alert Display window. For instructions on accessing this window, see Viewing Alert Messages on page 56.



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, 1999Clear Time - 6:05 PM December 8, 1999Clear Reason - Suspended By - User eastrue on host astureSuspended For - 10000 minute(s) Reason For Suspension - Sysadmin has been paged

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.

You can also use the RulebaseEngine:suspendAlert method to suspend specific alerts. Refer to the TIBCO Hawk Methods Reference for details.



Clearing Alert MessagesAlerts 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 MessagesItems 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:




| 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


• 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 Monitoring with Rulebases

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

Rule

RuleRule

Rule

Rulebase

RuleRule

RuleRule

Data Source

Test

ActionActionAction

Yes

Test

ActionAction

Yes


Overview | 65

Default Installation DirectoryThe 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.



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:

2. Click Create.

Opens the selectedrulebase for editing

Removes the selected rulebasefrom the current agent

Creates anew rulebase

Copies the selected rulebase andopens the copy for editing

Sends the selectedrulebase to one or more agents or

Saves changes on the current agent

Repositories in a container


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:

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.

Moves the selected object up or downin the list of objects. For tests and actions,

Creates a new object andopens it for editing. Theobject type depends on the active dialog.

Deletes the selected object.

Opens the selected object for editing.

Copies the selectedobject and opens the copy for editing. objects higher in the list are processed first.

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.



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

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.

data source test

action

action

action


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.

Specifying a Data SourceThe 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.

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.



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.

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.

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.


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.

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 TestTo create a new test in the current rule:

A test is true only when the entire test evaluates to true, not just the test expression.



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 ExpressionThe 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 Usage to use as the test parameter. (On UNIX, use Virtual KBytes.)

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.



<<=>>=

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.

inRange The test expression is true when the value of the test parameter is between two extremes of a range. Endpoints are included.

outOfRange The test expression is true when the value of the test parameter is outside the range of two operator values. Endpoints are excluded.

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

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

Decrease The test expression is true when the value of the test parameter decreases by at least the operator value between two successive tests.

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

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

Table 2 Test Operators For Numeric Method Results (Cont’d)




Defining Tests | 75

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

postedConditionExists

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

!postedConditionExists

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


Equals The test expression is true when the value of the test parameter exactly matches the operator value. This is a case-sensitive match.

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

StartsWith The test expression is true when the value of the test parameter starts with the operator value. This is a case-sensitive match.

Table 2 Test Operators For Numeric Method Results (Cont’d)





Building Compound TestsA 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.

Contains The test expression is true when the value of the test parameter contains the operator value. This is a case-sensitive match.

!Contains The test expression is true when the value of the test parameter does not contain the operator value. This is a case-sensitive match.

Perl5 PatternMatch

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.

Table 4 Test Operators for Boolean Results


isTrue The test expression is true when the value of the test parameter is true.

isFalse The test expression is true when the value of the test parameter is false.

Table 3 Test Operators for Text String Results (Cont’d)



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.



Using Advanced Test FeaturesA 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.

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.

Note: These instructions begin in the Test Editor dialog. For instructions on accessing this dialog, see Defining Tests on page 71.


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.

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.

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.



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.

To define an action:

1. Click Create on the toolbar. The Action Editor displays:

These instructions begin in the Test Editor dialog. For instructions on accessing this dialog, see Defining Tests on page 71.


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 Result Usage Notes

Alert (default)

Sends an alert message to TIBCO Hawk Display

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.

Email Sends an email message.

Specify a message recipient as [email protected]. 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.



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.

— To insert an internal variable, right-click on Insert and select Internal Variable from the menu.

Internal variables available in the Agent Menu are:

— 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 -variable option for the rulebase engine (suboption of -M RuleBaseEngine) when the agent is started.

— To insert a data source variable in a string argument, select a variable name from the menu.

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.

• Agent Name • Current RuleBase • Current Rule

• Current Test • Current Action • Condition True Time



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.

5. Click OK.

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.



Using Advanced Action FeaturesAdvanced 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.



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



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 Job is running."

— 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 Job needs to be checked".

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



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.

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.

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.



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.

Saving a Rulebase to a FileYou 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.

Results of working with rulebase files depend on the agent configuration mode. For more information, see Chapter 5, Managing Your Configuration.



3. Browse to a directory for the rulebase file, then click OK.

Loading a Rulebase from a FileYou 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 RulebaseYou 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.

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.


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.

Copying an Existing RulebaseIf 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.

A rulebase must have the same name as its rulebase file. You can only rename a rulebase or rulebase file using TIBCO Hawk Display.



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

Sending a Rulebase to AgentsTo 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.

Results of distributing rulebase files depend on the agent configuration mode. For more information, see Chapter 5, Managing Your Configuration.

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.



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.

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

3. Click the agent to remove the rulebase from. Use the Shift and Control keys to select multiple agents.

4. Click OK.

Warning: If an existing rulebase with the same name exists on the destination agent, it is immediately overwritten with the new rulebase.

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.


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.




| 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 Managing Your Configuration

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.



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



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.

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

3. In the Rulebase Editor dialog, click OK.

Note: You cannot move Repository icons from the Repository container, or include them in Canvas View.

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.



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

4. Click OK.

If an existing rulebase with the same name exists on the destination Repository, it is immediately overwritten.



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.



Removing a Rulebase from a RepositoryYou 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.

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.


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.



The rulebase is deleted from the selected Repository or Repositories. However, the rulebase remains on the agent.

From a Repository

These steps describe how to remove a rulebase from the current Repository.

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.

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.

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.



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 Manual Configuration Automatic Configuration

Specify startup rulebases.

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.

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

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

Delete a rulebase and apply the change to an agent.

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 rulebase is deleted from memory, and the rulebase file is deleted from the auto- configuration directory.


Understanding Configuration Scenarios | 109

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.

Send a rulebase across the network to an agent.

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.

The rulebase is copied to memory on the machine you send it to, and copied to a file in that agent’s auto-configuration directory. Because the file is in the auto- configuration directory, it is reloaded at startup.

Delete a rulebase across the network for an agent that has this type of configuration.

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.

You delete the rulebase from memory; you also delete the rulebase file in the agent’s auto-configuration directory; and it is not reloaded at startup.

Load a rulebase using the RuleBaseEngine: loadRuleBase() method.

The agent searches the list of configuration path directories or Repositories for rulebases with the specified name.

The method invocation fails.

Manually copy a rulebase file into the auto-configuration directory.

Nothing will happen, and the rulebase is not loaded at startup.

Not applicable.

Table 6 Configuration Scenarios (Cont’d)

Action Manual Configuration Automatic Configuration




| 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


• 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 Using the TIBCO Hawk Event Service

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 InstrumentationThe 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 JDBCAll 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 and onRulebaseRemoved 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 Data Type Description

Hawk_Domain VARCHAR(128)

Agent_Name VARCHAR(128)

Agent_Domain VARCHAR(128)

Agent_IP_Address VARCHAR(64)

Agent_StartTime VARCHAR(128)

Event_Time VARCHAR(128)

Event_Type VARCHAR(32) Can be:

onAgentAliveonAgentExpiredonMicroAgentAddedonMicroAgentRemovedonRuleBaseAddedonRuleBaseRemoved

MicroAgentID VARCHAR(128)

Rulebase VARCHAR(128)

Table 8 Table Layout for HawkAlertClearInfo

Column Name Data Type Comments

Hawk_Domain VARCHAR(128)



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

Agent_Name VARCHAR(128)

Agent_Domain VARCHAR(128)

Agent_IP_Address VARCHAR(128)

AlertID INTEGER

Event_Time VARCHAR(128)

Event_Type VARCHAR(32) Can be onAlert or onClear

Alert_State VARCHAR(32) Can be:

NO_ALERTALERT_LOWALERT_MEDIUMALERT_HIGH

Alert_Text VARCHAR(1024) "NA" for a clear

Rulebase VARCHAR(128)

RuleName VARCHAR(512) "NA" for a clear

Test VARCHAR(512) "NA" for a clear

Alert_Properties VARCHAR(512) "NA" for a clear

Clear_Reason VARCHAR(256) "NA" for an alert event

Table 8 Table Layout for HawkAlertClearInfo (Cont’d)

Column Name Data Type Comments


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.



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:

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

Table 9 Numeric Representations of Alert Levels in Event.dat Files

Numeric Value Alert Level

0 Notification

25 Low

50 Medium

75 High



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 offrem Usage - sendpage.bat <agentname> <agent_ipaddress>send_page.exe %1 %2exit

You could also call a script that logs into the machine and checks for the existence of an agent process before sending notification.

For considerations on executing commands in your TIBCO Hawk environment, see Tips on Monitoring Custom Scripts on page 197.


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.




| 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 Advanced Rulebase Features

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.

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

Note: Rulebase maps are supported only when running in Manual Configuration mode. For more information, see Choosing a Configuration Mode on page 98.


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.

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.

Adds a new mappingto the rulebase map

Copies the selected mappingand opens the copy for editing

Deletes the selected mapping

Edits the Sends the rulebase mapmap to one or more Repositories on the network

selected mapping

Saves the rulebasemap in the currentRepository



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



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.

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

Note: Agents in a group should have similar rulebase requirements.



To remove a group name from the In Group list, click it and then click Remove.

6. Click OK.

Mapping Rulebases to AgentsAfter 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.

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.

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.



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.



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 CommandsAn 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 Group’s 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 group’s external command mapping to generate Rulebase list.

7. Click OK.

Saving a Rulebase Map in a RepositoryTo 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:



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


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

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.

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.



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.

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.

Note: Include lists are supported only when running in Manual Configuration mode. For more information, see Choosing a Configuration Mode on page 98.


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.



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



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

Supported Typesof 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 ofEvaluation

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

Variable substitution affects the performance of rulebase processing. Therefore, you should reference a variable only when it provides a clear benefit.



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 VariablesInternal 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 rule’s 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 enteringvariables

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



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 diskspace was around 84.6%

Then for less than one minute,

The alert is still active because disk space

disk space was around 84.5%

is still below 90%.

And since then it has been around 84.39%.


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.

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

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.



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

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.

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.



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



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.

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

Modify

Copy

Delete



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.

Create

Modify

Copy

Delete

Apply Changes



The Schedule Editor displays:

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.

Set the time zone

Click here to create inclusion periods

Click here to create exclusion periods



The Schedule Period dialog displays:

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

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.



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

To create a custom interval, click in either the Start or End field. The Edit Interval frame displays.

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.

Click to display drop-down list

Click to delete a selected interval

Click to display time in 24-hour format

Click to create a new interval

Click to apply changes



To delete an interval, click in the Start or End field and then click the Delete button.

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.

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.

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



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



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.

Create

Modify

Copy

Delete



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.

Create

Modify

Copy

Delete



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.

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:

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.



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.



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



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



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



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 FileAll 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 SchedulesTypically, 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 FileYou 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.



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



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


• Define Problem Areas, page 175

• Translate Requirements, page 178

• Formulate Rules, page 180


174 | Chapter 8 Planning Your Monitoring Strategy

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 RequirementsFor 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 ActionsIdentify 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.”



Map Information RequirementsThe 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 RequirementsAfter 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 ActionsDefine 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?



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.

Transform to Rule ElementsTransform the table entries into TIBCO Hawk rule elements using the following equivalents:

• Information — a microagent, method and arguments in a rule’s data source

• How often — a data delivery interval in a rule’s data source

• Conditions — each test in a rule

• Actions — each test’s actions

Table 10 Mapping Table

Column Sample Contents

Information to gather

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.

How often to gather the information

Every sixty seconds, or whenever a log file entry is made, or whenever a message is received from a managed application through AMI.

Conditions that define the question, problem, or situation

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.

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

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.


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



Formulate Rules

With requirements defined and translated into TIBCO Hawk equivalents, you can encapsulate monitoring logic in TIBCO Hawk rulebases.

Build and Test RulesIn 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 RulesAfter 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 MethodsYou 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.




| 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 Performing Common Monitoring Tasks

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 ProcessesIf 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 Process:getInstanceCountbyCommand() 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.

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



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 Performance:Process() and Process:getProcess() methods, see the TIBCO Hawk Methods Reference and the reference documentation for your operating system.

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.



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



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 % Used field to test for swap file usage.

Automating System Resource MonitoringCPU 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.



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.

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 FeedCharacters

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.

Create the log file before you specify it in the method. If the log file does not exist, an error is generated.


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 asC:\${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().



Automating Log File MonitoringSince 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 FilesThe 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 FilesThe 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 rule’s 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.

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

Note: Because of file blocking restrictions, this method is particularly recommended for agents running on Microsoft Windows.



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 offecho This is a test.

testReturningNumber.bat@echo offecho 12.5

• UNIX: Create the following scripts (substituting your shell for csh if necessary):testReturningString.csh#!/bin/cshecho This is a test.

testReturningNumber.csh#!/bin/cshecho 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



• 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 MonitoringYou 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 Programmer’s Guide.




| 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


• Interrogating Microagents, page 204

• Performing Network Queries, page 206

• Performing Network Actions, page 212


202 | Chapter 10 Performing Group Operations

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

Now Over Time Now Over Time

On One Computer

invoke a microagent method

subscribe to a microagent method invoke a microagent method

build a rulebase that takes an action at repeated intervals


Overview | 203

On Multiple Computers

perform a network query

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

perform a network action

build a rulebase that takes an action at repeated intervals and distribute it to other agents

Table 11 Method to Retrieve Information and Perform Tasks (Cont’d)

Retrieving Information Performing Tasks

Now Over Time Now Over Time



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.



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.



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.

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.

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.



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.



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.



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.

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.

Note: Since performing a single network action can have a widespread effect, use this powerful feature with caution.


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.



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

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.



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 RepositoriesWhen 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 FileIf your external variables file contains Japanese characters, you must use the included native2ascii utility to convert the file before starting the agent.

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.

The native2ascii utility is in the JDK bin directory. The utility is not available in the JRE.

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.



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 Text

0x8000078D8 A counter with a negative value was detected.0x8000078D6 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 Frequently Asked Questions

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.


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.


Version: All


General | 225

Why can’t 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/cshsetenv XFILESEARCHPATH netscape $*



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.


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.


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.



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.


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.


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.


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.


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.


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.


Version: All



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.


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.


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.


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



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 Error Text0x8000078D8 A counter with a negative value was detected.

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


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.


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.


Version: All



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.


Version: All


Command Lines and Process Names | 235

Command Lines and Process Names

I can’t 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.


Version: All

Why can't I match long process names?

When using the process:getProcess method (UNIX) or performance: ProcessCount method (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.

• Use regular expressions to match process names. For example, to find process abcdefghijklmn 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.



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


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.


Version: All



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.


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.


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.




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.


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.


Version: All

Why does the Posted Condition display as PostedConditionExist?

In the Rulebase Test Editor, if PostedCondition is specified as ${Posted.x} > 0 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

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



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


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.


Version: All


| 243

Appendix C TIBCO BusinessWorks and Hawk

This section discusses the use of Hawk with BusinessWorks.

Topics


• Components, page 245

• Integrating with Third Party Management Systems, page 246


244 | Appendix C TIBCO BusinessWorks and Hawk

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 AdministratorBusinessWorks 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 AgentTIBCO 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 DomainThe 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 TIBCO BusinessWorks and Hawk

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 Using Regular Expressions

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

. matches any single character f.t matches fit and fat

^ anchors the match to the start of a line or piece of text

î matches it but not ti

$ anchors the match to the end of a line or piece of text

^$ matches only empty text

* matches zero or more of the last character

it* matches it and i but not ia

+ matches one or more of the last character

it+ matches it but not ip

? matches zero or one of the last character

it? matches i or it but not itt

\w matches any alphanumeric character a\w matches at but not a+

\W matches any non- alphanumeric character

a\W matches a+ but not at

[a-z] matches a lower-case character within a range

[a-d] matches c but not p

[A-Z] matches an upper-case character within a range

[A-D] matches C but not c or P


Perl5PatternMatch Syntax | 249

Table 13 shows the available modifiers of a regular expression.

\d matches any digit a\d matches a2 but not at

/^\d\d/ matches any string that starts with 2 digits

\D matches any non-digit a\D matches at but not a2

[0-9] matches any digit within a range [1-4] matches 2 but not 5

\n, \t matches a new line character or tab character

one\ttwo matches one <tab> two

Table 13 Regular Expression Modifiers

Modifier Function

i Do case-insensitive pattern matching.

m Treat the string as multiple lines.

s Treat the string as a single line.

x Use extended regular expressions.

Table 12 Perl5PatternMatch Regular Expressions (Cont’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


. matches any single character except an end-of-line character

f.t matches fit and fat

^ anchors the match to the start of a line or piece of text when specified at the start of a regular expression

î matches it but not ti

[âbcd] matches any single character except an end-of-line character or the characters in brackets. The following characters are interpreted literally: .*[ \

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

$ anchors the match to the end of a line or piece of text

^$ matches only empty text

* matches zero or more of the last character

it* matches it and i but not ia

+ matches one or more of the last character

it+ matches it but not ip

? matches zero or one of the last character

it? matches i or it but not itt

\ matches the following special character literally

\$ matches $ and \wh*t?\ matches wh*t?


REGEXP Syntax | 251

\\ matches the most-recently specified regular expression

[a-z] matches a lower-case character within a range

[a-d] matches c but not p

[A-Z] matches an upper-case character within a range

[A-D] matches C but not c or P

[0-9] matches any digit within a range [1-4] matches 2 but not 5

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

\_cat< matches _category and _catalog, as well as @_category and @_catalog

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

\gory> matches category and allegory, as well as {category} and {allegory}

\{_m\} matches exactly _m occurrences of the regular expression, where _m is a positive integer less than 256

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

[abc]\{5\} matches 5 or more occurences of [abc], which could be instances of a, b, or c.

\{_m,_n\} matches from _m through _n occurrences of the regular expression, where _m and _n are positive integers less than 256

\Error<\{15,25\} matches the 15th through 25th occurrences of strings that start with Error

 matches the same set of characters matched by the enclosed regular expression

See following row.

Table 14 REGEXP Regular Expression Elements (Cont’d)




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

^\(.*$\1$ matches a line consisting of two repeated appearances of the same string

Table 14 REGEXP Regular Expression Elements (Cont’d)



| 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


• 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 Interpreting TIBCO Hawk Log Files

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

• Display.log, which records information about the TIBCO Hawk Display application

• Event.log, which records information about the TIBCO Hawk Event Service.

• Hawk_<microagent>.log and Hawk_HMA.log , which records information about microagent activities

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.

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.


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 : Adding Rulebase HawkAgent-WinNT at Tue Aug 25 12:08:06 EDT 1998

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



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



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/20002000/01/21 22:58:56.358 Options in effect: -rvd_session 7475 ; tcp:7475 -logdir C:/program files/TIBCO/hawk/Log -logmaxsize 1024 -logmaxnum 5WARNING 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 Servicedata file options are:maximum number of files: 5maximum file size: 1024 K

When Event.dat is full, this filedrops out of the list and Event4.datis renamed to Event5.dat




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

MessageCode Unique code for the message. For example:

HWKAMI-000001

Description Informative text message explaining the trace message.

Category Name of the component which generated the message.

Role 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 Unable to create AMI error due to memory allocation failure.Role Error.

Category TIBCO Hawk AMI APIResolution Insufficient memory available for process.

HWKAMI-000002 Insufficient memory to process request.Role Error

Category TIBCO Hawk AMI APIResolution Insufficient memory available for process.

HWKAMI-000003 Specified AMI error handle is invalid.Role Error

Category TIBCO Hawk AMI APIResolution Programming error. AMI error handle passed to function is null.

HWKAMI-000004 Specified AMI error handle is invalid or corrupted.Role Error

Category TIBCO Hawk AMI APIResolution Programming error. AMI error handle passed to function is invalid, corrupted or

was previously destroyed.

HWKAMI-000005 Required argument not specified (null).Role Error

Category TIBCO Hawk AMI APIResolution Programming error. Null value specified for a required function argument.

HWKAMI-000006 Invalid argument specified.Role Error

Category TIBCO Hawk AMI APIResolution Programming error. Invalid value specified for a function argument.

HWKAMI-000007 Specified AMI session handle <handle value (hex)> is invalid.Role Error

Category TIBCO Hawk AMI APIResolution Programming error. AMI session handle passed to function is null.

HWKAMI-000008 Specified AMI session handle <handle value (hex)> is invalid or corrupted.Role Error

Category TIBCO Hawk AMI API



Resolution Programming error. AMI session handle passed to function is invalid, corrupted or was previously destroyed.

HWKAMI-000009 Specified AMI method handle <handle value (hex)> is invalid.Role Error

Category TIBCO Hawk AMI APIResolution Programming error. AMI method handle passed to function is null.

HWKAMI-000010 Specified AMI method handle <handle value (hex)> is invalid or corrupted.Role Error

Category TIBCO Hawk AMI APIResolution Programming error. AMI method handle passed to function is invalid, corrupted

or was previously destroyed.

HWKAMI-000011 Specified AMI subscription handle <handle value (hex)> is invalid.Role Error

Category TIBCO Hawk AMI APIResolution Programming error. AMI subscription handle passed to function is null.

HWKAMI-000012 Specified AMI subscription handle <handle value (hex)> is invalid or corrupted.Role Error

Category TIBCO Hawk AMI APIResolution Programming error. AMI subscription handle passed to function is invalid,

corrupted or was previously destroyed.

HWKAMI-000013 Specified AMI parameter list list handle <handle value (hex)> is invalid.Role Error

Category TIBCO Hawk AMI APIResolution Programming error. AMI parameter list list handle passed to function is null.

HWKAMI-000014 Specified AMI parameter list list handle <handle value (hex)> is invalid or corrupted.

Role ErrorCategory TIBCO Hawk AMI API

Resolution Programming error. AMI parameter list list handle passed to function is invalid, corrupted or was previously destroyed.

HWKAMI-000015 Specified AMI parameter list handle <handle value (hex)> is invalid.Role Error

Category TIBCO Hawk AMI APIResolution Programming error. AMI parameter list handle passed to function is null.

HWKAMI-000016 Specified AMI parameter list handle <handle value (hex)> is invalid or corrupted.




Resolution Programming error. AMI parameter list handle passed to function is invalid, corrupted or was previously destroyed.

HWKAMI-000017 Specified AMI parameter handle <handle value (hex)> is invalid.Role Error

Category TIBCO Hawk AMI APIResolution Programming error. AMI parameter handle passed to function is null.

HWKAMI-000018 Specified AMI parameter handle <handle value (hex)> is invalid or corrupted.Role Error

Category TIBCO Hawk AMI APIResolution Programming error. AMI parameter handle passed to function is invalid,

corrupted or was previously destroyed.

HWKAMI-000019 TIBCO Rendezvous error <error number> <error text>.Role Error

Category TIBCO Hawk AMI APIResolution The specified TIBCO Rendezvous error occurred. Refer to TIBCO Rendezvous

documentation.

HWKAMI-000020 Received invocation request for unknown AMI method <method name>.Role Error

Category TIBCO Hawk AMI APIResolution 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.

HWKAMI-000021 Method <method name> does not have a parameter named <parameter name>.Role Error

Category TIBCO Hawk AMI APIResolution 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.

HWKAMI-000022 Failed to add object to linked list.Role Error

Category TIBCO Hawk AMI APIResolution Link list add failed due to insufficient memory available for process.

HWKAMI-000023 TIBCO Rendezvous error <error number> occurred attempting to get value for argument <argument name> of method <method name>. <error text>.

Role Error



Category TIBCO Hawk AMI APIResolution The specified TIBCO Rendezvous error occurred when attempting to get

argument value. Refer to TIBCO Rendezvous documentation.

HWKAMI-000024 <method name> invocation received for unknown subscription with context <context number> and reply subject <subject name>.


Resolution Internal error. Contact TIBCO Support for assistance.

HWKAMI-000025 Attempt made to announce an AMI session which is already announced.Role Error

Category TIBCO Hawk AMI APIResolution Programming error. An AMI session cannot be announced while it is currently

announced.

HWKAMI-000026 Attempt made to stop an AMI session which has not been announced.Role Error

Category TIBCO Hawk AMI APIResolution Programming error. An AMI session cannot be stopped if it is not currently

announced.

HWKAMI-030101 Unable to request ami heartbeat: <com.tibco.rv.TibrvException>Role Error

Category Application TIBCO Hawk AgentResolution A TIBCO Rendezvous error has occurred. Consult the TIBCO Rendezvous

documentation.

HWKAMI-030102 Unable request ami refresh: <com.tibco.rv.TibrvException>Role Error


documentation.

HWKAMI-030103 Unable to get CONTEXT field in AMI reply message for <microagent_id>, <com.tibco.rv.TibrvException>

Role ErrorCategory Application TIBCO Hawk Agent

Resolution A TIBCO Rendezvous error has occurred. Consult the TIBCO Rendezvous documentation.

HWKAMI-030104 COM.TIBCO.hawk.agent.mafactories.AmiMsgFormatError <error>Role Error



Category Application TIBCO Hawk AgentResolution An AMI message is incorrectly formatted. Consult the documentation for the

AMI instrumented application.

HWKAMI-030105 Unknown message type received for <microagent_id>Role Error

Category Application TIBCO Hawk AgentResolution Contact TIBCO Support.

HWKAMI-030106 Received asynchronous data message for non-existent subscription in : <microagent id>

Role WarningCategory Application TIBCO Hawk Agent

Resolution Contact TIBCO Support

HWKAMI-030107 Unable to process AMI reply message in: <microagent_id>, <com.tibco.rv.TibrvException>



HWKAMI-030109 Async method control msg reply contained non-empty RETURN field, Async method may have sent data to incorrect reply-subject



HWKAMI-030110 <microagent_id>:COM.TIBCO.hawk.agent.mafactories.AmiMsgFormatError <error>


Resolution An AMI message is incorrectly formatted. Contact the vendor of the AMI instrumented application.

HWKAMI-030111 <microagent_id>:COM.TIBCO.hawk.talon.MicroAgentResolution Exception <error>


Resolution An error has been received from an AMI instrumented application. Consult the documentation for the AMI instrumented application.

HWKAMI-030112 Unable to stop subscription: <com.tibco.rv.TibrvException>





HWKAMI-030113 stopSubscription called for non-existent subscription : <subscription> in <microagent id>



HWKAMI-030121 Method <name> returned tabular data but INDEX was not specified. Ignoring all but first RETURNS field


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

HWKAMI-030501 Multiple startup announcement messages received for <microagent id>Role Warning

Category Application TIBCO Hawk AgentResolution Contact TIBCO Support

HWKAMI-030502 Unable to process AMI announcement message: <com.tibco.rv.TibrvException>Role Error


documentation.

HWKAMI-030503 Unable to process AMI announcement message: <ami_msg_format_error>Role Error

Category Application TIBCO Hawk AgentResolution An AMI message is incorrectly formatted. Contact the vendor of the AMI

instrumented application.

HWKAMI-030504 Announced AMI application <application name> did not respond to first heartbeat request. Presumed dead.





HWKAMI-030505 Discovering methods. AMI App: <name>, exception: <com.tibco.rv.TibrvException>



HWKAMI-030506 Timed out waiting for reply to _describeMethods. AMI App: <name>Role Error


HWKAMI-030507 Unable to process AMI _describeMethods reply: <ami_msg_format_error>Role Error



HWKAMI-030508 Unable to process AMI _describeMethods reply: <exception>Role Error


HWKAMI-030509 Creating AMI microagent <name>, <COM.TIBCO.hawk.talon.MicroAgentException>;


Resolution Contact TIBCO Support.

HWKAMI-030510 Creating AMI microagent <name>, <com.tibco.rv.TibrvException>;Role Error


HWKAMI-030511 Adding discovered AMI microagent <name>, <exception>;Role Error


HWKAMI-030512 Unable to process AMI stop message: <com.tibco.rv.TibrvException>Role Error

Category Application TIBCO Hawk Agent




HWKAMI-030513 Unable to process AMI stop message: <ami_msg_format_error>Role Error



HWKAMI-030514 Unable to remove AMI microagent <name>, <COM.TIBCO.hawk.talon.MicroAgentException>



HWKAMI-030515 Unable to send announcement request: <com.tibco.rv.TibrvException>Role Error


documentation.

HWKAMI-030516 Internal error, AMI Microagent not successfully removed <name>Role Error


HWKAMI-030517 Unable to remove <name>, <COM.TIBCO.hawk.talon.MicroAgentException>;Role Error


HWKAMI-030519 Unable to process AMI unsolicited msg: <com.tibco.rv.TibrvException>Role Error


documentation.

HWKAMI-030520 Unable to process AMI unsolicited msg: <ami_msg_format_error>Role Error





HWKAMI-030521 AmiTibrvService dispatch thread was interrupted: <java.io.InterruptedException>



HWKAMI-030522 AmiTibrvService dispatch thread caught exception: <com.tibco.rv.TibrvException>



HWKAMI-030523 AmiTibrvService dispatch thread caught exception: <java.lang.Throwable>Role Error


HWKHMA-001000 Unknown message template ID specified.Role Error

Category TIBCO Hawk HMAResolution Internal error. Attempt to lookup an unknown error message. Contact TIBCO

Support for assistance.

HWKHMA-001001 Trace function <function name> failed with error <error number> <error text>Role Error

Category TIBCO Hawk HMAResolution 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.

HWKHMA-001002 PROGRAM: NAME <program name> VERSION <version> DATE <build date> Role Information

Category TIBCO Hawk HMA Resolution Used to log product name, version and build date.

HWKHMA-001003 TIBCO Rendezvous error <error number> <error text>.Role Error

Category TIBCO Hawk HMAResolution The specified TIBCO Rendezvous error occurred. Refer to TIBCO Rendezvous

documentation.

HWKHMA-001004 Insufficient memory to process request.Role Error



Category TIBCO Hawk HMAResolution Insufficient memory available for process.

HWKHMA-001005 Null or invalid argument specified.Role Error

Category TIBCO Hawk HMAResolution An invalid value was specified for a command line option. Refer to TIBCO Hawk

documentation for command line description.

HWKHMA-001007 TIBCO Hawk HMA initialization completed successfully.Role Information

Category TIBCO Hawk HMA

HWKHMA-001008 Execution of TIBCO Hawk HMA terminated successfully.Role Information


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

Role ErrorCategory TIBCO Hawk HMA

Resolution 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-001010 Directory specified, <directory name>, is invalid. <error text>.Role Error

Category TIBCO Hawk HMAResolution An invalid directory name was specified. If resolution is not obvious from the

error description then contact TIBCO Support for assistance.

HWKHMA-001011 File specified, <file name>, is invalid. <error text>.Role Error

Category TIBCO Hawk HMAResolution An invalid file name was specified. If resolution is not obvious from the error

description then contact TIBCO Support for assistance.

HWKHMA-001012 Function <function name> failed for file <file name>. OS error <error number> <error text>.


Resolution An error occurred for the specified file function. If resolution is not obvious from the error description then contact TIBCO Support for assistance.



HWKHMA-001014 An option specified is invalid.Role Error

Category TIBCO Hawk HMAResolution An invalid command line option was specified. Refer to TIBCO Hawk


HWKHMA-001015 Invalid value specified for option <option name>.Role Error

Category TIBCO Hawk HMAResolution An invalid value was specified for a command line option. Refer to TIBCO Hawk


HWKHMA-001016 Value missing for option <option name>.Role Error

Category TIBCO Hawk HMAResolution No value was specified for a command line option. Refer to TIBCO Hawk


HWKHMA-001017 Error processing specified TIBCO Hawk HMA command line. Error <error code>: <error test>.


Resolution The specified error was encountered processing the specified command line. Refer to TIBCO Hawk documentation for command line description.

HWKHMA-001020 OPTIONS RVD_SESSION<rendezvous parameters> TRACELEVEL<trace level> LOGDIR<log directory> LOGMAXSIZE<maximum log size> LOGMAXNUM<maximum log number>

Role InformationCategory TIBCO Hawk HMA

Resolution Used to log specified command line options to the TIBCO Hawk log files.

HWKHMA-001021 TIBCO Hawk HMA microagent <microagent name> initialization completed successfully.

Role Information.Category TIBCO Hawk HMA

HWKHMA-001023 Error <error number> occurred on thread <thread ID (hex)> at line <line number> in file <file name>. <error text>.


Resolution 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-001025 Function <function name> failed. OS error <error number> <error text>.Role Error

Category TIBCO Hawk HMAResolution An error occurred for the specified function. If resolution is not obvious from the

error description, contact TIBCO Support for assistance.

HWKHMA-001026 Stopping TIBCO Hawk HMA in response to a <signal name> signal.Role Information


HWKHMA-001027 Unable to install signal handler for signal <signal name>.Role Error

Category TIBCO Hawk HMAResolution Contact TIBCO Support for assistance.

HWKHMA-001028 Internal error. Unable to obtain TIBCO Hawk HMA configuration. <error text>.Role Error

Category TIBCO Hawk HMAResolution Unable to obtain configuration for TIBCO Hawk HMA. If resolution is not

obvious from the error description, contact TIBCO Support for assistance.

HWKHMA-001029 This asynchronous method does not support synchronous invocation.Role Error

Category TIBCO Hawk HMAResolution Attempt was made to synchronously invoke an asynchronous method. Specific

method does not support synchronous invocation.

HWKHMA-001030 Unknown microagent name, <microagent name>, specified in option <option name>.


Resolution Invalid microagent name was specified in command line option. Refer to TIBCO Hawk documentation for command line description.

HWKHMA-001031 TIBCO Hawk HMA microagent <microagent name> has been disabled via disable command line option.

Role InformationCategory TIBCO Hawk HMA

HWKHMA-001032 Internal HMA event <event name> received.Role Information




HWKHMA-001033 HMA restart event received for microagent <microagent name>.Role Information


HWKHMA-001034 HMA restart event processed for microagent <microagent name>.Role Information


HWKHMA-001035 Unknown internal HMA event, <event name>, received.Role Error


HWKHMA-001036 Attempt to increase default thread stack size failed. Function <function name> returned error <Error code>


Resolution Internal error. Contact TIBCO Support for assistance.

HWKHMA-001037 TIBCO Hawk HMA signal handling for signal <signal name> has been disabled via command line option.

Role warningCategory TIBCO Hawk HMA

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

HWKHMA-001038 Unable to set signal disposition for signal <signal name>. Role Error

Category TIBCO Hawk HMAResolution 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.

HWKHMA-001039 This instance of microagent <microagent name> has a stop request pending. Restart ignored.


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

HWKHMA-002000 Internal error. Unable to obtain service name.




Resolution Contact TIBCO Support for assistance.

HWKHMA-002001 Internal error. Unable to obtain service startup parameters.Role Error


HWKHMA-002002 Internal error. Unable to parse service startup parameters.Role Error


HWKHMA-002003 Internal error. Unable to obtain service start type.Role Error


HWKHMA-002004 Internal error. Invalid service start type specified.Role Error


HWKHMA-002005 Internal error. Unable to obtain service control command code.Role Error


HWKHMA-002006 Internal error. Unable to construct discovery reply.Role Error


HWKHMA-002007 Internal error. OpenSCManager failed. WIN32 error <error code> (<error code hex>): <error text>


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.

HWKHMA-002008 Internal error. Unable to allocate memory for services array.Role Error



Category TIBCO Hawk HMAResolution Insufficient memory available to process. Contact TIBCO Support for assistance.

HWKHMA-002009 Internal error. Unable to construct Windows NT service configuration message.Role Error


HWKHMA-002010 Internal error. Unable to construct Windows NT service status message.Role Error


HWKHMA-002011 Internal error. Unable to allocate memory for services enumeration.Role Error


HWKHMA-002012 Internal error. GetServiceDisplayName failed for service "<service name>". WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-002013 Internal error. QueryServiceConfig failed for service "<service name>". WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-002014 Internal error. EnumServicesStatus failed. WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-002015 StartService failed for service "<service name>". WIN32 error <error code> (<error code hex>): <error text>





HWKHMA-002016 OpenService failed for service "<service name>". WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-002017 ControlService failed for service "<service name>". WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-002018 QueryServiceStatus failed for service "<service name>". WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-002019 ChangeServiceConfig failed for service "<service name>". WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-002022 Conversion from UNICODE to UTF8 failed.Role Error


HWKHMA-003000 Internal error. Unable to obtain process virtual base address.Role Error


HWKHMA-003001 Unable to retrieve process command line for this Microsoft Operating System version. Please contact TIBCO Hawk technical support.





HWKHMA-003002 Internal error. EnumProcesses failed. WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-003003 Unable to retrieve process count.Role Error


HWKHMA-003004 Function getprocs returned a process with a PID of 0. Process was skipped.Role Information


HWKHMA-003005 HMA could not load NTDLL.DLL.Check path environment variable. Category TIBCO Hawk HMA

Role ErrorResolution HMA process could not load ntdll.dll. Make sure that PATH environment

variable contains path which points to ntdll.dll.

HWKHMA-003006 Could not locate entry point for function NtQueryInformationProcess in dll NTDLL.DLL. 'Parent Process ID' column for all processes are set to -1.

Category TIBCO Hawk HMARole Error

Resolution Contact TIBCO Support for assistance

HWKHMA-004000 Failure to obtain kernel stats for network interface <interface name>.Role Error

Category TIBCO Hawk HMAResolution Make sure TIBCO Hawk HMA is running with root permission. If not resolved

then contact TIBCO Support for assistance.

HWKHMA-004001 Failed to read kernel stats for network interface <interface name> errno <errno>.Role Error

Category TIBCO Hawk HMAResolution 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-004002 Failure to obtain kernel stats for network-related statistics <error text>.Role Error



HWKHMA-004003 get_lanstats returned error <error text>Role Error



HWKHMA-004004 get_lanstats on <id> returned <error text>Role Error



HWKHMA-004005 Unable to obtain statistics for interface name <interface name>.Role Warning.

Category TIBCO Hawk HMAResolution Statistics unavailable. No resolution necessary.

HWKHMA-004006 <function name> socket(AF_INET,SOCK_DGRAM,0) returned [<socket>] errno[<error number] [<error text>]



HWKHMA-004007 <function name> ioctl(<socket>, <ioctl function id>,) returned [<ioctl rc>] errno[<error number] [<error text>]



HWKHMA-004011 <function name> ioctl(<socket> NIC[%d] returned [<ioctl rc>] errno[<error number] [<error text>]

Role Warning.Category TIBCO Hawk HMA




HWKHMA-004013 lseek(<file handle>, <seek operation>, <seek position>) returned [<return code>] errno[<error number] [<error text>]



HWKHMA-004015 read(<file handle>, <buffer address>, <buffer size>) returned [<return code>] errno[<error number] [<error text>]



HWKHMA-004018 <function name> Can not open /dev/kmem file errno[<error number] [<error text>]


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. If "access denied" is indicated then make sure TIBCO Hawk HMA is running with root permission.

HWKHMA-004019 <function name> knlist lookup on symbol [<symbol name] failed - res[<return code>] errno[<error number] [<error text>].



HWKHMA-004023 <function name> malloc failed with errno <error number> <error text>.Role Error


HWKHMA-004024 Unexpected implementation of kernel stats for network interface <interface name>.



HWKHMA-004026 get_lanstats returned no info on interface <interface name>.Role Error




HWKHMA-004027 get_lanstats returned no info on interface <interface name>, nmid <nmid>.Role Error


HWKHMA-004028 Can not open /dev/kmem file errno[<error number] [<error text>]Role Error

Category TIBCO Hawk HMAResolution Make sure TIBCO Hawk HMA is running with root permission. If not resolved

then contact TIBCO Support for assistance.

HWKHMA-004029 Function <function name> failed for file <file name>. OS Error <OS error code> <OS error text>.


Resolution Make sure that file indicated by error message exist at given location.

HWKHMA-004030

Invalid record format encountered in file <file name>.



HWKHMA-004031 Failed to open /dev/dlpi. errno = <error number> errormessage = <error text>Category TIBCO Hawk HMA

Role ErrorResolution Make sure that file indicated by error message exist at given location.

HWKHMA-004032 No Physical Point of Attachment. Network statistics not available.Category TIBCO Hawk HMA

Role ErrorResolution Contact TIBCO Support for assistance.

HWKHMA-004033 <interface name> interface is attached on PPA number <PPA number>.Category TIBCO Hawk HMA

Role Information

HWKHMA-004034 putmsg stream function failed for primitive <primitive name> errno = <error number> and errormessage = <error text>.





HWKHMA-004035 getmsg stream function failed with errno = <error number> and errormessage = <error text>.



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

Category TIBCO Hawk HMARole Information

HWKHMA-004037 Total Number of valid PPAs currently installed in system is <total ppa number>. Category TIBCO Hawk HMA

Role Information

HWKHMA-004038 Failed to retrieve proper control code for primitive <primitive name>.Category TIBCO Hawk HMA


HWKHMA-004039 Error attaching PPA number: <ppa number>.Category TIBCO Hawk HMA


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



HWKHMA-004041 Received Wrong Primitive. Expected Primitive: <primitive number>, Received Primitive: <primitive number>.



HWKHMA-004042 Received only data portion of the message. Failed to receive control portion of the



messageCategory TIBCO Hawk HMA


HWKHMA-004043 No message found in stream. May be system call was interrupted.Category TIBCO Hawk HMA


HWKHMA-004044 Failed to get Network Statistics for PPA: <ppa number>.Category TIBCO Hawk HMA


HWKHMA-005000 kstat_open() returned null, errno <error number> <error text>.Role Error



HWKHMA-005001 kstat_read() returned error, errno <error number> <error text>.Role Error



HWKHMA-005002 kstat_lookup() on %s returned null, errno <error number> <error text>.Role Error



HWKHMA-005003 kvm_open() returned error, errno <error number> <error text>.Role Error



HWKHMA-005004 kvm_nlist() returned error, errno <error number> <error text>.Role Error





HWKHMA-005005 kvm_read() returned error, errno <error number> <error text>.Role Error



HWKHMA-005006 Can't open <file name> <error text>.Role Error



HWKHMA-005007 Can't knlist <error text>.Role Error



HWKHMA-005008 Failure to fseek <error text>.Role Error



HWKHMA-005009 Failure to read <error text>.Role Error



HWKHMA-005010 pstat_getdynamic() returned <return code>, errno <error number> <error text>.Role Error



HWKHMA-005011 malloc failed with errno <error number> <error text>.Role Error




HWKHMA-005013 pstat_getvminfo returned <return code>, errno <error number> <error text>.Role Error



HWKHMA-005014 pstat_getstatic() returned <return code>, errno <error number> <error text>.Role Error



HWKHMA-005017 ERROR returning from system swapctl function SC_LIST errno <error number> <error text>.



HWKHMA-006000 Failed to get host address for specified network parameter.Role Error

Category TIBCO Hawk HMAResolution Invalid network parameter specified in Rendezvous microagent network

parameter. Refer to TIBCO Hawk Method Reference manual.

HWKHMA-006001 hma_getHostAddr() returned <error code> for network <network parameter> and daemon <daemon parameter>.



HWKHMA-006002 RV transport key not found for RV advisory message: <message text>.Role Error


HWKHMA-006003 <function name>: received advisory message with subject: <subject name> message: <message text>.



HWKHMA-006004 <function name>: Failed to allocate context.





HWKHMA-006005 <function name>: Failed to allocate host status context.Role Error


HWKHMA-006006 <function name>: Failed to get host name.Role Error


HWKHMA-006007 <function name>: Failed to get host entry for <host name>.Role Error


HWKHMA-006008 <function name>: Failed to register context.Role Error


HWKHMA-006009 <function name>: Unable to deregister context.Role Error


HWKHMA-006010 Error getting value for argument <argument name>.Role Error


HWKHMA-006011 Failed to send unsolicited message: <message text>.Role Error


HWKHMA-006012 Failed to send pending RVD.DISCONNECTED advisory message.Role Error





HWKHMA-006013 Failed to send async data on advisory message <subject name>.Role Error


HWKHMA-006014 <function name>: Unable to parse RV version: <version>.Role Error


HWKHMA-006015 <function name>: Unable to get field <field name> due to RV error: <RV error text>.



HWKHMA-006016 The argument "HMA_N_INTERVAL" is less than 90 seconds. It has been changed to the default value of 90 seconds.

Role WarningCategory TIBCO Hawk HMA

Resolution Interval argument must be 90 seconds or greater.

HWKHMA-006017 <function name>: Failed to create RV timer due to RV error: <RV error text>.Role Error


HWKHMA-006018 <function name>: Failed to create RV listener because of RV error: <RV error text>.



HWKHMA-006019 <function name>: setUpRvAdvisoryMonitoring failed. <error text>Role Error


HWKHMA-006020 createRvdTransport failed. <error text>Role Error





HWKHMA-006021 tibrvEvent_CreateListener failed. RV error: <RV error text>.Role Error


HWKHMA-006022 util_ListCreate failed with error <error code>.Role Error


HWKHMA-006023 util_ListFindObj failed with error <error code>.Role Error


HWKHMA-006024 util_ListAdd failed with error <error code>.Role Error


HWKHMA-006025 Unable to create new RV transport because the internal buffer limit has been exceeded.



HWKHMA-006026 Required tibrvTransport argument is null.Role Error


HWKHMA-006027 Unable to create RV parameter key.Role Error


HWKHMA-006028 tibrvTransport_Create failed for '<session>' '<network>' '<daemon>'. RV error: <RV error text>.





HWKHMA-006029 Sending unsolicted message: <message text>.Role Information


HWKHMA-006030 No RV daemon status was received in the last reporting interval.Category TIBCO Hawk HMA

Role ErrorResolution Make sure that RVD is running on the system.

HWKHMA-006031 Unable to determine RV daemon statistics because some daemon status information were missing in the last reporting interval.


Resolution Make sure that RVD is running on the system.

HWKHMA-007000 PdhOpenQuery failed with error <error code>.Role Error


HWKHMA-007003 Object <object name> has no counters. Ignoring object.Role Warning

Category TIBCO Hawk HMAResolution Object encountered with no defined counters so no data can be returned. Object is

being ignored. No action required.

HWKHMA-007005 No open query for this subscription.Role Error


HWKHMA-007006 PdhCollectQueryData for method <method name> instance <instance name> failed with error <error code>.



HWKHMA-007007 Object <object name> has been removed.Role Warning

Category TIBCO Hawk HMAResolution Performance object was removed by system and is no longer available. No action

required.



HWKHMA-007008 PdhEnumObjectItems for object <object name> failed with error <error code>.Role Error


HWKHMA-007009 PdhEnumObjects failed with error <error code>.Role Error


HWKHMA-007010 PdhAddCounter for counter <counter name> failed with error <error code>.Role Error


HWKHMA-007011 PdhCollectQueryData for object <object name> and instance <instance name> failed with error <error code>.



HWKHMA-007012 PdhGetFormattedCounterValue for object <object name> and instance <instance name> and counter <counter name> failed with error <error code>.



HWKHMA-007013 PdhRemoveCounter for object <object name> and instance <instance name> and counter <counter id> failed with error <error code>.



HWKHMA-007014 PdhCloseQuery for object <object name> and instance <instance name> failed with error <error code>.



HWKHMA-007015 Failed to get instance and counter information for method <methodname>. Ignoring method : <method name>




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.

HWKHMA-007016 Found duplicate counter name: <counter name> for method: <method name>. Ignoring method: <method name>.


Resolution Specified Object contains duplicate counter name. Skipping this Object from announcing as method during discovery process.

HWKHMA-007017 PdhLookupPerfNameByIndex failed with Pdh status code: <status code> <method name>



HWKHMA-008000 Key must be specified.Role Error

Category TIBCO Hawk HMAResolution Registry microagent key argument is a required argument.

HWKHMA-008001 Entry must be specified.Role Error

Category TIBCO Hawk HMAResolution Registry microagent entry argument is a required argument.

HWKHMA-008002 Value must be specified.Role Error

Category TIBCO Hawk HMAResolution Registry microagent value argument is a required argument.

HWKHMA-008003 Invalid system key name. Role Error

Category TIBCO Hawk HMAResolution Registry microagent key argument specified is invalid or non-existent.

HWKHMA-008004 Invalid key path. Role Error

Category TIBCO Hawk HMAResolution Registry microagent key path argument specified is invalid or non-existent.



HWKHMA-008005 RegOpenKeyEx failed for key <key name>. WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-008007 RegFlushKey failed for key <key name>. WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-008008 RegCloseKey failed for key <key name>. WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-008009 RegQueryValueEx failed for key <key name> entry <entry name>. WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-008013 RegEnumValue failed for key <key name>. WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-008014 SubKey must be specified.Role Error

Category TIBCO Hawk HMAResolution Registry microagent subkey argument is a required argument.

HWKHMA-008015 Specified key <key name> already exists.Role Error




Resolution Attempt to create an existing key was made.

HWKHMA-008016 RegEnumKeyEx failed for key <key name>.Role Error



HWKHMA-008017 RegCreateKeyEx failed for key <key name>. WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-008018 RegSetValueEx failed for key <key name> entry <entry name> value <value>. WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-008019 RegSetValueEx failed for key <key name> entry <entry name> value <value>. WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-008020 Value for key <key name> entry <entry name> is not of type <type name>.Role Error

Category TIBCO Hawk HMAResolution Registry microagent value specified is not the specified type. Check actual

registry entry for correct data type.

HWKHMA-008021 Root key specified is invalid.Role Error

Category TIBCO Hawk HMAResolution An invalid system root key was specified. See method reference for correct system

key values.

HWKHMA-008022 RegFlushKey failed for key <key name>. WIN32 error <error code> (<error code hex>): <error text>





HWKHMA-008023 RegCloseKey failed for key <key name>. WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-008024 ExpandEnvironmentStrings failed for key <key name> entry <entry name>Category TIBCO Hawk HMA


HWKHMA-009002 Unable to retrieve source parameter.Role Error

Category TIBCO Hawk HMAResolution EventLog microagent source argument is a required argument.

HWKHMA-009003 CreateEvent failed. WIN32 error <error code> (<error code hex>): <error text>Role Error



HWKHMA-009004 OpenEventLog failed for <event log name> event log. WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-009005 beginthread failed for <event log name> event log monitoring thread. System reports error <error number> <error text>.





HWKHMA-009006 RegOpenKeyEx failed for key "<key name>". WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-009007 RegQueryValueEx failed for value "<value name>" under key "<key name>". WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-009008 RegCloseKey failed for key "<key name>". WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-009009 ExpandEnvironmentStrings failed. WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-009010 LoadLibraryEx failed for library "<library name>". WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-009011 FormatMessage failed for event <event ID> of event source "<source name>". WIN32 error <error code> (<error code hex>): <error text>





HWKHMA-009012 Message file name of event source "<source name>" exceeds maximum size of <maximum size> characters.



HWKHMA-009013 RegisterEventSource failed for event source "<source name>". WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-009014 ReportServiceEvent failed for event source "<source name>". WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-009015 DeregisterEventSource failed for event source "<source name>". WIN32 error <error code> (<error code hex>): <error text>



HWKHMA-009016 <event log name> event log overrun. <event count> events lost. Warning.Category TIBCO Hawk HMA

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

HWKHMA-009017 <event log name> event record <record number> exceeded maximum size. Record skipped.


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

HWKHMA-009018 <event log name> event monitoring thread shutdown due to errors encountered.Role Error



Category TIBCO Hawk HMAResolution 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.

HWKHMA-009019 Failed to get description for event <record number> in source "<source name>". Error <error number> <error text>.



HWKHMA-009021 WaitForMultipleObjects failed. WIN32 error <error code> (<error code hex>): <error text>


Resolution Internal error. Contact TIBCO Support.

HWKHMA-009022 WaitForMultipleObjects returned unexpected value <return code>.Role Error

Category TIBCO Hawk HMAResolution Internal error. Contact TIBCO Support.

HWKHMA-009023 WaitForSingleObject failed. WIN32 error <error code> (<error code hex>): <error text>


Resolution Internal error. Contact TIBCO Support.

HWKHMA-009024 WaitForSingleObject returned unexpected value <return code>.Role Error

Category TIBCO Hawk HMAResolution Internal error. Contact TIBCO Support.

HWKHMA-009025 NotifyChangeEventLog failed for <event log name> event log.Category TIBCO Hawk HMA

Role ErrorResolution This error will also contain the OS specific error description. If resolution is not


HWKHMA-009026 All attempts to reopen <event log name> event log have failed.Category TIBCO Hawk HMA

Role Error



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.

HWKHMA-009027 ReadEventLog failed for <event log name> event log.Category TIBCO Hawk HMA

Role ErrorResolution This error will also contain the OS specific error description. If resolution is not


HWKHMA-009028 The <event log name> event log has changed (e.g. cleared) between read operations. Possible loss of events. Re-opening event log.

Category TIBCO Hawk HMARole Warning

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

HWKHMA-009029 All attempts to resync <event log name> event log after overrun have failed.Category TIBCO Hawk HMA

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



HWKHMA-009030 Event category specified, <event category number>, is invalid. Category value must be between 0 and 65535 inclusive.


Resolution Specify an event category between zero and 65353 inclusive. A zero indicates "no category".

HWKAGT-010201 Reading variables file <variable file name> java.io.FieNotFoundExceptionRole Error

Category Application TIBCO Hawk AgentResolution Make sure that the variable’s file is readable and is in the proper Java properties

format.

HWKAGT-010202 Reading variables file <variable’s file name> java.io.SecurityExceptionRole Error


format.

HWKAGT-010203 Reading variables file <variable’s file name> java.io.IOExceptionRole Error


format.

HWKAGT-010204 Reading variables file <variable’s file name> java.lang.ExceptionRole Error


format.

HWKAGT-010205 Can not determine current working directory from system property user.dir Please specify config path.


Resolution Java Virtual Machine’s System Property "user.dir" has to be set correctly.

HWKAGT-010207 No variables have been loadedRole Warning


format.



HWKAGT-010208 config path directory <path> does not yet exist.Role Warning

Category Application TIBCO Hawk AgentResolution Make sure that the specified configuration path exists

HWKAGT-010209 config path <path> is not a directory.Role Warning

Category Application TIBCO Hawk AgentResolution Make sure that the specified configuration path is a directory

HWKAGT-010210 config path directory <path> can not be read.Role Warning

Category Application TIBCO Hawk AgentResolution Make sure that the specified configuration path is readable and it contains TIBCO

Hawk configuration files

HWKAGT-010402 java.io.IOExceptionRole Error

Category Application TIBCO Hawk AgentResolution An internal error occurred while waiting to read the output from the executed

command. Contact TIBCO Support

HWKAGT-010405 java.io.IOExceptionRole Error

Category Application TIBCO Hawk AgentResolution An internal error occurred while executing the requested command. Contact

TIBCO Support

HWKAGT-010406 A process is blocking, killing itRole Warning


HWKAGT-010407 The process <cmd> timed out. It was terminated.Role Warning

Category Application TIBCO Hawk AgentResolution Try executing the command from a command prompt and report the results to

TIBCO Support

HWKAGT-010502 Duplicate ami_rvd_transport parameters. Ignoring ami_rvd_transport <service> <network> <daemon>




Resolution Check the command line arguments and remove all duplicates

HWKAGT-010503 The rvd_transport and ami_rvd(s)_transport parameters match. Ignoring ami_rvd(s)_transport <service> <network> <daemon>


Resolution Check the command line arguments and remove all duplicates

HWKAGT-010902 enableLogging() invoked without typeRole Error

Category Application TIBCO Hawk AgentResolution Invoke the method "enableLogging() again after specifying a valid value for

argument "Type"

HWKAGT-010903 enableLogging() invoked with invalid typeRole Error

Category Application TIBCO Hawk AgentResolution Invoke the method "enableLogging() again after specifying a valid value for

argument "Type"

HWKAGT-010904 disableLogging() invoked without typeRole Error

Category Application TIBCO Hawk AgentResolution Invoke the method "disableLogging() again after specifying a valid value for

argument "Type"

HWKAGT-010905 disableLogging() invoked with invalid typeRole Error

Category Application TIBCO Hawk AgentResolution Invoke the method "disableLogging() again after specifying a valid value for

argument "Type"

HWKAGT-010906 activateClass() invoked without class nameRole Error


HWKAGT-010907 deactivateClass() invoked without class nameRole Error


HWKAGT-011001 COM.TIBCO.hawk.microagent.Repository: Fatal error: no repository name





HWKAGT-011004 Initialization of -repository_dir failed: <COM.TIBCO.hawk.agent.source.SourceException>



HWKAGT-011006 COM.TIBCO.hawk.microagent.Repository: Failed to load rulebase <rulebase name>. Exception: <SourceException>



HWKAGT-011007 COM.TIBCO.hawk.microagent.Repository: Failed to load rulebase <rulebase name>. Exception: <SourceTimeoutException>



HWKAGT-011008 COM.TIBCO.hawk.microagent.Repository: Failed to load rulebase <rulebase name>. Exception: <SourceException>



HWKAGT-011009 COM.TIBCO.hawk.microagent.Repository: Failed to load rulebase <rulebase name>. Exception: <SourceTimeoutException>



HWKAGT-011012 COM.TIBCO.hawk.microagent.Repository: Failed to load schedules. Exception: <SourceException>



HWKAGT-011013 COM.TIBCO.hawk.microagent.Repository: Failed to load schedules. Exception: <SourceTimeoutException>

Role Warning




HWKAGT-011014 COM.TIBCO.hawk.microagent.Repository: Failed to load rulebase map <rulebase map name>. Exception: <SourceException>



HWKAGT-011015 COM.TIBCO.hawk.microagent.Repository: Failed to load rulebase map <rulebase map name>. Exception: <SourceTimeoutException>



HWKAGT-011016 COM.TIBCO.hawk.microagent.Repository: Failed to load rulebase map <rulebase map name>. Exception: <SourceException>



HWKAGT-011017 COM.TIBCO.hawk.microagent.Repository: Failed to load rulebase map <rulebase map name>. Exception: <SourceTimeoutException>



HWKAGT-011022 COM.TIBCO.hawk.microagent.Repository: Failed to start request listener. Exception: TibrvException <>



HWKAGT-011023 COM.TIBCO.hawk.microagent.Repository: Exiting on Fatal errorRole Error

Category Application TIBCO Hawk AgentResolution An internal error has occurred. Contact TIBCO Support

HWKAGT-011024 COM.TIBCO.hawk.microagent.Repository: Fatal error: Duplicate repository(<name>) detected.





HWKAGT-011027 COM.TIBCO.hawk.microagent.Repository: Failed to send ping reply.Role Error


HWKAGT-011028 COM.TIBCO.hawk.microagent.Repository: Configuration type <type> not a valid type.



HWKAGT-011030 COM.TIBCO.hawk.microagent.Repository: Failed to send <type> inventory.Role Error


HWKAGT-011034 COM.TIBCO.hawk.microagent.Repository: Configuration Type <type> not valid.Role Error


HWKAGT-011036 COM.TIBCO.hawk.microagent.Repository: Failed to send <type> object <name>.Role Error


HWKAGT-011038 COM.TIBCO.hawk.microagent.Repository: Failed to retrieve rulebase <rulebase name>. Exception: <SourceException>



HWKAGT-011039 COM.TIBCO.hawk.microagent.Repository: Failed to retrieve rulebase <rulebase name>. Exception: <SourceTimeoutException>



HWKAGT-011042 addRuleBase() invoked without RulebaseXML parameterRole Error




Resolution This internal error occurred while adding (or updating) a rulebase in the repository. Contact TIBCO Support

HWKAGT-011046 addRuleBase() invoked without RulebaseXML parameterRole Error

Category Application TIBCO Hawk AgentResolution This internal error occurred while adding (or updating) a rulebase in the

repository. Contact TIBCO Support

HWKLMA-070401 <Pattern file access or pattern retrieval error message>Role Error

Category Application TIBCO Hawk AgentResolution Make sure that the "patternfile" argument specified to

"onNewLineWithPatternFile" method is correct and the file contains at least one valid Perl5 pattern

HWKLMA-070402 Unable to evaluate logfile name: <filename with embedded quotes>Role Warning

Category Application TIBCO Hawk AgentResolution Make sure that the file name with embedded back quotes is correct

HWKLMA-070403 <file name> does not yet exist. Will try reopening it laterRole Warning

Category Application TIBCO Hawk AgentResolution Make sure that the file name does exist and has proper read permission

HWKLMA-070602 <file name> has been truncated.Role Warning

Category Application TIBCO Hawk AgentResolution The file being monitored has been over written by some other application

HWKLMA-070604 java.io.IOExceptionRole Error

Category Application TIBCO Hawk AgentResolution An internal error occurred while trying to read additional data from the logfile

being monitored. Contact TIBCO Support


Category Application TIBCO Hawk AgentResolution An internal error occurred while trying to close the logfile being monitored.

Contact TIBCO Support




Category Application TIBCO Hawk AgentResolution An internal error occurred while waiting to read the output from the executed

command. Contact TIBCO Support

HWKLMA-070906 A process is blocking, killing itRole Warning


HWKLMA-070907 The process <cmd> timed out. It was terminated.Role Warning


HWKRBE-040101 getAlertIDForClear found _currentAlertID=0 : <path>Role Error

Category Application TIBCO Hawk AgentResolution Internal error, contact TIBCO Support.

HWKRBE-040102 Attempted activation of already active node: <path>Role Error


HWKRBE-040103 Internal rbengine error, sendAlert invoked with state of NONERole Error


HWKRBE-040302 DataSourceError with <datasource name>: <error> at, <path>Role Warning


HWKRBE-040303 DataSourceError Cleared for <datasource name> at <path>Role Warning

Category Application TIBCO Hawk AgentResolution This message merely indicates that a previous data source error has now cleared.

HWKRBE-040401 MAX_DATA_ELEMENTS exceeded, discarding data for rule <rule>




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

HWKRBE-040402 removing orphaned child at <path>Role Error

Category Application TIBCO Hawk AgentResolution Rulebase engine encountered inconsistent data from microagent. Contact TIBCO

Support.

HWKRBE-040403 can’t create child: <reason> at <path>Role Error


HWKRBE-040404 can’t create child: <reason> at <path>Role Error


HWKRBE-040405 invalid data type received at <path>Role Error

Category Application TIBCO Hawk AgentResolution The rule at path received an unsupported data type from the microagent. Contact

TIBCO Support.

HWKRBE-040501 getAlertIDForClear found currentAlertID=0 : <path>Role Error


HWKRBE-040502 NoValidDataSource for <rule> at <path>Role Error

Category Application TIBCO Hawk AgentResolution A valid data source does not exist for the rule. Instantiate a valid data source or

modify the rulebase to use available data sources.

HWKRBE-040901 RBEngine timer dispatch thread caught exception: <com.tibco.rv.TibrvException>Role Error




HWKRBE-040902 RBEngine timer dispatch thread caught exception: <java.lang.Throwable>Role Error


HWKRBE-040903 RBEngine timer dispatch thread interrupted: <java.io.InterruptedException>Role Warning




HWKRBE-041206 Processed clear for non-existent alert. ID:<id> Reason:<reason>Role Error


HWKRBE-041303 initializing subscription for rule <name>Role Error




HWKRBE-041306 while canceling subscription for rule <rulename>, <exception>Role Error


HWKRBE-041309 onSubscriptionPending, data source <data_source_instance> already exists.Role Error


HWKRBE-041311 initializing subscription for rule: <rulename>, microagent: <microagent name>, <exception>





HWKRBE-041312 onSubscriptionError, data source <method_name>: <data_source_instance> not registered.


Resolution Internal error, contact TIBCO Support.

HWKRBE-041314 onData, data source <method_name>: <data_source_instance> not registered.Role Error


HWKRBE-041315 onData, subscription and data have inconsistent microagent id, subscription: <id>, data: <id>



HWKRBE-041317 Rule datasource error for rule <path> exception: <COM.TIBCO.hawk.talon.MicroAgentException>



HWKRBE-041318 onRoleError, data source <method_name>: <data_source_instance> not registered.



HWKRBE-041319 adding DataSourceNode <method name>, <exception>Role Error


HWKRBE-041321 onErrorCleared, data source <method_name>: <data_source_instance> not registered.





HWKRBE-041324 adding DataSourceNode <method name>, <exception>Role Error


HWKRBE-041325 adding NoValidDataSourceNode <exception>Role Error




HWKRBE-041407 can’t evaluate test: <exception>, At: <path>Role Error

Category Application TIBCO Hawk AgentResolution Unable to evaluate test for stated reason.

HWKRBE-041408 can’t evaluate test: <exception>, At: <path>Role Error

Category Application TIBCO Hawk AgentResolution Unable to evaluate test for stated reason.

HWKRBE-041410 Couldn’t launch clear timer: <reason>Role Error

Category Application TIBCO Hawk AgentResolution Unable to launch timer for stated reason.

HWKRBE-041413 Unable to evaluate action: <action>, <exception>Role Error

Category Application TIBCO Hawk AgentResolution Unable to evaluate action because of stated error.

HWKRBE-041414 clear action is not of type ActionNode <type>Role Error

Category Application TIBCO Hawk AgentResolution Illegally formatted rulebase file.

HWKRBE-041415 Unable to evaluate action: <action>, <exception>Role Error



Category Application TIBCO Hawk AgentResolution Unable to evaluate action because of stated error.

HWKRBE-041416 Unable to reset timer: <reason>Role Error

Category Application TIBCO Hawk AgentResolution Unable to restart timer for stated reason.

HWKRBE-041601 Scheduler registering node <node> with schedule <scheduleName> node already registered.



HWKRBE-041602 Schedule <schedule name> is not loadedRole Warning

Category Application TIBCO Hawk AgentResolution Try loading the schedule’s file (schedules.hsf) using TIBCO Hawk Display’s

Schedules Editor

HWKRBE-041603 Invalid arguments for Scheduler.deregister(), node:<node>, scheduleName:<scheduleName>



HWKRBE-041604 Scheduler deregistering node <node>. Schedule <scheduleName> not in active list.



HWKRBE-041605 Scheduler deregistering node <node> with schedule <scheduleName>, node not found.



HWKRBE-041608 Schedule <schedule name> is no longer loadedRole Warning




HWKRBE-041609 In Scheduler.evaluateSchedules() - node <node> threw exception <exception> in response to inSchedule() call. Deregistering node from scheduler.");



HWKRBE-041623 InterruptedException in Scheduler sleep <exception>Role Error

Category Application TIBCO Hawk AgentResolution Contact TIBCO Support if this error persists.

HWKRBE-041705 Ignoring includes list of <rulebase name>. Include lists are not supported in auto config mode.


Resolution Edit the <rulebase name> and remove all the included rulebase lists

HWKRBE-041708 Error purging <config_file>: <exception>Role Error

Category Application TIBCO Hawk AgentResolution Unable to purge config_file from local cache. If resolution is not obvious from the


HWKRBE-041709 Error examining inventory of source <config_source>: <exception>Role Error

Category Application TIBCO Hawk AgentResolution Unable to examine config_source inventory. If resolution is not obvious from the


HWKRBE-041711 Error purging <schedules name>: <exception>Role Error

Category Application TIBCO Hawk AgentResolution Unable to purge config_source inventory cache. If resolution is not obvious from

the error description then contact TIBCO Support for assistance.

HWKRBE-041712 Error examining inventory of source <config_source>: <exception>Role Error



HWKRBE-041714 Error purging <rulebase name>: <exception>Role Error



Category Application TIBCO Hawk AgentResolution Unable to purge config_source inventory cache. If resolution is not obvious from

the error description then contact TIBCO Support for assistance.

HWKRBE-041715 Error examining inventory of source <rulebase name>: <exception>Role Error



HWKRBE-041717 Corrupt rulebase <rulebase name> from <config source>, name of the rulebase does not correspond to the name of config object.



HWKRBE-041719 Error loading rulebase <name> from <config_source>: <exception>Role Error

Category Application TIBCO Hawk AgentResolution Unable to load named rulebase from named config_source. Check configuration

according to exception or contact TIBCO Support.

HWKRBE-041720 Config object is of incorrect type: <config_object>, expected <type>Role Error


HWKRBE-041721 Requested config object <name> not found in config sourceRole Error

Category Application TIBCO Hawk AgentResolution Unable to locate config object in config source. Insure that it exists.

HWKRBE-041722 Error loading <config object name> from <config source>, <SourceException>Role Warning


HWKRBE-041723 Error loading <config object name> from <config source>, <SourceTimeoutException>





HWKRBE-041724 Error loading <config object name> from <config source>, <java.lang.Exception>Role Warning


HWKRBE-041725 Config object <config object name> was retrieved from an emergency source: <source name>


Resolution Make sure that the specified config object exists in the config source directory

HWKRBE-041727 Config object is of incorrect type: <name>, expected Schedules.hsfRole Error

Category Application TIBCO Hawk AgentResolution Unable to locate Schedules.hsf in config source. Insure that it exists.

HWKRBE-041731 Config object is of incorrect type: <name>, expected rbmap.hrmRole Error

Category Application TIBCO Hawk AgentResolution Unable to locate rbmap.hrm in config source. Insure that it exists.

HWKRBE-041734 Config object is of incorrect type: <name>, expected Schedules.hsfRole Error

Category Application TIBCO Hawk AgentResolution Unable to locate Schedules.hsf in config source. Insure that it exists.

HWKRBE-041736 Error finding rulebase: <exception>Role Error

Category Application TIBCO Hawk AgentResolution Unable to examine auto-config directory. Check path and permissions.




HWKRBE-041739 Error loading rulebase <name> from <config_source>: <exception>Role Error

Category Application TIBCO Hawk AgentResolution Unable to load named rulebase from named config_source. Check configuration

according to exception or contact TIBCO Support.



HWKRBE-041740 Config object is of incorrect type: <name>, expected COM.TIBCO.hawk.config.rbengine.rulebase.Rulebase


Resolution Unable to locate rbmap.hrm in config source. Insure that it exists.

HWKRBE-041741 Rulebase <name> found in inventory but unable to retrieveRole Error

Category Application TIBCO Hawk AgentResolution Unable to retrieve named rulebase from config source. Check permissions.

HWKRBE-041744 Invoking method <exception>Role Error


HWKRBE-041745 loadRuleBase() may not be invoked when agent is in auto-config mode. Use loadRuleBaseFromFile() instead.


Resolution The loadRuleBase() method of the RBEngineMicroAgent was used under conditions when it is not permitted. Use the loadRuleBaseFromFile() method instead.

HWKRBE-041746 loadRuleBase() invoked without rulebase nameRole Error

Category Application TIBCO Hawk AgentResolution Modify method invocation to include a rulebase name.




HWKRBE-041752 RuleBase file not found: <name>Role Error

Category Application TIBCO Hawk AgentResolution Insure that the named rulebase file exists.

HWKRBE-041753 loadRuleBaseFromFile() invoked without rulebase nameRole Error




Resolution Modify method invocation to include a rulebase name.

HWKRBE-041755 unloadRuleBase() invoked without rulebase nameRole Error

Category Application TIBCO Hawk AgentResolution Modify method invocation to include a rulebase name.

HWKRBE-041757 sendMail: messageNotDelivered.Role Error

Category Application TIBCO Hawk AgentResolution Unable to deliver email. Check email server or sendMail method invocation.

HWKRBE-041758 sendMail: messagePartiallyDelivered.Role Error

Category Application TIBCO Hawk AgentResolution Unable to deliver email. Check email server or sendMail method invocation.

HWKRBE-041759 Send Mail Exception: <exception>Role Error

Category Application TIBCO Hawk AgentResolution Unable to deliver email. Check email server or sendMail method invocation as

per exception or contact TIBCO Support.

HWKRBE-041760 setSchedules() invoked without SchedulesXML parameterRole Error


HWKRBE-041761 Error saving schedules in auto-config: <exception>Role Error

Category Application TIBCO Hawk AgentResolution Check auto-config path or permissions.

HWKRBE-041763 Error deleting rulebase: <exception>Role Error


HWKRBE-041764 addRuleBase() invoked without RulebaseXML parameterRole Error




HWKRBE-041765 Error saving rulebase <name> in auto-config: <exception>Role Error


HWKRBE-041766 updateRuleBase() invoked without rulebaseRole Error


HWKRBE-042301 Arbitrable node <node> threw exception <exception> in response to wonArbitration() call. Deregistering node from Arbiter.



HWKRBE-042302 Arbitrable node <node> threw exception <exception> in response to wonArbitration() call. Queued for deregistration from Arbiter.



HWKRBE-042701 Alert suspension thread interrupted, terminating thread.Role Error

Category Application TIBCO Hawk AgentResolution Contact TIBCO Support if this error persists.

HWKRBE-043301 Fatal error in <thread_name> thread:<exception>Role Error


HWKRBE-043302 SubscriptionMultiplexer error: null event receivedRole Error


HWKRBE-043303 Unchecked exception thrown in SubscriptionMultiplexer thread while processing SubscribeEvent for sub: <subscription>, microagent:<id>, exception: <exception>





HWKRBE-043304 Unchecked exception thrown in SubscriptionMultiplexer thread while calling onSubscriptionError() for handler: <subscription>, microagent:<id>, exception: <exception>



HWKRBE-043305 Unchecked exception thrown in SubscriptionMultiplexer thread by method Subscription.cancel() for sub: <subscription>, microagent:<id>, exception: <exception>



HWKRBE-043307 Unchecked exception thrown in SubscriptionMultiplexer thread while processing MAAddedEvent for sub: <subscription>, microagent:<id>, exception: <exception>



HWKRBE-043308 Unchecked exception thrown in SubscriptionMultiplexer thread while calling onSubscriptionError() for handler: <subscription>, microagent:<id>, exception: <exception>



HWKRBE-043309 SubscriptionMultiplexer error: Unknown event type.Role Error


HWKMAG-020310 stopSubscription call failed for <microagent_id>::<subscription>Role Error


HWKMAG-020313 Inconsistent microagent state for method subscription <subscription>Role Error




HWKMAG-020314 Attempt to remove MicroAgent more than once, <microagent_id>Role Error


HWKCON-220601 RemoteAccessServer dispatch thread caught exception: <com.tibco.rv.TibrvException>



HWKCON-220602 RemoteAccessServer dispatch thread caught exception: <java.lang.Throwable>Role Error


HWKCON-220603 RemoteAccessServer processRequest thread caught exception: <java.lang.Throwable>



HWKCON-220604 RemoteAccessServer.processRequest(), request type= <type> <java.lang.Throwable>



HWKCON-220605 Processing groupOp error reply: <COM.TIBCO.hawk.talon.MicroAgentResolution Exception>



HWKCON-220606 Processing groupOp error reply: <java.lang.Exception>Role Error


HWKCON-220607 Sending reply: <java.lang.Exception>Role Error





HWKCON-220608 processing pingRequest: <java.lang.Exception>Role Error


HWKCON-220609 processing commitRequest: <com.tibco.rv.TibrvException>Role Error


HWKCON-220610 processing refreshRequest: <com.tibco.rv.TibrvException>Role Error


HWKCON-220611 RemoteAccessServer dispatch thread was interrupted: <java.io.InterruptedException>


Resolution Internal error, contact TIBCO Support

HWKCON-220701 DuplicateAgentResolution Check dispatch thread caught exception: <exception>


Resolution Make sure there is only one agent running with the same startup parameters.

HWKCFG-120901 RBMap::toXML() - Unable to write to output stream.\n Exception: <java.io.IOException>



HWKCFG-131101 Failed to convert rulebase <rulebase name> ...Role Error


HWKCFG-110101 MicroAgentDescriptorReader - Unable to read DataDescriptor.\n Exception: <java.lang.Exception>

Role Error




HWKDIS-274404 <COM.TIBCO.hawk.hawkeye.Error ExceptionEvent.getMessage()>Role Error

Category Application TIBCO Hawk DisplayResolution An internal error occurred in the TIBCO Hawk Console API. Contact TIBCO

Support.

HWKDIS-274405 <COM.TIBCO.hawk.console.hawkeye.WarningExceptionEvent.getConsoleWarning().getMessage()>


Resolution The warning exception event should provide additional details

HWKDIS-271604 Unable to locate container - <container>Role Error

Category Application TIBCO Hawk DisplayResolution An error occurred while locating container when moving a container. Verify that

the name of the container to be moved is valid.

HWKDIS-270502 Reading variables file <file name> <java.io.FileNotFoundException>Role Error

Category Application TIBCO Hawk DisplayResolution An error occurred while reading the specified variables file. If the resolution is not

obvious from the exception description then contact TIBCO Support.

HWKDIS-270503 Reading variables file <file name> <java.io.SecurityException>Role Error

Category 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-270504 Reading variables file <file name> <java.io.IOException>Role Error

Category Application TIBCO Hawk DisplayResolution An error occurred while reading the specified variables file. If the resolution is not


HWKDIS-270505 Reading variables file <file name> <java.lang.Exception>Role Error




Resolution An error occurred while reading the specified variables file. If the resolution is not obvious from the exception description then contact TIBCO Support.

HWKDIS-270506 Unable to load variables from file <file name>Role Warning

Category Application TIBCO Hawk AgentResolution Make sure that the variable’s file is readable, it contains at least one valid variable

and is in the proper Java properties format

HWKDIS-270508 Unable to openDisplay Display file - <fileName>Role Error

Category Application TIBCO Hawk DisplayResolution An error occurred while reading the specified display file. This message is

followed by a message with detail reason for the failure.

HWKDIS-270509 Unable to openDisplay - <exception>Role Error


An error occurred while opening a display file. If the resolution is not obvious from the exception description then contact TIBCO Support.

HWKDIS-270511 Unable to initialize TIBCO Hawk Display : <COM.TIBCO.hawk.console.hawkeye.ConsoleInitializationException>

Role ErrorCategory Application TIBCO Hawk Display

Resolution An error occurred while initializing TIBCO Hawk Display. If the resolution is not obvious from the exception description then contact TIBCO Support for assistance.

HWKDIS-270512 Unable to initialize TIBCO Hawk Display : <java.lang.Throwable>Role Error

Category Application TIBCO Hawk DisplayResolution An error occurred while initializing TIBCO Hawk Display. If the resolution is not

obvious from the exception description then contact TIBCO Support for assistance.

HWKDIS-270513 Unable to reinitialize TIBCO Hawk Display : <COM.TIBCO.hawk.console.hawkeye.ConsoleInitializationException>


Resolution An error occurred while reinitializing TIBCO Hawk Display. If the resolution is not obvious from the exception description then contact TIBCO Support for assistance.



HWKDIS-270514 Unable to reinitialize TIBCO Hawk Display : <java.lang.Throwable>Role Error

Category Application TIBCO Hawk DisplayResolution An error occurred while reinitializing TIBCO Hawk Display. If the resolution is

not obvious from the exception description then contact TIBCO Support for assistance.

HWKDIS-270517 Unable to find <key> in HawkGui.properties ...Role Error

Category Application TIBCO Hawk DisplayResolution 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.

HWKDIS-270518 Unable to find <key> in HawkGui.properties ...Role Error

Category Application TIBCO Hawk DisplayResolution 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.

HWKDIS-270901 Unable to locate node in tree - <node>Role Error

Category Application TIBCO Hawk DisplayResolution An error occurred while locating the specified node in the display tree. Contact

TIBCO Support.

HWKDIS-271602 Unable to locate parent node of - <node name>Role Error

Category Application TIBCO Hawk DisplayResolution Internal error. Contact TIBCO Support.

HWKDIS-271603 Unable to locate node in tree - <node name>Role Error


HWKDIS-271604 Unable to locate container - <container name>Role Error


HWKDIS-271605 Unable to find container Discovered




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

HWKDIS-271606 Varying versions of same rulebase <rulebase name> detected on agent <agent name>


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

HWKDIS-272701 Unable to open display file: <file name> - Error <java.io.FileNotFoundException>Role Error

Category Application TIBCO Hawk DisplayResolution 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.

HWKDIS-272702 Unable to open display file: <file name> - Error <java.io.StreamCorruptedException>


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

HWKDIS-272703 Unable to open display file: <file name> - Error <java.lang.Exceptin>Role Error

Category Application TIBCO Hawk DisplayResolution 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.

HWKDIS-273903 Unsupported resources version: <version>Role Error

Category Application TIBCO Hawk DisplayResolution The properties file is of different version. Check or re-install Hawk to ensure that

HawkGui.properties and Display are of the same version.

HWKDIS-273904 Missing resources file HawkGui.properties ... exitingRole Error




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.

HWKDIS-275502 Image Directory not found...Role Error

Category Application TIBCO Hawk DisplayResolution The image directory is not found. Check or re-install Hawk to ensure that

HawkGui.properties is at the proper location.

HWKDIS-275601 Unable to send config object. - Error <COM.TIBCO.hawk.talon.MicroAgentException>


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

HWKDIS-300401 ERROR: building method invocation while performing network query/action: <exception message>


Resolution An error occurred while performing network query/action. The exception message should provide more details about the error.

HWKDIS-300402 ERROR: performing network query/action: <exception message>Role Error

Category Application TIBCO Hawk DisplayResolution An error occurred while performing network query/action. The exception

message should provide more details about the error.

HWKDIS-300403 ERROR: parsing results while performing network query/action: <exception message>



HWKDIS-300801 Unable to retrieve Micro Agents from - <hostname>. - Error: <java.lang.Exception>





HWKDIS-310101 Failed to invoke java command: <toolCommand>; Exception - <java.lang.Exception>


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

HWKDIS-310402 Failed to load resources from input stream ...Role Error

Category Application TIBCO Hawk DisplayResolution An error occurred while loading resource such as an icon. Verify that the

resource’s path is valid.

HWKDIS-310403 Error saving preferences to resources file <file name>.Role Error

Category Application TIBCO Hawk DisplayResolution 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.

HWKDIS-310404 Failed to invoke java command: <toolCommand>; Exception - <java.lang.Exception>


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

HWKDIS-310601 IllegalAccessException: <error text>Role Error

Category Application TIBCO Hawk DisplayResolution 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.

HWKDIS-310602 IllegalArgumentException: <error text>Role Error




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.

HWKDIS-310603 InvocationTargetException: <error text>Role Error

Category Application TIBCO Hawk DisplayResolution 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.

HWKDIS-310604 ExceptionInInitializerError: <error text>Role Error

Category Application TIBCO Hawk DisplayResolution 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.

HWKDIS-331201 Unable to save rulebase <rulebase name> to file <file name>Role Error

Category Application TIBCO Hawk DisplayResolution 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.

HWKDIS-331202 Unable to save Rulebase - <file name> \n <java.lang.Exception>Role Error

Category Application TIBCO Hawk DisplayResolution A error occurred while saving rulebase to a local file system. If the resolution is


HWKDIS-331203 Unable to add rulebase - <rulebase name>; Exception: <java.lang.Exception>Role Error

Category Application TIBCO Hawk DisplayResolution A error occurred while sending the rulebase to the agent. If the resolution is not


HWKDIS-331204 Unable to add rulebase - <rulebase name>; Exception: <COM.TIBCO.hawk.talon.MicroAgentException>


Resolution A error occurred while sending the rulebase to the agent. If the resolution is not obvious from the exception description then contact TIBCO Support.



HWKDIS-331205 Unable to update rulebase - <rulebase name>; Exception: <java.lang.Exception>Role Error

Category Application TIBCO Hawk DisplayResolution A error occurred while sending the rulebase to the agent. If the resolution is not


HWKDIS-331206 Unable to update rulebase - <rulebase name>; Exception: <COM.TIBCO.hawk.talon.MicroAgentException>



HWKDIS-331207 Unable to unload rulebase - <rulebase name>; Exception: <java.lang.Exception>Role Error

Category Application TIBCO Hawk DisplayResolution A error occurred while unloading the rulebase from the agent. If the resolution is


HWKDIS-331208 Unable to unload rulebase - <rulebase name>; Exception: <COM.TIBCO.hawk.talon.MicroAgentException>


Resolution A error occurred while unloading the rulebase from the agent. If the resolution is not obvious from the exception description then contact TIBCO Support.

HWKDIS-331209 Unable to send rulebase; Exception: <COM.TIBCO.hawk.talon.MicroAgentException>



HWKDIS-331210 Unable to retrieve rulebase <rulebase name> from <agent or repository name>; Exception: <java.lang.Exception>


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

HWKDIS-332912 Unable to load Micro Agent Descriptors from - <host name>; Exception - <java.lang.Exception>




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

HWKDIS-331301 Unable to clone rulebase for - <rulebase name>; Exception - <java.lang.Exception>


Resolution Internal Error Contact TIBCO Support.

HWKDIS-332901 Unable to export Micro Agent Descriptors from - <host name>; Exception - <java.lang.Exception>


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

HWKDIS-340801 Unable to retrieve Micro Agents from - <agent name>; Exception - <java.lang.Exception>


Resolution An error occurred while retrieving micro agents from the specified agent. The exception message should provide more details about the error.

HWKDIS-350401 Unable to execute command - <command string>Role Error

Category Application TIBCO Hawk DisplayResolution An error occurred while executing the specified command in the command file

for Tekmon support. Verify that the command is a valid command.

HWKDIS-381301 Unable to retrieve schedules from - <host or repository name>. - Error <java.lang.Exception>


Resolution An error occurred while retrieving schedules from either the agent or repository. The exception message should provide more details about the error.

HWKDIS-381401 Unable to send Schedules; Exception - <java.lang.Exception>Role Error




Resolution An error occurred while sending schedules to either the agent or repository. The exception message should provide more details about the error.

HWKEVT-390101 Missing -datadir and JDBC command line options. TIBCO Hawk events will not be persistent

Role WarningCategory Application TIBCO Hawk Event Service

Resolution Specify missing command line options if TIBCO Hawk events needs to be written to file or database.

HWKEVT-390104 Setting data destination failed. Exiting !!Role Error

Category Application TIBCO Hawk Event ServiceResolution Make sure that the directory specified for -datadir command line option has write

permission

HWKEVT-390106 java.lang.NumberFormatExceptionRole Error

Category Application TIBCO Hawk Event ServiceResolution Check command line options and verify that they are all correct

HWKEVT-390107 java.lang.UnsupportedEncodingExceptionRole Error

Category Application TIBCO Hawk Event ServiceResolution Check command line option -characer_encoding and verify that it is valid

HWKEVT-390108 java.lang.ExceptionRole Error

Category Application TIBCO Hawk Event ServiceResolution Contact TIBCO Support

HWKEVT-390110 Failed to create FT TibrvRvdTransport - <com.tibco.tibrv.TibrvException>Role Error

Category Application TIBCO Hawk Event ServiceResolution Check the TIBCO Rendezvous session -rvd_session command line option and

verify that it is valid

HWKEVT-390111 Exception joining fault tolerance group - <com.tibco.tibrv.TibrvException>Role Error

Category Application TIBCO Hawk Event ServiceResolution Check the TIBCO Rendezvous fault tolerant -ft command line option and verify

that it is valid



HWKEVT-390701 Unable to create RV session for AMI communication - <com.tibco.tibrv.TibrvException>

Role ErrorCategory Application TIBCO Hawk Event Service

Resolution Check the TIBCO Rendezvous session -ami_rvd_session command line option and verify that it is valid

HWKEVT-390802 JDBC Driver is unable to insert a record for "onAgentAlive" event. <java.sql.SQLException>


Resolution Contact JDBC driver vendor for more info

HWKEVT-390803 JDBC Driver is unable to insert a record for "onAgentExpired" event. <java.sql.SQLException>



HWKEVT-390804 JDBC Driver is unable to insert a record for "onAlert" event. <java.sql.SQLException>



HWKEVT-390805 JDBC Driver is unable to insert a record for "onClear" event. <java.sql.SQLException>



HWKEVT-390806 JDBC Driver is unable to insert a record for "onMicroAgentChange" event. <java.sql.SQLException>



HWKEVT-390807 JDBC Driver is unable to insert a record for "onRulebaseChange" event. <java.sql.SQLException>





HWKEVT-390808 JDBC Driver is unable to create table "HawkAgentInfo". <java.sql.SQLException>Role Error

Category Application TIBCO Hawk Event ServiceResolution Contact JDBC driver vendor for more info

HWKEVT-390809 JDBC Driver is unable to create table "HawkAlertClearInfo". <java.sql.SQLException>



HWKEVT-390810 JDBC Driver is unable to close connection. <java.sql.SQLException>Role Error

Category Application TIBCO Hawk Event ServiceResolution Contact JDBC driver vendor for more info




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

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

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


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.

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.

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

escalation period. The period of time following the false-to-true transition of an action’s 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.

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.

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

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.

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

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.

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.

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.


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.

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

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.

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.

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

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


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 AgreementREAD 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 AgreementsThe following are the software licenses for the Third Party Software provided in connection with the software.

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 [email protected].

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

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 [email protected].

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.


348 | Third Party Software License Agreements


| 349

Index

A

accessingAction Editor 80Advanced Rule Editor 143Advanced Rulebase Editor 134Alert Detail window 57Canvas View 25Repository View 102Rule Editor 67Rulebase Editor 67Rulebase View 31

Action Editor, accessing 80actions

advanced options 84clear 79clearing 60creating 80escalating 85network 212specifying variables in 139substituting variables in 141

addingagents to Canvas View 26containers 21tools menu commands 36

advancedaction options 84rule options 143rulebase options 134test options 78

Advanced Action Editor, accessing 84Advanced Rule Editor, accessing 143Advanced Rulebase Editor, accessing 134Advanced Test Editor, accessing 78Agent View 16

agents 255auto-discovery 16default icon colors 16finding 23performing actions on multiple 212querying multiple 206querying remote 206removing rulebases from Repositories 106retrieving rulebases on 66rulebase map groups 124sending rulebases to 93sending rulebases to Repositories from 104sending to containers 22using a rulebase map 127viewing alerts for 56viewing icons for 17viewing log files 255

Alert Detail window, accessing 57Alert Display

description of 56filtering alerts from 57viewing details in 57

alertsadding sound to 35changing default colors 35clearing 60marking all 58suspending 58viewing for a rulebase 31viewing for an agent 56viewing purged 60

AMIdescription 10monitoring instrumented applications 199role in applications monitoring 4

arguments, methodspecifying 70using regular expressions in 250

arguments, method, specifying 70


350 | Index

asynchronous methodsclearing actions from 60description 49using in a rule 70

auto-discovery 16Automatic Configuration mode

consequences of 108description 99

automatingfile system space monitoring 189log file monitoring 194process existence monitoring 187process resource consumption monitoring 187system resource monitoring 191

B

Boolean test operators 76

C

Canvas Viewaccessing 25adding agents to 26adding shapes to 27lock mode 28

character encoding 220charts, viewing subscriptions as 54clear actions, specifying 79clear conditions, specifying 79clear test option 79clear timer option 79clearing alert messages 60codepage configuration 220command line length 235, 236commands

adding to a rulebase 136adding to Tools menu 36executing on loss of heartbeat 118

compound tests 76

configuration modesAutomatic 99Manual 100overview 98scenarios 108

containersadding 21deleting 23finding agents in 23renaming 22sending agents to 22

copying rulebases 91creating

actions 80rulebase maps 122rulebases 67rules 68schedules 149tests in a rule 71

customer support xviii

D

data delivery interval, specifying 53data files, Event Service 116data source variables 141data sources

example 69See also methods, microagentspecifying in a rule 68

deletingcontainers 23rulebases 92, 94

deriving rulebases 91

E

email, sending with actions 81encoding 220escalating actions 85evaluation intervals, test 71


Index | 351

Event Service log, TIBCO Hawk 257Event.log 257executing commands

from an agent icon 40in a rulebase 136on loss of heartbeat 118on the Tools menu 37

expressionsbuilding test 72using regular 248, 250

external variables 139referencing in a rulebase 139, 140

F

false host list 210file systems, monitoring space in 189files

loading display 33loading rulebases from 90rulebase 89rulebase map 134saving display 33saving rulebase maps in 133saving rulebases in 89

finding agents in containers 23first false option 79

G

group operations, performing 202groups, agent 124

H

Hawk.log 255Hawk_HMA.log 258.hrb files 89.hrm files 133

.hsf files 168

I

identifier, character encoding 220identifying same-named processes 184IMPACT_ACTION methods, definition of 49IMPACT_ACTION_INFO methods, definition of 49IMPACT_INFO methods, definition of 49including rulebases 134in-schedule 165internal variables 140intervals

data delivery 53recovered to OK 35test evaluation 71

invoking methodsinteractively 49remotely 204

L

limit on command line length 235, 236limit on process line length 235loading

display files 33rulebase files 90rulebase map files 134rulebases using methods 172

lock mode, Canvas View 28log files

monitoring 192TIBCO Hawk agent 255TIBCO Hawk Display 256TIBCO Hawk HMA 258TIBO Hawk Event Service 257


352 | Index

M

Manual Configuration modeConfiguration Path option 100consequences of 108overview 100Repository option 101

marking alerts 58memory usage, testing 73methods, microagent

asynchronous 49invoking interactively 49invoking remotely 204–212referencing in actions 141results of 51subscribing to 52synchronous 49types of 49using to load rulebases 172

microagent methodsSee methods, microagent

microagentsdefault platform-independent 44interrogating remote 204refreshing list of 48using methods in a rule 49

monitoringAMI applications 199file system space 189log files 192process resource consumption 187system resources 191with custom scripts 196

N

network actions 212network queries

adding tests to 208definition 206sending 206viewing results of 210

numeric test operators 73

O

operators, testspecifying 73specifying values for 73

overrulingallowing in a rule 143description 143overlapping rules for 144

P

Period Groups 148Perl5PatternMatch

syntax 248test operator for 76

Post Condition, action type 81posted conditions

counting result sets 146creating with actions 81description 146monitoring processes with 185test operators for 75testing values 146

preferencesadding tools menu commands 36setting options 35

problem escalation 85process line length 235processes

identifying same-named 184monitoring in a rule 70monitoring resources for 187monitoring with posted conditions 185

Q

queries, network 206querying multiple agents 206


Index | 353

R

recovered to OK interval 35refreshing microagent list 48REGEXP syntax 250regular expressions

elements 250modifiers 249Perl5PatternMatch 248REGEXP 250using in method arguments 250using in tests 248

removingrulebases from agents 94rulebases from Repositories 106

renaming containers 22Repositories

accessing objects in 102definition of 101removing rulebases from 106removing rulebases from other 107saving rulebases in 103sending rulebases to 104sending rulebases to other 105viewing icons in TIBCO Hawk Display 102

Repository View, accessing 102resources

monitoring process consumption 187monitoring system 191

Rule Editor, accessing 67Rulebase Editor, accessing 67rulebase map

assigning rulebases in 127creating 122defining agent groups 124–127definition 122loading from file 134saving to file 133

Rulebase View, accessing 31

rulebasesadding commands to 136applying schedules to 148, 166automating management 172copying 91creating 67deleting 94deleting from an agent 92deriving 91description 64including 134loading from files 90mapping to agents 127overruling rules in 143referencing internal variables in 140removing from a Repository 107removing from an agent 92removing from other agents 94retrieving for an agent 66saving in a Repository 103saving on an agent 88saving to files 89sending from agent to Repository 104sending to a Repository 104sending to agents 93sending to other Repositories 105viewing alerts for 31

rulesallowing overruling for 143creating 68description 64, 68overlapping 144overruling 143specifying a data source 68using to monitor processes 70

S

savingdisplay files 33rulebase maps to files 133rulebases to files 89

scenarios, configuration 108


354 | Index

schedulesapplying 166creating 149definition 148testing 164

scriptsexecuting from Tools menu 36monitoring with 196

Sending 22sending

agents to containers 22email with actions 81rulebases 93rulebases to a Repository 104rulebases to agents 93

specifyingdata delivery intervals 53external variables in actions 82true test counters 79

starting TIBCO Hawk Display 15subscribing to methods 52subscriptions

comparing multiple 55creating 52viewing charts of 54viewing tables of 55

support, contacting xviiisuspending alerts 58synchronous methods

clearing actions from 60description 49specifying data delivery intervals for 53using in a rule 70

syntaxdata source variable 141external variable rulebase 139internal variable 140Perl5PatternMatch 248REGEXP 250

system resources, monitoring 191

T

Tabular View 55technical support xviiiTest Builder, accessing 72Test Editor, accessing 71testing

rule boundaries 52schedules 164

testsadding to network queries 208advanced options 78Boolean operators 76compound 76creating in a rule 71description 71evaluation intervals 71numeric operators 73scheduling 79specifying clear actions for 79specifying clear conditions for 79specifying expressions in 72true test counters 79using posted conditions in 146using regular expressions in 248

TIBCO Hawk Displayaccessing Canvas View 25, 26accessing Rulebase View 31adding containers in 21changing views of 17default icon colors 16finding agents in 23loading from a file 33organizing agents 22saving customized views 33saving in a file 33starting 15viewing log files 256


Index | 355

TIBCO Hawk Event Serviceexecuting commands with 118integrating with 119interpreting data files 116numeric alert levels in 117overview 112viewing log files 257viewing purged alerts 60

TIBCO Hawk HMA log files 258Tools menu, adding commands to 36true host list 210truncated process names 235

V

variableseffect on actions 141referencing data source 141referencing external 139referencing internal 140specifying in actions 139

viewingalert messages 56alerts for an agent 56log files 255Repository icons 102rulebase icons 31


356 | Index

Hawk Admin

Documents