APM - 9.5 - Environment Performance Agent Implementation Guide

Environment Performance Agent
Implementation Guide
Release 9.5
CA Application Performance
Management

This Documentation, which includes embedded help systems and electronically distributed materials, (hereinafter referred to
as the Documentation) is for your informational purposes only and is subject to change or withdrawal by CA at any time.
This Documentation may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without
the prior written consent of CA. This Documentation is confidential and proprietary information of CA and may not be disclosed
by you or used for any purpose other than as may be permitted in (i) a separate agreement between you and CA governing
your use of the CA software to which the Documentation relates; or (ii) a separate confidentiality agreement between you and
CA.
Notwithstanding the foregoing, if you are a licensed user of the software product(s) addressed in the Documentation, you may
print or otherwise make available a reasonable number of copies of the Documentation for internal use by you and your
employees in connection with that software, provided that all CA copyright notices and legends are affixed to each reproduced
copy.
The right to print or otherwise make available copies of the Documentation is limited to the period during which the applicable
license for such software remains in full force and effect. Should the license terminate for any reason, it is your responsibility to
certify in writing to CA that all copies and partial copies of the Documentation have been returned to CA or destroyed.
TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION AS IS WITHOUT WARRANTY OF ANY
KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE,
DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST
INVESTMENT, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED IN ADVANCE OF THE
POSSIBILITY OF SUCH LOSS OR DAMAGE.
The use of any software product referenced in the Documentation is governed by the applicable license agreement and such
license agreement is not modified in any way by the terms of this notice.
The manufacturer of this Documentation is CA.
Provided with Restricted Rights. Use, duplication or disclosure by the United States Government is subject to the restrictions
set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section 252.227-7014(b)(3), as applicable, or
their successors.
Copyright 2013 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to
their respective companies.

CA Technologies Product References
This document references the following CA Technologies products and features:
CA Application Performance Management (CA APM)
CA Application Performance Management ChangeDetector (CA APM
ChangeDetector)
CA Application Performance Management ErrorDetector (CA APM ErrorDetector)
CA Application Performance Management for CA Database Performance (CA APM
for CA Database Performance)
CA Application Performance Management for CA SiteMinder (CA APM for CA
SiteMinder)
CA Application Performance Management for CA SiteMinder Application Server
Agents (CA APM for CA SiteMinder ASA)
CA Application Performance Management for IBM CICS Transaction Gateway (CA
APM for IBM CICS Transaction Gateway)
CA Application Performance Management for IBM WebSphere Application Server
(CA APM for IBM WebSphere Application Server)
CA Application Performance Management for IBM WebSphere Distributed
Environments (CA APM for IBM WebSphere Distributed Environments)
CA Application Performance Management for IBM WebSphere MQ (CA APM for
IBM WebSphere MQ)
CA Application Performance Management for IBM WebSphere Portal (CA APM for
IBM WebSphere Portal)
CA Application Performance Management for IBM WebSphere Process Server (CA
APM for IBM WebSphere Process Server)
CA Application Performance Management for IBM z/OS (CA APM for IBM z/OS)
CA Application Performance Management for Microsoft SharePoint (CA APM for
Microsoft SharePoint)
CA Application Performance Management for Oracle Databases (CA APM for Oracle
Databases)
CA Application Performance Management for Oracle Service Bus (CA APM for
Oracle Service Bus)
CA Application Performance Management for Oracle WebLogic Portal (CA APM for
Oracle WebLogic Portal)
CA Application Performance Management for Oracle WebLogic Server (CA APM for
Oracle WebLogic Server)
CA Application Performance Management for SOA (CA APM for SOA)

CA Application Performance Management for TIBCO BusinessWorks (CA APM for
TIBCO BusinessWorks)
CA Application Performance Management for TIBCO Enterprise Message Service
(CA APM for TIBCO Enterprise Message Service)
CA Application Performance Management for Web Servers (CA APM for Web
Servers)
CA Application Performance Management for webMethods Broker (CA APM for
webMethods Broker)
CA Application Performance Management for webMethods Integration Server (CA
APM for webMethods Integration Server)
CA Application Performance Management Integration for CA CMDB (CA APM
Integration for CA CMDB)
CA Application Performance Management Integration for CA NSM (CA APM
Integration for CA NSM)
CA Application Performance Management LeakHunter (CA APM LeakHunter)
CA Application Performance Management Transaction Generator (CA APM WTG)
CA Cross-Enterprise Application Performance Management
CA Customer Experience Manager (CA CEM)
CA Embedded Entitlements Manager (CA EEM)
CA eHealth Performance Manager (CA eHealth)
CA Insight Database Performance Monitor for DB2 for z/OS
CA Introscope
CA SiteMinder
CA Spectrum Infrastructure Manager (CA Spectrum)
CA SYSVIEW Performance Management (CA SYSVIEW)

Contact CA Technologies
Contact CA Support
For your convenience, CA Technologies provides one site where you can access the
information that you need for your Home Office, Small Business, and Enterprise CA
Technologies products. At http://ca.com/support, you can access the following
resources:
Online and telephone contact information for technical assistance and customer
services
Information about user communities and forums
Product and documentation downloads
CA Support policies and guidelines
Other helpful resources appropriate for your product
Providing Feedback About Product Documentation
If you have comments or questions about CA Technologies product documentation, you
can send a message to techpubs@ca.com.
To provide feedback about CA Technologies product documentation, complete our
short customer survey which is available on the CA Support website at
http://ca.com/docs.

Contents 7

Contents

Chapter 1: Installing, Configuring, and Using the EPAgent 13
The Environment Performance Agent Overview ....................................................................................................... 13
EPAgent Can Receive Input From Processes ....................................................................................................... 13
EPAgent and Scripting Environments .................................................................................................................. 14
EPAgent Can Accept Input From Network Sources ............................................................................................. 15
EPAgent and CA Introscope .............................................................................................................................. 16
Supported Plug-ins .............................................................................................................................................. 16
Environment Performance Agent Installation ............................................................................................................ 18
The EPAgent Standalone Installers ..................................................................................................................... 18
Configuring the EPAgent ............................................................................................................................................ 19
Configure EPAgent Properties ............................................................................................................................. 19
Configure EPAgent Logging Options ................................................................................................................... 20
Configuring EPAgent Plug-ins .............................................................................................................................. 21
Configuring the EPAgent for Network Data Sources ........................................................................................... 23
Run the EPAgent......................................................................................................................................................... 24
Run the EPAgent on UNIX .......................................................................................................................................... 25
Creating and Using Custom Plug-ins With the EPAgent ............................................................................................. 25
Metric Data Format ............................................................................................................................................. 26
Precautions With Either Type of Custom Plug-in Format ................................................................................... 27
Error or Event Data Format ................................................................................................................................. 28
Creating an Error Snapshot in XML Format ......................................................................................................... 29
EPAgent Events and Transaction Traces ............................................................................................................. 29
XML Schema for Error or Event Data .................................................................................................................. 31
Chapter 2: EPAgent Default Plug-ins 33
solaris/diskStats.pl ..................................................................................................................................................... 33
Metrics Produced ................................................................................................................................................ 33
Command-Line Arguments ................................................................................................................................. 33
windows/processAvailability.pl AND solaris/processAvailability.pl ........................................................................... 34
windows/diskStats.pl ................................................................................................................................................. 35
apacheLogReader.pl, weblogicLogReader.pl, and websphereLogReader.pl .............................................................. 35

8 Environment Performance Agent Implementation Guide

httpSvcAvailability.pl .................................................................................................................................................. 36
Perl Support Issues .............................................................................................................................................. 38
kstat.pl ........................................................................................................................................................................ 38
Perl Support Issues .............................................................................................................................................. 39
iisLogReader.pl ........................................................................................................................................................... 39
iisLogReader.cfg Configuration File ..................................................................................................................... 40
Configuring IIS Web Server logging in IIS4.0 and IIS5.0....................................................................................... 48
Chapter 3: EPAgent Default Plug-in Metrics 51
Invalid Character Replacement .................................................................................................................................. 51
IIS log reader metrics ................................................................................................................................................. 51
Total Page Hits .................................................................................................................................................... 52
Total Visitors Count ............................................................................................................................................. 52
Page Hits For <URL> ............................................................................................................................................ 52
Bytes Transferred ................................................................................................................................................ 53
ErrorCount_400_BadRequest ............................................................................................................................. 53
ErrorCount_401_Unauthorized .......................................................................................................................... 53
ErrorCount_403_Forbidden ................................................................................................................................ 54
ErrorCount_404_ServerConfiguration ................................................................................................................ 54
ErrorCount_500_InternalServerError ................................................................................................................. 54
ErrorMessage_400_BadRequest ......................................................................................................................... 55
ErrorMessage_401_Unauthorized ...................................................................................................................... 55
ErrorMessage_403_Forbidden............................................................................................................................ 55
ErrorMessage_404_PageNotFound .................................................................................................................... 56
ErrorMessage_500_InternalServerError ............................................................................................................. 56
HTTP/HTTPS service availability metrics .................................................................................................................... 56
Available .............................................................................................................................................................. 57
Response Time .................................................................................................................................................... 57
Average Throughput ........................................................................................................................................... 57
Solaris kernel statistics (Kstat) metrics ....................................................................................................................... 58
Solaris Kernel <class>|<module>|<name> Metrics ............................................................................................ 58
Process availability metrics ........................................................................................................................................ 58
Count ................................................................................................................................................................... 59
Disk Stats (Windows) Metrics..................................................................................................................................... 59

