Epa Gent Guide

Date: 10-2007

Version 7.2

CA Wily Introscope®

Environment Performance Agent Guide

6000 Shoreline Court, Suite 200South San Francisco, CA 94080

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 [email protected].

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 [email protected].

US Toll Free 888 GET WILY ext. 1US +1 630 505 6966Fax +1 650 534 9340Europe +44 (0)870 351 6752Asia-Pacific +81 3 6868 2300Japan Toll Free 0120 974 580

www.wilytech.com

mailto:[email protected]

http://support.wilytech.com/cgi-bin/wilytech.cfg/php/enduser/acct_login.php

mailto:[email protected]

Contents iii

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



windows/diskStats.pl . . . . . . . . . . . . . . . . . . 23


iv Contents

CA Wily Introscope


apacheLogReader.pl, weblogicLogReader.pl, and websphereLogReader.pl 24



httpSvcAvailability.pl . . . . . . . . . . . . . . . . . . 25



Perl support issues . . . . . . . . . . . . . . . . . . 25

kstat.pl . . . . . . . . . . . . . . . . . . . . . . 26



Perl support issues . . . . . . . . . . . . . . . . . . 27

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

Installing, Configuring, and Using the EPAgent 1

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

2 Installing, Configuring, and Using the EPAgent

CA Wily Introscope

Environment Performance Agent overviewThe 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.

Environment Performance Agent overview 3


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.


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.

Environment Performance Agent overview 5


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

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

Plug-in Function Supported on

process availability check

looks for a running process with a given name

Windows 2000, Solaris

OS-level disk statistics reports reads/writes, transaction times, % time waiting, disk capacity, etc.


Apache log reader reports number of HTTP errors, number of transactions, average transaction size



CA Wily Introscope

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

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, number of pages served, number of users by IP address

Windows 2000, Solaris 2.7, 8

HTTP Service Availability

HTTPS Service Availability

reports connection success/failure, connection round-trip time, average throughput/bandwidth

Windows 2000, Solaris 2.7, 8

Solaris Kstat statistics reports any statistics available through Kstat utility, such as I/O statistics, network statistics for all devices, virtual memory statistics

Solaris 2.7, 8

Plug-in Function Supported on

Installing the Environment Performance Agent 7


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


CA Wily Introscope

Configuring the Environment Performance AgentThe 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:


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

Configuring the Environment Performance Agent 9


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


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


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


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

Configuring the Environment Performance Agent 11


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


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

http://www.gnu.org/software/wget/wget.html

Running the Environment Performance Agent 13


Running the Environment Performance AgentThe 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 EPAgentRunning 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:


CA Wily Introscope

<resource_segment>:<metric_name>=<value>

For example (all one line):

Resource Usage|File IO:diskWrites=37Apache 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.

Using custom plug-ins with the EPAgent 15


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


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.



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.


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



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


CA Wily Introscope

EPAgent Default Plug-ins 21

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

22 EPAgent Default Plug-ins

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.


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

windows/diskStats.pl 23


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.


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.

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.



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


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

Example:

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


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


httpSvcAvailability.pl 25


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


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

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


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 returnav = 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


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


This plug-in takes four command-line arguments:

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


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

iisLogReader.pl 27


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


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

Example:

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


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



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/LogFiles/W3SVC1

Full directory pathname that contains the 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.

iisLogReader.pl 29


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.

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.

Property Name Default Value Description


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_FORMATSub-Property Name

Default Value Description

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

\d+\.\d+\.\d+\.\d+ Enabled by default.

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

\d+\.\d+\.\d+\.\d+ The IP address of the server on 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|DELETE

Enabled by default.

The action the client was trying to perform (for example, a GET command).

iisLogReader.pl 31


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

\d+ Enabled by default.

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

\d+ The number of bytes received by the server. One or more digits.

FIELDS->TimeTaken \d+ The length of time the action took in milliseconds. One or more digits.

FIELDS->ProtocolVersion

