eSleuth 1.0
`
`Administrator’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_1012_0001
`
`

`

`Printed April 10, 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. ES10000410
`
`HP_1012_0002
`
`

`

`Contents
`
`Chapter 1 eSleuth Administration Overview . . . . . . . . . . . . . . . . . . .
`eSleuth Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`eSleuth Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`Chapter 2 Installing eSensors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Installing on Windows NT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Installing on Sun Solaris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Installing on HP-UX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Installing on IBM AIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Installing on IBM OS/390 CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`Chapter 3 Installing the eSleuth Analyzer . . . . . . . . . . . . . . . . . . . . .
`Installation Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Installation Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`Chapter 4 Installing the eSleuth Communication Link Editor . . . . .
`Installation Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Installation Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`
`Chapter 5 Creating Communication Links . . . . . . . . . . . . . . . . . . . .
`Planning Communication Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`Using the Communication Link Editor . . . . . . . . . . . . . . . . . . . . . . . . .
`
` 1
`1
`2
`
` 5
`6
`7
`7
`8
`9
`
` 15
`15
`16
`
` 17
`17
`18
`
` 19
`19
`26
`
`eSleuth Administrator’s Guide
`
`i
`
`HP_1012_0003
`
`

`

`ii
`
`eSleuth Administrator’s Guide
`
`HP_1012_0004
`
`

`

`Chapter 1
`eSleuth Administration Overview
`
`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.
`
`eSleuth Administration
`Most eSleuth users will run the eSleuth Analyzer to record event data from eSensors
`and view it graphically, employing data collection and presentation filters to customize
`the amount of information collected and displayed.
`
`However, the following administrative tasks are necessary before any eSleuth projects
`may be created and analyzed:
`
`•
`
`•
`
`•
`
`•
`
`eSensors must be installed on every system where applications to be monitored
`with eSleuth run. See Chapter 2, “Installing eSensors,” for instructions.
`
`The eSleuth Analyzer must be installed on a Windows NT computer. See
`Chapter 3, “Installing the eSleuth Analyzer,” for instructions.
`
`The eSleuth Communication Link Editor must be installed on a Windows NT
`computer. See Chapter 4, “Installing the eSleuth Communication Link Editor,” for
`instructions.
`
`Communication Links and associated MQSeries queues must be created for the
`exchange of information between eSensors and the Analyzer. See Chapter 5,
`“Planning Communication Links,” for instructions.
`
`eSleuth Administrator’s Guide
`
`1
`
`HP_1012_0005
`
`

`

`Chapter 1 • eSleuth Administration Overview
`eSleuth Components
`
`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, generate an eSleuth event that contains information about the call, and forward
`the eSleuth event to the Analyzer via MQSeries.
`
`eSensors do not require you to change or recompile your applications, even if they are
`compiled in optimized (non-debug) mode.
`
`eSensors use MQSeries queues to exchange information with the eSleuth Analyzer.
`Data Collection Filters
`eSensors use data collection filters to determine the amount and type of information
`collected by each eSensor. Data collection filters to 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 so
`that any monitored process calls the eSensor library at runtime instead of the standard
`MQSeries library.
`
`2
`
`eSleuth Administrator’s Guide
`
`HP_1012_0006
`
`

`

`Chapter 1 • eSleuth Administration Overview
`eSleuth Components
`
`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.
`
`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.
`
`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.
`
`See the eSleuth User’s Guide for complete instructions on using the eSleuth Analyzer.
`
`eSleuth Administrator’s Guide
`
`3
`
`HP_1012_0007
`
`

`

`Chapter 1 • eSleuth Administration Overview
`eSleuth Components
`
`4
`
`eSleuth Administrator’s Guide
`
`HP_1012_0008
`
`

`