Contents 9

Disk Reads/sec .................................................................................................................................................... 60
Disk Writes/sec ................................................................................................................................................... 60
Disk Read Bytes/sec ............................................................................................................................................ 60
Disk Write Bytes/sec ........................................................................................................................................... 61
Current Disk Queue Length ................................................................................................................................. 61
Average Disk Read Time (ms) .............................................................................................................................. 61
Average Disk Write Time (ms) ............................................................................................................................. 62
Average Disk Bytes/Read .................................................................................................................................... 62
Average Disk Bytes/Write ................................................................................................................................... 62
Free Disk Space (mb) ........................................................................................................................................... 63
Free Disk Space (%) ............................................................................................................................................. 63
Disk Stats (Solaris) Metrics ......................................................................................................................................... 63
Disk Time (%) ....................................................................................................................................................... 64
Transaction Waiting Time (%) ............................................................................................................................. 64
Average # Transaction Active .............................................................................................................................. 65
Average # Transaction Waiting ........................................................................................................................... 65
Disk Reads/sec .................................................................................................................................................... 65
Disk Writes/sec ................................................................................................................................................... 66
KB Read per Second ............................................................................................................................................ 66
KB Written per Second ........................................................................................................................................ 66
Average Service Time in Waiting Queue (ms) ..................................................................................................... 67
Average Service Time for Active Transactions (ms) ............................................................................................ 67
Free Disk Space (mb) ........................................................................................................................................... 67
Free Disk Space (%) ............................................................................................................................................. 68
Apache Log Metrics .................................................................................................................................................... 68
PageHitCount ...................................................................................................................................................... 69
ErrorCount_400_BadRequest ............................................................................................................................. 69
ErrorCount_401_Unauthorized .......................................................................................................................... 69
ErrorCount_403_Forbidden ................................................................................................................................ 70
ErrorCount_404_PageNotFound ......................................................................................................................... 70
ErrorCount_500_ServerConfiguration ................................................................................................................ 70
ErrorMessage_400_BadRequest ......................................................................................................................... 71
ErrorMessage_401_Unauthorized ...................................................................................................................... 71
ErrorMessage_403_Forbidden............................................................................................................................ 71
ErrorMessage_404_PageNotFound .................................................................................................................... 72
ErrorMessage_500_ServerConfiguration ............................................................................................................ 72
WebSphere log metrics .............................................................................................................................................. 72
MessageCount_Audit .......................................................................................................................................... 73
MessageCount_Warning ..................................................................................................................................... 73
MessageCount_EventDebug ............................................................................................................................... 74
MessageCount_Error .......................................................................................................................................... 74
MessageCount_Fatal ........................................................................................................................................... 74


MessageText_Audit ............................................................................................................................................. 75
MessageText_Warning........................................................................................................................................ 75
MessageText_EventDebug .................................................................................................................................. 75
MessageText_Error ............................................................................................................................................. 76
MessageText_Fatal ............................................................................................................................................. 76
WebLogic log metrics ................................................................................................................................................. 79
ServerVersion ...................................................................................................................................................... 80
MessageCount_Warning ..................................................................................................................................... 80
MessageCount_Error .......................................................................................................................................... 80
MessageCount_Notice ........................................................................................................................................ 81
MessageCount_Critical ....................................................................................................................................... 81
MessageCount_Alert ........................................................................................................................................... 81
MessageCount_Emergency ................................................................................................................................. 82
MessageText_Warning........................................................................................................................................ 82
MessageText_Error ............................................................................................................................................. 82
MessageText_Notice ........................................................................................................................................... 83
MessageText_Critical .......................................................................................................................................... 83
MessageText_Alert ............................................................................................................................................. 83
MessageText_Emergency ................................................................................................................................... 84
Chapter 4: EPAgent Properties 85
IntroscopeEPAgent.properties file ............................................................................................................................. 85
Agent and Process Name Settings ...................................................................................................................... 85
Agent metric aging ..................................................................................................................................................... 86
Configuring agent metric aging ........................................................................................................................... 87
introscope.agent.metricAging.turnOn ................................................................................................................ 88
introscope.agent.metricAging.heartbeatInterval ............................................................................................... 89
introscope.agent.metricAging.dataChunk .......................................................................................................... 89
introscope.agent.metricAging.numberTimeslices .............................................................................................. 90
introscope.agent.metricAging.metricExclude.ignore.0 ...................................................................................... 90
Case-Sensitive Metrics ............................................................................................................................................... 90
introscope.epagent.metricscasesensitive ........................................................................................................... 91
ChangeDetector Configuration .................................................................................................................................. 91
introscope.changeDetector.enable..................................................................................................................... 91
introscope.changeDetector.rootDir .................................................................................................................... 92
introscope.changeDetector.isengardStartupWaitTimeInSec.............................................................................. 92
introscope.changeDetector.waitTimeBetweenReconnectInSec......................................................................... 92
introscope.changeDetector.enableEPA .............................................................................................................. 93
introscope.changeDetector.agentID ................................................................................................................... 93
introscope.changeDetector.profile ..................................................................................................................... 93
introscope.changeDetector.profileDir ................................................................................................................ 94

Contents 11

Enterprise Manager Connection ................................................................................................................................ 94
introscope.agent.enterprisemanager.connectionorder ..................................................................................... 94
introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT ................................................................... 95
EPAgent Configuration ............................................................................................................................................... 95
introscope.epagent.config.networkDataPort ..................................................................................................... 95
introscope.epagent.config.httpServerPort ......................................................................................................... 96
Extensions Directory .................................................................................................................................................. 96
introscope.agent.extensions.directory ............................................................................................................... 96
Logging ....................................................................................................................................................................... 96
log4j.logger.EPAgent ........................................................................................................................................... 97
log4j.appender.logfile.File................................................................................................................................... 97
Processes .................................................................................................................................................................... 97
introscope.agent.customProcessName .............................................................................................................. 98
introscope.agent.defaultProcessName ............................................................................................................... 98
introscope.agent.agentName ............................................................................................................................. 99
Remote Configuration ................................................................................................................................................ 99
introscope.agent.remoteagentconfiguration.enabled ....................................................................................... 99
Stateful Plug-ins ......................................................................................................................................................... 99
introscope.epagent.plugins.stateful.names ...................................................................................................... 100
introscope.epagent.stateful.<pluginname>.command..................................................................................... 100
introscope.epagent.stateful.<pluginname>.class ............................................................................................. 101
Stateless Plug-ins ...................................................................................................................................................... 101
introscope.epagent.plugins.stateless.names .................................................................................................... 101
introscope.epagent.stateless.<pluginname>.command ................................................................................... 102
introscope.epagent.stateless.<pluginname>.class ........................................................................................... 102
introscope.epagent.stateless.<pluginname>.delayInSeconds .......................................................................... 102
introscope.epagent.stateless.<pluginname>.schedule ..................................................................................... 103
introscope.epagent.config.stalledStatelessPluginTimeoutInSeconds .............................................................. 103
introscope.epagent.stateless.<pluginname>.metricNotReportedAction ......................................................... 104
Index 105


Chapter 1: Installing, Configuring, and
Using the EPAgent

This section covers installing, configuring, and using the CA APM Environment
Performance Agent (EPAgent).
This section contains the following topics:
The Environment Performance Agent Overview (see page 13)
Environment Performance Agent Installation (see page 18)
Configuring the EPAgent (see page 19)
Run the EPAgent (see page 24)
Run the EPAgent on UNIX (see page 25)
Creating and Using Custom Plug-ins With the EPAgent (see page 25)
The Environment Performance Agent Overview
The CA APM Environment Performance Agent (EPAgent) integrates metric data from
non-Java sources into CA Introscope.
The 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.
EPAgent Can Receive Input From Processes
The EPAgent is implemented in Java and runs in a Java Virtual Machine (JVM). The
EPAgent uses the JVM facility to invoke a subprocess and receive STDOUT and STDERR
from that process. The subprocess can be any script, executable, or anything that can be
invoked on a command line. For example:
A compiled program written by the user in C
A Perl script


By executing a simple PRINT function, the application or script in the subprocess can
communicate with the EPAgent. This illustration shows how applications or scripts
communicate metric data to the EPAgent by printing to STDOUT.

The EPAgent expects the text it receives using 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
guide.
In this guide, 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.
More information:
Configuring EPAgent Plug-ins (see page 21)
EPAgent Default Plug-ins (see page 33)

EPAgent and Scripting Environments
Although the EPAgent can receive text from any executable entity in a subprocess
(including compiled applications), 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 the EPAgent to gather performance and
management information from virtually any source. This illustration shows how scripts
can access information from many sources.