[\w/.]+ The protocol (HTTP, FTP) version 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.

LINE_FORMATSub-Property Name

Default Value Description


CA Wily Introscope

Configuring IIS Web Server logging in IIS4.0 and IIS5.01 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.

iisLogReader.pl 33


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.


CA Wily Introscope

Metrics Produced By Environment Performance Agent Default Plug-ins 35

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

36 Metrics Produced By Environment Performance Agent Default Plug-ins

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:

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.

Original Character

Replaced By Descriptions

| _ pipes replaced by underscores

: ^ colons replaced by carets

Resource Sub-Resource Metric Introscope Data Type

Unit Default 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_BadRequest

IntCounter 1 (error) on

IISWebServer <Sub-Resource> ErrorCount_401_Unauthorized


IISWebServer <Sub-Resource> ErrorCount_403_Forbidden


IISWebServer <Sub-Resource> ErrorCount_404_ServerConfiguration


IISWebServer <Sub-Resource> ErrorCount_500_InternalServerError


IISWebServer <Sub-Resource> ErrorMessage_400_BadRequest

StringEvent N/a off

IISWebServer <Sub-Resource> ErrorMessage_401_Unauthorized

StringEvent N/a off

Metrics produced by EPAgent default plug-ins 37


HTTP/HTTPS service availability metrics

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

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

IISWebServer <Sub-Resource> ErrorMessage_403_Forbidden

StringEvent N/a off

IISWebServer <Sub-Resource> ErrorMessage_404_PageNotFound

StringEvent N/a off

IISWebServer <Sub-Resource> ErrorMessage_500_InternalServerError

StringEvent N/a off





Remote Machine <hostnameOrlPAddr>|Service|HTTP

Available IntCounter 0-1 on


Response Time IntCounter sec on


Average Throughput

IntCounter KB/msec on

Remote Machine <hostnameOrlPAddr>|Service|HTTPS

Available IntCounter 0-1 on


Response Time IntCounter sec on


Average Throughput

IntCounter KB/msec on



Solaris Kernel <class>|<module>|<name>

<stat> IntCounter Varies on


CA Wily Introscope

Process availability metrics

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

Disk Stats (Win 2000) metrics

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



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



Disk <Sub-Resource>

Disk Reads/sec IntCounter 1 (count) on

Disk <Sub-Resource>

Disk Writes/sec IntCounter 1 (count) on

Disk <Sub-Resource>

Disk Read Bytes/sec IntCounter 1 byte on

Disk <Sub-Resource>

Disk Write Bytes/sec IntCounter 1 byte on

Disk <Sub-Resource>

Current Disk Queue Length

IntCounter 1 (request) on

Disk <Sub-Resource>

Average Disk Read Time (ms)

IntCounter 1 ms on

Disk <Sub-Resource>

Average Disk Write Time (ms)

IntCounter 1 ms on

Disk <Sub-Resource>

Average Disk Bytes/Read IntCounter 1 byte on

Disk <Sub-Resource>

Average Disk Bytes/Write

IntCounter 1 byte on

Disk <Sub-Resource>

Free Disk Space (mb) IntCounter 1 mb on

Disk <Sub-Resource>

Free Disk Space (%) IntCounter 1 percent on



Disk Stats (Solaris) metrics

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

Apache log metrics

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



Disk <Sub-Resource> Disk Time (%) IntCounter 1 percent on

Disk <Sub-Resource> Transaction Waiting Time (%)

IntCounter 1 percent on

Disk <Sub-Resource> Average # Transaction Active

IntCounter 1 transaction on

Disk <Sub-Resource> Average # Transaction Waiting

IntCounter 1 transaction on

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 Second

IntCounter 1 byte on

Disk <Sub-Resource> Average Service Time in Waiting Queue (ms)

IntCounter 1 ms on

Disk <Sub-Resource> Average Service Time for Active Transactions (ms)

IntCounter 1 ms on

Disk <Sub-Resource> Free Disk Space (mb) IntCounter 1 mb on

