CA Wily Introscope®

Environment
Performance Agent
Guide
Version 7.2

Date: 10-2007
Copyright © 2007, 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. If you have comments or suggestions about Wily documentation, please
send us an e-mail at wily-techpubs@ca.com.

6000 Shoreline Court, Suite 200
South San Francisco, CA 94080
US Toll Free 888 GET WILY ext. 1
US +1 630 505 6966
Fax +1 650 534 9340
Europe +44 (0)870 351 6752
Asia-Pacific +81 3 6868 2300
Japan Toll Free 0120 974 580
www.wilytech.com
CONTENTS

Table of Contents

Chapter 1 Installing, Configuring, and Using the EPAgent . . . . . . . 1

Environment Performance Agent overview . . . . . . . . . . . 2
Environment Performance Agent can receive input from processes . . 2
Environment Performance Agent and scripting environments . . . . 3
EPAgent can accept input from network sources . . . . . . . . 4
Environment Performance Agent and Introscope . . . . . . . . 4
Supported plug-ins. . . . . . . . . . . . . . . . . . . 5
Installing the Environment Performance Agent . . . . . . . . . . 6
Using the EPAgent included with base Introscope installation . . . . 6
Using the EPAgent standalone installer . . . . . . . . . . . . 7
Configuring the Environment Performance Agent . . . . . . . . . 8
Configuring Environment Performance Agent logging options . . . . 8
Configuring Environment Performance Agent plug-ins . . . . . . 9
Configuring the EPAgent for network data sources . . . . . . . 12
Running the Environment Performance Agent . . . . . . . . . 13
Using custom plug-ins with the EPAgent . . . . . . . . . . . 13
Formats for data . . . . . . . . . . . . . . . . . . 13
EPAgent events and transaction traces . . . . . . . . . . . 16

Chapter 2 EPAgent Default Plug-ins . . . . . . . . . . . . . . . 21

solaris/diskStats.pl . . . . . . . . . . . . . . . . . . 22
Metrics produced . . . . . . . . . . . . . . . . . . 22
Command-line arguments . . . . . . . . . . . . . . . 22
windows/processAvailability.pl AND solaris/processAvailability.pl . . 22
Metrics produced . . . . . . . . . . . . . . . . . . 22
Command-line arguments . . . . . . . . . . . . . . . 22
windows/diskStats.pl . . . . . . . . . . . . . . . . . . 23
Metrics produced . . . . . . . . . . . . . . . . . . 23

Contents „ iii
CA Wily Introscope

Command-line arguments . . . . . . . . . . . . . . . 23
apacheLogReader.pl, weblogicLogReader.pl, and websphereLogReader.pl
24
Metrics produced . . . . . . . . . . . . . . . . . . 24
Command-line arguments . . . . . . . . . . . . . . . 24
httpSvcAvailability.pl . . . . . . . . . . . . . . . . . . 25
Metrics produced . . . . . . . . . . . . . . . . . . 25
Command-line arguments . . . . . . . . . . . . . . . 25
Perl support issues . . . . . . . . . . . . . . . . . . 25
kstat.pl . . . . . . . . . . . . . . . . . . . . . . 26
Metrics produced . . . . . . . . . . . . . . . . . . 26
Command-line arguments . . . . . . . . . . . . . . . 26
Perl support issues . . . . . . . . . . . . . . . . . . 27
iisLogReader.pl . . . . . . . . . . . . . . . . . . . . 27
Metrics produced . . . . . . . . . . . . . . . . . . 27
Command-line arguments . . . . . . . . . . . . . . . 27
iisLogReader.cfg Configuration File . . . . . . . . . . . . 28
Configuring IIS Web Server logging in IIS4.0 and IIS5.0 . . . . 32

Appendix A Metrics Produced By Environment Performance Agent Default Plug-

ins 35
Metrics produced by EPAgent default plug-ins . . . . . . . . . 36
Invalid character replacement . . . . . . . . . . . . . . 36
IIS log reader metrics. . . . . . . . . . . . . . . . . 36
HTTP/HTTPS service availability metrics . . . . . . . . . . 37
Solaris kernel statistics (Kstat) metrics. . . . . . . . . . . 37
Process availability metrics . . . . . . . . . . . . . . . 38
Disk Stats (Win 2000) metrics . . . . . . . . . . . . . . 38
Disk Stats (Solaris) metrics . . . . . . . . . . . . . . . 39
Apache log metrics . . . . . . . . . . . . . . . . . . 39
WebSphere log metrics . . . . . . . . . . . . . . . . 40
WebLogic log metrics . . . . . . . . . . . . . . . . . 41

Appendix B Environment Performance Agent Properties . . . . . . . . 43

IntroscopeEPAgent.properties file . . . . . . . . . . . . . 43
IntroscopeEPAgent.properties settings . . . . . . . . . . . 45

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

iv „ Contents
CHAPTER
1

Installing, Configuring, and Using the

EPAgent

This section covers installing and using the Introscope Environment Performance
Agent version 7.2 add-on component for Introscope in the following sections:

Environment Performance Agent overview . . . . . . . . . . . . 2

Installing the Environment Performance Agent . . . . . . . . . . 6
Configuring the Environment Performance Agent . . . . . . . . . . 8
Running the Environment Performance Agent . . . . . . . . . . 13
Using custom plug-ins with the EPAgent. . . . . . . . . . . . 13

Installing, Configuring, and Using the EPAgent „ 1

CA Wily Introscope

Environment Performance Agent overview

The Environmental Performance Agent (EPAgent) integrates metric data from
non-Java sources into Introscope.

EPAgent takes advantage of the facility available in many operating systems for
one process to spawn a sub-process and receive standard output from the sub-
process via operating system pipes (standard IPC mechanism). When the ability
to initiate a sub-process is combined with a flexible scripting environment (such
as Perl) the result is an adaptable and powerful facility for gathering application
performance information from virtually any source.

Environment Performance Agent can receive input from processes

EPAgent is implemented in Java and runs in a Java Virtual Machine. EPAgent
makes use of the JVM facility to invoke a sub-process and receive STDOUT and
STDERR from that process. The sub-process can be any script, executable or
anything that can be invoked on a command-line. Examples include:
„ a compiled program written by the user in C

„ a Perl script.

By executing a simple PRINT function, the application or script in the sub-process

can communicate with the EPAgent. This illustration shows how applications or
scripts communicate metric data to EPAgent by printing to STDOUT.

EPAgent expects the text it receives via STDOUT to conform to a specific format,
either:
„ a simple name/value pair, or

„ XML

The EPAgent text format requirements and options are fully explained later in this
document.

2 „ Installing, Configuring, and Using the EPAgent

 Environment Performance Agent Guide

In this document the application or script sending data to EPAgent is referred to

as an EPAgent plug-in. The EPAgent includes several default plug-ins that provide
detailed metric data; you can also create custom plug-ins. Related topics in this
manual describe:
„ the different types of default plug-ins

„ how to create custom plug-ins

„ how to configure EPAgent to invoke any plug-ins.

Environment Performance Agent and scripting environments

Although EPAgent can receive text from any executable entity in a subprocess—
including compiled application—the most flexible approach is to use a scripting
environment such as Perl, KornShell, or rexx. Interpretative scripting
environments have the advantage of ease of implementation and often supply
libraries or interfaces to real-world data sources such as relational databases, OS
subsystems (process table, file system, etc.) and third party products.

Scripts can gather information from a wide variety of sources. For example, a
script may:
„ call a library function or system utility to check for the existence of a critical
application such as a database.
„ scan and parse application logfiles to detect application errors.

The flexibility of a scripting environment allows EPAgent to gather performance

and management information from virtually any source. This illustration shows
how scripts can access information from many sources.

Environment Performance Agent overview „ 3

CA Wily Introscope

Wily emphasizes the use of Perl with EPAgent because Perl interpreters are
available on a wide variety of platforms and have broad support for data APIs to
operating systems, middleware, and third party products. Introscope EPAgent
includes a set of sample Perl scripts to perform a variety of functions such as
checking for process availability, obtaining disk performance statistics and
reading HTTP logs. These scripts may be extended to perform other functions.

EPAgent can accept input from network sources

In addition to accepting input from local processes, EPAgent can accept input
from network sources. This is useful for collecting information from networked
processes where EPAgent cannot run—for instance, a C++ backend system that
provides monitoring information via a network port, or posts data periodically to
a web URL. For more information, see Configuring the EPAgent for network data
sources on page 12.

Environment Performance Agent and Introscope

EPAgent runs as a standalone process. Like the Introscope Agent, it connects to
the Introscope Enterprise Manager to deliver management and performance
information. This illustration shows how EPAgent forwards data to the Introscope
Enterprise Manager.

EPAgent helps obtain a better overall view of your application environment.