CA Technologies emphasizes the use of Perl with the 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. CA 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.
Note: For support with customizations to PBDs, EPAgent scripts, or JavaScript
calculators, contact CA Technologies Professional Services.
EPAgent Can Accept Input From Network Sources
In addition to accepting input from local processes, EPAgent can accept input from
network sources. This ability is useful for collecting information from networked
processes where EPAgent cannot run, for example, a C++ backend system that provides
monitoring information using a network port, or posts data periodically to a web URL.
More information:
Configuring the EPAgent for Network Data Sources (see page 23)



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

The 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. The EPAgent permits the easy collection of
information from the non-Java and non-.NET portion of the application environment for
display alongside the Java and .NET metrics in the CA Introscope Workstation.
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
These are the available plug-in types:
Stateful plug-insStateful plug-ins are expected to be long running scripts
(daemons) to be started when the EPAgent starts and run indefinitely. These
stateful plug-ins can feed data back into CA 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-insStateless 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 the
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 you can use with minimal
configuration. The following table summarizes the function of each plug-in and the
operating systems on which they are supported.

Plug-in Function Supported on
process availability
check
looks for a running process with a given
name
Solaris
OS-level disk statistics reports reads/writes, transaction times,
% time waiting, disk capacity, and so on
Solaris
Apache log reader reports number of HTTP errors, number
of transactions, average transaction size
Solaris
WebLogic log reader reports error count, warning count Solaris
WebSphere log reader reports error count, warning count Solaris
IIS log reader reports number of errors by type,
number of pages served, number of users
by IP address
Windows
HTTP Service
Availability
HTTPS Service
Availability
reports connection success/failure,
connection round-trip time, average
throughput/bandwidth
Solaris
Solaris Kstat statistics reports any statistics available through
Kstat utility, such as I/O statistics,
network statistics for all devices, virtual
memory statistics
Solaris

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.
More information:

Environment Performance Agent Installation


Environment Performance Agent Installation
You use the Standalone agent installer to install the EPAgent.
Note: For more information, see the CA APM Installation and Upgrade Guide.
The EPAgent Standalone Installers
You can install the EPAgent on another computer using one of the following Standalone
agent installers. You can download CA APM products from the CA APM software
download area on CA Support.
EPAgent<version>windows.zip
EPAgent<version>ebcdic.tar
EPAgent<version>unix.tar
After you extract the EPAgent installer, the following files are installed in the
<EPAgent_Home>/epagent directory.
Note: <EPAgent_Home> is the computer where you have installed the EPAgent.
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
Configuring the EPAgent


/xml (top-level directory for ChangeDetector files)
ChangeDetectorAgent.jar
ChangeDetector-Agent_Server.jar
ChangeDetector-CommonAll.jar
ChangeDetector-config.xml
Windows: cdnativefile.dll
UNIX: libcdnativefile.so
The EPAgent includes a set of agent configuration properties, such as the Enterprise
Manager location and port settings.
Note: The EPAgent will fail to start when it encounters any errors in the properties file
settings, for example, invalid filename path. Verify that the properties are set correctly if
you are starting the EPAgent automatically at start-up.
More information:
Configure EPAgent Properties (see page 19)
Configure EPAgent Logging Options (see page 20)
Configuring EPAgent Plug-ins (see page 21)
Configuring the EPAgent for Network Data Sources (see page 23)

Configure EPAgent Properties
The properties used by the EPAgent are the same as the properties that are used for the
Java agent.
Follow these steps:
1. Configure the EPAgent settings in the IntroscopeEPAgent.properties file. The
settings for the EPAgent are the same type as found in the CA Introscope Agent
profile.
Note: For more information about properties, see the CA APM Java Agent
Implementation Guide.


2. If you change the name or location of the IntroscopeEPAgent.properties 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 command linefor example, after -jarit will not work.
Configure EPAgent Logging Options
By default, the EPAgent sends message and error output to the command console. You
can configure the EPAgent to send message and error output to a log file also.
Follow these steps:
1. Open the file <EPAgent_Home>/epagent/IntroscopeEPAgent.properties.
2. Modify the properties.
Run EPAgent in Verbose Mode and Redirect the Output File
Running the EPAgent in verbose mode records details to the log, which is helpful in
debugging. The property that controls verbose mode also controls the placement of the
output log file.
Follow these steps:
1. Open the <EPAgent_Home>/epagent/IntroscopeEPAgent.properties file.
2. Comment out the property log4j.logger.EPAgent, for example:
#log4j.logger.EPAgent=INFO, console
3. Uncomment the property log4j.logger.IntroscopeAgent and replace INFO with
VERBOSE#com.wily.util.feedback.Log4JSeverityLevel, and console with logfile to
send the output to a log file instead of the console. For example, if you wanted the
EPAgent to report in Verbose mode to a logfile, the property would look like the
following:
log4j.logger.IntroscopeAgent=VERBOSE#com.wily.util.feedback.Log4JSeverityLeve
l,logfile
4. Save changes and close the IntroscopeEPAgent.properties file.
Important! After you save the IntroscopeEPAgent.properties file, the EPAgent logs still
show in the command console, until the properties files is read and implemented. After
the properties file has been implemented, the log is written into the logfile from then
onwards.


Configuring EPAgent Plug-ins
To run EPAgent using the default plug-ins, you simply need to uncomment certain
properties in IntroscopeEPAgent.properties file.
However, you may want to remove plug-ins you dont 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.
Add Stateful Plug-ins
Plug-ins used by the EPAgent are configured in the IntroscopeEPAgent.properties file.
Follow these steps:
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.
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
<EPAgent_Home>/epagent/epaplugins/apache/apacheLogReader.pl
introscope.epagent.stateful.WEBLOGIC.command=/usr/bin/perl
<EPAgent_Home>/epagent/epaplugins/weblogic/weblogicLogReader.pl
introscope.epagent.stateful.WEBSPHERE.command=/usr/bin/perl
<EPAgent_Home>/epagent/epaplugins/websphere/websphereLogReader.pl
introscope.epagent.stateful.IIS.command=/usr/bin/perl
<EPAgent_Home>/epagent/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
More information:



Next Steps
You can add stateless plug-ins (see page 22). If you are not adding stateless plug-ins,
save the changes to the IntroscopeEPAgent.properties file, and restart the EPAgent.
Add Stateless Plug-ins
You can add stateless plug-ins.
Follow these steps:
1. Open the file <EPAgent_Home>/epagent/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),
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
<EPAgent_Home>/epagent/epaplugins/solaris/diskStats.pl
introscope.epagent.stateless.DISK.delayInSeconds=900
introscope.epagent.stateless.ORACLE.command=/usr/bin/perl
<EPAgent_Home>/epagent/solaris/processAvailability.pl
introscope.epagent.stateless.ORACLE.delayInSeconds=900
introscope.epagent.stateless.HTTP.command=/usr/bin/perl
<EPAgent_Home>/epaplugins/solaris/httpSvcAvailability.pl
introscope.epagent.stateless.HTTP.delayInSeconds=900
introscope.epagent.stateless.KSTAT.command=/usr/bin/perl
<EPAgent_Home>/epaplugins/solaris/kstat.pl
introscope.epagent.stateless.KSTAT.delayInSeconds=900
Note: These examples are the default values for these properties. To use them,
uncomment each of the properties.
4. Save changes and restart the EPAgent if you are finished.


More information:

Remove Stateful and Stateless Plug-ins
You can remove the plug-ins for any reason.
Follow these steps:
2. In the properties introscope.epagent.plugins.stateful.names and
introscope.epagent.plugins.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 EPAgent for Network Data Sources
You can configure the EPAgent to accept data from network sources.
Configure the EPAgent for simple or XML network input (see page 23).
Configure the EPAgent for HTTP GET input (see page 24).
Configure 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
Run the EPAgent


Configure 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 use 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=8080
2. Restart the EPAgent.
The changes take effect.
3. Test the HTTP GET request through a browser. For example:
http://localhost:9090/?metricType=IntCounter&metricName=
MyHTTPMetric|Test:MyCounter&metricValue=15
After 15 seconds, the MyHTTPMetric|Test:MyCounter metric appears under your
EPAgent.
To update the metric, the EPAgent must 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 about Wget is available at:
http://www.gnu.org/software/wget/wget.html
Run the EPAgent
You can run the EPAgent 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 the following
example:
java -jar <EPAgent_Home>/epagent/lib/EPAgent.jar
-Dcom.wily.introscope.epagent.properties="<EPAgent_Home>/epagent/IntroscopeEP
Agent.properties"
Run the EPAgent on UNIX