Disk <Sub-Resource> Free Disk Space (%) IntCounter 1 percent on



ApacheWebServer <Sub-Resource> PageHitCount IntCounter 1 (hit) on

ApacheWebServer <Sub-Resource> ErrorCount_400_BadRequest


ApacheWebServer <Sub-Resource> ErrorCount_401_Unauthorized


ApacheWebServer <Sub-Resource> ErrorCount_403_Forbidden



CA Wily Introscope

WebSphere log metrics

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

ApacheWebServer <Sub-Resource> ErrorCount_404_PageNotFound


ApacheWebServer <Sub-Resource> ErrorCount_500_ServerConfiguration


ApacheWebServer <Sub-Resource> ErrorMessage_400_BadRequest

StringEvent 1 (error) on

ApacheWebServer <Sub-Resource> ErrorMessage_401_Unauthorized


ApacheWebServer <Sub-Resource> ErrorMessage_403_Forbidden


ApacheWebServer <Sub-Resource> ErrorMessage_404_PageNotFound


ApacheWebServer <Sub-Resource> ErrorMessage_500_ServerConfiguration






WebSphereApplicationServer

<Sub-Resource> ServerVersion StringEvent na on


<Sub-Resource> MessageCount_Audit IntCounter 1 (message) on


<Sub-Resource> MessageCount_Warning

IntCounter 1 (message) on


<Sub-Resource> MessageCount_EventDebug

IntCounter 1 (message) on


<Sub-Resource> MessageCount_Error IntCounter 1 (message) on


<Sub-Resource> MessageCount_Fatal IntCounter 1 (message) on


<Sub-Resource> MessageText_Audit StringEvent na off


<Sub-Resource> MessageText_Warning StringEvent na off


<Sub-Resource> MessageText_EventDebug

StringEvent na off



WebLogic log metrics

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


<Sub-Resource> MessageText_Error StringEvent na off


<Sub-Resource> MessageText_Fatal StringEvent na off





WebLogicApplicationServer

<Sub-Resource>

ServerVersion StringEvent na on


<Sub-Resource>

MessageCount_Warning IntCounter 1 (message) on


<Sub-Resource>

MessageCount_Error IntCounter 1 (message) on


<Sub-Resource>

MessageCount_Notice IntCounter 1 (message) on


<Sub-Resource>

MessageCount_Critical IntCounter 1 (message) on


<Sub-Resource>

MessageCount_Alert IntCounter 1 (message) on


<Sub-Resource>

MessageCount_Emergency IntCounter 1 (message) on


<Sub-Resource>

MessageText_Warning StringEvent na off


<Sub-Resource>

MessageText_Error StringEvent na off


<Sub-Resource>

MessageText_Notice StringEvent na off


<Sub-Resource>

MessageText_Critical StringEvent na off


<Sub-Resource>

MessageText_Alert StringEvent na off


<Sub-Resource>

MessageText_Emergency StringEvent na off


CA Wily Introscope

Environment Performance Agent Properties 43

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

44 Environment Performance Agent Properties

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.

IntroscopeEPAgent.properties file 45


IntroscopeEPAgent.properties settings

The following table contains information about all available properties for the EPAgent.

This Setting Specifies Default Setting

introscope.epagent.plugins.stateful.names

Specifies name(s) of stateful plug-ins to run.

Note: These names can be user-defined, as long as they match the names used in the following introscope.epagent.plugins.stateful.<pluginname>.command properties

Commented out; APACHE,WEBLOGIC,WEBSPHERE,IIS

introscope.epagent.stateful.<pluginname>.command

Specifies the command to run plugin specified in the introscope.epagent.plugins .stateful.names property; requires one property line per plugin name specified

Commented out

introscope.epagent.stateful.<pluginname>.class

Specifies class to be run as a 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

Commented out

introscope.epagent.plugins.stateless.names

Specifies name(s) of stateless plug-ins to run.

Note: These names can be user-defined, as long as they match the names used in the following introscope.epagent.plugins.stateless.<pluginname>.command properties