Distributed application architectures are complex, often comprised of a mixture
of Java and non-Java application subsystems. EPAgent permits the easy
collection of information from the non-Java portion of the application
environment for display alongside the Java metrics in the Introscope
Workstation.

4 „ Installing, Configuring, and Using the EPAgent

 Environment Performance Agent Guide

Supported plug-ins
The EPAgent supports both stateful and stateless plug-ins.

» Note Perl version 5.00503 or later is required by all default plug-ins.

Plug-in types

Plug-in type Description

Stateful plug-ins Stateful plug-ins are expected to be long running scripts (i.e.
daemons) to be started when the EPAgent starts and run
indefinitely. These stateful plug-ins can feed data back into
Introscope at any time through the standard output channel of
the plug-in. Should a stateful plug-in terminate, it will be
restarted by the EPAgent.
Stateless plug-ins Stateless plug-ins are designed to run on a recurring schedule
and can be configured with the frequency (specified as delay
between runs) at which they should be run. These are expected
to be short-running scripts intended to collect some data, send
it to the EPAgent through the standard output channel, and
terminate.
Note: No special error-checking is done by the EPAgent to
ensure only one instance of a stateless plug-in is
running at one time, so plug-in developers are required
to design their stateless plug-ins to run and complete in
a reasonably short period of time.

Error logging
Errors can be logged through the standard error channel of the plug-in, enabling
EPAgent to log this error output as it would any other errors.

Default plug-ins
The EPAgent includes a library of default plug-ins that may be used with minimal
configuration. The following table summarizes the function of each plug-in and
the operating systems they are supported on.

Plug-in Function Supported on

process availability looks for a running process with a given Windows 2000,
check name Solaris
OS-level disk statistics reports reads/writes, transaction times, Windows 2000,
% time waiting, disk capacity, etc. Solaris
Apache log reader reports number of HTTP errors, number Windows 2000,
of transactions, average transaction size Solaris

Environment Performance Agent overview „ 5

CA Wily Introscope

Plug-in Function Supported on

WebLogic log reader reports error count, warning count Windows 2000,
Solaris
WebSphere log reader reports error count, warning count Windows 2000,
Solaris
IIS log reader reports number of errors by type, Windows 2000,
number of pages served, number of Solaris 2.7, 8
users by IP address
HTTP Service reports connection success/failure, Windows 2000,
Availability connection round-trip time, average Solaris 2.7, 8
HTTPS Service throughput/bandwidth
Availability
Solaris Kstat statistics reports any statistics available through Solaris 2.7, 8
Kstat utility, such as I/O statistics,
network statistics for all devices, virtual
memory statistics

Custom plug-ins
The EPAgent supports gathering data from arbitrary programs and plug-ins, with
the requirement that they produce output in one of two supported formats. For
more information, see Using custom plug-ins with the EPAgent on page 13.

Installing the Environment Performance Agent

Using the EPAgent included with base Introscope installation
The EPAgent, all necessary configuration files, and default plug-ins are provided
with all base Introscope 7.2 installations. The following are the EPAgent files
installed in <Introscope home> with the base installation:
„ config/IntroscopeEPAgent.properties

„ lib/EPAgent.jar

„ epaplugins/ (top-level directory for plug-ins)

† epaplugins/apache/apacheLogReader.pl
† epaplugins/iis/iisLogReader.pl
† epaplugins/iis/LogReader.cfg
† epaplugins/solaris/diskStats.pl
† epaplugins/solaris/kstat.pl
† epaplugins/solaris/httpSvcAvailability.pl
† epaplugins/solaris/processAvailability.pl

6 „ Installing, Configuring, and Using the EPAgent

 Environment Performance Agent Guide

† epaplugins/weblogic/weblogicLogReader.pl
† epaplugins/websphere/websphereLogReader.pl
† epaplugins/windows/diskStats.pl
† epaplugins/windows/httpSvcAvailability.pl
† epaplugins/windows/processAvailability.pl

Using the EPAgent standalone installer

The EPAgent can also be installed on another machine using one of the
standalone installers available from your Wily representative:
„ EPAgent7.2.x.ywindows.zip

„ EPAgent7.2.x.yebcdic.tar

„ EPAgent7.2.x.yunix.tar

After extracting the EPAgent installer, these files are installed into the <EPA
directory>/epagent directory:

„ config/IntroscopeEPAgent.properties

„ lib/EPAgent.jar

„ epaplugins/ (top-level directory for plug-ins)

† epaplugins/apache/apacheLogReader.pl
† epaplugins/iis/iisLogReader.pl
† epaplugins/solaris/diskStats.pl
† epaplugins/solaris/kstat.pl
† epaplugins/solaris/httpSvcAvailability.pl
† epaplugins/solaris/processAvailability.pl
† epaplugins/weblogic/weblogicLogReader.pl
† epaplugins/websphere/websphereLogReader.pl
† epaplugins/windows/diskStats.pl
† epaplugins/windows/httpSvcAvailability.pl
† epaplugins/windows/processAvailability.pl
» Note Since the file structure of the EPAgent files is parallel within the
<Introscope home> and <EPAgent directory>/epagent, for
simplicity, we will show file examples originating in <Introscope
home>.

Installing the Environment Performance Agent „ 7

CA Wily Introscope

Configuring the Environment Performance Agent

The EPAgent includes a set of Agent configuration properties, such as Enterprise
Manager location and port settings.

» Note The EPAgent will fail to start if it encounters any errors in the properties
file settings—for example, invalid filename path—so be sure properties
are set correctly if you are going to be starting the EPAgent automatically
at boot-time.

1 Configure the EPAgent settings in the IntroscopeEPAgent.properties file.

The settings for the EPAgent are the same type as found in the Introscope Agent
profile, and are explained in the Introscope 7.2 Java Agent Guide.
2 By default, the EPAgent looks for its properties file at <Introscope home>/
config/IntroscopeEPAgent.properties. If you change the name or location
of this file, you can set it with the Java system property:
-Dcom.wily.introscope.epagent.properties=filename
» Note This system property should immediately follow “java” in the command
line. If it is placed later on the commandline—for example, after -jar—
it will not work.

Configuring Environment Performance Agent logging options

By default, the EPAgent sends message and error output to the console. You can
configure the EPAgent to also send message and error output to a logfile.

‹ Open the file <Introscope home>/config/IntroscopeEPAgent.properties.

Running EPAgent in verbose mode

Running the EPAgent in verbose mode records details to the log, which is helpful
in debugging.

1 Open the file <Introscope home>/config/IntroscopeEPAgent.properties.

2 In the property log4j.logger.EPAgent, replace INFO with the following:
VERBOSE#com.wily.util.feedback.Log4JSeverityLevel
3 Save changes and close the IntroscopeEPAgent.properties file.

Redirect EPAgent output to a file

To redirect Agent output to a file:

1 Open the file <Introscope home>/config/IntroscopeEPAgent.properties.

2 In the property log4j.logger.EPAgent, replace console with logfile.

8 „ Installing, Configuring, and Using the EPAgent

 Environment Performance Agent Guide

For example, if you wanted the EPAgent to report in Verbose mode to a logfile,
the property would look like this:
log4j.logger.EPAgent=VERBOSE#com.wily.util.feedback.Log4JSeverityL
evel,logfile
3 If desired, change the name and/or location of the EPAgent logfile in the property
log4j.appender.logfile.File.
4 Save changes and close the IntroscopeEPAgent.properties file.

Configuring Environment Performance Agent plug-ins

To run EPAgent using the default plug-ins, you simply need to uncomment certain
properties in IntroscopeEPAgent.properties.

However, you may want to remove plug-ins you don’t need from the default plug-
ins in the IntroscopeEPAgent.properties file, or add additional plug-ins.

EPAgent plug-ins are separated into two sections in the

IntroscopeEPAgent.properties file, stateful and stateless.

Adding stateful plug-ins

Plug-ins used by the EPAgent are configured in the
IntroscopeEPAgent.properties file.

1 Open the file <Introscope home>/config/IntroscopeEPAgent.properties.

2 Uncomment the property introscope.epagent.plugins.stateful.names,
and add the names for all stateful plug-ins, separated by commas, as in the
following example:
introscope.epagent.plugins.stateful.names=APACHE,WEBLOGIC,WEBSPHERE,IIS
3 For each stateful plug-in name added in the previous step, add a line specifying
the full command required to launch or start the stateful plug-in, including any
command-line arguments desired. For more information see EPAgent Default
Plug-ins on page 21.
» Note You can use the default properties in the file by uncommenting them, but
you must include the full command-line required to launch or start the
plug-in.