To run the EPAgent as a Java application
Add the EPAgent files to the appropriate classpath as in the following example:
java -classpath "<EPAgent_Home>/epagent/lib/EPAgent.jar"
-Dcom.wily.introscope.epagent.properties="<EPAgent_Home>/epagent/IntroscopeEP
Agent.properties"
Run the EPAgent on UNIX
You can use a control script (shell script) to run the Introscope EPAgent on a UNIX
operating system.
Follow these steps:
1. Open a command prompt.
2. Navigate to the directory that has the control script. For example:
cd Introscope<version_number>/bin
3. Run the command that corresponds to the action you want:
EPACtrl.sh start
Starts the EPAgent.
EPACtrl.sh status
Shows the status of EPAgent process whether it is running or stopped.
EPACtrl.sh stop
Stops the EPAgent process
EPACtrl.sh help
Displays the help menu.
Creating and Using Custom Plug-ins With the EPAgent
Running the EPAgent with the default plug-ins gathers information that is usually
sufficient for most users 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
Metric data format (see page 26), and Error or event data format (see page 28)).
Add the custom plug-ins in the IntroscopeEPAgent.properties file as described in the
section Configuring EPAgent plug-ins (see page 21).


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:
<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 a CA Introscope "IntCounter" type.
Any value composed of anything other than numeric digits will be interpreted as
string data and will be reported as an CA 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 format allows full support of Introscope data types and equal signs in both
metric names and values.
The "type" attribute of a metric must be one of the following:
PerIntervalCounterthe value is a rate "per interval" where the interval can
change. These metrics are aggregated over time by summing the values. For
example, if there were 10 method invocations per 15 seconds followed by 15
method invocations per 15 seconds, then aggregating to 30 seconds would
result in "25 method invocations per 30 seconds".
IntCounterint values can go up and down
IntAverageint value that is averaged over time
IntRatethe value is a per second rate. These metrics are aggregated over
time by taking the average of the values.
LongCounterlong values can go up and down
LongAveragelong value that is averaged over time
StringEventrepresents a type which periodically generates Strings. This
recorder does not have a notion of current value; it merely reports events in
the order in which they are reported to it.
Timestampa type which generates successively increasing timestamps.
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 the EPAgent will log an error.
Precautions With Either Type of Custom Plug-in Format
Consider the following precautions when you use either type of custom plug-in format:
Supporting both formats causes an interaction where the system does 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.
If the plug-in returns multiple lines, parsing continues with the next line.
For each metric name, only one metric type can be specified. If more than one type
is specified, the following error occurs:
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"/>
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 (60,000 milliseconds):
<event resource="Some Resource" startTime="123003000" 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="123003000" 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 when time information is contained in the event
sent by the EPAgent. To include time information, use the startTime and offset
attributes on the <event> and <calledComponent> tags.
The startTime attribute is absolute time. Its format is anything that java.util.Date.parse()
can parse. Specifying startTime in the <event> element is not requiredif 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 has "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.
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 timecomputed by adding
startTime and offset of a <calledComponent> elementshould 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>


Chapter 2: EPAgent Default Plug-ins

This section describes the default plug-ins provided with CA APM Environment
Performance Agent and their optional command-line arguments.
solaris/diskStats.pl (see page 33)
windows/processAvailability.pl AND solaris/processAvailability.pl (see page 34)
windows/diskStats.pl (see page 35)
apacheLogReader.pl, weblogicLogReader.pl, and websphereLogReader.pl (see page 35)
httpSvcAvailability.pl (see page 36)
kstat.pl (see page 38)
iisLogReader.pl (see page 39)
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.
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


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.
Each of these plug-ins take five optional command-line arguments:
match
Regular Perl expression to search for
resource
Resource part of the metric name
subResource
Sub-resource part of the metric name
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


windows/diskStats.pl
This plug-in reports disk usage/capacity statistics based on the statistics available from
the Windows 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
(Windows) metrics.
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.
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 wont begin reporting
to the Enterprise Manager until a new entry is added to the log file.
httpSvcAvailability.pl


Metrics Produced
Metrics produced by these plug-ins are detailed in following ones:
Apache log metrics
WebSphere log metrics
WebLogic log metrics
Each of these plug-ins take four optional command-line arguments:
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
Example:
perl apacheLogReader.pl -sleepTime 30 -logfileDir "c:/Apache/logs"
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.


This plug-in takes three optional command-line arguments:
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
kstat.pl


Perl Support Issues
For httpSvcAvailability.pl plug-in (HTTP):
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 ActiveStates Perl.
kstat.pl
This plug-in reports metrics based on the kernel statistics available from Solariss Kstat
utility.
Metrics Produced
Metrics produced by the kstat.pl plug-in are detailed in Solaris kernel statistics (Kstat)
metrics.
This plug-in takes four command-line arguments:
class
Regular expression that will match a kstat class
module
Regular expression that will match a kstat module
iisLogReader.pl


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


This plug-in takes four optional command-line arguments:
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
Example:
perl iisLogReader.pl -sleepTime 30 -logfileDir "c:/Program Files/iis/logs"
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.
LOGFILEDIR
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).
Default
C:/WINNT/system32/LogFiles/W3SVC1
iisLogReader.pl


LOGFILE
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.
Default
ex(tend)?\d+\.log
SLEEPTIME
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.
Default
15
RESOURCE
Resource part of the Introscope metric name. This corresponds to the first node
underneath the Agent node in the Workstation Investigator.
Default
IISWebServer
SUBRESOURCE
Subresource part of the Introscope metric name. This corresponds to the sub-nodes
underneath the Resource node specified above.
Default
<empty>
iisLogReader.pl


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.
Default
n/a
LINE_FORMAT Sub-Properties
The following table describes the property, LINE_FORMAT, and all its subproperties.
The following properties for LINE_FORMAT must exactly match the fields that are
logged to the logfile by the IIS Web Server. If the properties do not match, the
iisLogReader.pl plug-in fails 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). You can configure logging fields for the IIS Web Server
logging in IIS4.0 and IIS5.0 (see page 48).
By default, IIS Web Server logs only the following fields:
Time
ClientIPAddress
Method
URIStem
ProtocolStatus
To match, the default iisLogReader.cfg file also enables only these five LINE_FORMAT
subproperties.
Out-of-the-box, the iisLogReader.pl plug-in expects a default IIS Web Server logging
configuration. The plug-in can report all metrics with the exception of Bytes Transferred.
Bytes Transferred requires that the IIS Web Server logs the BytesSent data field and that
the iisLogReader.cfg subproperty, BytesSent, is uncommented/enabled. If the user fails
to enable BytesSent in IIS Web Server and in the iisLogReader.cfg, the Bytes Transferred
metric is not reported to CA Introscope.
If a subproperty line is uncommented, the iisLogReader.pl plug-in expects to find that
field in the IIS Web Server logfile (as specified by the LOGFILEDIR and LOGFILE
properties). Conversely, if the subproperty line is commented, the iisLogReader.pl
plug-in does not expect to find the field in the logfile. The order of the subproperty lines
already matches the left-to-right order in which the IIS Web Server logs the data (if the
fields are enabled in IIS Web Server). The ordering should not be changed.
iisLogReader.pl


DELIMITER
Continuous whitespace (spaces, tabs)
Default
\s+
FIELDS
n/a
Default
n/a
FIELDS->Date
The date on which the activity occurred. YYYY-MM-DD.
Default
\d\d\d\d-\d\d-\d\d
FIELDS->Time
Enabled by default.
The time the activity occurred. 24HH:MM:SS GMT.
Default
\d\d\d\d-\d\d-\d\d
FIELDS->ClientIPAddress
Enabled by default.
The IP address of the client that accessed your server. Four numbers, separated by
periods.
Default
\d+\.\d+\.\d+\.\d+
iisLogReader.pl


FIELDS->UserName
The name of the user who accessed your server. Any combination of -, backslash, and
alphanumeric characters.
Default
[-\\\w]+
FIELDS->ServiceName
The Internet service that was running on the client computer. Any combination of
alphanumeric characters.
Default
\w+
FIELDS->ServerName
The name of the server on which the log entry was generated. Any combination of
period, hyphens, alphanumeric characters.
Default
[.-\w]+
FIELDS->ServerIPAddress
The IP address of the server on which the log entry was generated. Four numbers,
separated by periods.
Default
\d+\.\d+\.\d+\.\d+
FIELDS->ServerPort
The port number the client is connected to. One or more digits.
Default
\d+
iisLogReader.pl


FIELDS->Method
Enabled by default.
The action the client was trying to perform (for example, a GET command).
Default
GET|HEAD|PUT|POST|DELETE
FIELDS->URIStem
Enabled by default.
The resource accessed; for example, an HTML page, a CGI program, or a script. A
sequence of non-spaces.
Default
\S+
FIELDS->URIQuery
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.
Default
\S+
FIELDS->ProtocolStatus
Enabled by default.
The status of the action, in HTTP terms.
Default
\d+
FIELDS->Win32Status
The status of the action, in terms used by Windows. One or more digits.
Default
\d+
iisLogReader.pl


FIELDS->BytesSent
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.
Default
\d+
FIELDS->BytesReceived
The number of bytes received by the server. One or more digits.
Default
\d+
FIELDS->TimeTaken
The length of time the action took in milliseconds. One or more digits.
Default
\d+
FIELDS->ProtocolVersion
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.
Default
[\w/.]+
FIELDS->Host
The host of the client. A sequence of alphanumeric characters, period, colons.
Default
[\w.:]+
iisLogReader.pl


FIELDS->UserAgent
The browser used on the client. A sequence of non-spaces.
Default
\S+
FIELDS->Cookie
The content of the cookie sent or received, if any. A sequence of non-spaces.
Default
\S+
FIELDS->Referer
The site that directed the user to the current site. A sequence of non-spaces.
Default
\S+
iisLogReader.pl


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

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.
5. Click Properties.
The Extended Logging Properties dialog window appears.
iisLogReader.pl


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.


Chapter 3: EPAgent Default Plug-in Metrics

