eSleuth 1.0
`
`User’s Guide
`
`Bristol Technology Inc.
`39 Old Ridgebury Road
`Danbury, CT 06810-5113
`USA
`(203) 798-1007
`
`Bristol Technology BV
`Plotterweg 2A
`3821 BB Amersfoort
`The Netherlands
`+31 (0)33 450 50 50
`
`HP_1011_0001
`
`

`

`Printed April 13, 2000
`
`This manual supports eSleuth Early Adoption Release 1.0.x.
`No part of this manual may be reproduced in any form or by any means without written permission of:
`
`Bristol Technology Inc
`39 Old Ridgebury Road
`Danbury, CT 06810-5113 U.S.A.
`
`Copyright © Bristol Technology Inc. 2000
`
`RESTRICTED RIGHTS
`
`The information contained in this document is subject to change without notice.
`
`For U.S. Government use:
`Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the
`Rights in Technical Data and Computer Software clause at 52.227-7013.
`
`All rights reserved. Printed in the U.S.A.
`
`The information in this publication is believed to be accurate in all respects; however, Bristol Technology Inc. cannot
`assume responsibility for any consequences resulting from its use. The information contained herein is subject to
`change. Revisions to this publication or a new edition of it may be issued to incorporate such changes.
`
`Bristol Technology® and eSleuthTM are trademarks of Bristol Technology Inc. All other trademarks herein are the
`property of their respective holders.
`
`General Notice: Some of the product names used herein have been used for identification purposes only and may be
`trademarks of their respective companies.
`
`Part No. ES11000404
`
`HP_1011_0002
`
`

`

`Contents
`
`Chapter 1 Getting Started with eSleuth . . . . . . . . . . . . . . . . . . . . . . .
`eSleuth Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Analyzer Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Steps for Using eSleuth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Quick Tour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`Chapter 2 Configuring eSensors . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Loading eSensors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Logging eSensor Trace Information . . . . . . . . . . . . . . . . . . . . . . . . . . .
`eSensors and FASTPATH_BINDING . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`Chapter 3 Managing eSleuth Projects . . . . . . . . . . . . . . . . . . . . . . .
`Creating, Opening, and Closing Projects . . . . . . . . . . . . . . . . . . . . . . . .
`Recording eSleuth Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Changing Project Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Configuring Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Changing Communication Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`Chapter 4 Using eSleuth Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Using the Component Layout View . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Using the Event Timeline View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Using the Event List View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Using the Event Details View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`Chapter 5 Presentation Filter Script Reference . . . . . . . . . . . . . . . .
`eSleuth COM Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`COM Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
` 1
`1
`6
`7
`8
`
` 17
`17
`18
`19
`
`21
`21
`24
`25
`28
`33
`
` 35
`35
`44
`48
`53
`
` 57
`57
`58
`60
`
`eSleuth User’s Guide
`
`i
`
`HP_1011_0003
`
`

`

`Contents
`
`Chapter 6 Troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Communication Link Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Database Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Event Recording Problems on Windows NT . . . . . . . . . . . . . . . . . . . . .
`Disabling SHLIB_PATH on HP-UX . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
` 63
`63
`65
`66
`66
`
`ii
`
`eSleuth User’s Guide
`
`HP_1011_0004
`
`

`

`Chapter 1
`Getting Started with eSleuth
`
`eSleuth is eBusiness transaction analysis software that graphically shows you the
`interaction between all the components of your system. The information presented by
`eSleuth enables you to visually identify and resolve logic and performance problems
`throughout your system from a single console.
`
`During application development, using eSleuth enables you to identify problems that
`you may otherwise not find, improving the reliability and quality of your eBusiness
`application. Because eSleuth replaces tedious, time-consuming, and error-prone
`debugging tasks, it speeds the deployment of your application. After you deploy, you
`can continue using eSleuth to monitor your system for errors in a production
`environment.
`
`eSleuth Components
`eSleuth consists of two main components: eSensors that collect information from your
`applications and an Analyzer, which stores the data received from eSensors, correlates
`it into transactions, and graphically displays information.
`
`eSensors
`
`eSensors are lightweight agents installed on each computer in your eBusiness
`application environment. They monitor each MQSeries API (MQI) call made on that
`system and compare it agains filter conditions. If the call matches the filter conditions,
`eSensors generate an eSleuth event that contains information about the call, and
`forward the eSleuth event to the Analyzer.
`
`eSensors do not require you to change or recompile your applications, even if they are
`compiled in optimized (non-debug) mode.
`
`eSleuth User’s Guide
`
`1
`
`HP_1011_0005
`
`