The stateful names property specified in the previous step would require four
lines:
introscope.epagent.stateful.APACHE.command=/usr/bin/perl <Introscope
home>/epaplugins/apache/apacheLogReader.pl
introscope.epagent.stateful.WEBLOGIC.command=/usr/bin/perl <Introscope
home>/epaplugins/weblogic/weblogicLogReader.pl

Configuring the Environment Performance Agent „ 9

CA Wily Introscope

introscope.epagent.stateful.WEBSPHERE.command=/usr/bin/perl <Introscope
home>/epaplugins/websphere/websphereLogReader.pl
introscope.epagent.stateful.IIS.command=/usr/bin/perl <Introscope home>/
epaplugins/iis/iisLogReader.pl
» Note On Windows machines, when adding a path, you must escape a
backslash (\) with another backslash (each one doubled), such as:

introscope.epagent.stateful.TEST.command=perl
c:\\mydirectory\\myscript.pl

For information on running the EPAgent default plug-ins with additional

command-line arguments, see EPAgent Default Plug-ins on page 21.

Next steps
Continue to the next section, Adding stateless plug-ins on page 10, if adding
stateless plug-ins. Otherwise, save changes and restart the EPAgent if you are
finished.

Adding stateless plug-ins

1 Open the file <Introscope home>/config/IntroscopeEPAgent.properties.
2 In the property introscope.epagent.plugins.stateless.names,
uncomment the property, and add the logical names for all stateless plug-ins,
separated by commas, as in the following example:
introscope.epagent.plugins.stateless.names=DISK,ORACLE,HTTP,KSTAT
3 For each stateless plug-in name added in the previous step, add two additional
lines specifying:
„ the full command-line required to launch or start the stateless plug-in
(including any command-line arguments desired, see EPAgent Default Plug-ins
on page 21), with the following syntax:
introscope.epagent.plugins.stateless.<pluginname>.command= <command>
„ the frequency that the EPAgent runs the plug-in, as a delay in seconds, with
the following syntax:
introscope.epagent.stateless.<pluginname>.delayInSeconds=
<value in seconds>
For example:
introscope.epagent.stateless.DISK.command=/usr/bin/perl <Introscope
home>/epaplugins/solaris/diskStats.pl
introscope.epagent.stateless.DISK.delayInSeconds=900
introscope.epagent.stateless.ORACLE.command=/usr/bin/perl <Introscope
home>/epaplugins/solaris/processAvailability.pl
introscope.epagent.stateless.ORACLE.delayInSeconds=900

10 „ Installing, Configuring, and Using the EPAgent

 Environment Performance Agent Guide

introscope.epagent.stateless.HTTP.command=/usr/bin/perl <Introscope
home>/epaplugins/solaris/httpSvcAvailability.pl
introscope.epagent.stateless.HTTP.delayInSeconds=900
introscope.epagent.stateless.KSTAT.command=/usr/bin/perl <Introscope
home>/epaplugins/solaris/kstat.pl
introscope.epagent.stateless.KSTAT.delayInSeconds=900
» Note The examples above are the default values for these properties. To use
them, uncomment each of the properties.

For information on running the EPAgent default plug-ins with additional

command-line arguments, see EPAgent Default Plug-ins on page 21.
4 Save changes and restart the EPAgent if you are finished.

Removing stateful and stateless plug-ins

To remove stateful and stateless plug-ins:

1 Open the file, <Introscope home>/config/

IntroscopeEPAgent.properties.
2 In the properties, introscope.epagent.stateful.names, and
introscope.epagent.stateless.names delete the names of plug-ins you
want removed.
3 Either comment out or delete any command lines associated with the plug-ins you
are deleting.
4 Save changes and restart the EPAgent if you are finished.

Configuring Java class plug-ins

To configure a plug-in that is a Java class that is executed within the EPAgent
JVM, configure these properties in the EPAgent properties file:

introscope.epagent.stateful.JAVA-CLASS.class=my.package.path.Class
arg1 arg2 arg3
» Note Supply the fully qualified class name followed by any optional
arguments, for example:

introscope.epagent.plugins.stateful.names=add

introscope.epagent.stateful.add.class=com.wily.math.Add 1 2

Configuring the Environment Performance Agent „ 11

CA Wily Introscope

Configuring the EPAgent for network data sources

Configuring the EPAgent for simple or XML network input

To enable the EPAgent to accept data over the network, uncomment this line in
the EPAgent properties file:
introscope.epagent.config.networkDataPort=8000

Configuring the EPAgent for HTTP GET input

You can create a simple HTTP server in the EPAgent that listens to HTTP GET
requests. The HTTP GET request determines what metrics are sent to the
Enterprise Manager

HTTP GET requests should follow the following syntax:

http://epaHost:epaPort/?metricType=type&metricName=name&metricValue=
value

To enable and test the simple HTTP server:

1 Enable the simple HTTP server by uncommenting the following property in

EPAgent properties file.
introscope.epagent.config.httpServerPort=9090
Restart the EPAgent for the change to take effect.
2 Test the HTTP GET request through a browser. For example:
http://localhost:9090/?metricType=IntCounter&metricName=
MyHTTPMetric|Test:MyCounter&metricValue=15
After 15 seconds, you should see the MyHTTPMetric|Test:MyCounter metric
under your EPAgent.
3 To update the metric, the EPAgent needs to receive a new HTTP GET request.
Therefore, the simple HTTP server functionality is intended to be used with a tool
that can issue multiple HTTP GET requests. For example, you can use the open-
source tool Wget to issue multiple wget commands to create multiple HTTP GET
requests. More information on Wget is available at:
http://www.gnu.org/software/wget/wget.html

12 „ Installing, Configuring, and Using the EPAgent

 Environment Performance Agent Guide

Running the Environment Performance Agent

The EPAgent can be run as either a standalone .jar file, or a Java application.

To run the EPAgent as a standalone .jar file:

‹ Run a Java command-line with the appropriate -jar flag, as in:

java -jar <Introscope home> /lib/EPAgent.jar

To run the EPAgent as a Java application:

‹ Add the EPAgent files to the appropriate classpath as in the following example:

java -classpath "<Introscope home>/lib/EPAgent.jar"

com.wily.introscope.api.IntroscopeEPAgent

Using custom plug-ins with the EPAgent

Running the EPAgent with the default plug-ins gathers information that is usually
sufficient for most user’s needs. However, you may want to use custom plug-ins
with the EPAgent. To do this, observe two guidelines:
„ Make sure the output of the custom plug-ins can be parsed by the EPAgent (see
Formats for data below, and Error or event data format on page 15).
„ Add the custom plug-ins in the IntroscopeEPAgent.properties file as
described in the section Configuring Environment Performance Agent plug-ins on
page 9.

Formats for data

Metric data format

The EPAgent can parse metric data provided by plug-ins (or other metric-
producing programs plugged into the EPAgent) in two different formats:
„ Simple

„ XML

Simple format for metric data

Specify one metric name and value per line using the format:

<metric_name>=<value>

For example:

diskWrites=37

You can also include a reference to a resource segment:

Running the Environment Performance Agent „ 13

CA Wily Introscope

<resource_segment>:<metric_name>=<value>

For example (all one line):

Resource Usage|File IO:diskWrites=37

Apache Errors:LastErrorString=ERROR: Apache shutdown unexpectedly

Simple format guidelines:

„ In the “simple” format, the metric name should not contain an equals sign (=).
If there is need for an equals sign in the name, use the XML format.
„ The value may contain an equals sign (string), and the EPAgent will always
parse all characters up to the first equals sign (left to right) as the metric
name, and all characters after the first equals sign as the value.
„ Any value composed of numeric digits will be interpreted as numeric data and
will be reported as an Introscope “IntCounter” type.
„ Any value composed of anything other than numeric digits will be interpreted
as string data and will be reported as an Introscope “string event” type.

XML format for metric data

Where the “simple” format limits the Introscope metric types, XML style format
allows the plug-in to report additional information, such as Introscope metric
name, Introscope metric type, and value, as in the following example:
<metric type="LongCounter" name="Resource Usage|File IO:diskWrites"
value="37" />
<metric type="StringEvent" name="Apache Errors:LastErrorString"
value="ERROR: Apache shutdown unexpectedly" />

XML format guidelines:

„ This allows full support of Introscope data types as well as equals signs in both
metric names and values.
„ The “type” attribute of a metric must be one of the following:

† PerIntervalCounter
† IntCounter
† IntAverage
† IntRate
† LongCounter
† LongAverage
† StringEvent
† Timestamp
„ The comparison is case-insensitive (to make it easy for the plug-in writer). If
a numeric type is supplied, but the value is non-numeric, nothing is reported
to Introscope and an error will be logged by the EPAgent.

14 „ Installing, Configuring, and Using the EPAgent

 Environment Performance Agent Guide

Precautions with either type of custom plug-in format