Commented out;DISK,ORACLE,HTTP,KSTAT


CA Wily Introscope

introscope.epagent.stateless.<pluginname>.command

Specifies the command to run plug-in specified in the introscope.epagent.plugins.stateless.names property; requires one property line per plug-in name specified

Commented out

introscope.epagent.stateless.<pluginname>.class

Specifies class to be run as a stateless plug-in within the EPAgent VM.

Commented out

introscope.epagent.stateless.<pluginname>.delayInSeconds

Specifies the frequency (in seconds) that the EPAgent runs the specified plug-in; requires one property line per plug-in name specified

Commented out;900

introscope.epagent.stateless.<pluginname>.schedule

Specifies the schedule on which to run the plug-in specified in introscope.epagent.stateless.<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.stateless.<pluginname>.delayInSeconds property. If both properties are present, EPAgent will quit.

Commented out

introscope.epagent.config.stalledstatelessPluginTimeoutInSeconds

Specifies how long to wait before killing stalled stateless plug-ins.

Commented out; 60 seconds

introscope.epagent.config.networkDataPort

Specifies the port on which the EPAgent listens for network connections for incoming XML data.

Commented out;8000

introscope.epagent.config.httpServerPort

Specifies the port on which the EPAgent listens for HTTP GET commands.

Commented out;8080

introscope.agent.customProcessName

Specifies a name for process being monitored.

Commented out; set to name of application server for application-server specific installers


IntroscopeEPAgent.properties file 47


introscope.agent.defaultProcessName

Specifies a default name for an Agent if introscope.Agent.customProcessName is not set and the name cannot be inferred from the main class of the application.

UnknownProcess; may vary by installer

introscope.agent.agentName

Specifies name of Agent as it appears in the Enterprise Manager and Workstation.

Commented out; set to UnknownAgent or name of application server for application-specific installers, as in <appservername>Agent

introscope.agent.enterprisemanager.connectionorder

The connection order of backup Enterprise Managers the Agent uses if it is disconnected from its Enterprise Manager. Items in the list must be comma-separated.

DEFAULT

introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT

The host name of machine running the Enterprise Manager.

localhost

introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT

The port on the Enterprise Manager machine that listens for the Agent.

5001

log4j.logger.EPAgent Specifies the amount of logging detail for the EPAgent log

INFO, console

log4j.appender.logfile.File Specifies the name and location of EPAgent logfile

IntroscopeEPA.log



CA Wily Introscope

Index 49

INDEX

Index

AAgent

configurationverbose mode 8

apacheLogReader.pl 24

Cconfiguring

adding stateless plug-ins 10logging options 8plug-ins 9removing stateful and stateless plug-ins 11

Ddata sources 3diskstats.pl

Solaris 22Windows 23

EEP Agent plug-in, definition 3EPA

installingwith base Introscope installer 6with EPA standalone installer 7

EPA default plugins 21, 33Metrics produced by 35, 41

EPA properties 43EPAgent

redirecting output to a file 8running 8, 13verbose mode 8

ErrorSnapshot 16

HhttpSvcAvailability.pl 25

Iinstalling 7

Kkstat 22, 26

LLINE_FORMAT property 29log reader 27logfile 28logging 32

Nnetwork sources 4

PPerl 4perl 27platform support 5plug-ins

addingstateful 9stateless 10

custom 6, 13XML format 14

default 5installation directories 6platform support for 5stateful/stateless 5types 5

PRINT function 2processAvailability.pl

solaris 22Windows 22

propertiesfiles 43

50 Index

CA Wily Introscope

settings 43

Rrunning

as Java application 13as standalone .jar file 13

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

Ttransaction tracing 16

offset 17startTime 17, 18XML schema for errors/events 18

Vverbose mode

running Agent in 8

WweblogicLogReader.pl 24websphereLogReader.pl 24

XXML schema 18

Epa Gent Guide

Documents

Transcript of Epa Gent Guide