`

`Chapter 1 • Getting Started with eSleuth
`eSleuth Components
`
`eSensors use MQSeries queues to send captured information to the eSleuth Analyzer.
`The eSleuth Administrator’s Guide provides instructions for installing eSensors and
`creating communication links for them to use.
`
`Data Collection Filters
`eSensors use data collection filters defined by the Analyzer to determine the amount
`and type of information collected by each eSensor. Data collection filters specify the
`following:
`• Which hosts, programs, or APIs to collect information about
`• Which queues or queue managers to collect information about
`• What time range to collect information for
`•
`The level of detail to be collected, such as API name only, API name and call
`arguments, or API name, call arguments, and data buffer segment
`eSensor Library
`The eSensor library implements all MQI entry points and has the same name as the
`standard MQSeries library (for example, mqm.dll on Windows NT). It is installed in
`a different directory location, and any monitored process calls the eSensor library at
`runtime instead of the standard MQSeries library.
`
`application
`
`application
`
`eSensor
`
`M Q I
`
`filtering criteria
`event information
`
`eSleuth
`Analyzer
`
`filtering criteria
`
`event information
`
`MQI
`
`eSensor
`
`MQSeries
`
`MQSeries
`
`When a program running on the system where an eSensor is installed calls an MQI, it
`actually calls the corresponding function in the eSensor library.
`
`2
`
`eSleuth User’s Guide
`
`HP_1011_0006
`
`

`

`Chapter 1 • Getting Started with eSleuth
`eSleuth Components
`
`The eSensor function first generates an eSleuth event, recording the MQI call and other
`details based on the data collection filters. It then invokes the actual MQI from the
`standard MQSeries library. When the actual MQI returns, the eSensor function
`generates another eSleuth event, this time representing the exit state of the function,
`and then forwards the return information to the calling program.
`
`Important! For eSensors to intercept MQI calls from applications, the applications must link
`dynamically to the MQSeries library as a shared library. Otherwise, eSensors cannot
`record events for the applications.
`
`On the OS/390 platform, the CICS subsystem does not support dynamic linking to
`shared libraries. Rather than requiring applications to be re-linked with the eSensor
`library, eSensors on this platform use the crossing exit mechanism provided by CICS.
`
`Analyzer
`
`The eSleuth Analyzer is a Windows NT application that collects eSleuth events from
`all eSensors installed throughout your organization, performs different kinds of data
`analysis on the collected events, presents event information in a variety of formats, and
`enables you to control data collection filters for eSensors.
`eSleuth Projects
`The Analyzer uses projects to distinguish between various Analyzer sessions. Each
`project keeps track of the user preferences for Analyzer settings and maintains an event
`database. Other project information includes the following:
`• Which communication links the Analyzer should connect to
`• Which data collection filters to use to control event collection by the eSensors
`•
`Any database restrictions such as a maximum number of events
`Analyzer Views
`The eSleuth Analyzer provides four different views of event data collected by the
`eSensors.
`
`The Component Layout view graphically displays the interaction between all
`components of your eBusiness system, including message queues, programs, and hosts.
`Because eSleuth builds this graph from data collected during program execution, it is
`an accurate and complete representation of how information flows throughout your
`system. The thickness of the lines between components can be set to indicate
`performance characteristics of your system. Color-coding makes error conditions easy
`to pinpoint at a glance. You can customize the appearance of the Component Layout
`View and print it as a map of your entire eBusiness system.
`
`eSleuth User’s Guide
`
`3
`
`HP_1011_0007
`
`