„ Supporting both formats causes an interaction where the system will not
recognize metric names that start with the less-than sign.
„ With both formats, if the format is unparseable (garbage or incorrect syntax),
the EPAgent ignores the line and logs an error.
„ In the case of multiple lines being returned by the plug-in, parsing will continue
with the next line.
„ For each metric name, only one metric type may be specified. If more than one
type is specified, the following error will occur:
mm/dd/yy hh:mm:ss PM PDT [ERROR] [EPAgent] Metric name from plugin 'Plugin
<plugin_name>' is invalid: "<metric_name>" is already in use by another
DataRecorder of a different type

Error or event data format

The EPAgent can parse error or event data provided by plug-ins in two different
formats:
„ Simple

„ XML

Simple format for error or event data

In general, simple format scripts start with the following fixed string:

event:

Everything after the colon:

„ is part of a "name=value" pair, with each pair separated by the ampersand
character (&).
„ is an optional parameter to the event.

The example below is the output of a hypothetical script that monitors the Firefox
browser process and sends a notification when the browser exits.

event:type=processWentAway&processName=firefox

Simple XML format for error or event data

Events can also be specified in an XML format, which gives the full expressive
power of events in the Agent. The simplest XML format event gives the name of
a resource that generated the event (an example might be “Connection Pool” or
“Java Virtual Machine”). The example below provides a notification that some
event happened in Some Resource.

<event resource="Some Resource"/>

Using custom plug-ins with the EPAgent „ 15

CA Wily Introscope

The timestamp will be the time the event was created, and the duration of the
event will be zero.

XML Format for error or event data with parameters and time data

You can configure event notification with an explicit timestamp and an explicit
duration. The timestamp format is any Java-parsable format. The duration is in
milliseconds. The example below is an event with a duration of one minute.

<event resource="Some Resource" starttime="Nov 29 2007 11:28:00"

duration="60000">
<param name="urgent" value="true"/>
</event>

Creating an error snapshot in XML format

An error snapshot must indicate its type as an error snapshot in the parameters:

<event resource="Some Resource" starttime="Nov 29 2005 11:28:00"

duration="60000">
<param name="Trace Type" value="ErrorSnapshot"/>
</event>

Nested components

The example below shows an event with nested subcomponents. An event can
have from zero to an infinite number of sub-components, and each of those can
also have from zero to an infinite number of sub-components. In practice, the
level of nesting tends to be small or zero.

<event resource="Some Resource">

<calledComponent resource="Another Resource">
<param name="isCorrelated" value="uncertain"/>
<calledComponent resource="A Third Resource"/>
<calledComponent resource="A Fourth Resource"/>
</calledComponent>
</event>

EPAgent events and transaction traces

You can view EPAgent events in the Event Viewer as transaction traces by
selecting the Trace View tab.

Trace views are easier to understand if time information is contained in the event
sent by the EPAgent. To do this, use the startTime and offset attributes on
the <event> and <calledComponent> tags.

16 „ Installing, Configuring, and Using the EPAgent

 Environment Performance Agent Guide

The startTime attribute is absolute time. Its format is anything that can be
parsed by java.util.Date.parse(). Specifying startTime in the <event>
element is not required—if absent, it defaults to the value of the current time, as
specified by the Java methods System.currentTimeMillis() or new
Date().getTime(). Omitting startTime from a <calledComponent> element
makes the time default to the time of the containing element, so that if no
startTime attribute is specified anywhere, everything defaults to the current
time.

The offset attribute is an integer value. It is interpreted as time in milliseconds

and is added to the startTime attribute (whether startTime is default or
explicit) to produce the actual time reported for the <event> or
<calledComponent>.

Example 1
<event resource="Customized Web Server" startTime="123456789"
duration="500">
<calledComponent resource="Web Server Module" offset="300"
duration="100"/>
</event>

The trace view of this event will have "Customized Web Server" starting at
1234567879 and "Web Server Module" starting at 123457089 (123456789 +
300). Specifying a duration in each element produces a useful trace view
showing:
„ "Customized Web Server" running 300 milliseconds

„ "Web Server Module" called by "Customized Web Server" and running for 100
milliseconds
„ "Customized Web Server" running for another 100 milliseconds after "Web
Server Module" returns

Example 2
<event resource="Customized Web Server" duration="500">
<calledComponent resource="Web Server Module" offset="300"
duration="100"/>
</event>

This example is similar to Example 1 except that "Customized Web Server" starts
at the current time, and "Web Server Module" starts 300 milliseconds later. Note
how no part of this example requires the EPAgent script to know the current time.

Using custom plug-ins with the EPAgent „ 17

CA Wily Introscope

Example 3
<event resource="Customized Web Server" startTime="123000000" offset="1000"
duration="5000">
<calledComponent resource="Web Server Module" startTime="123003000"
duration="200"/>
</event>

Here "Customized Web Server" starts at 123001000 (123000000 + 1000) and

"Web Server Module" starts at 123003000.

Notice again how specifying durations promotes readability and usability.

Incorrectly specifying startTimes, offsets and durations can make trace views
hard to read, so care must be taken when using them. In particular, the start
time—computed by adding startTime and offset of a <calledComponent>
element—should always be after the start time of its containing <event> or
<calledComponent> and the (start time + duration) of a <calledComponent>
should always be less than the (start time + duration) of its containing <event>
or <calledComponent>.

XML schema for error or event data

The formal XSD schema supported is:

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified" attributeFormDefault="unqualified">
<xs:element name="event" type="eventElement">
<xs:annotation>
<xs:documentation>The root element for events. This element is
nearly equivalent to the calledComponent element, except that the event
element must occur only once, at the outermost level.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="param">
<xs:complexType>
<xs:attribute name="name" type="xs:string" use="required"/>
<xs:attribute name="value" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
<xs:element name="calledComponent" type="eventElement">
<xs:annotation>
<xs:documentation>A component called by the containing element.
This element is nearly equivalent to the event element, except that this
element cannot occur at the outermost level.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:complexType name="eventElement">

18 „ Installing, Configuring, and Using the EPAgent

 Environment Performance Agent Guide

<xs:sequence>
<xs:element ref="param" minOccurs="0" maxOccurs="unbounded"/>
<xs:element ref="calledComponent" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="startTime" type="xs:dateTime" use="optional"/>
<xs:attribute name="offset" type="xs:integer" use="optional"
default="0"/>
<xs:attribute name="duration" type="xs:dateTime" use="optional"
default="0"/>
</xs:complexType>
</xs:schema>

Using custom plug-ins with the EPAgent „ 19

CA Wily Introscope

20 „ Installing, Configuring, and Using the EPAgent

CHAPTER
2

EPAgent Default Plug-ins

This section describes the provided default plug-ins provided with Introscope
Environment Performance Agent and their optional command-line arguments in
the following sections:

solaris/diskStats.pl . . . . . . . . . . . . . . . . . . 22
windows/processAvailability.pl AND solaris/processAvailability.pl . . . 22
windows/diskStats.pl . . . . . . . . . . . . . . . . . . 23
apacheLogReader.pl, weblogicLogReader.pl, and websphereLogReader.pl . 24
httpSvcAvailability.pl . . . . . . . . . . . . . . . . . . 25
kstat.pl . . . . . . . . . . . . . . . . . . . . . . 26
iisLogReader.pl . . . . . . . . . . . . . . . . . . . 27

EPAgent Default Plug-ins „ 21

CA Wily Introscope

solaris/diskStats.pl
This plug-in returns metrics containing information about the system hard disks.

Metrics produced
Metrics produced by the /solaris/diskStats.pl plug-in are detailed in Solaris
kernel statistics (Kstat) metrics on page 37.

Command-line arguments
This plug-in takes disk names as command-line arguments. If no disk names are
specified, the information about all disks is reported.

„ For example, the following command reports metrics on all local disks:

perl diskStats.pl
„ The following command reports metrics on only the disks '/' and '/usr':

perl diskStats.pl / /usr

» Note You may want to use this argument to narrow your results.

windows/processAvailability.pl AND solaris/

processAvailability.pl
This plug-in returns a metric with a value equal to the number of process names
that match the passed in argument value. The type of metric returned is
'IntCounter'.

Metrics produced
Metrics produced by the /windows/processAvailability.pl and solaris/
processAvailability.pl plug-in are detailed in Process availability metrics on
page 38.

Command-line arguments
Each of these plug-ins take five optional command-line arguments:

Command Line Argument Definition

match Regular Perl expression to search for
resource Resource part of the metric name
subResource Sub-resource part of the metric name

22 „ EPAgent Default Plug-ins

 Environment Performance Agent Guide

Command Line Argument Definition

metric Main part of the metric name
distinctMatch This has no value and determines whether to keep
and report counts for each regular expression match
separately. This option overrides the value of the
subResource argument if it is specified.

