Introscope8 0 2 0ConfigAdminGuide

CA Wily Introscope®
Configuration and
Administration Guide
Version 8.0
Date: 10-2008
Copyright © 2008, CA. All rights reserved.
Wily Technology, the Wily Technology Logo, Introscope, and All Systems Green are registered
trademarks of CA.
Blame, Blame Game, ChangeDetector, Get Wily, Introscope BRT Adapter, Introscope
ChangeDetector, Introscope Environment Performance Agent, Introscope ErrorDetector, Introscope
LeakHunter, Introscope PowerPack, Introscope SNMP Adapter, Introscope SQL Agent, Introscope
Transaction Tracer, SmartStor, Web Services Manager, Whole Application, Wily Customer Experience
Manager, Wily Manager for CA SiteMinder, and Wily Portal Manager are trademarks of CA. Java is a
trademark of Sun Microsystems in the U.S. and other countries. All other names are the property of
their respective holders.
For help with Introscope or any other product from CA Wily Technology, contact Wily Technical
Support at 1-888-GET-WILY ext. 1 or support@wilytech.com.
If you are the registered support contact for your company, you can access the support Web site
directly at http://support.wilytech.com.
We value your feedback
Please take this short online survey to help us improve the information we provide you. Link to the
survey at: http://tinyurl.com/6j6ugb
If you have other comments or suggestions about Wily documentation, please send us an e-mail at
wily-techpubs@ca.com.
US Toll Free 888 GET WILY ext. 1

6000 Shoreline Court, Suite 200 US +1 630 505 6966
South San Francisco, CA 94080 Fax +1 650 534 9340
Europe +44 (0)870 351 6752
Asia-Pacific +81 3 6868 2300
Japan Toll Free 0120 974 580
Latin America +55 11 5503 6167
www.wilytech.com
CONTENTS
Table of Contents
Chapter 1 Starting and Stopping the Enterprise Manager . . . . . . . 7

Starting the Enterprise Manager on Windows . . . . . . . . . . 8
Starting the Enterprise Manager on UNIX. . . . . . . . . . . 10
Starting the Enterprise Manager on OS/400 . . . . . . . . . . 11
Starting and configuring the Enterprise Manager on z/OS . . . . . 12
Configuring the Enterprise Manager to use a different JVM . . . . 20
Configuring the Enterprise Manager config directory . . . . . . . 20
Stopping the Enterprise Manager . . . . . . . . . . . . . 21
Enterprise Manager shell and terminal window commands . . . . . 22
Chapter 2 Administering the Enterprise Manager . . . . . . . . . . 23

Monitoring Enterprise Manager health and load . . . . . . . . 24
Managing Enterprise Manager capacity . . . . . . . . . . . 31
Shutting down the Enterprise Manager from the Workstation . . . . 32
Mounting and unmounting agents . . . . . . . . . . . . . 32
Shutting off agents . . . . . . . . . . . . . . . . . . 34
Shared state in multiple Workstations . . . . . . . . . . . . 39
Chapter 3 Configuring Enterprise Manager Communications . . . . . . 41

The default Enterprise Manager communications channel . . . . . 42
Connecting to the Enterprise Manager across a firewall . . . . . . 45
Enabling SSL for Enterprise Managers on OS/400 . . . . . . . . 45
Configuring the Enterprise Manager Web Server for HTTPS . . . . 46
Chapter 4 Configuring Enterprise Manager Data Storage . . . . . . . 51

Configuring SmartStor data storage . . . . . . . . . . . . 52
Configuring Transaction Event database location and aging . . . . 54
Configuring location of baseline storage . . . . . . . . . . . 54
Contents iii
CA Wily Introscope
Chapter 5 Working with Enterprise Manager Clustering . . . . . . . . 55

Understanding Enterprise Manager clustering . . . . . . . . . 56
Configuring a cluster of Enterprise Managers . . . . . . . . . 63
Chapter 6 Creating and Editing Introscope Dashboards . . . . . . . . 67

Introscope Dashboard Editor overview. . . . . . . . . . . . 68
Creating Dashboards . . . . . . . . . . . . . . . . . . 71
Creating Data Viewers in a Dashboard. . . . . . . . . . . . 76
Setting data-viewing properties of a Data Viewer . . . . . . . . 82
Embedding an Investigator Tab View in a Dashboard . . . . . . 91
Adding shapes and lines to Dashboard. . . . . . . . . . . . 92
Coloring shapes, lines and connectors . . . . . . . . . . . . 95
Creating and editing text . . . . . . . . . . . . . . . . 97
Inserting an image on a Dashboard. . . . . . . . . . . . . 100
Manipulating Dashboard objects . . . . . . . . . . . . . . 101
Creating and managing custom hyperlinks . . . . . . . . . . 106
Chapter 7 Working with Management Modules . . . . . . . . . . 111

About Management Modules . . . . . . . . . . . . . . . 112
Creating and working with Management Modules . . . . . . . . 113
Configuring metric groupings . . . . . . . . . . . . . . . 119
Monitoring performance with Alerts . . . . . . . . . . . . . 125
Working with Alert Downtime Schedules . . . . . . . . . . . 145
Using Calculators . . . . . . . . . . . . . . . . . . . 154
Using JavaScript calculators . . . . . . . . . . . . . . . 155
Deploying Management Modules . . . . . . . . . . . . . . 160
Chapter 8 Using the Command-Line Workstation . . . . . . . . . 163

About the Command Line Workstation (CLW) . . . . . . . . . 164
Running the CLW . . . . . . . . . . . . . . . . . . . 164
CLW command reference . . . . . . . . . . . . . . . . 167
Sample scripts . . . . . . . . . . . . . . . . . . . . 202
Chapter 9 Configuring Introscope Security and Permissions . . . . . 207

About Introscope security and permissions . . . . . . . . . . 208
Configuring and managing realms . . . . . . . . . . . . . 208
Configuring and managing users and groups . . . . . . . . . 219
Defining User and Group Permissions . . . . . . . . . . . . 228
iv Contents
Configuration and Administration Guide
Chapter 10 Configuring WebView Options . . . . . . . . . . . . 235

Configuring WebView for Non-ISO-8859-1 characters . . . . . . 236
Configuring the WebView application context path . . . . . . . 236
Running WebView on z/OS . . . . . . . . . . . . . . . . 237
Chapter 11 Tailoring your Workstation Configuration . . . . . . . . 245

Running Workstation in verbose mode. . . . . . . . . . . . 246
Redirecting Workstation output to a file . . . . . . . . . . . 246
Configuring Workstation to supply login values. . . . . . . . . 246
Configuring the Workstation for Asian-language reports . . . . . 247
Chapter 12 System Configurations . . . . . . . . . . . . . . . 249

Configuring the Clock Skew Tolerance . . . . . . . . . . . . 250
Setting the Maximum Data Point Retrieval Property . . . . . . . 251
Increasing the Number of Query Results Returned . . . . . . . 251
Appendix A Introscope Properties Files . . . . . . . . . . . . . . 253

IntroscopeEnterpriseManager.properties . . . . . . . . . . . 254
Introscope Enterprise Manager.lax . . . . . . . . . . . . . 276
EMService.conf File . . . . . . . . . . . . . . . . . . 279
IntroscopeWorkstation.properties . . . . . . . . . . . . . 281
Introscope Workstation.lax. . . . . . . . . . . . . . . . 283
IntroscopeWebView.properties . . . . . . . . . . . . . . 286
Introscope WebView.lax. . . . . . . . . . . . . . . . . 290
Appendix B Using the JDBC API . . . . . . . . . . . . . . . . . 293

Configuring the JDBC API . . . . . . . . . . . . . . . . 294
Using the JDBC API . . . . . . . . . . . . . . . . . . 294
Index . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Contents v
CA Wily Introscope
vi Contents
CHAPTER
1
Starting and Stopping the

Enterprise Manager
This chapter provides instructions for starting and stopping the Enterprise
Manager (EM), and for automating startup in supported environments. It includes
these topics:
Starting the Enterprise Manager on Windows . . . . . . . . . . . 8

Starting the Enterprise Manager on UNIX . . . . . . . . . . . 10
Starting the Enterprise Manager on OS/400 . . . . . . . . . . 11
Starting and configuring the Enterprise Manager on z/OS . . . . . . 12
Configuring the Enterprise Manager to use a different JVM . . . . . . 20
Stopping the Enterprise Manager . . . . . . . . . . . . . . 21
Enterprise Manager shell and terminal window commands . . . . . . 22
» Note See Introscope Properties Files on page 253 for details of properties
discussed in this guide.
Starting and Stopping the Enterprise Manager 7

CA Wily Introscope
Starting the Enterprise Manager on Windows

When running the Enterprise Manager in a Windows environment, you can either
start the Enterprise Manager manually, or run it as a Windows Service.
Starting the Enterprise Manager Manually on Windows

You can start the Enterprise Manager manually in one of these ways:
Navigate to Start > Programs > Introscope > Administration > Introscope
Enterprise Manager.
Run the IntroscopeEnterpriseManager.exe located in the
<Introscope_Home> directory.
The Enterprise Manager starts in accordance with the property settings in

<Introscope_Home>/Introscope Enterprise Manager.lax, described in
the Introscope Properties Files on page 253.
Running the Enterprise Manager as a Windows Service

Installing the Enterprise Manager as a Windows Service increases its availability.
If you configure the Enterprise Manager as a Windows Service, when the machine
on which it runs starts, the Enterprise Manager starts automatically. It shuts
down when the machine is shut down.
» Note Introscope uses a public domain Java Service Wrapper from Tanuki
Software (http://wrapper.tanukisoftware.org) to enable the
Enterprise Manager to run as a Windows Service. See the Configuration
Property Overview (http://wrapper.tanukisoftware.org/doc/english/
properties.html) for information about the Tanuki wrapper.
These instructions assume you are familiar with configuring applications as

Windows Services, and are familiar with using the Windows Services console.
Configuring the Enterprise Manager as a Windows Service

This section provides instructions on how to register a single Enterprise Manager
on a Windows machine that is running with Introscope-default JVM system
parameters.
1 Stop the Enterprise Manager—see Stopping the Enterprise Manager on page 21.
2 In the IntroscopeEnterpriseManager.lax file, in your <Introscope_Home>
directory, set the lax.stdin.redirect property to blank, and save the file.
8 Starting and Stopping the Enterprise Manager

3 In the IntroscopeEnterpriseManager.properties file, in your

<Introscope_Home>/config directory, set the
introscope.enterprisemanager.disableInteractiveMode property to true and
save the file.
4 Assign a unique name to the Enterprise Manager service. By default, a service
name is assigned in the EMService.conf, in your <Introscope_Home>
directory. If no other services are configured on the machine, you can use the
default service name. Otherwise, modify EMService.conf to specify a unique
name and a display name for the service using these properties:
wrapper.ntservice.name=<unique EM name>
wrapper.ntservice.displayname=<EM display name>
Save changes to the file.

5 Run the <Introscope_Home>/RegisterEMService.bat script to register the
Enterprise Manager instance as a service.
The Windows Services console shows that the Enterprise Manager is configured
as a Windows Service.
Repeat these steps for each Enterprise Manager you want to run as a service.
Changing Windows Service properties

If you need to change configuration properties in the EMService.conf file, first
unregister the service, as described in the following section. Make the changes,
then re-register the service for the changes to take effect.
Unregistering an Enterprise Manager Windows Service

Unregister the Enterprise Manager Service:
before you make changes to the EMService.conf properties file.
to return the Enterprise Manager instance to Console control.
before you uninstall the Enterprise Manager instance.
To unregister an Enterprise Manager Service:
1 Stop the Enterprise Manager Service and shut down the Windows Services GUI.
2 Run <Introscope_Home>/DeregisterEMService.bat.
» Note If either the Enterprise Manager Service or the Windows Services GUI is
active, the service is not deleted, but is marked for deletion. This is
standard Windows Service behavior, and occurs because the Windows
Registry lock prevents the service from being removed. When you restart
the machine, the service is deleted.
Starting the Enterprise Manager on Windows 9

CA Wily Introscope
Stopping and Restarting the Enterprise Manager Windows

Service
Use the standard controls in the Windows Services GUI to start, stop, and restart
the Enterprise Manager running as a Windows Service.
Starting the Enterprise Manager on UNIX

When running the Enterprise Manager in a UNIX environment, you can either
start the Enterprise Manager manually, or run it in nohup mode.
Starting the Enterprise Manager Manually on UNIX

To start the Enterprise Manager on UNIX, run Introscope_Enterprise_Manager by
typing this at the command prompt:
./Introscope_Enterprise_Manager
The Enterprise Manager starts in accordance with the property settings in

<Introscope_Home>/Introscope Enterprise Manager.lax, described in
Introscope Properties Files on page 253.
Enterprise Manager output appears in the UNIX shell. The shell does not accept
user input, unless you start up the Enterprise Manager in nohup mode, as
described in the following section.
Running the Enterprise Manager on Unix

You can manage the Enterprise Manager by running control scripts that allow you
to start, stop, and check the server application status. You can use the EMCtrl.sh
startup script to start and stop the Enterprise Manager instead of directly using
the ./Introscope_Enterprise_Manager command.
To run the Introscope Enterprise Manager on Unix:
Use the following commands at the bin folder:
./EMCtrl.sh start—This starts the Enterprise Manager.
./EMCtrl.sh stop—This stops the Enterprise Manager.
./EMCtrl.sh status—This gives the status of the Enterprise Manager.
./EMCtrl.sh help—This shows the supported options for the script.

Running Enterprise Manager in nohup Mode on UNIX

The UNIX nohup command runs a command, but suppresses the action of the HUP
(hangup) signal, enabling the command to continue running after the user who
issued it logs out. In this case, output that normally goes to the terminal goes to
a file named nohup.out.
To run the Introscope Enterprise Manager in nohup mode on UNIX:
1 In the IntroscopeEnterpriseManager.lax file, in your <Introscope_Home>

directory, set the lax.stdin.redirect property to blank, and save the file.
2 In the IntroscopeEnterpriseManager.properties file, in the
<Introscope_Home>/config directory, set the property
introscope.enterprisemanager.disableInteractiveMode to true and save the file.
3 Start the Enterprise Manager with this command:
nohup Introscope_Enterprise_Manager&
» Note Do not run the Enterprise Manager in nohup mode without performing
the configuration described above. Otherwise, the Enterprise Manager
might not start, or might start and consume excessive system resources.
Starting the Enterprise Manager on OS/400

This section provides instructions for starting the Enterprise Manager on OS/400
using the OS/400 start script, and invoking from the command line.
Running the OS/400 start script

When the Enterprise Manager is installed on OS/400, the installer automatically
generates two start scripts. One for Enterprise Manager and one for WebView. To
invoke the start script from a QShell command prompt from the
<Introscope_Home> directory, use one of the following commands:
Enterprise Manager start script:
nohup ./runem.sh &

WebView start script:
nohup ./runwv.sh &
If you run the script from a directory other than <Introscope_Home>, identify
the home directory as shown below:
nohup ./runem.sh /<Introscope_Home> &
Starting the Enterprise Manager on OS/400 11

CA Wily Introscope
where <Introscope_Home> is the root of your Enterprise Manager installation

directory.
The output will default to the nohup.out in the directory from which the script is
executed.
» Note Use the runem.sh script to start the Enterprise Manager on Red Hat
Linux 5.
Using control scripts for OS/400 and Z/OS

You can use control scripts in OS/400 and Z/OS to start the Enterprise Manager.
Use these control scripts for OS/400 and Z/OS:
1 Go to <Introscope_Home>\bin directory.
2 Use these commands:
./EMCtrl.sh start—Starts the Enterprise Manager.
./EMCtrl.sh status—Verifies whether the Enterprise Manager is running or

not.
./EMCtrl.sh —Stops the Enterprise Manager.
Running the Enterprise Manager as a Java program

To start Enterprise Manager from the command line, enter this command from
the <Introscope_Home> directory:
lib/EnterpriseManager.jar:lib/WebServices.jar:lib/IntroscopeClient.jar:lib/
SNMPAdapter.jar:lib/Workstation.jar:lib/IntroscopeServices.jar
Start command syntax can vary, depending on your version of Java and other
environmental factors.
» Note If you are running the Enterprise Manager as a Java Program on SAP, use
this command:
lib/EnterpriseManager.jar:lib/WebServices.jar:lib/
IntroscopeClient.jar:lib/SNMPAdapter.jar:lib/
Workstation.jar:lib/IntroscopeServices.jar:lib/
WebViewAPI.jar:lib/WebViewServer.jar
Starting and configuring the Enterprise Manager on

z/OS
To start the Enterprise Manager on z/OS, use the runem.sh file.

For instructions on running the EM as a Java program, please see Running the
Enterprise Manager as a Java program on page 12.
To facilitate use of Introscope in the z/OS environment, run the product in a

manner familiar to z/OS operations and development staff—as a z/OS batch job,
or as a started task. You can also run Introscope Enterprise Manager as a shell
process. This section describes running the Introscope Enterprise Manager as a
batch job or started task:
Prerequisites for running Enterprise Manager as a z/OS batch job on page 13

briefly describes the z/OS environment and the BPXBATCH utility. This section
describes software prerequisites, security, authorization and address space
size requirements.
Configuring Enterprise Manager to run as a z/OS batch job on page 16
describes the tasks necessary to customize the sample JCL and other files in
preparation for running the Introscope Enterprise Manager as a batch job on
the z/OS platform.
Running the Enterprise Manager on z/OS on page 18 describes the activities
required to run the Introscope Enterprise Manager as a batch job or started
task on the z/OS platform.
Prerequisites for running Enterprise Manager as a z/OS batch job
z/OS base infrastructure for Java

The MVS utility program, BPXBATCH, enables users to invoke UNIX System
Services to run shell commands, shell scripts and executable files in MVS batch.
You can therefore use the BPXBATCH utility to start the Introscope
Enterprise Manager.
Software prerequisites
The specific software prerequisites to run Java (and therefore the Introscope
Enterprise Manager) on z/OS can be found in the Java for z/OS Program Directory
GI10-0614. The minimum software requirements are:
The Introscope Enterprise Manager requires JVM 1.5 (either 32 or 64 bits).
» Note WebView needs JVM 1.5 to run.
UNIX System Services must be enabled
Language Environment 1.5 or higher
Java for z/OS
Starting and configuring the Enterprise Manager on z/OS 13

CA Wily Introscope
Security and authorization

Authorization is determined by the RACF profile associated with a user’s USERID.
To successfully start the Introscope Enterprise Manager, a user must have
authority to access the following resources:
UNIX System Services as specified by the OMVS parameter in the RACF profile
EXEC PGM= BPXBATCH
EXEC WILYPROC
It is important to understand how the user is identified in these contexts:

Batch—When a user submits a batch job through the TSO/E or ISPF interface,
the user’s TSO UserID and password are propagated to the batch job. Provided
the submitted Batch JOB CARD does not explicitly contain a User and
Password, the batch job acquires the same access authority as the TSO user.
If User and Password are coded on the Batch JOB CARD, they override the
UserID and Password of the TSO/E user.
Started Task—If the Introscope Enterprise Manager is initiated as a started
task, it runs under the authorization of the STC user ID. A Site-specific
algorithm might be used to relate the name of the started PROC to a particular
UserID. You must make sure that the algorithm produces a UserID with the
correct authorization to run the Introscope Enterprise Manager.
Virtual memory
If the OMVS address space is not large enough, an out-of-memory condition
occurs when an attempt is made to run the Introscope Enterprise Manager. The
OMVS ASSIZEMAX(address-space-size) parameter in the RACF profile for the
owner of the Introscope Enterprise Manager job or started task must be large
enough to execute the Introscope Enterprise Manager. The maximum value for
this parameter is 2G.
In addition, in order to run the Enterprise Manager with Java 1.5 and avoid
encountering Java 1.5 GC Heap Initialization errors, you may need to raise the
MEMLIMIT in your SMFPRMxy PARMLIB member. Update your SMFPRMxy to add
the following line if it does not already exist:
MEMLIMIT(256M) /* SET MINIMUM MEMLIMIT FOR JAVA 1.5 */
» Note The 256M value is minimum requirement. Recommended value can be

1024M or more.
DB2
1 To access JDBC and SQLJ from UNIX Systems Services, you must set the
following environment variables:

STEPLIB must include the SDSNEXIT, SDSNLOAD and SDSNLOD2 data sets
LIBPATH and LD_LIBRARY_PATH must include the DLL libraries for the JDBC
and SQLJ drivers
2 In order to run the Introscope Enterprise Manager as a z/OS job, the runem.sh
shell script must contain the following statements where DSNXXX denotes the
High Level Qualifier of your DB2 libraries:
export STEPLIB=DSNXXX.SDSNEXIT:DSNXXX.SDSNLOAD:DSNXXX.SDSNLOD2
export LIBPATH=/usr/lpp/db2/db2710/lib:$LIBPATH
export LD_LIBRARY_PATH=/usr/lpp/db2/db2710/
lib:$LD_LIBRARY_PATH
» Note While DB2SQLJPROPERTIES—the directory containing the

db2sqljjdbc.properties file—is used to specify the name of a SQLJ
properties file, it is not always necessary to set this environment
variable.
3 The CLASSPATH must include the JDBC and SQLJ driver classes. Include this file
in the classpath in the runem.sh shell script:
/usr/lpp/dsn710/db2/db2710/classes/db2sqljclasses.zip
» Note The character string “710” in dsn710 and db2710 refers to the version
and release of DB2 being used. If another version of DB2 is being used,
these directories must be changed.
4 Specify the DB2 subsystem identifier:

SYS_DB2_SUB_SYSTEM_NAME=xxx, where xxx is the subsystem identifier.
JDBC
JDBC for z/OS is based on the DB2 Call Level Interface (CLI). You must ensure
that the DB2 CLI has been set up as follows:
1 The DB2 CLI application plan (the default name is DSNACLI) must be bound
before you can use the DB2 CLI. A sample bind job can be found in
DSNXXX.SDSNSAMP(DSNTIJCL) where DSNXXX denotes the high level qualifier
of your DB2 installation.
2 The DB2 CLI application plan must be public. Execute the following command
from SPUFI or from a batch job:
GRANT EXECUTE ON PLAN DSNACLI TO PUBLIC
3 Set DSNAOINI to point to the CLI initialization file. The CLI initialization file
provides information about DB2 subsystem names and additional configuration
parameters. You can place the file either in an HFS file or in an MVS data set using
one of the following statements:

CA Wily Introscope
export DSNAOINI=/usr/lpp/db2/db2510/dsnaoini
export DSNAOINI=DSNxxx.CLIINI
export DSNAOINI=DSNxxx.CLIINI(CONF1)
4 Make sure that the DB2 subsystem referenced in the CLI initialization file
references the DB2 subsystem that you want to connect to. DB2 subsystem
names usually take the form DB2n where n is a unique qualifier.
Configuring Enterprise Manager to run as a z/OS batch job

Before the Introscope Enterprise Manager can run as a z/OS batch job, the
following files (extracted from the z/OS installer file) must be copied into the
z/OS environment and customized to ensure compatibility with site-specific
requirements.
IntroscopeEnterpriseManager.properties – the Introscope Enterprise Manager

properties file, which specifies information pertinent to the operation of the
Introscope Enterprise Manager
runem.sh – the shell script used to launch the Introscope Enterprise Manager
process
WILYPROC – the z/OS PROC used to execute z/OS BPXBATCH program that
launches the shell script
readme.txt - a description of the runem.sh and WILYPROC files and how to use
and customize them
Copying and customizing Introscope Enterprise Manager files

IntroscopeEnterpriseManager.properties and runem.sh are UNIX files that must
be copied into the Hierarchical File System (HFS) on the z/OS platform. These
files are used by UNIX System Services and the Introscope Enterprise Manager
respectively. Use a UNIX-based editor such as vi to make required changes to
these files. Do not use the ISPF editor because it does not properly handle
insertion of characters that increase line length.
WILYPROC is a z/OS file that is used by the JES2 component of z/OS and by DB2
for z/OS. Make changes to this file using the ISPF editor.
To copy the Enterprise Manager files:
Copy the IntroscopeEnterpriseManager.properties and runem.sh files into the

Introscope installation directory, as shown in the following examples, where
<UID> is the UID assigned to Wily Technology:
/u/<UID>/introscope7.2/runem.sh
/u/<UID>/introscope7.2/config/IntroscopeEnterpriseManager.properties

To customize Enterprise Manager properties file:
1 Open the u/xxxx/introscope7.2/config/

IntroscopeEnterpriseManager.properties file.
2 Find the Interactive Mode heading and make sure the value for the following
property is set to true:
introscope.enterprisemanager.disableInteractiveMode=true
To customize the UNIX shell script runem.sh:
1 Verify the version and release of DB2. The DB2 files in the runem.sh shell script
reference DB2 V7.1.
» Note If you are connecting to a DB2 subsystem other than version 7.1, you
must change all instances of 710 to the appropriate character string for
the version being used.
2 Make the following changes to the runem.sh script:

In the CLASSPATH, /usr/lpp/dsn710/db2/db2710/classes/
db2sqljclasses.zip\
export STEPLIB=DSN710.SDSNEXIT:DSN710.SDSNLOAD,DSNXXX.SDSNLOD2
#export LIBPATH=/usr/lpp/dsn710/db2/db2710/lib:$LIBPATH
#export LD_LIBRARY_PATH=/usr/lpp/dsn710/db2/db2710/
lib:$LD_LIBRARY_PATH
» Note If LIBPATH and LD_LIBRARY_PATH have been commented out, remove
the #.
To copying Enterprise Manager files to a z/OS partitioned dataset (PDS)
1 Using ISPF, create a partition dataset named userid.JCL.CNTL, (where userid

is the userid assigned to WILY) with fixed-block (FBA) of 80 byte records.
2 Copy WILYPROC into the PDS userid.JCL.CNTL.
3 Do not try to copy the shell script runem.sh, or the properties file
IntroscopeEnterpriseManager.properties, into this PDS. These files have
lines that are longer than 80 bytes. An attempt to copy them either fails, or lines
are truncated.
To customize the z/OS PROC that invokes BPXBATCH
1 Edit WILYPROC using the ISPF editor. Make the following changes:
On the ISPF command line, type CAPS OFF and press Enter.
On the ISPF command line, type NUM OFF and press Enter.
Set the IHOME parameter equal to the fully qualified path to the directory that
contains runem.sh.

CA Wily Introscope
2 This statement is coded to end the batch job and the UNIX shell script within 20
seconds:
// PARM='SH nohup &IHOME/runem.sh &IHOME & sleep 20'
If z/OS is too busy to initiate the Introscope Enterprise Manager within 20
seconds, the Enterprise Manager does not start. If you encounter this problem,
try increasing the sleep time.
3 Modify the STDERR and STDOUT file names contained in the following statements
to satisfy installation naming conventions:
//STDOUT DD PATH='/<path>/stdout',
//STDERR DD PATH='/<path>/stderr',
To copy WILYPROC into an active PROCLIB
Using ISPF option 3, copy the PROC to xxxx.PROCLIB where xxxx represents an
site-dependent high-level qualifier. If WILYPROC is not an acceptable name in
your installation, rename the PROC accordingly.
Running the Enterprise Manager on z/OS
Executing the z/OS PROC
Running as a started task from the z/OS console or SDSF
You can run the Enterprise Manager as an MVS started task (STC). A started task
is a familiar, operator-friendly environment that allows the Enterprise Manager to
be started, monitored, and cancelled from the MVS console. In this case, the
Enterprise Manager runs under the authorization of the STC user ID, allowing
assignment of specific authorities to the started task.
To run the Introscope Enterprise Manager as a started task, type this command
on the MVS console or on the command line of SDSF:
/start WILYPROC
You must type the member name of the PROC stored in an active PROCLIB. If you
were required to change the name of WILYPROC, you must use the new name in
the /start command.
Running as a batch job
You can run the Enterprise Manager as a batch job, using JCL (job-control
language) to describe the job's requirements.
To run the Enterprise Manager as a batch job, submit the following JCL:
//jobname JOB installation jobcard parameters,NOTIFY=&SYSUID

ISCOPE EXEC WILYPROC
/*

You must execute the member name of the PROC stored in an active PROCLIB. If
you were required to change the name WILYPROC, you must use the new name
in the EXEC statement.
The z/OS batch job and the OMVS shell end shortly after the Enterprise Manager
processes start. If you submitted the batch JCL from your ISPF session and your
JOB card contains NOTIFY=&SYSUID, your ISPF session receives notification
when your batch job ends.
Verifying the Enterprise Manager is running

The most accurate way to determine that the Enterprise Manager has started
correctly is to view the STDOUT file. To view STDOUT, telnet into z/OS and view
the STDOUT file defined in the WILYPROC. The last line of the file indicates that
the Enterprise Manager has started.
You can also determine that the Enterprise Manager has started from SDSF using
one of the following procedures:
If you started the Enterprise Manager as a started task, on the DA screen you
should see at least two active started tasks whose owner is the owner
associated with the Enterprise Manager PROC.
If you started the Enterprise Manager by submitting a batch job from your TSO
session, look for two active tasks with your TSO USERID as the owner.
You might see the job that invoked the WILYPROC, as well as the OMVS shell
script. These two entries disappear from the list after the Enterprise Manager
starts.
The owner of your TSO session is also your TSO/E USERID. Do not mistake your
TSO/E session for one of the Enterprise Manager tasks.
Starting the Enterprise Manager automatically

To start the Enterprise Manager automatically when JES2 starts:
1 Place the following statement in JES2PARM:

$VS,'start WILYPROC
2 Type the member name of the PROC stored in an active PROCLIB. If you were
required to change the name of WILYPROC, use the new name in the /start
command.
You can also run the Enterprise Manager as a batch job using the job scheduling
package you use to manage your batch workload.

CA Wily Introscope
Configuring the Enterprise Manager to use a

different JVM
By default, an Introscope component uses the JVM it is bundled with. This section
has instructions on how to configure the Enterprise Manager to use a different
JVM.
If you start the Enterprise Manager with Introscope Enterprise

Manager.exe, edit the lax.nl.current.vm property in Introscope
Enterprise Manager.lax to point to the desired JVM executable.
You can use an absolute or relative path to the executable.
On Windows, escape backslashes, and include the JVM executable file
extension: java.exe instead of java.
If you run the Enterprise Manager as a Windows service, edit the
wrapper.java.command property in EMService.conf to point to the desired
JVM executable.
You can use absolute paths; backslashes must be escaped.
You can also use relative paths; Wily Technology Division recommends that
you use UNIX forward slashes and start with dot-slash (./).
The executable is java not java.exe.
If you start the Enterprise Manager with the runem.sh script on z/OS or AS/
400, edit the JAVA_HOME variable in runem.sh to point to the desired JVM root
directory.
Use an absolute to the executable, not a relative path.
Configuring the Enterprise Manager config directory

If you have multiple Enterprise Managers and want to run them using a single
instance of Introscope, you can create a separate configuration directory for each
Enterprise Manager. For each Enterprise Manager, make a copy of the config,
logs, data, and traces directories. In each copy of the config directory, set the
appropriate properties in the IntroscopeEnterpriseManager.properties file
to point to the copies of your config, logs, data, and traces directories.
By creating separate configuration directories, you can keep all the directories
within one instance of Introscope while maintaining separate config, logs, data,
and traces directories for each Enterprise Manager.
To specify a different configuration directory for your Enterprise Manager:
1 Open the IntroscopeEnterpriseManager.properties file and modify the

following property:

introscope.enterprisemanager.directory.config=config
The default directory is config, which is the configuration directory created when
Introscope was first installed. Change the location of this directory using either
an absolute path (e.g. C:\\Introscope\em1\\config) or a path relative to the
Introscope installation directory (e.g. config2). For example:
introscope.enterprisemanager.directory.config=
C:\\Introscope\\em1\\config
» Note In a Windows environment, backslashes must be escaped (doubled) for
the path to function.
2 Save the changes made to the IntroscopeEnterpriseManager.properties

file.
3 Open the Introscope Enterprise Manager.lax file and modify the following
property:
lax.nl.java.option.additional
This property modifies the Java command-line and can contain multiple
properties. Use the location of the config file you selected in step one. For
example:
lax.nl.java.option.additional=-Xms512m -Xmx512m -Djava.awt.headless=false -
Dcom.wily.introscope.em.properties=C:\Introscope\em1\config
» Note This property can point either to a directory containing a
Enterprise Manager properties file, or to an
IntroscopeEnterpriseManager.properties file directly. For
example:
-Dcom.wily.introscope.em.properties=C:\Introscope\em1\config
or
-Dcom.wily.introscope.em.properties=
C:\Introscope\em1\config\IntroscopeEnterpriseManager.properties
4 Save the changes to the Introscope Enterprise Manager.lax file.
5 Restart the Enterprise Manager.
Stopping the Enterprise Manager

When you stop the Enterprise Manager:
Agents stop reporting data.
SmartStor does not save data.
you are logged out of the Workstation.
all users connected to the Enterprise Manager are disconnected.
Stopping the Enterprise Manager 21

CA Wily Introscope
Stopping the Enterprise Manager from the terminal window

From the Enterprise Manager terminal window, enter:
iscopeshutdown
» Note Interactive mode must be enabled to use this command. Set

introscope.enterprisemanager.disableInteractiveMode to
false in the Enterprise Manager properties file. For more information,
see Introscope Properties Files on page 253.
Stopping the Enterprise Manager from the Workstation

If you have shutdown privileges for the Enterprise Manager, you can stop the
Enterprise Manager from the Workstation in a Management Module Editor
window, by choosing Manager > Shut Down Enterprise Manager.
Automatic shutdown of Enterprise Manager

If the Enterprise Manager detects errors writing to disk, indicating a shortage of
disk space, it automatically shuts down. If failover is configured, agents can
failover to another Enterprise Manager. For more information, see the Java Agent
Guide or .NET Agent Guide.
Enterprise Manager shell and terminal window

commands
When the Enterprise Manager is running, if lax.stdin.redirect (defined in
Introscope Properties Files on page 253) is set to console, you can enter the
following commands in the Enterprise Manager terminal window or shell:
Command Result
iscopedebugpolling [true | false] Periodically reports debugging information to the
[delay in seconds] log
iscopehelp Display help screen
iscopeshutdown Shuts down the Enterprise Manager
» Note Interactive mode must be enabled to use these commands. Set

false in the Enterprise Manager properties file. For more information,
see Introscope Properties Files on page 253.

CHAPTER
2
Administering the Enterprise Manager
This chapter describes how to use the Introscope Workstation to manage the
information collected and reported by the Introscope Enterprise Manager. It
includes these topics:
Monitoring Enterprise Manager health and load . . . . . . . . . 24

Shutting down the Enterprise Manager from the Workstation . . . . . 32
Mounting and unmounting agents. . . . . . . . . . . . . . 32
Shutting off agents . . . . . . . . . . . . . . . . . . 34
Shared state in multiple Workstations . . . . . . . . . . . . 39
Administering the Enterprise Manager 23

CA Wily Introscope
Monitoring Enterprise Manager health and load

Understanding Enterprise Manager metrics
The Enterprise Manager generates metrics that are useful in managing and
diagnosing itself, assessing its health, and determining how well it is performing
under its workload. Metrics are reported every 15 seconds.
Enterprise Manager metrics appear in the Investigator tree under:
Custom Metric Host (Virtual)

Custom Metric Process (Virtual)
Custom Metric Agent (Virtual)(SuperDomain)
Enterprise Manager
In a clustered environment, the metrics appear under the Collector cluster node.
You can also create Dashboards that present custom views of Enterprise Manager
metrics, and set up alerts based on the values of Enterprise Manager metrics.
» Note For all installations, you must apply the appropriate Daylight Savings
Time patch to your operating system to ensure the correct operation of
your Enterprise Manager. For more information, see the Introscope
Installation and Upgrade Guide.
24 Administering the Enterprise Manager

Enterprise Manager
Host—The name of the machine on which the Enterprise Manager is running.
Name—The name of the Enterprise Manager as defined in the property

introscope.enterprisemanager.name.
Overall Capacity (%)—Estimate of the percentage of the Enterprise Manager’s

capacity that is consumed. The value can range from 0% to over 100%. The value
can exceed 100% because the metric calculation assumes an upper bound of
desirable capacity usage that is less than 100%—the premise being that most
customers prefer to run an Enterprise Manager at 50-75% capacity during normal
times and allow headroom for handling increased load during peak periods.
Capacity is determined in part by the values of the Metrics described in Enterprise
Manager | Health on page 29.
Port—The port number as defined in the property

introscope.enterprisemanager.port.channel1
Enterprise Manager | CPU

EM CPU Used (%)—Shows what percent of the total available CPU was used by
running Enterprise Managers during the time period specified.
» Note This number does not reflect other processes running on the server or
overall server CPU in use, but rather how much CPU the particular
Enterprise Manager used.
This metric is acquired from the JVM using an API introduced in the JDK 1.5.
Therefore, it is supported only on some platforms.
Enterprise Manager | Configuration

Agent Clusters Metric Load—Number of Metrics reported by all Virtual Agents.
Number of Agent Clusters—Number of Virtual Agents.
Number of Metric Groupings—Number of Metric Groupings for the Enterprise

Manager, including user-defined and temporary system Metric Groupings. This
value is an indicator of how much business logic is running on the Enterprise
Manager—a significant factor in the volume of Metrics it can support.
Enterprise Manager | Configuration | Agent Clusters |

VirtualAgentName
Metric Load—Number of Metrics reported by a Virtual Agent.
Monitoring Enterprise Manager health and load 25

CA Wily Introscope
Enterprise Manager | Connections

Metrics Queued (%)—Percentage of incoming Metrics (for the current time
slice) waiting to be processed.
Number of Agents—Number of Agents currently connected and reporting live

data.
Number of Applications—The total number of applications reported by all the

connected Agents.
Number of Historical Metrics—All the metrics that are present in the SmartStor
database.
Number of Metrics—Number of Metrics the Enterprise Manager is aware of.

When agents disconnect, this number drops.
Number of Metrics Handled—Number of incoming Metrics processed per 15

second interval. This number varies, but should be around the same value as
Number of Metrics. A value less than Number of Metrics indicates the Enterprise
Manager is overloaded and is not processing incoming data fast enough.
Number of Workstations—Number of connected Workstations.
Enterprise Manager | Data Store | SmartStor

Metrics Appended To Query Per Interval—Tracks the SmartStor data
appending task that runs every day, and shows how many Metrics are appended
per interval.
Metrics Converted From Spool to Query Per Interval—Tracks the SmartStor

spool to query conversion task that runs every hour.
SmartStor Disk Usage (mb)—Megabytes of disk used by SmartStor.
Enterprise Manager | Data Store | SmartStor | MetaData

Agents with Data—The number of agents tracked by the Enterprise Manager for
which there is metric data.
Agents without Data—The number of agents tracked by the Enterprise Manager

for which there is no metric data.
» Note This is an approximate value.
Metrics with Data—The number of fully qualified metrics (agent name + partial
metric name) tracked by the Enterprise Manager for which there is metric data.

Partial Metrics with Data—The number of partial metrics (that is, metrics
without the agent name qualifier) tracked by the Enterprise Manager for which
there is metric data.
Partial Metrics without Data—The number of partial metrics tracked by the

Enterprise Manager for which there is no metric data. If this value is greater than
0, the Enterprise Manager is tracking partial metrics unnecessarily.
Write Duration (ms)—The time in milliseconds spent writing to the SmartStor

metadata file.
Enterprise Manager | Data Store | SmartStor |Tasks

Converting Spool To Data—Tracks whether the spool to query conversion task is
running. When this task is running, this Metric has the value 1; when not running,
the value is 0.
Data Append—Tracks whether the data appending task is running. When this
task is running, this Metric has the value 1; when not running, the value is 0.
Reperiodizing—Tracks whether the reperiodization task is running. When this

task is running, this Metric has the value 1; when not running, the value is 0.
Enterprise Manager | Data Store | Transactions

Number of Dropped Per Interval—This is the number of transaction traces
dropped per 15 second interval because transaction traces could not be
processed fast enough. If transaction traces are received faster than they can be
processed and inserted into the data store, then the excess are dropped.
Number of Inserts Per Interval—Number of transaction trace inserts per 15

second interval.
Number of Queries Per Interval—The number of transaction trace queries per

time slice that are included in the “greater than last 20 minute” category.
Number of Traces in Database—Number of transaction traces in the transaction

trace database.
Number of Traces in Insert Queue—The Transaction Trace storage system

includes an insert queue that is 1000 elements in size. If the Enterprise Manager
becomes overloaded with incoming transaction traces, they are put into this
queue. The Enterprise Manager might become overloaded if, for example, too
many metrics are reporting, or perhaps if an aggressive Transaction Trace
session was started and the rate of traces is too high. When the insert queue
reaches 2000, the transaction traces are dropped to prevent the Enterprise
Manager from running out of memory.

CA Wily Introscope
TT Database Disk Usage (mb)—Number of megabytes of disk storage the

transaction trace database is using.
Total Data Insertion Duration Per Interval (ms)—How much time spent per
time slice inserting the transaction trace data into internal data store.
Total Index Insertion Duration Per Interval (ms)—How much time spent per
time slice indexing the transaction trace data.
Total Query Duration Per Interval (ms)—How much time spent per time slice
fetching data from internal data store.
Enterprise Manager | Data Store | Volume Space Free

» Note The Volume Free Space metrics are not available if you are running the
Enterprise Manager on the z/OS platform.
Baseline Volume Free (mb)—How much baseline volume space is free in

megabytes.
Log Volume Free (mb)—How much log volume space is free in megabytes.
SmartStor Archive Volume Free (mb)—How much SmartStor Archive volume

space is free in megabytes.
SmartStor Data Volume Free (mb)—How much SmartStor data volume space
is free in megabytes.
Traces Volume Free (mb)—How much Traces volume space is free in

megabytes.
Volume Free (mb)—The number of megabytes of disk space available on the

disk partition holding the baselines file. (This is defined by the property
introscope.enterprisemanager.dbfile, and defaults to the local drive if
none is found.) It does this by running a OS specific file system utility: dir /-c
on Windows, df –kP on AIX/HP-UX, and df –k on other Linux and other Unix
implementations. It will not work if these utilities are either not available, or in
the case of df, do not support GNU format when passed –k (or –kP).
Enterprise Manager | Database

Metric Data Points Sent per Interval—A metric data point is one timeslice of
data for one metric. This metric shows the number of metric data points written
to the relational database per interval.
Queued Metric Data Points—Number of metric data points not yet written to the
relational database.

Enterprise Manager | GC Heap

GC Duration (ms)—The time in milliseconds (during a time slice) spent handling
high-priority system tasks—most likely garbage collection—that prevented
threads from running. As this number grows, the overall capacity of the system
is diminished. When memory runs low and the JVM is spending a lot of time
garbage collecting, this number will be high—perhaps 5000 to 10000 ms.
In Use (mb)—Megabytes of heap in use.
In Use Post GC (mb)—Tracks how much heap is used after a major garbage
collection.
Total (mb)—Size of the heap in megabytes.
Enterprise Manager | Health

CPU Capacity (%)—Shows what percent of the total available CPU was used by
running Enterprise Managers during the time period specified.
» Note This number does not reflect other processes running on the server or
overall server CPU in use, but rather how much CPU the particular
Enterprise Manager used.
This metric is acquired from the JVM using an API introduced in the JDK 1.5.
Therefore, it is supported only on some platforms.
GC Capacity (%)—An average of the last 8 values. This is used to normalize

abnormal numbers.
Harvest Capacity (%)—The current capacity of the Enterprise Manager to

harvest data every 15 seconds. This value computes 100% in use based on how
long harvest takes vs. 15000ms. For example, if harvest takes 15000ms, then
this metric will be 100.
Heap Capacity (%)—The maximum possible total heap vs. current in use
(tracked by GC Heap: In Use Post GC (mb). For example, if the JVM is launched
with -Xmx1024m, then the total possible heap is 1024m. A 25% buffer remains
when this metric is at 100% and when the actual heap would be at 100%. For
example, if the total heap is 1000MB and the current heap usage is 750MB, then
this metric will be 100%. This is because Java needs heap space for "normal
operation".

CA Wily Introscope
Incoming Data Capacity (%)—The capacity of the Enterprise Manager to handle

incoming data, based on an internal Metric that indicates the number of incoming
Metrics yet to be processed. This internal Metric is divided by twice the total
number of Metrics. For example, if 150,000 Metrics are in the to-be-processed
queue and the Enterprise Manager has a total of 300,000 Metrics, the incoming
data capacity will be 25%.
SmartStor Capacity (%)—The capacity of the SmartStor subsystem. This value

computes 100% in use based on how long smartstor writes take vs 15000ms. For
example, if smartstor duration is 15000ms, then this metric will be 100.
Enterprise Manager | Internal

The Internal node contains metrics that relate to Enterprise Manager internals.
These metrics are for use by Wily Technology Division personnel only, and are
subject to change without notice.
Enterprise Manager | Problems| Management Modules

Warning Count—The total number of missing constructs in Management
Modules. For example, if a dashboard named, Dashboard XYZ, is missing and is
referenced by 11 other dashboards, it is considered one warning (not 11).
Enterprise Manager | MOM

Number of Collector Metrics—The number of metrics received from the
Collectors per interval.
Collector Metrics Received Per Interval—The number of metric data points

the MOM is receiving every (15 second) interval period. It is essentially the total
amount of traffic from the Collectors to the MOM, and shows the overall load that
queries are putting on the entire cluster.
Enterprise Manager | MOM | Collectors | CollectorHost@Port

Connected—The status of a Collector Enterprise Manager in an Enterprise
Manager cluster.
Values are based on Introscope alert values, and can be:

1 - connected
2 - connected to a slow Collector. A Collector is considered slow if the Ping Time

is greater than ten seconds.
3 - not connected

Ping Time (ms)—Measures the time in milliseconds to send a no-op message to

the Collector and return. It's a measure of the responsiveness of the MOM-
Collector connection taking into account the network round-trip time and the time
to process the message in the MOM and Collector.
Enterprise Manager | Tasks

Harvest Duration (ms)—The time in milliseconds (during a time slice) spent
harvesting data.
SmartStor Duration (ms)—The time in milliseconds (during a time slice) spent

writing Metric data to disk.
Managing Enterprise Manager capacity

An inappropriately configured agent can create thousands of metrics in quick
succession and overload the Enterprise Manager. To prevent this, the Enterprise
Manager uses a metric throttle that stops an agent when its metric output
becomes excessive.
Configuring the Enterprise Manager metric throttle

The default Metric throttle is 50,000 Metrics. To change the Metric threshold, you
add a property to the IntroscopeEnterpriseManager.properties file. For
more information, see Enterprise Manager Metric Clamping on page 264.
To configure the Enterprise Manager Metric throttle:
1 Open the IntroscopeEnterpriseManager.properties file.

2 Add the property introscope.enterprisemanager.agent.metrics.limit to
the file, and enter a value for the Metric throttle limit.
3 Save your changes.
The new value is applied when the Enterprise Manager checks the property file
during a hot deploy. A hot deploy occurs about once every 60 seconds.
If an agent generates more than the specified number of Metrics, the Enterprise
Manager will drop Metrics.
If this occurs, modify the agent’s configuration to reduce the volume of Metrics
reported. Metric explosion typically is a result of inadequately filtered JMX data
or SQL Metrics. For more information, see the Java Agent Guide or .NET Agent
Guide, as appropriate to your environment.
Managing Enterprise Manager capacity 31

CA Wily Introscope
Automatic shutdown of the Enterprise Manager

If the Enterprise Manager detects errors writing to disk, indicating a shortage of
disk space, it automatically shuts down so that agents can failover to another
Enterprise Manager. To enable failover, see the Java Agent Guide or the .NET
Agent Guide, as appropriate to your environment.
Shutting down the Enterprise Manager from the

Workstation
You can shut down the Enterprise Manager from the Workstation. Shutting down
the Enterprise Manager automatically logs you out of the Workstation.
» Important To shut down the Enterprise Manager, you must have shutdown
or full permission for the Enterprise Manager.
To shut down the Enterprise Manager:
1 Within a Management Module Editor window, select Manager > Shut Down
Enterprise Manager.
The Shut Down Confirmation message appears.
» Note If the Shut Down Enterprise Manager command is disabled, you do

not have shutdown or full permission. Contact your administrator.
2 Click Yes to confirm Enterprise Manager shutdown.

The Enterprise Manager shuts down, logs you out of the Workstation, and opens
the Workstation login window.
Mounting and unmounting agents

Agents that disconnect and then reconnect to an Enterprise Manager are
recognized as the same agent, and simply become active again in the
Investigator tree. You might, however, encounter situations where an agent
disconnects and does not reconnect, such as agents used in QA environments.
For example, you might have a load test running with an agent, but the agent
disconnects after tweaking the managed application for performance.

An agent that does not reconnect to and Enterprise Manager after a user-defined
time limit is automatically unmounted and removed from the Investigator tree
(see Auto-unmounting of disconnected agents on page 33); or it can be manually
unmounted at any time after disconnects.
To mount and unmount agents, you must have either historical_agent_control

or full permission for the Domain.
Unmounting disconnected agents

When an agent is disconnected, its icon in the Investigator tree is disabled.
Disconnected agents are automatically unmounted from the Workstation after a

user-defined time. Disconnected agents can also be unmounted manually.
» Note You can only unmount disconnected agents.
Disconnected and unmounted agents that have recorded at least one data point
can be remounted.
Auto-unmounting of disconnected agents

Disconnected agents are automatically unmounted from the Workstation after 60
minutes. This is the default setting, but this value can be changed in the
autoUnmountDelayInMinutes property in the
IntroscopeEnterpriseManager.properties file. See Introscope Properties
Files on page 253.
Unmounting an agent manually

To unmount a disconnected agent manually:
In the Investigator tree, right-click the agent and choose Unmount <agent
name> from the menu.
» Note If the Unmount command is disabled, you do not have
historical_agent_control or full permission. Contact your
administrator.
Mounting agents
You might want to remount a disconnected agent to view previously collected
Metrics from a database. Disconnected and unmounted agents that connected
while database recording was enabled can be remounted.
Mounting and unmounting agents 33

CA Wily Introscope
When an application process is disconnected from Introscope and is not

recognized as the same returning agent, (due to a change in host location, etc.),
and has been unmounted, you can remount and view it in the tree. Metrics it was
collecting appear in the tree.
If a user remounts an agent, any Metrics that agent ever reported to the database
appear as Resources in the Investigator tree.
To mount an agent:
1 Choose Manager > Mount Agent.

The agent Chooser opens.
» Note If the Mount Agent command is disabled, you do not have

historical_agent_control or full permission. Contact your
administrator.
2 Click the agent to mount, and click Choose.

» Note If you mount an agent, you must unmount it manually. It does not auto-
unmount.
Shutting off agents

Use the Agent Shutoff feature to shut off reporting at the agent, Resource, or
Metric level.
You can individually turn on or shut off each agent, Resource, or Metric. You can
also turn on or shut off all components under an agent all at once.
It is important to remember that when you shut off a component, you are only
shutting off that component’s reporting—the component is still present.
You can turn on or off a component’s reporting in two ways:

turn on or off the component itself
turn on or off a component that is upstream (one that either directly contains
that component, or is several levels above)

To change the shutoff state of agents, Resources, or Metrics, you must have
either read and live_agent_control permissions, or full permission for the
Domain.
Shutting off and turning on components

You can shut off and turn on agent, Resource, and Metric components. To shut
off or turn on components, right-click the component and choose the shutoff
command:
You can shut off and turn on agents, resources, and metrics:
To Do this
Shut off metric By default, individual metric reporting is on (Shutoff is not
reporting checked).
To shut off an individual metric’s reporting, right-click the metric
and choose Shutoff <Metric> from the menu.
When you shut off an individual Metric:
the metric’s toggle is shut off
the metric’s icon in the Investigator tree turns gray
the metric stops reporting (shows as a change in the Reporting
Status field in the settings)
Turn on metric To turn on a metric’s reporting, right-click the Metric and choose
reporting Shutoff <Metric> from the menu (this unchecks the Shutoff
option).
If data is available and metrics are not shut off because of an
upstream toggle, the metric begins reporting, and the metric’s
icon regains color. The Reporting Status field shows that the
metric is currently reporting.
Shutting off agents 35

CA Wily Introscope
To Do this
Shut off resource By default, individual resource reporting is on.
reporting To shut off resource reporting, right-click the resource and choose
Shutoff <Resource> from the menu. This checks the Shutoff
option.
When you shut off a Resource’s reporting:
the resource’s toggle is shut off
the resource’s icon turns gray
the resource stops reporting
any resources below (downstream) of the Resource turn gray
and stop reporting
any metrics below (downstream) of the Resource turn gray and
stop reporting
Turn on resource To turn on an individual Resource’s reporting, right-click the

reporting Resource and select Shutoff <Resource> from the menu. This
unchecks the Shutoff option.
If data is available and Metrics are not shut off because of an
upstream toggle, the Metrics under the Resource begin reporting,
and their icons regain color. The Reporting Status field shows that
the Resource contains Metrics that are currently reporting.
Shut off agent By default, individual agent reporting is on (Shutoff option is not
reporting selected).
To shut off agent reporting, right-click the agent and select Shutoff
<Agent> from the menu. This checks the Shutoff option.
When you shut off an agent’s reporting:
the agent’s toggle is shut off
the agent’s icon turns gray
the agent stops reporting
any Resources below (downstream) of the agent turn gray and
stop reporting
any Metrics below (downstream) of the agent turn gray and stop
reporting
Turn on agent To turn on an individual agent’s reporting, right-click the agent

reporting and select Shutoff <Agent> from the right-click menu. This
unchecks the Shutoff option.
If data is available, the Metrics under the agent begin reporting,
and their icons regain color. The Reporting Status field shows that
the agent contains Metrics that are currently reporting.

To Do this
Shut off all agent You can quickly turn on or shut off all components under an agent
components that is reporting.
To shut off reporting for everything under a specific agent:
1 Open an Investigator window.
2 Expand the Investigator tree to show the agent whose settings
you want to change.
3 Right-click on the agent and select Shut Off All Agent
Components. A warning dialog notifies that you cannot undo this
action.
4 Click Continue to shut off agent components.
The Agent and all components contained by it turn gray and stop
reporting.
Note: It is possible to have Agent reporting shut off and
individual Metrics underneath turned on. However,
upstream toggles override downstream toggles.
When you select Shut Off All Agent Components:
the Agent’s toggle is shut off
the Agent’s icon turns gray
the Agent stops reporting
all components under the Agent have their toggles shut off
the icons of all components under the Agent turn gray
all components under the Agent stop reporting
Note: This function is for shutting off reporting for an individual
Agent and all components under that Agent. It is not for
shutting off reporting for all connected Agents. Agent
reporting must be specifically turned on or shut off for
each Agent.
Turn on all Agent To turn on reporting for All Agent Components, right-click the
components agent and select Turn On All Agent Components.
After a short delay (usually the time slice during which new data
is being gathered), the Agent and all components contained by it
regain color and begin reporting if there is data available.
Discovering why a component is not reporting data

Icons for Metrics and Resources in the Investigator tree are grayed out when they
have no data available to report. With the Agent Shutoff feature, there might also
be no data available either because the item’s toggle is off, or an upstream toggle
is off.
Shutting off agents 37

CA Wily Introscope
Icon appearance
This table details reasons why a component might not be reporting data:
Metric Resource Agent

its toggle is shut off its toggle is shut off its toggle is shut off
an upstream Resource an upstream Resource Agent has been
or Agent toggle is shut or Agent toggle is shut disconnected (but has not
off off yet been unmounted)
there is no data there is no data there is no data available
available available because all because all Resources and
while an Agent was Resources and Metrics it Metrics it contains might be
disconnected, its contains might be shut shut off
application code off there is no data available
changed, and the there is no data for Metrics underneath
Metric is no longer available for Metrics
recognized by the underneath
Agent
Reporting status messages

You can investigate why data is not available to a component by looking at the
component’s Shutoff status and its Reporting Status field.
If a component is currently reporting, one of these messages appears:

<Metric name> is currently reporting
<Resource name> contains Metrics that are currently reporting
<Agent name> contains Metrics that are currently reporting
If a component is not reporting, one of these messages appears:

<component> is shut off due to its own toggle
<component> is shut off due to an upstream toggle
<Metric name> is not known to the current Agent
<Metric name> has no data available
<Resource name> contains no Metrics that have data available
<Resource name> contains no Metrics known to the current agent
<Agent name> contains no Metrics known to the current agent
» Note The above messages might occur in combination.

Shared state in multiple Workstations

Several Workstations can communicate with one Enterprise Manager, and when
changes are made on one Workstation, they are immediately reflected on other
Workstations.
Because of the Workstation’s shared state, several users could be editing the
same piece of information in the Management Module Editor or in the Console at
the same time.
You’ll encounter competing changes in the Management Module Editor if, for
example, you and another user are editing the same alert in the Management
Module Editor, and the other user clicks the Apply button first to save changes.
As soon as that user’s changes are applied, you see this message in your
Workstation:
Click Continue to close this dialog

box and return to your own edits.
If you click Apply, your changes
override those made by the other
user.
Click Update to close this dialog
box and update your settings with
those made by the other user.
You’ll encounter competing changes in the Console if, for example, you and
another user are editing the same Dashboard, and the other user selects File
> Save first. As soon as that user’s changes are applied, you see this message
in your Workstation:
Click Save to override changes

made by the other user.
Click Save As to save the current
Dashboard as a new Dashboard.
Shared state in multiple Workstations 39

CA Wily Introscope

CHAPTER
3
Configuring Enterprise Manager

Communications
This section includes information about how the Enterprise Manager

communicates with other components in an Introscope environment, default
communications behaviors, and options for configuring Enterprise Manager
communications.
The default Enterprise Manager communications channel . . . . . . 42

Connecting to the Enterprise Manager across a firewall . . . . . . . 45
Enabling SSL for Enterprise Managers on OS/400 . . . . . . . . . 45
Configuring the Enterprise Manager Web Server for HTTPS . . . . . . 46
Configuring Enterprise Manager Communications 41

CA Wily Introscope
The default Enterprise Manager communications

channel
By default the Enterprise Manager communicates with Agents, Workstations,
WebView, and in a cluster of Enterprise Managers on port 5001. See Working with
Enterprise Manager Clustering on page 55, for more information.
All socket communication to the EM is obfuscated, and passwords are encrypted
The properties in the Enterprise Manager properties file that define

communication channels and their use are:
introscope.enterprisemanager.serversocketfactory.<ChannelName>
introscope.enterprisemanager.port.<ChannelName>
introscope.enterprisemanager.serversockets.reuseaddr
introscope.enterprisemanager.enabled.channels
Each Agent that communicates with the Enterprise Manager has analogous
properties that must specify matching values, as described in Defining Agent
Connection and Name Properties in the Java Agent Guide or the .NET Agent
Guide, as appropriate for your environment.
Similarly, the WebView properties file specifies the Enterprise Manager port in the
introscope.webview.enterprisemanager.tcp.port property.
Rebinding a communication channel to a port in use

There are socket states where nothing is actually using the socket, but memory
is still in use, thus rendering the socket unusable. Examples of these states are
FIN_WAIT and TIME_WAIT.
The property introscope.enterprisemanager.serversockets.reuseaddr on

page 257 allows an Enterprise Manager communication channel to rebind to a
local port that is in use. Use this feature if an Enterprise Manager socket is stuck
in an unusable state, but you still want to start the Enterprise Manager.
» Note Do not enable this property by default and use it only when a socket is
in an unusable state. You should disable it after the Enterprise Manager
starts, as there may be a valid reason that the port is in use (for
example, a collector on the same machine is already bound to the port).
42 Configuring Enterprise Manager Communications

Configuring SSL
Configuring the Enterprise Manager for SSL is done in
IntroscopeEnterpriseManager.properties by enabling a secure
communications channel. This can be in addition to the default non-secure
channel.
The following is an example of enabling both a secure and non-secure

communications channel. It sets up the default non-secure listener on port 5001,
and a secure listener on port 5443:
# The enabled communication channels.

introscope.enterprisemanager.enabled.channels=channel1, channel2
# The default communication channel.

introscope.enterprisemanager.serversocketfactory.channel1=com.wily.isen
gard.postofficehub.link.net.server.DefaultServerSocketFactory
introscope.enterprisemanager.port.channel1=5001
# The secure communication channel.

introscope.enterprisemanager.serversocketfactory.channel2=com.wily.isen
gard.postofficehub.link.net.server.SSLServerSocketFactory
# Location of a keystore containing certificates for authenticating the
EM to clients.
# Either an absolute path or a path relative to the config directory.
# On Windows, backslashes must be escaped. For example:
#
introscope.enterprisemanager.keystore.channel1=C:\\Introscope\\config
\\internal\\server\\keystore
introscope.enterprisemanager.keystore.channel2=internal/server/keystore
# The password for the keystore.
introscope.enterprisemanager.keypassword.channel2=password
# Location of a truststore containing trusted client certificates.
# Either an absolute path or a path relative to the config directory.
# On Windows, backslashes must be escaped. For example:
#
introscope.enterprisemanager.truststore.channel1=C:\\Introscope\\conf
ig\\internal\\server\\keystore
# A truststore is only needed if client authentication is required.
# If no truststore is specified, the EM trusts all client certificates.
The default Enterprise Manager communications channel 43

CA Wily Introscope
SSL property rules

The Enterprise Manager must be configured with an SSL server socket in
IntroscopeEnterpriseManager.properties by enabling a secure
communications channel in addition to the default channel.
When configuring SSL properties, the following rules:
The keystore property is the location of a keystore. It should contain a

certificate used by the EM to authenticate itself to the client. The EM's default
keystore contains a self-signed certificate that is inherently untrustworthy.
This doesn't matter because by default the Workstation and Agent don't
validate server certificates.
The keystore property is either an absolute path or a path relative to the
config directory.
If the needclientauth property is set to true, the EM requires the client to
authenticate.
The EM must be configured with a trustore.
Agents and Workstations must be configured with a keystore containing a
certificate trusted by the EM.
If needclientauth = true, and a truststore is not configured, the EM does
not start.
This requires setting the trustore property.
The truststore property is the location of a truststore. It should contain the
certificates of trusted clients. It is only needed if clients are required to
authenticate.
If no truststore is specified, all client certificates are trusted.
The ciphersuites property is used to set the enabled cipher suites.
This can be used to enable anonymous authentication or avoid data

encryption. For example, for anonymous authentication, you might set the
cipher suites to SSL_DH_anon_WITH_RC4_128_MD5. For example:
introscope.enterprisemanager.ciphersuites.channel2=SSL_DH_anon_WITH_R
C4_128_MD5
A particular JSSE implementation may have several cipher suites available
that permit anonymous authentication (they all contain "anon"). However,
the cipher suite will be common to both client and server, and enabled on
both.
You might also specify a cipher suite that does not encrypt data. For
example:
introscope.enterprisemanager.ciphersuites.channel2=SSL_RSA_WITH_NULL_
SHA

Connecting to the Enterprise Manager across a

firewall
HTTP tunneling is enabled by default. Tunneling technology enables one network
to send its data via another network’s connections.
To use the tunneling transport on the Workstation, connect to the port for the
Enterprise Manager’s embedded web server. By default the port is 8081. You can
configure it with the introscope.enterprisemanager.webserver.port
property in the Enterprise Manager properties file. For more information, see
introscope.enterprisemanager.webserver.port.
In addition to using tunneling for the Enterprise Manager, you can configure
Agents to send information using tunneling technology. This feature enables
Agents to connect to an Enterprise Manager remotely. See the Java Agent Guide
for more information about Agent HTTP tunneling.
Enabling SSL for Enterprise Managers on OS/400

By default the AS/400 JVM uses a native JSSE provider. You must configure use
of the pure Java JSSE provider to allow an Enterprise Manager hosted on an AS/
400 to communicate with other Introscope components such as the Workstation,
or in a cluster, other Enterprise Managers.
To enable SSL for Enterprise Managers on OS/400:
1 Open your Java security file, usually in your JVM's lib/security directory.
2 In the list of security providers, look for com.ibm.jsse.IBMJSSEProvider. If it
exists, make sure it is higher up the list and thus takes priority over other SSL
providers, including com.ibm.as400.ibmonly.net.ssl.Provider. If it not
present, add it to the list.
3 Set the following SSL properties, replacing any previous definitions:
ssl.KeyManagerFactory.algorithm=IbmX509
ssl.TrustManagerFactory.algorithm=IbmX509
ssl.SocketFactory.provider=com.ibm.jsse.JSSESocketFactory
ssl.ServerSocketFactory.provider=com.ibm.jsse.
JSSEServerSocketFactory
Connecting to the Enterprise Manager across a firewall 45

CA Wily Introscope
Configuring the Enterprise Manager Web Server for

HTTPS
You can configure the Enterprise Manger web server for HTTPS by using the Jetty
configuration file. The Jetty file is provided for advanced configuration and
can be found in the config directory of the <Introscope_Home>
installation.
This file is activated by uncommenting the

introscope.enterprisemanager.webserver.jetty.configurationFile
property in IntroscopeEnterpriseManager.properties.
For additional information about configuration, refer to the following:
Default Jetty configuration file on page 47 and Modifying the Jetty-config.xml

file on page 48
http://docs.codehaus.org/display/JETTY/How+to+configure+SSL to access the
Jetty website for addtional information.
Understanding how HTTPS works

The Enterprise Manager web server supports HTTP tunneling over SSL.
This is done by introducing an optional Jetty 6.0.2 XML configuration file for the
embedded Jetty web server in the EM. A default configuration file is provided that
sets up a secure listener on port 8444, which allows the WorkStation and Agent
to access the EM using HTTPS tunneling through the EM web Server.
The Jetty configuration file is specified by the

property in IntroscopeEnterpriseManager.properties. The property
specifies a path to a Jetty 6.0.2 XML configuration file. It can be absolute or a
path relative to the config directory. The configuration file is loaded at startup
and does not support hot configuration. The default value is em-jetty-
config.xml. For example, it would appear as follows:
=em-jetty-config.xml
When you configure the Jetty configuration properties in the EM Web Server
Settings section of IntroscopeEnterpriseManager.properties the
following rules apply:
If the Jetty config file is successfully loaded, the default non-secure listener
specified by introscope.enterprisemanager.webserver.port is not
created.

If a non-secure HTTP listener is desired in addition to a secure HTTPS listener,

the default config file has a block of XML that can be uncommented to do this.
Default Jetty configuration file

A default em-jetty-config.xml is provided in the config directory. The contents
of this file are:
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN"
"http://jetty.mortbay.org/configure.dtd">




<Configure id="Server" class="org.mortbay.jetty.Server">









<Call name="addConnector">
<Arg>
<New class="com.wily.webserver.TrustingSslSocketConnector">
<Set name="validateCertificates">false</Set>
<Set name="verifyHostnames">false</Set>
<Set name="port">8444</Set>
<Set name="keystore"><SystemProperty name="introscope.config"
default="./config" />/internal/server/keystore</Set>
<Set name="password">password</Set>
<Set name="keyPassword">password</Set>
<Set name="truststore"><SystemProperty name="introscope.config"
<Set name="trustPassword">password</Set>
<Set name="needClientAuth">false</Set>

<Set name="ThreadPool">
<New class="org.mortbay.thread.BoundedThreadPool">
<Set name="minThreads">3</Set>
<Set name="maxThreads">100</Set>
<Set name="maxIdleTimeMs">60000</Set>
</New>
</Set>
</New>
</Arg>
</Call>



<Call name="addConnector">
<Arg>
<New class="com.wily.webserver.NoNPESocketConnector">
<Set name="ThreadPool">
<New class="org.mortbay.thread.BoundedThreadPool">
<Set name="minThreads">10</Set>
<Set name="maxThreads">100</Set>
<Set name="maxIdleTimeMs">60000</Set>
</New>
</Set>
</New>
</Arg>
</Call>
</Configure>
Modifying the Jetty-config.xml file

You can modify many components of SSL using Jetty-config.xml.
For more information about Jetty, see http://docs.codehaus.org/display/JETTY/

How+to+configure+SSL.
Change the HTTPS port from the default 8444, by changing the value of the
port attribute, such as in the following example:
The location of the config directory is specified in the XML by the
introscope.config system property. This is set by the EM web server at
startup and is designed as such to support a configurable config directory.

By default, the SSL listener is configured to use the keystore located at /

internal/server/keystore, a path relative to the config directory. This
contains a self-signed certificate that is untrustworthy. It is highly
recommended that you substitute your own keystore, containing a certificate
signed by a recognized Certificate Authority (CA). See http://
docs.codehaus.org/display/JETTY/How+to+configure+SSL for information
about this.
The default keystore password is password. Passwords can be obfuscated in
the Jetty XML file. See http://docs.codehaus.org/display/JETTY/
How+to+configure+SSL for information about this.
By default, SSL is configured to accept self-signed certificates and not verify
that the host name in the client's URL matches the host name in the digital
certificate. This is to ensure that SSL works out of the box with the untrusted
certificate in the default keystore. Customers needing strict authentication
should create a keystore containing a trusted certificate, and set these
attributes to in the XML, replacing the default keystore with their own:
<Set name="validateCertificates">true</Set>
<Set name="verifyHostnames">true</Set>
<Set name="keystore"><SystemProperty name="introscope.config"
<Set name="password">password</Set>
Additionally, to require client authentication, create a truststore containing
client certificates and set these attributes in the XML, replacing the default
truststore with their own:
<Set name="needClientAuth">true</Set>
<Set name="truststore"><SystemProperty name="introscope.config"
<Set name="trustPassword">password</Set>
If client authentication is required, Agents and Workstations must be
configured with a keystore containing a certificate trusted by the EM web
server.
To set the enabled cipher suites, set the cipherSuites attribute to a list of
cipher suites:
<Set name="cipherSuites">
<Array type="java.lang.String">
<Item>SSL_DH_anon_WITH_RC4_128_MD5</Item>
</Array>
</Set>
The Agents and Workstations must have an enabled cipher suite in common
with the EM in order to use SSL. You might restrict the enabled cipher suites
to prevent vulnerability to weak cipher suites, to allow anonymous
connections, or to not encrypt data.
Configuring the Enterprise Manager Web Server for HTTPS 49

CA Wily Introscope

CHAPTER
4
Configuring Enterprise Manager Data

Storage
This section describes configuration options for Introscope’s internal databases.

It contains these topics:
Configuring SmartStor data storage . . . . . . . . . . . . . 52

Configuring Transaction Event database location and aging . . . . . 54
Configuring location of baseline storage . . . . . . . . . . . . 54
Configuring Enterprise Manager Data Storage 51

CA Wily Introscope
Configuring SmartStor data storage

SmartStor records all application performance data (Introscope metrics) at all
times while it is in production. This enables users to analyze historical data, to
identify root causes of application downtime or perform capacity analysis—
without the need for an external database.
SmartStor is enabled with default settings when installing Introscope, but can be
turned off—for more information about turning off SmartStor, see
introscope.enterprisemanager.smartstor.enable on page 265. SmartStor
requires approximately 8GB of disk storage. SmartStor data is set to age-out over
time, so the data store will not get excessively large.
» Important Wily Technology strongly recommends that you configure

SmartStor to write to a dedicated disk. This avoids severely
affecting Enterprise Manager performance and responsiveness,
which could be caused by disk contention with other Enterprise
Manager activities or with other processes running on the host.
If you use a dedicated disk for SmartStor data, set the property
to true (the Introscope installer sets this property to false by
default). See
introscope.enterprisemanager.smartstor.dedicatedcontroller on
page 266.
These sections provide SmartStor planning and configuration instructions:

Determining SmartStor system requirements on page 52
Specifying SmartStor data tier values on page 53
Determining SmartStor system requirements

Your installation includes a spreadsheet to help determine SmartStor system
requirements:
<Introscope_Home>/examples/SmartStorSizing.xls
You can experiment with different values for number of metrics, and different
periods and aging ranges for your data tiers. The resulting GB size usage appears
in the table below.
SmartStor’s performance is sensitive to the operating system, JVM, and file

system choices.
52 Configuring Enterprise Manager Data Storage

This is the SmartStor Sizing Tool formula window:
After you determine the appropriate data tier frequency and aging periods, you
enter your specifications into the appropriate SmartStor properties.
Specifying SmartStor data tier values

Three data tiers configure SmartStor data storage. Each tier consists of a
property pair:
the storage frequency (in seconds)
the data aging period (in days)
The rules for the frequency and aging values are:

The storage frequency must be a multiple of 15 seconds.
The frequency must not be greater than 1800 seconds (30 minutes).
Each tier's frequency must be an even multiple of the previous tier's frequency
(this multiple can be one; each tier can have the same frequency).
The age must not be zero.
All three tiers must be defined, and you cannot define more than three tiers.
To configure the SmartStor data tier values:
1 Open the file IntroscopeEnterpriseManager.properties .
2 For the introscope.enterprisemanager.smartstor.tier1.frequency

property, enter the appropriate value.
Configuring SmartStor data storage 53

CA Wily Introscope
3 For the introscope.enterprisemanager.smartstor.tier1.age property,

enter the appropriate value.
4 Repeat for the remaining two data tier property pairs.
» Note If you change your data tiers and reboot the Enterprise Manager,
SmartStor attempts to adjust data to your new configuration, but it
might lose a day’s worth of data.
Configuring Transaction Event database location

and aging
The Enterprise Manager stores transaction traces and other event data in the
Transaction Event database.
The location of the Transaction Event database is configured during the

Enterprise Manager installation. Unless you identify a different location during
installation, the database is created in the <Introscope_Home>/traces
directory. After installation, you can choose a different location with the
introscope.enterprisemanager.transactionevents.storage.dir
property in IntroscopeEnterpriseManager.properties.
The number of days that Introscope retains transaction event data is configured
during the Enterprise Manager installation. The default value of 14, can be
changed using the
introscope.enterprisemanager.transactionevents.storage.max.data.
age property.
» Note Increasing length of time that Introscope saves event data increases
system overhead and disk storage requirements.
Configuring location of baseline storage

By default, Introscope stores Metric baseline information on the Enterprise
Manager machine, in <Introscope_Home>/data/baselines.db.
The Enterprise Manager installer does not offer the option of selecting a different
location for baseline storage. However, you can define a different location for
baselines.db in the introscope.enterprisemanager.dbfile property in
the Enterprise Manager properties file.
For information about how Introscope uses Metric baselines to enable high-level
indicators of application health, see the Introscope Workstation User Guide.
54 Configuring Enterprise Manager Data Storage

CHAPTER
5
Working with Enterprise Manager

Clustering
This section describes Introscope’s Enterprise Manager clustering functionality

and provides instructions for configuring and starting an Enterprise Manager
cluster. It includes these topics:
Understanding Enterprise Manager clustering . . . . . . . . . . 56

When to cluster Enterprise Managers . . . . . . . . . . . . 56
Understanding how MOMs manage Collectors . . . . . . . . . . 56
Clustering and Enterprise Manager clock synchronization . . . . . . 57
Clustering and Agent naming . . . . . . . . . . . . . . . 58
Clustering and Load Balancing . . . . . . . . . . . . . . . 58
Clustering and Management Modules . . . . . . . . . . . . 61
Using MOM Hot Failover . . . . . . . . . . . . . . . . . 61
Configuring a cluster of Enterprise Managers . . . . . . . . . . 63
Configuring the MOM . . . . . . . . . . . . . . . . . . 63
Configuring a Collector . . . . . . . . . . . . . . . . . 64
Configuring the assignment of Agents to Collectors . . . . . . . . 64
Working with Enterprise Manager Clustering 55

CA Wily Introscope
Understanding Enterprise Manager clustering

In a clustered environment, an Enterprise Manager serves as a Manager of
Managers (MOM), managing the other Enterprise Managers in the cluster. The
managed Enterprise Managers are called Collectors.
A Workstation user who is logged into a MOM can see and access the data that is
reported by the agents that report to each of the Collectors the MOM manages.
This Workstation user can perform all usual Workstation functions on those
Collectors.
This section describes Enterprise Manager clustering. For instructions on

configuring a cluster, see Configuring a cluster of Enterprise Managers on
page 63.
When to cluster Enterprise Managers

Clustering is useful in large Introscope environments that consist of multiple
Enterprise Managers and many Agents—a cluster configuration reduces the
complexity and cost of managing a multiple-Enterprise Manager environment.
Understanding how MOMs manage Collectors

When you start a MOM, configured as described in Configuring a cluster of
Enterprise Managers on page 63, it attempts to establish a connection with each
of the Collectors it manages.
Every Agent in the Investigator automatically has a metric called EM Host. This
metric is helpful when running a cluster, so you can tell to which Collector EM the
Agent is actually connected.
The MOM uses a built-in, pre-configured user account for connecting to

Collectors. The password is protected using public/private key encryption.
If the MOM’s initial attempt to connect to one of its Collectors results in an

unrecoverable error, such as an authentication error, an unknown host exception,
or a java.rmi.ConnectIOException, then that Collector is removed from the
cluster—the MOM stops trying to connect to that Collector until the next restart
of the MOM.
For recoverable errors, such as a lost connection, or a

java.rmi.ConnectionException, the MOM repeats the connection attempt
every 10 seconds.
Logging of connection status occurs in this fashion:

If the logging level is DEBUG, a stack trace of the connection failure is written
to the log.
56 Working with Enterprise Manager Clustering

If the logging level is VERBOSE, a message is written to the log for the first 10
consecutive failed attempts; after 10 consecutive failed attempts, a message
is written to the log that no further logging of failed connections attempts will
be made.
A message is always written to the log when the MOM connects or re-connects
to a Collector.
As long as it remains running, the MOM polls the Collectors it manages.
Clustering and Enterprise Manager clock synchronization

In an Enterprise Manager cluster, Collector system clocks must be within three
seconds of the MOM clock setting. If at startup, a Collector’s clock is not
synchronized with the MOM’s clock, the Collector will fail to join the cluster.
During operation, if a previously synchronized Collector’s clock become more
than three seconds off, the MOM will no longer accept data from that Collector.
Clock synchronization among the MOM and the Collector Enterprise Managers is
not automatic.
To keep the MOM and Collector Enterprise Manager clocks synchronized, Wily
recommends that all Enterprise Managers synchronize their clocks at regular
intervals to an NTP server. If a Collector clock becomes more than three seconds
off from the MOM’s clock, error messages in the MOM’s log indicate that the MOM
is no longer accepting data from the Collector. If this occurs, increase the
frequency of synchronization with the NTP server. No restart of Enterprise
Managers is necessary after clock synchronization. The MOM will automatically
re-connect to the Collector when it detects the clocks are synchronized.
» Note It is necessary to run a time server software which synchronizes the

clocks of all the machines in the cluster at regular intervals.
Understanding Enterprise Manager clustering 57

CA Wily Introscope
Clustering and Agent naming

In an Enterprise Manager cluster, the names of the Agents reporting to the
Collector Enterprise Managers must be unique.
The MOM requires unique agent names across the cluster. Although each
Enterprise Manager ensures that the Agents that connect to it have a unique
name, as described in the discussion about resolving agent naming conflict in the
Java Agent Guide or the .NET Agent Guide, you must ensure that the Agents
across the Collectors in the cluster have unique names. If more than one Agent
in the cluster have the same name, only the last encountered by the MOM
appears in Workstation views. Configuring Agents to obtain their names from the
application server is a technique for assigning unique Agent names. For more
information, see the discussion about obtaining an Agent name from the
application server in the Java Agent Guide or .NET Agent Guide, as appropriate
to your environment.
A Collector automatically renames Custom Metric Agents, adding a unique

identifier to the Agent name to identify the Agent's Collector. The default
identifier has the form (host@port), where host is the hostname of the
Collector and port is the Collector's connection port, as defined in its property
introscope.enterprisemanager.port.<ChannelName> on page 256. Alternatively,
the identifier can be set using the
introscope.enterprisemanager.clustering.collector.identifier
property. The identifier should be unique.
For example, the name of a Custom Metric Agent in the Super Domain in a
Collector on myhost that listens for connections on port 5001 would be:
Custom Metric Agent (myhost@5001) (*SuperDomain*)
Clustering and Load Balancing

8.0 Agents that connect to the MOM are re-directed to a Collector in the cluster.
If an Agent is subsequently disconnected from the Collector, the Agent re-

connects to the MOM and may be assigned to a different Collector.
Pre-8.0 Agents may not connect to the MOM; they must instead directly connect
to one of the Collectors. If a pre-8.0 Agent connects to the MOM, the connection
is refused and a warning message is written to both the MOM's log and the
Agent's log.

Understanding how the Load Balancer allocates Agents to

Collectors
As a general rule, each incoming Agent is redirected to the Collector with the
lightest weight-adjusted load. Load is the number of metrics as measured by
Enterprise Manager|Connnections:Number of Metrics. Weights are user-
defined values assigned to Collectors based on which ones have more (or less)
capacity than others.
The loadbalancing.xml file can be used to restrict Agents to a set of Collectors,

or exclude them from a set of Collectors. For more information, see Configuring
the assignment of Agents to Collectors on page 64.
An Agent is only assigned to a Collector that supports the same connection type
that the Agent used to connect to the MOM. For example, if the Agent connected
to the MOM using HTTP, then the Collector must have enabled HTTP connections.
The Load Balancer gives preference to Collectors that have data for the Agent in
SmartStor. This is to avoid an explosion of SmartStor metadata which causes
excessive memory overhead if Agents are bounced around the cluster. An Agent
is assigned to a Collector with history unless those Collectors are overloaded or
there is an alternate Collector that is under loaded.
A Collector is considered overloaded if its weighted metric load is over the cluster
average by more than the threshold. A Collector is considered under loaded if its
weight metric load is under the cluster average by more than the threshold. The
threshold is a user-defined value set by the
introscope.enterprisemanager.loadbalancing.threshold property in the
IntroscopeEnterpriseManager.properties file that represents the tolerance
for imbalance.
Adjusting Collector relative metric load
A weighting factor can be applied to adjust the relative load of a Collector. This
is desirable if the Collectors differ in overall metric capacity. The MOM then uses
weight-adjusted metric counts when assigning Agents to Collectors and when
rebalancing the cluster.
You can adjust the weight of a Collector by setting the

introscope.enterprisemanager.clustering.login.em1.weight property
in the IntroscopeEnterpriseManager.properties file. The value of this
property is a positive number that controls the relative load of the Collector. All
other factors being equal, the percentage of metric load assigned to a Collector
is the weight divided by the total weight for the cluster.
If no weight is specified, the Collector’s weight is the average for the cluster.

CA Wily Introscope
For more information, see Clustering Settings on page 271.
Example:
An Agent connects to the MOM. Collector A has 200,000 metrics and a weight of
100. Collector B has 160,000 metrics and a weight of 50. Collector A has the
lightest weighted load because it has 66% of the total weight but only 56% of the
metric load, so it's relatively under loaded compared to Collector B which has 33%
of the total weight but 44% of the load.
Understanding how the Load Balancer rebalances the cluster
The Load Balancer can disconnect Agents from a Collector and re-direct them to
other Collectors if it detects that the cluster has become unbalanced. A cluster is
unbalanced if any Collector is either under loaded or overloaded.
A cluster can become unbalanced for a number of reasons. For example:
A Collector may crash and be restarted.
A new Collector may be added to the cluster.
A bunch of Agents may connect directly to one Collector.
The Load Balancer checks periodically for rebalancing. The interval is a user-
defined value set by the
introscope.enterprisemanager.loadbalancing.interval property in the
IntroscopeEnterpriseManager.properties file. If the cluster is unbalanced,
the Load Balancer seeks to redress the imbalance by disconnecting Agents from
Collectors that are over the weight-adjusted average. Ejected Agents re-connect
to the MOM and are re-directed to Collectors that are under the weight-adjusted
average. The goal is an assignment of Agents that equalizes the weight-adjusted
metric load across the cluster.
The Load Balancer does not disconnect Agents that connected directly to the
Collector. This includes pre-8.0 Agents and 8.0 Agents that are not participating
in load balancing. Also, an Agent is not disconnected if the Load Balancer
determines that it would be re-assigned to the same Collector.
Load balancing when Agents prefer a specific Collector
If you have an Agent that prefers a particular Collector, connect the Agent
directly to that favored Collector. This prevents the MOM from ejecting the Agent,
because the MOM only rebalances Agents that connected directly to the MOM. For
example, if you extend Introscope with ChangeDetector to enable Introscope to
monitor and report changes in application code and configuration, a
ChangeDetector Agent may keep state in a particular Collector Enterprise
Manager. This would be the ChangeDetector Agent’s preferred Collector.

In this case, you would configure the Agent connection properties (see the Java
Agent Guide or the .NET Agent Guide) to have the Agent connect first to its
preferred Collector and secondarily to the MOM as the fallback EM enabled in case
of a failover situation. If the preferred Collector fails, the Agent then connects to
the MOM for load balancing to another Collector. However, the MOM connects the
Agent back to the preferred Collector upon failure recovery.
Clustering and Management Modules

In an Enterprise Manager cluster, only the Management Modules installed on the
MOM are used. For performance reasons, it is recommended that no Management
Modules reside on the Collector Enterprise Managers.
Using MOM Hot Failover

MOM Hot Failover can be used if a pair of Enterprise Managers shares a single
Introscope installation and are on different machines. The Introscope installation
must reside on a Storage Area Network (SAN) file system or be shared using a
Network Attached Storage (NAS) protocol such as Network File System (NFS) or
Server Message Block (SMB).
You can configure the Failover mechanism for a standalone Enterprise Manager
or MOM.
It works by designating one EM as a primary and the other as a secondary or

backup, or both EMs as primaries. The responsibility of the secondary is to take
control if the primary fails, and to relinquish control when the primary recovers.
While the responsibility of the primary is to take control from the secondary.
By default, Hot Failover is not enabled. To enable it, you will have to set the Hot
Failover properties in the IntroscopeEnterpriseManager.properties file.
For more information, see MOM Hot Failover on page 275.
When connecting to an EM, Agents and Workstations try all the IP addresses for
a host name. Thus, if you have defined a logical host in DNS with the IP
addresses of the primary and secondary EMs, then Agents and Workstations can
use this for the EM host name and will connect to whichever EM is running.
» Note In a failover environment, you can use the EMCtrl script to start a
Primary EM. The secondary EM should not use the control script. For
example, on a Unix platform, start the primary using the control script
EMCtrl.sh start and start the secondary as
./Introscope_Enterprise_Manager.

CA Wily Introscope
Hot Failover rules

There are a series of rules that apply to Hot Failover:
When you start the MOM with hot failover, you must start each MOM one at a
time. In case of a primary/secondary configuration, the primary first must be
started first.
If both EMs are primary, then the second primary waits for the first primary to
fail, and does not relinquish control when the first primary recovers.
It is possible for the Introscope installation and EMs to reside on the same host,
which will permit a second EM to take over if the first crashes when it is not
desirable to run the EM as a Windows service, or to restart it using a shell
script. For more information, see Configuring Failover to Work on a Single Host
on page 63.
If the EM's host matches one of the primary hosts, then the EM assumes the
role of primary.
If the EM's host matches one of the secondary hosts, then the EM assumes the
role of secondary.
If the EM's host matches neither the primary nor secondary host, then the EM
does a normal startup. However a warning message is logged.
A secondary EM checks every two minutes (configurable) to see if a primary
EM is waiting to start. If so, the secondary yields to the primary and shuts
down.
A primary EM does not yield to a secondary EM or another Primary EM.
The startup and shutdown sequence is as follows: When starting the Hot
Failover pair, start the primary EM first then the secondary, and when shutting
down the Hot Failover pair, stop the secondary first then the primary.
Secondary EM Startup for Hot Failover

Once the secondary has yielded to the primary, it exits the JVM, and it is up to
the Customer to restart the secondary. This could be done with a script or by
running as a Windows service. The secondary exits with a status code of 23
(org.eclipse.equinox.app.IApplication.EXIT_RESTART) if it shuts down
because it needs to yield to a primary. It exits with a 0 status code if it shuts
down normally because of a command-line interrupt or by the Workstation.
If you are using Windows you could use a command like this:
:RESTART
"Introscope Enterprise Manager"
IF ERRORLEVEL 23 GOTO RESTART

The introscope.enterprisemanager.failover.interval property controls

how often a running secondary EM checks to see if a primary EM is waiting to
start. For more information, see MOM Hot Failover on page 275.
Configuring Failover to Work on a Single Host

You can configure the Failover mechanism for your Enterprise Manager or MOM
to work on a single host rather than a shared filesystem.
To configure Failover for a single host:
1 Set the following EM properties as follows:

introscope.enterprisemanager.failover.enable=true
introscope.enterprisemanager.failover.primary=localhost
2 Start the first primary by clicking Introscope Enterprise Manager.exe.

3 Start the second primary by clicking Introscope Enterprise Manager.exe.
Configuring a cluster of Enterprise Managers

You configure a cluster of Enterprise Managers by defining cluster-related
properties in the MOM’s properties file.
Configuring the MOM

To configure the MOM for a set of Collector Enterprise Managers:
1 Set introscope.enterprisemanager.clustering.manager.enable in the

MOM’s properties file to true.
2 Define the connection properties for each of the Collector Enterprise Managers
that the MOM will manage. For each Collector that the MOM will manage, define
these properties in the MOM’s properties file:
introscope.enterprisemanager.clustering.login.<emName>.host on
page 272—specify the Collector hostname or IP address.
introscope.enterprisemanager.clustering.login.<emName>.port on
page 272—specify the listener port on the Collector.
introscope.enterprisemanager.clustering.login.<emName>. publickey on
page 272—uncomment this property to set it to the default value:
config/internal/server/EM.public
where <emName> in each of the properties is the same arbitrary identifier of the
Collector Enterprise Manager.
3 Restart the MOM.
Configuring a cluster of Enterprise Managers 63

CA Wily Introscope
Configuring a Collector
To configure a Collector in a cluster of Enterprise Managers:
1 Set introscope.enterprisemanager.clustering.collector.enable
Collector’s properties file to true. (For more information, see
introscope.enterprisemanager.clustering.collector.enable.)
2 If you want this Collector to have a special identifier, you can set the optional
property introscope.enterprisemanager.clustering.collector.identifier in the
Collector’s properties file.
If you don’t specify a special identifier for the collector, the default of host@port
is used, where host is the Enterprise Manager’s host name, and port is the
Enterprise Manager's connection port.
Default Collector private key

1 Each Collector the MOM manages must be configured to use a private key for
decrypting the password that the MOM uses to connect. The private key for a
Collector EM is defined in the
introscope.enterprisemanager.clustering.collector.enable property,
which by default is:
config/internal/server/EM.private
2 You do not need to reconfigure the private key, unless you generate a new public/
private key for the Collector. For more information, see
introscope.enterprisemanager.clustering.collector.enable.
Configuring the assignment of Agents to Collectors
Use loadbalancing.xml to configure Agent elements that will control the

assignment of connecting Agents to collectors by the MOM’s Load Balancer. For
more information about how this works, see Understanding how the Load
Balancer allocates Agents to Collectors on page 59.
For configuration examples, see Agent Load Balancer configuration examples on

page 66.
To configure Agents for load balancing:
1 Open loadbalancing.xml from the <Introscope_Home>/config directory.

2 Define the properties to meet the needs of your environment.
Follow the guidelines below and use the Agent Load Balancer configuration
examples on page 66 for reference when defining these properties:
For each <agent-collector> element, define one or more <agent-
specifier> elements to match a set of Agents.

The text content of the <agent-specifier> should be a Perl5 regular

expression, such as .*\|.*\|EPAgent1</agent-specifier.
For the <agent-collector> element list none or one collector in the
<include> elements for which the agents are permitted. If the include list is
empty, agents are not permitted in any collectors.
<include>
</include>
-or-
<include>
<collector host="localhost" port="5002"/>
</include>
For the <agent-collector> element list none or one collector in the
<exclude> elements for which the agents are not permitted. If the exclude list
is empty, agents are permitted in all collectors.
<exclude>
</exclude>
-or-
<exclude>
<collector host="localhost" port="5002"/>
</exclude>
By default, the Agent is assigned to a collector chosen by the Load Balancer.
This will also occur if a connecting Agent does not match any of the <agent-
collector> elements.
The <agent-collector> elements are evaluated in sequential order by the
MOM’s Load Balancer. If a connecting Agent matches any of the <agent-
specifiers>, it is assigned to one of the collectors in the <include> list. If
there is no <include> list, it is assigned to a collector that is not in the
<exclude> list. If there are no collectors available that meet these
restrictions, the Agent's request for a collector is rejected.
The <name> attribute is optional.
The new value is when the Enterprise Manager checks the property file during a
hot deploy. A hot deploy occurs about once every 60 seconds.
Configuring a cluster of Enterprise Managers 65

CA Wily Introscope
Agent Load Balancer configuration examples

You can configure the Agent Load Balancer properties a variety of ways. These
examples, provide code examples of the following configurations:
Assign an Agent to a particular Collector or set of Collectors on page 66
Exclude an Agent from a particular Collector or set of Collectors on page 66
Assign multiple Agents to multiple Collectors on page 66
Assign an Agent to a particular Collector or set of Collectors
The following example shows Agent Load Balancing properties configured to

assign an agent to a specific Collector.
<agent-collector name="Example 1">

<agent-specifier>.*\|.*\|MyAgent</agent-specifier>
<include>
<collector host="myhost" port="5001"/>
</include>
</agent-collector>
Exclude an Agent from a particular Collector or set of Collectors
The following example shows excluding an Agent from a Collector.

<agent-specifier>.*\|.*\|MyAgent</agent-specifier>
<exclude>
<collector host="MyHost" port="5001"/>
</exclude>
</agent-collector>
Assign multiple Agents to multiple Collectors
The following example shows how to assign multiple Agents to multiple

Collectors.

<agent-specifier>.*\|.*\|MyAgent.*</agent-specifier>
<agent-specifier>.*\|.*\|MyOtherAgent.*</agent-specifier>
<include>
<collector host="MyHost" port="5001"/>
<collector host="MyOtherHost" port="5001"/>
</include>
</agent-collector>

CHAPTER
6
Creating and Editing Introscope

Dashboards
This chapter describes how to create and edit Introscope Dashboards in the
Introscope Workstation. It includes these topics:
Introscope Dashboard Editor overview . . . . . . . . . . . . 68
Creating Dashboards . . . . . . . . . . . . . . . . . . 71
Creating Data Viewers in a Dashboard . . . . . . . . . . . . 76
Setting data-viewing properties of a Data Viewer . . . . . . . . . 82
Embedding an Investigator Tab View in a Dashboard . . . . . . . 91
Adding shapes and lines to Dashboard . . . . . . . . . . . . 92
Coloring shapes, lines and connectors . . . . . . . . . . . . 95
Creating and editing text . . . . . . . . . . . . . . . . 97
Inserting an image on a Dashboard . . . . . . . . . . . . . 100
Manipulating Dashboard objects . . . . . . . . . . . . . . 101
Creating and managing custom hyperlinks . . . . . . . . . . . 106
Creating and Editing Introscope Dashboards 67

CA Wily Introscope
Introscope Dashboard Editor overview

Users with write permission to a Domain can create and edit Data Viewers and
other Dashboard objects such as imported images, shapes, lines, and text.
Introscope Dashboards allow total layout control of objects on a Dashboard.
You create Data Viewers in the Dashboard Editor window. In addition, there are
now two ways to create Data Viewers:
Creating Data Viewers automatically by dragging and dropping data from the
Investigator tree onto a Dashboard
Creating an empty Data Viewer in the Dashboard Editor, then adding the data
to the viewer
Both of these options are described in detail in this chapter.
Dashboard editing and Domain enforcement

The Domains and Users features partition Agents into specific Domains. Users
have access only for certain Domains. Introscope enforces Domain access as you
create and edit Dashboards. Any time you create or modify a Data Viewer in the
Dashboard Editor, the operation is validity-checked against the Domain visibility
rules.
Elements in Dashboard objects in the SuperDomain can reference Elements

and data in any Domain
Elements in Dashboard objects in a user-defined Domain can only reference
Elements and data in the same Domain
For more information on Domains and Domain enforcement, see the Introscope
Installation Guide.
68 Creating and Editing Introscope Dashboards

About Dashboard objects

There are two types of Dashboard objects: data viewer objects, and shapes,
images and text objects.
Data Viewer objects

Depending on the type of metric or element selected, Introscope can display the
data in a Data Viewer as these objects:
Graph String Viewer

Bar Chart Text Viewer
Dial Meter Alert Status Indicator
Equalizer
See the Introscope Workstation User Guide for more information about these
objects.
Shapes, images and text objects

You can add text blocks, images, shapes, and lines to the dashboard, to help
explain and illuminate your data.
For example, you could:
add a conceptual diagram of your application environment
add your company logo to your Dashboards
insert images of your products
add text blocks to the Dashboard to explain Dashboard elements in your

company’s language
draw a rectangle without a fill to visually group items on a Dashboard
draw arrows to point to an object and add emphasis
draw connectors between objects to create a simple flow chart
Graphic and text objects

Graphic and text objects correspond to simple tools found in image editing
programs, with the addition of the imported graphic.
Rectangle Basic Line

Rounded Rectangle Straight Connector
Oval Elbow Connector
Polygon Imported Graphics
Scribble (freehand drawing tool) Text box
Introscope Dashboard Editor overview 69

CA Wily Introscope
Editing a Dashboard
To add or manipulate Dashboard contents, you open the Dashboard in the
Dashboard Editor. Only a user with write access to a Domain or SuperDomain can
edit a Dashboard.
To open a Dashboard in the Dashboard Editor:
1 In the Console, select the Dashboard tab to activate it.

2 Select Dashboard > Edit Dashboard.
The Dashboard Editor opens.
The Dashboard Editor contains the tools you use to change the look of a
dashboard, or create a new one.

About the tools palette

The tools palette contains all the tools for creating and editing Dashboard objects.
It contains standard drawing tools, tools for connecting objects, and tools for
adding text. It also contains tools for drawing empty data viewers, onto which
you can place data.
Selects objects Creates an empty text box for

user-entered text
Draws rectangles Creates an empty alert status
indicator
Draws rounded rectangles Creates an empty graph
Draws ovals Creates an empty bar chart
Draws polygons Creates an empty dial meter
Draws freehand shapes Creates an empty graphic

equalizer
Draws straight lines Creates an empty string
Draws a straight connector line Creates empty text

between two objects
Draws a connector line between
two objects with right angles
Creating Dashboards
By creating new Dashboards, you can create collections of different Data Viewers
for different uses. For example, you might have one Dashboard containing
database information, and one Dashboard for system Alerts.
Creating a new Dashboard in the Console

You can create a new Dashboard from a command in the Console.
To create a new Dashboard in the Console:
1 In the Console, select Dashboard > New Dashboard.
Creating Dashboards 71
CA Wily Introscope
2 Enter a name for the new Dashboard, and choose a Management Module to
contain the Dashboard.
Select a Management Module from the drop-down list.
Click Choose, select a Management Module from the list, and click Choose
again.
3 Click OK.
The new Dashboard opens in the Dashboard Editor.
4 Edit the Dashboard to suit your needs, as described in this chapter.

5 Select File > Save.

The new Dashboard appears in the Management Module Editor tree, under the
Domain and Management Module in which you saved it.
6 If you are finished editing the Dashboard, select Workstation > Close Window.
Creating a New Dashboard in the Management Module Editor

To create a new Dashboard in the Management Module Editor:
1 Select Elements > New Dashboard.
2 Enter a name for the new Dashboard, and choose a Management Module to
contain the Dashboard.
Select a Management Module from the drop-down list box.
Click Choose, then select a Management Module from the list and click
Choose again.
3 Select the Description tab to enter descriptive text and any important
information about the dashboard in the Description Text field.
This field should contain no more than 64 KB of data. After it is applied, it will be
persisted in the management module jar.
4 Click OK.
The new Dashboard appears, highlighted, in the Management Module Editor tree.
5 To edit the Dashboard, open the Console, select the tab of the new Dashboard,
and use the Dashboard > Edit Dashboard command.
Other Dashboard editing options

Use the Console Edit Dashboard menu to resize a dashboard workspace area, and
save, rename, and delete dashboards.
CA Wily Introscope
Resizing a Dashboard
To resize a dashboard workspace area:
1 In the Console, select Dashboard > Edit Dashboard.

2 Select Edit > Change Dashboard Properties.
Enabling Snap to Grid and setting a grid

size helps you align objects on the
dashboard.
3 Enter new width and height values (in pixels) in the fields.
4 Enable Snap to Grid and set a grid size, if you want dashboards to snap to a
specific location as you drag them.
5 Enable Clear Previous Lens Settings if you want the lens cleared each time a
user selects this Dashboard. See Dashboard links support Agent lens on page 106
for more information.
6 Click OK.
The Dashboard workspace area resizes to the defined size.
7 Select File > Save to save Dashboard changes.
Saving a copy of a Dashboard

To save a copy of a dashboard:
1 With a Dashboard open in the Dashboard Editor, select File > Save As.
2 Enter a name for the copy of the Dashboard.

3 Choose a Management Module to contain the Dashboard.

Click Choose, then select a Management Module from the list and click
Choose again.
» Note You can only choose a Management Module that belongs to a Domain to
which you have access, and that has access to all elements and metrics
viewed in the dashboard.
4 Click OK.
The new Dashboard appears in the Management Module Editor tree, under the
Domain and Management Module in which you saved it.
Renaming a Dashboard
1 With a Dashboard open in the Dashboard Editor, select File > Save and Rename.
2 Enter a new name for the Dashboard.
3 Click OK.
» Note You can also rename a Dashboard by selecting it in the Management
Module Editor, and editing the name in the Preview pane.
Deleting a Dashboard (from the Management Module Editor)

To delete a Dashboard from the Management Module Editor:
1 In the Management Module Editor tree, select the Dashboard to delete.
CA Wily Introscope
Right-click on it, and select Delete <Dashboard Name>.
Select Elements > Delete <Dashboard Name>.
The Delete Confirmation dialog box opens.

2 Click Yes to delete the Dashboard.
The Dashboard is deleted from the Management Module Editor tree and Console.
Creating Data Viewers in a Dashboard

There are two ways to create Data Viewers in Introscope:
Select a Metric in the Investigator tree, or a Metric Grouping, or Element from
the Management Module Editor tree, and drag it onto a Dashboard,
automatically creating the default Data Viewer for that type of information.
Create an empty Data Viewer, then add information to it.
» Note When you create or make changes to a dashboard, always save the
dashboard as the last step. Although it isn’t necessary to save changes
to a dashboard after every individual edit, it is important that you save
changes frequently to make changes available to other Workstation
users with access to that dashboard.
Creating a Data Viewer automatically

The easiest way to create a Data Viewer is to select a Metric (or Element, etc.)
from the Management Module Editor tree, and drag-and-drop it onto the
Dashboard Editor window. You can drag-and-drop in two ways:
Drag the data onto an existing Data Viewer in a Dashboard (the new data
replaces the existing data in the viewer)
Drag the data to an empty area on a Dashboard, which automatically creates
a new viewer to contain it

These are the default data viewer types for each of the data types:
Data type Default Data Viewer type

Metric graph
Metric Grouping graph
Alert status indicator
Calculator graph
Creating a Data Viewer by dragging and dropping data

The easiest way to create a Data Viewer automatically is to select something
(Metric, Metric Grouping, Alert, etc.) from the Investigator tree and drag it onto
the Dashboard. These directions use a Metric as an example.
To create a Data Viewer by dragging and dropping data:
1 In the Console, select Dashboard > Edit Dashboard.

2 Open an Investigator window and position it so both the Investigator window and
Dashboard are visible.
3 In the Investigator, click and hold a Metric in the tree. Drag it to the Dashboard
and drop it when you see the blue highlighted line all around the Dashboard.
Creating Data Viewers in a Dashboard 77

CA Wily Introscope
» Note If you attempt to drag something to a Dashboard in violation of Domain

enforcement rules, you do not see the blue highlight on the Dashboard
and nothing appears on the Dashboard when you release the mouse
button.
The blue border shows that the

Data Viewer will be created here.
A Data Viewer appears on the

Dashboard and is shown in the
appropriate Data Viewer type for
that information.
If you drop the selection when only an existing Data Viewer is highlighted, and
the Data Viewer type is compatible with the selection, the information you are
dragging replaces what is in that viewer.
Creating an empty Data Viewer and adding data

In this process, you create a Data Viewer first, then specify the data to appear in
the viewer. You create a Data Viewer using the Tools Palette.
There are two ways to add data to an empty Data Viewer.

Drag and drop data from the Investigator tree.
Add data through the Data Options dialog.

Creating an empty Data Viewer

To create an empty Data Viewer:
1 In the Console, open the Dashboard to edit by selecting Dashboard > Edit
Dashboard.
2 Select a Dashboard object creation tool from the Tools Palette.
3 Click and drag the location and size of the empty Data Viewer on the Dashboard
area.
4 Release the mouse button.

The Data Viewer appears on the Dashboard as drawn. You can now manipulate
the Data Viewer.
Adding data to a Data Viewer by dragging and dropping

You can add data to a Data Viewer by dragging and dropping from the
Investigator or the Management Module Editor.
You can use this function to:

Add data to an empty Data Viewer.
Replace the data displayed in existing Data Viewer.
To add data to a Data Viewer by dragging and dropping:
Dashboard.

CA Wily Introscope
2 Select the data to add to the Dashboard:

To add a Metric to the Dashboard, open an Investigator window and position it
so both the Investigator window and Dashboard are visible, then click and hold
a Metric in the tree.
To add an Element to the Dashboard, open the Management Module Editor, and
click and hold an Element in the tree.
3 Drag the Metric or Element to the Dashboard and drop it when you see the blue
highlighted line around the Data Viewer.
» Note If you try to drag a Metric or Element to a Dashboard that violates
Domain enforcement rules, you do not see the blue highlight on the
Dashboard, and nothing populates the Data Viewer when you release the
mouse.
If the Data Viewer already contains data, it is replaced by your new data when
you drop it.
Adding data to Data Viewer using the data options dialog

To add data to Data Viewer using the data options dialog:
Dashboard.
2 Right-click on the empty Data Viewer and select Data Options.
The Data Options window opens.

3 From the left side of the window (Data Type), select a data type for this Data
Viewer.
Data Type options differ depending on the Data Viewer type. Possible options are:
Metric Grouping Calculator

Alert Metric
4 From the Data Selection list, select the data selection to appear in the Data
Viewer.
5 Click OK.
The Data Viewer is populated with the data selection.
Discovering which data appears in a Data Viewer

Some Data Viewers (such as Alerts) do not display the name of the Metrics that
supply its data.
To discover which data is displayed in a Data Viewer:
Dashboard.
2 Right-click on the Data Viewer and select Data Options...
The Data Type and exact Data Selection that are used are highlighted in the Data
tab.
3 Click Cancel or OK to close the Data Options window.

CA Wily Introscope
Setting data-viewing properties of a Data Viewer

In the Dashboard Editor window, you can change these properties of a Data
Viewer:
Viewer display type Whether Labels are on or off
Scaling options View period
Sorting/Filtering options
Data Viewer display options

In the Workstation, you can define views for almost all types of Metrics. These
views can appear as several view types, depending on the data defined in the
Metric.
Because Metric data can consist of different information (text, dates, counters,
numbers, and so forth), not all data can appear in every Data Viewer type. For
example, the data from the metric Java Version cannot appear as a Graph,
because its data is text.
To find out what view display types are available for the selected view, right-click
on the Data Viewer and look at the View As... submenu.
To change the Data Viewer display type:
Dashboard.
2 Select the Data Viewer whose display type you want to change in one of these
ways:
Right-click and select View As and the new Data Viewer display type from the
submenu
Select Properties > View As and select the new Data Viewer display type from
the submenu
Changing scaling options for a Data Viewer

You can change the scale of graph charts while viewing live data in Introscope
Workstation, to provide a more readable view. You change the scale of a chart by
setting a minimum and maximum value for the chart’s data axis.
The chart scaling feature is available only for graph charts in Live mode. It is not
available in Historical mode or for any other viewer type such as bar chart, top
ten, or string viewer.

» Note Scale changes that you make to a chart are temporary—the settings are
not saved with the dashboard. When you select a new dashboard or close
the Console window, Introscope discards the settings and returns to the
scale options that were applied when the dashboard was created.
To view the scale of a graph chart:
Click on a chart to select it, and then:
Select Viewer > Scale options, or
Right-click the chart and select Scale Options from the context menu.
The Data Options dialog box opens.
Setting the
Auto Scale
Minimum and
Maximum
default values
provides a
more readable
view of charts
in Live mode.
To rescale using min and max values:
1 Click on a chart to select it, and then:

2 Enter the minimum and maximum values for the data axis of the graph.
3 Click OK.
Setting data-viewing properties of a Data Viewer 83

CA Wily Introscope
For example, if the chart data values lie primarily between 350 and 550 but the
chart value axis shows 0-1000, it might be helpful to set the scale Min value to
300 and Max value to 600 for a better view of the relevant data:
To force minimum and maximum values:

2 Select Pin at on both the Minimum and Maximum sides of the dialog, and enter
a value for the minimum and maximum points of the data access.
3 Click OK.
Setting Min and Max values for a chart showing live data is risky, however, if
there is a chance the data may exceed the values you set.
To avoid this problem, use the Auto Scale option to automatically set the graph
to change its scale according to the data it displays.
To rescale using Auto Scale:


2 Select AutoScale on both the Minimum and Maximum sides of the dialog.
3 Click OK.
The resulting chart’s data axis is reset based on the data in the chart, as shown
in the illustration below. This often results in sharper valleys and peaks in the
graph display:
You can also set the scaling options to Auto Expand. This option uses 0 as the
bottom of the data axis and automatically expands and scales the data axis to
display all data for the time range.
To rescale using Auto Expand:

2 Choose Auto Expand on both the Minimum and Maximum side of the dialog.
3 Click OK.

CA Wily Introscope
Changing Sorting and Filtering Options

You can define sorting and filtering options for Graph and Bar Chart viewers.
In the Sorting/Filtering Options tab, you can:

Enable/disable filtering.
Switch between top/bottom Metric filtering.
Specify how many Metrics to filter (default is 10).
Add, remove, or clear included or excluded Metrics.
» Note While sorting/filtering is in use, these Metric viewing options are not
available: bring to front, send to back, and hide/show Metric.
Defining type and number of metrics shown in Filtered View

To define type and number of Metrics shown in Filtered View
1 Check the Enable Filter checkbox.

2 In the Show the Top/Bottom pull down menu, choose whether to show the Top
N or Bottom N Metrics.
3 In the X Metrics field, enter the number of Metrics to view in the Filtered Views
list. The default number is 10.
4 Click OK.
The Data Viewer shows the number of top or bottom Metrics you defined, and
identifies the number of Metrics it is displaying.

Including selected metrics

To include selected metrics:
1 On the Sort/Filter tab, in the Included Metrics area, click Add.
2 The window lists metrics that currently match the metric grouping, sorted
alphabetically. Metrics that are already defined in the Included or Excluded
Metrics lists do not appear.
3 Click to select the Metric to add to the Included Metrics list. Select multiple
Metrics using Shift or Ctrl key.
4 Click OK, then OK again.
The included Metrics appear in the Included Metrics list in the Sorting/Filtering
Options window.
A message notifies you if no additional Metrics are available.

CA Wily Introscope
Excluding selected metrics

You can exclude any Metrics, regardless of whether they are ranked in your
defined top or bottom viewer.
To exclude selected Metrics:
1 In the Excluded Metrics area of the Sort/Filter tab, click Add.
The window lists Metrics that currently match the Metric grouping, sorted
alphabetically. Metrics already defined in the Included or Excluded Metrics lists
are not shown.
2 Click to select the Metric to add to the excluded Metrics list. Select multiple
Metrics using Shift or Ctrl key.
3 Click OK, then OK again.
The excluded Metrics appear in the Excluded Metrics list in the Sorting/Filtering
Options window.
A message notifies you if no additional Metrics are available.
Removing selected metrics from included or excluded metric

lists
To remove individual metrics from the included or excluded metrics lists:
1 In either the Included or Excluded Metrics list, click on the Metric you want to
remove from the list. Select multiple Metrics using Shift or Ctrl key.
2 Click Remove.
3 Click OK.
The Metric is removed from the Included or Excluded Metric list.

Clearing all included or excluded metrics

To clear all metrics from the included or excluded metrics list:
1 In either the Included or Excluded Metrics list, click Clear All.

2 Click OK.
All Metrics in the list are removed.
Changing the view resolution

You can change the view resolution on every viewer type except for an alert
status indicator. Note that this only changes the view resolution in the Data
Viewer, not the collection resolution for any referenced Metric Groupings or other
Elements.
To change the view resolution for a Data Viewer:
1 Open the Dashboard in the Dashboard Editor.

2 Select the Data Viewer with the Selection tool and right-click and select Data
Options and then click the Miscellaneous tab. Or, select Properties > Data
Options and then click the Miscellaneous tab.
3 Select a new view resolution and click OK.

The viewer displays data using the new time-resolution value.

CA Wily Introscope
Turning labels on and off

Labels that you can turn on and off refer to the Metric information shown in a
Data Viewer.
Labels or legend on (showing). Labels or legend off (hidden).
You can turn labels on and off in these Data Viewers:
Graphs Graphic Equalizer

Bar Charts String Viewer
Dial Meter Text Viewer
To turn labels on and off in a Data Viewer:
Dashboard.
2 Select the Data Viewer with the Selection tool.
3 Select Properties > Data Options, then click the Miscellaneous tab.
4 Turn Labels on or off in one of these ways:

Check the Show Labels or Legend checkbox to turn Labels on.
Uncheck the Show Labels or Legend checkbox to turn Labels off.
5 Click OK.

Changing alert status indicator options

Alert status indicator viewers can display:
An alert status indicator, which contains three indicators; only one of the three
circles lights up to show the current status.
A single alert status indicator, which contains only one indicator; the indicator
changes color according to current status.
To change the options for an alert status indicator:
Dashboard.
2 Select an alert status indicator with the Selection tool and right-click and select
Data Options, then click the Alert tab, or, select Properties > Data Options,
then click the Alert tab.
3 In the Alert Type field, use the pull-down menu to choose either a Single
Indicator or Multiple Indicator option.
4 Click OK.
The alert status indicator changes to the selected view.
Embedding an Investigator Tab View in a Dashboard

To add an Investigator View to a Dashboard:
1 Open the Dashboard in the Dashboard Editor.

2 Open an Investigator window, select an item in the Investigator tree, and select
the tab for the View you want.
3 Drag the tab for that View into the Dashboard Editor.
See the Introscope Workstation User Guide for a description of Investigator tab
views.
Embedding an Investigator Tab View in a Dashboard 91

CA Wily Introscope
Adding shapes and lines to Dashboard

Use the Dashboard Editor to add shapes, lines, text, and images to your
dashboards. You can add these shapes to a Dashboard:
Rectangle Polygon
Rounded Rectangle Scribble (freeform draw tool)
Oval/Circle Basic Line
After you draw a shape or line with any tool, the Selection tool is automatically
selected, so you can then move or resize the shape or line.
To add shapes and lines to Dashboard:
1 In the Console, select Dashboard > Edit Dashboard to open the Dashboard.
2 Select the appropriate tool.
To Do this
Draw rectangles, 1 Click one of the shape tools:
rounded
rectangles or ovals Rectangle
on the Dashboard
Rounded Rectangle
Oval/Circle
2 Click and drag to draw a shape.

Change the 1 Select the rounded rectangle in the dashboard with the
amount of edge Selection tool
roundness on a
rounded rectangle
.
2 Click on the yellow dot and drag it inward to change the edge
roundness.
Pulling the yellow dot in different directions changes the edge
roundness in different ways.
Click the yellow dot and drag it

to change the shape of the
rounded rectangle.

To Do this
Draw a polygon on 1 Click the Polygon tool.
the Dashboard
2 Click on a starting point anywhere on the Dashboard, then

click more points to form the shape of the polygon.
3 When you have drawn enough points, double-click to finish the

polygon.
Draw a scribble 1 Click the Scribble tool.

(freeform shape)
on the Dashboard
2 Click on a starting point, then hold down the mouse button and
draw a shape.
3 To finish the scribble, double-click.

Draw lines on the 1 Click the Line tool.
Dashboard
2 Click on a starting point, then drag in any direction to draw a

line; release the mouse button to end the line.
Move the 1 Select the line with the Selection tool.
endpoints of a line
2 Click on one of the endpoints, and drag it to a new location.

3 Click anywhere outside the line to deselect it.
Drawing connector lines and adding arrowheads

You can show a relationship between two or more Dashboard objects by
connecting them with either a straight connector or an elbow connector. Using a
connector line enables you to move the two Dashboard objects while maintaining
the connection.
Adding shapes and lines to Dashboard 93

CA Wily Introscope
To draw connector lines and add arrowheads:
Dashboard.
To Do this
Connect two 1 Click the Straight Connector or the Elbow Connector tool.
Dashboard objects
with a connector Straight connector Elbow connector
2 Click on the first Dashboard object to be connected.

3 Hold the mouse button down and move over the second
Dashboard object.
4 Release the mouse button.
A connector appears between the two dashboard objects.
Add arrowheads to 1 Right-click the line or connector to edit with the Selection
a line or connector tool.
2 Select Arrows from the sub-menu, then an arrowhead

option:
None (removes existing arrowheads from a line)
At End (adds an arrowhead where line ended when
drawn)
At Start (adds an arrowhead where the line started when
drawn)
Both (adds arrowheads to both ends of the selected line)
3 By default, a connector uses the Both option (arrowheads at
both ends).
Arrowheads appear as you have specified on the line or
connector.

Coloring shapes, lines and connectors

You can add a fill color to shapes and a pen color to shapes and lines, selecting
from standard or custom colors.
To color shapes, lines, and connectors:
Dashboard.
To Do this
Add fill color to a 1 Select the shape to color with the Selection tool.
shape
2 Choose the color:

Select Properties > Fill Color, then select a color from the
menu.
Right-click and select Fill Color, and select a color from the
menu.
The object is filled with the selected color.
Add pen color to a 1 Select the shape, line, or connector to color with the Selection
shape or line tool.
2 Choose the color:

Select Properties > Pen Color, then select a color from the
menu.
Right-click and select Pen Color, and select a color from the
menu.
The outline, line, or connector is colored with the selected
color.
Add a custom fill or 1 Select a shape, line or connector with the Selection tool.
pen color
2 Choose the color:

Select Properties > Fill Color or Pen Color, then select
Other.
Right-click and select Fill Color or Pen Color, and select
Other.
The Choose Color dialog opens. This dialog contains three
tabs, Swatches, HSB and RGB, which all contain additional
color options.
Coloring shapes, lines and connectors 95

CA Wily Introscope
To Do this
Use choose a color 1 Click the Swatches tab.
from a selection of
swatches
2 Click on any color swatch.

The Preview area shows what the selected color look like as a
fill, outline (pen color), text, or text background.
3 When you’re satisfied with a color, click OK.
Use define a color 1 Click the HSB tab.
using Hue,
Saturation, and
Brightness values
2 Select a color by:

Entering values in HSB fields.
Moving slider up and down through the spectrum, then
clicking in the large square to select a color.
The Preview area shows what the selected color looks like as
a fill, outline (pen color), text, or text background.

To Do this
Define colors using 1 Click the RGB tab.
RGB (Red, Green,
Blue) values
2 Select a color by:

Entering values in RGB fields, or
Moving each of the Red, Green or Blue sliders up and down.
Drag the slider up and
down the color spectrum The Preview area shows what the color looks like as a fill,
to select a basic shade outline (pen color), text, or text background.
Creating and editing text

The Label tool is useful for adding descriptive text boxes to add context to your
Data Viewers.
Note that you can only change the font attributes for user-created text blocks
(created with the Label tool). You cannot change font attributes for Legend text
in a Data Viewer.
Creating Text on a Dashboard

To create a text block on a Dashboard:
Dashboard.
Creating and editing text 97

CA Wily Introscope
2 Click the Label tool .

3 Click anywhere on the Dashboard to create a placement point. A text box opens.
4 Type in your text. To create text boxes with multiple lines, press Enter at the end
of a line of text—the cursor moves to the next line in the box for you to resume
typing.
5 To exit the text entry field, click anywhere on the Dashboard outside the text
field, or choose another tool.
Editing text
To edit existing text:
1 Click the Label Tool and click on the text block. The text is highlighted and
you can edit it.
2 Click anywhere outside the text block to deselect it.


Changing text attributes

You can change the font, font size, color, background color, and style of text in
a text block.
To change text attributes:
1 Click the Selection tool to select the text block to modify.
To Do this
Change text font 1 Select Properties > Text > Font, or right-click and select
Text > Font from the menu.
2 Select a font from the font list.
The text block updates with font selection.
Change text size 1 Select Properties > Text > Size, or right-click and select
Text > Size from the menu.
2 Select a text size from the list.
The text block updates with text size selection.
Change text color 1 Select Properties > Text > Color, right-click and select Text
> Color from the menu.
2 Select a color for the text by:
Selecting a color from the menu
Selecting Properties > Text > Color > Other... and
choosing a color from one of the color pickers.
For more information on additional color options, see Add a
custom fill or pen color on page 95.
The text block updates with color selection.
Change text style 1 Select Properties > Text > Style, or right-click and select
Text > Style from the menu.
2 Select a text style (Plain, Bold or Italic) from the list.
The text block updates with style selection.
Add a Text 1 Select Properties > Fill Color, right-click and select Fill
background color Color from the menu.
2 Select a background color for the text by:
Selecting a color from the menu
Selecting Fill Color > Other... and choosing a color from
one of the color pickers
For more information on additional color options, see Add a
custom fill or pen color on page 95.
The text block updates with color selection.
Creating and editing text 99

CA Wily Introscope
Changing text size freehand

You change the size of text freehand by resizing the text block.
To change text size freehand:
1 Use the Selection tool to select the text block to resize.
Click and drag the yellow dot to resize text.
2 Click on the yellow dot and drag in or out to resize text.

3 Click anywhere outside the text block to deselect it.
Quick font editing directions
To Do this
Change text color 1 Select Properties > Text > Color.
2 Select color from menu, or Properties > Text > Color >
Other and choose other color from color pickers.
Add text 1 Select Properties > Fill Color
background color 2 Select color from menu, or Properties > Fill Color > Other
and choose other color from color pickers.
Change text style 1 Select Properties >Text >Style
2 Select text style (plain, bold or italic)
Change font size Select Properties > Text > Size
select text size, or
resize the text block freehand
Inserting an image on a Dashboard

An easy way to give your dashboards more context is to import an image—for
example, representations of network components, or a company logo. Introscope
provides some basic network images (located in the <Introscope_Home>/
images directory), or you can insert any graphic file of .JPEG or .GIF format.
» Note Introscope does not support animated .GIF files.
To insert an image onto a Dashboard:
Dashboard.
2 Select Edit > Insert Image to browse for an image.

3 Browse to select an image, then click Open.

The image is inserted in the upper left corner of the Dashboard.
4 Click the Selection tool, then click on the image to select it and move it.
Manipulating Dashboard objects

You can use the Dashboard Editor to perform these actions with dashboard
objects:
Select Align
Move Arrange dashboard objects front to back
Resize Group and ungroup
Resize graph legend size Connect with connectors
Cut/copy/paste/duplicate/delete
Dashboard objects, except for connectors, can be moved and placed anywhere
on the dashboard area. Both line connectors and elbow connectors are
repositioned automatically when the objects to which they are connected are
moved.
Most dashboard objects can be resized, with some restrictions:

If multiple Dashboard objects are selected, only the Dashboard object whose
handle is used is resized.
Grouped dashboard objects cannot be resized.
Polygons are resized in a special way.
Scribbles cannot be resized, although you can reposition the points in the
scribble, thus changing the length of the segments that make up the scribble.
When Data Viewers are resized, they simply get bigger or smaller—the
representation of data does not change (scale does not change, no more or
fewer points are visible).
To manipulate a Dashboard object:
Dashboard.
2 Select the object with the Selection tool .
Manipulating Dashboard objects 101

CA Wily Introscope
The Dashboard object’s handles appear.
3 To select multiple Dashboard objects, hold down the Shift key, and click on each
object to add it to the selection.
You can also use the Shift key to deselect an object from a multiple-object
selection.
4 Make changes as needed.
To Do this
Move a Dashboard Using the Selection tool drag the Dashboard object to the
object target location.
Dashboard objects, except for connectors, can be moved and
placed anywhere on the dashboard area. Both line connectors
and elbow connectors are repositioned automatically when the
objects to which they are connected are moved.
Move a dashboard With the object selected, use the keyboard’s arrow keys to
object in small move the dashboard object one pixel at a time in the arrow
increments key’s indicated direction.
Resize a Place the pointer over one of the object’s handles, click on it,
dashboard object and drag it inwards or outwards to resize the object.
Resize a polygon With the polygon selected, click and drag the yellow dot to
resize the polygon.
You can also rotate the polygon as you resize it.
Click and drag the yellow dot to resize

the polygon.
Cut, copy, and 1 With the object selected, right-click on the object(s) and select
paste a Dashboard Cut or Copy from the menu
object Note: Introscope only allows objects to be pasted into
Dashboards within the same Domain as the Dashboard
they were copied or cut from.
2 Open the destination Dashboard by selecting Dashboard >
Edit Dashboard.
3 Right-click on the Dashboard and select Paste from the menu.
Note: A line connector is only cut/copied/pasted if both objects
it is connected to are cut/copied/pasted.

To Do this
Duplicate a With the object selected, right-click on the object and select
Dashboard object Duplicate from the menu or select Edit > Duplicate.
The Dashboard object is duplicated on the Dashboard. If
multiple items are selected, they are all duplicated.
Delete a With the object selected, select Edit > Delete, right-click and
Dashboard object select Delete, or press the Delete or Backspace keys.
The Dashboard object is deleted from the Dashboard.
Note: Dashboard objects are not displayed as Elements in the
Management Module Editor tree; you must delete
Dashboard objects in the Dashboard Editor window. If
multiple items are selected, they are all deleted.
Resizing graph legend size within a graph Data Viewer

Resizing a graph by using its handles resizes the overall graph size.
To resize the graph legend area:
1 Make sure the graph is showing Labels/Legend.

2 Click and drag the yellow diamond up or down to make the Graph legend area
smaller or larger relative to the Graph area.
Before resizing the Graph legend area. After resizing the Graph legend area.
» Note If you replace the data in this Graph with data that contains additional
Metrics, you might need to resize the Graph to show all the Metrics
(although scroll bars appear if the Metrics cannot all be viewed).
Aligning Dashboard objects

To align two or more Dashboard objects:
Dashboard.

CA Wily Introscope
2 Select the Dashboard objects to be aligned.

If only one dashboard object is selected, the Align commands are disabled.
3 Select an Align command from the Edit > Align menu:
Top aligns objects so that the tops are even.
Middle aligns objects vertically, so that

the centers are even.
Bottom aligns objects vertically, so that

the bottoms are even.
Left aligns objects on Center aligns objects Right aligns objects on

their left sides by their centers. their right sides.
The Dashboard objects are aligned as specified.

Arranging Dashboard objects front to back

You can layer Dashboard objects, and move them in front of and in back of each
other.
To move objects to front and back:
Dashboard.
2 Select the object to be moved with Selection tool and move it in one of these
ways:
Right-click on object and select either Bring to Front or Send to Back from
the menu.
Select Edit menu and then select either Bring to Front or Send to Back.

Grouping and ungrouping objects

In Dashboards with many objects, it might be helpful to group the objects to
make placement easier. You can also group multiple grouped objects.
To group selected objects:
Dashboard.
2 Select the objects to be grouped (shift+click to add objects to a selection), and
select Edit > Group, or right-click on the group of objects and select Group from
the menu.
Selected objects are grouped into one item, represented by one set of handles.
Ungrouped—
more than one
set of handles.
Grouped—one set of
handles.
» Note You cannot resize grouped objects.
To ungroup a grouped object:
1 Select the object to be ungrouped, and select Edit > Ungroup, or right-click on
the grouped object and select Ungroup from the menu.
The grouped object is separated into individual objects, all with their handles
highlighted.
» Note If the grouped object contained another grouped object, this object
remains grouped.

CA Wily Introscope
Creating and managing custom hyperlinks

You can use custom links to create hyperlinks between dashboard objects and
other dashboards, or external Web pages. A dashboard object can have multiple
links of multiple types. Custom hyperlinks are available to any Introscope user.
Dashboard links support Agent lens

You can associate an Agent lens with a Dashboard link, so that it is applied each
time the link is clicked. For example, if you have an Overview Dashboard with
alert status indicators for multiple Agents, you can link each Alert to the same
Dashboard, and set a Dashboard lens for each link to specify the Agent associated
with the Alert.
You can set Edit > Change Dashboard Properties > Clear Previous Lens
Setting for a dashboard, to clear the lens each time a user selects that
dashboard. For example, if the Clear Lens option is set for the Overview
Dashboard, when a user returns to the Overview Dashboard from another
Dashboard to which a different lens is applied, that lens is cleared so that the
Overview Dashboard shows data for multiple Agents, as intended.
Dashboard lens settings are part of the navigation history. When you navigate to
a previously viewed Dashboard using the Back button, a lens that was previously
applied is reapplied.
Creating a custom link to a Dashboard

To create a custom link to a Dashboard:
Dashboard.
2 Select the Dashboard object to contain the custom link. These dashboard objects
cannot contain links: Line, Scribble, Connector, and Elbow Connector.
3 With the Dashboard object selected, right-click on the Dashboard object and
select Object Links from the menu. Or, select Properties > Object Links.
The Object Links dialog box opens.
4 Click Add.
The Add Object Link dialog box opens.
5 Select the Dashboard Link radio button.
6 Select a Dashboard from the Dashboard drop-down list and click Choose.
The Select Agent Lens dialog opens.
7 Select a single Agent, or select multiple Agents (click and drag, or CTRL/click) on
which to filter.

» Note You can begin typing an Agent name, hostname, or process name in the
Search field. As you type, the Agent list filters to match what you type.
8 Click OK in the Select Agent Lens dialog, then click OK in the Add Object Links
dialog.
The new Dashboard link appears in the Object Links dialog box.
9 Click OK to exit the Object Links dialog box.

10 Select File > Save to save changes to the Dashboard.
The link is now accessible to users in the Workstation.
Creating custom link to an external Web page

To create a custom link to an external Web page:
Dashboard.
2 Right-click on the Dashboard object and select Object Links from the menu, or
select Properties > Object Links.
3 Click Add. The Add Object Link dialog box appears.
4 Select the Web link radio button.
5 In the Name field, enter a name for the Web link. Keep the name short and
descriptive, because it appears under the Links menu.
6 In the URL field, enter the address of the Web page link.
» Note The URL must be fully specified or it will not work correctly on all
platforms. For example, instead of entering www.wilytech.com, you
must enter http://www.wilytech.com.
Creating and managing custom hyperlinks 107

CA Wily Introscope
7 Click OK.
The new web link appears in the Object Links dialog box.
8 Click OK again to exit the Object Links dialog box.

The link is now accessible to users in the Workstation.
Defining default links

A default link can be accessed by double-clicking it. If a dashboard object
contains only one custom link, that link is automatically treated as the default
link.
» Note There can only be one default link per object.
To specify a link as a default link:
1 In the Console, open the dashboard to edit by selecting Dashboard > Edit
Dashboard.
2 Select the dashboard object that contains the custom link and right-click on the
Dashboard object and select Object Links from the menu, or select Properties
> Object Links.
The Object Links dialog box appears.
3 Select the row that contains the link for which to define a default link for.
4 Click Set As Default.
The defined default link appears in bold in the list in the Manage Links dialog
box.

To change the default link, click on a different link, and click Set As Default.
The default link changes.
To clear the default link, click Clear Default.
5 Click OK.
This quick link can be accessed by a user by double-clicking on the object with
the custom default link.
Editing custom links

You can perform these edits to links:
for a Dashboard link, choose a different Dashboard
for a web link, edit the name or URL
change the link type from Dashboard to Web link
apply a lens to a Dashboard link.
To edit custom links:
Dashboard.
2 Select the Dashboard object to contain the custom link and select Properties >
Object Links, or right-click on the Dashboard object and select Object Links
from the menu.
3 Select the row that contains the link to edit.

4 Click Edit.
Creating and managing custom hyperlinks 109

CA Wily Introscope
The Edit Object Link dialog box opens.
5 Edit the link as appropriate. Click OK.

6 Click OK again to exit the Object Links dialog box.
Removing links
To remove a custom link:
Dashboard.
2 Select the Dashboard object to remove the custom link from and right-click on
the Dashboard object and select Object Links from the menu, or select
Properties > Object Links
3 Select the row that contains the link to delete.

4 Click Remove.
5 Click OK.

CHAPTER
7
Working with Management Modules
This section describes how to add new or updated Management Modules to an

Enterprise Manager. It also describes how to use the Management Module Editor
to configure presentation, detection, and notification logic for managing
Introscope-enabled applications.
This section includes these topics:

About Management Modules . . . . . . . . . . . . . . . 112
Creating and working with Management Modules . . . . . . . . . 113
Configuring metric groupings . . . . . . . . . . . . . . . 119
Monitoring performance with Alerts . . . . . . . . . . . . . 125
Working with Alert Downtime Schedules . . . . . . . . . . . 145
Creating Actions . . . . . . . . . . . . . . . . . . . 150
Using Calculators . . . . . . . . . . . . . . . . . . . 154
Using JavaScript calculators . . . . . . . . . . . . . . . 155
Deploying Management Modules . . . . . . . . . . . . . . 160
Working with Management Modules 111

CA Wily Introscope
About Management Modules

A Management Module contains a set of Introscope monitoring configuration
information. You configure Introscope’s monitoring logic by using Management
Modules and Elements, which organize Metric data in the Workstation.
Management Modules for each domain contain elements. Elements are objects
that contain and organize metric data with monitoring logic, for presentation in
the Workstation. Introscope elements are:
Metric Groupings
Alerts (which includes Simple and Summary Alerts)
Actions (which includes Shell Command, E-mail, and Workstation Actions)
Dashboards
Calculators
Report Templates
SNMP Collections
A Sample Management Module is included in the SuperDomain when you install

Introscope. This Sample Management Module contains pre-configured
dashboards that include commonly used performance-monitoring logic. You must
create other Management Modules for other created domains.
The Introscope Workstation User Guide describes the contents of the sample
Dashboards.
Permissions, domain enforcements and element editing

Agents are partitioned into domains. Users are given access to certain domains,
and can only create Elements and Management Modules that reference data in
domains to which the users belong.
To create or edit Elements in the Workstation, you must have the appropriate
permissions. To perform most changes to Elements, you need write permission
to the Domain in which the Element is contained. Some functions require a
specific permission.
Keep in mind that when creating or modifying an element that elements in

individual domains can only reference other elements in the same Domain.
Elements in the SuperDomain can reference elements in any domain.
For more information about domains and user permissions, see Defining User and
Group Permissions on page 228.
112 Working with Management Modules

Creating and working with Management Modules

Management Modules organize Dashboards and other Elements so that you can
conveniently find, copy, and edit them. Management Modules are stored as .jar
files in your <Introscope_Home>/config/modules directory. They can also
exist in subdirectory domains beneath the <Introscope_Home>/config/
modules directory, if a user defines those domains and the Management Module
.jar beneath them. Management Modules can be moved between Enterprise
Managers—see the Introscope Installation and Upgrade Guide.
A Management Module can be defined as editable/non-editable, or active/

inactive. If a Module is not editable, the Elements within it are also not editable.
If a Management Module is inactive, the Elements within it are also inactive.
Elements in the Management Module Editor

These are the Element names, their associated icons, and descriptions:
Element Name Icon Element Description

and Folder Icon
Container that maps Agents, and holds Management
Modules. User permissions are associated with a
Domain.
Container that holds Elements.
Specifies Actions to be triggered by Alerts.
Notifications of possible problems in your managed

Java Application, generated by comparing Metric
values against user-defined threshold values, and
producing a status.
Sums or averages Metric data to produce custom
Metrics.
Contains Data Viewers, shapes, text, and images.
Grouping that specifies which Metrics to act upon;

used as building blocks for Elements such as Alerts.
Creating and working with Management Modules 113

CA Wily Introscope
Element Name Icon Element Description

and Folder Icon
Contains Introscope report templates.
Part of SNMP Adapter functionality; defines which

collected Metrics are to be included in a published
MIB.
Note: SNMP Collections require the SNMP Adapter,
(purchased separately) for full functionality.
Using hyperlinks in the Management Module Editor

The Workstation Console and Management Module Editor provide hyperlinks
between related items. For example, a Metric in the Management Module Editor
tree contains a link to any Dashboard it is used in.
Links for an item in a Dashboard or the Management Module Editor appear on the
Links menu, with link types separated by a horizontal line. In the Management
Module Editor, links on top of the menu are for Management Module Editor tree
items; links on the bottom of the menu are for Dashboards. In the Console, links
on bottom of the menu are for Management Module Editor tree items; links on
the top are for Dashboards.
Hyperlinks can be viewed in two ways:

right-click on the item in the tree, select the Links submenu
select an item in the tree, select Properties > Links
If no links are available for a selected object, the Links menu is disabled.
Agent expressions for Management Modules

In Introscope, metric groupings (and their agent and metric expressions) filter
data that matches the agent and metric criteria. All metric groupings in a
Management Module can share a single set of Agent Expressions. You can then
specify at the metric grouping level whether to use the shared Agent Expression,
or the metric grouping’s Agent Expressions.
Using Management Module Agent Expressions simplifies monitoring logic

configuration. You can make a change to the Management Module Agent and
Metric expressions, and have it apply to all metric groupings contained within. If
something in your deployment changes (the machine name, for example), it is
easy to make the change at the Management Module level, and it applies to
everything within. Or, you can copy a precisely configured Management Module
and change the Agent Expression to monitor a different Agent.

For simplicity, CA suggests that you either use Management Module Agent
Expressions, or Metric Grouping Agent Expressions, but not a mix of both within
a single Management Module. You might also use only Metric Grouping Agent
Expressions if you want to monitor a specific set of Metrics from a specific set of
Agents.
For steps to specify Agent Expressions in metric groupings, see Configuring

metric groupings on page 119.
Naming Management Modules and elements

These are the rules for naming Management Modules and Elements:
Management Modules within the same Domain must have unique names.
Non-unique Management Module names are allowed in separate Domains.

Same types of Management Module Elements within a single Management
Module must have unique names.
For example, you could have one alert and one calculator, both named “Bytes
In Use,” but you couldn’t have two alerts both called “Bytes In Use.”
Non-unique Management Module Element names can exist, if they are in
separate Management Modules.
For example, you could have two Alerts, both named Servlet Alert A, with one
in the Sample Management Module and one in a Module you created called Test
Module.
To make naming easier, Introscope provides a Force Uniqueness option for

creating and naming a Management Module or Element:
If the Force Uniqueness option is on and you enter a name that is not unique,
Introscope adds a number to the name to make it unique.
The appended number appears after the report template is created, when you
view it in the Management Module Editor.
If the Force Uniqueness option is off and an identical report template name
exists, Introscope displays an error message and does not create the report.

CA Wily Introscope
Creating a new Management Module

To create a new Management Module:
1 From any Workstation window, select Workstation > New Management

Module Editor.
2 In the Management Module Editor window, select Elements > New Management
Module.
3 Enter a name for the Management Module in the Name field (this name appears
in the Management Module Editor tree.)
4 Enter a .jar file name for the Management Module, using alphanumeric characters
without spaces (to comply with all operating systems).
5 In the Domain Name field, use the pull-down menu to select which Domain
contains the Management Module.
6 Click OK.
The Management Module appears in the Management Module Editor tree. Modules
are active and editable when they are created.
Defining Agent expressions for a Management Module

To define Agent expressions for a Management Module:
1 Select the Management Module in the Management Module Editor tree.

The Management Module’s settings appear in the settings pane.
2 Click Add.
A blank Agent Expressions field appears. You can supply Agent Expressions
information, in one of two ways:

Type in the information in a regular expression.
Open another Investigator window, select an Agent or Metric and drag the
information to the Agent Expressions field, so that a the line appears around
the Agent Expressions field. For example:
When you click and drag information into

the Agent Expressions field, the cursor looks
like this.
3 Click Apply.
» Note The Agent Expressions defined here are not automatically applied to
metric groupings within. You must specifically choose to use the
Management Module’s Agent Expressions instead of the Metric
Grouping’s Agent Expressions. For information on this process, see
Configuring metric groupings on page 119.
Copying a Management Module

Copying a Management Module also copies all the Elements in it.
To copy a Management Module:
1 In the Management Module Editor, right-click on a Management Module and

select Copy Management Module <name of Management Module>.
2 Enter a name for the copied Management Module in the Name field.
3 Enter a .jar file name for the Management Module, using alphanumeric characters
without spaces, to comply with all operating systems.
4 In the Domain Name field, use the pull-down menu to select which Domain
contains the Management Module.
5 Click OK.
The new Management Module appears in the Management Module Editor tree. It
is active and editable.

CA Wily Introscope
Deleting a Management Module

Deleting a Management Module deletes all the Elements in it.
To delete a Management Module:
1 In the Management Module Editor, right-click on a Management Module and

select Delete Management Module <name of Management Module>.
2 Click Yes.
Making a Management Module active or inactive

If the Management Module is made inactive, everything it is made inactive.
To make a Management Module active or inactive:
1 Select the Management Module in the Management Module Editor tree.

2 In the settings pane for the Management Module, check or uncheck the Active
box.
3 Click Apply.
Making a Management Module editable or non-editable

If a Module is not editable, the Elements it contains are also not editable. A non-
editable Management Module is identified by a small padlock on its icon in the
Management Module Editor tree:
A padlock icon on a Management Module

means that you cannot edit it.
Custom Management Modules you create are editable, but you can make them
non-editable to prevent others from changing them.
» WARNING Once a Management Module is made non-editable, you cannot

return it to its editable state. For instructions on how to make a
custom Management Module non-editable, see Read-only
Management Modules on page 173.

Configuring metric groupings

When you create metric groupings in the Investigator, you specify the data you
want the metric grouping to display, using regular expression language from Perl
5 in the Metric Grouping Agent Expressions and Metric Expressions fields. These
fields filter data based on the hierarchy that appears in the Investigator tree.
The Metric Grouping Agent Expressions field specifies the data up to and including
the Agent name. The Metric Expressions field specifies the Resource (the chain of
folders leading to the Metric) and the Metric.
To populate these fields, you can either type in the information using Perl 5
regular expressions language, or you can select and drag Metrics and Agents from
the Investigator into the fields.
Agent Expressions can be defined per Management Module. These Agent

Expressions can then be applied to metric groupings within a Management
Module.
By default, every metric grouping uses its own Agent Expressions to match
Agents. If you want instead to use the Agent Expressions from the Management
Module, choose this option in the metric grouping’s settings panel. If you select
this option, the matching Agents automatically change if the Management
Module’s Agent Expressions change.
Metric name structure

A fully qualified Metric name looks like this:
Domain|Hostname|Process|AgentName|Resource:Metric
For example, a fully qualified Metric name of a Metric in a Resource looks like this:
Acme|c1737019-a|AcmeUSA|AcmeWest|GC Heap:Bytes In Use
If a Metric is located within two Resources, the name looks like this:
Acme|c1737019-a|AcmeUSA|AcmeWest|Servlets|FileServlet:Responses
Per Second
If there are deeper Resource layers, Resources are separated by the pipe
character (|).
» Note Users in Domains other than the SuperDomain see the Metric name
without Domain information in the following syntax:
Hostname|Process|AgentName|Resource:Metric. For example:
c1737019|AcmeUSA|AcmeWest|GC Heap:Bytes In Use
Configuring metric groupings 119

CA Wily Introscope
Creating a new metric grouping
Creating a new metric grouping from an existing metric

To create a new metric grouping from an existing metric:
1 Right-click the Metric and select New Metric Grouping from Metric <Name>
from the menu.
2 Accept the default name for the metric grouping.

3 Choose a Management Module to contain the metric grouping in one of these
ways:
Select a Management Module from the drop-down list box
Click Choose, select a Management Module from the list, then click Choose
again
4 Click OK.
The new metric grouping you created is highlighted in the Management Module
Editor tree, under the Management Module in which you saved it.
» Note The metric grouping is active when it is created, and cannot be de-
activated.

In the Settings pane for the metric grouping, Metric Grouping Agent Expressions
and Metric Expressions fields already contain the Metric information.
information about the metric groupings in the Description Text field.
6 Select which Agent Expressions to use:
Select Use Management Module Agent Expressions to use the Agent
Expressions defined for the Management Module
Select Use Metric Grouping Agent Expressions to use Agent Expressions
defined for this metric grouping
7 Click Apply.
Creating a new metric grouping from the Elements menu

To create a new metric grouping from the Elements menu:
1 From any Workstation window, select Workstation > Management Module

Editor.
2 In the Management Module Editor window, select Elements > New Metric
Grouping.
3 In the Name field, enter a name for the metric grouping.
4 Choose a Management Module to contain the metric grouping in one of these
ways:
again.
5 Click OK.

CA Wily Introscope
The metric grouping you just created is highlighted in the Investigator tree, and
its settings appear in the settings pane.
» Note The metric grouping is active when it is created, and cannot be de-
activated.
6 Enter specific Agent and Metric information in the Metric Grouping Agent
Expressions and Metric Expressions fields.
You can enter information in one of these ways:

type in the information in a regular expression
open another Investigator window, select a Metric, and drag the information
to the Metric Groupings window, so that the blue line appears around the
Metric Grouping Agent Expressions and Metric Expressions fields:
When you click and drag information into the

Agent Expressions field, the cursor looks like this.
When you release the mouse button, the Metric Grouping Agent Expressions
and Metric Expressions fields automatically fill with Metric information.
7 Select which Agent Expressions to use:
Select Use Management Module Agent Expressions to use the Agent
Expressions defined for the Management Module.
Select Use Metric Grouping Agent Expressions to use Agent Expressions

defined for this metric grouping.

8 Click Apply.
Adding another Metric To a metric grouping

To add another Metric to appear in a metric grouping:
1 In the Metric Grouping settings pane, click Add.

This adds another Agent/Metric Expressions field pair to accept the second
Metric’s information.
2 Launch another Investigator window.
3 In the second Investigator window, select the Metric you want the new metric
grouping to display, drag it to the settings pane, and this time drop it on the
Metric Grouping Agent Expressions field.
4 Reselect the metric from the second Investigator window, and drag it onto the
Metric Expressions field.
Customizing metric groupings

If you require more customized information than that achieved from dragging and
dropping data, you can customize the regular expressions in the metric grouping
by editing the Metric Grouping Agent Expressions and Metric Expressions fields
to specify the Metrics to match.
To customize metric groupings:
1 If you need to edit the definition, follow these rules:

Separate the successive levels of the Investigator tree with backslash-pipe
symbols. (The backslash acts as an escape character.)
In Metric Grouping Agent Expressions: Host\|Process\|AgentName

CA Wily Introscope
Use ([^\|:]*) to represent one Resource segment.
In Servlets\|([^\|:]*):Average Response Time $ms$

An escape character (backslash) is required for separators and parentheses \|
and $and $.
In Servlets\|Servlet1:Average Response Time $ms$
To match several things with one expression, you can include lists of things
between parentheses using pipe characters.
In Servlets\|Servlet(1|14|18):Average Response Time $ms$.
If there are no Resource folders between the AgentName and the Metric, enter
only the Metric name. Otherwise, separate the Resource folders with
backslash-pipe symbols and precede the Metric name with a colon (:).
In Metric Expressions: resource\|subresource:Metric
In Metric Expressions: resource:Metric
In Metric Expressions: Metric
For example, in Metric Expressions you specify the average JDBC query time
for a servlet called OptionReport as Servlets\|OptionReport\|JDBC:Average
Query Time.
Use (.*) to represent “any.”
For example, Cherubim\|PhoneHome\|(.*) followed by Sockets:Output

Bandwidth would specify the output bandwidth for all sockets for any
instance of the process PhoneHome running on the host Cherubim.
An entry of File System:(.*) in the Metric Expressions field means that the
data to be displayed is the file input and output Metrics found in the
Investigator under File System. In contrast, File System:File Input Rate
displays the file input rate only.
Use (.*)\|(.*)\|(.*) in the Agent field to make the metric grouping display
data from any server, any process, and any Agent. Or, you can specify any
or all of the segments to match Agents with a given host, process and/or
Agent name.
2 If necessary, click Add to specify additional metrics for the metric grouping.
3 Click Apply.

Monitoring performance with Alerts

There are two types of Alerts: Simple and Summary.
A Simple Alert takes status information produced by a comparison as input,
compares it to user-defined threshold values, and outputs a status.
A Summary Alert bases its status on the status of multiple Simple Alerts and
other Summary Alerts.
Both types of Alerts appear together under the Alerts node in the Investigator
tree.
About simple alerts

A Simple Alert takes status information produced by a comparison as input,
compares it to user-defined threshold values, and outputs a status. A Simple
Alert has one of four states:
Not reporting data—this could happen if the Simple Alert is not matching any
Metrics, if the Metrics it is matching are not reporting (perhaps because they
are shut off), or if the Simple Alert itself is inactive
Green (OK)
Yellow (Caution)
Red (Danger)
You can define Actions to be triggered for Caution and/or Danger states. Simple
Alerts can use Danger and Caution Action Delays (SmartTrigger functionality) to
determine when to initiate specified Actions.
The Simple Alert is the foundation Alert in Introscope. Simple Alerts can trigger
Actions and notifications, or can provide input for a Summary Alert.
Creating Simple Alerts

There are two ways to create a Simple Alert in the Workstation:
Select the data (a metric, metric grouping, or resource), and create a Simple
Alert from the data
» Note If you create a Simple Alert from a metric, a metric grouping with the
same name as the Simple Alert is automatically created.
Create a Simple Alert from the Elements menu, then add the Metric information
using regular expressions
Monitoring performance with Alerts 125

CA Wily Introscope
Creating a Simple Alert from existing data
These instructions describe creating a Simple Alert by first selecting data (a

metric grouping), then creating a Simple Alert using the right-click context menu.
1 In the Management Module Editor tree, right-click on the metric grouping from
which to create the Simple Alert. From the menu, select New Simple Alert from
Metric Grouping <Name>.
2 In the Name field, enter a name for the Simple Alert. The Management Module
is the same one that the metric grouping belongs to.
information about the alert in the Description Text field.
4 Click OK.
Proceed to the section, Configuring Simple Alert settings on page 127, to
configure specific Simple Alert settings.
Creating a Simple Alert from the Elements menu
To create a new Simple Alert from the Elements menu:
1 In the Management Module Editor window, select Elements > New Alert > New
Simple Alert.
2 In the Name field, enter a name for the Simple Alert.
3 Choose a Management Module to contain the Simple Alert in one of these ways:
again.
4 Click OK.

The Simple Alert you just created is highlighted in the Management Module Editor
tree, and its settings appear in the settings pane.
Selecting a Metric Grouping to Supply Data to the Simple Alert
When you create a Simple Alert, a metric grouping with the same name as the
Simple Alert is automatically created. You can either:
Customize the newly created metric grouping with regular expression
information (follow the instructions in the section Configuring metric groupings
on page 119).
Choose an existing metric grouping to supply data for this Simple Alert
(described here).
To select a metric grouping to supply data to the Simple Alert:
1 In the Metric Grouping area, choose a metric grouping to supply data to the
Simple Alert:
Select a metric grouping from the drop-down list.
Click Choose, select a metric grouping from the list, then click Choose again.
2 If you are finished, click Apply to apply the changes.

Otherwise, proceed to the next section to configure specific Simple Alert settings.
Configuring Simple Alert settings

After creating a Simple Alert (see Creating Simple Alerts on page 125), you
define the conditions under which it is triggered.

CA Wily Introscope
To configure Simple Alert settings:
1 If the Simple Alert settings is not already visible, locate the Simple Alert you just
created in the Management Module Editor tree, under the Management Module
into which you placed it. Click on the Simple Alert to select it and display its
settings.
2 In the settings pane, check the Active checkbox to activate the Simple Alert.
Check the Active box

to activate the Alert.

3 Configure and save the Simple Alert settings:
Field Setting
Resolution Select or enter a time period resolution in hours, minutes, or
seconds.
A Simple Alert uses input data from a selected metric grouping. For
the time resolution you select, Introscope gathers information and
summarizes a value for that time period. The resulting value
depends on the type of data in the Metric. For example, if the
Metric is a rate, the summarized value is the average rate during
that time period. Or if the Metric is a counter, it produces the most
recent value of the counter.
Note: Time resolution values must be in 15-second increments.
Combination Choose a value from the drop-down list:
any—a Simple Alert is triggered when one Metric goes over a
threshold
all—a Simple Alert is triggered only when all Metrics go over a
threshold
Note: The Combination field is ignored when the Notify by
individual Metric box is checked.
Comparison Choose a value from the drop-down list for the condition that
Operator triggers the Simple Alert, either Less Than, Greater Than, Equal
To, or Not Equal To.
The Comparison Operator, along with Danger and Caution
Threshold values, defines the condition that trigger the Simple
Alert.
The Comparison Operator relates to the Danger and Caution
threshold values. For example, if you want to be notified when an
average servlet response time is greater than 5000, you would use
the “greater than” operator. The Comparison operator also affects
the Caution and Danger Threshold values. If the Comparison
operator is set to greater than, the Danger Threshold value must
be greater than the Caution Threshold value. Conversely, if the
Comparison operator is set to less than, the Danger Threshold
value must be less than the Caution Threshold value.
Notify by Select to trigger individual Metric Alerts. You can use the Individual
individual Metric Alert Notification and Resolution Alert together.
metric The Notify by Individual Metric feature (also called Metric Level
Alert) configures Introscope to trigger a Simple Alert status when
an individual Metric crosses a user-defined threshold. This is
helpful if you create a Simple Alert on a metric grouping and use
this option—you only need to set up one Simple Alert, and you can
receive individual Simple Alerts for each individual metric in the
metric grouping.
Notifications are sent as if there were separate Simple Alerts for
each Metric, so be aware that multiple Alerts/Resolutions are
possible in the same period.

CA Wily Introscope
Field Setting
Trigger Alert Choose an option from the drop-down list:
Notification Each Period While Problem Exists—produces a problem
message every period that the Simple Alert is in Caution or
Danger.
When Severity Increases—produces a problem message on
any period when the state of the Simple Alert escalates from
Normal to Caution, from Normal to Danger, or from Caution to
Danger. This is the default state for the Simple Alert.
Whenever Severity Changes (Resolution Alert)—produces
problem and/or resolution messages on any state transition. For
example, a change of state of the Simple Alert from Danger to
Caution would produce a resolution message (Danger status has
been resolved) and a problem message (the Caution status is still
a problem). This type of resolution Alert produces a resolution
message if the state changes from Caution or Danger.
Report Only Final State Whenever Severity Changes
(Resolution Alert)—produces a problem or resolution message
only for the final state of an Alert transition. For example, for a
change from Danger to Caution, the Simple Alert would trigger
only a problem message for the final state, which is Caution. This
type of resolution Alert produces a resolution message only if the
state goes to Normal.
For more alert notification information, see About Alert Notification
options, messages, and exceptions on page 140.
Danger Area Settings
Danger Enter the value that triggers a Danger Alert.
Threshold Danger Thresholds specify when Simple Alerts are to be triggered.
The units in the Danger Threshold values correspond to the value
used in the metric grouping. For example, if you are making a
Simple Alert for Servlet Average Response Time, the value is
milliseconds. You set Danger Thresholds in conjunction with the
Comparison Operator.
Sustained Alert Settings
Sustained Alert settings allow you to configure the Alert to only
trigger if a Danger status is sustained over one or more time
periods.
Using this option, the Alert is not triggered until the metric
grouping(s) cross the danger threshold X times in Y periods.
At least n of the Enter the number of instances of the status of Danger that would
last n periods trigger Alert notification.
Actions Add Actions as described in Adding actions on page 132.

Field Setting
Action Delay Enter the delay in hours, minutes, and seconds.
Note: When using the Resolution Alert option, Danger Action
delay is not available.
Danger Action Delays (also known as SmartTrigger functionality),
determine when a Simple Alert Action is triggered.
To prevent being flooded by Simple Alert notifications when values
remain in or re-enter a danger region, enter delay for Danger
Action Delay. The Action is not repeated until the delay time has
elapsed. For more information on SmartTrigger functionality, see
Alerts and the SmartTrigger feature on page 140.
Caution Area Settings
Caution Enter the value that triggers a Caution Alert.
Threshold Caution Thresholds specify when Simple Alerts are to be triggered.
The units in the Caution Threshold values correspond to the value
used in the metric grouping. For example, if you are making a
Simple Alert for Servlet Average Response Time, the value is
milliseconds. You set Caution Thresholds in conjunction with the
Comparison Operator.
Sustained Alert Settings
Sustained Alert settings allow you to configure the Alert to only
trigger if a Caution status is sustained over one or more time
periods.
Using this option, the Alert is not triggered until the metric
grouping(s) cross the caution threshold X times in Y periods.
At least n of the Enter the number of instances of the status of Caution that is to
last n periods trigger Alert notification.
Actions Add Actions as described in Adding actions on page 132.
Caution Action Enter the delay in hours, minutes, and seconds.
Delay Caution Action delays (also known as SmartTrigger functionality),
determine when a Simple Alert Action is triggered.
To prevent being flooded by Simple Alert notifications when values
remain in or re-enter a caution region, enter delay for Caution
Action Delay. The Action is not repeated until the delay time has
elapsed. For more information on SmartTrigger functionality, see
Alerts and the SmartTrigger feature on page 140
Note: When using the Resolution Alert option, Caution Action
delay is not available.

CA Wily Introscope
Adding actions
Add Actions to occur when the Alert Comparison condition is met (when a caution
or danger threshold value has been exceeded). You can add an Action for either
or both of the Danger or Caution conditions. You can also create multiple Actions
for the same condition.
» Note If you define both a Caution and a Danger Threshold Action for a Simple
Alert, and a Simple Alert status goes directly from normal (green) to
danger (red) during a defined time period, only Danger Actions are
triggered.
To add an action:
1 Under either Danger Actions or Caution Actions, click Add.
2 Select an Action and click Choose.

3 Add another Action if appropriate.
4 In the Simple Alert settings pane, click Apply (in the bottom left corner).
The Simple Alert is complete, and appears in the tree under the Management
Module you placed it in.
» Note When creating a Simple Alert from a metric, a metric grouping is created
automatically when a Simple Alert is created. It is in the same
Management Module as the Simple Alert you just created.

Activating an Action
The default actions included with Introscope (and any new Actions created from
this dialog) must be activated before first use.
To active an action:
1 In the Management Module Editor tree, find and select the Action you just defined
(or created) for the Simple Alert. Notice it is grayed out because it is not yet
active.
2 In the Action’s settings pane, check the Active checkbox to activate the Action.
3 Click Apply.
About Summary Alerts

A Summary Alert provides a way to show the status of multiple underlying Simple
Alerts with one overall status.
A Simple Alert has one of four states—not reporting, green, yellow, and red.
Because the Summary Alert state is defined as the worst state among the Simple
Alerts it contains, Summary Alerts have no explicit danger or caution thresholds
or comparison expressions, as with Simple Alerts.
To understand the relationship between the states of the underlying Simple Alerts
and the containing Summary Alert, consider an example Summary Alert, which
includes two Simple Alerts—GC Heap Alert, and Connection Pool Alert.
The following table defines alert states:
State Icon Definition Numeric Value

Red Danger 3
Yellow Caution 2
Green Normal 1
Gray Not Reporting 0
Red with a black circle in Danger, but in a downtime -3
the middle period, and still be reported.
Yellow with a black circle Caution, but in a downtime -2
in the middle period, and still be reported.
Green with a black circle Normal, but in a downtime -1
in the middle period, and still be reported.

CA Wily Introscope
Summary Alerts and time periods of underlying Simple Alerts

Summary Alerts do not have a user-defined time period for checking the current
state of each underlying Simple Alert. The Summary Alert period is automatically
configured as the minimum period of any included Simple Alerts. There are two
possible cases:
All Alerts have the same time period—There is no delay between the
evaluations of any of the Alerts on the latest Metric data.
All Alerts have different time periods—The Summary Alert still evaluates its
own state on its own period, using the most recently calculated state from each
of the Alerts it depends on. For example, if Summary Alert A depended upon
Alert X (30 second period) and Alert Y (45 second period), then every 30
seconds, Summary Alert A would determine its state based upon the current
states of Alert X and Alert Y using whatever states they had most recently
calculated for their own periods.
If the underlying Simple Alerts have different time periods, the minimum
period is used as the Summary Alert time period. This works well if the
underlying Simple Alerts have time periods that are relatively close together.
However, with underlying Simple Alerts with a wide variance of time periods,
this can lead to old or stale states in which the user might expect the Summary
Alert to be Green, but because of a Simple Alert with a long period, it might
have a state reflective of a time far back in the past.
For example, if a Summary Alert (Application Health) depends upon a Simple
Alert (WebServerSlow) which has a time period of one hour, then the Summary
Alert could show a state that is triggered by the WebServerSlow state, which
could be as old as an hour. If the WebServer was slow one hour ago, but
corrected itself 50 minutes ago, the real application state might be apparent
as Green/OK, but the WebServerSlow Simple Alert might still be Red, and by
extension the Summary Alert, Application Health, is still red.
The best way to prevent this situation from occurring is to compose Summary
Alerts of Simple Alerts whose time periods are the same or at least close
together.
Summary Alert notes

Note these caveats about Summary Alerts:
Summary Alerts can contain Simple Alerts and other Summary Alerts
Summary Alerts are only viewable with the alert status indicator Data Viewer
Including a Simple Alert in a Summary Alert does not disable any notification
Actions the Simple Alert might have. If a notification Action is defined at both
the level of the Simple Alert and the level of the Summary Alert, it is possible
to get multiple notifications with duplicate information for the same problem.

Therefore, you might want to disable the actions in the Simple Alert if you don’t
want duplicate notifications for the same problem.
Creating a Summary Alert

To create a Summary Alert:
1 In the Management Module Editor window, select Elements > New Alert > New
Summary Alert.
2 In the Name field, enter a name for the Summary Alert.
» Note Since Summary Alerts and Simple Alerts appear together under the
Alerts node, it might be helpful to name the Summary Alert to distinguish
it from a Simple Alert.
3 Choose a Management Module to contain the Summary Alert in one of these

ways:
again.
4 Click OK.
The Summary Alert you created is highlighted in the Management Module Editor
tree, and appears in the settings pane.
5 In the settings pane, check the Active checkbox to activate the Summary Alert.
Check the Active box to

activate the Summary Alert.
Use the arrows to include

alerts in the Summary. You
can include both Simple and
Summary Alerts.

CA Wily Introscope
6 Specify the alerts to be included in the Summary alert, by selecting one or more
alerts and using the arrows to move them from the Available list to the Included
list:
> moves a single selected alert into the Included list

>> moves all sample alerts into the Included list
< removes a single selected alert from the Included list
<< removes all sample alerts from the Included list
Both Simple and Summary alerts appear in the list of available alerts. Basing a
Summary alert on other Summary alerts enables you to build high-level alerts.
For example, you can create a high-level summary alert that incorporates system
health alerts into one overall system health alert.
» Note Do not define two Summary alerts that are inputs for one another. The
resulting recursive effect produces unpredictable results.
7 Configure the Summary Alert settings.
Field Setting
Trigger Alert Select a Trigger Alert Notification state for Any Alert or All
Notification Alerts. The Any Alert option will take the maximum state of all
the alerts and the All Alerts option will take the minimum state
of all the alerts having a state of more than 0 (not reporting).
For example if you have a summary alert that consists of the
following alerts:
Alert: A State: 0
Alert: B State: 1
Alert: C State: 1
Alert: D State: 2
Alert: E State: 3
The Any Alert option will take 3 and the All Alerts option will
take 1.
The trigger state determines how the Summary Alert behaves:

Field Setting
Trigger Alert Each Period While Problem Exists—produces a problem
Notification message every period that the Summary Alert is in Caution or
(cont.) Danger.
When Severity Increases—produces a problem message on
any period when the state of the Summary Alert escalates from
Normal to Caution, from Normal to Danger, or from Caution to
Danger. This is the default state for the Summary Alert.
Whenever Severity Changes (Resolution Alert)—produces
problem and/or resolution messages on any state transition. For
example, a change of state of the Summary Alert from Danger
to Caution would produce a resolution message (Danger status
has been resolved) and a problem message (the Caution status
is still a problem). This type of resolution Alert produces a
resolution message if the state changes from Caution or
Danger.
Report Only Final State Whenever Severity Changes
(Resolution Alert)—produces a problem or resolution message
only for the final state of an Alert transition. For example, for a
change from Danger to Caution, the Summary Alert would
trigger only a problem message for the final state, which is
Caution. This type of resolution Alert produces a resolution
message only if the state goes to Normal.
Resolution Alert Information
You need to know when a Summary Alert status goes to a Caution
or Danger status, and it is also helpful to know when that Caution
or Danger status has decreased in severity (has been resolved.)
The Resolution Alert can be set to notify you when:
a Summary Alert status changes to Caution or Danger
a Summary Alert status changes from Caution or Danger
For more alert notification information, see About Alert
Notification options, messages, and exceptions on page 140.

CA Wily Introscope
Field Setting
Danger Area Settings
Alerts Add Actions as described in Adding an Action, below.
Action Delay Enter the delay in hours, minutes, and seconds.
Danger Action delays (also known as SmartTrigger functionality)
determine when a Summary Alert Action is triggered.
To prevent being flooded by Summary Alert notifications when
values remain in or re-enter a danger region, enter delay for
Danger Action Delay. The Action is not repeated until the delay
time has elapsed. For more information on SmartTrigger
functionality, see Alerts and the SmartTrigger feature on
page 140.
Note: When you use the Resolution Alert option, Danger Action
Delay is not available.
Caution Area Settings
Actions Add Actions as described in Adding an Action, below.
Caution Action Enter the delay in hours, minutes, and seconds.
Delay Caution Action delays (also known as SmartTrigger functionality)
determine when a Summary Alert Action is triggered.
To prevent being flooded by Summary Alert notifications when
values remain in or re-enter a caution region, enter delay for
Caution Action Delay. The Action is not repeated until the delay
time has elapsed. For more information on SmartTrigger
functionality, see Alerts and the SmartTrigger feature on
page 140.
Note: When you use the Resolution Alert option, Caution Action
Delay is not available.
Adding an Action
Add Actions to occur when the aggregate Summary Alert status is Danger or
Caution. You can add an Action for either or both of the Danger or Caution
conditions. You can also create multiple Actions for the same condition.
» Note If you define both a Caution and a Danger Threshold Action for an Alert,
and an Alert status goes directly from normal (green) to danger (red)
during a defined time period, only Danger Actions are triggered.

To add an action:
1 Under either the Danger Actions or Caution Actions, click Add.

2 Select an Action and click Choose.
3 Add another Action if needed.
4 In the Summary Alert settings pane, click Apply (in the bottom left corner).
The Summary Alert is complete, and appears in the tree under the Management
Module in which you placed it.
Activating Actions
The default actions included with Introscope (and any new Actions created from
this dialog) must be activated before they are used for the first time.
To activate an Action:
1 In the Investigator tree, select the Action you just defined (or created) for the
Alert.
It is grayed out, because it is not yet active.
2 In the Action’s settings pane, check the Active checkbox to activate the Action.
3 Click Apply.
Summary Alert notifications

Summary Alert notifications do not include any Metric data; they include this
information:
timestamps
the name of the Summary Alert
the state the Summary Alert is in
a list of the underlying Simple Alerts that triggered the current state of the
Summary Alert
This is an example of the format of a Summary Alert notification message:

4/13/04 12:31:45 PM PST
The Summary Alert "Application Health" is in the danger state due to:
SuperDomain/<Acme>|<SimpleAlertName1> is in danger
SuperDomain/<Acme>|<SimpleAlertName2> is in caution
SuperDomain/<Acme>|<SimpleAlertName3> is normal
SuperDomain/<Acme>|<SimpleAlertName4> is not reporting

CA Wily Introscope
About Alert Notification options, messages, and exceptions

Alert Notification options determine when a Simple Alert or a Summary Alert
notification is triggered and what type of information message is generated by
Introscope.
A Simple Alert or a Summary Alert status generates two types of information

messages—a problem message and a resolution message.
This information can be output (through a Shell Command Action, for example)
to an external enterprise control panel (such as CA Unicenter). The four Alert
notification options produce a combination of these messages under different
conditions.
» Note An Action must be defined for the Simple Alert or Summary Alert in order
to output the problem/resolution message information.
These exceptions affect when a resolution Alert is generated:

When you configure a Simple Alert or a Summary Alert to be a resolution Alert,
the resolution Alert behavior does not take effect until the next Summary Alert
time period.
If you are editing a Simple Alert or a Summary Alert, resolution Alert
notifications based on the new information won’t be generated until you click
Apply.
If you shut down the Enterprise Manager, Resolution Alert notifications are not
generated.
Resolution Alert notifications are not generated for Simple Alerts or Summary
Alerts on Metrics/Agents that disconnect or stop reporting.
Alerts and the SmartTrigger feature

SmartTrigger functionality (through Danger and Caution Action delays)
determines the conditions under which danger or caution statuses are reported
by a Comparison result in an Action. SmartTrigger functionality prevents you
from being flooded by Alert notifications. It acts like a snooze button for Alert
notifications, enabling you to set a delay between the first Alert notification and
subsequent notifications.

Using SmartTrigger to delay Actions
Danger Alert Notifications received with 30-second alert setting
Imagine a situation where you have your Alert time period set for 30 seconds. If
the information generates a Danger Alert status and you defined an Action for it,
the Action is triggered. Without SmartTrigger set, if the Danger status continues,
you are notified every time the Danger Threshold is exceeded, as shown in this
illustration.
Alert time period= 30 seconds

No Action Delays set
Action Action Action Action Action Action Action Action

Danger
Threshold
30s 1m 2m 3m 4m 5m 6m
Caution
threshold
As the illustration shows, you would be notified eight times over this short period.
Danger Alert Notifications received with SmartTrigger settings
Because problems usually cannot be resolved in such a short time period as 30

seconds, it makes sense to delay the subsequent Actions with an Action delay.
For example, with the same 30 second Alert time period, if you set a five minute
Action delay for the Danger status, you receive the first Alert notification at the
30-second mark as usual.

CA Wily Introscope
However, if the Danger status occurs again during that five-minute Action
blackout period, and the Danger threshold is still exceeded when the blackout
period ends, you are not notified by a second Action until five minutes after the
first notification, as this illustration shows:

Danger Action delay= 5 minutes
Action Action
Danger
Threshold
30s 1m 2m 3m 4m 5m 6m
Caution
threshold
Action delay period
Using the SmartTrigger when severity increases option

Sometimes you only want to be notified when an Alert status worsens, such as
changing from normal to caution, or from caution to danger. To do this, use the
When Severity Increases option in the Trigger Alert Notification field.
Let’s go back to the previous example. You might only want to be notified if the
status worsens to danger, not if it exceeds the danger threshold and stays there.

This illustration shows what happens with a Danger Action delay of five minutes,
and the When Severity Increases option selected:

Danger Action delay= 5 minutes
When Severity Increases Notification Option
Action
Danger
Threshold
30s 1m 2m 3m 4m 5m 6m
Caution
threshold
Action delay period
In this example, you wouldn’t receive a Danger Alert notification at the 5.5
minute mark as in the previous illustration, because the values are on a decline—
the status is improving.
Generating Alert state Metrics

You can configure Introscope to create metrics that represent the trinary state of
all alerts in an Enterprise Manager. This enables you to view live and historical
views of Alert states in the Workstation and in WebView.
Alert state Metrics can be used in custom views, such as:

a graph of Alert state over time, correlated with other graphed Metrics
a chart showing the percentage of time an Alert spent in each Alert state over
a period of time
When you delete or rename an Alert, the old metric for it is grayed out.
You can view Alert state metrics in the Investigator (see Alert state metrics in the
Investigator) and in the Management Module Editor (see Alert state metrics in the
Management Module Editor).

CA Wily Introscope
Alert state metrics in the Investigator

In the Investigator, Alert state metrics appear in the virtual agent (calculator
agent) for each Domain defined in the Enterprise Manager, under the Alerts node.
Alert state metrics in the Investigator are classified by numbers. For more
information about the states, see About Summary Alerts on page 133.
This example shows the All EJB Response Time metric in a state of 3—Danger:
Alert-state metrics appear in the Investigator in the virtual agent (calculator

agent) for each Domain defined in the Enterprise Manager, under the Alerts node:
Alerts|[management module name]:[alert name]
» Note You can configure a different Metric name for the node that contains Alert
state Metrics in the Enterprise Manager properties file, using the
property introscope.enterprisemanager.alertstatemetric.prefix.
Alert state metrics in the Management Module Editor

In the Management Module Editor, Alert state metrics appear as an alert status
indicator, showing the states of green (OK), yellow (Caution), and red (Danger).
This example shows a red alert status indicator for the all Agent Connection
Status metric; it is in a state of Caution:

Working with Alert Downtime Schedules

Alert Downtime Schedules let you manage downtime periods from the Introscope
Workstation Management Module Editor.
An Alert Downtime Schedule can be associated with one or more alerts. It also
provides a convenient way of associating alerts in one or more management
modules. While any action associated to an alert will not occur during a downtime
period, the alert status will still be reported. For more information, see About
Summary Alerts on page 133.
This feature is also capable of handling overlapping downtime periods that affect
the same alert. For example if you have two downtimes scheduled that affect the
same alert, the system is sophisticated enough to know this and maintain the
down time.
For example, if there is a downtime scheduled for Monday 8 AM to 10 AM, which

affects Alert A, and additionally there is another downtime scheduled for Monday
9:30 AM to 10:30 AM that affects the same Alert A, then the system will
continuously maintain the downtime. Thus the system will remain down from 8
AM through 10:30 AM without any glitches.
Creating an Alert Downtime Schedule

To create a new alert downtime schedule:
1 From the Management Module Editor, choose Elements > New Alert
Downtime Schedule.
2 Enter a name for the alert downtime schedule in the Name field.
3 The Force Uniqueness check box is selected by default to ensure that the Alert
Downtime Schedule names are unique within a within a Management Module. If
you create a new schedule with a name already in existence, the system will
append a number to the name to force uniqueness. Deselect this check box to
turn off this option.
4 Choose a Management Module from drop-down menu or click Choose to enter a
search string.
5 Click OK.
The new Alert Downtime Schedule will appear highlighted in the Management
Module editor tree and its definitions will appear in the Settings tab in the lower
editor pane:
Working with Alert Downtime Schedules 145

CA Wily Introscope
You can select the Description tab to enter information about the alert or the
Settings tab to define the alert time downtime settings. For more information,
see Defining Alert Downtime Schedules on page 146.
Defining Alert Downtime Schedules

Define these settings after you create an alert downtime schedule (see Creating
an Alert Downtime Schedule on page 145) or from selecting an existing alert
downtime schedule from the editor tree and selecting the criteria in the Settings
tab:
To define alert downtime schedule:
1 In the Name field enter or rename the existing Alert Downtime Schedule.
2 Select the Active check box to make the make the Alert Downtime Schedule
active.
3 Select a Management Module from the drop-down menu or click Choose to enter
a search string.
4 Select one of the following scheduling options:
Simple Schedule–allows you to schedule weekly, monthly, and daily one time
or recurring alerts that can be set to start and end at a specific time.
Cron Schedule–a Unix scheduling tool that uses expressions. While this tool
provides a wide range of capabilities, the values entered in the fields need to
be precise. For more information, see Using Cron to Schedule Alert Downtimes
on page 146.
5 Select the Alerts or Management Modules option to pick from a list of alerts
or Management Modules to which you wish to apply the settings.
You can apply settings only to alerts in your Management Module. This is done as
a safeguard measure, so alerts aren’t inadvertently deactivated.
6 Click Apply to or Revert to
Using Cron to Schedule Alert Downtimes

Cron is a powerful UNIX tool that provides a variety of scheduling capabilities. It
uses expressions that can trigger alerts that apply rules such as "8:00am every
Monday through Friday" or "1:30am every last Friday of the month".
Use it by selecting the Cron Schedule option when you define alert downtime
schedules (For more information, see Defining Alert Downtime Schedules on
page 146):
Cron expressions can be as simple as: * * * * * ? *

or, a complex as: 0 0/5 14,18,3-39,52 ? JAN,MAR,SEP MON-FRI 2002-2010
For more sample expressions, see Cron Sample Expressions on page 148.
The following table lists the values and special characters that are allowed in the
Cron Schedule fields:
Field Name Required Values Special Charactersa

Minutes yes 0-59 , -* /
Hours yes 0-23 , -* /
Day of Month yes 1-31 , -* ? / LW C
Month yes 1-12 or JAN-DEC , -* /
Day of Week yes 1-7 or SUN-SAT , -*?/LC#
Year no empty, 1970-2099 ,-*/
aFor more information about special characters, see Cron Special Charac-
ters on page 147.
Cron Special Characters
The following table lists the Cron special characters and their meanings.
Special Definition
Character
* Selects all values within a field. For example, "*" in the minute
(all values) field means "every minute".
? Specifies something in one of the two fields in which the

(no specific value) character is allowed, but not the other. For example, if I want
my trigger to fire on a particular day of the month (say, the
10th), but don't care what day of the week that happens to be,
I would put "10" in the day-of-month field, and "?" in the day-
of-week field. See the examples below for clarification.
- Specifies ranges. For example, "10-12" in the hour field means
"the hours 10, 11 and 12"
, Specifies additional values. For example, "MON, WED, FRI" in the
day-of-week field means "the days Monday, Wednesday, and
Friday".
/ Specifies increments. For example, "0/15" in the seconds field
means "the seconds 0, 15, 30, and 45". And "5/15" in the
seconds field means "the seconds 5, 20, 35, and 50". You can
also specify '/' after the '*' character - in this case '*' is
equivalent to having '0' before the '/'. '1/3' in the day-of-month
field means "fire every 3 days starting on the first day of the
month".

CA Wily Introscope
Special Definition
Character
L Specifies the last of something. This special character has a
(last) different meaning in the two fields for which it is allowed: Day
of Month and Day of Week. For example, the if you insert an
L in the Day of Month field, it means the last day of the month,
which would be day 31 for January, day 28 for February on non-
leap years. If used in the day-of-week field by itself, it simply
means "7" or "SAT". But if used in the day-of-week field after
another value, it means "the last xxx day of the month" - for
example "6L" means "the last friday of the month". When using
the 'L' option, it is important not to specify lists, or ranges of
values, as you'll get confusing results.
Note: The 'L' and 'W' characters can also be combined in the
day-of-month field to yield 'LW', which translates to "last
weekday of the month".
W Specifies the weekday (Monday-Friday) nearest the given day.
(weekday) As an example, if you were to specify "15W" as the value for the
day-of-month field, the meaning is: "the nearest weekday to the
15th of the month". So if the 15th is a Saturday, the trigger will
fire on Friday the 14th. If the 15th is a Sunday, the trigger will
fire on Monday the 16th. If the 15th is a Tuesday, then it will fire
on Tuesday the 15th. However if you specify "1W" as the value
for day-of-month, and the 1st is a Saturday, the trigger will fire
on Monday the 3rd, as it will not 'jump' over the boundary of a
month's days. The 'W' character can only be specified when the
day-of-month is a single day, not a range or list of days.
# Specifies "the nth" XXX day of the month. For example, the value
of "6#3" in the day-of-week field means "the third Friday of the
month" (day 6 = Friday and "#3" = the 3rd one in the month).
Other examples: "2#1" = the first Monday of the month and
"4#5" = the fifth Wednesday of the month. Note that if you
specify "#5" and there is not 5 of the given day-of-week in the
month, then no firing will occur that month.
c This means values are calculated against the associated
(calendar) calendar, if any. If no calendar is associated, then it is equivalent
to having an all-inclusive calendar. A value of "5C" in the day-of-
month field means "the first day included by the calendar on or
after the 5th". A value of "1C" in the day-of-week field means
"the first day included by the calendar on or after Sunday".
Cron Sample Expressions
The following table lists the Cron special characters and their meanings.
Expression Meaning
0 0 12 * * ? Trigger an alert at 12pm (noon) every day
0 15 10 ? * * Trigger an alert at 10:15am every day

Expression Meaning
0 15 10 * * ? Trigger an alert at 10:15am every day
0 15 10 * * ? Trigger an alert at 10:15am every day

0 15 10 * * ? 2005 Trigger an alert at 10:15am every day during the year 2005
0 * 14 * * ? Trigger an alert every minute starting at 2pm and ending at

2:59pm, every day
0 0/5 14 * * ? Trigger an alert every 5 minutes starting at 2pm and ending at

2:55pm, every day
0 0/5 14,18 * Trigger an alert every 5 minutes starting at 2pm and ending at
* ? 2:55pm, AND fire every 5 minutes starting at 6pm and ending at
6:55pm, every day
0 0-5 14 * * ? Trigger an alert every minute starting at 2pm and ending at
2:05pm, every day
0 10,44 14 ? 3 Trigger an alert at 2:10pm and at 2:44pm every Wednesday in

WED the month of March.
0 15 10 ? * Trigger an alert at 10:15am every Monday, Tuesday,

MON-FRI Wednesday, Thursday and Friday
0 15 10 15 * ? Trigger an alert at 10:15am on the 15th day of every month
0 15 10 L * ? Trigger an alert at 10:15am on the last day of every month
0 15 10 ? * 6L Trigger an alert at 10:15am on the last Friday of every month
0 15 10 ? * 6L Trigger an alert at 10:15am on the last Friday of every month

0 15 10 ? * 6L Trigger an alert at 10:15am on every last friday of every month
2002-2005 during the years 2002, 2003, 2004 and 2005
0 15 10 ? * Trigger an alert at 10:15am on the third Friday of every month

6#3
0 0 12 1/5 * ? Trigger an alert at 12pm (noon) every 5 days every month,

starting on the first day of the month.
0 11 11 11 11 Trigger an alert every November 11th at 11:11am.

?

CA Wily Introscope
Creating Actions
An Action is caused by an Alert, and defines what happens when an Alert is
triggered.
Introscope provides three standard Action types:

Workstation Notification Action displays an Alert notification on all running
Workstations connected to the Enterprise Manager—see Creating a
Workstation Notification Action, below.
Shell Command Action runs a shell script residing on the Enterprise Manager
machine—see Creating a Shell Command Action on page 151.
SMTP Email Action sends an e-mail to the recipient(s) specified in its settings—
see Creating an SMTP Email Action on page 153
Introscope includes two default Actions in the Sample Management Module: SMTP
Email Notification and Workstation Notification. They must be configured and
activated to be used.
Creating a Workstation Notification Action

The Workstation Action type displays an Alert notification on all running
Workstations connected to the Enterprise Manager. This is the simplest Action
type, because it doesn’t require any other systems or setup to work. The Alert
notification looks similar to this:
To create a new Workstation Notification Action:
1 In the Management Module Editor, select Elements > New Action > New
Workstation Notification Action.
2 Name the Action and select a Management Module to contain it.

3 Check the Active box to activate the Action.
Check the Active box to

activate the Alert.
4 Click Apply.
5 Click Test Now to see the result of the Action (the Action must be active).
This example shows a test of a Workstation Notification Action.
» Note The Test Now button produces a test result only for the last applied
Action.
Creating a Shell Command Action

The Shell Command Action type runs a shell script residing on the Enterprise
Manager machine. The Action can pass a short text message to the script,
describing the reason why the Alert was triggered—for example:
4:05:15 PM PST Introscope Enterprise Manager (aardvark:192.168.0.45)

reported: The Alert My App Heap Bytes In Use Alert was triggered because
the value 841904 exceeded danger target of 800000 for Acme|c1737019-
a|AcmeUSA|AcmeWest|GC Heap:Bytes In Use"
To create a new Shell Command Action:
1 In the Management Module Editor, select Elements > New Action > New Shell
Command Action.
3 Select the Force Uniqueness check box to make the name unique within a
Management Module.
4 Choose a Management Module from the drop-down menu or click Choose to enter
a search string and narrow the list of options.
5 Click OK.

CA Wily Introscope
The Shell Command Action Settings pane appears:
6 Choose a Management Module to contain the Shell Command Action:

Select a Management Module from the drop-down list box, or
again.
7 Check the Active checkbox to activate the Action.
8 Enter the name of the shell command in the Shell Command field.
9 Enter an optional parameter that needs to be passed to the shell command In the
User-defined parameter field.
10 Click Test Now to see the result of the Action.
Action.
11 Select the Command Parameters option to pick from a list of command

parameters which you want to be included during shell script execution.
The command parameters are added by selecting the parameter from the
Available Command Parameters list and clicking the > button. All the
command parameters can be added by clicking the >> button.The command
parameters are removed by selecting the command parameters from the
Included Command Parameters list and clicking the < button. All the
command parameters can be removed by clicking the << button.
12 Click Apply to apply the changes or Revert to revert back to the original values.

Creating an SMTP Email Action

The SMTP Email Action type sends an e-mail to the recipient(s) specified in its
settings. This Action type requires access to an SMTP e-mail server that the
Enterprise Manger can connect to.
This Action type could send an e-mail to several places:

a regular e-mail address
an already-defined mail list
a pager gateway, which can trigger a person’s pager
a management system that can take the e-mail text as input and trigger an
Action
To create a new SMTP Email Action:
1 In the Management Module Editor, select Elements > New Action > New SMTP
Email Action.
3 Check the Active checkbox to activate the Action.
4 Enter the return address of the e-mail message in the From: field.
5 Enter the recipient name in the To: field (can be a single e-mail address, or
multiple addresses separated by commas)
6 Enter the name of the SMTP host in the SMTP Host field.
7 Select Send Short Message to send an abbreviated version of the notification
message, for bandwidth-sensitive channels such as a pager.
8 Click Apply.
9 Click Test Now to see the result of the Action.
Action.

CA Wily Introscope
Using Calculators
Calculators take the values from a metric grouping as input, average or sum the
values, and output the resulting value as a custom metric in the Investigator tree.
Metrics generated by calculators appear under a virtual process, Custom Metric
Process, running on a virtual host, Custom Metric Host.
Creating Calculators
To create a calculator:
1 In the Management Module Editor, select Elements > New Calculator.

2 Name the calculator, and choose a Management Module to contain the calculator:
again.
3 Click OK.
The calculator you created is highlighted in the Management Module Editor tree,
with its settings shown in the settings pane.
You must specify a metric grouping to supply data to the calculator. When the
calculator was created, a metric grouping was automatically created with the
same name as the calculator. However, the metric grouping must be customized
before it can supply data to the calculator—see Configuring metric groupings on
page 119.
4 To choose another metric grouping:
Select a metric grouping from the drop-down list box.
Click Choose, select a metric grouping from the list, then click Choose again.
» Note Choose a metric grouping that provides integer values—calculators

cannot accept non-integer values as input. Mixed types produce
unexpected results.
5 From the Operation menu, choose average or sum to determine the Action to
perform on the input from the metric grouping.
6 If you are creating a Sum calculator, from the Metric Type menu select the Metric
type for the calculator, either counter or interval counter. Use an interval counter
when the calculator is to create a sum of interval counts; otherwise, use counter.
7 In the Destination field, specify a name for the Metric to label the calculator’s
output:
To have the Metric appear in a Resource folder instead of directly under
Custom Metrics, specify the Resource name, followed by a colon (:), followed
by the Metric name.

To specify a chain of nested Resource folders, separate the Resource names by

pipe symbols (|). You do not need to use an escape character with these pipe
symbols.
name of resource|name of resource:name of Metric
8 Click Apply.
Calculators and weighted averages

Introscope calculators that produce Metrics based on averages are based on
weighted averages, not straight averages. This is especially useful when
monitoring the performance of your application in a clustered environment, so
you have an accurate response time between multiple servers that are likely to
have different load levels.
For example, if you have a calculator that generates a Metric from the average
response time for five servlets, a straight average would add up the response
time for a defined time period, and divide by five. A weighted average would give
more weight to the servlets that were called more often, giving a more accurate
average.
Using JavaScript calculators

A JavaScript calculator reads input metrics and produces output metrics
according to calculations specified in a user-created JavaScript text file. The new
calculated Metrics can appear in the Investigator tree under the Virtual Custom
Agent, or in any node of the Investigator tree, according to the output metric that
is specified in the calculator script.A calculated metric can be shut off, but the
calculator producing it does not know about the shutoff state.
The Enterprise Manager JavaScript engine allows you hot-deploy JavaScript

calculators to a running Enterprise Manager.
Writing JavaScript calculators

JavaScript calculator files must end with a .js extension and reside in the
Enterprise Manager’s scripts directory. Sample JavaScript calculator files are
provided in the examples/scripts/ directory of your Enterprise Manager
installation.
JavaScript calculators specify input metrics and produce one or more output
metrics.
Using JavaScript calculators 155

CA Wily Introscope
The execute ( ) Function

Each calculator must have an execute() function that takes two arguments.
Additionally, helper functions are available to help build metrics to send back the
Enterprise Manager. The syntax is:
function execute(metricData,javascriptResultSetHelper)
where
metricData—is an array of Metric Data supplied to the function when it is called

at every 15 seconds before execute() intervals
javascriptResultSetHelper—is an object that collects the new metric data
produced by the script and sends them back to the EM
kDefaultFrequency - is used as input to the frequency argument of the
addMetric() helper function
kIntegerConstant - maps to the integer constant metric type
kIntegerFluctuatingCounter - maps to the integer fluctuating counter metric
type
kLongConstant - maps to the long constant metric type
kLongFluctuatingCounter - maps to the long fluctuating counter metric type
kLongTimestamp - maps to the long timestamp metric type
kLongTimestampConstant - maps to the long timestamp constant metric
type
kIntegerPercentage - maps to the integer percent metric type
kIntegerDuration - maps to the integer duration metric type
kLongDuration - maps to the long duration metric type \
kLongIntervalCounter - maps to the long interval counter metric type
kStringIndividualEvents - maps to the string metric type
addMetric(metricName, count, value, min, max, metricType, frequency) -
supports setting the count/value/min/max of a metric value, which is
needed for the rate and interval count metric types, where the "value" of the
metric is based on its "count"
getCustomMetricAgentMetric(agentMetric) - helps build a fully qualified
metric name using the agent metric supplied and filling in the rest based on
the name of the SuperDomain custom metric agent
The execute() function is called every 15 seconds by the scripting engine.

Specifying input Metrics

The calculator script can specify the input Metrics that it receives in one of two
ways:
The easiest way to specify input metrics is with a pair of methods: function
getAgentRegex() which returns a string containing a regular expression to
match agents and function getMetricRegex() which returns a string containing
a regular expression to match metrics.
You can also use the method function getMetricSpecifier() which returns a
Metric Specifier.
» Note The regular expressions created as strings in function getAgentRegex()

and function getMetricRegex() must use character escaping differently
than other regular expressions you use in Introscope—for example, in
metric groupings or in the Search view. Any Java escape characters that
are returned from these JavaScript functions must also be escaped in the
JavaScript. So, for example, '\|' must be escaped as '\\|' in the
JavaScript.
Global variable log

All JavaScript calculator functions have access to a global variable log, which is
of type IModuleFeedbackChannel. For example:
function execute(metricData,javascriptResultSetHelper) {
log.info("message");
log.error("message");
log.debug("message");
}
» Note If you want to use advanced JavaScript features or are concerned with
ECMA compliance, note that the script engine embeds the Mozilla Rhino
JavaScript library, version 1.6_R1.
Creating output metric data

Creating output metric data requires:
Metric name—consisting of the agent plus the full path to the appropriate node
in the metric tree.
The metric name can be created based on the incoming data, in which case
the new calculated data appears along with that agent's other metric data,
or
A new calculator metric name can be specified, to show the calculated metric
data in its own node in the metric tree.
Data value—calculated by the script.

CA Wily Introscope
Result data type—specified by a constant value from the class

com.wily.introscope.spec.metric.MetricTypes.
Reporting Frequency—The frequency at which the new metric data is reported
to the Enterprise Manager, which can be obtained from the incoming data, or
specified explicitly. You can change this to a multiple of the Enterprise
Manager's default frequency (15 seconds).
A typical calculated value from a script looks like this:
javascriptResultSetHelper.addMetric(metricName,
heapUsedValue,Packages.com.wily.introscope.spec.metric.MetricTypes.kInte
gerFluctuatingCounter,frequency)
» Note Specify regular expressions with care, as they can potentially match any
Metrics you produce. For instance, a regular expression of "EJB.*Time.*"
could insert a new value under EJB. (that is, inserting a new value under
"EJB" when you have a regex on "EJB.*Time.*"). You can either change
your regular expression to do this, or remove metric data from your own
metrics.
Running JavaScript Calculators on the MOM

You can run a JavaScript calculator on the MOM to produce metrics for the MOM's
Custom Metric Agent. While it cannot produce metrics for agents that are
connected to a Collector, it can see input metrics from agents in the Collectors.
If a calculator is added, modified, or deleted in a clustered environment, the MOM

will automatically propagate the change to all Collectors unless you turn off the
automatic update for collectors. For more information, see Turning off the
automatic update for Collectors on page 159.
The runOnMOM function

A JavaScript calculator that should not run on the MOM must implement a
runOnMOM function that returns false, such as in the following example:
// return false if the script should not run on the MOM

// default is true.
function runOnMOM()
{
return false;
}
If the runOnMOM function returns true or is not implemented, the JavaScript

calculator will run on the MOM.

Reducing the number of logged metric creation errors

If a calculator runs on the MOM and creates a metric for an agent that exists in
the Collectors, there is a one-time logging of the event at the WARN level, such
as in the following example:
5/15/07 02:32:20 PM PDT [WARN] [Manager.MetricCalculatorBean] Calculator

Registered Metric <ID=7, JavaScript calculator
C:\workspaces\workspaceKrakatau\com.wily.introscope.em.feature\rootFi
lesMOM\.\scripts\HeapUsedPercentage.js>. A JavaScript calculator in
the MOM cannot output metric data to an agent that exists in a
Collector: SuperDomain|rhart-dt1|EPAgentProcess1|EPAgent15|GC
Heap:Heap Used (%) 5/15/07 02:32:20 PM PDT [WARN]
[Manager.MetricCalculatorBean]
Subsequent events are logged only at the DEBUG level.
Adding a JavaScript calculator

To install a new JavaScript calculator, copy the JavaScript text file into the
<Introscope_Home>/scripts directory of your Enterprise Manager installation.
You can use another directory for scripts; if you do, specify the directory using
the introscope.enterprisemanager.javascript.dir property.
Scripts are automatically deployed from this scripts directory at the frequency
specified by the introscope.enterprisemanager.javascript.refresh property, which
by default is 60 seconds.
After successful deployment, the new Metrics appear in the Investigator tree.
Turning off the automatic update for Collectors

Clustered environments are automatically set to propagate an added, modified,
or deleted JavaScript calculator to all Collectors. However, you could turn this
feature off if you did not want the calculators propagated.
To turn off the automatic update for Collectors:
1 Open the Enterprise Manager property file.

2 Change the value setting to false:
introscope.enterprisemanager.javascript.hotdeploy.collectors.ena
ble=false
3 Verify the change has been applied by viewing the
JavaScriptCalculatorsMOM.properties file in the
<Introscope_Home>\config\internal\server\scripts directory.

CA Wily Introscope
Deploying Management Modules

This section provides information about adding new or updated Management
Modules to an Enterprise Manager. You can deploy Management Modules without
restarting the Enterprise Manager using the Hot Deploy Service (see Using the
Management Module Hot Deploy Service on page 161). However, it is
recommended that you do not use this mechanism on production Collectors or
MOMs. For more information, see Management Module Hot Deployments to Avoid
on page 161
To deploy new or updated management modules, you place them in a deploy

directory, which the Enterprise Manager polls periodically. When the Enterprise
Manager detects new Management Module files in the deploy directory, it
automatically deploys them to the Introscope SuperDomain.
If you have multiple Introscope domains and want to deploy Management

Modules selectively, create a subdirectory for each target domain within the
deploy directory. The Enterprise Manager polls any subdirectories of the deploy
directory, and deploys Management Modules it finds to the domain corresponding
to the subdirectory name.
When you deploy a Management Module that includes links to elements in

another Management Module, you must deploy the Management Module that
contains the target elements as well.
» Note By default, if a Management Module contains references to another

management module which has not been deployed you will receive a
startup warning notification. The warning will be logged in the
IntroscopeEnterpriseManager.log file located in
<Introscope_Home>/logs directory and will contain detailed
information to help you troubleshoot and resolve the issue. To change
the default system behavior, you can update the property in the
IntroscopeEnterpriseManager.properties file. For more
information, see Management Module Bootstrapping on page 270.
Copying Management Modules

If you copy a Management Module from one Enterprise Manager to another, the
copy is independent of the original Management Module—subsequent edits you
make to the original Management Module are not replicated in the copy.
Updating deployed Management Modules

Before deploying an update to a Management Module, delete the existing
Management Module before deploying the updated version of the Management
Module .jar file.

Using the Management Module Hot Deploy Service

Use the Hot Deploy Service with certain Management Modules, but do not
perform Management Module hot deployments on production Collectors or MOMs.
For more information, see Management Module Hot Deployments to Avoid on
page 161.
To use the Management Module hot deployment, copy the Management Module
.jar file or files into the <Introscope_Home>/deploy directory, or a Domain-
specific subdirectory of the deploy directory, as appropriate.
The Management Modules are deployed at the next polling interval which, by
default, occurs within 60 seconds. The Management Module .jar file is:
copied to the config/modules folder
backed up in the config/modules-backup folder
deleted from the deploy directory
The deployment is logged in the Enterprise Manager log.
Management Module Hot Deployments to Avoid

Do not perform Management Module hot deployments on production Collectors or
MOMs. It will lock the system and prevent the metric data from being reported.
Because the hot deployment of virtual agents and Management Modules is CPU
intensive, it can lock up Collectors for a couple of minutes during which metric
harvest does not happen. This can happen if you change the virtual agent
definitions or redeploy Management Modules in the MOM or Collector; the
consequence can be that the cluster stops responding to Workstation users for
extended periods. Based on this, we strongly recommend not doing Management
Module hot deployments in production environments.
You may perform a hot deployment during development and when developing
Management Modules. However, if you are working with a large fully loaded
Enterprise Manager or a large cluster, avoid performing a Management Module
hot deployment, as it is likely that the system will stop responding.
For more information about Virtual Agents, see the Introscope Java Agent Guide.
Deploying Management Modules 161

CA Wily Introscope

CHAPTER
8
Using the Command-Line Workstation
This chapter describes the Introscope Command Line Workstation (CLW), a

command-line interface to the Introscope Enterprise Manager, and includes these
topics:
About the Command Line Workstation (CLW) . . . . . . . . . . 164
Running the CLW . . . . . . . . . . . . . . . . . . . 164
CLW command reference . . . . . . . . . . . . . . . . 167
Sample scripts . . . . . . . . . . . . . . . . . . . . 202
Using the Command-Line Workstation 163

CA Wily Introscope
About the Command Line Workstation (CLW)

The Introscope Command Line Workstation (CLW) is available for performing
some of the Introscope Workstation functions.
The CLW is useful for automating or scheduling Introscope operations tasks. For
example, you can perform repetitive tasks such as disabling multiple alerts in
several Management Modules more quickly with the CLW than with the
Workstation interface. Similarly, the CLW is useful for scheduling tasks that need
to be performed automatically or on a periodic basis.
Using CLW commands you can:

Manage Management Modules and Elements—You can list, copy, rename,
and delete Management Modules and Elements, see if they are active, and
change their current state.
You can create Management Modules and Elements based on existing ones,
using CLW copy and rename commands. You cannot, however, create
Management Modules and Elements from scratch, or modify their details using
the CLW.
Control Agents—You can start, stop, and resume agent reporting remotely,
and copy configuration files to remote agents.
Start Transaction Trace Sessions—You can write scripts to automatically
start a Transaction Trace Session as a result of alert conditions.
Shut Down the Enterprise Manager—You can write scripts to shut down the
Enterprise Manager on scheduled basis. For example, you might want to stop
the Enterprise Manager during off-hours, when using the Workstation might be
inconvenient.
If the CLW exits—CLW exits with a 0 value if nothing goes wrong. It will exit
with a negative status code if one of the following happens:
EM authentication failure.
Connection problem with the EM such as a dropped network connection, or
invalid host name.
There is an invalid WS and EM.
Running the CLW

This section is an overview of how to run the CLW. For information on specific
commands, see CLW command reference on page 167.
JVM requirements
The CLW requires JVM 1.5 or later.
164 Using the Command-Line Workstation

Where to run CLW commands

You can include CLW commands in script or batch files, or enter them at the
command line. The CLW .jar file is installed in the <Introscope_Home>/lib
directory. Run CLW commands from that directory, or include the path to the
directory in the commands.
Using CLW interactive mode

You can change from the default mode to interactive mode by using the -i flag,
such as in the following example. If you plan on writing scripts for CLW, this mode
cannot be used, as it will break them.
java -Xmx128M <EM_logon> <TT_properties> -jar CLWorkstation.jar >

usage | -i | <command>
Interactive mode will read command line arguments for a command, execute,
then exit. However, if no command line arguments are passed, other than JVM
options like -DHost=, then it will read and execute one line of standard input and
will continue to do so until it reaches the end of the file is reached or you exit the
system. If no arguments are passed, and no input is provided, an error will be
printed and it will exit the system. All lines that begin with the # symbol will be
ignored.
Invoking CLW
CLW command syntax is:
java –Xmx128M < EM_logon> -jar CLWorkstation.jar <command>
Where:
–Xmx128M sets the Java heap size, preventing
java.lang.OutOfMemoryError errors that might otherwise occur.
<EM_logon> is your Enterprise Manager logon information:
-Duser=<user name>
–Dpassword=<password>
–Dhost=<Enterprise Manager host / ip address>
–Dport=<Enterprise Manager port number>
<command> is one of the commands described in the CLW command reference
on page 167.
For example:
java –Xmx128M -Duser=jdoe –Dpassword=mypassword –Dhost=jdoeDT
–Dport=5001 -jar CLWorkstation.jar <command>
Running the CLW 165

CA Wily Introscope
Default logon values for accessing the Enterprise Manager are used if you invoke
the CLW without supplying your logon information:
java –Xmx128M -jar CLWorkstation.jar <command>
Every CLW command you enter at the command line or in a script must start with
the CLW invocation:
java –Xmx128M -jar CLWorkstation.jar
» Note To avoid getting a java.lang.OutOfMemoryError, set the Java heap

size.
CLW is case-sensitive
CLW commands accept arguments that specify agents, Management Modules,
and other named items in your Introscope deployment. CLW is case-sensitive—
you must enter the names of Introscope objects exactly as they are named. For
example, if an agent is named WebLogic1, a CLW command that refers to
weblogic1 does not execute for that agent.
CLW command output

CLW commands return their output to the command window. You can direct
command output to a file, as appropriate.
CLW and regular expressions

You can use CLW commands to manipulate elements of your Introscope
environment, such as agents, Management Modules, Dashboards, actions, and
alerts. Depending on the type of target, you can perform operations such as copy,
list, rename, activate, and deactivate.
You designate the target or targets of a CLW command using exact text strings
or Perl regular expressions. For example, this CLW command lists all agents
connected to the Enterprise Manager:
list agents matching (.*)
This command lists only agents whose name contains the string weblogic:
list agents matching .*weblogic.*

Backslashes and quotes in CLW commands

When you supply CLW command arguments that contain spaces, surround the
argument with quotation marks ("), and include a backslash in front of each
quotation mark, to prevent the shell from interpreting the quotation mark. For
example:
\"2005/01/01 12:20:37\"
Using CLW in different environments

Regular expression syntax varies depending on your operating system and
command shell, and in some cases, based on whether you enter the expression
at the command line or in a script. The sample commands in this chapter are
written for a Windows environment, and reflect the syntax required to use regular
expression in a batch file.
CLW command reference

These sections define CLW commands and syntax:
Enterprise Manager commands on page 167
Introscope Agent commands on page 169
Management Module commands on page 171
Read-only Management Modules on page 173
Alert commands on page 177
Alert Downtime Schedule commands on page 180
Calculator commands on page 182
Dashboard commands on page 184
Metric Grouping commands on page 187
Report Templates Commands on page 188
SNMP Collections commands on page 193
Starting a Transaction Trace session on page 196
» Note The syntax shown for each command does not include the invocation
portion of the command. As described in Invoking CLW on page 165,
each CLW command must begin with: java -jar CLWorkstation.jar
Enterprise Manager commands

The Enterprise Manager aggregates application performance data from agents,
runs requested calculations, makes performance data available to authorized
clients, and stores performance data.
CLW command reference 167

CA Wily Introscope
Shut down Enterprise Manager

This command shuts down the Enterprise Manager. To run it, you must have
shutdown or full permission. Any Workstation users connected to the Enterprise
Manager are logged off when you shut down the Enterprise Manager.
Syntax: shutdown
Example: shutdown
Output: None
Extract persistent data (time range)

This command extracts historical data for a specified time period from SmartStor.
You supply a regular expression that specifies the agents, a regular expression
that specifies the metric groups, and the start and end of the time period. The
hh:mm:ss portion of the date-time string is optional—if you do not supply it, the
default is 00:00:00 (midnight).
Syntax: get historical data from agents matching <REGULAR

EXPRESSION> and metrics matching <REGULAR EXPRESSION>
between <YYYY-MM-DD [hh:mm:ss]> and <YYYY-MM-DD
[hh:mm:ss]>
Syntax: get historical data from agents matching [REGULAR
EXPRESSION] and metrics matching [REGULAR EXPRESSION]
for past [EXACT MATCH] (minute|minutes) with frequency
of [EXACT MATCH] (second|seconds|sec|secs|s)
between \”2004-10-12 00:00:00\” and \”2004-10-12
00:00:01\” with frequency of [EXACT MATCH]
(second|seconds|sec|secs|s)
Example: get historical data from agents matching “.*weblogic.*”
and metrics matching \“Servlets:Average Response Time
$ms$\” between \”2004-10-12 00:00:00\” and \”2004-10-
13 00:00:00\”
This command extracts the persisted data for the Servlets:Average
Response Time $ms$ Metric Grouping, for all Agents whose name
includes the string weblogic, for the time period from midnight on
October 12, 2004 through midnight on October 12, 2004.
Output: The data is returned in comma-separated value (CSV) format.

Extract persistent data

(previous N minutes with frequency of N seconds)
This command extracts historical data for a specified number of minutes prior to
execution of the command, at a specific frequency, in seconds. You supply a
regular expression that specifies the Agents, a regular expression that specifies
the Metric Groups, and the number of minutes of history to be extracted, and the
frequency at which to extract the data.

for past [EXACT MATCH] (minute|minutes) with frequency
of [EXACT MATCH] (second|seconds|sec|secs|s)
Example: get historical data from agents matching “.*weblogic.*”
and metrics matching \“Servlets:Average Response Time
$ms$\” for past 5 minutes with frequency of 60 seconds
This command extracts the persisted data for the Servlets:Average
Response Time $ms$ Metric Grouping, for all Agents whose name
includes the string weblogic, for the past five minutes, every 60
seconds.
Output: The data is returned in comma-separated value (CSV) format.
Specify a pathname for authentication

Syntax: Dkeyfile=<file name>
Example: Specifies the full pathname for a public key file to use instead of
username/password authentication when connecting to the Enterprise
Manager. The public key used is the same one used for Manager of
Managers/Collector authentication.
Output: none
Introscope Agent commands

An Agent runs as a part of the managed application on the Java Application
machine. It collects and summarizes the Probe-reported data and sends it to the
Enterprise Manager.
List Agents
The List Agents command lists one or more Agents that are connected to the
Enterprise Manager. You supply a regular expression that determines which
Agents are listed.
Syntax: list agents matching <REGULAR EXPRESSION>

CA Wily Introscope
Example: list agents matching (.*)

This command lists all Agents that are connected to the Enterprise
Manager.
Output: Each Agent is listed, prefixed by its Host and Process. Virtual Agents are
included in the list. For example:
jdoe-dt|Weblogic|WebLogicAgent
Custom Metric Host (Virtual)|Custom Metric Process
(Virtual)|Custom Metric Agent (Virtual)
Turn on Agents
This command starts or resumes Metric reporting from one or more Agents. You
supply a regular expression that specifies the target Agents.
Syntax: turn on agents matching <REGULAR EXPRESSION>

Example: turn on agents matching (.*)
This command turns on all Agents.
Output: None
Turn off Agents

This command stops Metric reporting from one or more Agents. You supply a
regular expression that specifies the target Agents.
Syntax: turn off agents matching <REGULAR EXPRESSION>

Example: turn off agents matching (.*)
This command turns off all Agents.
Output: None
Send configuration file

This command sends a specified file to one or more Agents. You supply the name
of the file, a regular expression that specifies the target Agents, and the source
and destination directories.
Target Agents must be configured to allow remote writes in their

introscope.agent.remoteagentconfiguration.enabled property. The
location and its default values vary. For more information, see the Java Agent
Guide or .NET Agent Guide.
You can only copy files explicitly specified in the Agent’s

introscope.agent.remoteagentconfiguration.allowedfiles property.

The default value of this property is domainconfig.xml, which is the file that
contains all the information that Wily Introscope needs to recognize transactions
for Wily CEM. For more information about the Wily CEM integration with
Introscope, see the Wily CEM Integration Guide.
Syntax: send config file <EXACT MATCH> to agents matching

<REGULAR EXPRESSION> to destination dir <EXACT MATCH>
where:
config file is the file to send. A fully qualified path can be
provided; otherwise, the location is resolved relative to the current
working directory.
destination dir is relative to the <Agent_Home> directory.
Example: send config file c:\cem\domainconfig.xml to agents
matching (.*) to destination dir .
Output: None
Management Module commands

Management Modules organize Elements in the Workstation, making them easier
to find and manipulate. CLW commands for Management Modules simplify the
process of moving a a Management Module and the Elements it contains from one
Enterprise Manager to another.
List Management Modules

The List Management Module command lists one or more Management Modules.
You supply a regular expression that specifies the Management Modules.
Syntax: list management modules matching <REGULAR EXPRESSION>

Example: list management modules matching (.*)
This command lists all Management Modules.
Output: The name of each Management Module is listed:
Sample
Sample13
Sample11
Query Management Modules

The Query Management Module command lists Management Modules and their
current state: active or inactive. You supply a regular expression that specifies
the target Management Modules.
Syntax: query state of management modules matching <REGULAR

EXPRESSION>

CA Wily Introscope
Example: query state of management modules matching (.*)

This command returns the name and state of all Management Modules.
Output: The name and state of each Management Module is listed:
Sample1:Active
Sample2:Active
Activate Management Modules

The Activate Management Module command activates one or more Management
Modules. You supply a regular expression that specifies the target Management
Modules.
Syntax: activate management modules matching <REGULAR

EXPRESSION>
Example: activate management modules matching (Sample.*)
This command activates Management Modules whose name begins with
Sample.
Output: The name and state of each Management Module that was activated by
the command is listed:
Sample1:Active
Sample2:Active
Deactivate Management Modules

The Deactivate Management Module command deactivates one or more
Management Modules. You supply a regular expression that specifies the target
Management Modules.
Syntax: deactivate management modules matching <REGULAR

EXPRESSION>
Example: deactivate management modules matching (Sample.*)
This command deactivates Management Modules whose
name begins with Sample.
Output: The name and state of each Management Module that was deactivated
by the command is listed:
Sample1:Inactive
Sample2:Inactive
Copy Management Module

The Copy Management Module command creates a copy of a Management Module
in the <Introscope_Home>/config/modules directory.

This command is an efficient way to create one or more new Management

Modules that are based on existing Management Modules. For example, to create
a new Management Module that is identical to an existing one, except for its
Metric Group, you copy it using the CLW, and then modify the new Management
Module’s Metric Group in the GUI Workstation.
In the Copy Management Module command, you identify the Management Module
you want to copy, a name for new Management Module, and a name, excluding
the file extension, for the .jar file for the new Management Module.
Syntax: copy management module named <EXACT MATCH> to <EXACT

MATCH> in file <EXACT MATCH>
Example: copy management module named Sample to Sample1 in file
SampleManagementModule1
This command makes a copy of the Management Module named
Sample, and saves it with the name Sample1 in
SampleManagementModule1.jar.
Output: None
Delete Management Module

The Delete Management Module command deletes a Management Module. You
supply the exact name of the Management Module you want to delete.
Syntax: delete management module named <EXACT MATCH>

Example: delete management module named Sample1
This command deletes the Management Module named Sample1; the
SampleManagementModule1.jar file is deleted from the
<Introscope_Home>/config/modules directory.
Output: None
Read-only Management Modules

This command sets Management Modules that match a specified regular
expression to read-only.
» WARNING The CA Wily Technology Division recommends that you save a

version of your editable Management Module to a safe location for
future use. Once a Management Module is set to read-only, you
cannot return it to an editable state.
To set Management Modules to read-only, use this command:
set readonly management modules matching <regular expression>

CA Wily Introscope
Then log into the Workstation, open the Management Module Editor and note that
management modules matching the regular expression have a lock icon next to
them, have the Editable checkbox unchecked—changes to these Management
Modules are no longer allowed.
» Note This feature is intended for use by Wily Technology Division partners.
Please contact Wily Technology Division Customer Support before using
this feature in your environment.
Action Commands
An Action is a behavior, such as a notification, that can be triggered by an Alert.
List Actions
The List Actions command lists one or more Actions in one or more Management
Modules. You supply two regular expressions—one that specifies the Actions, and
one that specifies the Management Modules.
Syntax: list actions matching <REGULAR EXPRESSION> in

management modules matching <REGULAR EXPRESSION>
Example: list actions matching (.*) in management modules
matching (.*)
This command lists all Actions in all Management Modules.
Output: Each Action is listed, prefixed by the Management Module that contains
it:
Sample.SMTP Email Action
Sample10.Workstation Notification
Sample2.Workstation Notification
Activate Actions
The Activate Actions command activates one or more Actions in one or more
Management Modules. You supply two regular expressions—one that specifies the
Actions to activate, and one that specifies the Management Modules in which to
activate them.
Syntax: activate actions matching <REGULAR EXPRESSION> in


Example: activate actions matching (SMTP.*) in management

modules matching (.*)
This command activates Actions that begin with the string SMTP in all
Management Modules.
Output: Each Action activated by the command is listed, prefixed by the
Management Module that contains it, suffixed by its activation state:
Sample.SMTP Email Action:Active
Sample10.Workstation Notification:Active
Sample2.Workstation Notification:Active
Deactivate Actions
The Deactivate Actions command deactivates one or more Actions in one or more
Actions to deactivate, and one that specifies the Management Modules in which
to deactivate the Actions.
Syntax: deactivate actions matching <REGULAR EXPRESSION> in

Example: deactivate actions matching (SMTP.*) in management
This command deactivates Actions that begin with the string SMTP in all
Management Modules.
Output: Each Action deactivated by the command is listed, prefixed by the
Management Module that contains it, suffixed by its activation state:
Sample.SMTP Email Action:Inactive
Sample10.Workstation Notification:Inactive
Query Actions
The Query Actions command lists the state—active or inactive—of one or more
Actions in one or more Management Modules. You supply two regular
expressions—one that specifies the Actions, and one that specifies the
Management Modules.
Syntax: query state of actions matching <REGULAR EXPRESSION> in


CA Wily Introscope
Example: query state of actions matching (.*) in management

This command queries the state of all Actions in all Management
Modules.
Output: Each Action is listed, prefixed by the Management Module that contains
it, suffixed by its state:
Sample.SMTP Email Action:Inactive
Rename Action
The Rename Action command renames an Action. You specify the name of the
Action and the Management Module that contains it, and a new name for the
Action.
Syntax: rename action named <EXACT MATCH> in management module

named <EXACT MATCH> to <EXACT MATCH>
Example: rename action named \"Workstation Notification\" in
management module named Sample2 to \"ICU Notification\"
This command renames the Action named Workstation
Notification in the Management Module named Sample2 to ICU
Notification.
Output: None
Delete Action
The Delete Action command deletes one or more Actions from one or more
Actions, and one that specifies the Management Modules from which to delete
them.
» Note You cannot delete an Action that is used or referenced by another

Element—for example, one that is linked to an Alert.
Syntax: delete actions matching <REGULAR EXPRESSION> in

Example: delete actions matching (.*Email.*) in management
modules matching Sample
This command deletes Actions whose name contains the string Email
from the Management Module named Sample.
Output: None

Alert commands
An Alert indicates potential problems in your managed Java Application by
comparing Metric values to user-defined threshold values.
List Alerts
The List Alerts command lists one or more Alerts in one or more Management
Modules. You supply two regular expressions—one that specifies the Alerts, and
one that specifies the Management Modules.
Syntax: list alerts matching <REGULAR EXPRESSION> in management

modules matching <REGULAR EXPRESSION>
Example: list alerts matching (.*) in management modules
matching Sample
This command lists the Alerts in the Management Module named
Sample.
Output: Each Alert is listed, prefixed by the Management Module that contains it:
Sample.Console Summary Alert
Sample.All Servlet Response Time
Sample.All EJB Response Time
Activate Alerts
The Activate Alerts command activates one or more Alerts in one or more
Alerts to activate, and one that specifies the Management Modules in which to
activate those Alerts.
Syntax: activate alerts matching <REGULAR EXPRESSION> in

Example: activate alerts matching (.*) in management modules
matching Same2
This command activates all of the Alerts in the Management Module
named Sample2.
Output: Each Alert activated by the command is listed, prefixed by the
Management Module that contains it, and suffixed by its state:
Sample2.Application Summary Alert:Active
Sample2.SQL Average Processing Time #2 (ms):Active
Sample2.CPUApp1:Active

CA Wily Introscope
Deactivate Alerts
The Deactivate Alerts command deactivates one or more Alerts in one or more
Alerts to deactivate, and one that specifies the Management Modules in which to
deactivate those Alerts.
Syntax: deactivate alerts matching <REGULAR EXPRESSION> in

Example: deactivate alerts matching \".*Availability$\" in
management modules matching (.*)
This command deactivates Alerts whose name ends with the string
Availability, in all Management Modules.
Output: Each Alert deactivated by the command is listed, prefixed by the
Sample13.Web Server Availability:Inactive
Query Alerts
The Query Alerts command lists the state—active or inactive—of one or more
Alerts in one or more Management Modules. You supply two regular expressions—
one that specifies the Alerts, and one that specifies the Management Modules.
Syntax: query state of alerts matching <REGULAR EXPRESSION> in

Example: query state of alerts matching (.*) in management
This command queries the state of all Alerts in all Management Modules.
Output: Each Alert is listed, prefixed by the Management Module that contains it,
suffixed by its state.
Sample10.SQL Average Processing Time (ms):Active
Sample11.All JSP Response Time:Active
Sample10.Idle Servlet Thread Count:Active

Rename Alert
The Rename Alert command renames an Alert. You specify the name of the Alert
and the Management Module that contains it, and a new name for the Alert.
Syntax: rename alert named <EXACT MATCH> in management module

named <EXACT MATCH> to <EXACT MATCH>
Example: rename alert named \"Socket Bandwidth\" in management
module named Sample2 to \"Socket Bandwidth2\"
This command renames the alert named Socket Bandwidth in the
Management Module named Sample2 to Socket Bandwidth2.
Output: None
Delete Alert
The Delete Alerts command deletes one or more Alerts from one or more
Alerts, and one that specifies the Management Modules from which to delete
them.
» Note You cannot delete a Alert that is used or referenced by another element—
for example, one that is used on a dashboard.
Syntax: delete alerts matching <REGULAR EXPRESSION> in

Example: delete alerts matching (.*Email.*) in management
This command deletes Alerts whose name contains the string Email
from the Management Module named Sample.
Output: None

CA Wily Introscope
Alert Downtime Schedule commands

Alert Downtime Schedules let you manage downtime periods from the Introscope
Workstation Management Module Editor.
List Alert Downtime Schedules

The List Alert Downtime Schedules command lists one or more alert downtime
schedules in one or more Management Modules. You supply two regular
expressions—one that specifies the alert downtime schedule, and one that
specifies the Management Modules.
Syntax: list alert downtime schedules matching [REGULAR

EXPRESSION] in management modules matching [REGULAR
EXPRESSION]
Example: list alert downtime schedules matching (.*) in management modules
matching Sample
Output: Sample.Example Alert Downtime Schedule
Sample.Another Alert Downtime Schedule
Activate Alert Downtime Schedules

The Activate Alert Downtime Schedules command activates one or more alert
downtime schedules in one or more Management Modules. You supply two
regular expressions—one that specifies the alert downtime schedules to activate,
and one that specifies the Management Modules in which to activate those alert
downtime schedules.
Syntax: activate alert downtime schedules matching [REGULAR

EXPRESSION]
Example: activate alert downtime schedules matching (.*) in management
Output: Sample.Example Alert Downtime Schedule:Active
Sample.Another Alert Downtime Schedule:Active

Deactivate Alert Downtime Schedules

The Deactivate Alert Downtime Schedules command deactivates one or more
alert downtime schedules in one or more Management Modules. You supply two
regular expressions—one that specifies the alert downtime schedules to
deactivate, and one that specifies the Management Modules in which to
deactivate those alert downtime schedules.
Syntax: deactivate alert downtime schedules matching [REGULAR

EXPRESSION]
Example: deactivate alert downtime schedules matching (.*) in
management modules matching Sample
Output: Sample.Example Alert Downtime Schedule:Inactive
Sample.Another Alert Downtime Schedule:Inactive
Query Alert Downtime Schedules

The Query Alert Downtime Schedules command lists the state—active or
inactive—of one or more alert downtime schedules in one or more Management
Modules. You supply two regular expressions—one that specifies the alert
downtime schedules, and one that specifies the Management Modules.
Syntax: query state of alert downtime schedules matching

[REGULAR EXPRESSION] in management modules matching
[REGULAR EXPRESSION]
Example: query state of alert downtime schedules matching (.*) in management
Output: Sample.Example Alert Downtime Schedule:Inactive
Sample.Another Alert Downtime Schedule:Inactive
Rename Alert Downtime Schedules

The Rename Alert Downtime Schedules command renames an alert downtime
schedule. You specify the name of the alert downtime schedule and the
Management Module that contains it, and a new name for the alert downtime
schedule.
Syntax: rename alert downtime schedule named <EXACT MATCH> in

management module named <EXACT MATCH> to <EXACT MATCH>
Example: rename alert downtime schedule named \"Example Alert Downtime
Schedule\" in management module named Sample to \"Example ADS\"
Output: None

CA Wily Introscope
Delete Alert Downtime Schedules

The Delete Alert Downtime Schedules command deletes one or more alert
downtime schedules from one or more Management Modules. You supply two
regular expressions—one that specifies the alert downtime schedule, and one
that specifies the Management Modules from which to delete them.
Syntax: delete alert downtime schedules matching [REGULAR

EXPRESSION]
Example: delete alert downtime schedules matching (.*) in management
Output: None
Calculator commands
Calculators create custom Metrics by summing or averaging Metric data.
List Calculators
The List Calculators command lists one or more calculators in one or more
calculators, and one that specifies the Management Modules.
Syntax: list calculators matching <REGULAR EXPRESSION> in

Example: list calculators matching (.*) in management modules
matching (.*)
This command lists all calculators in all Management Modules.
Output: Each calculator is listed, prefixed by the Management Module that
contains it:
Sample.Average Servlet Response Time
Activate Calculators
The Activate Calculators command activates one or more calculators in one or
more Management Modules. You supply two regular expressions—one that
specifies the calculators to activate, and one that specifies the Management
Modules in which to activate those calculators.
Syntax: activate calculators matching <REGULAR EXPRESSION> in


Example: activate calculators matching (.*) in management

modules matching Sample2
This command activates all calculators in the Management Module
named Sample2.
Output: Each calculator activated by the command is listed, prefixed by the
Sample2.Average Servlet Response Time:Active
Deactivate Calculators
The Deactivate Calculators command deactivates one or more calculators in one
or more Management Modules. You supply two regular expressions—one that
specifies the calculators to deactivate, and one that specifies the Management
Modules in which to deactivate those calculators.
Syntax: deactivate calculators matching <REGULAR EXPRESSION> in

Example: deactivate calculators matching (.*) in management
This command deactivates all calculators in the Management Module
named Sample2.
Output: Each calculator deactivated by the command is listed, prefixed by the
Management Module that contains it, and suffixed by its activation
state:
Sample2.Average Servlet Response Time:Inactive
Query Calculators
The Query Calculators command lists the state—active or inactive—of one or
more calculators in one or more Management Modules. You supply two regular
expressions—one that specifies the calculators, and one that specifies the
Management Modules.
Syntax: query state of calculators matching <REGULAR

EXPRESSION> in management modules matching <REGULAR
EXPRESSION>
Example: query state of calculators matching (.*) in management
This command queries the state of all calculators in all Management
Modules.
Output: Each calculator is listed, prefixed by the Management Module that
contains it, suffixed by its state:
Sample.Average Servlet Response Time:Inactive

CA Wily Introscope
Rename Calculator
The Rename Calculator command renames a calculator. You specify the name of
the calculator and the Management Module that contains it, and a new name for
the calculator.
Syntax: rename calculator named <EXACT MATCH> in management

module named <EXACT MATCH> to <EXACT MATCH>
Example: rename calculator named \"SQL Calculator\" in
management module named \"Sample\" to \"SQL Calc\"
This command renames the calculator named SQL Calculator in the
Management Module named Sample to SQL Calc.
Output: None
Delete Calculators
The Delete Calculators command deletes one or more calculators from one or
specifies the calculators, and one that specifies the Management Modules from
which to delete them.
» Note You cannot delete a calculator that is used or referenced by another

Element, for instance, one that is used in a Dashboard.
Syntax: delete calculators matching <REGULAR EXPRESSION> in

Example: delete calculators matching \"SQL Calculator\" in
management modules matching (.*)
This command deletes calculators named SQL Calculator from all
Management Modules.
Output: None
Dashboard commands
A dashboard is a page in the Workstation that contains Data Viewer objects such
as Graphs, Bar Charts, and alert status indicators, along with graphic and text
objects.

List Dashboards
The List Dashboards command lists one or more Dashboards in one or more
Dashboards, and one that specifies the Management Modules.
Syntax: list dashboards matching <REGULAR EXPRESSION> in

Example: list dashboards matching (.*Triage) in management
This command lists the Dashboards, in all Management Modules, whose
name ends in the string Triage.
Output: Each dashboard is listed, prefixed by the Management Module that
contains it:
Sample10.3. Triage
Sample2.3. Triage
Sample.3. Triage
Activate Dashboards
The Activate Dashboards command activates one or more dashboards in one or
specifies the Dashboards to activate, and one that specifies the Management
Modules in which to activate those Dashboards.
Syntax: activate dashboards matching <REGULAR EXPRESSION> in

Example: activate dashboards matching (.*) in management modules
matching Sample2
This command activates all dashboards in the Management Module
named Sample2.
Output: Each dashboard activated by the command is listed, prefixed by the
Sample2.4b. Database Detail:Active
Sample2.1. Introscope Console:Active
Sample2.2. Detection:Active

CA Wily Introscope
Deactivate Dashboards
The Deactivate Dashboards command deactivates one or more dashboards in one
or more Management Modules. You supply two regular expressions—one that
specifies the Dashboards to deactivate, and one that specifies the Management
Modules in which to deactivate those Dashboards.
Syntax: deactivate dashboards matching <REGULAR EXPRESSION> in

Example: deactivate dashboards matching (.*) in management
This command deactivates all Dashboards in the Management Module
named Sample2.
Output: Each dashboard deactivated by the command is listed, prefixed by the
Sample2.4b. Database Detail:Inactive
Sample2.1. Introscope Console:Inactive
Sample2.2. Detection:Inactive
Query Dashboards
The Query Dashboards command lists the state—active or inactive—of one or
more dashboards in one or more Management Modules. You supply two regular
expressions—one that specifies the dashboards, and one that specifies the
Management Modules.
Syntax: query state of dashboards matching <REGULAR EXPRESSION>

in management modules matching <REGULAR EXPRESSION>
Example: query state of dashboards matching (.*) in management
This command queries the state of all Dashboards in the Management
Module named Sample2.
Output: Each dashboard is listed, prefixed by the Management Module that
Sample2.4b. Database Detail:Active
Sample2.1. Introscope Console:Active
Sample2.2. Detection:Active

Rename Dashboard
The Rename Dashboard command renames a dashboard. Specify the name of the
dashboard and the Management Module that contains it, and a new name for the
dashboard.
Syntax: rename dashboard named <EXACT MATCH> in management

module named <EXACT MATCH> to <EXACT MATCH>
Example: rename dashboard named \"3. Triage\" in management
module named Sample11 to \"3x Triage\"
This command renames the Dashboard named 3. Triage to 3x
Triage.
Output: None
Delete Dashboards
The Delete Dashboards command deletes one or more dashboards from one or
specifies the dashboards, and one that specifies the Management Modules from
which to delete them.
» Note You cannot delete a dashboard that is used or referenced by another

element. For example, you cannot delete a dashboard that is has a
hyperlink to a data viewer on another dashboard.
Syntax: delete dashboards matching <REGULAR EXPRESSION> in

Example: delete dashboards matching (.*) in management modules
matching Sample11
This command deletes all Dashboards in the Management Module named
Sample11.
Output: None
Metric Grouping commands

A Metric Grouping specifies which Metrics to act upon; it is used as a building
block for elements such as alerts and calculators.

CA Wily Introscope
List Metric Groups

The List Metric Groups command lists one or more Metric Groups in one or more
Metric Groups, and one that specifies the Management Modules.
Syntax: list metric groups matching <REGULAR EXPRESSION> in

Example: list metric groups matching (.*Response.*) in
management modules matching Sample
This command lists the Metric Groups in the Management Module named
Sample, whose name includes the string Response.
Output: Metric Groups are listed in this format:
<Management Module>.<Metric Group>[Agent: "<Agent
Expression>" Attribute: "<Metric Expression>"]
For example:
Sample.Servlet Average Response Time (ms) [Agent:
"(.*)\|(.*)\|(.*)" Attribute:\"Servlets:Average
Response Time $ms$"]
The sample above provides this information for the Metric Grouping:
Management Module—Sample
Metric Grouping Name—Servlet Average Response Time (ms)
Agent Expression— (.*)\|(.*)\|(.*)
Metric Expression—Servlets:Average Response Time $ms$
Report Templates Commands

This section defines CLW commands for managing and generating reports. For
more information about Introscope’s reporting capabilities, see the Reporting
chapter of the Introscope Workstation User Guide.
List Report Templates

The List Report Templates command lists one or more report templates in one or
specifies the report templates, and one that specifies the Management Modules.
Syntax: list report templates matching <REGULAR EXPRESSION> in


Example: list report templates matching (.*) in management

This command lists all report templates in the Management Module
named Sample.
Output: Each report template is prefixed by the Management Module that
contains it.
Sample.QA/Test Application Performance
Sample.System Availability
Sample.Application Capacity Planning
Activate Report Templates

The Activate Report Templates command activates one or more report templates
in one or more Management Modules. You supply two regular expressions—one
that specifies the report templates to activate, and one that specifies the
Management Modules in which to activate the report templates.
Syntax: activate report templates matching <REGULAR EXPRESSION>

Example: activate report templates matching (.*) in management
This command activates all Report Templates in the Management Module
named Sample2.
Output: Each report template activated by the command is listed, prefixed by the
Sample2.Application Capacity Planning:Active
Sample2.Production Application Health:Active
Sample2.System Availability:Active
Deactivate Report Templates

The Deactivate Report Templates command deactivates one or more report
templates in one or more Management Modules. You supply two regular
expressions—one that specifies the report templates to deactivate, and one that
specifies the Management Modules in which to deactivate those report templates.
Syntax: deactivate report templates matching <REGULAR

EXPRESSION>

CA Wily Introscope
Example: deactivate report templates matching (.*) in management

This command deactivates all Report Templates in the Management
Output: Each report template deactivated by the command is listed, prefixed by
the Management Module that contains it, and suffixed by its state:
Sample2.Application Capacity Planning:Inactive
Sample2.Production Application Health:Inactive
Sample2.System Availability:Inactive
Query Report Templates

The Query Report Templates command lists the state—active or inactive—of one
or more report templates in one or more Management Modules. You supply two
regular expressions—one that specifies the report templates, and one that
Syntax: query state of report templates matching <REGULAR

EXPRESSION>
Example: query state of report templates matching (.*) in
management modules matching Sample2
This command queries the state of all report templates in the
Management Module named Sample2.
Output: Each report template is prefixed by the Management Module that
contains it and suffixed by its state:
Sample2.Application Capacity Planning:Active
Sample2.Production Application Health:Active
Sample2.System Availability:Active
Rename Report Template

The Rename Report Template command renames a report template. You specify
the name of the report template and the Management Module that contains it,
and a new name for the report template.
Syntax: rename report template named <EXACT MATCH> in

Example: rename report template named \"System Availability\" in
management module named \"Sample2\" to \"Availability\"
This command renames the report template named System
Availability in the Management Module named Sample2 to
Availability.
Output: None

Delete Report Templates

The Delete Report Templates command deletes one or more report templates
from one or more Management Modules. You supply two regular expressions—
one that specifies the report templates, and one that specifies the Management
Modules from which to delete them.
Syntax: delete report templates matching <REGULAR EXPRESSION>

Example: delete report templates matching \"Availability\" in
management modules matching Sample2
This command deletes the Report Template named Availability
from the Management Module named Sample2.
Output: None

CA Wily Introscope
Generate Report
Use the Generate Report command to generate a report. You supply these
arguments:
report name start time
management module name end time
filename—This file is written to the current working directory, unless
a path is specified. The file is written in the format associated with
the file extension, which must be one of these: HTML, PDF, XLS,
TEXT, XML, or CSV.
There are three Generate Report commands, basic, expanded, and an Agent
override command:
Syntax: Basic command:

generate report named [EXACT MATCH] in management
module named [EXACT MATCH] to [EXACT MATCH]
Expanded command:
module named [EXACT MATCH] starting at [EXACT MATCH]
ending at [EXACT MATCH] to [EXACT MATCH]
Optional The optional parameters can be used with both the basic and
Parameters: expanded commands above:
{in agents matching [REGEX PATTERN]} {starting at
[EXACT MATCH] ending at [EXACT MATCH]}
Syntax
The syntax for the optional parameters is:
module named [EXACT MATCH] {in agents matching [REGEX
PATTERN]} {starting at [EXACT MATCH] ending at [EXACT
MATCH]} to [EXACT MATCH]
Example: generate report named \"Application Capacity
Planning\" in management module named "Sample"
starting at \"2007/2/21 12:43\" ending at \"2007/2/
22 16:43\" to report.pdf
Output: The report is written to local disk storage.

SNMP Collections commands

These commands define which collected Metrics are to be included in a published
MIB.
List SNMP Collections

The List SNMP Collections command lists one or more SNMP collections in one or
specifies the SNMP Collections, and one that specifies the Management Modules.
Syntax: list snmp collections matching <REGULAR EXPRESSION> in

Example: list snmp collections matching (.*) in management
This command lists all SNMP Collections in all Management Modules.
Output: Each SNMP Collection is prefixed by the Management Module that
contains it. For example:
Sample2.JDBC QueryUpdate
Activate SNMP Collections

The Activate SNMP Collections command activates one or more SNMP collections
in one or more Management Modules. You supply two regular expressions—one
that specifies the SNMP collections to activate, and one that specifies the
Management Modules in which to activate those SNMP collections.
Syntax: activate snmp collections matching <REGULAR EXPRESSION>

Example: activate snmp collections matching (.*) in management
This command activates all SNMP collections in the Management Module
named Sample2.
Output: Each SNMP collection activated by the command is listed, prefixed by the
Management Module that contains it, suffixed by its state.
Sample2.JDBC QueryUpdate:Active

CA Wily Introscope
Deactivate SNMP Collections

The Deactivate SNMP Collections command deactivates one or more SNMP
collections in one or more Management Modules. You supply two regular
expressions—one that specifies the SNMP collections to deactivate, and one that
specifies the Management Modules in which to deactivate those SNMP collections.
Syntax: deactivate snmp collections matching <REGULAR

EXPRESSION>
Example: deactivate snmp collections matching (.*) in management
This command deactivates all SNMP Collections in the Management
Output: Each SNMP collection deactivated by the command is listed, prefixed by
the Management Module that contains it, suffixed by its state.
Sample2.JDBC QueryUpdate:Inactive
Query SNMP Collections

The Query SNMP collections command lists the state—active or inactive—of one
or more SNMP collections in one or more Management Modules. You supply two
regular expressions—one that specifies the SNMP collections, and one that
Syntax: query state of snmp collections matching <REGULAR

EXPRESSION>
Example: query state of snmp collections matching (.*) in
management modules matching Sample2.
This command lists the state of all SNMP collections in the Management
Output: Each SNMP collection is listed, prefixed by the Management Module that
Sample2.JDBC QueryUpdate:Active

Rename SNMP Collection

The Rename SNMP collection command renames a SNMP collection. You specify
the name of the SNMP collection and the Management Module that contains it,
and a new name for the SNMP collection.
Syntax: rename snmp collection named <EXACT MATCH> in

Example: rename snmp collection named \"JDBC QueryUpdate\" in
management module named \"Sample2\" to \"JDBC Query
Update\"
This command renames the SNMP collection named JDBC
QueryUpdate in the Management Module named Sample to JDBC
Query Update.
Output: None
Delete SNMP Collections

The Delete SNMP Collections command deletes one or more SNMP collections
from one or more Management Modules. You supply two regular expressions—
one that specifies the SNMP collection, and one that specifies the Management
Modules from which to delete them.
Syntax: delete snmp collections matching <REGULAR EXPRESSION>

Example: delete snmp collections matching \"JDBC Query Update\"
in management modules matching Sample2
This command deletes the SNMP collection named JDBC Query Update
from the Management Module named Sample2.
Output: None
Configuring Transaction Trace Options

The CLW gives you the option of configuring a variety of Transaction Trace
options using these system properties:
-Dintroscope.clw.tt.console—If set to "true", the transaction traces will

be printed to a console.
-Dintroscope.clw.tt.dirname—The local directory where transaction trace
XML files are stored.
-Dintroscope.clw.tt.filename—The file name used to store the
transaction trace. This must not include the directory name.
-Dintroscope.clw.tt.encoding— The encoding used when writing XML files to
disk. Options for this property include the default option ISO-8859-1 and UTF-
8, UTF-16, and Windows-1252

CA Wily Introscope
Starting a Transaction Trace session

The Transaction Tracer traces the activity of individual transactions as they flow
through the boundaries of a single JVM.
Transaction Traces are automatically saved to the Transaction Events database,

and by default are also captured in one or more XML files, which you can open
and analyze in the Transaction Trace Viewer in the Introscope Workstation. See
the Introscope Workstation User Guide for information about the Introscope
Transaction Tracer.
Command syntax
There are many aspects of a Transaction Trace Session that a CLW command can
specify. Some of these include:
Execution threshold value—The minimum execution time for transactions to be

traced. Tracing is performed for transactions that take longer than the
threshold to execute. The threshold can be specified in seconds.
Agent to trace—A Perl regular expression that specifies the Agent or Agents for
which transactions are traced.
Session duration—The duration of the Transaction Trace Session, in seconds.
The syntax for starting a Transaction Trace Session, specifying the threshold
in seconds, is:
trace transactions exceeding <EXACT MATCH>
(second|seconds|sec|secs|s) in agents matching <REGULAR
EXPRESSION> for <EXACT MATCH> <second|seconds|sec|secs|s>
Other CLW command options are detailed in Command options, below. For
Transaction Trace CLW command examples, see Transaction Trace command
examples on page 199.
Specify Transaction Trace output file

You can specify the name of the Transaction Trace output file.
» Note This property is deprecated with this release of Introscope.
Syntax: Dtxn.file=<file name>

Example: Specifies the file name (but not the full path) of the transaction trace
output file. Use in conjunction with a property to specify the output
directory.
Output: Sends transaction trace output to the specified file.

Command options
This section describes Transaction Trace command options.
Trace mode
The CLW supports two modes of capturing Transaction Trace Session results:
Synchronous Mode—By default, the CLW writes the trace at the end of the
session to the Transaction Events Database, and to a single XML file named
TransactionTraceData-yyyyMMddhhmmss.xml, where the date-time string
reflects the start of the session.
Asynchronous Mode—In this mode, the CLW writes the trace for each
transaction as soon as it is reported to the Transaction Events Database, and
to its own XML file named nnnn(sec)-
TransactionTraceDatayyyyMMddhhmmss-<sequence number>.xml, where
nnnn is the transaction duration in seconds, and the date-time string reflects
the start of the transaction. If you provide your own file name, it will append
the sequence number before the last ".". If file name provided does not have
".", it will append the sequence number at the end of the file name.
Results recorded in Synchronous Mode are easier to view—all the data is in a

single file. However, you cannot view the data until the end of the session, and
for high-volume or complex transactions, synchronous capture can consume
significant memory.
Recording transaction data asynchronously consumes less memory, and enables

you to view transactions data before the end of the Transaction Trace Session.
-Dintroscope.clw.tt.mode=(Synch|Asynch)
Output to Transaction Events Database only
Use this option to run a transaction trace and save the output only to the
Transaction Events Database (no XML file output). This command is useful when
triggered by an Introscope Alert to automatically start tracing transactions when
the Alert is triggered.
Precede the command with the word quietly as in:
quietly trace transactions exceeding 2 seconds in agents matching "(.*)" for

60 seconds
Transaction Trace file directory
Use this option to specify the directory to which the CLW writes Transaction Trace
Session results. The directory must exist. If you specify a directory that does not
exist, the Transaction Trace are written to the current working directory.

CA Wily Introscope
-Dintroscope.clw.tt.dirname=<directory>
Output to console
Use this option to redirect the output of a Transaction Trace Session to the
command line shell. If you use this option, results are still sent to the Transaction
Events Database, but not to a file.
-Dintroscope.clw.tt.console=<true|false>
Return only header data
In some cases, when retrieving a large amount of transaction trace data via CLW,
the traces.db file may grow without bound, causing CLW to take a long time to
return. Setting this property to false solves the problem by reducing the amount
of data returned by the EM.
CLW will then return only header trace data. By default or when this property is
set to true, getting transaction trace data via the CLW will return both the header
and body.
-Dwily.ps.workstation.clws.gettracebody
Transaction Tracer Clamp
The size of an individual Transaction Trace is now clamped when it reaches 5000
trace components by default. Any Transaction Trace exceeding the clamp will be
discarded at the Introscope Agent and a warning message like the following will
be logged in the Introscope Agent log file:
2/23/07 05:33:18 PM PST [WARN] [IntroscopeAgent] Transaction trace component

limit of 5000 reached, recording will cease for this transaction.
To change the maximum number of components allowed in a transaction trace,

change the following Introscope Agent property:
introscope.agent.transactiontrace.componentCountClamp=max_TT_components
(default is 5000)
For example, the following line in the Agent profile:
introscope.agent.transactiontrace.componentCountClamp=30000
will change the maximum components allowed in a Transaction Trace to 30,000.

» WARNING If this clamp size is increased, the memory required for

transaction traces may be higher and as such, the max heap size
for the JVM may need to be adjusted accordingly, or else the
managed application may run out of memory.
Transaction Trace command examples

This section provides examples of CLW commands to start a Transaction Trace
Session. Each example command initiates a session 600 seconds long.
Transactions that take longer than 5 seconds, from all Agents, are traced.
» Note All example commands use default login settings to connect to the
Enterprise Manager.
For examples of scripts that run Transaction Trace Sessions, see Sample scripts
on page 202.
Transaction Trace using default option values
This CLW command starts a Transaction Trace Session using default settings for:
Trace Mode—Transaction Trace data is captured synchronously—all results are

written to a single XML file.
Directory Location—When -Dintroscope.clw.tt.dirname is not specified,
trace results are written to the current working directory.
java -jar CLWorkstation.jar trace transactions exceeding 5 seconds in agents
matching "(.*)" for 600 seconds
Transaction Trace using asynchronous capture
This CLW command starts a Transaction Trace Session using the default directory
location for session output:
java –Dintroscope.clw.tt.mode=Asynch -jar CLWorkstation.jar trace

transactions exceeding 5 seconds in agents matching "(.*)" for 600 seconds
Data is captured asynchronously—a separate XML file is created for each

transaction.
Transaction Trace results written to a user-defined directory
This CLW command starts a Transaction Trace Session using the default setting
for Trace Mode—Transaction Trace data is captured synchronously. All results are
written to a single XML file:
java –Dintroscope.clw.tt.dirname=C:\mytraces -jar CLWorkstation.jar trace

transactions exceeding 5 seconds in agents matching "(.*)" for 600 seconds

CA Wily Introscope
This command specifies a non-default location for the XML file—the C:\mytraces
directory.
Transaction Trace using parameter and error filters
You can initiate a Transaction Trace session that specifies the number of seconds
to run and uses the same filters that are available in the Workstation—user ID,
URL, URL query, session ID, request header, request parameter, session
attribute, and error:
Filtering on User ID, URL, URL query, or session ID

trace transactions where (userid|url|url query|sessionid) (equals|not
equals|contains|not contains|starts with|ends with) [EXACT MATCH] in
agents matching [REGULAR EXPRESSION] for [EXACT MATCH]
trace transactions where (userid|url|url query|sessionid) (exists|not
exists) in agents matching [REGULAR EXPRESSION] for [EXACT MATCH]
quietly trace transactions where (userid|url|url query|sessionid)
(equals|not equals|contains|not contains|starts with|ends with) [EXACT
MATCH] in agents matching [REGULAR EXPRESSION] for [EXACT MATCH]
quietly trace transactions where (userid|url|url query|sessionid)
(exists|not exists) in agents matching [REGULAR EXPRESSION] for [EXACT
MATCH] (second|seconds|sec|secs|s)
Filtering on request header, request parameter, or session attribute

trace transactions where (request header|request parameter|session
attribute) [EXACT MATCH] (equals|not equals|contains|not contains|starts
with|ends with) [EXACT MATCH] in agents matching [REGULAR EXPRESSION] for
[EXACT MATCH] (second|seconds|sec|secs|s)
trace transactions where (request header|request parameter|session
attribute) [EXACT MATCH] (exists|not exists) in agents matching [REGULAR
EXPRESSION] for [EXACT MATCH] (second|seconds|sec|secs|s)
quietly trace transactions where (request header|request parameter|session
attribute) [EXACT MATCH] (equals|not equals|contains|not contains|starts
with|ends with) [EXACT MATCH] in agents matching [REGULAR EXPRESSION] for
[EXACT MATCH] (second|seconds|sec|secs|s)
quietly trace transactions where (request header|request parameter|session
attribute) [EXACT MATCH] (exists|not exists) in agents matching [REGULAR
EXPRESSION] for [EXACT MATCH] (second|seconds|sec|secs|s)
Filtering on errors
trace transactions with errors containing [EXACT MATCH] in agents matching
[REGEX] for [EXACT MATCH] (second|seconds|sec|secs|s)
quietly trace transactions with errors containing [EXACT MATCH] in agents
matching [REGEX] for [EXACT MATCH] (second|seconds|sec|secs|s)

Transaction Trace Queries from Transaction Events Database

Transaction Trace results are automatically stored in the Transaction Events
Database. Use the CLW commands described here to retrieve that data.
Get Historical Events Matching <VALUE>
This command retrieves a full event XML output file from the Transaction Events
Database. A full event (as opposed to a summary event, below) is the full data
available in the lower section of the Transaction Event Viewer.
java –Dintroscope.clw.tt.mode=Asynch -jar CLWorkstation.jar trace

transactions get historical events matching "localhost"
Here is an example of the output:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<TransactionTracerSession Duration="78" Version="0.1" EndDate="2005-06-
20T17:40:24.146-08:00" StartDate="2005-06-20T17:40:24.068-08:00"
User="Admin">
<TransactionTrace Domain="SuperDomain" Duration="78"
Process="UnknownProcess" Host="maddleman-dt2" AgentName="Tomcat"
StartDate="2005-06-20T17:40:24.068-08:00" EndDate="2005-06-
20T17:40:24.146-08:00">
<CalledComponent RelativeTimestamp="0" Duration="78" ComponentType="Browser"
ComponentName="Browser" MetricPath="Browser">
<CalledComponents>
<CalledComponent RelativeTimestamp="0" Duration="0" ComponentType="JNDI"
ComponentName="ProxyDirContext"
MetricPath="JNDI|Context|ProxyDirContext">
<Parameters>
<Parameter Value="lookup" Name="Method"/>
</Parameters>
</CalledComponent>
<Parameters>
</Parameters>
</CalledComponent>
<CalledComponent RelativeTimestamp="0" Duration="62"
ComponentType="Servlets" ComponentName="HelloWorldExample"
MetricPath="Servlets|HelloWorldExample">
<CalledComponents>
<Parameters>

CA Wily Introscope
</Parameters>
</CalledComponent>
<Parameters>
</Parameters>
</CalledComponent>
</CalledComponents>
</TransactionTrace>
</TransactionTracerSession>
Get summaries matching <VALUE>
This command retrieves only the event summary XML from the Transaction
Events database and outputs an XML file. An event summary is information
available in the top pane of the Transaction Event Viewer. This command is useful
to export data from the Transaction Events database for generating reports on
the number of errors the system experiences by day, for example.
get historical event summaries matching [REGULAR EXPRESSION]
Here is an example of the output:

<TransactionTracerSession Duration="78" Version="0.1" EndDate="2005-06-
20T17:40:24.146-08:00" StartDate="2005-06-20T17:40:24.068-08:00"
User="Admin">
<TransactionTrace Domain="SuperDomain" Duration="78"
Process="UnknownProcess" Host="maddleman-dt2" AgentName="Tomcat"
StartDate="2005-06-20T17:40:24.068-08:00" EndDate="2005-06-
20T17:40:24.146-08:00">
<CalledComponent RelativeTimestamp="0" Duration="78" ComponentType="Browser"
ComponentName="Browser" MetricPath="Browser">
<Parameters>
<Parameter Value="" Name="URL"/>
<Parameter Value="Normal" Name="Trace Type"/>
<Parameter Value="\20050620\17\1119314425302" Name="Trace ID"/>
<Parameter Value="" Name="User ID"/>
</Parameters>
</CalledComponent>
</TransactionTrace>
</TransactionTracerSession>
Sample scripts
This section contains sample scripts that use CLW commands:
Transaction Trace Session on page 203

Transaction Trace session triggered by Alert on page 206
These scripts use other scripts—setIscEnv.cmd and configureWily.cmd—that

are available on the Wily Community site at https://
community.wilytech.com/
entry!default.jspa?categoryID=492&externalID=2103. They are part of a
Community Developed Tool named Useful Introscope Scripts, that can assist in
startup, shutdown, restart, and using CLW. Download the appropriate ZIP file and
follow the instructions to install the scripts:
1 Extract the appropriate file, scriptsBin.unix.zip or scriptsBin.win.zip

into your Enterprise Manager installation. The package will create a bin
subdirectory.
2 Go to the bin subdirectory, and invoke:
.\configureScriptsEnv.cmd
or
./configureScriptsEnv.sh
3 This creates the file setIscEnv.cmd or setIscEnv.sh. This file contains all
relevant Introscope folder locations from which the other scripts will read.
» Note These scripts were originally created for Introscope 5.x, but should work
on 7.x as well.
Additional sample scripts are available on the Wily Community site at http://
community.wilytech.com.
Transaction Trace Session

This script initiates a Transaction Trace Session for all agents. At run-time, you
supply two arguments:
Execution threshold value—The minimum execution time, in seconds, for

transactions to be traced.
Session duration—The duration of the Transaction Trace Session, in seconds.
The script stores results in a date-oriented directory structure.
Name: clwTxnTracer
Syntax: clwTxnTracer <threshold> <duration>
where:
threshold is the transaction execution time threshold, in seconds
duration is duration of the session, in seconds
Sample scripts 203

CA Wily Introscope
Example: clwTxnTracer 1 600

Causes Transactions Trace Sessions of 600 seconds duration to be run
for any transaction that takes longer than 1 second to execute.
Results: The Transaction Trace data is written to a single file, in a directory that
corresponds to current date:
<Introscope_Home>\traces\<year>\<month>\<day>\<agents>
_<threshold>secs_for<duration>secs.<start_time>.xml
For example:
C:\introscope\traces\2004\11\11\AllAgents_1secs_for600secs.
14091705.xml
@ECHO OFF
SETLOCAL
TITLE Introscope -- Transaction Tracer Session
REM ****
REM Sets the current working directory with quotes around it
REM This enables this file to execute correctly if it is
REM invoked somewhere other than its location.
REM ****
FOR /f "tokens=1 delims=" %%a in ('cd') DO SET PWD=%%a
REM ****
REM Set the command directory to the command argument itself,
REM namely the full path of this file or the relative path
REM to where the file was invoked.
SET CMD_DIR=%0
REM Now simply strip out the name of this file to get dir
REM !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
REM Use current filename
SET CMD_DIR=%CMD_DIR:clwTxnTracer.cmd=%
REM !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
REM Strip the quotes
REM add quotes if they're not there
SET CMD_DIR="%CMD_DIR%"
REM if not add quotes, then this statement chokes
SET CMD_DIR=%CMD_DIR:"=%
REM if the current dir wasn't determined, just set it to working dir
IF NOT EXIST "%CMD_DIR%" SET CMD_DIR=.
IF "%CMD_DIR%" == %0 SET CMD_DIR=.
IF "%CMD_DIR%" == "%0" SET CMD_DIR=.
REM ****
REM Now set the home directory for Introscope, and others
IF NOT EXIST "%CMD_DIR%\setIscEnv.cmd" goto noSetEnvFile
call "%CMD_DIR%\setIscEnv.cmd"
SET TT_THRESHOLD_IN_SECS=%1
SET TT_DURATION_IN_SECS=%2

IF "X%TT_THRESHOLD_IN_SECS%" == "X" SET TT_THRESHOLD_IN_SECS=10000

IF "X%TT_DURATION_IN_SECS%" == "X" SET TT_DURATION_IN_SECS=600
IF %TT_THRESHOLD_IN_SECS% LEQ 0 GOTO badArg
IF %TT_DURATION_IN_SECS% LEQ 0 GOTO badArg
SET TT_AGENTS=(.*)
REM Java Options (e.g. increase Max heap size )

SET JAVA_OPTS=-Xms64m -Xmx512m
SET JAVA_OPTS=%JAVA_OPTS% %CLW_USER_OPT% %CLW_PASSWORD_OPT%
%CLW_EM_HOST_OPT% %CLW_EM_PORT_OPT%
SET COMMAND=trace transactions exceeding %TT_THRESHOLD_IN_SECS% seconds in

agents matching \"%TT_AGENTS%\" for %TT_DURATION_IN_SECS% seconds
SET AGENT_STR=%TT_AGENTS%
REM Remove the spaces, parentheses
SET AGENT_STR=%AGENT_STR:(=%
SET AGENT_STR=%AGENT_STR:)=%
SET AGENT_STR=%AGENT_STR: =%
if "X%TT_AGENTS%" == "X(.*)" SET AGENT_STR=AllAgents
FOR /f "tokens=1-4 delims=:." %%a in ("%time%") DO SET
SECS_STR=%%a%%b%%c%%d
FOR /f "tokens=1-4 delims=/ " %%a in ("%date%") DO SET
TRACES_DIR=%ISC_TRACES%\%%d\%%b\%%c
REM Create the traces dir, if not exist

IF NOT EXIST "%TRACES_DIR%" MKDIR "%TRACES_DIR%"
SET
TT_FILE=%TRACES_DIR%\%AGENT_STR%_%TT_THRESHOLD_IN_SECS%secs_for%TT_DURAT
ION_IN_SECS%secs.%SECS_STR%.xml
TITLE Introscope -- Transaction Tracer for %TT_DURATION_IN_SECS% secs with

threshold %TT_THRESHOLD_IN_SECS% secs
REM send stderr to null b/c there are meaningless disconnect excepts that
might be *scary-looking*
ECHO Saving session output to %TT_FILE%
"%ISC_JAVA_HOME%\bin\java" %JAVA_OPTS% -jar "%CLW_JAR%" %COMMAND% >
"%TT_FILE%" 2>NUL
goto finish
:badArg
ECHO Arguments should be greater than zero.
Sample scripts 205

CA Wily Introscope
ECHO Syntax: $0 "threshold in secs" "duration in secs"

goto finish
:noSetEnvFile
ECHO There is no environment setup file: setIscEnv.cmd
ECHO Please re-run configureWily.cmd in installation directory!
goto finish
:finish
ENDLOCAL
Transaction Trace session triggered by Alert

This script initiates a Transaction Trace Session as a result of an Alert being
triggered. You use a Shell Command Action to invoke it, passing the Alert
message text as an argument.
The script parses the Alert message text for the Agent that reported the data that
triggered the Alert, and the danger level value that was exceeded, which it uses
as the agent and threshold values for the Transaction Trace Session. Session
results are stored in a date-oriented directory structure.
Name: alert2TxnTracer
Syntax: See Creating a Shell Command Action on page 151 for instructions.
Results: The Transaction Trace data is written to a single file, in a directory that
corresponds to current date:
<Introscope_Home>\traces\<year>\<month>\<day>\<agents>
_<threshold>secs_for<duration>secs.<start_time>.xml
For example:
C:\introscope\\traces\2004\11\11\AllAgents_1secs_for600secs.1409
1705.xml

CHAPTER
9
Configuring Introscope Security and

Permissions
This section contains information about Introscope security and permissions

options. It contains these topics:
About Introscope security and permissions . . . . . . . . . . . 208

Configuring and managing realms . . . . . . . . . . . . . 208
Configuring and managing users and groups . . . . . . . . . . 219
Configuring and managing domains . . . . . . . . . . . . . 223
Defining User and Group Permissions . . . . . . . . . . . . 228
Configuring Introscope Security and Permissions 207

CA Wily Introscope
About Introscope security and permissions

Introscope administers security and permissions using the following entities:
Realms—A repository containing user and group information and their
associated security and authentication settings. Configure this file to first
determine whether you want to authenticate using a local or external
authentication mechanism.
Users and groups—Users are a defined individual identity, generally a
person. Groups are a defined set of users or groups, usually classified by
common traits. Both are defined in the users.xml file. For more information,
see Configuring and managing users and groups on page 219.
» Note User and groups permissions are defined for the domain in domains.xml
and for the Enterprise Manager in server.xml. For more information,
see Defining User and Group Permissions on page 228.
Domains—A partition of agents and monitoring logic. Agents are mapped to a

Domain using a Perl5 regular expression in the domains.xml file. For more
information, see Configuring and managing domains on page 223.
» Note Users and permissions are case insensitive, meaning if you login using
admin or Admin; the permissions for that user role are applied.
Configuring and managing realms

Introscope uses the realms.xml to authenticate users or groups using LDAP.
Each realm in the chain is checked to see if the user or group with the given ID
exists. The first matching realm is checked to see if the user or group password
supplied matches the value provided in the realm. If the password doesn't match
or if not matching realm is found, authentication will fail.
Additionally, realm types can be added by creating plugins extending the EM's
realms extension point.
Defining Realms
1 Open the <Introscope_Home>/config/realms.xml file.
2 Set the properties to meet the needs of your desired configuration. For more
information, see Simple Admin Realm Parameters on page 209 and Local Realm
Parameters on page 209.
3 Save changes to the file, and restart the Enterprise Manager for the changes to
take affect.
208 Configuring Introscope Security and Permissions

Simple Admin Realm Parameters
You can define a realm entry for a simple admin user.
If a user id other than Admin is specified, that user will not have any permissions
in the EM until the domain definitions are updated with additional grants.
If you desire to make additional configurations to the simple admin realm, you
should instead use the local realm.
» Note When creating an admin user, keep in mind that users and permissions
are case insensitive, meaning if a user logs in using admin or Admin; the
permissions for that user role are applied.
The following table, lists the available parameters for a simple admin realm:
Parameter Definition
userid The user or group identification for the administrator
user.
password The user or group password. This is blank by default.
useGust The guest password that is set to true if an account
Guest is enabled. The password can't be changed from
Guest.
Local Realm Parameters
A local realm obtains user and group definitions from XML files in the config area.
The XML files store user passwords.
The following table, lists the available parameters for a local realm:
Parameter Definition
usersFile The file name relative to the config directory where
users are stored.
By default, users.xml. This file also contains group
definitions.
passwordPattern A regular expression to match all passwords. Allows you
to specify a minimum length for passwords.
Default is to allow any password.
Configuring and managing realms 209

CA Wily Introscope
Realm syntax with LDAP enabled

The following is the syntax for configuring an LDAP-enabled realm:
<?xml version="1.0" encoding="UTF-8"?>
<realms xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="0.1"
xsi:noNamespaceSchemaLocation="realms0.1.xsd">
<realm active="true" descriptor="LDAP Realm" id="LDAP">


<property name="url">
<value>ldap://myActiveDirectoryServer.mydomain.com:389</value>
</property>

<property name="useSSL">
<value>false</value>
</property>






<property name="bindName">
<value>CN=Automatic Binding User,OU=Groups,DC=myDomain,DC=com</
value>
</property>







<property name="bindPassword">
<value>secretPassword</value>
</property>





<property name="bindAuthentication">
<value>simple</value>
</property>











<property name="baseDN">
<value>DC=myDomain,DC=com</value>
</property>


<property name="scopeDepth">
<value>subtree</value>
</property>



<property name="usernameAttribute">
<value>cn</value>
</property>








<property name="userObjectQuery">
<value>(&(objectClass=organizationalPerson)(cn={0}))</value>
</property>




CA Wily Introscope

















</realm>
</realms>

Configuring LDAP authentication

LDAP authentication works supports the following v3 LDAP servers and a variety
of others:
IBM Directory Server (version 5.1)
SunONE Directory Server (version 5.1)
MS Active Directory (Windows 2000 and 2003 versions)
LDAP authentication is configured in the <Introscope_Home>/config/

realms.xml file.
» Note If you renamed your Introscope directory during the upgrade, and your
property files used absolute paths to reference files in the Introscope
directory, then you will have to update these paths as a manual post-
upgrade task. To avoid this, CA Wily recommends using relative paths to
refer to any file inside the Introscope root directory.
Configuring realms.xml for authentication extension

Every site's LDAP server is configured uniquely, so you must obtain LDAP
configuration information from the site's LDAP administrator before attempting
to configure the following LDAP properties.
LDAP properties are configured the file, <Introscope_Home>/config/

realms.xml.
The following table describes the properties in this file:
Property Specifies Example

url URL for the remote LDAP server ldap://host:port
The default port for non-SSL connections is
389, the default port for SSL connections is
636.
Note: If you are using SSL, the SSL LDAP port
should be part of the server URL.
useSSL Whether to use SSL to connect to remote LDAP false

server.
Options are: true/false
bindName Name used to bind to LDAP server. If blank, IntroscopeLDAPUse

anonymous bind is used. r
bindPasswo Password used to bind to LDAP server. If password123

rd anonymous bind is used, this property is
ignored.

CA Wily Introscope
Property Specifies Example

bindAuthen Authentication type to use when binding. simple
tication Options are: none, simple, DIGEST-MD5.
baseDN Base distinguished name (DN) for all user dc=com

object queries.
Options are: cn=Users, dc=dev, dc=com
scopeDepth Search depth when querying for a user object subtree
usernameAt Name of LDAP attribute that will match an userPrincipalName

tribute Introscope username.
userObject LDAP search filter used to query a user object. (&(userPrincipalNa

Query The token “%u” will be filled in with the me=%u)(objectclas
Introscope username before the query s=user))
executes.
serverCert Name of certificate file. Supported certificate blank

ificate types are of type X.509, and base64-encoded.
If not specified, default certificate authorities
provided by the JVM will be used (see http://
java.sun.com/j2se/1.5/docs/index.html).
groupNameA Name of group attribute that will match an cn
ttribute Introscope username.
groupObjec LDAP search filter used to query a group object. (&(objectClass=gro

tQuery The token “%u” will be filled in with the up)(cn={0}))
Introscope group name before the query
executes.
groupMembe LDAP search filter used to query a group (&(objectClass=gro

rQuery member. The token “%u” will be filled in with up)(member={0}))
the Introscope group member before the query
executes.
LDAP configuration examples

The following section contains examples of LDAP configurations on each of the
supported LDAP Servers. Please note that the following code samples are
provided for example only; every site's LDAP server is configured uniquely.
IBM Directory Server
The following example shows LDAP properties configured for use with the IBM
Directory Server, using SSL.


<value>ldap://sqw32vserv01.ca.com:389</value>
</property>
<value/>
</property>
<value>jon</value>
</property>
</property>
<value>(&(objectClass=organizationalPerson)(cn={0})) </value>
</property>
<value>cn</value>
</property>
<value>(&(objectClass=organizationalUnit)(cn={0}))</value>
</property>
<value>(&(objectClass=groupofNames)(member={0}))</value>
</property>
</property>
<value>cn=Jon Doe,ou=Groups,o=unitTest</value>
</property>
<value>cn</value>
</property>
</property>
</realm>
</realms>
SunONE Directory Server
This example shows LDAP properties configured for use with the Sun ONE
Directory Server, using SSL.

<realm descriptor="Local Users and Groups Realm" id="Local Users and Groups"
active="true">
<property name="usersFile">
<value>users.xml</value>

CA Wily Introscope
</property>
</realm>
<realm active="true" id="Introscope LDAP Realm" descriptor="LDAP Realm">
<value>uid=JDOE1,ou=Users,dc=ca,dc=com</value>
</property>
</property>
<value>DC=ca,DC=com</value>
</property>
<value>jim</value>
</property>
<value>ldap://123serv01.company.com:389</value>
</property>
<value>cn</value>
</property>
<value>(&(objectClass=organizationalPerson)(cn={0}))</value>
</property>
<value>cn</value>
</property>
<value>(&(objectClass=group)(cn={0}))</value>
</property>
<value>(&(objectClass=group)(member={0}))</value>
</property>
</property>
</property>
<value/>
</property>
</realm>
</realms>

MS Active Directory
This example shows LDAP properties configured for use with MS Active Directory,
using SSL.


<value>ldap://123serv01.company.com:389:389</value>
</property>
<value/>
</property>
<value>.B3HTt33.</value>
</property>
</property>
<value>(&(objectClass=organizationalPerson)(cn={0})) </value>
</property>
<value>DC=ad-dev-02,DC=com</value>
</property>
</property>
<value>CN=Jon Doe,cn=Users,DC=ad-dev-02,DC=com</value>
</property>
<value>cn</value>
</property>
</property>
</realm>
</realms>
Sample Realms Configuration File for LDAP

<realms version="0.1" xsi:noNamespaceSchemaLocation="realms0.1.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<realm active="true" id="Introscope LDAP Realm" descriptor="LDAP Realm">

CA Wily Introscope
<value>uid=admin,ou=system</value>
</property>
</property>
<value>o=unitTest</value>
</property>
<value>secret</value>
</property>
<value>ldap://localhost:389</value>
</property>
<value>uid</value>
</property>
<value>(&(objectClass=inetOrgPerson)(uid=%u))</value>
</property>
<value>cn</value>
</property>
<value>(&(objectClass=groupOfUniqueNames)(cn=%g))</value>
</property>
<value>(&(objectClass=groupOfUniqueNames)(uniquemember=%u))</
value>
</property>
</property>
</property>
</realm>
</realms>

Configuring and managing users and groups

Introscope offers an extensible authentication system that can integrate with
existing systems through LDAP. If you do not use an external authentication
mechanism, authentication is configured locally by referencing the users stored
in the users.xml file.
to use local authentication, follow the instructions in this section, then proceed
to Defining User and Group Permissions on page 228, to define permissions for
each user or group.
If you will be using an external authentication mechanism, see Defining User
and Group Permissions on page 228.
About local user authentication

Local authentication is used by default in Introscope. The authentication method
used is configured in the realms.xml file. If local authentication is used, the
Enterprise Manager references a local authentication properties configuration file,
which then refers to users.xml where users and passwords are stored.
Local authentication changes are dynamic: when a user attempts to log in, login
values are compared to users.xml file each time an authentication request is
made. Changes to the contents of the users.xml file do not require an
Enterprise Manager restart.
Introscope provides an optional mechanism for encoding passwords for use in

local authentication.
There are several steps involved in setting up local authentication:

making sure Introscope is configured to use local authentication
changing the location of the users.xml file if desired
defining users in the users.xml file
generating passwords
Configuring local authentication
Configuring Enterprise Manager to use local authentication

Introscope uses local authentication by default.
To check that local authentication is used:
1 Go to <Introscope_Home>/config and open realms.xml.

2 Verify that this line is present as the third entry in realms.xml:
Configuring and managing users and groups 219

CA Wily Introscope
<realm active="true" descriptor="Local Users and Groups Realm"

id="Local Users and Groups">
3 Save changes to this file if necessary, and restart the Enterprise Manager.
Configuring location or name of local authentication file

Local authentication using users.xml doesn’t require configuration or any
shared security service at your site. By default, this file is located at
<Introscope_Home>/config/users.xml.
However, you might want to configure the name or location of this username/
password file. Because you can specify the name and location of this file, several
Enterprise Managers could share the same authentication file.
» Note If you are migrating users from a previous Introscope installation, do not
change the name or location of the users.xml file until after migration
is complete.
To configure the pathname of the local authentication file:
1 Open the file, <Introscope_Home>/config/realms.xml.

2 Enter the path of the users.xml file.
3 Save changes, and restart the Enterprise Manager.
Defining users and groups
User and group configuration modifiers and syntax

You must define a username and password for each user or group.
» Note When creating an admin user, keep in mind that users and permissions
are case insensitive, meaning if a user logs in using admin or Admin; the
permissions for that user role are applied.
This table contains the modifiers for defining users:
Parameter Value Rules

name username alphanumeric characters only, and underscore (_)
and dash (-)
password user any characters except quotation marks
password by default, passwords are encrypted and not in clear-
text or obfuscated (can optionally generate encoded
passwords)
password characters can be legal XML characters
a password value can be empty

The syntax for configuring a user is:
<users>
<user password="adb831a7fdd83dd1e2a39ce7591dff8" name="Guest"/>
<user password="" name="Admin"/>
</users>
The syntax for configuring a group is:
<groups>
<group description="Administrator Group" name="Admin">
<user name="Admin"/>
</group>
</groups>
Defining a user or group

To define a user or group:
1 Open the <Introscope_Home>/config/users.xml file in an XML editor.

2 Define a user name and password using the above attributes and syntax.
» Note All XML tags are case sensitive.
3 Repeat step two for any additional users required.

4 Save and close the users.xml file.
» Note If there are any syntax or other errors in the users.xml file, the
Enterprise Manager will not start.
Generating passwords
The passwords stored in the users.xml file used by the local authentication
mechanism are currently stored as encrypted by default. You have the option to
generate additional passwords using the MD5 scripts. This scripts take input as
plain text and give the encrypted form. However, you can use either plain text or
encrypted passwords by adding them to users.xml.
To generate a password:
1 Run the appropriate script located in <Introscope_Home>\tools:

for Windows, MD5Encoder.bat <password>

CA Wily Introscope
for UNIX, MD5encoder.sh <password>
2 Copy the generated encrypted password, and paste it into the second line of the
users.xml file:
<user password="5b5ab9639b79259f54bc39515540aeaf" name="john"/>
3 You can optionally use a plain text password by inserting a plaintextPasswords
parameter with a true value into the second line of the users.xml file:
<principals xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
plainTextPasswords="false" version="0.3"
4 Save changes to users.xml file.
Default user configuration

The default user configuration defines the following users:
“Admin,” with no password
“Guest,” with Guest as the password

Configuring and managing domains

A Domain in Introscope is a partition of agents and monitoring logic. Agents are
mapped to a Domain using a Perl5 regular expression in the domains.xml file.
Domain types
There are two types of Domains in Introscope:
SuperDomain—The SuperDomain is the superset domain that contains all
user-defined domains in the system. All Agents are visible in the SuperDomain,
but may also appear in user-defined domains. The default Introscope
configuration contains only the SuperDomain. If no other domains are
configured by a user, all agents are mapped to the SuperDomain.
User-defined domain—New domains are defined in the <Introscope_Home>/
config/domains.xml file. The file provides mappings of domain names to
regular expressions.
An AgentDomain is a user-defined domain. This is configured in the
agentclusters.xml file as well as the domains.xml file. For more
information, see The AgAgentDomain on page 225.
Creating Domains
If you add, remove, or edit Domains, the changes are not recognized until the
Enterprise Manager is restarted.
Rules for creating Domains

The rules for creating Domains in the domains.xml file are:
Domain creation must follow valid XML file rules.
Domain names are case-sensitive.
Any Domain must be placed inside the root XML domain’s element.
You may have multiple Agent mappings within a Domain or SuperDomain. If a

Domain is configured to match an agent, then that agent maps to that Domain,
and is also visible from the SuperDomain.
» Note When initiating a transaction trace, such agent will be attached to a
custom domain in the transaction trace window.
An agent will always map to the first Domain it is assigned to. If no Domain
has been assigned, the agent will map to the SuperDomain; if a custom
Domain has been assigned, the Agent will map to the custom Domain.
If you do not alter the current SuperDomain Agent mapping (by default it is
configured to match all Agents), any newly created Domains are placed before

CA Wily Introscope
the <SuperDomain> tags.

Agents that do not match any mappings (either due to mistakes in the regular
expressions in the domains.xml file, or other issues) will be placed in the
SuperDomain.
Domain attributes
These are the attributes for defining a Domain:
Parameter Value Rules

name name of Domain alphanumeric characters only, and _ and
-
no spaces allowed
description short description of any characters except quotation marks

Domain
agent fully qualified Agent The value of agent mapping attribute is
mapping name a Perl5 regular expression
(Domain|host|process| special characters (such as the pipe
Agent) for Agent character) must be escaped with a
backslash
The Agent name defined must match the
actual full Agent name exactly (spelled
correctly and also matching in case) or it
will be placed in the SuperDomain
instead of being mapped to the desired
Domain.
grant user permission Users are granted permissions per
Domain. Domain permissions are
discussed in Defining User and Group
Permissions on page 228.
Domain syntax
The Domain syntax is:
<domain name=”Domainname” description=”Domain description”>

<agent mapping=”host\|process\|agentname or matching agents”/>
<grant user=“username” permission=”permission”/>
</domain>
Creating a Domain and mapping agents

1 Open the file <Introscope_Home>/config/domains.xml in an XML editor.
2 Define any Domains, using the syntax and attributes, and following the rules
described in Rules for creating Domains on page 223.
» Note All XML tags are case-sensitive.

3 Save and close the domains.xml file.

4 Restart the Enterprise Manager so it can load the new Domain(s).
» Note If there are syntax or other errors in the domains.xml file, the
The AgAgentDomain
The AgAgentDomain is defined in the agentclusters.xml file:
- <agent-cluster name="FrontendsAgAgentDomain" domain="AgAgentDomain">

<agent-specifier>.*\|.*\|W[A|L]S.*Agent.*</agent-specifier>
<metric-specifier>Frontends\|.*</metric-specifier>
</agent-cluster>
The AgAgentDomain should also be defined in the domains.xml file. For

example, the following statement should be added:
<domain name="AgAgentDomain" description="anand">

<agent mapping="(.*)"/>
<grant user="Admin" permission="full"/>
<grant user="Guest" permission="read"/>
</domain>
Associating Management Modules with Domains

When you create new Management Modules, you can choose which Domains will
contain them.
You associate Management Modules with Domains by creating directories that

correspond to the names of the Domains you defined in domains.xml, then
moving the Management Modules into the new directories.
1 In <Introscope_Home>/config/modules, create a directory that corresponds

to the Domain name you created in the previous section. For example, if you
created a Domain named “PetstoreA,” in this step, you would create a directory
also named PetstoreA, as in the following example:
<Introscope_Home>/config/modules/PetstoreA
» Note The Domain directory must match the name defined in the domains.xml
file exactly (spelled correctly and also matching in case) or any
Management Modules that reside in the directory will not be loaded.
2 Move the desired Management Module from the <Introscope_Home>/config/

modules directory into the new directory you just created.
3 Restart the Enterprise Manager so it can load the new Domains.

CA Wily Introscope
Adding sample Management Module to newly created Domains

When you create a new Domain, it does not contain any Management Modules.
If you want the newly created Domain to show the default sample dashboards,
you will need to copy the Sample Management Module into the newly created
Domain.
To copy the Sample Management module into the newly created Domain:
1 In the directory, <Introscope_Home>/config/modules/, copy the

SampleManagementModule.jar file to the appropriate modules directory in the
newly created Domain. For example, if you created a Domain called Petstore A,
you would copy the file into the following directory:
<Introscope_Home>/config/modules/PetstoreA
2 Restart the Enterprise Manager so it can load the new Management Module.
» Important The Sample Management Module copied into the new Domain is
not linked in any way to the original Sample Management Module.
Any changes to the original Sample Management Module will not
be reflected in any copies of the Sample Management Module in
other Domains, and vice versa.
Changing the Domain mapping of an Agent

Remapping an Agent to a different Domain, (either after deleting a Domain, or
merging two Domains), has the following ramifications:
If an Agent mapped to a deleted Domain is not reassigned and is still reporting,
it will appear under the SuperDomain
If an Agent has associated SNMP collections, the SNMP MIB will have to be
republished
When an Agent is moved into a different Domain, all shutoff information within
that Agent is lost.
Deleting a Domain
You might need to delete a Domain when you:
assign an Agent to a different Domain
merge two Domains
To delete a Domain and disconnect its associations:
1 Shut down the Enterprise Manager.

2 Delete the Domain from the <Introscope_Home>/config/domains.xml file.
3 If necessary, reassign any mapped Agents to different Domains.

4 Delete the corresponding Domain directory from <Introscope_Home>/config/

modules.
Merging two Domains

Merging two Domains involves merging all Agent mapping information into one
Domain, and moving any associated Management Modules under one Domain.
To merge two Domains:
1 Shut down the Enterprise Manager.

2 Open the <Introscope_Home>/config/domains.xml file.
3 Under the source Domain (for example, Domain A), copy the Agent mapping XML
code information.
4 Under the target Domain (for example, Domain B), paste the Agent mapping XML
code information.
5 Delete Agent mapping XML code from the source Domain (for example, Domain
A).
6 Move any Management Modules from the source Domain (for example, Domain
A) directory in <Introscope_Home>/config/modules/ to the target Domain (for
example, Domain B).
» Note If any Management Modules already exist in the target Domain directory
with the same name as the ones you are moving over, you will need to
rename the Management Modules from the source Domain. If two
Management Modules with the same name exist, the Enterprise Manager
will not start.
7 Delete the source Domain from domains.xml.

Moving a Domain from one Introscope installation to another
Moving a Domain between installations to clone the Domains

If the target installation Domain configuration is exactly the same as the source
installation (all Domains defined in the domains.xml file are going to be exactly
the same), use the following steps:
1 Copy the <Introscope_Home>/config/domains.xml file in the source installation

over to the same directory in the target installation.

CA Wily Introscope
2 Copy the <Introscope_Home>/config/shutoff/

MetricShutoffConfiguration.xml in the source installation over to the same
directory in the target installation.
3 Copy the contents of the <Introscope_Home>/config/modules/<domain>
directory from the source installation to the target installation.
Moving a Domain between non-cloned installations

If the Domain configurations between the old and new installations vary slightly,
follow these steps:
1 Open the <Introscope_Home>/config/domains.xml file in the source installation.

2 Copy the Domain information.
3 Open the <Introscope_Home>/config/domains.xml file in the target installation.
4 Copy the Domain information into the domains.xml file.
5 In the target installation, create new Management Module directories that
correspond to those in the source installation in <Introscope_Home>/config/
modules.
6 Copy any Management Modules that belong to the Domain you are moving over
and paste them into the corresponding Domain directories.
7 Delete the Domain from the source installation.
Defining User and Group Permissions

Setting up permissions for users and groups allows you to define greater
deployment security by:
defining user and group permissions within a specific Domain
defining user and group permissions for the Enterprise Manager
Permissions determine what tasks the user or group can perform including
configuring monitoring logic in the Workstation, or Enterprise Manager
administration tasks.
Permissions in Introscope are defined for Domains and the Enterprise Manager.
Users and groups can be granted permissions to either or both.
Domain permissions are configured in <Introscope_Home>/config/

domains.xml
Enterprise Manager permissions are configured in <Introscope_Home>/config/
server.xml

Permissions rules
Permissions are “fixed” when a user or group logs in; if changes are made for that
while they are logged in, they will not be recognized until the login attempt. This
means if a permissions are changed during a session, the session will not be
terminated.
Introscope permissions are dynamic; the domains.xml and server.xml files are
checked whenever a login attempt is made. Thus, permissions changes can be
made without restarting the Enterprise Manager.
Users are given permissions on domains during log in according to the following
scheme:
All grants listed in each domain which specify the user.
All grants listed in each domain for any group to which the user belongs.
Domain permissions
Domain access rules

The SuperDomain is treated just like any other Domain in terms of
permissions.
Any permissions granted to a user or group with access to the SuperDomain
will also allow them to use these privileges in all user-defined Domains.
One user or group can have multiple permissions for a single Domain.
One user or group can have permissions in multiple Domains.
If a user or group has multiple permissions, use one line for each user/
permission pair.
Defining User and Group Permissions 229

CA Wily Introscope
Domain permissions defined

This table defines the Domain permissions available for users or groups in a
Domain.
Permission Definition
read Users or groups can view all Agents and business logic in Domain.
This includes tasks such as:
Viewing Investigator tree (which will show Agents in the Domain
user has access to)
Viewing dashboards in the Console
Viewing metric and element data in the Investigator Preview pane,
including default Top N Filtered Views for certain Resources in the
Investigator tree
Viewing any Management Module, Agent or Element settings
Viewing Alert messages
Refreshing historical data in a historical Data Viewer, and zoom in
and out
Changing historical date range options for historical Data Viewer
Showing/Hiding metrics in a graph
Moving metrics in a Data Viewer to the back or front
Changing group and user preferences (setting a home dashboard,
displaying Management Module names with dashboard names)
Note: Users or groups with read permission will be able to see all
commands in the Workstation, but the commands they do not
have access to will be disabled.
write A user or group with write permission can do everything a those with
read permission can, but can also:
view all Agents and business logic in Domain
create and edit dashboards
edit all monitoring logic in a Domain
run_tracer Users or groups can start a Transaction Trace Session for an Agent.
Note: This permission also requires the assignment of read
permission.
historical_ag Users or groups can mount and unmount Agent(s).
ent_control
permission.
live_agent_ Users or groups can shut off reporting for Metrics, Resources, and
control Agent within Domain
permission.
full Users or groups have all possible permissions for Domain.

Domain permissions syntax
Here is the syntax for configuring user or group permissions for a Domain:
<grant group="Admin" permission="full"/>

<grant user="Guest" permission="read"/>
Defining Domain permissions

To define Domain permissions for a user or group:
1 Open the <Introscope_Home>/config/domains.xml file in an xml editing

program.
2 For each Domain, define permissions for each user or group, with the above
attributes and syntax.
3 Repeat for any additional users or groups required.

4 Save and close the domains.xml file.
The new value is applied when the Enterprise Manager checks the file during a
hot deploy. This means when someone logs into a domain the domain.xml file
will be consulted then to see if the user has the appropriate permission.
» Note If there are any syntax or other errors in the domains.xml file, the
Default Domain configuration
In the default Domain configuration the following apply. Users and permissions
are case insensitive, meaning if you login using admin or Admin; the
permissions for that user role are applied:
the user or group, “Admin” has full permission in the SuperDomain
the user or group, “Guest” has read (view only) permission in the
SuperDomain
» Note SAP user or group permissions vary slightly and are as follows:
the user or group, “sapsupport” has full permission in the SuperDomain

the user or group, “Admin” has read (view only) permission in the
SuperDomain
Configured Domain example
The following configured Domain permissions example gives Domain permissions

to the following users:
bsmith, full permission in HRApplication Domain
fjones, read and run_tracer permissions in HRApplication Domain

CA Wily Introscope
jlo, write permission in SuperDomain
pdiddy, read permission in SuperDomain
The domains.xml file would look like the following example:

<domains xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="domains0.2.xsd" version="0.2">
<domain name="HRApplication" description="">
<agent mapping="(.*)HRAppAgent(.*)" />
<grant user="bsmith" permission="full" />
<grant user="fjones" permission="read" />
<grant user="fjones" permission="run_tracer" />
</domain>
<SuperDomain>
<agent mapping="(.*)"/>
<grant user="jlo" permission="write"/>
<grant user="pdiddy" permission="read"/>
</SuperDomain>
</domains>
Domain permissions and the Investigator tree

The Investigator tree will look different to users or groups with different Domain
permissions:
Users or groups with SuperDomain permission (at least read permission) can
view the contents of all defined Domains in the Investigator tree.
Users or groups with permissions for multiple Domains will see Domain
information for those Domains in the Investigator tree.
Users or groups with permissions for only one Domain will not see Domain
information in the Investigator tree.

Server Permissions
Server permissions are defined for activities relating to operation of the
Enterprise Manager.
shutting down the Enterprise Manager
publishing MIB files
Server Permissions defined

The following table defines the server permissions available.
Permission Definition
shutdown Users or groups can shut down the Enterprise Manager.
publish_mib Users or groups can publish SNMP collection data to a MIB.
Note: In order to have a MIB to publish, a user must create a
SNMP Collection. This task requires write access to the
Domain the SNMP Collection will be saved to.
full Users or groups have all possible server permissions.
Here is the syntax for configuring user permissions for a server:
<grant user="username" permission="permission">
A user or group can have multiple permissions for the Enterprise Manager. To
grant a multiple permissions, use one line for each user/permission or group/
permission pair.
Defining server permissions

To define server permissions for a user or group:
1 Open the <Introscope_Home>/config/server.xml file in an xml editing program.

2 Define permissions for each user or group, with the above attributes and syntax.
3 Repeat for any additional users required.

4 Save and close the server.xml file.
» Note If there are any syntax or other errors in the server.xml file, the
Default Server configuration
In the default Server configuration, the “Admin” user or group has full
permission.

CA Wily Introscope
Configured Server example
In the following example, we want to give permissions to the following users:

bsmith, shutdown permission
tjones, publish_mib permission
The server.xml file would look like the following example:

<?xml version="1.0" encoding="UTF-8"?> <server xmlns:xsi="http://
www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="users0.1.xsd" version="0.1">
<grant user="bsmith" permission="shutdown" />
<grant user="tjones" permission="publish_mib" />
</server>
Agent Failover and user/domain configuration

If you want to take advantage of the Agent Failover functionality and have users
and passwords defined, you must make sure that the information in the
domains.xml, server.xml, and users.xml files is in sync across the specified
failover Enterprise Managers.
» Note For more information on Agent failover, see Configuring Agent Failover in
the Java Agent Guide or the .NET Agent Guide, as appropriate to your
environment.

CHAPTER
10
Configuring WebView Options
This chapter describes how to configure optional behavior for the WebView
application. It includes these topics:
Configuring WebView for Non-ISO-8859-1 characters . . . . . . . 236

Configuring the WebView application context path . . . . . . . . 236
Running WebView on z/OS . . . . . . . . . . . . . . . . 237
Configuring WebView Options 235

CA Wily Introscope
Configuring WebView for Non-ISO-8859-1

characters
To configure WebView to display non-ISO-8859-1 characters, such as Japanese:
1 In the IntroscopeWebView.properties file, set:

introscope.webview.svg.text.as.images=true
2 In the IntroscopeWebView.lax file, add the -Duser.language and
-Duser.region JVM options to the lax.nl.java.option.additional line.
For instance, to configure WebView for Japanese characters, set the following
JVM options:
-Duser.language=ja -Duser.region=JP
Configuring the WebView application context path

A user can optionally configure the application context path for the WebView
installation. This path will be appended to the fully qualified hostname and port
number of WebView, to form the URL for accessing WebView. This feature allows
the user to define an “application name” for WebView.
If you do not define a context path, access WebView with this URL:
http://servername:port
If you configure a context path, access WebView with this URL:
http://servername:port/contextpath/
For example, if contextpath is defined as webview, and the

introscope.webview.tcp.port property is set to the default value of 8080,
access WebView with this URL:
http://servername:8080/webview/
Configure a WebView context path using the

introscope.webview.context.path property in the WebView properties file.
For more information, see introscope.webview.context.path on page 288.
Restart WebView after setting a new context path.
236 Configuring WebView Options

Running WebView on z/OS

This section contains information and instructions for setting up Introscope
WebView to run on z/OS.
» Note WebView runs only on z/OS 1.7 and later. To run WebView on z/OS, you
must edit the WebView startup script to use a 1.5 JVM. See Editing
runwv.sh to use a 1.5 JVM on page 242.
You can run WebView on z/OS in one of these ways:
as a USS shell script invoked from the command line
as z/OS batch Job
Before you begin
Verify read/write access to configuration directory

Verify that WebView has both read access and write access to the
<Introscope_Home>/config directory, so that any configuration changes can be
properly saved.
Software prerequisites
The software prerequisites to run Java, and hence Introscope WebView, on z/OS
are located in the Java for z/OS Program Directory GI10-0614.
These are the minimum software requirements:
Introscope WebView requires Java 1.5 SR2 or later. Check your OS

documentation to make sure it supports Java 1.5.
UNIX System Services must be enabled.
Language Environment 1.5 or higher.
Java for z/OS.
Security and authorization

Authorization is determined by the RACF profile associated with a user’s USERID.
To successfully start the Introscope WebView, a user must have authority to
access the following resources:
UNIX System Services as specified by the OMVS parameter in the RACF profile
EXEC PGM= BPXBATCH
EXEC WVPROC
Running WebView on z/OS 237

CA Wily Introscope
Virtual memory
If the USS/OMVS address space is not large enough, an out of memory condition
will occur when an attempt is made to run WebView. The OMVS ASSIZEMAX
(address-space-size) parameter in the RACF profile for the owner of the
Introscope WebView job or started task must be large enough to execute the
WebView. The maximum value for this parameter is 2G.
Copying and customizing WebView files

Before WebView can run, the following files (extracted from the Introscope z/OS
installer file) must be copied into the z/OS environment and customized to ensure
compatibility with site-specific requirements:
IntroscopeWebView.properties—the Introscope WebView properties file,

which specifies information pertinent to the operation of the Introscope
WebView
runwv.sh —the shell script used to launch the Introscope WebView process
WVPROC—the z/OS PROC used to execute z/OS BPXBATCH program that

launches the shell script
IntroscopeWebView.properties and runwv.sh are UNIX files that must be

copied into the Hierarchical File System (HFS) on the z/OS platform. These files
will be used by UNIX System Services and Introscope WebView, respectively.
Required changes to these files can be made using a Telnet-based editor such as
vi. Using the USS/OMVS editor can be difficult, because it does not easily handle
insertion of characters that increase line length beyond 72 characters.
Configure WebView for EBCDIC

Enable WebView to write out its messages and logs in EBCDIC (CP-1047) format
by adding these properties to the log4j.appender section of the
IntroscopeWebView.properties file:
log4j.appender.console.encoding=IBM-1047
log4j.appender.console=com.wily.org.apache.log4j.ConsoleAppender
log4j.appender.logfile.encoding=IBM-1047
log4j.appender.logfile=com.wily.org.apache.log4j.RollingFileAppender
Configuring WebView to run as a z/OS batch job

For ease of support in a z/OS environment, it is desirable to run WebView in a
manner familiar to z/OS operations and development staff—either as a z/OS
batch job or a started task. You can also run WebView as a shell process if
desired. This section describes running the Introscope WebView as a batch job or
started task.

Overview
The infrastructure required to run the Introscope WebView as an MVS batch job
or started task is straightforward. The MVS utility program, BPXBATCH, enables
users to invoke UNIX System Services to run shell commands, shell scripts and
executable files in MVS batch. Specifically, WebView can be started using the
BPXBATCH utility.
Copy WebView z/OS files to a z/OS Partitioned Dataset (PDS)

To copy WVPROC into the PDS:
1 Using ISPF, create a partition dataset named userid.JCL.CNTL, (where

userid is the userid assigned to WILY) with fixed block (FBA) 80 byte records.
2 Copy WVPROC into the PDS “userid.JCL.CNTL”, where userid is the userid
assigned to Wily and userid.JCL.CNTL is the name of the previously created
PDS.
3 Do not try to copy the shell script, runwv.sh, or the properties file,
IntroscopeWebView.properties, into this PDS. These are HFS files, and have
lines that are longer than 80 bytes. An attempt to copy them will either fail or
lines will be truncated.
Customize the WebView z/OS PROC that invokes BPXBATCH

1 Edit the Introscope WVPROC using the TSO ISPF editor:
On the ISPF command line, type CAPS OFF and press Enter.
On the ISPF command line, type NUM OFF and press Enter.
Set the IHOME parameter equal to the fully qualified path to the directory that
contains the runwv.sh.
The following statement is coded so that the batch job and the UNIX shell script
will end within 20 seconds:
// PARM='SH nohup &IHOME/runwv.sh &IHOME & sleep 20'
In the unlikely event that the z/OS is too busy to complete WebView initiation
within 20 seconds, WebView will not be started. If you encounter this problem,
try increasing sleep time.
2 Modify the STDERR and STDOUT file names contained in the following statements
to satisfy installation naming conventions:
//STDOUT DD PATH='/<path>/stdout',
//STDERR DD PATH='/<path>/stderr',

CA Wily Introscope
Copy WVPROC into an active PROCLIB

Using ISPF option 3, copy the PROC to xxxx.PROCLIB where xxxx represents a
site-dependent high level qualifier. If WVPROC is not an acceptable name in your
installation, rename the PROC accordingly.
Running as a z/OS batch job

It is important to understand how the user is identified in various contexts:
Batch—When a user submits a batch job through the TSO/E or ISPF interface,
the user’s TSO UserID and password are propagated to the batch job. Provided
the submitted Batch JOB CARD does not explicitly contain a User and
Password, the batch job acquires the same access authority as the TSO user.
If User and Password are coded on the Batch JOB CARD, they override the
UserID and Password of the TSO/E user.
Started Task—If Introscope WebView is initiated as a started task, it runs
under the authorization of the STC user ID. A Site-specific algorithm may be
used to relate the name of the started PROC to a particular UserID. You must
make sure that the algorithm produces a UserID with the correct authorization
to run the Introscope Enterprise Manager.
Running as a started task from the z/OS Console or SDSF

You may run the Introscope WebView as an MVS started task (STC). A started
task is a familiar, operator-friendly environment that allows the Introscope
Enterprise Manager to be started, monitored and cancelled from the MVS console.
In this case, WebView runs under the authorization of the STC user ID, thereby
allowing assignment of specific authorities to the started task.
To run WebView as a started task, type the following command on the MVS
console or on the command line of SDSF:
/start WVPROC
You must type the member name of the PROC stored in an active PROCLIB. If you
were required to change the name of WVPROC, you must use the new name in
the /start command.

Running as a batch job

To run WebView as a batch job, submit the following JCL:
//jobname JOB installation jobcard parameters,NOTIFY=&SYSUID

ISCOPSTP EXEC WVPROC
/*
You must execute the member name of the PROC stored in an active PROCLIB. If
you were required to change the name WVPROC, you must use the new name on
the EXEC statement.
The z/OS batch job and the OMVS Shell will end shortly after WebView processes
have started. If you submitted the batch JCL from your ISPF session and your JOB
card contains NOTIFY=&SYSUID, your ISPF session will receive notification when
your batch jobs ends.
Verifying that the WebView job is running

The most accurate way to determine that the Introscope WebView has started
correctly is to view the STDOUT file. To view STDOUT, you can telnet into the z/
OS and view the STDOUT file defined in the WVPROC. The last line of the file
should indicate that the Introscope WebView has started.
You can also determine that WebView has started from SDSF by following one of
the procedures below:
If you started WebView as a started task, on the DA screen you should see at
least two active started tasks whose owner is the owner associated with the
WebView PROC.
If you started e WebView by submitting a batch job from your TSO session,
look for two active tasks with your TSO USERID as the owner.
You may also see the job that invoked the WVPROC, in addition to the OMVS shell
script. These two entries will disappear from the list once the WebView job has
started.
The owner of your TSO session is also your TSO/E USERID. Do not mistake your
TSO/E session for one of the Introscope WebView tasks.
Starting the Introscope WebView job automatically

To can start the Introscope WebView automatically when JES2 starts:
1 Place the following statement in JES2PARM:

$VS,'start WVPROC'

CA Wily Introscope
2 You must type the member name of the PROC stored in an active PROCLIB. If you
were required to change the name of WVPROC, you must use the new name in the
/start command.
You can also run Introscope WebView as a batch job using whatever job
scheduling package you use to manage your batch workload.
Running WebView from a shell script

To start WebView as a USS/OMVS process from a shell script, use the runwv.sh
file.
Examples of running WebView from the USS command line are:
runwv.sh &
nohup ./runwv.sh &
If you run the script from a directory other than WebViewHome, identify the home
directory as shown below:
nohup ./runwv.sh /WebViewHome &
where WebViewHome is the root of your WebView installation.
Editing runwv.sh to use a 1.5 JVM

To run WebView on z/OS, you must change the default Java Virtual Machine in
the runvw.sh file to enable WebView to run on a 1.5 JVM.
1 Open a command prompt and browse to the Introscope root directory.

2 In a text editor, open the file runwv.sh
3 Locate this line, which sets the location of your Java VM:
JAVAPATH=/usr/lpp/java/IBM/J1.5; export JAVAPATH
4 Edit the line to point the JAVAPATH variable to the root directory of a 1.5 JVM.
For example:
JAVAPATH=/usr/lpp/java/IBM/J1.5; export JAVAPATH
If you prefer, you can comment out the line and add a new line instead of editing
it.
5 Save your changes and exit the text editor.
6 Use the edited runwv.sh script to start WebView.

Writing status information to log file

As WebView starts and runs, it writes status information to a log, which, by
default, appears in the command prompt window (if started normally) and to the
nohup.out file, if started in nohup mode.

CA Wily Introscope

CHAPTER
11
Tailoring your Workstation Configuration
This section describes how to configure optional behavior for the Introscope
Workstation. It includes these topics:
Running Workstation in verbose mode . . . . . . . . . . . . 246

Redirecting Workstation output to a file . . . . . . . . . . . . 246
Configuring Workstation to supply login values . . . . . . . . . 246
Tailoring your Workstation Configuration 245

CA Wily Introscope
Running Workstation in verbose mode

Running the Workstation in verbose mode creates detailed log messages that are
helpful for debugging or troubleshooting.
To run the Workstation in verbose mode:
1 Open the file, IntroscopeWorkstation.properties, in <Introscope_Home>/

config.
2 In the property, log4j.logger.Workstation, replace “INFO” with the
following:
VERBOSE#com.wily.util.feedback.Log4JSeverityLevel
3 Save changes.
Redirecting Workstation output to a file

To redirect Workstation output to a file:
1 Open the file, IntroscopeWorkstation.properties, in <Introscope_Home>/

config.
2 In the log4j.logger.Workstation property, replace “console” with
“logfile.” For example, this property setting causes the Workstation to log
verbose messages to a logfile:
log4j.logger.Workstation=VERBOSE#com.wily.util.feedback.Log4JS
everityLevel,logfile
3 You can change the change the name and location of the Workstation logfile using
the log4j.appender.logfile.File property.
Configuring Workstation to supply login values

You can modify the Introscope Workstation.lax file to supply login values
and bypass the login screen.
To set up command line arguments to bypass the Workstation login screen:
1 Open the file, <Introscope_Home>/Introscope Workstation.lax.

2 In the lax.command.line.args property, add -login commands for each login
command to which to supply a value. For example, using local authentication, this
property might look like this:
lax.command.line.args=$CMD_LINE_ARGUMENTS$ -loginimmediate
-loginhost foos -loginport 4503 -loginresponse
sanderson,45tst87
246 Tailoring your Workstation Configuration

» Note Do not delete the default value, $CMD_LINE_ARGUMENTS$ from the

setting.
If the login is successful (the correct information was supplied in the commands
using the correct syntax), you are logged into the Workstation and a Console
opens.
If login fails, the Workstation does not start, and an error message is logged.
Configuring the Workstation for Asian-language

reports
If you plan to generate Introscope Reports in languages that use multi-byte
character sets such as Chinese and Japanese, follow the instructions here to add
components to your Workstation installation.
To Do this
Generate Asian-language Install the Supplemental Language Support to East
reports in RTF and HTML Asian Languages in Windows. See http://
formats www.microsoft.com/globaldev/handson/user/
xpintlsupp.mspx
Generate Asian-language Download and install the Acrobat Reader Asian Font
reports in PDF formats Pack from http://www.adobe.com/products/
acrobat/acrrasianfontpack.html
Configuring the Workstation for Asian-language reports 247

CA Wily Introscope
248 Tailoring your Workstation Configuration

CHAPTER
12
System Configurations
This section describes Introscope’s overall system configurations. The topics

included are:
Configuring the Clock Skew Tolerance . . . . . . . . . . . . 250

Setting the Maximum Data Point Retrieval Property . . . . . . . . 251
Increasing the Number of Query Results Returned . . . . . . . . 251
System Configurations 249

CA Wily Introscope
Configuring the Clock Skew Tolerance

The Clock Skew Tolerance is the variation of the clock setting adjustments that
are typically done in small increments. For example, setting a slightly fast
running computer clock back a few seconds account for the small alterations you
see in the logs. The variations in this delay cause the clock to timestamp the same
metric at different times, which cause the system to get two metric values for the
overlapping time period.
Turning back time is something that can happen both explicitly (the operator
changes the clock time), or implicitly via automatic clock synchronizations, which
is likely to occur with large installations.
Enterprise Manager addresses Clock Skew Tolerance one of two ways:
For large clock adjustments the system issues an error and exits.
For small backwards clock adjustments, a warning is issued and the harvest
cycle is stopped until the timestamp is as far along as it was previously.
The value of this threshold is set at a default of 60 seconds, but can be
configured. A negative clock adjustment of less than seconds results in a
warning and temporary harvest suspension, while anything greater results in
a system exit.
If the EM detects your system clock has been set back, which is a common
occurrence when a fast CPU clock is reset by a network time service, it will delay
the harvest cycle until the clock catches up to its previous time. This delay is
usually accompanied by a warning message. If you want to suppress warning
messages, you can set the optional
introscope.enterprisemanager.clock.skewsuppresswarn property. The
value of this property is the number of milliseconds the metric harvest will be
delayed before it is considered serious enough to be logged.
To configure the Clock Skew Tolerance threshold:
1 Open the IntroscopeEnterpriseManager.properties file.

2 Add the following property, where <XXX> is a number in seconds:
introscope.enterprisemanager.clock.skewtoleranceseconds=<XXX>
3 Optionally set the
introscope.enterprisemanager.clock.skewsuppresswarn property. The
default value expressed in milliseconds is 0.
» Note This value cannot be set to more than the
introscope.enterprisemanager.clock.skewtoleranceseconds
property, or it will suppress the warnings completely and result in a
system exit.
250 System Configurations

New settings are applied when the Enterprise Manager checks the property file
during a hot deploy, which occurs about once every 60 seconds.
Setting the Maximum Data Point Retrieval Property

The Maximum Data Point Retrieval property should be set as a performance
measure.
It limits the volume of data queried on the Enterprise Manager. If it is not set, it
could cause an Enterprise Manager overload, which will cause your system to
perform slowly and could potentially cause an out of memory error. Additionally,
if not set, it may prompt the Command Line Workstation or Workstation to extract
too much data, which in turn may cause the Enterprise Manager to stop
responding.
To set the Maximum Data Point Retrieval property:
1 Open the Introscope Enterprise Manager.lax file.

2 Add the following property to LAX.NL.JAVA.OPTION.ADDITIONAL:
introscope.enterprisemanager.query.datapointlimit=100000
where 100000 will limit the number of returned data points at approximately
100,000. If no numeric value is entered, no limitation is applied.
The setting is applied when the Enterprise Manager checks the property file
Increasing the Number of Query Results Returned

When RangeQuery, PrefixQuery, WildcardQuery, or FuzzyQuery queries are
performed they are expanded before the search is performed. For example, if the
indexed documents contain the terms "car" and "cars" the query "ca*" will be
expanded to "car OR cars" before the search takes place. This might cause a
system error if this number exceeds the default value of the term threshold,
which is 2048. If this occurs, a TooManyClauses exception will be returned.
To increase the number of query results returned:
1 Go to <Introscope_Home>\config and open

IntroscopeEnterpriseManager.properties.
2 Add the following property with a higher value then its default value of 2048:
introscope.enterprisemanager.lucene.search.BooleanQuery.SetMaxCl
auseCount
The setting is applied when the Enterprise Manager checks the property file
Setting the Maximum Data Point Retrieval Property 251

CA Wily Introscope
252 System Configurations

APPENDIX
A
Introscope Properties Files
The properties files in the following folders allow you to control the settings the
Enterprise Manager, Workstation, and WebView:
File Name Location Description

IntroscopeEnterpriseMana <Introscope_Home>/ A variety of Enterprise Manager behaviors are
ger.properties config controlled by properties defined in this file.
Introscope Enterprise <Introscope_Home> The runtime behavior of the EM is controlled by

Manager.lax properties defined in this file.
EMService.conf File <Introscope_Home> The EMService.conf file, in
<Introscope_Home> contains settings used
when the Enterprise Manager is run as a
Windows Service.
IntroscopeWorkstation.pro <Introscope_Home>/ A variety of Workstation behaviors are
perties config controlled by properties defined in this file.
Introscope Workstation.lax <Introscope_Home> The runtime behavior of the Workstation is

controlled by properties defined in this file.
IntroscopeWebView.proper <Introscope_Home>/ A variety of WebView behaviors are controlled
ties config by properties defined in this file.
Introscope WebView.lax <Introscope_Home> The runtime behavior of WebView is controlled

by properties defined in this file.
Note: On Windows machines, when adding a path in the properties files you must escape a backslash
(\) with another backslash (each one doubled)—for example C:\\Introscope\\lib\\Agent.jar.
Introscope Properties Files 253

CA Wily Introscope
IntroscopeEnterpriseManager.properties
A variety of Enterprise Manager behaviors are controlled by properties defined in
the Enterprise Manager properties file,
IntroscopeEnterpriseManager.properties.
After configuring most Enterprise Manager properties, you must restart the
Enterprise Manager before any changes you make will take effect.
Some Enterprise Manager properties, however, use the Introscope hot

configuration service. You do not need to restart the Enterprise Manager after
making changes to those properties. For more information, see Hot Configuration
Service on page 259.
Available Processors . . . . . . . . . . . . . . . . . . 255

Alert Behaviors . . . . . . . . . . . . . . . . . . . 255
Communications . . . . . . . . . . . . . . . . . . . 256
Hot Configuration Service . . . . . . . . . . . . . . . . 259
Application Heuristics . . . . . . . . . . . . . . . . . 260
Logging . . . . . . . . . . . . . . . . . . . . . . 260
Persistent Collections—Recording Data to a Database . . . . . . . 262
Flat File Properties . . . . . . . . . . . . . . . . . . 263
Enterprise Manager Metric Clamping . . . . . . . . . . . . . 264
SmartStor . . . . . . . . . . . . . . . . . . . . . 265
Transaction Event Database . . . . . . . . . . . . . . . 267
Transaction Trace Sampling . . . . . . . . . . . . . . . 269
Baseline Data Storage . . . . . . . . . . . . . . . . . 270
SNMP Collections . . . . . . . . . . . . . . . . . . . 270
WebView . . . . . . . . . . . . . . . . . . . . . 270
Management Module Bootstrapping . . . . . . . . . . . . . 270
Management Module Deployment . . . . . . . . . . . . . . 271
JavaScript Deployment . . . . . . . . . . . . . . . . . 271
Clustering Settings . . . . . . . . . . . . . . . . . . 271
Agent interactions . . . . . . . . . . . . . . . . . . 274
MOM Hot Failover . . . . . . . . . . . . . . . . . . . 275
Configuration directory . . . . . . . . . . . . . . . . . 275
254 Introscope Properties Files

Available Processors
Available Processors
Property Description Default
Value
introscope.enterprisemanager. Use this property to set the number of processors <blank>
availableprocessors available to this EM. It should be used if there is more
than one Enterprise Manager on a host.
Alert Behaviors
Alert Behaviors
Value
introscope.enterprisemanager. Name of the Investigator node under which Alert state Alerts
alertstatemetric.prefix metrics are shown.
IntroscopeEnterpriseManager.properties 255
CA Wily Introscope
Communications
Communications
Value
introscope.enterprisemanager. Specifies the communication channels that the channel1
enabled.channels Enterprise Manager can use. To enable a
communication channel, add the channel type to the
comma separated list of enabled channels. To disable a
communication channel, remove it from the list.
The enabled.channels property works in conjunction
with the
property.
For example:
If you have two communications channels called
channel1 and channel2, you would set these properties:
introscope.enterprisemanager.enabled.channels=ch
annel1,channel2
1
2
introscope.enterprisemanager. This listener port that the Enterprise Manager uses for 5001
port.<ChannelName> encrypted communication with Workstations and
Agents.
To create a custom communication channel, add these
properties to the properties file:
introscope.enterprisemanager.port.ChannelName
introscope.enterprisemanager.serversocketfactory.Ch
annelName
where ChannelName is the name of the new channel.
To enable the custom channel, add its name to the
property.

Communications
Value
introscope.enterprisemanager. This property identifies the classname of the Server com.wily.isen
serversocketfactory.<ChannelN Socket Factory that the Enterprise Manager uses for gard.postoffic
ame> encrypted communication with Workstations and ehub.link.net.
Agents. DefaultServer
If you create a custom communication channel, add a SocketFactory
new property to the properties file, for instance,
introscope.enterprisemanager.serversocketfacto
ry.ChannelName
where ChannelName is the name of the new channel,
and set the property value to the fully qualified
classname of the custom Server Socket Factory that
implements the
com.wily.isengard.postofficehub.link.net.
IServerSocketFactory interface.
You must also specify the listener port for the channel,
and enable it, as described in
on page 256.
For example, if you have two communications channels
called channel1 and channel2 set like this:
=channel1,channel2
introscope.enterprisemanager.port.channel1=
5001
introscope.enterprisemanager.port.channel2=
5002
you would set the serversocketfactory property like
this:
introscope.enterprisemanager.serversocketfact
ory.channel1=<classname>
introscope.enterprisemanager.serversocketfa
ctory.channel2=<classname>
introscope.enterprisemanager. Set this property to true to allow a communication False
serversockets.reuseaddr channel server socket to rebind to a local port that is
stuck in a FIN_WAIT or TIME_WAIT state. Once the
EM starts up again, this property should be disabled.
Do not enable this property by default, since there may
be a valid reason that the port is already in use.
CA Wily Introscope
Communications
Value
introscope.enterprisemanager. Disables interactive console (whether or not the console true
disableInteractiveMode accepts input).
Note: On many UNIX platforms, nohup will not work
if the application is trying to read from standard
input. To run in nohup mode, set this property
to true, and change the lax.stdin.redirect
property in the Introscope Enterprise
Manager.lax file to <blank>. If both of these
properties are not set exactly as stated above,
it can either render the application unable to
start up in nohup, or cause maximum CPU
utilization.
introscope.enterprisemanager. The port on which the Enterprise Manager’s embedded 8081
webserver.port Web server listens.
introscope.enterprisemanager. The maximum number of listener threads in the Web 100
webserver.max.threads server—that is, the number of concurrent HTTP clients
that can be served by the Enterprise Manager’s
embedded Web server.
Note: Configure this property only if more than 80
HTTP tunneling agents are connecting to this
Enterprise Manager. In this situation, CA
recommends setting the property value to 20
more than the maximum number of connecting
HTTP tunneling agents. If you expect fewer
than 80 concurrent HTTP Agents, do not modify
this property value.

Communications
Value
introscope.enterprisemanager.i Binds all Enterprise Manager communication channels, <Red
paddress including the embedded Web server, to a specific local Font>PLAC
IP address. EHOLDER
When this property is not configured, the Enterprise
Manager accepts connections on all local addresses.
Rules to consider when configuring this property:
If this property is configured to a IPv4 address, the
EM will only accept connections from agents or clients
on machines running an IPv4 compliant JVM.
If the property is configured to an IPv6 address, the
EM will only accept connections from agents or clients
on machines running an IPv6 compliant JVM.
If you do not bind the EM or WebView instance to a
specific IP address, it can accept connections from
both IPv4 and IPv6 environments.
Workstations, Agents, Browsers, and other clients
should use the DNS name, not the IP address, to
connect to the EM or WebView instance.
IPv6 support on the Agent is dependent upon IPv6
support in the environment (JVM, operating system,
hardware stack) in which the agent is running.
introscope.enterprisemanager. Specifies the channel for connecting to the WebStart channel1
workstation.connection.channel Workstation.
Hot Configuration Service

The Enterprise Manager includes a hot configuration that is enabled by default for
these properties:
log4j logging properties—see Logging on page 260
clustering properties—see Clustering Settings on page 271
Hot Configuration Service

Value
introscope.enterprisemanager. Enables the hot configuration service. Set to false to true
hotconfig.enable disable the service.
introscope.enterprisemanager. Specifies how often to check this file for changes, in 60 seconds
hotconfig.pollingInterval seconds.
CA Wily Introscope
Application Heuristics
Application Heuristics
Value
introscope.enterprisemanager. To improve Enterprise Manager performance, you can true
application.overview.baselines turn off heuristics by setting the property to false.
If you do this the Enterprise Manager turns off the
Enterprise Manager’s assessment of JVM, application,
and backend health. It also turns off the Baseline
Engine, which means that matrices in the Workstation
will be inactive and report no values. They will appear
gray unless the configuration is set back to true, at
which point they will be active again.
Logging
Logging properties define the level of detail in the Enterprise Manager logs and
the name and location of Enterprise Manager log files. See Log4J documentation
at http://jakarta.apache.org/log4j/docs/documentation.html for information on
advanced Log4J functions.
Logging
Value
log4j.logger.Manager Controls the level of detail, and destination for log INFO,
messages. console,
Level of detail value can be: INFO or logfile
VERBOSE#com.wily.util.feedback.Log4JSever
ityLevel.
Destination value can be console or logfile. The default
setting writes log information to the console and the log
file.

Logging
Value
log4j.appender.logfile.File Name and location of Enterprise Manager logfile, logs/
relative to the Introscope home directory. IntroscopeEn
terpriseMana
ger.log
log4j.appender.logfile.layout.C Allows you to customize your log files. <blank>
onversionPattern The property can be set the following values:
d{M/dd/yy hh:mm:ss a z} [%-3p] [%c] %m%n
The pattern is implemented in the log4j library and the
format is described here: http://logging.apache.org/
log4j/docs/api/org/apache/log4j/PatternLayout.html
The date/time format appears in the %d{..} and
follows a pattern described here: http://
java.sun.com/j2se/1.4.2/docs/api/java/text/
SimpleDateFormat.html
CA Wily Introscope
Persistent Collections—Recording Data to a Database

You can configure the properties described in this section to record traced data
to an external, relational database. For more information, see the SQL Database
Settings section of the IntroscopeEnterpriseManager.properties file.
These settings are all deployed via hot configuration, so they do not require a
manual restart of the Enterprise Manager.
Introscope includes an API that enables you to extract metric and event data for
historical ranges, then use a data analysis tool such as Excel or SAS to view
Introscope data. CA recommends that you use this API record data—see Using
the JDBC API on page 123. You can also use the Command-Line Workstation
commands for extracting persisted data—see Using the Command-Line
Workstation on page 163.

Value
introscope.enterprisemanager. This is the agent regular expression property. Add this <blank>
database.collection.agentExpre setting to the
ssion IntroscopeEnterpriseManager.properties file
and it will be deployed via hot configuration.
For example:
Introscope.enterprisemanager.database.col
lection.agentExpression=rhart-
dt1\\|EPAgentProcess1\\|EPAgent5
introscope.enterprisemanager. This is the metric regular expression property. Add <blank>
database.collection.metricExpr this setting to the
ession IntroscopeEnterpriseManager.properties file
For example:
introscope.enterprisemanager.database.col
lection.metricExpression=Servlets\\|MySer
vlet:Average Response Time \$ms\$


Value
introscope.enterprisemanager. Where agentExpression is the agent regular none
database.collection.frequencyin expression, metricExpression is the metric regular
seconds expression, and frequencyinseconds is the frequency
in seconds to aggregate the data and write it to the
database. Add this setting to the
IntroscopeEnterpriseManager.properties file
Note: There is no default setting as each persistent
collection can have a different value. This
property should be set for each persistent
collection.
introscope.enterprisemanager. The maximum number of metric data points on the 150k
database.recordingQueue.uppe queue. A metric data point is one time slice of data for (thousand)
rLimit.value one metric. This setting will be deployed via hot
configuration.
Flat File Properties

Flat files are plain-text comma-separated value (.csv) files. Introscope can write
to flat files, but cannot read from them. You can analyze flat files with numerical
analysis tools.
Flatfile recording is enabled by default and directed to the

<Introscope_Home>/flatfiles directory. You can also specify that these files
reside in a directory outside of the Introscope directory. Note that for Windows
paths, you must escape backslashes (\) with another backslash (doubled), for
example: C:\\Introscope\\FlatFileDir.
CA Wily Introscope
Enterprise Manager Metric Clamping

These properties define the limits set for the number results you get for metrics
from a standalone EM or Collector. They are hot configurable meaning the values
are applied when the Enterprise Manager checks the property file during a hot
deploy. A hot deploy occurs about once every 60 seconds.

Value
introscope.enterprisemanager. Number of metrics the Agent reports before it is shut 50000
agent.metrics.limit off. The default number of metrics is 50,000, but an
inappropriately configured Agent can create thousands
of metrics in quick succession, overloading the
Enterprise Manager.
Use this property to prevent metric overload. If an
Agent generates more than the specified number of
metrics, the Enterprise Manager will drop them. If this
occurs, modify the Agent’s configuration to reduce the
volume of metrics reported. For more information, see
the Java Agent Guide or .NET Agent Guide.
introscope.enterprisemanager. This property limits live metrics currently reporting 500000
metrics.live.limit from Agents. When the EM detects that it has exceeded
the limit, the EM will stop all Agents from registering
new metrics. The limit is checked every 15 seconds, so
the EM may go above this value before the clamp is
applied. Old metrics will continue to report. Metrics for
which we have historical data will never be clamped.
For example, if an Agent has 60k metrics it has reported
to an EM before clamping, and then the clamp of 50k is
applied; all 60k old metrics can still register with the
EM. If however, any new metrics attempt to register for
which we historical data is not already collected, then
they will not be allowed to register.


Value
introscope.enterprisemanager. This property limits the number of historical metrics in 1200000
metrics.historical.limit the EM. The limit is checked every 15 seconds, so the
EM may go above this value before the clamp is applied.
When the EM detects that it has exceeded this limit, the
EM will stop all Agents from registering new metrics.
Old metrics will continue to report.
introscope.enterprisemanager. The property defines the maximum metric data points 0 (Where 0
query.datapointlimit the EM will return from any one query. The clamp is for means there
each query and not for multiple concurrent queries. is no limit.)
For example, if the limit is set to 10000 and one user
makes a query that returns 11000 data points, while
another user makes a query that returns 8000 data at
the same time. Then the first user’s query is limited to
10000 data points and the second user will have the
ability to continue performing their query.
Note: You cannot set this property to clamp a query
for a MOM.
SmartStor
The properties in this section define the directory where SmartStor data is stored,
and configure data collection and aging behavior for three tiers of storage. It also
allows you to disable SmartStor if desired.
» Note All three tiers must be defined. You cannot define more than three tiers.
SmartStor
Value
introscope.enterprisemanager. Allows you to enable or disable SmartStor. While True
smartstor.enable disabling SmartStor will save disk space, it will not store
statistics and you will be prevented from monitoring
them.
Set to False to disable SmartStor.
Note: If you do not see the property in the SmartStor
section, then SmartStor is enabled. To disable
SmartStor add the following line to the
properties file:
introscope.enterprisemanager.smarts
tor.enable=false
introscope.enterprisemanager. Specifies the directory, relative to the Enterprise data
smartstor.directory Manager home directory, that SmartStor will use.
CA Wily Introscope
SmartStor
Value
introscope.enterprisemanager. Specifies the directory that SmartStor will use to data/archive.
smartstor.directory.archive store archived data.
introscope.enterprisemanager. Specifies whether SmartStor data is written to a false
smartstor.dedicatedcontroller dedicated disk.
Set to true if SmartStor data is being written to a
dedicated disk.
introscope.enterprisemanager. Specifies the frequency (in seconds) of data collection 15
smartstor.tier1.frequency for the first data tier. The frequency:
must be a multiple of 15 seconds.
must not be greater than 1800 seconds (30 minutes).
must be an even multiple of the previous tier's
frequency—this multiple can be one; each tier can
have the same frequency).
introscope.enterprisemanager. Specifies the number of days after which data in first 7
smartstor.tier1.age tier ages out of SmartStor. The value cannot be zero.
smartstor.tier2.frequency for the second data tier. The frequency:
introscope.enterprisemanager. Specifies the number of days after which data in second 23
smartstor.tier3.frequency for the third data tier. The frequency:
introscope.enterprisemanager. Specifies the number of days after which data in third 335

Transaction Event Database

The Enterprise Manager stores captured transaction events locally on its file
system for a fixed length of time or until a maximum disk usage is exceeded. You
can control where to store these events and when they should be deleted by
setting the transaction event database properties.

Value
introscope.enterprisemanager.t Specifies the location, relative to the Enterprise traces
ransactionevents.storage.dir Manager home directory, where Introscope stores
transaction event data.
introscope.enterprisemanager.t Specifies, in days, how long to store transaction event 14
ransactionevents.storage.max. data.
data.age
introscope.enterprisemanager.t Determines the maximum desired disk usage in MB for <blank>
ransactionevents.storage.max. the trace storage. If this maximum is exceeded, then the
disk.usage daily historical trace stores will be deleted starting with
the oldest first until the total historical trace storage size
is below this value entered. Even if the size of this
property value is exceeded, stored traces may not be
deleted because the size of the trace index is not
considered when determining what historical trace stores
to delete.
A negative or zero value indicates that all historical trace
valueslstored should be deleted.
If the Perst database is larger than this value, historical
storage files are deleted until the total database size is
less than this value, starting with the oldest storage file.
This might delete historical data even if it has not
reached the fully aged date. The current live storage is
not deleted, even if its size exceeds the max database
size.
If you determine that the Perst database is too large, you
can delete database files manually, when the Enterprise
Manager is shut down. When the Enterprise Manager is
restarted, the transaction trace storage system
recognizes that the files have been deleted manually and
adjusts the trace index accordingly.
Note: If you delete files manually, delete only files in
the traces directory that have this format:
traces_yyyyMMdd.db, where yyyyMMdd
represents the year, month, and day of the
traces in that file.
Do not delete any other files in that directory or
subdirectory.
CA Wily Introscope

Value
introscope.enterprisemanager.t Specifies how often, in hours, the trace storage should be 24 hours
ransactionevents.storage.optim optimized by cleaning up aged data.
ize.frequency Enables aging of transaction trace data when the
Enterprise Manager starts.
introscope.enterprisemanager.t Specifies the time offset for storage optimization, which 02 (2AM)
ransactionevents.storage.optim allows you to schedule purges to start on a specific hour
ize.timeoffsethour of every day against the time offset.
For example, if the time offset is set to 02 and
optimize frequency (see
introscope.enterprisemanager.transactionevents.stor
age.optimize.frequency on page 268) is set to 24
hours, optimization will run every 24 hours offset
from time 02:00AM.
Note: Entering a 00 value for this property will display
an error message, as this value must be a
positive integer.

Transaction Trace Sampling

These transaction trace sampling properties are located, by default, in Enterprise
Manager properties file.
Transaction Trace Sampling

Value
introscope.agent.transactiontra Configured for 1 sample trace by default. This property 1
cer.sampling.perinterval.count works in conjunction with the
introscope.agent.transactiontracer.sampling.interval.se
conds property.
You can change the number of traces per interval to
trace, by modifying its value and uncommenting it in the
properties file.
introscope.agent.transactiontra Configured to trace every 2 minutes by default. This 120 seconds
cer.sampling.interval.seconds property works in conjunction with the
introscope.agent.transactiontracer.sampling.perinterval
.count property.
You can change the sampling interval by modifying its
value and uncommenting it in the properties file.
Note: Before overriding the defaults for the
sampling.perinterval and sampling.interval
properties, consider the potential for increased
load in the Enterprise Manager with higher
sampling rates.
CA Wily Introscope
Baseline Data Storage
Baseline Data Storage

Value
introscope.enterprisemanager. Specifies the filename, and its location relative to the data/
dbfile Enterprise Manager home directory, of the database in baselines.db
which Introscope stores metric baseline information.
SNMP Collections
SNMP Collections
Value
introscope.enterprisemanager. Enables SNMP Agent (only relevant if you have installed false
snmp.enable SNMPServices.jar)
introscope.enterprisemanager. Enterprise Manager port that communicates with the 161
snmp.agent.port SNMP Agent
WebView
WebView
Value
introscope.enterprisemanager. Determines whether WebView can establish a connection false
webview.disableLogin with Enterprise Manager.
introscope.enterprisemanager. Specifies password WebView users to connect to WebView
webview.password Enterprise Manager.
Management Module Bootstrapping

Value
introscope.enterprisemanager. Logs invalid references as warnings. If set to true, invalid false
managementModules.invalid.re references will prevent the Enterprise Managerfrom
ferences.as.errors starting.

Management Module Deployment

Value
introscope.enterprisemanager. Defines the directory, relative to the Introscope home deploy
hotdeploy.directory directory, to check for updated applications to deploy.
introscope.enterprisemanager. Specifies how often, in seconds, to check for updated 60
hotdeploy.checkFrequencyInSe Management Modules to deploy.
conds
JavaScript Deployment
JavaScript Deployment
Value
introscope.enterprisemanager.j Defines the directory, relative to the Introscope home scripts
avascript.dir directory, to check for updated JavaScript files to deploy.
introscope.enterprisemanager.j Specifies how often, in seconds, to check for updated 60
avascript.refresh JavaScript files to deploy.
Clustering Settings
For more information about Enterprise Manager clustering, see When to cluster
Enterprise Managers on page 38.
Clustering Settings
Value
introscope.enterprisemanager. Setting this property to true identifies the Enterprise false
clustering.manager.enable Manager as the Manager of Managers, or MOM, in a
cluster of Enterprise Managers.
introscope.enterprisemanager. Set this property to define the threshold for the ping 10000 (in
clustering.manager.slowcollect metric for your environment. The ping metric monitors milliseconds)
orthreshold only the lower boundary of the round-trip response time
from the MOM to each Collector.
CA Wily Introscope
Clustering Settings
Value
introscope.enterprisemanager. Set this property to define the threshold for which the 60 (in
clustering.manager.slowcollect MOM will automatically disconnect from the Collector if seconds)
ordisconnectthresholdseconds exceeded. This will prevent the entire cluster from
hanging, which is a side effect of when one Collector in a
cluster is greatly under performing.
If this property is set to zero or a negative value, which
is not recommended, this will not be enabled.
Note: The MOM checks collectors every 7.5 seconds, so
small changes will not affect its behavior.
introscope.enterprisemanager. Hostname or IP address of the Collector Enterprise <blank>
clustering.login.<emName>.ho Manager.
st
introscope.enterprisemanager. Value of the Collector Enterprise Manager’s <blank>
clustering.login.<emName>.po introscope.enterprisemanager.port.<ChannelName>
rt property.
introscope.enterprisemanager. Specifies the public key for encrypting the password the config/
clustering.login.<emName>. MOM uses to connect to a Collector Enterprise Manager. internal/
publickey server/
EM.public,
commented
out
introscope.enterprisemanager. Specifies the private key a Collector Enterprise Manager config/
clustering.privatekey uses to decrypt the password the MOM uses to connect internal/
to it. server/
EM.private
introscope.enterprisemanager. Set to true to identify an Enterprise Manager as a false
clustering.collector.enable Collector, for clustering. If an Enterprise Manager is
configured for both the Manager of Managers role and
the Collector role, the Enterprise Manager becomes the
Collector.
If the Enterprise Manager is designated a Collector
during installation, the installer configures this property.
If the Enterprise Manager is designated a Manager of
Managers (MOM), the installer can configure up to 5
collectors. If you want a MOM to track 6 or more
collectors, set this property manually.
You can also use this property if you configured the
Enterprise Manager standalone during installation, then
decide later it will be part of a cluster.
introscope.enterprisemanager. Optional. You can set this property if you want to give false
clustering.collector.identifier this Collector a descriptive name.
If you don’t specify an identifier, Introscope uses the
default identifier of host@port, where host is the EM's
host name, and port is the EM's connection port.

Clustering Settings
Value
introscope.enterprisemanager.l Set this property to define the tolerance of the Load 20000
oadbalancing.threshold Balancer for imbalance. The number of metrics in a (metrics)
collector must differ from the weight-adjusted cluster
average (i.e. the average for all collectors) by at least
the threshold before the Load Balancer rebalances the
cluster.
Rebalancing means redistributing Agents among
collectors to equalize the weight-adjusted metric load.
For more information, see Clustering and Load Balancing
on page 40.
introscope.enterprisemanager.l Set this property to determine how often the Load 600 (10
oadbalancing.interval Balancer should rebalance in seconds. The minimum minutes)
value, is 120 seconds.
introscope.enterprisemanager. Set this optional property to control the relative load of Average
clustering.login.em1.weight the collector. value for the
All other things being equal, the weight divided by the cluster, with
total weight for the cluster is the percentage of metric the weight
load assigned to that collector. For example, if the weight being the
of a collector is 50 and the sum of the weights of all load
collectors is 250, the collector should get 20% of the balancing
cluster's metric load. weight for
this
Enterprise
Manager
collector.
CA Wily Introscope
Agent interactions
Most agent interaction properties are not included in the Enterprise Manager
properties file. To change their default values, add them to the
IntrscopeEnterpriseManager.properties file. After adding the properties to
the file, you must shutdown and restart the Enterprise Manager to enable the new
values.
Agent interactions
Value
introscope.enterprisemanager. Controls whether or not the Enterprise Manager True
agentconnection.metrics.enabl generates Agent connection metrics.You can set this
e to True or False.
Note: This property is not included in the Enterprise
Manager properties file. To change the value,
add the property to the properties file and
restart the Enterprise Manager to enable the
property.
introscope.enterprisemanager. Specifies how many minutes after an agent disconnect 30
agentconnection.metrics.agent the Enterprise Manager stops generated connection (minutes)
TimeoutInMinutes metrics for the agent.
property.
ntroscope.enterprisemanager.a Number of metrics the agent reports before it is shut off. 50000
gent.metrics.limit The default number of metrics is 50,000, but an
inappropriately configured agent can create thousands of
metrics in quick succession, overloading the Enterprise
Manager. You can use this property to prevent this
metric overload.
property.
introscope.enterprisemanager. Number of minutes the Enterprise Manager continues to 60 (minutes)
autoUnmountDelayInMinutes track an agent after the agent is disconnected, in case
the disconnection is temporary. After this time runs out,
the Enterprise Manager releases agent tracking
resources.

MOM Hot Failover

These properties allow you to enable and apply Hot Failover settings, which can
be used for enterprise managers sharing the same installation directories. When
setting these properties, you might want to consider the Hot Failover rules on
page 44.
MOM Hot Failover

Value
introscope.enterprisemanage This property enables Hot Failover. false
r.failover.enable
introscope.enterprisemanager.f This property allows you to set the hostname or IP <blank>
ailover.primary address of the primary EM. To configure both EMs as
primary, set to a comma-separated list of hostnames or
IP addresses of the primary EMs. The following is an
example of both EMs configured as primary:
introscope.enterprisemanager.failover.prim
ary=myhost1, myhost2.
introscope.enterprisemanage This property allows you to set the hostname or IP <blank>
r.failover.secondary address of the secondary EM by specifying the
hostname or IP address of the EM's host. For
example,
introscope.enterprisemanager.failover.seco
ndary=myhost2.
introscope.enterprisemanager.f This property allows you to set in seconds how often a 120
ailover.interval running secondary EM checks to see if a primary EM is (2 minutes)
waiting to start. This setting is deployed via hot
configuration.
Configuration directory
This property allows you to specify the location of the Enterprise Manager config
directory.
Configuration directory
Value
introscope.enterprisemanager. The directory the EM will use for configuration. In The config
directory.config Windows, backslashes must be escaped (doubled). For directory in
example: C:\\Introscope\\config the original
Introscope
installation.
CA Wily Introscope
Introscope Enterprise Manager.lax

The runtime behavior of the EM is controlled by properties defined in this file.

Value
lax.class.path The Java classpath necessary to run this application. Can <blank>
be appended with a JDBC driver and license.
Default: lib/EnterpriseManager.jar:lib/
WebServices.jar:lib/IntroscopeClient.jar:lib/
SNMPAdapter.jar:lib/Workstation.jar:lib/
IntroscopeServices.jar:lax.jar
For SAP installations, the default is:
lib/EnterpriseManager.jar:lib/
WebServices.jar:lib/IntroscopeClient.jar:lib/
SNMPAdapter.jar:lib/Workstation.jar:lib/
IntroscopeServices.jar:lib/WebViewAPI.jar:lib/
WebViewServer.jar
lax.command.line.args This is passed to the main method. When entering this <blank>
value, be sure to quote arguments with spaces. For
example,
lax.command.line.args=$CMD_LINE_ARGUMENTS$
-consolelog -noExit -product
com.wily.introscope.em.product -install
".\\product\\enterprisemanager" -
configuration
".\\product\\enterprisemanager\\configurat
ion"
lax.dir The path to the directory holding LaunchAnywhere's <blank>
native launcher.
lax.main.class The class that contains the main method for the main
application. For example,
lax.main.class=org.eclipse.core.launcher.M
ain.
lax.main.method The main method of LaunchAnywhere's java launcher. main
This property should not be adjusted from its default
value:
lax.nl.java.launcher.main.method=main.
lax.nl.current.vm This property represents the virtual machine to be used The default
the next time the Enterprise Manager is started. It can value varies
be set to use an installed JDK or JRE version 1.5.0_15. by Operating
For example, if you are configuring this property to use System.
the bundled JVM provided, it would displays as follows:
lax.nl.current.vm=jre\bin\java.exe


Value
lax.nl.java.launcher.main.class The main class of LaunchAnywhere's java launcher. This com.zerog.la
property should not be adjusted from its default value: x.LAX
lax.nl.java.launcher.main.class=com.zerog.
lax.LAX
lax.nl.java.launcher.main.meth The main method of LaunchAnywhere's java launcher. main
od This property should not be adjusted from its default
value: lax.nl.java.launcher.main.method=main
lax.nl.java.option.additional Initial minimum and maximum heap sizes -Xms128m -
Xmx512m
lax.nl.message.vm.not.loaded The message displayed in a user dialog if no virtual The
machine from the lax.nl.valid.vm.list can be found. lax.nl.messa
This property is internal to the InstallAnywhere launcher. ge.vm.not.l
Introscope has separate Java requirements. For more oaded=Laun
information, consult the "System Requirements". chAnywhere
either could
not find a
Java VM, or
the Java VM
on this
system is
too old.
LaunchAnyw
here
requires a
Java 2 VM in
order to
launch
Introscope.
lax.nl.valid.vm.list A string containing one or more of [ ALL JDK JRE J1 J2
J2 JRE_J1 JDK_J1 JRE_J2 JDK_J2 MSJ ] delimited
by spaces or commas. If the native launcher cannot find
the current virtual machine, it will search for ones in this
list: lax.nl.valid.vm.list=J2
lax.nl.win32.microsoftvm.min.v The minimum version of Microsoft's virtual machine with 2750
ersion which this launcher will run. For example,
lax.nl.win32.microsoftvm.min.version=2750.
lax.root.install.dir The path to the installdir magic folder. For example, <blank>
lax.root.install.dir=.
lax.stderr.redirect Standard Error Output. Leave blank for no output, console
console to send to a console window, or any path to a file
to save to the file.
Introscope Enterprise Manager.lax 277

CA Wily Introscope

Value
lax.stdin.redirect Set to blank for no input, console to read from the console
console window, and any path to a file to read from that
file.
If you are running the Enterprise Manager in nohup mode
for UNIX platforms, do NOT change this setting, or the
Enterprise Manager may fail to start.
If local requirements dictate that you set this property to
blank, you MUST set
true.
lax.stdout.redirect Standard Output. Leave blank for no output, console to console
send to a console window, or any path to a file to save to
the file.
lax.user.dir This property will cause the native launcher to not alter <blank>
the platform default behavior for setting the user
directory if left blank. To override this you may set this
property to a relative or absolute path with relative paths
being relative to the launcher. For example,
lax.user.dir=.
lax.version The version of LaunchAnywhere that created the 8.0
properties file. For example, lax.version=8.0.

EMService.conf File
The EMService.conf file, in <Introscope_Home> contains settings used when the
Enterprise Manager is run as a Windows Service.
» Note Before configuring these properties, you must unregister the Enterprise
Manager Service. After configuring properties, re-register the Enterprise
Manager Service.
EMService.conf File
Value
wrapper.java.command The Java application wrapper command. jre\\bin\\jav
a.exe
wrapper.java.mainclass The Java main class wrapper command. org.tanukisof
tware.wrapp
er.WrapperSi
mpleApp
wrapper.java.classpath.x The Java Classpath that includes the wrapper.jar. n/a
Class path elements should be added in a sequential
manner, such as follows:
wrapper.java.classpath.1=./lib/
ServiceWrapper.jar
wrapper.java.classpath.2=./launcher.jar
wrapper.java.classpath.3=
wrapper.java.library.path.1 The Java library path is the location of the Wrapper.DLL ./lib
or libwrapper.so .
wrapper.java.additional.x= Additional Java parameters that are applicable only on -Xrs
64-bit Windows.
The first additional parameter must be -Xrs. From there
you can add parameters as needed. For example:
wrapper.java.additional.1=-Xrs
wrapper.java.additional.1=-
Djava.awt.headless=false
wrapper.java.additional.2=-showversion
XX:+UseConcMarkSweepGC
XX:+UseParNewGC
wrapper.java.initmemory Wrapper’s initial memory size in megabytes. 128
wrapper.java.maxmemory Wrapper’s maximum memory size in megabytes. 512
EMService.conf File 279

CA Wily Introscope
EMService.conf File
Value
wrapper.app.parameter.x Application parameters. You can add parameters as n/a
needed. For example:
wrapper.app.parameter.1=org.eclipse.core.
launcher.Main
wrapper.app.parameter.2=-consolelog
wrapper.app.parameter.3=-noExit
wrapper.app.parameter.4=-product
wrapper.app.parameter.5=com.wily.introsco
pe.em.product
wrapper.app.parameter.6=-install
wrapper.app.parameter.7=./product/
enterprisemanager
wrapper.app.parameter.8=-configuration
wrapper.app.parameter.9=./product/
enterprisemanager/configuration
wrapper.startup.timeout The number of seconds to allow between the time that 30 (seconds)
the wrapper launches the JVM process and the time that
the JVM side of the wrapper responds that the application
has started. Entering a 0 value means the system will
never time out.
wrapper.console.format The format of output for the console. PM
wrapper.console.loglevel The log level for the console output. INFO
wrapper.logfile The name and location of the log file used for wrapper ./logs/
output logging. EMService.l
og
wrapper.logfile.format The format of the output for the log file. LPTM
wrapper.logfile.loglevel The log level for log file output. INFO
wrapper.logfile.maxsize The maximum size that the log file will be allowed to 0
grow to before the log is rolled. Size is specified in bytes.
With the 0 default value disabling the log roll. You can
abbreviate with a k (kb) or m (mb) suffix. For example,
10m = 10 megabytes.
wrapper.logfile.maxfiles The maximum number of rolled log files that will be 0
allowed before old files are deleted. The default value of
0 implies no limit.
wrapper.syslog.loglevel The log level for the system and event log output. NONE
Note: Do not modify any of the following ntservice properties when an application using this
configuration file has been installed as a service. Please uninstall the service before modifying
this section. After you have made modifications, the service can then be reinstalled.
wrapper.ntservice.name Name of the service. IScopeEM

EMService.conf File
Value
wrapper.ntservice.displayname Display name of the service. Introscope
Enterprise
Manager
wrapper.ntservice.description Description of the service. Introscope
Enterprise
Manager
wrapper.ntservice.dependency. Service dependencies. Add dependencies as needed n/a
x starting from 1. For example:
wrapper.ntservice.dependency.1=
wrapper.ntservice.starttype Mode in which the service is installed. Options include AUTO_START

AUTO_START or DEMAND_START.
wrapper.ntservice.interactive Setting this value to true, starts the service to interact false
with the desktop.
IntroscopeWorkstation.properties
A variety of Workstation behaviors are controlled by properties defined in this file.
Value
log4j.logger.Workstation Controls the amount of logging detail and the output INFO,
location of the Workstation log. console
Level of detail value can be:
FATAL
WARN
INFO
VERBOSE#com.wily.util.feedback.Log4JSeverityLevel
(This value increases the level of detail logged.)
DEBUG
TRACE
Destination value can be console or logfile.
log4j.appender.logfile.File Name and location of Workstation logfile. IntroscopeW
orkstation.lo
g
IntroscopeWorkstation.properties 281
CA Wily Introscope
Value
Note: While this file contains the following properties, they should not be modified for normal use:
log4j.additivity.Workstation=false
log4j.appender.console=com.wily.org.apache.log4j.ConsoleAppender
log4j.appender.console.layout=com.wily.org.apache.log4j.PatternLayout
log4j.appender.console.layout.ConversionPattern=%d{M/dd/yy hh:mm:ss a z} [%-
3p] [%c] %m%n
log4j.appender.logfile=com.wily.org.apache.log4j.RollingFileAppender
log4j.appender.logfile.layout=com.wily.org.apache.log4j.PatternLayout
log4j.appender.logfile.layout.ConversionPattern=%d{M/dd/yy hh:mm:ss a z} [%-
3p] [%c] %m%n
log4j.appender.logfile.MaxBackupIndex=4
log4j.appender.logfile.MaxFileSize=200MB
introscope.workstation.graph. This controls the anti-aliasing of lines and symbols in true

antialiased graphs. If this value is set to false, it disables anti-
aliasing.
transport.http.proxy.host An HTTP Tunneling Proxy Server property that specifies <blank>
the host the Workstation is tunneling over HTTP. If this
method is chosen, it must connect to the Enterprise
Manager through a proxy server (forward proxy). If the
proxy server cannot be reached at the specified host and
port, the Workstation tries a direct HTTP tunneled
connection to the Enterprise Manager before failing the
connection attempt.
transport.http.proxy.port An HTTP Tunneling Proxy Server property that specifies <blank>
the port the Workstation is tunneling over HTTP. If this
method is chosen, it must connect to the Enterprise
Manager through a proxy server (forward proxy). If the
proxy server cannot be reached at the specified host and
port, the Workstation tries a direct HTTP tunneled
connection to the Enterprise Manager before failing the
connection attempt.
transport.http.proxy.username The username applies only if the proxy server requires <blank>
authentication, at which point you would enter a value to
represent a user name.
transport.http.proxy.password The username applies only if the proxy server requires <blank>
authentication, at which point you would enter a value to
represent a password, that a user must enter.

Value
transport.tcp.truststore If you configure SSL this optional property specifies the <blank>
location of the truststore that contains the trusted EM
certificates. This value is either an absolute path or a
path relative to the Workstation's working directory.
If you are on Windows, backslashes must be escaped.
For example:
transport.tcp.truststore=C:\\Introscope\\c
onfig\\internal\\server\\keystore
If no truststore is specified, the Workstation trusts all
certificates.
transport.tcp.trustpassword The password for the truststore. password
transport.tcp.truststore The location of a keystore containing the workstation's ..\\Intros
certificate. Either an absolute path or a path relative to cope\\conf
the Workstation's working directory. If you are on ig\\intern
Windows, backslashes must be escaped. For example: al\\server
\\keystore
transport.tcp.keystore The property for the location of the keystore. This is internal/
needed only if the EM requires client authentication. server/
keystore
transport.tcp.keypassword The password for the keystore. password
transport.tcp.ciphersuites Set this to enable cipher suites using a comma-separated <blank>
list of cipher suites. If this property is not specified, the
default enabled cipher suites will be used.
Introscope Workstation.lax
A variety of Workstation behaviors are controlled by properties defined in this file.
Value
lax.application.name Note: It is important not to edit the default name of Introscope
this executable. Workstation.
exe
lax.class.path The Java classpath necessary to run this application. launcher.jar

It can be separated by colons (Mac OS/Unix) or ;lax.jar
semicolons (Windows).
Introscope Workstation.lax 283

CA Wily Introscope
Value
lax.command.line.args What command line arguments will be passed to the $CMD_LINE_
main method. Can use this property to supply ARGUMENTS$
Workstation with login values, bypassing the Login
screen when starting Workstation.
lax.dir The path to the directory holding LaunchAnywhere's <blank>
native launcher.
lax.main.class The class that contains the main method for the org.eclipse.c
application. ore.launcher
.Main
lax.main.method The method in the main class that will be invoked. main
lax.nl.current.vm VM to use the next time the Workstation is started. Varies by

Can be set to any installed JDK or JRE version 1.5.0.8. operating
system.
lax.nl.java.launcher.main.clas Note: It is important that you do not modify this com.zerog.l
s property because it is the main class of ax.LAX
LaunchAnywhere's java launcher.
lax.nl.java.launcher.main.meth Note: It is important that you do not modify this main
od property because it is the main method of
LaunchAnywhere's java launcher.
lax.nl.java.option.additional Other option settings for JVM -client -
Initial minimum and maximum heap sizes. Xms64m -
Xmx256m -
Dsun.java2
d.noddraw=
true
lax.nl.message.vm.not.loaded The message displayed in a user dialog if no virtual LaunchAnyw
machine from the lax.nl.valid.vm.list can be here either
found. could not
find a Java
Note: This property is internal to the InstallAnywhere
VM, or the
launcher. Introscope has separate Java Java VM on
requirements. For more information, consult the this system
System Requirements in the Installation and is too old.
Upgrade Guide. LaunchAnyw
here requires
a Java 2 VM
in order to
launch
Introscope.

Value
lax.nl.valid.vm.list A string containing one or more of [ ALL JDK JRE J1 J2 J2
JRE_J1 JDK_J1 JRE_J2 JDK_J2 MSJ ] delimited by spaces
or commas.
If the native launcher cannot find the current virtual
machine, it will search for ones defined in this list.
lax.nl.win32.microsoftvm.min.v The minimum version with which this version of 2750
ersion Microsoft's virtual machine launcher will run.
lax.root.install.dir The path to the installdir magic folder. <blank>
lax.stderr.redirect Standard Error Output. Leave blank for no output, <blank>
lax.stdin.redirect Standard Input. Leave blank for no input, console to read <blank>
from the console window, or any path to a file to read
from that file.
lax.stdout.redirect Standard Output. Leave blank for no output, console to <blank>
the file.
lax.user.dir This property will cause the native launcher to not alter <blank>
the platform default behavior for setting the user
directory.
To override this you may set this property to a relative
or absolute path. Relative paths are relative to the
launcher.
lax.version The version of LaunchAnywhere that created this 8.0
properties file.
Introscope Workstation.lax 285

CA Wily Introscope
IntroscopeWebView.properties
A variety of WebView behaviors are controlled by properties defined in this file.
Value
introscope.webview.jetty.config The path to a Jetty 6.0.2 XML configuration file. Either an webview-
urationFile absolute path, or a path relative to the config directory. jetty-
For advanced Jetty configuration, uncomment this config.xml
property and modify the settings in the Jetty
configuration file.
The default is webview-jetty-config.xml. This file creates
an SSL listener on port 8443 for HTTPS traffic.
If uncommented, the http listener specified by the
introscope.webview.tcp.port property is not created, but
if desired it can be configured in the Jetty configuration
file.
introscope.webview.tcp.ipaddre A WebView HTTP server setting property for binding (set to a
ss WebView to a specific local IP address. When it is not valid IP
configured, WebView will accept incoming connections address on
on all local addresses (the wildcard address). WebView
machine)
introscope.webview.tcp.port The port on which WebView listens for HTTP traffic. 8080
introscope.webview.context.pat The WebView application context path. This string will be <blank>
h appended to the fully qualified hostname and port to
form the WebView root URL.
For example, if the context path is... The WebView root
URL will be...
introscope.webview.enterprise Settings WebView uses to find the Enterprise Manager. (set to your
manager.tcp.host computer
user
identification
)
introscope.webview.enterprise Settings WebView uses to find the Enterprise Manager. 5001
manager.tcp.port
log4j.logger.WebView Amount of logging detail for the WebView log. INFO,
Level of detail value can be: INFO or console
VERBOSE#com.wily.util.feedback.Log4JSeverityLevel.
log4j.logger.WebServer Amount of logging detail for the WebServer log. INFO,
Level of detail value can be: INFO or VERBOSE console
com.wily.util.feedback.Log4JSeverityLevel.

Value
log4j.logger The logging property for the third-party software INFO,
WebView uses. Level of detail value can be: INFO or console
VERBOSE com.wily.util.feedback.Log4JSeverityLevel.
log4j.logger.com.wily Amount of logging detail for the CA Wily log. INFO,

Level of detail value can be: INFO or VERBOSE console
com.wily.util.feedback.Log4JSeverityLevel.
log4j.logger.com.isomorphic Amount of logging detail for the isomorphic log. Error,
console
Note: If logfile is specified above, the location of the
log file is configured with the following property,
log4j.appender.logfile.File. Full paths can be
used if desired.
log4j.logger.org.apache.myfa Amount of logging detail for the Apache Myfaces log. ERROR,cons
ces ole
Note: If logfile is specified above, the location of the
used if desired.
log4j.logger.org.apache.jaspe Amount of logging detail for the Apache Jasper log. ERROR,cons
r Note: If logfile is specified above, the location of the ole
used if desired.
log4j.logger.org.apache.strut Amount of logging detail for the Apache Struts log. ERROR,cons
s Note: If logfile is specified above, the location of the ole
used if desired.
log4j.logger.org.mortbay Amount of logging detail for the Mortbay log. ERROR,cons
Note: If logfile is specified above, the location of the ole
used if desired.
IntroscopeWebView.properties 287
CA Wily Introscope
Value
Logging Configuration The following properties should not be modified for dependant
Properties normal use: on property
log4j.additivity.WebView=false
log4j.additivity.WebServer=false
log4j.additivity.com.wily=false
log4j.appender.console=com.wily.org.apache.log4j.Co
nsoleAppender
log4j.appender.console.layout=com.wily.org.apache.lo
g4j.PatternLayout
log4j.appender.console.layout.ConversionPattern=%d
{M/dd/yy hh:mm:ss a z} [%-3p] [%c] %m%n
log4j.appender.logfile=com.wily.org.apache.log4j.Rolli
ngFileAppender
log4j.appender.logfile.layout=com.wily.org.apache.log
4j.PatternLayout
log4j.appender.logfile.layout.ConversionPattern=%d{
M/dd/yy hh:mm:ss a z} [%-3p] [%c] %m%n
log4j.appender.logfile.MaxBackupIndex=4
log4j.appender.logfile.MaxFileSize=200MB
Note: If the value are set to true, graphs will be
antialiased (better looking). For example,
introscope.workstation.graph.antialiased=true
introscope.workstation.graph. Graphs will be antialiased—better looking—if you true
antialiased keep the default true value.
introscope.explorer.refresh.inte Frequency (in seconds) at which the Investigator tree 15
rval refreshes.
introscope.webview.context.pat The application context path for WebView. The specified /
h context path is appended to the fully qualified hostname
and port number of the WebView server, to form the
WebView root—the URL for accessing Webview. This
feature allows the user to define an application name for
WebView.
If the context path is webview, the URL to access
WebView is:
http://host:port/webview/
introscope.webview.enterprise Enterprise Manager hostname to connect to. localhost
manager.tcp.host
introscope.webview.enterprise Enterprise Manager port to connect to. 5001
manager.tcp.port
introscope.webview.svg.text.as Set to true to enable WebView to display non-Latin false
.images character sets, such as Kanji.
introscope.webview.tcp.port Port on which WebView listens for HTTP traffic 8080

Value
log4j.appender.console This property is added to the WebView properties file, to
logs/
write messages to the console.
IntroscopeW
ebView.log
log4j.appender.console.encodin This property is added to the WebView properties file, <blank>
g and set to the value “IBM-1047” to enable WebView to
write messages in EBCDIC format when running under z/
OS.
log4j.appender.logfile This property is added to the WebView properties file, to com.wily.or
append messages to the log file. g.apache.lo
g4j.RollingFi
leAppender
log4j.appender.logfile.encoding This property is added to the WebView properties file, <blank>
and set to the value “IBM-1047” to enable WebView to
write messages in EBCDIC format when running under z/
OS.
log4j.appender.logfile.File Name and location, relative to the Introscope home logs/
directory, of the WebView logfile. IntroscopeW
ebView.log.
IntroscopeWebView.properties 289
CA Wily Introscope
Introscope WebView.lax
The runtime behavior of WebView is controlled by properties defined in this file.
Value
lax.application.name LaunchAnywhere Executable Properties File - <blank>
Macrovision Corp.
lax.class.path The Java classpath necessary to run this application. lib/
WebServices
.jar:lib/
IntroscopeCli
ent.jar:lib/
Workstation.
jar:lib/
WebViewAPI.
jar:lib/
WebViewSer
ver.jar:lib/
IntroscopeSe
rvices.jar
lax.command.line.args Command line arguments to pass to the main method. $CMD_LINE_
Can use this property to supply WebView with login ARGUMENTS
values, bypassing the Login screen when starting $
WebView.
lax.dir The path to the directory where the LaunchAnywhere’s <blank>
native launcher resides.
lax.main.class The class that contains the main method for the org.eclipse.c
application. ore.launcher.
Main
lax.main.method The method in the main class that will be invoked. main
lax.nl.current.vm VM to use the next time the Workstation is started. Can Varies by
be set to any installed JDK or JRE version 1.5.0.8. operating
system
lax.nl.java.launcher.main.class The main class of LaunchAnywhere's java launcher. com.zerog.l
Note: This property should not be adjusted. ax.LAX
lax.nl.java.launcher.main.meth The main method of LaunchAnywhere's java launcher. main

od
Note: This property should not be adjusted.

Value
lax.nl.java.option.additional Optional settings for JVM, such as heap size. -Xms128m -
Xmx512m -
Djava.awt.he
adless=false
-
Dsun.java2d.
noddraw=tru
e
lax.nl.message.vm.not.loaded The message displayed in a user dialog if no VM from n/a
the lax.nl.valid.vm.list can be found.
Note: This property is internal to the InstallAnywhere
launcher. Introscope has separate Java
requirements. For more information, consult the
System Requirements section of the Installation
and Upgrade Guide.
lax.nl.valid.vm.list A string containing one or more of [ ALL JDK JRE J1 J2 J2
JRE_J1 JDK_J1 JRE_J2 JDK_J2 MSJ ] delimited by spaces
or commas. If the native launcher cannot find the current
virtual machines, it will search for ones defined in this
list.
lax.nl.win32.microsoftvm.min The minimum version of Microsoft's VM this 2750
.version application will run against.
lax.root.installation.dir The path to the installdir magic folder. <blank>
lax.stderr.redirect Standard Error Output. Leave blank for no output, console

lax.stdin.redirect Standard Input. Leave blank for no input, console to read console
from the console window, or any path to a file to read
from that file.
lax.stdout.redirect Standard Output. Leave blank for no output, console to console
the file.
lax.user.dir This is left blank because the property will cause the <blank>
native launcher to not alter the platform default
behavior for setting the user dir.
To override this you may set this property to a relative

or absolute path.
Relative paths are relative to the launcher.
Introscope WebView.lax 291

CA Wily Introscope
Value
lax.version The version of LaunchAnywhere that created this 8.0
properties file.
lax.nl.valid.vm.list a string containing one or more of [ ALL JDK JRE J1 J2
J2 JRE_J1 JDK_J1 JRE_J2 JDK_J2 MSJ ] delimited by
spaces or commas. If the native launcher cannot find
the current virtual machine, it will search for ones in
this list

APPENDIX
B
Using the JDBC API
Introscope includes an API that enables you to use a data analysis tool such as
Excel or SAS to view Introscope data. Using the JDBC interface, you can extract
metric and event data for historical ranges. The data is returned in a table with
a single column containing an XML string that describes the table metadata, and
contains the table of results.
This section includes these topics:

Configuring the JDBC API . . . . . . . . . . . . . . . . 294
Using the JDBC API . . . . . . . . . . . . . . . . . . 294
Using the JDBC API 293

CA Wily Introscope
Configuring the JDBC API

The file IntroscopeJDBC.jar contains the JDBC driver class and all classes
needed by the driver. It is the only file needed on the classpath of the client
application.
The driver class is com.wily.introscope.jdbc.IntroscopeDriver.
The URL format is (note that case is important):

jdbc:introscope:net//{username}{:password}@{host}:{em port}
For example:
jdbc:introscope:net//Admin:@localhost:5001
Using the JDBC API

The syntax for the Introscope JDBC API supports these virtual views:
metric_data
trace_headers
traces
Metric queries
The basic metric query syntax is:
select * from metric_data where agent={regex} and metric={regex} and

timestamp between {starttime} and {endtime}
For example:
select * from metric_data where agent='.*Custom Metric Host.*' and

metric='.*' and timestamp between '01/01/01 00:00:00' and '01/01/07
00:00:00'
294 Using the JDBC API

These qualifiers support the Enterprise Manager’s metric aggregation features:
This qualifier Does this

sort by value {a|d} Flags the Enterprise Manager to do an ascending or
descending N sort on the metric values for each timeslice.
Use this qualifier with the maxmatches flag to specify the
metric limit for the Top N match.
maxmatches Flags the Enterprise Manager to only return data for up to

this number of metrics. If maxmatches=2, only data for
two metrics are returned.
This is different from the sql limit keyword, which limits
the number of rows returned. Our maxmatches=2
example might return 50 timeslices for 2 metrics, for a
total of 100 rows of data.
period Flags the Enterprise Manager to aggregate data points to

the given period. For example, the Enterprise Manager
usually reports 15-second data values, but can aggregate
to 60 seconds if period=60.
aggregateall Flags the Enterprise Manager to aggregate all metric data

into one summarized timeslice. For example, you could
use this qualifier to give a single Average Response Time
for a metric across a one-week time period.
Avoid using aggregateall with the period qualifier—
they both deal with aggregation and would conflict.
These qualifiers must appear in this order in the SQL statement:
[sort by value {ascending|descending}] [maxmatches={max metrics}]

[period={period in seconds}] [aggregateall]
Metric query examples

select * from metric_data where agent='.*' and metric='.*Average Response.*'
and timestamp between '01/01/01 00:00:00' and '01/01/07 00:00:00'
maxmatches=10

maxmatches=1

maxmatches=1 period=120
// match one metric_data and aggregate all values. This returns one row of
data select * from metrics where agent='.*' and metric='.*Average
Response.*' and timestamp between '01/01/01 00:00:00' and '01/01/07
00:00:00' maxmatches=1 aggregateall
Using the JDBC API 295

CA Wily Introscope
// this is a top 10 query select * from metric_data where agent='.*' and

metric='.*Average Response.*' and timestamp between '01/01/01 00:00:00'
and '01/01/07 00:00:00' sort by value d maxmatches=10
Transaction trace queries

The basic transaction header query syntax is:
select * from trace_headers where timestamp between {starttime} and {endtime}

and query={lucene query string} [limit {rows}]
where lucene query string is a valid Lucene query string, as in the

Workstation’s historical query (see the Introscope Workstation User Guide for
more information.)
The optional limit flag limits the number of rows returned by the query. If no
limit is specified, the default transaction limit defined in the server is used.
The query for trace bodies is identical, but references a different view:
select * from traces where timestamp between {starttime} and {endtime} and
query={lucene query string} [limit {rows}]
Transaction trace query examples:

select * from trace_headers where timestamp between '01/01/01 00:00:00' and
'01/01/07 00:00:00' and query='s*'
select * from trace_headers where timestamp between '01/01/01 00:00:00' and

'01/01/07 00:00:00' and query='host:blinky'
select * from traces where timestamp between '01/01/01 00:00:00' and '01/01/
07 00:00:00' and query='host:blinky' limit 100
The rows of data returned by trace queries include agent information like the
domain, host, process and agent name, and the XML representation of the
transaction trace.
296 Using the JDBC API

I ND E X
Index
A manually 33
actions Agent Failover
activate with simple alerts 133 Domains and User issues with 234
activating with summary alerts 139 alerts
adding with simple alerts 132 commands 177, 180
adding with summary alerts 138 monitoring performance with 125
commands 174 notification options 140
creating actions 150 settings
default 150 SmartTrigger 140
shell command action 151 simple
SMTP email action 153 about 125
types 150 activate actions 133
workstation notification 150 adding actions 132
activate actions command 174 configuring 127
activate alerts command 177, 180 creating from elements 126
activate calculators command 182 creating from existing data 126
activate dashboards command 185 metric groupings with 127
activate management modules command 172 summary
activate report templates command 189 about 133
activate snmp collections command 193 activating actions 139
agent adding actions 138
clusters creating 135
Enterprise Manager 25 notifications 139
expressions time periods 134
with management modules 114, 116 arrowheads
mounting historical 33 adding 93
shutoff 34 Authentication
agent reporting 36 LDAP 213
all agent components 37 local 219
metric reporting 35 Auto Expand 85
resource reporting 36 Auto Scale 84
why component not reporting 37
icon appearance 38 B
status messages 38 bootstrap
unmounting disconnected 33 Management Module 270
automatically 33
Index 297
CA Wily Introscope
C delete dashboards 187

calculators delete management module 173
adding a JavaScript 159 delete report templates 191
commands 182 delete snmp collections 195
creating 154 generate report 192
JavaScript 155 Introscope Agent 169
metrics 154 list actions 174
running JavaScript Calculators on the MOM list agents 169
158 list alert downtime schedules 180
weighted averages 155 list alerts 177
writing JavaScript 155 list calculators 182
capacity list dashboards 185
Enterprise Manager 31 list management modules 171
Clock Skew Tolerance list metric groups 188
setting for Enterprise Manager 250 list report templates 188
CLW list snmp collections 193
see Command Line Workstation 164 management modules 171
collectors metric groupings 187
MOM pathname
Enterprise Manager 30 specifying 169
Command Line Workstation persistent data
about 164 previous n minutes 169
command reference 167 time range 168
command syntax 165 query alert downtime schedules 181
commands query state of actions 175
actions 174 query state of alerts 178
activate actions 174 query state of calculators 183
activate alerts 177, 180 query state of dashboards 186
activate calculators 182 query state of management modules
activate dashboards 185 171
activate management modules 172 query state of report templates 190
activate report templates 189 query state of snmp collections 194
activate snmp collections 193 readonly management modules 173
alerts 177, 180 rename action 176
calculator 182 rename alert 179
copy management module 172 rename alert downtime schedules 181
dashboard 184 rename calculator 184
deactivate actions 175 rename dashboard 187
deactivate alerts 178, 181 rename report template 190
deactivate calculators 183 rename snmp collection 195
deactivate dashboards 186 report templates 188
deactivate management modules 172 send config file 170
deactivate report templates 189 shutdown 168
deactivate snmp collections 194 SNMP collections 193
delete actions 176 transaction trace 196
delete alert 179 turn off agents 170
delete alert downtime schedules 182 turn on agents 170
delete calculators 184 Enterprise Manager commands 167
298 Index
prerequisites 164 saving a copy of 74

running 164 saving new and changed 76
configuration settings snap to grid 74
Management Module Bootstrapping 270 Dashboard Editor 70
configuring tools palette 71
Domains 223 data store
connections Enterprise Manager 26, 28
Enterprise Manager 26 transactions
connectors Enterprise Manager 27
adding arrowheads to 93 Data Viewer
drawing 93 adding data to
copy management module command 172 drag and drop 79
CPU used through Data Options dialog 80
Enterprise Manager 25 changing display type 82
creating and editing dashboards 67, 110 changing resolution 89
changing scaling options of 82
D changing sorting and filtering options 86
danger alert creating
30-second delay 141 automatically by dragging and dropping
SmartTrigger 141 data 77
dashboard empty and adding data 78
adding shapes, lines and text to 92 creating automatically 76
commands 184 creating in dashboard 76
creating default type for data 77
in console 71 discovering which data is displayed in 81
in Management Module Editor 73 display options 82
creating Data Viewers in 76 labels, turning on and off 90
deleting 75 setting properties of 82
editing 70 Database
and domain enforcement 68, 112 Enterprise Manager 28
object DB2, z/OS 14
align 103 deactivate actions command 175
arrange 104 deactivate alerts command 178, 181
copy 102 deactivate calculators command 183
cut 102 deactivate dashboards command 186
Data Viewer 69 deactivate management modules command
delete 103 172
duplicate 103 deactivate report templates command 189
group 105 deactivate snmp collections command 194
moving 102 delay actions, SmartTrigger 141
paste 102 delete actions command 176
resizing 102 delete alert command 179
selecting 101 delete alert downtime schedules command 182
shapes, images and text objects 69 delete calculators command 184
ungroup 105 delete dashboards command 187
objects 69 delete management module command 173
renaming 75 delete report templates command 191
resizing 74 delete snmp collections command 195
Index 299
CA Wily Introscope
deregistering Enterprise Manager 9 monitoring health and load 24

domain enforcement, elements 112 running on Unix 10
Domains setting Clock Skew Tolerance 250
Agent mapping 224 shutdown command 168
changing 226 shutting down
associating Management Modules with 225 automatic 32
attributes and syntax 224 from Workstation 32
configuring and managing 223 starting
creating 223, 224 OS/400 11
creation rules 223 UNIX 10
deleting 226 Windows 8
managing 223 stopping 21
merging 227 UNIX nohup mode on 11
moving between Introscope installations 227 Windows Service
type 223 configuring 8
domains deregistering 9
dashboard editing and 68 modifying 9
element editing and domain enforcement prerequisites 8
112 stopping and starting 10
Domains and Users exceptions, alert notifications 140
with Agent Failover 234 extract persistent data command
drawing previous n minutes 169
connector lines 93 time range 168
lines 93
ovals 92 F
polygon 93 fill color
rectangles 92 adding to a shape 95
rounded rectangles 92 more color options 95
scribble 93 firewall
connecting components behind 45
E
elements G
about 112 garbage collection (GC) 29
in the Management Module Editor 113 GC Heap
naming 115 Enterprise Manager 29
Enterprise Manager generate report command 192
Administering from Workstation 23, 39 graph
automatic shutdown 22 resizing graph legend 103
automatic Windows Service 8 graphs
capacity 25 Auto Expand 85
configuring JVM 20 Auto Scale 84
configuring metric throttle 31 min and max values 83
configuring z/OS with 12, 16 scale 83
managing capacity 31
metrics H
configuration 25 health
CPU 25 Enterprise Manager 29
understanding 24 hyperlinks 106
300 Index
creating monitoring
default link 108 configuring 112
to dashboard 106
to web page 107 M
managing Management Module
removing 110 hot deployments and virtual agents 161
I configuring settings 270
images, inserting 100 Management Module Editor
internals competing changes in shared Workstations
Enterprise Manager 30 39
Introscope Agent, commands 169 management modules
Investigator, alert state in 144 about 112
activating and deactivating 118
J agent expressions and 114, 116
JavaScript commands 171
adding a calculator 159 copying 117, 160
calculators 155 creating 113, 116
running calculators on the MOM 158 deleting 118
writing calculators 155 deploying 160
JDBC API editing 118
configuring 294 hot deploy service 161
metric queries 294 Management Module Editor
transaction trace queries 296 alert state metrics 144
JDBC, z/OS 15 creating calculators 154
JVM, configuring Enterprise Manager 20 hyperlinks in 114
notification actions 150
L shell command action 151
lax files SMTP email action 153
Introscope Enterprise Manager.lax 276 Management Module Editor elements 113
Introscope WebView.lax 290 naming 115
Introscope Workstation.lax 283 updating 160
lines Maximum Data Point Retrieval Property
adding arrowheads to 93 setting 251
drawing 93 setting Workstation property 251
list actions command 174 messages, alert notifications 140
list agents command 169 metric groupings
list alert downtime schedules command 180 adding to 123
list alerts command 177 commands 187
list calculators command 182 configuring 119
list dashboards command 185 creating 120
list management modules command 171 creating from elements 121
list metric groups command 188 creating from existing 120
list report templates command 188 customizing 123, 124
list snmp collections command 193 metric throttle
Log4J Enterprise Manager 31
Workstation settings 246 Metrics
logic Enterprise Manager
Index 301
CA Wily Introscope
database 28 elements 112

metrics polygon
alert state drawing 93
Investigator 144 resizing 102
Management Module Editor 144 production environments, Management Module
alerts hot deployments in 161
state 143 properties
Enterprise Manager files 253
problems properties files
Management Modules 30 Introscope Enterprise Manager.lax 276
name structure 119 Introscope WebView.lax 290
using calculators 154 Introscope Workstation.lax 283
MOM IntroscopeEnterpriseManager.properties
Enterprise Manager 30 254
monitoring logic IntroscopeWebView.properties 286
configuring 112 IntroscopeWorkstation.properties 281
elements 112
management modules 112 Q
query alert downtime schedules command 181
N query state of actions command 175
naming query state of alerts command 178
management modules and elements 115 query state of calculators command 183
nohup query state of dashboards command 186
UNIX mode on Enterprise Manager 11 query state of management modules command
notification options 171
alerts 140 query state of report templates command 190
notifications query state of snmp collections command 194
with summary alerts 139
R
O readonly management modules command 173
OS/400 rectangle
command line with Enterprise Manager 12 drawing 92
control script with Enterprise Manager 12 redirect output
SSL 45 Workstation 246
start script with Enterprise Manager 11 rename action command 176
starting Enterprise Manager 11 rename alert command 179
oval rename alert downtime schedules command
drawing 92 181
rename calculator command 184
P rename dashboard command 187
pathname command rename report template command 190
specifying for authentication 169 rename snmp collection command 195
pen color reperiodization 27
adding to a shape or line 95 report templates
more color options 95 commands 188
performance resizing
monitoring with alerts 125 graph legend 103
permissions rounded rectangle
302 Index
drawing 92 time periods

summary alerts 134
S tools palette 71
scheduling tasks Transaction Event Database
using Command Line Workstation 164 settings 54, 267
scribble transaction trace
drawing 93 commands 196
send config file command 170 examples 199
severity increases output file 196
SmartTrigger 142 trace mode 197
shell commands queries
Enterprise Manager 22 from transaction events database 201
shutdown, automatic Enterprise Manager 22 sessions
SmartStor 52 sample scripts
Enterprise Manager 26 all agents 203
requirements 52 Transaction Trace Clamp 198
SmartTrigger turn off agents command 170
alerts turn on agents command 170
delay actions 141
severity increases 142 U
settings 140 UNIX
SMTP, email action 153 starting Enterprise Manager 10
snap to grid 74 Unix
SNMP Collections 270 running Enterprise Manager 10
SNMP collections User
commands 193 modifiers and syntax 220
Sorting and Filtering Options User permissions
changing 86 creation rules 229
excluding Metrics 88 Users
including Metrics 87 defining a user 220
SSL permissions
Enterprise Manager on OS/400 45 Domain access
defining permissions 231
T server access
task metrics defining permissions 233
Enterprise Manager 31 modifiers and syntax 233
terminal window
stopping Enterprise Manager from 22 V
terminal window commands verbose mode
Enterprise Manager 22 running Workstation in 246
text view
adding background color 99 display type
changing color 99 options 82
changing font 99 virtual agent
changing size 99, 100 Enterprise Manager 25
changing style 99 virtual agents
creating on dashboard 97 and Management Module hot deployments
editing 98 161
Index 303
CA Wily Introscope
virtual memory running Enterprise Manager as started task

z/OS 14 18
Volume Space Free running Enterprise Manager on 18
Enterprise Manager 28 security and authorization 14
software prerequisites for Java 13
W virtual memory 14
WebView WILYPROC with 18
settings 270
weighted averages
calculators 155
Windows Service
configuring Enterprise Manager 8
deregistering Enterprise Manager 9
modifying Enterprise Manager 9
prerequisites for Enterprise Manager 8
running Enterprise Manager 8
stopping and starting Enterprise Manager 10
Working 111
Workstation
command line functions 164
connecting to Enterprise Manager behind fire-
wall 45
management modules 113
activating and deactivating 118
copying 117
creating 116
deleting 118
editing 118
shared state in multiple 39, 111
stopping Enterprise Manager from 22
Z
z/OS
base structure for Java 13
configuring as batch job 12, 16
customizing Enterprise Manager for 16
customizing UNIX shell script 17
DB2 14
Enterprise Manager
starting automatically 19
verifying 19
installation overview
Enterprise Manager 16
JDBC 15
partitioned dataset 17
PROC
customizing 17
executing 17
304 Index

Introscope8 0 2 0ConfigAdminGuide

Enviado por

Dados do documento

Descrição original:

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Introscope8 0 2 0ConfigAdminGuide

Enviado por

Direitos autorais:

Formatos disponíveis

CA Wily Introscope®

We value your feedback

US Toll Free 888 GET WILY ext. 1

Chapter 1 Starting and Stopping the Enterprise Manager . . . . . . . 7

Chapter 2 Administering the Enterprise Manager . . . . . . . . . . 23

Chapter 3 Configuring Enterprise Manager Communications . . . . . . 41

Chapter 4 Configuring Enterprise Manager Data Storage . . . . . . . 51

Chapter 5 Working with Enterprise Manager Clustering . . . . . . . . 55

Chapter 6 Creating and Editing Introscope Dashboards . . . . . . . . 67

Chapter 7 Working with Management Modules . . . . . . . . . . 111

Chapter 8 Using the Command-Line Workstation . . . . . . . . . 163

Chapter 9 Configuring Introscope Security and Permissions . . . . . 207

Chapter 10 Configuring WebView Options . . . . . . . . . . . . 235

Chapter 11 Tailoring your Workstation Configuration . . . . . . . . 245

Chapter 12 System Configurations . . . . . . . . . . . . . . . 249

Appendix A Introscope Properties Files . . . . . . . . . . . . . . 253

Appendix B Using the JDBC API . . . . . . . . . . . . . . . . . 293

Starting and Stopping the

Starting the Enterprise Manager on Windows . . . . . . . . . . . 8

Starting and Stopping the Enterprise Manager  7

Starting the Enterprise Manager on Windows

Starting the Enterprise Manager Manually on Windows

The Enterprise Manager starts in accordance with the property settings in

Running the Enterprise Manager as a Windows Service

These instructions assume you are familiar with configuring applications as

Configuring the Enterprise Manager as a Windows Service

8  Starting and Stopping the Enterprise Manager

3 In the IntroscopeEnterpriseManager.properties file, in your

 wrapper.ntservice.displayname=<EM display name>

Save changes to the file.

Changing Windows Service properties

Unregistering an Enterprise Manager Windows Service

 before you make changes to the EMService.conf properties file.

 to return the Enterprise Manager instance to Console control.

 before you uninstall the Enterprise Manager instance.

To unregister an Enterprise Manager Service:

Starting the Enterprise Manager on Windows  9

Stopping and Restarting the Enterprise Manager Windows

Starting the Enterprise Manager on UNIX

Starting the Enterprise Manager Manually on UNIX

The Enterprise Manager starts in accordance with the property settings in

Running the Enterprise Manager on Unix

To run the Introscope Enterprise Manager on Unix:

Use the following commands at the bin folder:

 ./EMCtrl.sh start—This starts the Enterprise Manager.

 ./EMCtrl.sh stop—This stops the Enterprise Manager.

 ./EMCtrl.sh status—This gives the status of the Enterprise Manager.

 ./EMCtrl.sh help—This shows the supported options for the script.

10  Starting and Stopping the Enterprise Manager

Running Enterprise Manager in nohup Mode on UNIX

To run the Introscope Enterprise Manager in nohup mode on UNIX:

1 In the IntroscopeEnterpriseManager.lax file, in your <Introscope_Home>

Starting the Enterprise Manager on OS/400

Running the OS/400 start script

 Enterprise Manager start script:

nohup ./runem.sh &

nohup ./runwv.sh &

nohup ./runem.sh /<Introscope_Home> &

Starting the Enterprise Manager on OS/400  11

where <Introscope_Home> is the root of your Enterprise Manager installation

Using control scripts for OS/400 and Z/OS

Use these control scripts for OS/400 and Z/OS:

Starting and Stopping the Enterprise Manager 7

8 Starting and Stopping the Enterprise Manager

wrapper.ntservice.displayname=<EM display name>

before you make changes to the EMService.conf properties file.

to return the Enterprise Manager instance to Console control.

before you uninstall the Enterprise Manager instance.

Starting the Enterprise Manager on Windows 9

./EMCtrl.sh start—This starts the Enterprise Manager.

./EMCtrl.sh stop—This stops the Enterprise Manager.

./EMCtrl.sh status—This gives the status of the Enterprise Manager.

./EMCtrl.sh help—This shows the supported options for the script.

10 Starting and Stopping the Enterprise Manager

Enterprise Manager start script:

Starting the Enterprise Manager on OS/400 11

./EMCtrl.sh status—Verifies whether the Enterprise Manager is running or

12 Starting and Stopping the Enterprise Manager

Prerequisites for running Enterprise Manager as a z/OS batch job on page 13

UNIX System Services must be enabled

Language Environment 1.5 or higher

Java for z/OS

Starting and configuring the Enterprise Manager on z/OS 13

EXEC PGM= BPXBATCH

14 Starting and Stopping the Enterprise Manager

Starting and configuring the Enterprise Manager on z/OS 15

IntroscopeEnterpriseManager.properties – the Introscope Enterprise Manager

Copy the IntroscopeEnterpriseManager.properties and runem.sh files into the

16 Starting and Stopping the Enterprise Manager

Starting and configuring the Enterprise Manager on z/OS 17

18 Starting and Stopping the Enterprise Manager

Starting and configuring the Enterprise Manager on z/OS 19

If you start the Enterprise Manager with Introscope Enterprise

20 Starting and Stopping the Enterprise Manager

SmartStor does not save data.

you are logged out of the Workstation.

all users connected to the Enterprise Manager are disconnected.

Stopping the Enterprise Manager 21

22 Starting and Stopping the Enterprise Manager

Administering the Enterprise Manager 23