`

`Chapter 1 • Getting Started with eSleuth
`eSleuth Components
`
`The Event Timeline view correlates events across multiple programs, hosts, and
`operating systems into transactions. Color coding makes it easy to distinguish between
`local transactions, which occur in the same unit of work in a single program instance,
`and business transactions, which consist of local transactions associated with each
`other by the same MQSeries message ID, correlation ID, and other information.
`
`4
`
`eSleuth User’s Guide
`
`HP_1011_0008
`
`

`

`Chapter 1 • Getting Started with eSleuth
`eSleuth Components
`
`The Event List view displays all events in the event database in chronological order.
`Color coding makes it easy to spot events with a warning or error return code at a
`glance. You can limit the events shown to only the events that make up the local or
`business transaction associated with the currently selected event.
`
`The Event Details view provides additional information about any event in the Event
`Timeline View or the Event List View. The Event Details view interprets and displays
`all of the information in the MQMD header information, the dead letter queue header,
`and the user data buffer associated with the event. Multiple Event Detail windows
`enable you to compare data structure contents of any two events.
`
`eSleuth User’s Guide
`
`5
`
`HP_1011_0009
`
`

`

`Chapter 1 • Getting Started with eSleuth
`Analyzer Interface
`
`Presentation Filters
`While data collection filters control the events collected by eSensors, presentation
`filters control which collected events are actually displayed by the Analyzer.
`Presentation filters enable you to zero in on specific events from the event database.
`For example, you may specify that you only want to see MQPUT events with a
`particular message ID. You may configure presentation filters by selecting criteria on a
`dialog, or, for more complex criteria, through eSleuth’s VBScript interface.
`
`Analyzer Interface
`
`Menus
`Toolbar
`
`View Area
`
`Event Details
`
`Status Panel
`
`Menus
`
`All eSleuth Analyzer operations can be performed by selecting the appropriate menu
`item. In addition to the main menu, context menus are available for each Analyzer
`view. To access context menus, right-click in the current view. Context menu items
`depend on where the cursor is pointing when you access the context menu. In the
`Component Layout View, for example, the context menu items associated with a
`program icon are different from the menu items for queue manager icon.
`
`6
`
`eSleuth User’s Guide
`
`HP_1011_0010
`
`

`

`Chapter 1 • Getting Started with eSleuth
`Steps for Using eSleuth
`
`Toolbars
`
`In addition to menus, the eSleuth toolbars provide quick access to common Analyzer
`operations. To hide or show toolbars, use the View > Toolbars menu item.
`
`New Project
`Close Project
`Create Event List View
`Create Event Timeline View
`Refresh Current View
`
`Data Collection Filter
`Start Data Collection
`Stop Data Collection
`Presentation Filter
`
`Open Project
`Communication Liks
`Create Component Layout View
`Show/Hide Event Details
`Refresh All Views
`
`Zoom Out
`Zoom In
`Fit to Page
`
`Layout Properties
`Zoom Percent
`
`View Area
`
`Event Detail Area
`
`The Component Layout view, Event Timeline view, and Event List view each appear
`in a separate window in the view area. The CTRL+TAB key sequence changes the
`active window in the view area. You may open multiple instances of each view.
`
`The Event Details view appears in the Event Detail area. You can view details for two
`events at once for a side-by-side comparison of events. To hide or show the Event
`Detail area, use the View > Event Detail menu item.
`
`Steps for Using eSleuth
`To diagnose eBusiness system problems with eSleuth, you’ll follow these steps:
`1. Create an eSleuth project. Project settings such as communication links, data
`collection and presentation filters, and database settings control the type and
`quantity of information to collect. See Chapter 2, “Managing eSleuth Projects.”
`2. Use eSleuth Analyzer views to identify problems and drill down into the event
`details you need to resolve them. See Chapter 3, “Using eSleuth Analyzer Views.”
`
`If eSleuth is not installed on your system or if communication links are not defined for
`you to select when creating a project, see the eSleuth Administrator’s Guide for
`instructions on performing these tasks.
`
`eSleuth User’s Guide
`
`7
`
`HP_1011_0011
`
`