The following example reports the number of processes that begin with the
characters 'sh':

perl processAvailability.pl -match ^sh

windows/diskStats.pl
This plug-in reports disk usage/capacity statistics based on the statistics
available from the Windows 2000 Performance Monitor.

In order for this plug-in to report all statistics properly you must issue the
'diskperf -y' command. You must then reboot your machine in order to activate
the new settings.

Metrics produced
Metrics produced by the /windows/diskStats.pl plug-in are detailed in Disk
Stats (Win 2000) metrics on page 38.

Command-line arguments
This plug-in takes disk names as command-line arguments. If no disk names are
specified, information about all disks is reported.

„ For example, the following command reports metrics on all local disks:

perl diskStats.pl
„ The following command reports metrics on only the disks c: and d:

perl diskStats.pl c: d:
» Note You may want to use this argument to narrow your results.

windows/diskStats.pl „ 23
CA Wily Introscope

apacheLogReader.pl, weblogicLogReader.pl, and

websphereLogReader.pl
These plug-ins report metrics based on the metrics configured in the
<webserver>LogReader.cfg file.

Each web server application logfile parser has its own configuration file with the
default values for sleep delay, subresource name, resource name, logfile
directory, and logfile name pattern.

» Note When using any of these log reader plug-ins, the EPAgent won’t begin
reporting to the Enterprise Manager until a new entry is added to the log
file.

Metrics produced
Metrics produced by these plug-ins are detailed in:

„ Apache log metrics on page 39

„ WebSphere log metrics on page 40

„ WebLogic log metrics on page 41

Command-line arguments
Each of these plug-ins take four optional command-line arguments:

Command Line Argument Definition

logfileDir Directory in which the logfiles are located
sleepTime Number of seconds to delay between each check of
the logfile for new messages
logfile Regular expression that corresponds to the name
of the logfiles generated
subResource Sub-resource part of the metric name

Example:

perl apacheLogReader.pl -sleepTime 30 -logfileDir "c:/Apache/logs"

24 „ EPAgent Default Plug-ins

 Environment Performance Agent Guide

httpSvcAvailability.pl
This plug-in reports metrics based on the availability and performance of the http
service at the specified URL.

Metrics produced
Metrics produced by the httpSvcAvailability.pl plug-in are detailed in
HTTP/HTTPS service availability metrics on page 37.

Command-line arguments
This plug-in takes three optional command-line arguments:

Command Line Argument Definition

url A comma-delimited set of URLs with optional port
numbers. The URLs can include port numbers (if
they are different from defaults) as well as http: or
https: to differentiate HTTP vs. HTTPS.
get Requests a comma-delimited list (no spaces) of
HTTP requests to issue to the server.
Some web sites may not allow HEAD requests or
some application servers may not support GET.
Must specify at least one of: GET,HEAD
If both GET and HEAD are specified, then HEAD is
executed
first, followed by GET.
Default: -request HEAD
metric A comma-delimited listing of metrics to return
„ av = Availability / Can Connect (0=no, 1=yes)
„ rt = Round-trip Response Time (for connect)
„ tp = Throughput (kbytes. #Kbytes returned /
round-trip response)
„ all = all statistics
Default: all

Example:

perl epaplugins/solaris/httpSvcAvailability.pl -url https://

secure.server.com,http:8080//IIS.server.com

Perl support issues

„ For httpSvcAvailability.pl plug-in (HTTP):

httpSvcAvailability.pl „ 25
CA Wily Introscope

The httpSvcAvailability.pl plug-in (HTTP) requires the Perl library, libwww-perl

(v5.65+), to be installed for basic http service checking. www.activestate.com
provides Perl v5.6.1 which includes libwww-perl as part of the installation.
„ For httpSvcAvailability.pl plug-in (HTTPS):

† For https service checking on Windows, Crypt-SSLeay (v0.17.1+), should be

installed.
† For https service checking on Solaris, Net-SSLeay (v1.05+), should be
installed. Both of these are most easily installed using the ppm Package
Manager tool included with ActiveState’s Perl.

kstat.pl
This plug-in reports metrics based on the kernel statistics available from Solaris’s
Kstat utility.

Metrics produced
Metrics produced by the kstat.pl plug-in are detailed in Solaris kernel statistics
(Kstat) metrics on page 37.

Command-line arguments

This plug-in takes four command-line arguments:

Command Line Argument Definition

class Regular expression that will match a kstat class
module Regular expression that will match a kstat module
name Regular expression that will match a kstat name
statistic Regular expression that will match a kstat statistic

» Note You may want to use these arguments to narrow your results. If no
command-line switches are specified, the plug-in will return all Solaris
kernel information for class, module, name and statistics.

Example:

perl epaplugins/solaris/kstat.pl -class vm -module unix -name segmap -

statistic '^free'

The Introscope metric would create node VM, then resource UNIX, then segmap,
then see “free”, then value.

26 „ EPAgent Default Plug-ins

 Environment Performance Agent Guide

» Note If kstat reports a null value for a resource name, no metric will be
generated.

Perl support issues

For best performance, it is recommended that the kstat.pl plug-in be run with
the Solaris-supplied Perl (typically found in /usr/bin/perl with Perl libraries
installed in /usr/perl5) as this supports a direct interface to the Solaris kernel
subsystem via an included Perl library. If the kstat.pl plug-in is run with a
different Perl installation, then the kstat.pl command-line utility will be used,
which may incur slightly higher overhead.

iisLogReader.pl
This plug-in reports metrics based on the configuration in the
iisLogReader.cfg file.

» Note When using this log reader plug-in, the EPAgent won’t begin reporting to
the Enterprise Manager until a new entry is added to the log file.

Metrics produced
Metrics produced by the iisLogReader.pl plug-in are detailed in IIS log reader
metrics on page 36.

Command-line arguments

This plug-in takes four optional command-line arguments:

Command Line Argument Definition

logfileDir Directory in which the logfiles are located
sleepTime Number of seconds to delay between each check of
the logfile for new messages
logfile Regular expression that corresponds to the name of
the logfiles generated
subResource Sub-resource part of the metric name

Example:

perl iisLogReader.pl -sleepTime 30 -logfileDir "c:/Program Files/iis/logs"

iisLogReader.pl „ 27
CA Wily Introscope

iisLogReader.cfg Configuration File

The iisLogReader.cfg file contains values for the command-line arguments in
the iisLogReader.pl file.

Each web server application logfile parser has its own configuration file with
default values for sleep delay, subresource name, resource name, logfile
directory, and logfile name pattern. The config file also contains a list of metrics
to match and report on. Each metric configuration has a match (regular
expression), metricType, metricName, and metricValue.

Property Name Default Value Description

LOGFILEDIR C:/WINNT/system32/ Full directory pathname that contains the
LogFiles/W3SVC1 logfiles for the associated web server.
Note: Forward slashes are valid path
separators for Windows paths
(back slashes are acceptable as
well).
LOGFILE ex(tend)?\d+\.log Name of the logfile to read. This should be
a regular expression if it changes over
time (e.g. rotating logfiles). The match is
case-insensitive.
Note: this must match the entire name
of the file (without path).
Note: the default is set up to match
logfile names when IIS is
configured for W3C Extended Log
File Format, which is the only
supported format by the
iisLogReader.pl plug-in.
SLEEPTIME 15 Number of seconds to delay between each
check of the logfile for new messages.
Because counter metrics are defined as
“per interval” (see metric table),
generally, SLEEPTIME should be set equal
to or greater than the Enterprise Manager
time slice (i.e. 15 seconds), otherwise the
counter metrics will be incorrect.
RESOURCE IISWebServer Resource part of the Introscope metric
name. This corresponds to the first node
underneath the Agent node in the
Workstation Investigator.

28 „ EPAgent Default Plug-ins

 Environment Performance Agent Guide

Property Name Default Value Description

SUBRESOURCE <empty> Subresource part of the Introscope metric
name. This corresponds to the sub-nodes
underneath the Resource node specified
above.
LINE_FORMAT Defines the exact line format logged by
the IIS Web Server.
Sub-properties for line format are
described in the LINE_FORMAT Sub-
properties table.

LINE_FORMAT sub-properties
The following table describes the property, LINE_FORMAT, and all its sub-
properties.

The following properties for LINE_FORMAT must match EXACTLY the fields that
are logged to the logfile by the IIS Web Server, or the iisLogReader.pl plug-
in will fail to report some or all metrics.

The exact fields for the IIS Web Server are configured within the IIS Admin Tool
(or web page in older versions of IIS). To configure logging fields in IIS4.0 and
IIS5.0, see Configuring IIS Web Server logging in IIS4.0 and IIS5.0 on page 32.

By default, IIS Web Server logs only five fields:

„ Time

„ ClientIPAddress

„ Method

„ URIStem