This chapter describes the metrics produced by the default plug-ins included with the
EPAgent.
All metrics are calculated using the time set by your system clock. If the system clock is
reset during a transaction, the elapsed time reported for that transaction can be
misleading.
Invalid Character Replacement (see page 51)
IIS log reader metrics (see page 51)
HTTP/HTTPS service availability metrics (see page 56)
Solaris kernel statistics (Kstat) metrics (see page 58)
Process availability metrics (see page 58)
Disk Stats (Windows) Metrics (see page 59)
Disk Stats (Solaris) Metrics (see page 63)
Apache Log Metrics (see page 68)
WebSphere log metrics (see page 72)
WebLogic log metrics (see page 79)
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 automatically have these characters replaced:

Original
Character
Replaced By Descriptions
| _ pipes replaced by underscores
: ^ colons replaced by carets

IIS log reader metrics
The following sections describes 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, and describe the IISWebServer <Sub-Resource> metrics.


Total Page Hits
CA Introscope Data Type
IntCounter
Unit
1 (hit)
Default
on
Total Visitors Count
IntCounter
Unit
1 (hit)
Default
on
Page Hits For <URL>
IntCounter
Unit
1 (hit)
Default
on


Bytes Transferred
IntCounter
Unit
1 (MB)
Default
on
ErrorCount_400_BadRequest
IntCounter
Unit
1 (error)
Default
on
ErrorCount_401_Unauthorized
IntCounter
Unit
1 (error)
Default
on


ErrorCount_403_Forbidden
IntCounter
Unit
1 (error)
Default
on
ErrorCount_404_ServerConfiguration
IntCounter
Unit
1 (error)
Default
on
ErrorCount_500_InternalServerError
IntCounter
Unit
1 (error)
Default
on


ErrorMessage_400_BadRequest
StringEvent
Unit
N/a
Default
off
ErrorMessage_401_Unauthorized
StringEvent
Unit
N/a
Default
off
ErrorMessage_403_Forbidden
StringEvent
Unit
N/a
Default
off
HTTP/HTTPS service availability metrics


ErrorMessage_404_PageNotFound
StringEvent
Unit
N/a
Default
off
ErrorMessage_500_InternalServerError
StringEvent
Unit
N/a
Default
off
The following section describes the metrics generated by the httpSvcAvailability.pl
plug-in, and describe the Remote Machine
<hostnameOrlPAddr>|Service|HTTP<Sub-Resource> metrics.


Available
IntCounter
Unit
0-1
Default
on
Response Time
IntCounter
Unit
sec
Default
on
Average Throughput
IntCounter
Unit
KB/msec
Default
on
Solaris kernel statistics (Kstat) metrics


Solaris kernel statistics (Kstat) metrics
The following metrics are 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).
Solaris Kernel <class>|<module>|<name> Metrics
The following section describes the Solaris Kernel <class>|<module>|<name> metrics:
<stat>
IntCounter
Unit
Varies
Default
on
Process availability metrics
These are the metrics generated by the processAvailability.pl plug-in.
The following section describes the RunningProcesses <Sub-Resource> metrics.
Disk Stats (Windows) Metrics


Count
IntCounter
Unit
1 (process)
Default
on
These are the metrics generated by the <EPA_Home>/windows/diskStats.pl plug-in.
The following sections describe the RunningProcesses <Sub-Resource> metrics.
More information:
Disk Reads/sec (see page 60)
Disk Writes/sec (see page 60)
Disk Read Bytes/sec (see page 60)
Disk Write Bytes/sec (see page 61)
Current Disk Queue Length (see page 61)
Average Disk Read Time (ms) (see page 61)
Average Disk Write Time (ms) (see page 62)
Average Disk Bytes/Read (see page 62)
Average Disk Bytes/Write (see page 62)
Free Disk Space (mb) (see page 63)
Free Disk Space (%) (see page 63)



Disk Reads/sec
IntCounter
Unit
1 (count)
Default
on
Disk Writes/sec
IntCounter
Unit
1 (count)
Default
on
Disk Read Bytes/sec
IntCounter
Unit
1 byte
Default
on


Disk Write Bytes/sec
IntCounter
Unit
1 byte
Default
on
Current Disk Queue Length
IntCounter
Unit
1 (request)
Default
on
Average Disk Read Time (ms)
IntCounter
Unit
1 ms
Default
on


Average Disk Write Time (ms)
IntCounter
Unit
1 ms
Default
on
Average Disk Bytes/Read
IntCounter
Unit
1 byte
Default
on
Average Disk Bytes/Write
IntCounter
Unit
1 byte
Default
on
Disk Stats (Solaris) Metrics


Free Disk Space (mb)
IntCounter
Unit
1 mb
Default
on
Free Disk Space (%)
IntCounter
Unit
1 (process)
Default
on
This table shows the metrics generated by the <EPAgent_Home>/solaris/diskStats.pl
plug-in.
The following sections describe The Disk <Sub-Resource> metrics.


More information:
Disk Time (%) (see page 64)
Transaction Waiting Time (%) (see page 64)
Average # Transaction Active (see page 65)
Average # Transaction Waiting (see page 65)
Disk Reads/sec (see page 65)
Disk Writes/sec (see page 66)
KB Read per Second (see page 66)
KB Written per Second (see page 66)
Average Service Time in Waiting Queue (ms) (see page 67)
Average Service Time for Active Transactions (ms) (see page 67)
Free Disk Space (mb) (see page 67)
Free Disk Space (%) (see page 68)

Disk Time (%)
IntCounter
Unit
1 percent
Default
on
Transaction Waiting Time (%)
IntCounter
Unit
1 percent
Default
on


Average # Transaction Active
IntCounter
Unit
1 transaction
Default
on
Average # Transaction Waiting
IntCounter
Unit
1 transaction
Default
on
Disk Reads/sec
IntCounter
Unit
1 (count)
Default
on


Disk Writes/sec
IntCounter
Unit
1 (count)
Default
on
KB Read per Second
IntCounter
Unit
1 byte
Default
on
KB Written per Second
IntCounter
Unit
1 byte
Default
on


Average Service Time in Waiting Queue (ms)
IntCounter
Unit
1 ms
Default
on
Average Service Time for Active Transactions (ms)
IntCounter
Unit
1 ms
Default
on
Free Disk Space (mb)
IntCounter
Unit
1 mb
Default
on
Apache Log Metrics


Free Disk Space (%)
IntCounter
Unit
1 percent
Default
on
Apache Log Metrics
This table shows the metrics generated by the apacheLogReader.pl plug-in.
The following sections describe the ApacheWebServer <Sub-Resource> metrics.
More information:
PageHitCount (see page 69)
ErrorCount_400_BadRequest (see page 69)
ErrorCount_401_Unauthorized (see page 69)
ErrorCount_403_Forbidden (see page 70)
ErrorCount_404_PageNotFound (see page 70)
ErrorCount_500_ServerConfiguration (see page 70)
ErrorMessage_400_BadRequest (see page 71)
ErrorMessage_401_Unauthorized (see page 71)
ErrorMessage_403_Forbidden (see page 71)
ErrorMessage_404_PageNotFound (see page 72)
ErrorMessage_500_ServerConfiguration (see page 72)

Apache Log Metrics


PageHitCount
IntCounter
Unit
1 (hit)
Default
on
ErrorCount_400_BadRequest
IntCounter
Unit
1 (error)
Default
on
ErrorCount_401_Unauthorized
IntCounter
Unit
1 (error)
Default
on
Apache Log Metrics


ErrorCount_403_Forbidden
IntCounter
Unit
1 (error)
Default
on
ErrorCount_404_PageNotFound
IntCounter
Unit
1 (error)
Default
on
ErrorCount_500_ServerConfiguration
IntCounter
Unit
1 (error)
Default
on
Apache Log Metrics


ErrorMessage_400_BadRequest
StringEvent
Unit
1 (error)
Default
on
ErrorMessage_401_Unauthorized
StringEvent
Unit
1 (error)
Default
on
ErrorMessage_403_Forbidden
StringEvent
Unit
1 (error)
Default
on


ErrorMessage_404_PageNotFound
StringEvent
Unit
1 (error)
Default
on
ErrorMessage_500_ServerConfiguration
StringEvent
Unit
1 (error)
Default
on
These are the metrics generated by the websphereLogReader.pl plug-in.
The following sections describe the WebSphereApplicationServer <Sub-Resource>
metrics.


More information:
MessageCount_Audit (see page 73)
MessageCount_Warning (see page 73)
MessageCount_EventDebug (see page 74)
MessageCount_Error (see page 74)
MessageCount_Fatal (see page 74)
MessageText_Audit (see page 75)
MessageText_Warning (see page 75)
MessageText_EventDebug (see page 75)
MessageText_Error (see page 76)
MessageText_Fatal (see page 76)

MessageCount_Audit
IntCounter
Unit
1 (hit)
Default
on
MessageCount_Warning
IntCounter
Unit
1 (hit)
Default
on


MessageCount_EventDebug
IntCounter
Unit
1 (hit)
Default
on
MessageCount_Error
IntCounter
Unit
1 (hit)
Default
on
MessageCount_Fatal
IntCounter
Unit
1 (hit)
Default
on