`

`Chapter 1 • Getting Started with eSleuth
`Quick Tour
`
`Quick Tour
`
`To get a better idea of how eSleuth helps you identify problems, let’s look at a simple
`example. As we go through this example, you will follow some general steps for
`identifying problems. However, the steps you take to diagnose problems in your own
`system with eSleuth will be depend on the initial results you see.
`
`Our example application is a mortgage processing system. Agents at remote locations
`enter application information. A number of programs running on different computers
`process the information, then return the results (approved or declined) to the agents.
`
`Start an eSleuth Project
`To see how information flows throughout this system, perform the following steps to
`start the eSleuth Analyzer and open a project based on this mortgage processing
`system.
`
`1. From the Windows Start menu, choose Programs > Bristol eSleuth > eSleuth Analyzer
`to start the Analyzer.
`
`2. From the File menu in the Analyzer, choose Open Project.
`
`3.
`
`In the Open dialog box, navigate to the C:\Program Files\Bris-
`tol\eSleuth Analyzer\tutorial\demo_success directory, select
`the file demo_success.epj and click Open.
`
`4. Click
`
` on the eSleuth toolbar to open a Component Layout view.
`
`The Component Layout view shows the interaction between components throughout
`the system. In this system, the agent’s application, testmort, sends application
`information to the mortgage application, which then sends the application information
`to different programs for processing different types of information. These programs are
`called credit, asset, appraisal, titlesearch, income, and tax. Each of these programs
`sends its results to evaluator, which evaluates the results from each program and
`notifies testmort whether the application is approved or declined. All communication
`between components is carried out using MQSeries. The Component Layout view
`shows icons for the queues as well as for the programs.
`
`Notice that the logical flow of information throughout this system is a closed circle that
`starts and ends with the testmort application.
`
`8
`
`eSleuth User’s Guide
`
`HP_1011_0012
`
`

`

`Chapter 1 • Getting Started with eSleuth
`Quick Tour
`
`Starting the Search
`During testing following some system maintenance, however, testmort no longer
`receives approval results for submitted applications. Open a project for the failed
`application to determine the reason.
`1. Choose the File > Close Project menu item to close the current project.
`2. Choose the File > Open Project menu item to open the project for the failed applica-
`tion. This application is located in the C:\Program Files\Bris-
`tol\eSleuth Analyzer\tutorial\demo_failure directory and is
`named demo_failure.epj.
`3. Click
` on the eSleuth toolbar to open a Component Layout view.
`
`Narrowing the Search
`Notice that the flow of information on this Component Layout view is not a closed
`circle. Information goes into the evaluator program, but no messages come out.
`
`eSleuth User’s Guide
`
`9
`
`HP_1011_0013
`
`

`

`Chapter 1 • Getting Started with eSleuth
`Quick Tour
`
`To find out more about the flow of information, point your cursor to the view
`background and right-click. From the shortcut menu, choose Edge Widths > Successful
`MQGET/MQPUT/MQPUT1 Call Count. You should be able to tell at a glance that the edges
`going from the various programs into the ES.RESULT.QUEUE queue are thicker than
`the edge going from ES.RESULT.QUEUE to evaluator.
`
` on the eSleuth toolbar to zoom in so that you can read the labels of the edges
`Click
`in that area of the view. Notice that each processing program sends two messages to the
`queue (one for each application submitted by testmort) for a total of 12 messages on
`the queue, but evaluator only retrieves one message. The question now is whether
`evaluator is not trying to get the other messages off the queue or whether it is trying
`and failing.
`
`10
`
`eSleuth User’s Guide
`
`HP_1011_0014
`
`

`

`Chapter 1 • Getting Started with eSleuth
`Quick Tour
`
`Finding the Point of Failure
`Click
` on the eSleuth toolbar to open the Event List view. You can see a list of all
`events in the project database. In this view, error and warning messages are color coded
`to make them easy to find. Scroll down until you see the first event printed in red text.
`This event is an MQGET call from evaluator. The far right-hand columns show that
`this call failed with a reason code of “No Message Available.”
`
`eSleuth User’s Guide
`
`11
`
`HP_1011_0015
`
`