„ ProtocolStatus

To match, the default iisLogReader.cfg file also enables only these five
LINE_FORMAT sub-properties.

So out of the box, the iisLogReader.pl plug-in will expect a default IIS Web
Server logging configuration, and can report all metrics, with the exception of
“Bytes Transferred,” which requires that the “BytesSent” data field be logged by
IIS Web Server and the iisLogReader.cfg sub-property, “BytesSent,” be
uncommented/enabled. If the user fails to enable “BytesSent” in IIS Web Server
and in the iisLogReader.cfg, then the metric, “Bytes Transferred,” will not be
reported to Introscope.

iisLogReader.pl „ 29
CA Wily Introscope

If a sub-property line is uncommented, it means that the iisLogReader.pl

plug-in will expect to find that field in the IIS Web Server logfile (as specified by
the LOGFILEDIR and LOGFILE properties). Conversely, if the sub-property line is
commented, it means that the iisLogReader.pl plug-in does not expect to find
the field in the logfile. The order of the sub-property lines already match the left-
to-right order that the IIS Web Server will log the data in (if the fields were
enabled in IIS Web Server), hence, the ordering should not be changed.

LINE_FORMAT Default Value Description

Sub-Property Name
DELIMITER \s+ Continuous whitespace (spaces,
tabs)
FIELDS
FIELDS->Date \d\d\d\d-\d\d-\d\d The date on which the activity
occurred. YYYY-MM-DD.
FIELDS->Time \d\d\d\d-\d\d-\d\d Enabled by default.
The time the activity occurred.
24HH:MM:SS GMT.
FIELDS- \d+\.\d+\.\d+\.\d+ Enabled by default.
>ClientIPAddress The IP address of the client that
accessed your server. Four
numbers, separated by periods.
FIELDS->UserName [-\\\w]+ The name of the user who
accessed your server. Any
combination of -, backslash, and
alphanumeric characters.
FIELDS->ServiceName \w+ The Internet service that was
running on the client computer.
Any combination of alphanumeric
characters.
FIELDS->ServerName [.-\w]+ The name of the server on which
the log entry was generated. Any
combination of period, hyphens,
alphanumeric characters.
FIELDS- \d+\.\d+\.\d+\.\d+ The IP address of the server on
>ServerIPAddress which the log entry was
generated. Four numbers,
separated by periods.
FIELDS->ServerPort \d+ The port number the client is
connected to. One or more digits.
FIELDS->Method GET|HEAD|PUT|POST| Enabled by default.
DELETE The action the client was trying to
perform (for example, a GET
command).

30 „ EPAgent Default Plug-ins

 Environment Performance Agent Guide

LINE_FORMAT Default Value Description

Sub-Property Name
FIELDS->URIStem \S+ Enabled by default.
The resource accessed; for
example, an HTML page, a CGI
program, or a script. A sequence
of non-spaces.
FIELDS->URIQuery \S+ The query, if any, the client was
trying to perform; that is, one or
more search strings for which the
client was seeking a match. A
sequence of non-spaces.
FIELDS- \d+ Enabled by default.
>ProtocolStatus The status of the action, in HTTP
terms.
FIELDS->Win32Status \d+ The status of the action, in terms
used by Windows. One or more
digits.
FIELDS->BytesSent \d+ The number of bytes sent by the
server. One or more digits.
NOTE: This field is not enabled by
default in IIS. It must be turned on
in order to collect the “Bytes
Transferred” metric.
FIELDS- \d+ The number of bytes received by
>BytesReceived the server. One or more digits.
FIELDS->TimeTaken \d+ The length of time the action took
in milliseconds. One or more
digits.
FIELDS- [\w/.]+ The protocol (HTTP, FTP) version
>ProtocolVersion used by the client. For HTTP this
will be either HTTP 1.0 or HTTP
1.1. A sequence of alphanumeric
characters, forward slash, and
periods.
FIELDS->Host [\w.:]+ The host of the client. A sequence
of alphanumeric characters,
period, colons.
FIELDS->UserAgent \S+ The browser used on the client. A
sequence of non-spaces.
FIELDS->Cookie \S+ The content of the cookie sent or
received, if any. A sequence of
non-spaces.
FIELDS->Referer \S+ The site that directed the user to
the current site. A sequence of
non-spaces.

iisLogReader.pl „ 31
CA Wily Introscope

Configuring IIS Web Server logging in IIS4.0 and IIS5.0

1 Start Internet Services Manager.
2 On the left side, expand the tree node for your machine.

You should see three nodes:

„ FTP Site

„ Web Site

„ SMTP Virtual Server

3 Right-click on the Web Site node and select Properties.

The Properties dialog window will appear.

4 Select the Web Site tab and ensure that:

„ the Enable Logging checkbox is selected

„ W3C Extended Log File Format is selected in the Active log format drop-
down box.
» Note Only W3C Extended Log File Format is supported in Introscope version
4.2.x.

5 Click Properties.

32 „ EPAgent Default Plug-ins

 Environment Performance Agent Guide

The Extended Logging Properties dialog window appears.

6 In the General Properties tab, the LogFile Directory is specified and must match
the LOGFILEDIR property in the iisLogReader.cfg file.
7 In the Extended Properties tab, the following fields are required/mandatory for
the iisLogReader.pl plug-in to report all of its metrics:
„ Time

„ Client IP Address

„ Method

„ URIStem

„ Protocol Status

„ Bytes Sent (required in order to see Bytes Transferred)

All fields that are enabled (are checked) must match the enabled (uncommented)
fields in the iisLogReader.cfg file, under the LINE_FORMAT->FIELDS section.
This part of the iisLogReader.cfg file tells the iisLogReader.pl plug-in what
exact line format to expect in the logfile. If there is a mis-match, then the
iisLogReader.pl plug-in will fail to report metrics or will report incorrect
metrics.
» Note The default iisLogReader.cfg matches the default IIS Web Server 5.0
logging configuration.

iisLogReader.pl „ 33
CA Wily Introscope

34 „ EPAgent Default Plug-ins

CHAPTER
3

Metrics Produced By Environment

Performance Agent Default Plug-ins

This chapter describes the metrics produced by the default plug-ins included with
the Environment Performance Agent.

Information is presented in the following sections:

Invalid character replacement . . . . . . . . . . . . . . . 36
IIS log reader metrics . . . . . . . . . . . . . . . . . 36
HTTP/HTTPS service availability metrics . . . . . . . . . . . . 37
Solaris kernel statistics (Kstat) metrics . . . . . . . . . . . . 37
Process availability metrics. . . . . . . . . . . . . . . . 38
Disk Stats (Win 2000) metrics . . . . . . . . . . . . . . . 38
Disk Stats (Solaris) metrics . . . . . . . . . . . . . . . 39
Apache log metrics . . . . . . . . . . . . . . . . . . 39
WebSphere log metrics . . . . . . . . . . . . . . . . . 40
WebLogic log metrics . . . . . . . . . . . . . . . . . . 41

Metrics Produced By Environment Performance Agent Default Plug-ins „ 35

CA Wily Introscope

Metrics produced by EPAgent default plug-ins

Invalid character replacement
All resource, sub-resource, and metric names are checked for invalid characters
not allowed in Introscope metric names. In particular, the pipe character ( | ) and
colon ( : ) are reserved characters. Any user or system-generated names that
contain these characters will automatically have these characters replaced:

Original Replaced By Descriptions

Character
| _ pipes replaced by underscores
: ^ colons replaced by carets

IIS log reader metrics

The following table shows the metrics generated by the iisLogReader.pl plug-
in.

The count for these metrics is per interval, since the last time the plug-in checked
the logfile.

Resource Sub-Resource Metric Introscope Unit Default

Data Type Setting
IISWebServer <Sub-Resource> Total Page Hits IntCounter 1 (hit) on
IISWebServer <Sub-Resource> Total Visitors Count IntCounter 1 (hit) on
IISWebServer <Sub-Resource> Page Hits For <URL> IntCounter 1 (hit) on
IISWebServer <Sub-Resource> Bytes Transferred IntCounter 1 (MB) on
IISWebServer <Sub-Resource> ErrorCount_400_BadR IntCounter 1 (error) on
equest
IISWebServer <Sub-Resource> ErrorCount_401_Unau IntCounter 1 (error) on
thorized
IISWebServer <Sub-Resource> ErrorCount_403_Forbi IntCounter 1 (error) on
dden
IISWebServer <Sub-Resource> ErrorCount_404_Serve IntCounter 1 (error) on
rConfiguration
IISWebServer <Sub-Resource> ErrorCount_500_Inter IntCounter 1 (error) on
nalServerError
IISWebServer <Sub-Resource> ErrorMessage_400_Ba StringEvent N/a off
dRequest
IISWebServer <Sub-Resource> ErrorMessage_401_Un StringEvent N/a off
authorized