MessageText_Audit
IntCounter
Unit
1 (hit)
Default
on
MessageText_Warning
IntCounter
Unit
1 (hit)
Default
on
MessageText_EventDebug
IntCounter
Unit
1 (hit)
Default
on


MessageText_Error
IntCounter
Unit
1 (hit)
Default
on
MessageText_Fatal
IntCounter
Unit
1 (hit)
Default
on
StringEvent
Unit
n/a
Default
on
IntCounter
Unit
1 (message)


Default
on
IntCounter
Unit
1 (message)
Default
on
IntCounter
Unit
1 (message)
Default
on
IntCounter
Unit
1 (message)
Default
on
IntCounter


Unit
1 (message)
Default
on
StringEvent
Unit
n/a
Default
off
StringEvent
Unit
n/a
Default
off
StringEvent
Unit
n/a
Default
off
StringEvent


Unit
n/a
Default
off
StringEvent
Unit
n/a
Default
off
This table shows the metrics generated by the weblogicLogReader.pl plug-in.
The following sections describe the WebLogicApplicationServer <Sub-Resource>
metrics.
More information:
ServerVersion (see page 80)
MessageCount_Warning (see page 80)
MessageCount_Error (see page 80)
MessageCount_Notice (see page 81)
MessageCount_Critical (see page 81)
MessageCount_Alert (see page 81)
MessageCount_Emergency (see page 82)
MessageText_Warning (see page 82)
MessageText_Error (see page 82)
MessageText_Notice (see page 83)
MessageText_Critical (see page 83)
MessageText_Alert (see page 83)
MessageText_Emergency (see page 84)



ServerVersion
StringEvent
Unit
n/a
Default
on
MessageCount_Warning
IntCounter
Unit
1 (message)
Default
on
MessageCount_Error
IntCounter
Unit
1 (message)
Default
on


MessageCount_Notice
IntCounter
Unit
1 (message)
Default
on
MessageCount_Critical
IntCounter
Unit
1 (message)
Default
on
MessageCount_Alert
IntCounter
Unit
1 (message)
Default
on


MessageCount_Emergency
IntCounter
Unit
1 (message)
Default
on
MessageText_Warning
StringEvent
Unit
n/a
Default
off
MessageText_Error
StringEvent
Unit
n/a
Default
off


MessageText_Notice
StringEvent
Unit
n/a
Default
off
MessageText_Critical
StringEvent
Unit
n/a
Default
off
MessageText_Alert
StringEvent
Unit
n/a
Default
off


MessageText_Emergency
StringEvent
Unit
n/a
Default
off


Chapter 4: EPAgent Properties