`Chapter 2
`Installing eSensors
`
`eSensors are lightweight libraries monitor MQSeries applications by capturing event
`information about each MQSeries API call that the application makes and forwarding it
`to the eSleuth Analyzer. You must install an eSensor on each computer running
`applications that you want to analyze with eSleuth. A single eSensor library is used by
`all applications on that computer, per region.
`
`The following table shows the platforms supported by eSensors along with the required
`operating system and MQSeries versions:
`
`Platform
`
`Operating System
`
`MQSeries
`
`Microsoft Windows NT Windows NT 4.0 SP5
`
`Sun Solaris
`
`Solaris 2.5.1, 2.6, and 7
`
`Hewlett-Packard HP-UX HP-UX 10.20, 11.00
`
`IBM AIX
`
`AIX 4.2, 4.3
`
`IBM OS/390 with CICS
`
`OS/390 V2R5, CICS 1.2
`
`5.0/5.1
`
`5.0/5.1
`
`5.0/5.1
`
`5.0/5.1
`
`2.1
`
`Important! The MQSeries 5.1 for Windows NT CSD01 (DTF U200109) is recommended to
`prevent unexpected behavior starting or stopping event collection from applications
`connecting to an MQSeries 5.1 queue manager on Windows NT. The CSD can be
`found at ftp://ftp.software.ibm.com/software/mqseries/fixes/winnt51/U200109. More
`details about this CSD can be found at
`http://www4.ibm.com/software/ts/mqseries/support/apars/u200109.html.
`
`eSleuth Administrator’s Guide
`
`5
`
`HP_1012_0009
`
`

`

`Chapter 2 • Installing eSensors
`Installing on Windows NT
`
`Because eSensors are libraries instead of programs, you do not need to add entries to
`system startup files to start an eSensor process. The eSensor library is dynamically
`loaded into a program’s address space when the program makes an MQSeries API call.
`However, eSensors can be set from the Analyzer to log trace information in the UNIX
`system log, Windows NT event log, or OS/390 operator console log (depending on
`platform). Therefore, you must have system administrator privileges to install
`eSensors.
`
`Note that while eSensors are installed in fixed locations on UNIX platforms, there is no
`dependency on this location. You can copy the eSensor libraries to a different location.
`
`Installing on Windows NT
`To install the eSensor on Windows NT, perform the following steps:
`1.
`In the Windows NT Explorer, navigate to the eSensors\nt directory of the
`eSleuth CD-ROM.
`2. Double-click the eSensor_100_nt.exe icon. The eSensor Welcome screen
`appears.
`3. Click Finish to unpack the eSensor installation files and start the Setup program.
`4. Click Next> to view the eSleuth license agreement.
`5. Click Yes to accept the eSleuth license agreement and view the User Information
`page.
`6. Enter your name and company name, then click Next> to view the Destination
`Location page.
`7. The default installation location for the eSensor is C:\Program
`Files\Bristol\eSleuth eSensor. Click Browse to select a different
`installation directory. When the installation directory is set, click Next> to view the
`Program Folders page.
`8. The default program folder for eSleuth is Bristol eSleuth. You may select or enter a
`different folder name. Click Next> to continue with the installation.
`9. Select the Launch the Read Me file check box to view important information about
`eSleuth eSensors, then click Finish to complete the Setup program.
`
`To uninstall the eSensor, perform the following steps:
`1. From the Start menu, choose Settings > Control Panel.
`2. Double-click Add/Remove Programs.
`
`6
`
`eSleuth Administrator’s Guide
`
`HP_1012_0010
`
`