36 „ Metrics Produced By Environment Performance Agent Default Plug-ins

 Environment Performance Agent Guide

Resource Sub-Resource Metric Introscope Unit Default

Data Type Setting
IISWebServer <Sub-Resource> ErrorMessage_403_For StringEvent N/a off
bidden
IISWebServer <Sub-Resource> ErrorMessage_404_Pa StringEvent N/a off
geNotFound
IISWebServer <Sub-Resource> ErrorMessage_500_Int StringEvent N/a off
ernalServerError

HTTP/HTTPS service availability metrics

The following table shows the metrics generated by the
httpSvcAvailability.pl plug-in.

Resource Sub-Resource Metric Introscope Unit Default

Data Type Setting
Remote Machine <hostnameOrlPAddr>|S Available IntCounter 0-1 on
ervice|HTTP
Remote Machine <hostnameOrlPAddr>|S Response Time IntCounter sec on
ervice|HTTP
Remote Machine <hostnameOrlPAddr>|S Average IntCounter KB/msec on
ervice|HTTP Throughput
Remote Machine <hostnameOrlPAddr>|S Available IntCounter 0-1 on
ervice|HTTPS
Remote Machine <hostnameOrlPAddr>|S Response Time IntCounter sec on
ervice|HTTPS
Remote Machine <hostnameOrlPAddr>|S Average IntCounter KB/msec on
ervice|HTTPS Throughput

Solaris kernel statistics (Kstat) metrics

The following table shows the metrics generated by the kstat.pl plug-in.

The names of specific metrics produced by the kstat plug-in will vary depending
on both the Solaris system being monitored, Solaris naming concepts, as well as
the command-line invocation of the kstat.pl plug-in by the Environment
Performance Agent (as configured in IntroscopeEPAgent.properties).

Resource Sub-Resource Metric Introscope Data Unit Default

Type Setting
Solaris Kernel <class>|<module>| <stat> IntCounter Varies on
<name>

Metrics produced by EPAgent default plug-ins „ 37

CA Wily Introscope

Process availability metrics

This table shows the metrics generated by the processAvailability.pl plug-
in.

Resource Sub-Resource Metric Introscope Data Unit Default

Type Setting
RunningProcesses <Sub-Resource> Count IntCounter 1 (process) on

Disk Stats (Win 2000) metrics

This table shows the metrics generated by the <epa home>/windows/
diskStats.pl plug-in.

Resource Sub-Resource Metric Introscope Unit Default

Data Type Setting
Disk <Sub- Disk Reads/sec IntCounter 1 (count) on
Resource>
Disk <Sub- Disk Writes/sec IntCounter 1 (count) on
Resource>
Disk <Sub- Disk Read Bytes/sec IntCounter 1 byte on
Resource>
Disk <Sub- Disk Write Bytes/sec IntCounter 1 byte on
Resource>
Disk <Sub- Current Disk Queue IntCounter 1 (request) on
Resource> Length
Disk <Sub- Average Disk Read Time IntCounter 1 ms on
Resource> (ms)
Disk <Sub- Average Disk Write Time IntCounter 1 ms on
Resource> (ms)
Disk <Sub- Average Disk Bytes/Read IntCounter 1 byte on
Resource>
Disk <Sub- Average Disk Bytes/ IntCounter 1 byte on
Resource> Write
Disk <Sub- Free Disk Space (mb) IntCounter 1 mb on
Resource>
Disk <Sub- Free Disk Space (%) IntCounter 1 percent on
Resource>

38 „ Metrics Produced By Environment Performance Agent Default Plug-ins

 Environment Performance Agent Guide

Disk Stats (Solaris) metrics

This table shows the metrics generated by the <epa home>/solaris/
diskStats.pl plug-in.

Resource Sub-Resource Metric Introscope Unit Default

Data Type Setting
Disk <Sub-Resource> Disk Time (%) IntCounter 1 percent on
Disk <Sub-Resource> Transaction Waiting IntCounter 1 percent on
Time (%)
Disk <Sub-Resource> Average # IntCounter 1 transaction on
Transaction Active
Disk <Sub-Resource> Average # IntCounter 1 transaction on
Transaction Waiting
Disk <Sub-Resource> Disk Reads/sec IntCounter 1 (count) on
Disk <Sub-Resource> Disk Writes/sec IntCounter 1 (count) on
Disk <Sub-Resource> KB Read per Second IntCounter 1 byte on
Disk <Sub-Resource> KB Written per IntCounter 1 byte on
Second
Disk <Sub-Resource> Average Service Time IntCounter 1 ms on
in Waiting Queue
(ms)
Disk <Sub-Resource> Average Service Time IntCounter 1 ms on
for Active
Transactions (ms)
Disk <Sub-Resource> Free Disk Space (mb) IntCounter 1 mb on
Disk <Sub-Resource> Free Disk Space (%) IntCounter 1 percent on

Apache log metrics

This table shows the metrics generated by the apacheLogReader.pl plug-in.

Resource Sub-Resource Metric Introscope Unit Default

Data Type Setting
ApacheWebServer <Sub-Resource> PageHitCount IntCounter 1 (hit) on
ApacheWebServer <Sub-Resource> ErrorCount_400_BadR IntCounter 1 (error) on
equest
ApacheWebServer <Sub-Resource> ErrorCount_401_Unaut IntCounter 1 (error) on
horized
ApacheWebServer <Sub-Resource> ErrorCount_403_Forbid IntCounter 1 (error) on
den

Metrics produced by EPAgent default plug-ins „ 39

CA Wily Introscope

Resource Sub-Resource Metric Introscope Unit Default

Data Type Setting
ApacheWebServer <Sub-Resource> ErrorCount_404_PageN IntCounter 1 (error) on
otFound
ApacheWebServer <Sub-Resource> ErrorCount_500_Serve IntCounter 1 (error) on
rConfiguration
ApacheWebServer <Sub-Resource> ErrorMessage_400_Ba StringEvent 1 (error) on
dRequest
ApacheWebServer <Sub-Resource> ErrorMessage_401_Un StringEvent 1 (error) on
authorized
ApacheWebServer <Sub-Resource> ErrorMessage_403_For StringEvent 1 (error) on
bidden
ApacheWebServer <Sub-Resource> ErrorMessage_404_Pag StringEvent 1 (error) on
eNotFound
ApacheWebServer <Sub-Resource> ErrorMessage_500_Ser StringEvent 1 (error) on
verConfiguration

WebSphere log metrics

This table shows the metrics generated by the websphereLogReader.pl plug-in.

Resource Sub-Resource Metric Introscope Unit Default

Data Type Setting
WebSphereApplication <Sub-Resource> ServerVersion StringEvent na on
Server
WebSphereApplication <Sub-Resource> MessageCount_Audit IntCounter 1 (message) on
Server
WebSphereApplication <Sub-Resource> MessageCount_Warnin IntCounter 1 (message) on
Server g
WebSphereApplication <Sub-Resource> MessageCount_EventD IntCounter 1 (message) on
Server ebug
WebSphereApplication <Sub-Resource> MessageCount_Error IntCounter 1 (message) on
Server
WebSphereApplication <Sub-Resource> MessageCount_Fatal IntCounter 1 (message) on
Server
WebSphereApplication <Sub-Resource> MessageText_Audit StringEvent na off
Server
WebSphereApplication <Sub-Resource> MessageText_Warning StringEvent na off
Server
WebSphereApplication <Sub-Resource> MessageText_EventDe StringEvent na off
Server bug

40 „ Metrics Produced By Environment Performance Agent Default Plug-ins

 Environment Performance Agent Guide

Resource Sub-Resource Metric Introscope Unit Default

Data Type Setting
WebSphereApplication <Sub-Resource> MessageText_Error StringEvent na off
Server
WebSphereApplication <Sub-Resource> MessageText_Fatal StringEvent na off
Server

WebLogic log metrics

This table shows the metrics generated by the weblogicLogReader.pl plug-in.

Resource Sub-Resource Metric Introscope Unit Default

Data Type Setting
WebLogicApplica <Sub- ServerVersion StringEvent na on
tionServer Resource>
WebLogicApplica <Sub- MessageCount_Warning IntCounter 1 (message) on
tionServer Resource>

WebLogicApplica <Sub- MessageCount_Error IntCounter 1 (message) on

tionServer Resource>

WebLogicApplica <Sub- MessageCount_Notice IntCounter 1 (message) on

tionServer Resource>

WebLogicApplica <Sub- MessageCount_Critical IntCounter 1 (message) on

tionServer Resource>

WebLogicApplica <Sub- MessageCount_Alert IntCounter 1 (message) on

tionServer Resource>

WebLogicApplica <Sub- MessageCount_Emergency IntCounter 1 (message) on