This appendix details properties files and settings you use to customize the Environment
Performance Agent. You can read the files for other information (located at
<EPAgent_Home>/epagentIntroscopeEPAgent.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 (see page 85)
Agent metric aging (see page 86)
Case-Sensitive Metrics (see page 90)
ChangeDetector Configuration (see page 91)
Enterprise Manager Connection (see page 94)
EPAgent Configuration (see page 95)
Extensions Directory (see page 96)
Logging (see page 96)
Processes (see page 97)
Remote Configuration (see page 99)
Stateful Plug-ins (see page 99)
Stateless Plug-ins (see page 101)
IntroscopeEPAgent.properties file
The settings for the EPAgent are the same type as found in the CA Introscope agent
profile.
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.
Agent metric aging


Process Name
CA Introscope names the EPAgent according to these criteria, which take precedence
in their shown order.
A name defined by the property, introscope.agent.customProcessName.
A name inferred from the name of the main class of the application.
The name set by introscope.agent.defaultProcessName.
More information:
Processes (see page 97)

Agent Name
The introscope.agent.agentName property defines a name of the EPAgent.
CA Introscope names the Environment Performance Agent according to these criteria,
which take precedence in their shown order:
A name defined by the property, introscope.agent.agentName (see page 99).
If a unique name is not defined in introscope.agent.agentName, the Environment
Performance Agent will be named UnknownAgent.
Agent metric aging
Agent metric aging periodically removes dead metrics from the agent memory cache. A
dead metric is a metric that has no new data reported in a configured amount of time.
Removing old metrics helps to improve agent performance and avoid potential metric
explosions.
Note: A metric explosion happens when an agent is inadvertently set up to report more
metrics than the system can handle. When too many metrics are reported, the agent
can affect the performance of the application server, or in extreme cases, prevent the
server from functioning at all.
Metrics that are in a group are removed only if all metrics in the group are considered
candidates for removal. Currently, only BlamePointTracer and
MetricRecordingAdministrator metrics are removed as a group. Other metrics are
removed individually.
Agent metric aging


The MetricRecordingAdministrator has the following interfaces for creating, retrieving,
or removing a metric group:
getAgent().IAgent_getMetricRecordingAdministrator.addMetricGroup
String component, collection metrics. The component name is the metric resource
name of the metric group. The metrics must be under the same metric node to
qualify as a group. The metrics are a collection of
com.wily.introscope.spec.metric.AgentMetric data structures. You can only add
AgentMetric data structures to this collection.
getAgent().IAgent_getMetricRecordingAdministrator.getMetricGroup
String component. Based on the component name which is the metric resource
name, you can get the Collection of metrics.
getAgent().IAgent_getMetricRecordingAdministrator.removeMetricGroup
String component. The metric group is removed based on the component which is
the metric resource name.
getAgent().IAgent_getDataAccumulatorFactory.isRemoved
Checks if the metric is removed. You use this interface if you keep an instance of an
accumulator in your extension. If the accumulator is removed because of metric
aging, you use this interface to prevent holding onto a dead reference.
Important! If you create an extension that uses a MetricRecordingAdministrator
interface (for example, for use with other CA Technologies products), be sure to delete
your own instance of an accumulator. If a metric is aged out because it has not been
invoked, and data later become available for that metric, the old accumulator instance
will not create new metric data points. To avoid this situation, do not delete your own
instance of an accumulator and use instead the getDataAccumulatorFactory interface.
Configuring agent metric aging
Agent metric aging is on by default. You can choose to turn off this capability using the
property introscope.agent.metricAging.turnOn (see page 88). If you remove this
property from the IntroscopeAgent.profile, agent metric aging is turned off by default.
Agent metric aging runs on a heartbeat in the agent. The heartbeat is configured using
the property introscope.agent.metricAging.heartbeatInterval (see page 89). Be sure to
keep the frequency of the heartbeat low. A higher heartbeat will impact the
performance of the agent and CA Introscope.
Agent metric aging


During each heartbeat, a certain set of metrics are checked. This is configurable using
the property introscope.agent.metricAging.dataChunk (see page 89). It is also important
to keep this value low, as a higher value will impact performance. The default value is
500 metrics to be checked per heartbeat. Each of the 500 metrics is checked to see if it
is a candidate for removal. For example, if you set this property to check chunks of 500
metrics per heartbeat, and you have a total of 10,000 metrics in the agent memory,
then it will take longer with lower impact on performance to check all 10,000 metrics.
However, if you set this property to a higher number, you would check all 10,000
metrics faster, but with possibly high overhead.
A metric is a candidate for removal if the metric has not received new data after certain
period of time. You can configure this period of time using the property
introscope.agent.metricAging.numberTimeslices (see page 90). This property is set to
3000 by default. If a metric meets the condition for removal, then a check is performed
to see if all the metrics in its group are candidates for metric removal. If this
requirement has also been met then the metric is removed.
introscope.agent.metricAging.turnOn
Turns on or off agent metric aging.
Property settings
True or False
Default
True
Example
introscope.agent.metricAging.turnOn=true
Notes
Changes to this property take effect immediately and do not require the managed
application to be restarted.
Agent metric aging


introscope.agent.metricAging.heartbeatInterval
Specifies the time interval when metrics are checked for removal, in seconds.
Default
1800
Example
introscope.agent.metricAging.heartbeatInterval=1800
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.metricAging.dataChunk
Specifies the number of metrics that are checked during each interval.
Default
500
Example
introscope.agent.metricAging.dataChunk=500
Notes
Case-Sensitive Metrics


introscope.agent.metricAging.numberTimeslices
This property specifies the number of intervals to check without any new data before
making it a candidate for removal.
Default
3000
Example
introscope.agent.metricAging.numberTimeslices=3000
Notes
Changes to this property take effect immediately and do not require restarting the
managed application.
introscope.agent.metricAging.metricExclude.ignore.0
Excludes specified metrics from being removed. To exclude one or more metrics from
aging, add the metric name or a metric filter to the list.
Property settings
Comma separated list of metrics. You can use an asterisk (*) as a wildcard in metric
names.
Default
The default is metric names beginning with Threads (Threads*).
Example
introscope.agent.metricAging.metricExclude.ignore.0=Threads*
Notes
Case-Sensitive Metrics
The following property configures case sensitivity.
ChangeDetector Configuration


introscope.epagent.metricscasesensitive
Enables metric names to be case-sensitive.
Property settings
True or False
Default
true
Example
introscope.epagent.metricscasesensitive=true
Notes
Commented out by default.
Set to true, this property enables metrics to be case-sensitive.
Set to false, this property turns off case sensitivity.
The following properties configure the EPAgent interaction with ChangeDetector.
introscope.changeDetector.enable
Specifies whether ChangeDetector is enabled or disabled. Set the property to true to
enable ChangeDetector. It is commented out and set to false by default. If you enable
ChangeDetector, you should also set the additional ChangeDetector-related properties.
Property settings
True or False
Default
False
Example
introscope.changeDetector.enable=false
Notes


introscope.changeDetector.rootDir
Specifies the root directory for ChangeDetector files. The root directory is the folder
where ChangeDetector creates its local cache files.
Property settings
Full path to the root directory for ChangeDetector files as a text string.
Default
The default path is c://sw//AppServer//wily//change_detector.
Example
introscope.changeDetector.rootDir=c://sw//AppServer//wily//change_detector
Notes
Use a backslash to escape the backslash character, as in the example.
introscope.changeDetector.isengardStartupWaitTimeInSec
Specifies the number of seconds to wait after the agent starts before ChangeDetector
tries to connect to the Enterprise Manager. This property is commented out by default.
Default
The default is 15 seconds.
Example
introscope.changeDetector.isengardStartupWaitTimeInSec=15
introscope.changeDetector.waitTimeBetweenReconnectInSec
Specifies the number of seconds ChangeDetector waits before retrying a connection to
the Enterprise Manager. This property is commented out by default.
Default
The default is 10 seconds.
Example
introscope.changeDetector.waitTimeBetweenReconnectInSec=10


introscope.changeDetector.enableEPA
When ChangeDetector EPAgent is enabled, an EPAgent plugin can be used as a data
source for change data in XML format.
Property settings
True or False
Default
true
Example
introscope.changeDetector.enableEPA=true
Notes
introscope.changeDetector.agentID
Specifies a text string used by ChangeDetector to identify the EPAgent.
Example
introscope.changeDetector.agentID=SampleApplicationName
Notes
introscope.changeDetector.profile
Specifies the absolute or relative path to the ChangeDetector datasources configuration
file. This property is commented out by default.
Default
The default is ChangeDetector-config.xml.
Example
introscope.changeDetector.profile=CDConfig\\ChangeDetector-config.xml
Notes
Use a backslash to escape the backslash character, as in the example.
Enterprise Manager Connection


introscope.changeDetector.profileDir
Specifies the absolute or relative path to the directory that contains datasource
configuration files. If this property is set, all of the datasource configuration files in this
directory are used in addition to any file specified by the
introscope.changeDetector.profile property. This property is commented out by default.
Default
The default is changeDetector_profiles.
Example
introscope.changeDetector.profileDir=c:\\CDconfig\\changeDetector_profiles
Notes
Use a backslash to escape the backslash character.
Enterprise Manager Connection
The following properties configure the connection to the Enterprise Manager.
introscope.agent.enterprisemanager.connectionorder
Specifies the connection order of backup Enterprise Manager the EPAgent uses if it is
disconnected from its primary Enterprise Manager. Items in the list must be
comma-separated.
Default
DEFAULT
Example
introscope.agent.enterprisemanager.connectionorder=DEFAULT
EPAgent Configuration


introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT
Specifies the host name of the computer running the Enterprise Manager that the agent
connects to by default.
Default
localhost
Example
introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT=localhost
Notes
EPAgent Configuration
The following properties configure the EPAgent itself.
introscope.epagent.config.networkDataPort
Specifies the port on which the EPAgent listens for network connections for incoming
XML data.
Default
8000
Example
introscope.epagent.config.networkDataPort=8000
Notes
This property is commented out by default.
Extensions Directory


introscope.epagent.config.httpServerPort
Specifies the port on which the EPAgent listens for HTTP GET commands.
Default
8080
Example
introscope.epagent.config.httpServerPort=8080
Notes
Extensions Directory
The following metric specifies the extensions directory.
introscope.agent.extensions.directory
Specifies the location of all extensions to be loaded by the agent. You can specify an
absolute or relative path to the directory. If you do not specify an absolute path, the
value you specify is resolved relative to the location of the IntroscopeAgent.profiles file.
Default
The default location is ext directory in the <EPAgent_Home>/epagent/ext directory.
Example
introscope.agent.extensions.directory=../ext
Notes
Logging
The following properties configure logging.
Processes


log4j.logger.EPAgent

Specifies the amount of logging detail for the EPAgent log and the and the output
location of the log file.
Default
INFO, console
Example
log4j.logger.EPAgent=INFO, console
Notes
Replace INFO with VERBOSE#com.wily.util.feedback.Log4JSeverityLevel to increase
the level of detail in the log.
Replace console with logfile to send the output to a log file instead of the console.
log4j.appender.logfile.File
This property controls both the logging level and the output location for agent logging.
Default
IntroscopeEPA.log
Example
log4j.appender.logfile.File=IntroscopeEPA.log
Notes
Full path names to the log file location and name can be used.
Processes
The following properties configure processes.
Processes


introscope.agent.customProcessName
Specifies a name for process being monitored.
Default
EPAgentProcess
Example
introscope.agent.customProcessName=EPAgentProcess
Notes
Set to the name of the application server for application-server specific installers.
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.
Default
UnknownProcess
Example
introscope.agent.defaultProcessName=UnknownProcess
Notes
The default may vary by installer.
Remote Configuration


introscope.agent.agentName
Specifies the name of the EPAgent as it appears in the Enterprise Manager and
Workstation.
Default
EPAgent
Example
introscope.agent.agentName=EPAgent
Notes
Set to UnknownAgent or name of application server for application-specific installers, as
in <appservername>Agent.
Remote Configuration
The following property allows you to remotely configure the EPAgent.
introscope.agent.remoteagentconfiguration.enabled
Enables or disables remote configuration of the EPAgent.
Property settings
True or False
Default
False
Example
introscope.agent.remoteagentconfiguration.enabled=false
Notes
Stateful Plug-ins
The following properties configure stateful plug-ins.
Stateful Plug-ins


introscope.epagent.plugins.stateful.names
Specifies names of the stateful plug-ins to run. This property is required to enable
EPAgent plug-ins.
Property settings
Comma-separated list of plug-in names.
Default
APACHE,WEBLOGIC,WEBSPHERE,IIS
Example
introscope.epagent.plugins.stateful.names=APACHE,WEBLOGIC,WEBSPHERE,IIS
Notes
These names can be user-defined, as long as they match the names used in the
following introscope.epagent.plugins.stateful.<pluginname>.command properties
introscope.epagent.stateful.<pluginname>.command
Specifies the command to run the plug-in specified in the
introscope.epagent.plugins.stateful.names property; requires one property line per
plug-in name specified.
Example
introscope.epagent.stateful.APACHE.command=perl apacheLogReader.pl
introscope.epagent.stateful.WEBLOGIC.command=perl weblogicLogReader.pl
Notes
Stateless Plug-ins


introscope.epagent.stateful.<pluginname>.class
Plug-ins are either "stateless" or "stateful". Stateless plug-ins are executed periodically
by the EPAgent based on either a cron-like schedule or a delay. Stateful plug-ins are
started once by the EPAgent and are intended to run forever. If a stateful plug-in does
quit, it will be restarted.
Plug-ins can either be an external process, specified with the "command" sub-key or
they can be a java class that is executed within the EPAgent virtual machine. Java class
plug-ins are specified with the "class" subkey and a fully qualified class name followed
by any optional arguments. For example: my.package.path.Class arg1 arg2 arg3.
Example
introscope.epagent.stateful.myplugin.class=my.package.path.Class arg1 arg2 arg3
Notes
Stateless Plug-ins
The following properties configure stateless plugins.
introscope.epagent.plugins.stateless.names
Specifies name(s) of stateless plug-ins to run.
Default
DISK,ORACLE,HTTP,KSTAT
Example
introscope.epagent.plugins.stateless.names=DISK,ORACLE,HTTP,KSTAT
Notes
These names can be user-defined, as long as they match the names used in the
following introscope.epagent.plugins.stateless.<pluginname>.command properties.
Stateless Plug-ins


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.
Example
introscope.epagent.stateless.DISK.command=perl diskStats.pl
Notes
introscope.epagent.stateless.<pluginname>.class
Specifies class to be run as a stateless plug-in within the EPAgent VM.
Notes
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.
Default
900
Example
introscope.epagent.stateless.DISK.delayInSeconds=900
Notes
Stateless Plug-ins


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).
Notes
This property is used instead of the
introscope.epagent.stateless.<pluginname>.delayInSeconds property. If both
properties are uncommented, EPAgent will quit.
introscope.epagent.config.stalledStatelessPluginTimeoutInSeconds
Specifies how long to wait before killing stalled stateless plug-ins.
Default
60 seconds
Example
#introscope.epagent.config.stalledStatelessPluginTimeoutInSeconds=60
Notes
Stateless Plug-ins