`

`Chapter 2 • Installing eSensors
`Installing on Sun Solaris
`
`3. Select Bristol eSleuth eSensor and click Add/Remove.
`4. Click Yes to confirm that you want to delete the eSensor.
`
`Installing on Sun Solaris
`To install the eSensor on Solaris, perform the following steps:
`1. Copy the eSensors/solaris/eSensor_100_solaris_tar.gz file
`from the eSleuth installation CD-ROM to a temporary directory location.
`2. Unzip and expand the installation file:
`
`gunzip eSensor_100_solaris_tar.gz
`tar xpvf eSensor_100_solaris_tar
`Use the gunzip utility provided in the eSensor directory if it is not already
`installed on your computer.
`Install as superuser:
`
`3.
`
`su
`pkgadd -d .
`The eSensor libraries are installed in /opt/eSleuth/bin.
`
`To uninstall the eSensor, remove the package as superuser:
`
`su
`pkgrm eSleuth
`
`Installing on HP-UX
`To install the eSensor on HP-UX, perform the following steps:
`1. Copy the eSensors/hpux/eSensor_100_hpux10_tar.gz or
`eSensor_100_hpux11_tar.gz file (depending on which version of HP-UX
`you are using) from the eSleuth installation CD-ROM to a temporary directory
`location.
`2. Unzip and expand the installation file:
`
`gunzip eSensor_100_hpux11_tar.gz
`tar xpvf eSensor_100_hpux11 _tar
`Use the gunzip utility provided in the eSensor directory if it is not already
`installed on your computer.
`
`eSleuth Administrator’s Guide
`
`7
`
`HP_1012_0011
`
`

`

`Chapter 2 • Installing eSensors
`Installing on IBM AIX
`
`3.
`
`Install as superuser:
`su
`swinstall
`The eSensor libraries are installed in /opt/eSleuth/bin.
`
`To uninstall the eSensor, remove the package as superuser:
`
`su
`swremove
`
`Installing on IBM AIX
`To install the eSensor on AIX, perform the following steps:
`1. Copy the eSensors/aix/eSensor_100_aix42.bff or
`eSensor_100_aix43.bff file from the eSleuth installation CD-ROM to a
`temporary directory location.
`Install with either of the following commands:
`smit
`OR
`installp -acgNQqwX -d eSensor_100_aix43.bff eSleuth.sensor
`The eSensor libraries are installed in /usr/lpp/eSleuth/bin.
`
`2.
`
`To uninstall the eSensor, remove the package as superuser:
`
`smit
`OR
`
`installp -u eSleuth.sensor
`
`8
`
`eSleuth Administrator’s Guide
`
`HP_1012_0012
`
`

`

`Chapter 2 • Installing eSensors
`Installing on IBM OS/390 CICS
`
`Installing on IBM OS/390 CICS
`
`Before You Install the eSleuth eSensor
`The eSleuth eSensor for OS/390 CICS is an API crossing exit program for MQSeries.
`MQSeries API crossing exit programs for CICS are required to have the fixed program
`name CSQCAPX. Thus, only a single MQSeries API crossing exit can be installed in a
`given CICS region at one time. If you already have a program of this name installed in
`the target CICS region, remove the existing CSQCAPX load module from your
`DFHRPL concatenation and delete or disable the existing CICS program definitions for
`CSQCAPX before installing the eSleuth eSensor.
`
`The eSleuth eSensor for OS/390 CICS requires OS/390 Language Environment
`runtime support. Before installing the eSensor, be certain that your target CICS region
`has LE support enabled.
`
`Installation Procedure
`To install the eSensor on OS/390 CICS, perform the following steps:
`
`1. FTP the eSensor installation files from the CD-ROM to your OS/390 machine. Be
`sure to set binary mode transfer and the dataset characteristics as follows:
`
`ftp> SITE FIXrecfm 80 LRECL=80 RECFM=FB BLKSIZE=3120
`ftp> bin
`ftp> put slm100.f1
`ftp> put slm100.f2
`ftp> put slm100.f3
`ftp> put slm100.mcs
`2. Use the TSO RECEIVE command to create the SMP/E input datasets from the
`transferred files. The following table shows the RECEIVE commands and the file-
`name to enter for each one:
`
`Command
`
`Filename
`
`RECEIVE INDSNAME(SLM100.F1)
`
`dsn(BRISTOL.ASLM100.F1)
`
`RECEIVE INDSNAME(SLM100.F2)
`
`dsn(BRISTOL.ASLM100.F2)
`
`RECEIVE INDSNAME(SLM100.F3)
`
`dsn(BRISTOL.ASLM100.F3)
`
`RECEIVE INDSNAME(SML100.MCS)
`
`dsn(BRISTOL.ASL100.SMPMCS)
`
`eSleuth Administrator’s Guide
`
`9
`
`HP_1012_0013
`
`

`

`Chapter 2 • Installing eSensors
`Installing on IBM OS/390 CICS
`
`3. The datasets created are an SMP/E install package in RELFILE format. Verify the
`creation of the following SMP/E input datasets:
`
`Dataset
`
`Description
`
`BRISTOL.ASLM100.SMPMCS
`
`SMP/E MCS file for eSleuth eSensor
`
`BRISTOL.ASLM100.F1
`(ASLM100)
`
`BRISTOL.ASLM100.F2
`(SLMMOD01)
`
`BRISTOL.ASLM100.F3
`(SLMALLOC)
`
`BRISTOL.ASLM100.F3
`(SLMRECV)
`
`BRISTOL.ASLM100.F3
`(SLMDDDEF)
`
`BRISTOL.ASLM100.F3
`(SLMAPPLY)
`
`BRISTOL.ASML100.F3
`(SLMCICSD)
`
`BRISTOL.ASLM100.F3
`(SLMACCPT)
`
`JCLIN for SMP/E
`
`eSleuth eSensor for OS/390 CICS
`
`Sample JCL for eSleuth SMP/E target and dis-
`tribution library allocation
`
`Sample JCL for SMP/E Receive step
`
`Sample JCL for creating SMP/E DDDEFs for
`eSleuth
`
`Sample JCL for SMP/E Apply step
`
`Sample JCL for updating CICS CSD file with
`eSleuth eSensor program definition
`
`Sample JCL for SMP/E Accept step
`
`If any of the above datasets are missing, recheck Steps 1 and 2. If in doubt, contact
`Bristol Technology support for assistance.
`
`Note that sample JCL is provided for each of the major installation steps. You can
`copy this JCL to another dataset, edit it appropriately for your local requirements,
`and use it to perform the installation.
`
`The SMP/E FMID for this installation is ASLM100.
`
`4. Allocate the target and distribution libraries for the product. Sample JCL for this
`purpose is provided in the SLMALLOC member. You must tailor this job for the
`requirements of your installation before executing it. Four libraries will be created
`by the job:
`
`10
`
`eSleuth Administrator’s Guide
`
`HP_1012_0014
`
`

`

`Chapter 2 • Installing eSensors
`Installing on IBM OS/390 CICS
`
`Library
`
`Description
`
`target library &THLQUAL.SSLMOAD
`
`eSleuth eSensor load module
`
`target library &THLQUAL.SSLMINST
`
`eSleuth eSensor sample JCL
`
`distribution library &DHLQUAL.ASLMMOD
`
`eSleuth eSensor distribution module
`
`distribution library &DHLQUAL.ASLMINST
`
`eSleuth eSensor sample JCL
`
`5. Create the SMP/E DDDEFs in the distribution and target libraries. Sample JCL for
`this purpose is provided in the SLMDDDEF member. You may install into any
`SMP/E target zone desired. You must tailor this job for the requirements of your
`installation before executing it. The following DDDEFs will be created by the job:
`
`Library
`
`Description
`
`target zone DDDEF SSLMLOAD
`
`target zone DDDEF SSLMINST
`
`target zone DDDEF ASLMMOD
`
`target zone DDDEF SCEELKED
`
`target zone DDDEF SCSQLOAD
`
`target zone DDDEF SDFHLOAD
`
`distribution zone DDDEF ASLMMOD
`
`distribution zone DDDEF ASLMINST
`
`Points to the SSLMLOAD target library allo-
`cated in Step 4.
`
`Points to the SSLMINST target library allo-
`cated in Step 4.
`
`Points to the ASLMMOD distribution library
`allocated in Step 4.
`
`Points to the LE SCEELKED library. This
`DDDEF might already exist in your chosen
`target zone.
`
`Points to the MQSeries SCSQLOAD library.
`This DDDEF might already exist in your
`chosen target zone.
`
`Points to the CICS SDFHLOAD library.
`This DDDEF might already exist in your
`chosen target zone.
`
`Points to the ASLMMOD distribution library
`allocated in Step 4.
`
`Points to the ASLMINST distribution library
`created in Step 4.
`
`eSleuth Administrator’s Guide
`
`11
`
`HP_1012_0015
`
`

`

`Chapter 2 • Installing eSensors
`Installing on IBM OS/390 CICS
`
`6. SMP/E RECEIVE the eSleuth eSensor installation package. Sample JCL for this
`purpose can be found in the SLMRECV member. You must tailor this job for the
`requirements of your installation before executing it. Because this installation is
`packaged on CD-ROM rather than tape, you must edit the //SMPPTFIN DD state-
`ment to eliminate the TAPE parameters and point directly to the BRIS-
`TOL.ASLM100.SMPMCS file created in Step 2. You should also add an
`RFPREFIX parameter to the RECEIVE statement within the SMPCNTL input to
`account for the high level qualifier under which you created the
`BRISOTL.ASLM100.* datasets. For example, if the dataset were installed in
`USERNAME.BRISTOL.ASLM100.* and your global CSI dataset was MY.GLO-
`BAL.CSI, you customized JCL for the SMP/E RECEIVE might look as follows:
`
`//RECEIVE EXEC PGM=GIMSMP,REGION=4096K
`//SMPCSI DD DSN=MY.GLOBAL.CSI,
`//
`DISP=SHR
`//SMPPTFIN DD DSN=USERNAME.BRISTOL.ASLM100.SMPMCS,DISP=OLD
`//SYSPRINT DD SYSOUT=*
`//SMPCNTL DD *
`SET BDY(GLOBAL).
`RECEIVE SELECT(ASLM100) RFPREFIX(USERNAME) SYSMODS LIST.
`/*
`
`7. SMP/E APPLY the eSleuth eSensor installation package. Sample JCL for this pur-
`pose can be found in the SLMAPPLY member. You must tailor this job for the
`requirements of your installation before executing it. This job step will create the
`eSleuth eSensor load module CSQCAPX in the SSLMLOAD target library. It will
`also copy the sample JCL to the SSLMINST target library.
`
`8. Update your CICS CSD file with the CSQCAPX program definitions for the
`eSleuth eSensor. Sample JCL for this purpose can be found in the SLMCICSD
`member. You must tailor this job for the requirements of your installation before
`executing it. This job step will define a program resource definition for CSQCAPX
`in your CICS region. Note that if your region already has a program resource
`defined for CSQCAPX and a CSQCAPX program is already installed then this
`previous program load module must be removed from your DFHRPL concatena-
`tion before the eSleuth eSensor CSQCAPX module can be installed and used. This
`requirement results from the fixed naming mechanism used by MQSeries for the
`API crossing exit facility for CICS/MQSeries (only one crossing exit can be
`installed and it must be named CSQCAPX).
`
`12
`
`eSleuth Administrator’s Guide
`
`HP_1012_0016
`
`

`

`Chapter 2 • Installing eSensors
`Installing on IBM OS/390 CICS
`
`9. Place the CSQCAPX load module in a library within your DFHRPL concatena-
`tion. You can either copy the module into an existing library already present in
`your DFHRPL concatenation or you can add the SSLMLOAD library to the
`DFHRPL concatenation.
`10. Enable the MQSeries API crossing exit within your CICS region using the CKQC
`transaction. You can do this from the Connection > Modify > Enable API Exit menu
`item in the CKQC panel, or by specifying arguments to CKQC when invoking it.
`For example, you could enter CKQC MODIFY Y E to enable the crossing exit (E
`for enable, D for disable). Note, however, that in this case you must also specify
`the proper argument for auto-connect (Y | N) so you should be certain you know
`which setting is in use at your site before using CKQC MODIFY in this way.
`11. Create appropriate eSleuth eSensor configuration and event queues on the queue
`manager used by the CICS region into which you installed the eSleuth eSensor.
`See Chapter 5 for more information.
`12. When you are satisfied with the results of your installation, run the SMP/E
`ACCEPT step. Sample JCL for this purpose can be found in the SLMACCPT
`member. You must tailor this job to the requirements of your installation before
`running it.
`
`eSleuth Administrator’s Guide
`
`13
`
`HP_1012_0017
`
`

`

`Chapter 2 • Installing eSensors
`Installing on IBM OS/390 CICS
`
`14
`
`eSleuth Administrator’s Guide
`
`HP_1012_0018
`
`

`

`Chapter 3
`Installing the eSleuth Analyzer
`
`The eSleuth Analyzer graphically displays event information collected from eSensors
`throughout your eBusiness system. The Analyzer facilitates analysis and problem
`resolution by enabling you to customize the amount, type, and format of information
`displayed.
`
`For instructions on using the Analyzer, see the eSleuth User’s Guide.
`
`Installation Requirements
`The following table shows the platform supported by the Analyzer along with the
`required operating system and MQSeries Client versions:
`
`Platform
`
`Operating System
`
`MQSeries
`
`Microsoft Windows NT Windows NT 4.0 SP5
`
`5.0/5.1
`
`MQSeries is required because the Analyzer uses MQSeries Client to send configuration
`information to eSensors and to retrieve event information recorded by eSensors. If
`MQSeries is not installed, you may use the Analyzer to view existing eSleuth projects,
`but you may not record events or send data collection filters to eSensors.
`
`The eSleuth Analyzer depends on specific versions of some system DLLs; if these
`DLLs are not present or if older versions are installed on your system, the Analyzer
`Setup program installs them automatically. Therefore, administrator privileges may be
`required to install the eSleuth Analyzer.
`
`eSleuth Administrator’s Guide
`
`15
`
`HP_1012_0019
`
`

`

`Chapter 3 • Installing the eSleuth Analyzer
`Installation Steps
`
`Installation Steps
`To install the eSleuth Analyzer, perform the following steps:
`1.
`In the Windows NT Explorer, navigate to the Analyzer directory of the eSleuth
`CD-ROM
`2. Double-click the analyzer_100_nt.exe icon. The eSleuth Analyzer Wel-
`come screen appears.
`3. Click Finish to unpack the Analyzer installation files and start the Setup program.
`4. Click Next> to view the eSleuth license agreement.
`5. Click Yes to accept the eSleuth license agreement and view the User Information
`page.
`6. Enter your name and company name, then click Next> to enter your license key.
`7. Enter the license key provided by Bristol Technology, then click Next> to view the
`Destination Location page. If you do not have a license key, send email to sup-
`port@bristol.com to request one.
`8. The default installation location for the eSensor is C:\Program
`Files\Bristol\eSleuth Analyzer. Click Browse to select a different
`installation directory. When the installation directory is set, click Next> to view the
`Program Folders page.
`9. The default program folder for eSleuth is Bristol eSleuth. You may select or enter
`a different folder name. Click Finish to complete the Setup program.
`
`To uninstall the Analyzer, perform the following steps:
`1. From the Start menu, choose Settings > Control Panel.
`2. Double-click Add/Remove Programs.
`3. Select Bristol eSleuth Analyzer and click Add/Remove.
`4. Click Yes to confirm that you want to delete the Analyzer.
`
`16
`
`eSleuth Administrator’s Guide
`
`HP_1012_0020
`
`

`

`Chapter 4
`Installing the eSleuth Communication Link Editor
`
`The eSleuth Communication Link Editor enables you to define eSleuth communication
`links. The eSleuth Analyzer and eSensors use communication links to communicate
`with each other. The Analyzer sends messages to over the communication link
`indicating when to start collecting events, where to send event messages, what filter
`conditions to apply, and when to stop collecting events. The eSensors send event
`messages that match data collection filter conditions to the Analyzer over the
`communication link.
`
`For instructions on using the eSleuth Communication Link Editor, see Chapter 5,
`“Planning Communication Links.” For instructions on using the Analyzer, see the
`eSleuth User’s Guide.
`
`Installation Requirements
`The following table shows the platform supported by the Communication Link Editor
`along with the required operating system and MQSeries Client versions:
`
`Platform
`
`Operating System
`
`MQSeries
`
`Microsoft Windows NT Windows NT 4.0 SP5
`
`5.0/5.1
`
`MQSeries Client is required because the communication links defined by the
`Communication Link Editor use MQSeries queues and queue managers. To test
`communication links or create the queues used by communication links, MQSeries
`Client must be installed.
`
`eSleuth Administrator’s Guide
`
`17
`
`HP_1012_0021
`
`

`

`Chapter 4 • Installing the eSleuth Communication Link Editor
`Installation Steps
`
`Installation Steps
`To install the Communication Link Editor, perform the following steps:
`1.
`In the Windows NT Explorer, navigate to the CommLinkEditor directory of the
`eSleuth CD-ROM
`2. Double-click the CommLinkEditor_100_nt.exe icon. The Communication
`Link Editor Welcome screen appears.
`3. Click Finish to unpack the Communication Link Editor installation files and start
`the Setup program.
`4. Click Next> to view the eSleuth license agreement.
`5. Click Yes to accept the eSleuth license agreement and view the User Information
`page.
`6. Enter your name and company name, then click Next> to view the Destination
`Location page.
`7. The default installation location for the eSensor is C:\Program
`Files\Bristol\eSleuth Communication Link Editor. Click
`Browse to select a different installation directory. When the installation directory
`is set, click Next> to view the Program Folders page.
`8. The default program folder for eSleuth is Bristol eSleuth. You may select or enter
`a different folder name. Click Finish to complete the Setup program.
`
`To uninstall the Communication Link Editor, perform the following steps:
`1. From the Start menu, choose Settings > Control Panel.
`2. Double-click Add/Remove Programs.
`3. Select Bristol eSleuth Communication Link Editor and click Add/Remove.
`4. Click Yes to confirm that you want to delete the Analyzer.
`
`18
`
`eSleuth Administrator’s Guide
`
`HP_1012_0022
`
`

`

`Chapter 5
`Creating Communication Links
`
`eSleuth uses MQSeries for communication between eSensors and the Analyzer. Before
`an eSensor can collect events and forward them to the Analyzer for analysis, you must
`create a communication link between the eSensor and the Analyzer. A communication
`link defines the communication queue managers and queues that the eSensor and
`Analyzer will use to exchange messages. You must create a communication link for
`each queue manager accessed by the applications you wish to monitor.
`
`The eSleuth Communication Link Editor enables you to create communication links
`for use with eSleuth.
`
`Planning Communication Links
`eSleuth communication links require two types of queues for the exchange of messages
`between an eSensor and the Analyzer:
`
`•
`
`•
`
`A configuration queue that eSensors monitor for configuration messages from the
`Analyzer
`
`An event queue that the Analyzer monitors for event messages from eSensors
`
`Configuration Queues
`When an Analyzer user begins recording events for an eSleuth project, 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.
`
`eSleuth Administrator’s Guide
`
`19
`
`HP_1012_0023
`
`

`

`Chapter 5 • Creating Communication Links
`Planning Communication Links
`
`Event Queues
`
`When an application makes an MQI call, it actually calls the eSensor library installed
`on the application host. The first time an application makes an MQI call, the eSensor
`checks to see whether a configuration queue exists on the queue manager identified by
`the MQI hConn parameter. If no configuration queue exists, the eSensor simply passes
`the call on to the standard MQSeries library. If a configuration queue does exist, the
`eSensor reads all configuration messages on the queue, deleting any that have expired.
`
`The eSensor evaluates the MQI call against the data collection filter conditions
`specified in the configuration message. If any filter conditions are met, the eSensor
`creates an event entry message about the MQI call and puts it on the event queue
`specified in the configuration message. (There may be more than one configuration
`message, so event messages may be put on more than one event queue.) The eSensor
`then passes the MQI call on to the standard MQSeries library. When the MQSeries
`library returns from the call, the eSensor creates an event exit message and puts it on
`the specified event queue, then passes the return on to the calling application.
`
`Application
`
`MQPUT
`
`eSleuth
`Analyzer
`
`Queue Manager
`
`Configuration Queue
`
`Event Queue
`
`1. Check Configuration Queue
`
`2. Send data to Analyzer?
`
`4. Send data to Analyzer?
`
`eSensor
`MQPUT
`
`MQSeries
`Library
`
`3. Call MQPUT
`
`MQPUT
`
`MQPUT
`
`Configuration Message
`
`Event Message
`
`eSensors for all applications that make MQI calls on the same queue manager use the
`same configuration queue. However, data collection filter conditions such as host name
`or program name may limit the number of event messages sent to the Analyzer.
`
`After the first MQI call made by a program instance, the eSensor continues to check the
`configuration queue periodically for new configuration messages.
`
`20
`
`eSleuth Administrator’s Guide
`
`HP_1012_0024
`
`

`

`Chapter 5 • Creating Communication Links
`Planning Communication Links
`
`While the Analyzer is recording events, it reads messages from the event queues into
`the project database. It also sends new configuration messages to replace expiring
`configuration messages or to change the data collection filter conditions. When the
`Analyzer stops recording events, it sends a new configuration message to the
`configuration queue indicating that no more events should be recorded. The Analyzer
`may stop recording events for any of the following reasons:
`
`•
`
`•
`
`•
`
`The user stops event recording.
`
`The time period specified in the data collection filter expires.
`
`The project database reaches the specified maximum number of events.
`
`Configuration and event queues may reside on the same queue manager or on different
`queue managers. Three distinct configurations are possible:
`
`•
`
`•
`
`