tionServer Resource>

WebLogicApplica <Sub- MessageText_Warning StringEvent na off

tionServer Resource>
WebLogicApplica <Sub- MessageText_Error StringEvent na off
tionServer Resource>
WebLogicApplica <Sub- MessageText_Notice StringEvent na off
tionServer Resource>
WebLogicApplica <Sub- MessageText_Critical StringEvent na off
tionServer Resource>
WebLogicApplica <Sub- MessageText_Alert StringEvent na off
tionServer Resource>
WebLogicApplica <Sub- MessageText_Emergency StringEvent na off
tionServer Resource>

Metrics produced by EPAgent default plug-ins „ 41

CA Wily Introscope

42 „ Metrics Produced By Environment Performance Agent Default Plug-ins

CHAPTER
4

Environment Performance Agent

Properties

This appendix describes the properties files and the settings you can customize
for using the Environment Performance Agent version 7.2 in your Introscope®
deployment. The Enterprise Manager reads these files on startup; you must
restart the EPAgent for changes to take effect. You can read the files themselves
for other information (located at <Introscope home>/config/
IntroscopeEPAgent.properties.)

» Note In these files, on Windows machines, when adding a path, you must
escape a backslash (\) with another backslash (each one doubled), such
as C:\\Introscope\\lib\\Agent.jar.

IntroscopeEPAgent.properties file
The settings for the EPAgent are the same type as found in the Introscope Agent
profile.

Log 4J settings
Two properties define the level of detail in the EPAgent logs, and the name and
location of EPAgent log files.

See Log4J documentation for advanced Log4J functionality.

Agent properties settings

Enterprise manager connection order

This setting defines the order in which the Agent will attempt to connect to the
Enterprise Managers listed in the Enterprise Manager Locations and Names
section.

Enterprise manager locations and names

These settings define the host, port, and unique names of the Enterprise
Managers the Agent can connect to.

Environment Performance Agent Properties „ 43

CA Wily Introscope

Agent and process name settings

Two properties, introscope.agent.agentName, and
introscope.agent.customProcessName, define the name of the EPAgent and
the name of the Process, both of which are used as part of the Fully-Qualified
Agent Name (Domain | host | process | Agentname) to track information of a
single EPAgent over multiple Agent sessions.

These properties are optional. If the Agent name is not defined, it will be known
as UnknownAgent.

Process name

Introscope names the EPAgent according to these criteria, which take precedence
in their shown order.
1 A name defined by the property, introscope.agent.customProcessName.
2 A name inferred from the name of the main class of the application.
3 The name set by introscope.agent.defaultProcessName.

Agent name

The introscope.agent.agentName property defines a name of the

Environment Performance Agent.

Introscope names the Environment Performance Agent according to these

criteria, which take precedence in their shown order:
1 A name defined by the property, introscope.agent.agentName.
2 If a unique name is not defined in introscope.agent.agentName, the
Environment Performance Agent will be named UnknownAgent.

44 „ Environment Performance Agent Properties


IntroscopeEPAgent.properties settings
The following table contains information about all available properties for the
EPAgent.
This Setting
introscope.epagent.plugins.
stateful.names
introscope.epagent.stateful.
<pluginname>.command
introscope.epagent.stateful.
<pluginname>.class
introscope.epagent.plugins.
stateless.names
Environment Performance Agent Guide
Specifies Default Setting
Specifies name(s) of stateful plug- Commented out;
ins to run. APACHE,WEBLOGI
Note: These names can be user- C,WEBSPHERE,
IIS
defined, as long as they
match the names used in
the following
introscope.epagent.p
lugins.stateful.<plu
ginname>.command
properties
Specifies the command to run Commented out
plugin specified in the
introscope.epagent.plugins
.stateful.names property;
requires one property line per
plugin name specified
Specifies class to be run as a Commented out
stateful plug-in within the EPAgent
VM.
The fully qualified name of a Java
class that runs in the EPAgent JVM
and supplies metrics to the
EPAgent. Arguments can be
appended, as desired. For example:
my.package.path.Class arg1
arg2 arg3
Specifies name(s) of stateless plug- Commented
ins to run. out;DISK,ORACLE,
Note: These names can be user- HTTP,KSTAT
defined, as long as they
match the names used in
the following
introscope.epagent.p
lugins.stateless.<pl
uginname>.command
properties
IntroscopeEPAgent.properties file „ 45
CA Wily Introscope

This Setting Specifies Default Setting

introscope.epagent.stateless. Specifies the command to run plug- Commented out
<pluginname>.command in specified in the
introscope.epagent.plugins
.stateless.names property;
requires one property line per plug-
in name specified
introscope.epagent.stateless. Specifies class to be run as a Commented out
<pluginname>.class stateless plug-in within the EPAgent
VM.
introscope.epagent.stateless. Specifies the frequency (in Commented
<pluginname>.delayInSecon seconds) that the EPAgent runs the out;900
ds specified plug-in; requires one
property line per plug-in name
specified
introscope.epagent.stateless. Specifies the schedule on which to Commented out
<pluginname>.schedule run the plug-in specified in
introscope.epagent.statele
ss.<pluginname>.command
property. Input is CronTab
Schedule Syntax (or “man 5
crontab” on a Unix system).
Note: This property is used
instead of the
introscope.epagent.s
tateless.<pluginname
>.delayInSeconds
property. If both properties
are present, EPAgent will
quit.
introscope.epagent.config. Specifies how long to wait before Commented out;
stalledstatelessPluginTime killing stalled stateless plug-ins. 60 seconds
outInSeconds
introscope.epagent.config. Specifies the port on which the Commented
networkDataPort EPAgent listens for network out;8000
connections for incoming XML data.
introscope.epagent.config. Specifies the port on which the Commented
httpServerPort EPAgent listens for HTTP GET out;8080
commands.
introscope.agent.custom Specifies a name for process being Commented out;
ProcessName monitored. set to name of
application server
for application-
server specific
installers

46 „ Environment Performance Agent Properties

 Environment Performance Agent Guide

This Setting Specifies Default Setting

introscope.agent.default Specifies a default name for an UnknownProcess;
ProcessName Agent if introscope.Agent. may vary by
customProcessName is not set installer
and the name cannot be inferred
from the main class of the
application.
introscope.agent.agent Specifies name of Agent as it Commented out;
Name appears in the Enterprise Manager set to
and Workstation. UnknownAgent or
name of
application server
for application-
specific installers,
as in
<appservername>
Agent
introscope.agent.enterprisem The connection order of backup DEFAULT
anager.connectionorder Enterprise Managers the Agent uses
if it is disconnected from its
Enterprise Manager. Items in the
list must be comma-separated.
introscope.agent. The host name of machine running localhost
enterprisemanager.transport. the Enterprise Manager.
tcp.host.DEFAULT
introscope.agent. The port on the Enterprise Manager 5001
enterprisemanager.transport. machine that listens for the Agent.
tcp.port.DEFAULT
log4j.logger.EPAgent Specifies the amount of logging INFO, console
detail for the EPAgent log
log4j.appender.logfile.File Specifies the name and location of IntroscopeEPA.log
EPAgent logfile

IntroscopeEPAgent.properties file „ 47
CA Wily Introscope

48 „ Environment Performance Agent Properties

I ND E X

Index

A I
Agent installing 7
configuration
verbose mode 8 K
apacheLogReader.pl 24 kstat 22, 26

C L
configuring LINE_FORMAT property 29
adding stateless plug-ins 10 log reader 27
logging options 8 logfile 28
plug-ins 9 logging 32
removing stateful and stateless plug-ins 11
N
D network sources 4
data sources 3
diskstats.pl P
Solaris 22 Perl 4
Windows 23 perl 27
platform support 5
E plug-ins
EP Agent plug-in, definition 3 adding
EPA stateful 9
installing stateless 10
with base Introscope installer 6 custom 6, 13
with EPA standalone installer 7 XML format 14
EPA default plugins 21, 33 default 5
Metrics produced by 35, 41 installation directories 6
EPA properties 43 platform support for 5
EPAgent stateful/stateless 5
redirecting output to a file 8 types 5
running 8, 13 PRINT function 2
verbose mode 8 processAvailability.pl
ErrorSnapshot 16 solaris 22
Windows 22
H properties
httpSvcAvailability.pl 25 files 43

Index „ 49
CA Wily Introscope

settings 43

R
running
as Java application 13
as standalone .jar file 13

S
scripting environments 3
stateful/stateless plug-ins 5
STDERR 2, 5
STDOUT 2

T
transaction tracing 16
offset 17
startTime 17, 18
XML schema for errors/events 18

V
verbose mode
running Agent in 8

W
weblogicLogReader.pl 24
websphereLogReader.pl 24

X
XML schema 18

50 „ Index