introscope.epagent.stateless.<pluginname>.metricNotReportedAction
This property is used to determine what happens if a stateless plug-in stops reporting
values.
Property settings
The valid values for this property are:
same - continue to report same value until the metric is aged out.
zero - report metric with value 0 (if the metric type is stringevent or timestamp,
action 'same' is performed).
stop - stop reporting the metric value
Default
same
Example
The MATCHEDPROCS example below uses processAvailability plug-in to return value of 1
for each running process whose name matches the regular expression specified by the
match parameter (i.e. processes whose name starts with 'f' in this case). The
metricNotReportedAction parameter value 'zero' is used to reset metric value to 0 when
a process is no longer running.
introscope.epagent.stateless.MATCHEDPROCS.command=perl processAvailability.pl
-match ^f -distinctmatch
introscope.epagent.stateless.MATCHEDPROCS.delayInSeconds=900
introscope.epagent.stateless.MATCHEDPROCS.metricNotReportedAction=zero

Index 105

Index

<
<stat> 58
A
Add Stateful Plug-ins 21
Add Stateless Plug-ins 22
Agent and Process Name Settings 85
Agent metric aging 86
Agent Name 86
Apache Log Metrics 68
apacheLogReader.pl, weblogicLogReader.pl, and
websphereLogReader.pl 35
Available 57
Average # Transaction Active 65
Average # Transaction Waiting 65
Average Disk Bytes/Read 62
Average Disk Bytes/Write 62
Average Disk Read Time (ms) 61
Average Disk Write Time (ms) 62
Average Service Time for Active Transactions (ms)
67
Average Service Time in Waiting Queue (ms) 67
Average Throughput 57
B
Bytes Transferred 53
C
CA Technologies Product References 3
Case-Sensitive Metrics 90
ChangeDetector Configuration 91
Command-Line Arguments 33, 34, 35, 36, 37, 38,
40
Configure EPAgent Logging Options 20
Configure EPAgent Properties 19
Configure the EPAgent for HTTP GET Input 24
Configure the EPAgent for Simple or XML Network
Input 23
Configuring agent metric aging 87
Configuring EPAgent Plug-ins 21
Configuring IIS Web Server logging in IIS4.0 and
IIS5.0 48
Configuring Java Class Plug-ins 23
Configuring the EPAgent 19
Configuring the EPAgent for Network Data Sources
23
Contact CA Technologies 5
Count 59
Creating an Error Snapshot in XML Format 29
Creating and Using Custom Plug-ins With the
EPAgent 25
Current Disk Queue Length 61
Custom Plug-ins 17
D
Default Plug-ins 17
DELIMITER 43
Disk Read Bytes/sec 60
Disk Reads/sec 60, 65
Disk Stats (Solaris) Metrics 63
Disk Stats (Windows) Metrics 59
Disk Time (%) 64
Disk Write Bytes/sec 61
Disk Writes/sec 60, 66
E
Enterprise Manager Connection 94
Environment Performance Agent Installation 18
EPAgent and CA Introscope 16
EPAgent and Scripting Environments 14
EPAgent Can Accept Input From Network Sources
15
EPAgent Can Receive Input From Processes 13
EPAgent Configuration 95
EPAgent Default Plug-in Metrics 51
EPAgent Default Plug-ins 33
EPAgent Events and Transaction Traces 29
EPAgent Properties 85
Error Logging 17
Error or Event Data Format 28
ErrorCount_400_BadRequest 53, 69
ErrorCount_401_Unauthorized 53, 69
ErrorCount_403_Forbidden 54, 70
ErrorCount_404_PageNotFound 70
ErrorCount_404_ServerConfiguration 54
ErrorCount_500_InternalServerError 54
ErrorCount_500_ServerConfiguration 70
ErrorMessage_400_BadRequest 55, 71
ErrorMessage_401_Unauthorized 55, 71


ErrorMessage_403_Forbidden 55, 71
ErrorMessage_404_PageNotFound 56, 72
ErrorMessage_500_InternalServerError 56
ErrorMessage_500_ServerConfiguration 72
Extensions Directory 96
F
FIELDS 43
FIELDS->BytesReceived 46
FIELDS->BytesSent 46
FIELDS->ClientIPAddress 43
FIELDS->Cookie 47
FIELDS->Date 43
FIELDS->Host 46
FIELDS->Method 45
FIELDS->ProtocolStatus 45
FIELDS->ProtocolVersion 46
FIELDS->Referer 47
FIELDS->ServerIPAddress 44
FIELDS->ServerName 44
FIELDS->ServiceName 44
FIELDS->Time 43
FIELDS->TimeTaken 46
FIELDS->URIQuery 45
FIELDS->URIStem 45
FIELDS->UserAgent 47
FIELDS->UserName 44
FIELDS->Win32Status 45
Free Disk Space (%) 63, 68
Free Disk Space (mb) 63, 67
H
HTTP/HTTPS service availability metrics 56
httpSvcAvailability.pl 36
I
IIS log reader metrics 51
iisLogReader.cfg Configuration File 40
iisLogReader.pl 39
Installing, Configuring, and Using the EPAgent 13
introscope.agent.agentName 99
introscope.agent.customProcessName 98
introscope.agent.defaultProcessName 98
introscope.agent.enterprisemanager.connectionord
er 94
introscope.agent.enterprisemanager.transport.tcp.h
ost.DEFAULT 95
introscope.agent.extensions.directory 96
introscope.agent.metricAging.dataChunk 89
introscope.agent.metricAging.heartbeatInterval 89
introscope.agent.metricAging.metricExclude.ignore.
0 90
introscope.agent.metricAging.numberTimeslices
90
introscope.agent.metricAging.turnOn 88
introscope.agent.remoteagentconfiguration.enabled
99
introscope.changeDetector.agentID 93
introscope.changeDetector.enable 91
introscope.changeDetector.enableEPA 93
introscope.changeDetector.isengardStartupWaitTim
eInSec 92
introscope.changeDetector.profile 93
introscope.changeDetector.profileDir 94
introscope.changeDetector.rootDir 92
introscope.changeDetector.waitTimeBetweenRecon
nectInSec 92
introscope.epagent.config.httpServerPort 96
introscope.epagent.config.networkDataPort 95
introscope.epagent.config.stalledStatelessPluginTim
eoutInSeconds 103
introscope.epagent.metricscasesensitive 91
introscope.epagent.plugins.stateful.names 100
introscope.epagent.plugins.stateless.names 101
introscope.epagent.stateful.<pluginname>.class
101
introscope.epagent.stateful.<pluginname>.comman
d 100
introscope.epagent.stateless.<pluginname>.class
102
introscope.epagent.stateless.<pluginname>.comman
d 102
introscope.epagent.stateless.<pluginname>.delayInS
econds 102
introscope.epagent.stateless.<pluginname>.metricN
otReportedAction 104
introscope.epagent.stateless.<pluginname>.schedul
e 103
IntroscopeEPAgent.properties file 85
Invalid Character Replacement 51
K
KB Read per Second 66
KB Written per Second 66
kstat.pl 38

Index 107

L
LINE_FORMAT 42
LINE_FORMAT Sub-Properties 42
log4j.appender.logfile.File 97
log4j.logger.EPAgent 97
LOGFILE 41
LOGFILEDIR 40
Logging 96
M
MessageCount_Alert 81
MessageCount_Audit 73
MessageCount_Critical 81
MessageCount_Emergency 82
MessageCount_Error 74, 80
MessageCount_EventDebug 74
MessageCount_Fatal 74
MessageCount_Notice 81
MessageCount_Warning 73, 80
MessageText_Alert 83
MessageText_Audit 75
MessageText_Critical 83
MessageText_Emergency 84
MessageText_Error 76, 82
MessageText_EventDebug 75
MessageText_Fatal 76
MessageText_Notice 83
MessageText_Warning 75, 82
Metric Data Format 26
Metrics Produced 33, 34, 35, 36, 38, 39
N
Nested Components 29
Next Steps 22
P
Page Hits For <URL> 52
PageHitCount 69
Perl Support Issues 38, 39
Plug-in Types 16
Precautions With Either Type of Custom Plug-in
Format 27
Process availability metrics 58
Process Name 86
Processes 97
R
Remote Configuration 99
Remove Stateful and Stateless Plug-ins 23
RESOURCE 41
Response Time 57
Run EPAgent in Verbose Mode and Redirect the
Output File 20
Run the EPAgent 24
Run the EPAgent on UNIX 25
S
ServerVersion 80
Simple Format for Error or Event Data 28
Simple Format for Metric Data 26
Simple XML Format for Error or Event Data 28
SLEEPTIME 41
Solaris Kernel <class>|<module>|<name> Metrics
58
Solaris kernel statistics (Kstat) metrics 58
solaris/diskStats.pl 33
Stateful Plug-ins 99
Stateless Plug-ins 101
SUBRESOURCE 41
Supported Plug-ins 16
T
The Environment Performance Agent Overview 13
The EPAgent Standalone Installers 18
Total Page Hits 52
Total Visitors Count 52
Transaction Waiting Time (%) 64
W
WebLogic log metrics 79
WebSphere log metrics 72
windows/diskStats.pl 35
windows/processAvailability.pl AND
solaris/processAvailability.pl 34
X
XML Format for Error or Event Data With Parameters
and Time Data 28
XML Format for Metric Data 26
XML Schema for Error or Event Data 31

APM - 9.5 - Environment Performance Agent Implementation Guide

Загружено:

Сведения о документе

Исходное описание:

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

APM - 9.5 - Environment Performance Agent Implementation Guide

Загружено:

Авторское право:

Доступные форматы

Environment Performance Agent

Вам также может понравиться