`

`Chapter 1 • Getting Started with eSleuth
`Quick Tour
`
`This reason code makes it appear that there was no message on the queue, but the
`Component Layout view indicated that 12 messages were placed on the queue. You
`now need to determine whether the problem is that the messages are expiring before the
`MQGET call retrieves them or whether there is a problem with the MQGET call in
`evaluator.
`
`Viewing Transactions in Sequence
`Click
` on the eSleuth toolbar to see the Event Timeline view. To focus on the
`programs and queue where we’ve already determined the problem lies, let’s create and
`apply a presentation filter.
`
` on the eSleuth toolbar to open the Presentation Filter dialog.
`
`1. Click
`2. Click
` in the Filters area and enter demo as the new filter name.
`3. Click Queue Managers, expand QM.bennytpcx.bristol.com, and check
`ES.RESULT.QUEUE to limit the display to events involving this queue.
`
`4. Click Programs and check appraisal, asset, credit, evaluator, income, tax, and
`titlesearch to limit the display to events involving these programs.
`5. Click OK to apply the presentation filter.
`
`Notice that you can see all the MQPUT events from the processing programs along
`with the one successful and one failed MQGET event by evaluator.
`
`12
`
`eSleuth User’s Guide
`
`HP_1011_0016
`
`

`

`Chapter 1 • Getting Started with eSleuth
`Quick Tour
`
`Analyzing the Details
`To determine whether the messages are expiring on the queue before evaluator
`retrieves them, point your cursor to the first MQPUT event in the asset column.
`Double-click to open this event in the Event Details view. (You may need to click
`on the eSleuth toolbar first to open the Event Details window.)
`
`
`
`Scroll down until you see the Expiry field. The value is 1000 tenths of a second, or 100
`seconds. A quick glance at the time column shows that the failed MQGET call was less
`than a second later, so you can rule out the possibility that the messages expired before
`evaluator retrieved them. The problem must be in the MQGET call.
`
`eSleuth User’s Guide
`
`13
`
`HP_1011_0017
`
`

`

`Chapter 1 • Getting Started with eSleuth
`Quick Tour
`
`To help find the problem in the failed MQGET call, compare it to the successful
`MQGET. First select the failed MQGET call and drag it to the left-hand side of the
`Event Details view. Then select the successful MQGET call and drag it to the right-
`hand side. Scroll both calls, comparing the field values.
`
`14
`
`eSleuth User’s Guide
`
`HP_1011_0018
`
`

`

`Chapter 1 • Getting Started with eSleuth
`Quick Tour
`
`When you get to the MsgId field for the entry event, notice that the values are different.
`The successful MQGET has an entry message ID of MQMI_NONE, indicating that it
`should get the next event from the queue. The failed MQGET, however, has a specific
`entry message ID. Compare this message ID to the exit message ID of the successful
`call, and you’ll see that they are the same. The message ID was not reset after the first
`MQGET call—a fairly common problem in MQSeries applications.
`
`While this is a fairly simple problem, it is also a fairly common one. The same
`techniques used in this sample will help you identify problems in your own system:
`•
`First use the Component Layout view to identify the general area where the
`problem occurs.
`Next, use the Event List and Event Timeline views in conjunction with
`presentation filters to identify specific events related to the problem.
`Finally, use the Event Details view to pinpoint the exact problem cause.
`
`•
`
`•
`
`eSleuth User’s Guide
`
`15
`
`HP_1011_0019
`
`

`

`Chapter 1 • Getting Started with eSleuth
`Quick Tour
`
`16
`
`eSleuth User’s Guide
`
`HP_1011_0020
`
`

`

`Chapter 2
`Configuring eSensors
`
`eSensors are lightweight libraries that monitor MQSeries application by capturing
`event information about each application MQSeries API call and forwarding it to the
`eSleuth Analyzer. An eSensor must be installed on each computer running applications
`that you want to analyze with eSleuth. A single eSensor library is used by all
`applications on that computer. For instructions on installing eSensors, see the eSleuth
`Administrator’s Guide.
`
`Loading eSensors
`The eSensor library is dynamically loaded into a program’s address space when the
`program makes an MQSeries API call. Before you can use eSleuth to record event data
`for an application, you must configure the application environment to load the eSensor
`library instead of the standard MQSeries library.
`
`On all platforms other than OS/390 (CICS), you must add the directory location of the
`eSensor library to an environment variable setting on the computer where the
`monitored application runs before starting the application. The following table shows
`the appropriate environment variable and directory location to set for each platform. In
`all cases, the eSleuth entry must precede the standard MQSeries library entry.
`
`Platform
`
`Environment
`Variable
`
`Directory
`
`Windows NT
`
`PATH
`
`C:\Program Files\Bris-
`tol\eSleuth eSensor\bin
`
`Sun Solaris
`
`LD_LIBRARY_PATH
`
`/opt/eSleuth/bin
`
`eSleuth User’s Guide
`
`17
`
`HP_1011_0021
`
`

`

`Chapter 2 • Configuring eSensors
`Logging eSensor Trace Information
`
`Platform
`
`HP-UX
`
`IBM AIX
`
`Environment
`Variable
`
`SHLIB_PATH
`
`LIBPATH
`
`Directory
`
`/opt/eSleuth/bin
`
`/usr/lpp/eSleuth/bin
`
`Note that all of the directory locations in this table are the default eSensor installation
`locations. If the eSensor was installed in a location other than the default, you must
`specify the directory location for the eSensor executable.
`
`On the OS/390 platform, the CICS subsystem does not support dynamic linking to
`shared libraries. Rather than requiring applications to be re-linked with the eSensor
`library, eSensors on this platform use the crossing exit mechanism provided by CICS.
`
`Note that on the AIX platform, you must run /usr/sbin/slibclean to clear the
`original shared library from memory before you can pick up a new library that has the
`same name as an existing library.
`
`Logging eSensor Trace Information
`From the eSleuth Analyzer, you can enable trace logging to debug eSensor
`configuration. Trace information is logged to the UNIX system log, the Windows NT
`event log, or the OS/390 operator console log.
`
`On UNIX platforms, you can specify the log facility by setting the
`ESLEUTH_SYSLOG environment variable to one of the following values: user,
`local0, local1, local2, local3, local4, local5, local6, or local7. If ESLEUTH_SYSLOG
`is not set or is set to a value other than those listed, eSleuth uses local0. The target log
`file must already exist. Contact your system administrator to set up the system log
`facility, if required.
`
`eSensor error messages also go to the UNIX system log, the Windows NT event log, or
`the OS/390 operator console log.
`
`18
`
`eSleuth User’s Guide
`
`HP_1011_0022
`
`

`

`Chapter 2 • Configuring eSensors
`eSensors and FASTPATH_BINDING
`
`eSensors and FASTPATH_BINDING
`If FASTPATH_BINDING is set for the monitored application, it binds the application
`to the same address space as the queue manager and tries to load a secondary DLL that
`is linked against the standard MQSeries library. Since your environment is configured
`to load the eSensor library instead of MQSeries, the secondary DLL tries to call
`internal symbols that are not available.
`
`To work around this potential problem, eSensors disable all FASTPATH_BINDING by
`setting the MQ_CONNECT_TYPE environment variable to STANDARD whenever
`the monitored application calls MQCONNX.
`
`eSleuth User’s Guide
`
`19
`
`HP_1011_0023
`
`

`

`Chapter 2 • Configuring eSensors
`eSensors and FASTPATH_BINDING
`
`20
`
`eSleuth User’s Guide
`
`HP_1011_0024
`
`

`

`Chapter 3
`Managing eSleuth Projects
`
`Creating, Opening, and Closing Projects
`eSleuth Analyzer sessions are organized into projects. Each project consists of project
`settings and a project database. The project settings specify information such as which
`communication links to monitor, which data collection and presentation filters to use,
`and database settings. The project database contains the event information collected as
`a result of the project settings.
`
`You may have any number of eSleuth projects. However, only one project may be open
`at a time. Each project is stored in its own directory location. A project directory
`contains the project file, which ends with the .epj extension, and a number of
`database files.
`
`Create a New Project
`To create a new eSleuth Analyzer project, perform the following steps:
`1. Choose the File > New Project menu item to open the New Project Wizard.
`
`eSleuth User’s Guide
`
`21
`
`HP_1011_0025
`
`

`

`Chapter 3 • Managing eSleuth Projects
`Creating, Opening, and Closing Projects
`
`2. Specify the project name and location, then click Next to continue:
`
`Option
`
`Name
`
`Location
`
`Description
`
`The project name. eSleuth creates a directory with this name
`in the specified location. eSleuth also creates a project file
`with this name and the .epj extension within the project
`directory. A project name can contain up to 255 characters,
`including spaces. It cannot contain any of the following char-
`acters: \ / : * ? “ < > |
`
`The directory location where eSleuth will create the new
`project directory. You may type the full pathname or browse
`to a new directory.
`
`3. Select the communication links to activate for the project, then click Next. Commu-
`nication links, created with the eSleuth Communication Link Editor, define the
`queue manager and queues for the Analyzer and eSensors to use to exchange con-
`figuration and event information.
`
`22
`
`eSleuth User’s Guide
`
`HP_1011_0026
`
`

`

`Chapter 3 • Managing eSleuth Projects
`Creating, Opening, and Closing Projects
`
`Communication link definitions are stored in communication link (.ecl) files. If
`the communication link list is empty or the desired communication link is not
`listed, click Load Communication Links to select a communication link file to open.
`
`To verify that you can send and receive messages over a selected communication
`link, click Test Communication Link.
`To enable trace logging to debug eSensor configuration, click Trace On. eSensor
`verbose trace information is logged to the UNIX system log, Windows NT event
`log, or OS/390 operator console log during application execution. Use this
`information to determine whether any data collection conditions such as collection
`time or collection entities are too restrictive.
`To view detailed information about communication links, click Show Details. The
`list of communication links expands to include the link name, local event queue
`manager, local event queue, remote event queue manager, remote event queue,
`configuration queue manager, configuration queue, and maximum event message
`size.
`
`For instructions on creating communication links with the eSleuth Communication
`Link Editor, see the eSleuth Administrator’s Guide.
`4. Specify user information about the project, if desired, then click Next. User infor-
`mation provides the ability to record details of the project such as who created,
`why, and how to contact them. This information is particularly useful if you are
`sending a project to someone else within your organization for analysis. All fields
`are optional.
`5. Verify that all project information is correct. If you wish to configure a data collec-
`tion filter before continuing, click Filter (see Configuring Filters for more informa-
`tion), or click Finish to complete the project creation. The eSleuth Analyzer creates
`the project directory, then creates the project file and associated database in the
`project directory.
`
`Open an Existing Project
`To open an existing project, perform the following steps:
`
`1. Choose File > Open. The Open dialog appears. If a project was open in the
`Analyzer, you will be prompted to close it first.
`2. Select the project file and click Open. The Analyzer opens the project with the
`same project settings in effect as when you last closed the project.
`
`eSleuth User’s Guide
`
`23
`
`HP_1011_0027
`
`

`

`Chapter 3 • Managing eSleuth Projects
`Recording eSleuth Events
`
`Close an Existing Project
`To close a project, choose File > Close. The Analyzer saves all project settings and
`closes the project.
`
`Recording eSleuth Events
`Once you have created a project, you are ready to record eSleuth events for analysis.
`
`Initialize Event Recording
`To initialize event recording, choose Project > Data > Collect Events.
`
`The Analyzer sends a configuration message to the configuration queues defined in the
`active communication links for the project. This configuration message defines the data
`collection filter conditions for the project, the name of the queue that event messages
`should be sent to, and the expiration time of the configuration message itself.
`
`Once you initialize event recording, eSensors for all applications that use the eSensor
`queue managers specified in active communication links begin sending event messages
`for all events that match the data collection filter conditions.
`
`Important! If your data collection filter specifies a start time for event recording, be sure to
`initialize event recording before the scheduled start time. For example, if your data
`collection filter specifies a data collection time period from 1:00 p.m. until 3:00 p.m.,
`but you do not initialize event recording until 2:30 p.m., your project will only record
`events from 2:30 until 3:00.
`
`Stop Event Recording
`Stop event recording in any of the following ways:
`Explicitly stop recording at any time by clearing Project > Data > Collect Events.
`•
`•
`Specify a stop time or elapsed time in a data collection filter. Event recording will
`stop at the scheduled time. See Configuring Filters for instructions on specifying a
`stop time or elapsed time.
`Specify a maximum number of events for the project database. Event recording