How To Run The Envirment Performance Agent On A Pc Or Mac Or Mac (For Linux)

Transcription

1 CA Applicati Performance Management Envirment Performance Agent Implementati Guide Release 9.6

2 This Documentati, which includes embedded help systems and electrically distributed materials, (hereinafter referred to as the Documentati ) is for your informatial purposes ly and is subject to change or withdrawal by CA at any time. This Documentati is proprietary informati of CA and may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without the prior written csent of CA. If you are a licensed user of the software product(s) addressed in the Documentati, you may print or otherwise make available a reasable number of copies of the Documentati for internal use by you and your employees in cnecti 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 Documentati 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 reas, it is your respsibility to certify in writing to CA that all copies and partial copies of the Documentati 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 Documentati 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 Documentati is CA. Provided with Restricted Rights. Use, duplicati or disclosure by the ed States Government is subject to the restrictis set forth in FAR Sectis , , and (c)(1) - (2) and DFARS Secti (b)(3), as applicable, or their successors. Copyright 2014 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belg to their respective companies.

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

4 CA Applicati Performance Management for TIBCO BusinessWorks (CA APM for TIBCO BusinessWorks) CA Applicati Performance Management for TIBCO Enterprise Message Service (CA APM for TIBCO Enterprise Message Service) CA Applicati Performance Management for Web Servers (CA APM for Web Servers) CA Applicati Performance Management for webmethods Broker (CA APM for webmethods Broker) CA Applicati Performance Management for webmethods Integrati Server (CA APM for webmethods Integrati Server) CA Applicati Performance Management Integrati for CA CMDB (CA APM Integrati for CA CMDB) CA Applicati Performance Management Integrati for CA NSM (CA APM Integrati for CA NSM) CA Applicati Performance Management LeakHunter (CA APM LeakHunter) CA Applicati Performance Management Transacti Generator (CA APM WTG) CA Cross-Enterprise Applicati Performance Management CA Customer Experience Manager (CA CEM) CA Embedded Entitlements Manager (CA EEM) CA ehealth Performance Manager (CA ehealth) CA Insight Database Performance Mitor for DB2 for z/os CA Introscope CA SiteMinder CA Spectrum CA NetQoS Performance Center CA Performance Center

5 Ctact CA Technologies Ctact CA Support For your cvenience, CA Technologies provides e site where you can access the informati that you need for your Home Office, Small Business, and Enterprise CA Technologies products. At you can access the following resources: Online and telephe ctact informati for technical assistance and customer services Informati about user communities and forums Product and documentati downloads CA Support policies and guidelines Other helpful resources appropriate for your product Providing Feedback About Product Documentati If you have comments or questis about CA Technologies product documentati, you can send a message to [email protected]. To provide feedback about CA Technologies product documentati, complete our short customer survey which is available the CA Support website at

6

7 Ctents Chapter 1: Installing, Cfiguring, and Using the EPAgent 13 The Envirment Performance Agent Overview EPAgent Can Receive Input From Processes EPAgent and Scripting Envirments EPAgent Can Accept Input From Network Sources EPAgent and CA Introscope Supported Plug-ins Envirment Performance Agent Installati The EPAgent Standale Installers Cfiguring the EPAgent Cfigure EPAgent Properties Cfigure EPAgent Logging Optis Cfiguring EPAgent Plug-ins Cfiguring the EPAgent for Network Data Sources Run the EPAgent Run the EPAgent UNIX Creating and Using Custom Plug-ins With the EPAgent Metric Data Format Precautis With Either Type of Custom Plug-in Format Error or Event Data Format Creating an Error Snapshot in XML Format EPAgent Events and Transacti Traces XML Schema for Error or Event Data Chapter 2: EPAgent Plug-ins 33 solaris/diskstats.pl Metrics Produced Command-Line Arguments windows/processavailability.pl AND solaris/processavailability.pl Metrics Produced Command-Line Arguments windows/diskstats.pl Metrics Produced Command-Line Arguments apachelogreader.pl, weblogiclogreader.pl, and webspherelogreader.pl Metrics Produced Ctents 7

8 Command-Line Arguments httpsvcavailability.pl Metrics Produced Command-Line Arguments Perl Support Issues kstat.pl Metrics Produced Command-Line Arguments Perl Support Issues iislogreader.pl Metrics Produced Command-Line Arguments iislogreader.cfg Cfigurati File Cfiguring IIS Web Server logging in IIS4.0 and IIS Chapter 3: EPAgent Plug-in Metrics 51 Invalid Character Replacement IIS log reader metrics Total Page Hits Total Visitors Count Page Hits For <URL> Bytes Transferred ErrorCount_400_BadRequest ErrorCount_401_Unauthorized ErrorCount_403_Forbidden ErrorCount_404_ServerCfigurati ErrorCount_500_InternalServerError ErrorMessage_400_BadRequest ErrorMessage_401_Unauthorized ErrorMessage_403_Forbidden ErrorMessage_404_PageNotFound ErrorMessage_500_InternalServerError HTTP/HTTPS service availability metrics Available Respse Time Average Throughput Solaris kernel statistics (Kstat) metrics Solaris Kernel <class> <module> <name> Metrics Process availability metrics Count Disk Stats (Windows) Metrics Envirment Performance Agent Implementati Guide

9 Disk Reads/sec Disk Writes/sec Disk Read Bytes/sec Disk Write Bytes/sec Current Disk Queue Length Average Disk Read Time (ms) Average Disk Write Time (ms) Average Disk Bytes/Read Average Disk Bytes/Write Free Disk Space (mb) Free Disk Space (%) Disk Stats (Solaris) Metrics Disk Time (%) Transacti Waiting Time (%) Average # Transacti Active Average # Transacti Waiting Disk Reads/sec Disk Writes/sec KB Read per Secd KB Written per Secd Average Service Time in Waiting Queue (ms) Average Service Time for Active Transactis (ms) Free Disk Space (mb) Free Disk Space (%) Apache Log Metrics PageHitCount ErrorCount_400_BadRequest ErrorCount_401_Unauthorized ErrorCount_403_Forbidden ErrorCount_404_PageNotFound ErrorCount_500_ServerCfigurati ErrorMessage_400_BadRequest ErrorMessage_401_Unauthorized ErrorMessage_403_Forbidden ErrorMessage_404_PageNotFound ErrorMessage_500_ServerCfigurati WebSphere log metrics MessageCount_Audit MessageCount_Warning MessageCount_EventDebug MessageCount_Error MessageCount_Fatal Ctents 9

10 MessageText_Audit MessageText_Warning MessageText_EventDebug MessageText_Error MessageText_Fatal WebLogic log metrics ServerVersi MessageCount_Warning MessageCount_Error MessageCount_Notice MessageCount_Critical MessageCount_Alert MessageCount_Emergency MessageText_Warning MessageText_Error MessageText_Notice MessageText_Critical MessageText_Alert MessageText_Emergency Chapter 4: EPAgent Properties 85 IntroscopeEPAgent.properties file Agent and Process Name Settings Agent Metric Aging Properties Cfiguring agent metric aging introscope.agent.metricaging.turnon introscope.agent.metricaging.heartbeatinterval introscope.agent.metricaging.datachunk introscope.agent.metricaging.numbertimeslices introscope.agent.metricaging.metricexclude.ignore Case-Sensitive Metrics introscope.epagent.metricscasesensitive ChangeDetector Cfigurati introscope.changedetector.enable introscope.changedetector.rootdir introscope.changedetector.isengardstartupwaittimeinsec introscope.changedetector.waittimebetweenrecnectinsec introscope.changedetector.enableepa introscope.changedetector.agentid introscope.changedetector.profile introscope.changedetector.profiledir Envirment Performance Agent Implementati Guide

11 Enterprise Manager Cnecti introscope.agent.enterprisemanager.cnectiorder introscope.agent.enterprisemanager.transport.tcp.host.default EPAgent Cfigurati introscope.epagent.cfig.networkdataport introscope.epagent.cfig.httpserverport Extensis Directory introscope.agent.extensis.directory Logging log4j.logger.epagent log4j.appender.logfile.file Processes introscope.agent.customprocessname introscope.agent.defaultprocessname introscope.agent.agentname Remote Cfigurati introscope.agent.remoteagentcfigurati.enabled Stateful Plug-ins introscope.epagent.plugins.stateful.names introscope.epagent.stateful.<pluginname>.command introscope.epagent.stateful.<pluginname>.class Stateless Plug-ins introscope.epagent.plugins.stateless.names introscope.epagent.stateless.<pluginname>.command introscope.epagent.stateless.<pluginname>.class introscope.epagent.stateless.<pluginname>.delayinsecds introscope.epagent.stateless.<pluginname>.schedule introscope.epagent.cfig.stalledstatelessplugintimeoutinsecds introscope.epagent.stateless.<pluginname>.metricnotreportedacti Index 105 Ctents 11

12

13 Chapter 1: Installing, Cfiguring, and Using the EPAgent This secti covers installing, cfiguring, and using the CA APM Envirment Performance Agent (EPAgent). This secti ctains the following topics: The Envirment Performance Agent Overview (see page 13) Envirment Performance Agent Installati (see page 18) Cfiguring the EPAgent (see page 19) Run the EPAgent (see page 24) Run the EPAgent UNIX (see page 25) Creating and Using Custom Plug-ins With the EPAgent (see page 25) The Envirment Performance Agent Overview The CA APM Envirment Performance Agent (EPAgent) integrates metric data from n-java sources into CA Introscope. The EPAgent takes advantage of the facility available in many operating systems for e 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 envirment (such as Perl) the result is an adaptable and powerful facility for gathering applicati performance informati 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 a command line. For example: A compiled program written by the user in C A Perl script Chapter 1: Installing, Cfiguring, and Using the EPAgent 13

14 The Envirment Performance Agent Overview By executing a simple PRINT functi, the applicati or script in the subprocess can communicate with the EPAgent. This illustrati shows how applicatis or scripts communicate metric data to the EPAgent by printing to STDOUT. The EPAgent expects the text it receives using STDOUT to cform to a specific format, either: a simple name/value pair or XML The EPAgent text format requirements and optis are fully explained later in this guide. In this guide, the applicati 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 informati: Cfiguring EPAgent Plug-ins (see page 21) Creating and Using Custom Plug-ins With the EPAgent (see page 25) EPAgent Plug-ins (see page 33) EPAgent and Scripting Envirments Although the EPAgent can receive text from any executable entity in a subprocess (including compiled applicatis), the most flexible approach is to use a scripting envirment such as Perl, KornShell, or rexx. Interpretative scripting envirments have the advantage of ease of implementati and often supply libraries or interfaces to real-world data sources such as relatial databases, OS subsystems (process table, file system, etc.) and third party products. 14 Envirment Performance Agent Implementati Guide

15 The Envirment Performance Agent Overview Scripts can gather informati from a wide variety of sources. For example, a script may: call a library functi or system utility to check for the existence of a critical applicati such as a database. scan and parse applicati logfiles to detect applicati errors. The flexibility of a scripting envirment allows the EPAgent to gather performance and management informati from virtually any source. This illustrati shows how scripts can access informati from many sources. CA Technologies emphasizes the use of Perl with the EPAgent because Perl interpreters are available 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 functis such as checking for process availability, obtaining disk performance statistics and reading HTTP logs. These scripts may be extended to perform other functis. Note: For support with customizatis to PBDs, EPAgent scripts, or JavaScript calculators, ctact CA Technologies Professial Services. EPAgent Can Accept Input From Network Sources In additi to accepting input from local processes, EPAgent can accept input from network sources. This ability is useful for collecting informati from networked processes where EPAgent cannot run, for example, a C++ backend system that provides mitoring informati using a network port, or posts data periodically to a web URL. More informati: Cfiguring the EPAgent for Network Data Sources (see page 23) Chapter 1: Installing, Cfiguring, and Using the EPAgent 15

16 The Envirment Performance Agent Overview EPAgent and CA Introscope EPAgent runs as a standale process. Like the Java Agent or.net Agent, it cnects to the Enterprise Manager to deliver management and performance informati. This illustrati shows how EPAgent forwards data to the Enterprise Manager. The EPAgent helps obtain a better overall view of your applicati envirment. Distributed applicati architectures are complex, often comprised of a mixture of Java and n-java applicati subsystems. The EPAgent permits the easy collecti of informati from the n-java and n-.net porti of the applicati envirment for display algside the Java and.net metrics in the CA Introscope Workstati. Supported Plug-ins Plug-in Types The EPAgent supports both stateful and stateless plug-ins. Note: Perl versi or later is required by all default plug-ins. These are the available plug-in types: Stateful plug-ins Stateful plug-ins are expected to be lg running scripts (daems) 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-ins Stateless plug-ins are designed to run a recurring schedule and can be cfigured 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 de by the EPAgent to ensure ly e instance of a stateless plug-in is running at e time, so plug-in developers are required to design their stateless plug-ins to run and complete in a reasably short period of time. 16 Envirment Performance Agent Implementati Guide

17 The Envirment Performance Agent Overview 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. Plug-ins The EPAgent includes a library of default plug-ins that you can use with minimal cfigurati. The following table summarizes the functi of each plug-in and the operating systems which they are supported. Plug-in Functi Supported process availability check OS-level disk statistics Apache log reader looks for a running process with a given name reports reads/writes, transacti times, % time waiting, disk capacity, and so reports number of HTTP errors, number of transactis, average transacti size Solaris Solaris Solaris WebLogic log reader reports error count, warning count Solaris WebSphere log reader reports error count, warning count Solaris IIS log reader HTTP Service Availability HTTPS Service Availability Solaris Kstat statistics reports number of errors by type, number of pages served, number of users by IP address reports cnecti success/failure, cnecti round-trip time, average throughput/bandwidth reports any statistics available through Kstat utility, such as I/O statistics, network statistics for all devices, virtual memory statistics Windows Solaris Solaris Custom Plug-ins The EPAgent supports gathering data from arbitrary programs and plug-ins, with the requirement that they produce output in e of two supported formats. More informati: Creating and Using Custom Plug-ins With the EPAgent (see page 25) Chapter 1: Installing, Cfiguring, and Using the EPAgent 17

18 Envirment Performance Agent Installati Envirment Performance Agent Installati You use the Standale agent installer to install the EPAgent. Note: For more informati, see the CA APM Installati and Upgrade Guide. The EPAgent Standale Installers You can install the EPAgent another computer using e of the following Standale agent installers. You can download CA APM products from the CA APM software download area CA Support. EPAgent<versi>windows.zip EPAgent<versi>ebcdic.tar EPAgent<versi>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 18 Envirment Performance Agent Implementati Guide

19 Cfiguring the EPAgent /xml (top-level directory for ChangeDetector files) ChangeDetectorAgent.jar ChangeDetector-Agent_Server.jar ChangeDetector-CommAll.jar ChangeDetector-cfig.xml Windows: cdnativefile.dll UNIX: libcdnativefile.so Cfiguring the EPAgent The EPAgent includes a set of agent cfigurati properties, such as the Enterprise Manager locati 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 informati: Cfiguring EPAgent Plug-ins (see page 21) Cfiguring the EPAgent for Network Data Sources (see page 23) Cfigure EPAgent Properties (see page 19) Cfigure EPAgent Logging Optis (see page 20) Cfigure 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. Cfigure 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 informati about properties, see the CA APM Java Agent Implementati Guide. Chapter 1: Installing, Cfiguring, and Using the EPAgent 19

20 Cfiguring the EPAgent 2. If you change the name or locati 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 the command line for example, after -jar it will not work. Cfigure EPAgent Logging Optis By default, the EPAgent sends message and error output to the command csole. You can cfigure 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 ctrols verbose mode also ctrols 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, csole 3. Uncomment the property log4j.logger.introscopeagent and replace INFO with VERBOSE#com.wily.util.feedback.Log4JSeverityLevel, and csole with logfile to send the output to a log file instead of the csole. 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 csole, until the properties files is read and implemented. After the properties file has been implemented, the log is written into the logfile from then wards. 20 Envirment Performance Agent Implementati Guide

21 Cfiguring the EPAgent Cfiguring EPAgent Plug-ins Add Stateful 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 d t need from the default plug-ins in the IntroscopeEPAgent.properties file, or add additial plug-ins. EPAgent plug-ins are separated into two sectis in the IntroscopeEPAgent.properties file, stateful and stateless. Plug-ins used by the EPAgent are cfigured in the IntroscopeEPAgent.properties file. Follow these steps: 1. Open the <EPAgent_Home>/epagent/IntroscopeEPAgent.properties file. 2. Uncomment the property introscope.epagent.plugins.stateful.names, and add the names for all stateful plug-ins, separated by commas, as in the following example: introscope.epagent.plugins.stateful.names=apache,weblogic,websphere,iis 3. For each stateful plug-in name added in the previous step, add a line specifying the full command required to launch or start the stateful plug-in, including any command-line arguments desired. 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 e doubled), such as: introscope.epagent.stateful.test.command=perl c:\\mydirectory\\myscript.pl More informati: EPAgent Plug-ins (see page 33) Chapter 1: Installing, Cfiguring, and Using the EPAgent 21

22 Cfiguring the EPAgent Next Steps Add Stateless Plug-ins 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. 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 additial lines specifying: the full command-line required to launch or start the stateless plug-in (including any command-line arguments desired, see EPAgent 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 secds, with the following syntax: introscope.epagent.stateless.<pluginname>.delayinsecds=<value in secds> For example: introscope.epagent.stateless.disk.command=/usr/bin/perl <EPAgent_Home>/epagent/epaplugins/solaris/diskStats.pl introscope.epagent.stateless.disk.delayinsecds=900 introscope.epagent.stateless.oracle.command=/usr/bin/perl <EPAgent_Home>/epagent/solaris/processAvailability.pl introscope.epagent.stateless.oracle.delayinsecds=900 introscope.epagent.stateless.http.command=/usr/bin/perl <EPAgent_Home>/epaplugins/solaris/httpSvcAvailability.pl introscope.epagent.stateless.http.delayinsecds=900 introscope.epagent.stateless.kstat.command=/usr/bin/perl <EPAgent_Home>/epaplugins/solaris/kstat.pl introscope.epagent.stateless.kstat.delayinsecds=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. 22 Envirment Performance Agent Implementati Guide

23 Cfiguring the EPAgent More informati: EPAgent Plug-ins (see page 33) Remove Stateful and Stateless Plug-ins You can remove the plug-ins for any reas. Follow these steps: Cfiguring Java Class Plug-ins 1. Open the <EPAgent_Home>/epagent/IntroscopeEPAgent.properties file. 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. To cfigure a plug-in that is a Java class that is executed within the EPAgent JVM, cfigure 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 optial arguments, for example: introscope.epagent.plugins.stateful.names=add introscope.epagent.stateful.add.class=com.wily.math.add 1 2 Cfiguring the EPAgent for Network Data Sources You can cfigure the EPAgent to accept data from network sources. Cfigure the EPAgent for simple or XML network input (see page 23). Cfigure the EPAgent for HTTP GET input (see page 24). Cfigure 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.cfig.networkdataport=8000 Chapter 1: Installing, Cfiguring, and Using the EPAgent 23

24 Run the EPAgent Cfigure 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: 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.cfig.httpserverport= Restart the EPAgent. The changes take effect. 3. Test the HTTP GET request through a browser. For example: MyHTTPMetric Test:MyCounter&metricValue=15 After 15 secds, 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 functiality 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 informati about Wget is available at: Run the EPAgent You can run the EPAgent as either a standale.jar file, or a Java applicati. To run the EPAgent as a standale.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" 24 Envirment Performance Agent Implementati Guide

25 Run the EPAgent UNIX To run the EPAgent as a Java applicati 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 UNIX You can use a ctrol script (shell script) to run the Introscope EPAgent a UNIX operating system. Follow these steps: 1. Open a command prompt. 2. Navigate to the directory that has the ctrol script. For example: cd Introscope<versi_number>/bin 3. Run the command that correspds to the acti 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 informati that is usually sufficient for most user s needs. However, you may want to use custom plug-ins with the EPAgent. To do this, observe two guidelines: Make sure the output of the custom plug-ins can be parsed by the EPAgent (see 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 secti Cfiguring EPAgent plug-ins (see page 21). Chapter 1: Installing, Cfiguring, and Using the EPAgent 25

26 Creating and Using Custom Plug-ins With the EPAgent 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 e 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 e 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 ctain an equals sign (=). If there is need for an equals sign in the name, use the XML format. The value may ctain 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 "" 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 additial informati, such as Introscope metric name, Introscope metric type, and value, as in the following example: <metric type="lgcounter" name="resource Usage File IO:diskWrites" value="37" /> <metric type="stringevent" name="apache Errors:LastErrorString" value="error: Apache shutdown unexpectedly" /> 26 Envirment Performance Agent Implementati Guide

27 Creating and Using Custom Plug-ins With the EPAgent 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 e of the following: PerIntervalCounter the 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 invocatis per 15 secds followed by 15 method invocatis per 15 secds, then aggregating to 30 secds would result in "25 method invocatis per 30 secds". int values can go up and down IntAverage int value that is averaged over time IntRate the value is a per secd rate. These metrics are aggregated over time by taking the average of the values. LgCounter lg values can go up and down LgAverage lg value that is averaged over time StringEvent represents a type which periodically generates Strings. This recorder does not have a noti of current value; it merely reports events in the order in which they are reported to it. Timestamp a type which generates successively increasing timestamps. The comparis is case-insensitive (to make it easy for the plug-in writer). If a numeric type is supplied, but the value is n-numeric, nothing is reported to Introscope and the EPAgent will log an error. Precautis With Either Type of Custom Plug-in Format Csider the following precautis when you use either type of custom plug-in format: Supporting both formats causes an interacti 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 ctinues with the next line. For each metric name, ly e metric type can be specified. If more than e 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 Chapter 1: Installing, Cfiguring, and Using the EPAgent 27

28 Creating and Using Custom Plug-ins With the EPAgent 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 col: is part of a "name=value" pair, with each pair separated by the ampersand character (&). is an optial parameter to the event. The example below is the output of a hypothetical script that mitors the Firefox browser process and sends a notificati 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 "Cnecti Pool" or "Java Virtual Machine"). The example below provides a notificati that some event happened in Some Resource. <event resource="some Resource"/> The timestamp will be the time the event was created, and the durati of the event will be zero. XML Format for Error or Event Data With Parameters and Time Data You can cfigure event notificati with an explicit timestamp and an explicit durati. The timestamp format is any Java-parsable format. The durati is in millisecds. The example below is an event with a durati of e minute (60,000 millisecds): <event resource="some Resource" starttime=" " durati="60000"> </event> <param name="urgent" value="true"/> 28 Envirment Performance Agent Implementati Guide

29 Creating and Using Custom Plug-ins With the EPAgent Creating an Error Snapshot in XML Format Nested Compents An error snapshot must indicate its type as an error snapshot in the parameters: <event resource="some Resource" starttime=" " durati="60000"> </event> <param name="trace Type" value="errorsnapshot"/> The example below shows an event with nested subcompents. An event can have from zero to an infinite number of sub-compents, and each of those can also have from zero to an infinite number of sub-compents. In practice, the level of nesting tends to be small or zero. <event resource="some Resource"> </event> <calledcompent resource="another Resource"> <param name="iscorrelated" value="uncertain"/> <calledcompent resource="a Third Resource"/> <calledcompent resource="a Fourth Resource"/> </calledcompent> EPAgent Events and Transacti Traces You can view EPAgent events in the Event Viewer as transacti traces by selecting the Trace View tab. Trace views are easier to understand when time informati is ctained in the event sent by the EPAgent. To include time informati, use the starttime and offset attributes the <event> and <calledcompent> 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 required if absent, it defaults to the value of the current time, as specified by the Java methods System.currentTimeMillis() or new Date().getTime(). Omitting starttime from a <calledcompent> element makes the time default to the time of the ctaining 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 millisecds and is added to the starttime attribute (whether starttime is default or explicit) to produce the actual time reported for the <event> or <calledcompent>. Chapter 1: Installing, Cfiguring, and Using the EPAgent 29

30 Creating and Using Custom Plug-ins With the EPAgent Example 1 <event resource="customized Web Server" starttime=" " durati="500"> <calledcompent resource="web Server Module" offset="300" durati="100"/> </event> The trace view of this event has "Customized Web Server" starting at and "Web Server Module" starting at ( ). Specifying a durati in each element produces a useful trace view showing: "Customized Web Server" running 300 millisecds "Web Server Module" called by "Customized Web Server" and running for 100 millisecds "Customized Web Server" running for another 100 millisecds after "Web Server Module" returns Example 2 <event resource="customized Web Server" durati="500"> <calledcompent resource="web Server Module" offset="300" durati="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 millisecds 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=" " offset="1000" durati="5000"> <calledcompent resource="web Server Module" starttime=" " durati="200"/> </event> Here "Customized Web Server" starts at ( ) and "Web Server Module" starts at Notice again how specifying duratis promotes readability and usability. Incorrectly specifying starttimes, offsets and duratis can make trace views hard to read, so care must be taken when using them. In particular, the start time computed by adding starttime and offset of a <calledcompent> element should always be after the start time of its ctaining <event> or <calledcompent> and the (start time + durati) of a <calledcompent> should always be less than the (start time + durati) of its ctaining <event> or <calledcompent>. 30 Envirment Performance Agent Implementati Guide

31 Creating and Using Custom Plug-ins With the EPAgent XML Schema for Error or Event Data The formal XSD schema supported is: <?xml versi="1.0" encoding="utf-8"?> <xs:schema xmlns:xs=" elementform="qualified" attributeform="unqualified"> <xs:element name="event" type="eventelement"> <xs:annotati> <xs:documentati>the root element for events. This element is nearly equivalent to the calledcompent element, except that the event element must occur ly ce, at the outermost level.</xs:documentati> </xs:annotati> </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="calledcompent" type="eventelement"> <xs:annotati> <xs:documentati>a compent called by the ctaining element. This element is nearly equivalent to the event element, except that this element cannot occur at the outermost level. </xs:documentati> </xs:annotati> </xs:element> <xs:complextype name="eventelement"> <xs:sequence> <xs:element ref="param" minoccurs="0" maxoccurs="unbounded"/> <xs:element ref="calledcompent" minoccurs="0" maxoccurs="unbounded"/> </xs:sequence> <xs:attribute name="starttime" type="xs:datetime" use="optial"/> <xs:attribute name="offset" type="xs:integer" use="optial" default="0"/> <xs:attribute name="durati" type="xs:datetime" use="optial" default="0"/> </xs:complextype> </xs:schema> Chapter 1: Installing, Cfiguring, and Using the EPAgent 31

32

33 Chapter 2: EPAgent Plug-ins This secti describes the default plug-ins provided with CA APM Envirment Performance Agent and their optial command-line arguments. This secti ctains the following topics: 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 ctaining informati 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 informati about all disks is reported. For example, the following command reports metrics all local disks: perl diskstats.pl The following command reports metrics ly the disks '/' and '/usr': perl diskstats.pl / /usr Note: You may want to use this argument to narrow your results. Chapter 2: EPAgent Plug-ins 33

34 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 ''. Metrics Produced Metrics produced by the /windows/processavailability.pl and solaris/processavailability.pl plug-in are detailed in Process availability metrics. Command-Line Arguments Each of these plug-ins take five optial command-line arguments: match Regular Perl expressi to search for resource Resource part of the metric name subresource metric Sub-resource part of the metric name Main part of the metric name distinctmatch This has no value and determines whether to keep and report counts for each regular expressi match separately. This opti 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 34 Envirment Performance Agent Implementati Guide

35 windows/diskstats.pl windows/diskstats.pl This plug-in reports disk usage/capacity statistics based the statistics available from the Windows Performance Mitor. 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. Command-Line Arguments This plug-in takes disk names as command-line arguments. If no disk names are specified, informati about all disks is reported. For example, the following command reports metrics all local disks: perl diskstats.pl The following command reports metrics ly 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 the metrics cfigured in the <webserver>logreader.cfg file. Each web server applicati logfile parser has its own cfigurati 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 w t begin reporting to the Enterprise Manager until a new entry is added to the log file. Chapter 2: EPAgent Plug-ins 35

36 httpsvcavailability.pl Metrics Produced Metrics produced by these plug-ins are detailed in following es: Apache log metrics WebSphere log metrics WebLogic log metrics Command-Line Arguments Each of these plug-ins take four optial command-line arguments: logfiledir Directory in which the logfiles are located sleeptime Number of secds to delay between each check of the logfile for new messages logfile Regular expressi that correspds to the name of the logfiles generated subresource Sub-resource part of the metric name Example: perl apachelogreader.pl -sleeptime 30 -logfiledir "c:/apache/logs" httpsvcavailability.pl This plug-in reports metrics based 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. 36 Envirment Performance Agent Implementati Guide

37 httpsvcavailability.pl Command-Line Arguments This plug-in takes three optial command-line arguments: url get metric A comma-delimited set of URLs with optial 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. 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 applicati servers may not support GET. Must specify at least e of: GET,HEAD If both GET and HEAD are specified, then HEAD is executed first, followed by GET. : -request HEAD A comma-delimited listing of metrics to return av = Availability / Can Cnect (0=no, 1=yes) rt = Round-trip Respse Time (for cnect) tp = Throughput (kbytes. #Kbytes returned / round-trip respse) all = all statistics : all Example: perl epaplugins/solaris/httpsvcavailability.pl -url Chapter 2: EPAgent Plug-ins 37

38 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. provides Perl v5.6.1 which includes libwww-perl as part of the installati. For httpsvcavailability.pl plug-in (HTTPS): For https service checking Windows, Crypt-SSLeay (v ), should be installed. For https service checking Solaris, Net-SSLeay (v1.05+), should be installed. Both of these are most easily installed using the ppm Package Manager tool included with ActiveState s Perl. kstat.pl This plug-in reports metrics based the kernel statistics available from Solaris s Kstat utility. Metrics Produced Metrics produced by the kstat.pl plug-in are detailed in Solaris kernel statistics (Kstat) metrics. Command-Line Arguments This plug-in takes four command-line arguments: class Regular expressi that will match a kstat class module Regular expressi that will match a kstat module 38 Envirment Performance Agent Implementati Guide

39 iislogreader.pl name statistic Regular expressi that will match a kstat name Regular expressi 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 informati 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 installati, then the kstat.pl command-line utility will be used, which may incur slightly higher overhead. iislogreader.pl This plug-in reports metrics based the cfigurati in the iislogreader.cfg file. Note: When using this log reader plug-in, the EPAgent w t begin reporting to the Enterprise Manager until a new entry is added to the log file. Metrics Produced Metrics produced by the iislogreader.pl plug-in are detailed in IIS log reader metrics. Chapter 2: EPAgent Plug-ins 39

40 iislogreader.pl Command-Line Arguments This plug-in takes four optial command-line arguments: logfiledir Directory in which the logfiles are located sleeptime Number of secds to delay between each check of the logfile for new messages logfile Regular expressi that correspds to the name of the logfiles generated subresource Sub-resource part of the metric name Example: perl iislogreader.pl -sleeptime 30 -logfiledir "c:/program Files/iis/logs" iislogreader.cfg Cfigurati File LOGFILEDIR The iislogreader.cfg file ctains values for the command-line arguments in the iislogreader.pl file. Each web server applicati logfile parser has its own cfigurati file with default values for sleep delay, subresource name, resource name, logfile directory, and logfile name pattern. The cfig file also ctains a list of metrics to match and report. Each metric cfigurati has a match (regular expressi), metrictype, metricname, and metricvalue. Full directory pathname that ctains the logfiles for the associated web server. Note: Forward slashes are valid path separators for Windows paths (back slashes are acceptable as well). C:/WINNT/system32/LogFiles/W3SVC1 40 Envirment Performance Agent Implementati Guide

41 iislogreader.pl LOGFILE Name of the logfile to read. This should be a regular expressi 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 cfigured for W3C Extended Log File Format, which is the ly supported format by the iislogreader.pl plug-in. ex(tend)?\d+\.log SLEEPTIME Number of secds 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 secds), otherwise the counter metrics will be incorrect. 15 RESOURCE Resource part of the Introscope metric name. This correspds to the first node underneath the Agent node in the Workstati Investigator. IISWebServer SUBRESOURCE Subresource part of the Introscope metric name. This correspds to the sub-nodes underneath the Resource node specified above. <empty> Chapter 2: EPAgent Plug-ins 41

42 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. 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 cfigured within the IIS Admin Tool (or web page in older versis of IIS). You can cfigure logging fields for the IIS Web Server logging in IIS4.0 and IIS5.0 (see page 48). By default, IIS Web Server logs ly the following fields: Time ClientIPAddress Method URIStem ProtocolStatus To match, the default iislogreader.cfg file also enables ly these five LINE_FORMAT subproperties. Out-of-the-box, the iislogreader.pl plug-in expects a default IIS Web Server logging cfigurati. The plug-in can report all metrics with the excepti 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). Cversely, 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. 42 Envirment Performance Agent Implementati Guide

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

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

45 iislogreader.pl FIELDS->Method Enabled by default. The acti the client was trying to perform (for example, a GET command). 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 n-spaces. \S+ FIELDS->URIQuery The query, if any, the client was trying to perform; that is, e or more search strings for which the client was seeking a match. A sequence of n-spaces. \S+ FIELDS->ProtocolStatus FIELDS->Win32Status Enabled by default. The status of the acti, in HTTP terms. \d+ The status of the acti, in terms used by Windows. One or more digits. \d+ Chapter 2: EPAgent Plug-ins 45

46 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 in order to collect the "Bytes Transferred" metric. \d+ FIELDS->BytesReceived FIELDS->TimeTaken The number of bytes received by the server. One or more digits. \d+ The length of time the acti took in millisecds. One or more digits. \d+ FIELDS->ProtocolVersi FIELDS->Host The protocol (HTTP, FTP) versi 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. [\w/.]+ The host of the client. A sequence of alphanumeric characters, period, cols. [\w.:]+ 46 Envirment Performance Agent Implementati Guide

47 iislogreader.pl FIELDS->UserAgent The browser used the client. A sequence of n-spaces. \S+ FIELDS->Cookie The ctent of the cookie sent or received, if any. A sequence of n-spaces. \S+ FIELDS->Referer The site that directed the user to the current site. A sequence of n-spaces. \S+ Chapter 2: EPAgent Plug-ins 47

48 iislogreader.pl Cfiguring IIS Web Server logging in IIS4.0 and IIS 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 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. 48 Envirment Performance Agent Implementati Guide

49 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 secti. 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 2: EPAgent Plug-ins 49

50

51 Chapter 3: EPAgent 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 transacti, the elapsed time reported for that transacti can be misleading. This secti ctains the following topics: 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 col ( : ) are reserved characters. Any user or system-generated names that ctain these characters automatically have these characters replaced: Original Character Replaced By Descriptis _ pipes replaced by underscores : ^ cols replaced by carets IIS log reader metrics The following sectis 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. Chapter 3: EPAgent Plug-in Metrics 51

52 IIS log reader metrics Total Page Hits 1 (hit) Total Visitors Count 1 (hit) Page Hits For <URL> 1 (hit) 52 Envirment Performance Agent Implementati Guide

53 IIS log reader metrics Bytes Transferred 1 (MB) ErrorCount_400_BadRequest 1 (error) ErrorCount_401_Unauthorized 1 (error) Chapter 3: EPAgent Plug-in Metrics 53

54 IIS log reader metrics ErrorCount_403_Forbidden 1 (error) ErrorCount_404_ServerCfigurati 1 (error) ErrorCount_500_InternalServerError 1 (error) 54 Envirment Performance Agent Implementati Guide

55 IIS log reader metrics ErrorMessage_400_BadRequest StringEvent N/a off ErrorMessage_401_Unauthorized StringEvent N/a off ErrorMessage_403_Forbidden StringEvent N/a off Chapter 3: EPAgent Plug-in Metrics 55

56 HTTP/HTTPS service availability metrics ErrorMessage_404_PageNotFound StringEvent N/a off ErrorMessage_500_InternalServerError StringEvent N/a off HTTP/HTTPS service availability metrics The following secti describes the metrics generated by the httpsvcavailability.pl plug-in, and describe the Remote Machine <hostnameorlpaddr> Service HTTP<Sub-Resource> metrics. 56 Envirment Performance Agent Implementati Guide

57 HTTP/HTTPS service availability metrics Available 0-1 Respse Time sec Average Throughput KB/msec Chapter 3: EPAgent Plug-in Metrics 57

58 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 both the Solaris system being mitored, Solaris naming ccepts, as well as the command-line invocati of the kstat.pl plug-in by the Envirment Performance Agent (as cfigured in IntroscopeEPAgent.properties). Solaris Kernel <class> <module> <name> Metrics <stat> The following secti describes the Solaris Kernel <class> <module> <name> metrics: Varies Process availability metrics These are the metrics generated by the processavailability.pl plug-in. The following secti describes the RunningProcesses <Sub-Resource> metrics. 58 Envirment Performance Agent Implementati Guide

59 Disk Stats (Windows) Metrics Count 1 (process) Disk Stats (Windows) Metrics These are the metrics generated by the <EPA_Home>/windows/diskStats.pl plug-in. The following sectis describe the RunningProcesses <Sub-Resource> metrics. More informati: 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) Chapter 3: EPAgent Plug-in Metrics 59

60 Disk Stats (Windows) Metrics Disk Reads/sec 1 (count) Disk Writes/sec 1 (count) Disk Read Bytes/sec 1 byte 60 Envirment Performance Agent Implementati Guide

61 Disk Stats (Windows) Metrics Disk Write Bytes/sec 1 byte Current Disk Queue Length 1 (request) Average Disk Read Time (ms) 1 ms Chapter 3: EPAgent Plug-in Metrics 61

62 Disk Stats (Windows) Metrics Average Disk Write Time (ms) 1 ms Average Disk Bytes/Read 1 byte Average Disk Bytes/Write 1 byte 62 Envirment Performance Agent Implementati Guide

63 Disk Stats (Solaris) Metrics Free Disk Space (mb) 1 mb Free Disk Space (%) 1 (process) Disk Stats (Solaris) Metrics This table shows the metrics generated by the <EPAgent_Home>/solaris/diskStats.pl plug-in. The following sectis describe The Disk <Sub-Resource> metrics. Chapter 3: EPAgent Plug-in Metrics 63

64 Disk Stats (Solaris) Metrics More informati: Disk Time (%) (see page 64) Transacti Waiting Time (%) (see page 64) Average # Transacti Active (see page 65) Average # Transacti Waiting (see page 65) Disk Reads/sec (see page 65) Disk Writes/sec (see page 66) KB Read per Secd (see page 66) KB Written per Secd (see page 66) Average Service Time in Waiting Queue (ms) (see page 67) Average Service Time for Active Transactis (ms) (see page 67) Free Disk Space (mb) (see page 67) Free Disk Space (%) (see page 68) Disk Time (%) 1 percent Transacti Waiting Time (%) 1 percent 64 Envirment Performance Agent Implementati Guide

65 Disk Stats (Solaris) Metrics Average # Transacti Active 1 transacti Average # Transacti Waiting 1 transacti Disk Reads/sec 1 (count) Chapter 3: EPAgent Plug-in Metrics 65

66 Disk Stats (Solaris) Metrics Disk Writes/sec 1 (count) KB Read per Secd 1 byte KB Written per Secd 1 byte 66 Envirment Performance Agent Implementati Guide

67 Disk Stats (Solaris) Metrics Average Service Time in Waiting Queue (ms) 1 ms Average Service Time for Active Transactis (ms) 1 ms Free Disk Space (mb) 1 mb Chapter 3: EPAgent Plug-in Metrics 67

68 Apache Log Metrics Free Disk Space (%) 1 percent Apache Log Metrics This table shows the metrics generated by the apachelogreader.pl plug-in. The following sectis describe the ApacheWebServer <Sub-Resource> metrics. More informati: 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_ServerCfigurati (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_ServerCfigurati (see page 72) 68 Envirment Performance Agent Implementati Guide

69 Apache Log Metrics PageHitCount 1 (hit) ErrorCount_400_BadRequest 1 (error) ErrorCount_401_Unauthorized 1 (error) Chapter 3: EPAgent Plug-in Metrics 69

70 Apache Log Metrics ErrorCount_403_Forbidden 1 (error) ErrorCount_404_PageNotFound 1 (error) ErrorCount_500_ServerCfigurati 1 (error) 70 Envirment Performance Agent Implementati Guide

71 Apache Log Metrics ErrorMessage_400_BadRequest StringEvent 1 (error) ErrorMessage_401_Unauthorized StringEvent 1 (error) ErrorMessage_403_Forbidden StringEvent 1 (error) Chapter 3: EPAgent Plug-in Metrics 71

72 WebSphere log metrics ErrorMessage_404_PageNotFound StringEvent 1 (error) ErrorMessage_500_ServerCfigurati StringEvent 1 (error) WebSphere log metrics These are the metrics generated by the webspherelogreader.pl plug-in. The following sectis describe the WebSphereApplicatiServer <Sub-Resource> metrics. 72 Envirment Performance Agent Implementati Guide

73 WebSphere log metrics More informati: 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 1 (hit) MessageCount_Warning 1 (hit) Chapter 3: EPAgent Plug-in Metrics 73

74 WebSphere log metrics MessageCount_EventDebug 1 (hit) MessageCount_Error 1 (hit) MessageCount_Fatal 1 (hit) 74 Envirment Performance Agent Implementati Guide

75 WebSphere log metrics MessageText_Audit 1 (hit) MessageText_Warning 1 (hit) MessageText_EventDebug 1 (hit) Chapter 3: EPAgent Plug-in Metrics 75

76 WebSphere log metrics MessageText_Error 1 (hit) MessageText_Fatal 1 (hit) StringEvent n/a 1 (message) 76 Envirment Performance Agent Implementati Guide

77 WebSphere log metrics 1 (message) 1 (message) 1 (message) Chapter 3: EPAgent Plug-in Metrics 77

78 WebSphere log metrics 1 (message) StringEvent n/a off StringEvent n/a off StringEvent n/a off StringEvent 78 Envirment Performance Agent Implementati Guide

79 WebLogic log metrics n/a off StringEvent n/a off WebLogic log metrics This table shows the metrics generated by the weblogiclogreader.pl plug-in. The following sectis describe the WebLogicApplicatiServer <Sub-Resource> metrics. More informati: ServerVersi (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) Chapter 3: EPAgent Plug-in Metrics 79

80 WebLogic log metrics ServerVersi StringEvent n/a MessageCount_Warning 1 (message) MessageCount_Error 1 (message) 80 Envirment Performance Agent Implementati Guide

81 WebLogic log metrics MessageCount_Notice 1 (message) MessageCount_Critical 1 (message) MessageCount_Alert 1 (message) Chapter 3: EPAgent Plug-in Metrics 81

82 WebLogic log metrics MessageCount_Emergency 1 (message) MessageText_Warning StringEvent n/a off MessageText_Error StringEvent n/a off 82 Envirment Performance Agent Implementati Guide

83 WebLogic log metrics MessageText_Notice StringEvent n/a off MessageText_Critical StringEvent n/a off MessageText_Alert StringEvent n/a off Chapter 3: EPAgent Plug-in Metrics 83

84 WebLogic log metrics MessageText_Emergency StringEvent n/a off 84 Envirment Performance Agent Implementati Guide

85 Chapter 4: EPAgent Properties This appendix details properties files and settings you use to customize the Envirment Performance Agent. You can read the files for other informati (located at <EPAgent_Home>/epagentIntroscopeEPAgent.properties.) Note: In these files, Windows machines, when adding a path, you must escape a backslash (\) with another backslash (each e doubled), such as C:\\Introscope\\lib\\Agent.jar. This secti ctains the following topics: IntroscopeEPAgent.properties file (see page 85) Agent Metric Aging Properties (see page 86) Case-Sensitive Metrics (see page 89) ChangeDetector Cfigurati (see page 90) Enterprise Manager Cnecti (see page 93) EPAgent Cfigurati (see page 94) Extensis Directory (see page 95) Logging (see page 95) Processes (see page 96) Remote Cfigurati (see page 98) Stateful Plug-ins (see page 98) Stateless Plug-ins (see page 100) 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 informati of a single EPAgent over multiple agent sessis. These properties are optial. If the agent name is not defined, it will be known as UnknownAgent. Chapter 4: EPAgent Properties 85

86 Agent Metric Aging Properties 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 applicati. The name set by introscope.agent.defaultprocessname. More informati: Processes (see page 96) Agent Name The introscope.agent.agentname property defines a name of the EPAgent. CA Introscope names the Envirment Performance Agent according to these criteria, which take precedence in their shown order: A name defined by the property, introscope.agent.agentname (see page 98). If a unique name is not defined in introscope.agent.agentname, the Envirment Performance Agent will be named UnknownAgent. Agent Metric Aging Properties This secti ctains the following topics: Cfiguring agent metric aging (see page 87) introscope.agent.metricaging.turnon (see page 88) introscope.agent.metricaging.heartbeatinterval (see page 88) introscope.agent.metricaging.datachunk (see page 88) introscope.agent.metricaging.numbertimeslices (see page 89) introscope.agent.metricaging.metricexclude.ignore.0 (see page 89) 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 cfigured amount of time. Removing old metrics helps to improve agent performance and avoid potential metric explosis. Note: A metric explosi 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 applicati server, or in extreme cases, prevent the server from functiing at all. 86 Envirment Performance Agent Implementati Guide

87 Agent Metric Aging Properties Metrics that are in a group are removed ly if all metrics in the group are csidered candidates for removal. Currently, ly BlamePointTracer and MetricRecordingAdministrator metrics are removed as a group. Other metrics are removed individually. The MetricRecordingAdministrator has the following interfaces for creating, retrieving, or removing a metric group: getagent().iagent_getmetricrecordingadministrator.addmetricgroup String compent, collecti metrics. The compent 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 collecti of com.wily.introscope.spec.metric.agentmetric data structures. You can ly add AgentMetric data structures to this collecti. getagent().iagent_getmetricrecordingadministrator.getmetricgroup String compent. Based the compent name which is the metric resource name, you can get the Collecti of metrics. getagent().iagent_getmetricrecordingadministrator.removemetricgroup String compent. The metric group is removed based the compent 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 extensi. If the accumulator is removed because of metric aging, you use this interface to prevent holding to a dead reference. Important! If you create an extensi 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 situati, do not delete your own instance of an accumulator and use instead the getdataaccumulatorfactory interface. Cfiguring agent metric aging Agent metric aging is 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 a heartbeat in the agent. The heartbeat is cfigured using the property introscope.agent.metricaging.heartbeatinterval (see page 88). Be sure to keep the frequency of the heartbeat low. A higher heartbeat will impact the performance of the agent and CA Introscope. Chapter 4: EPAgent Properties 87

88 Agent Metric Aging Properties During each heartbeat, a certain set of metrics are checked. This is cfigurable using the property introscope.agent.metricaging.datachunk (see page 88). 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 lger with lower impact 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 cfigure this period of time using the property introscope.agent.metricaging.numbertimeslices (see page 89). This property is set to 3000 by default. If a metric meets the cditi 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 or off agent metric aging. Values: true or false : true Example: introscope.agent.metricaging.turnon=true Note: Changes to this property take effect immediately and do not require the managed applicati to be restarted. introscope.agent.metricaging.heartbeatinterval Specifies the time interval when metrics are checked for removal, in secds. : 1800 Example: introscope.agent.metricaging.heartbeatinterval=1800 Note: You must restart the managed applicati before changes to this property take effect. introscope.agent.metricaging.datachunk Specifies the number of metrics that are checked during each interval. : 500 Example: introscope.agent.metricaging.datachunk=500 Note: Changes to this property take effect immediately and do not require the managed applicati to be restarted. 88 Envirment Performance Agent Implementati Guide

89 Case-Sensitive Metrics introscope.agent.metricaging.numbertimeslices Specifies the number of intervals to check without any new data before making it a candidate for removal. : 3000 Example: introscope.agent.metricaging.numbertimeslices=3000 Note: Changes to this property take effect immediately and do not require restarting the managed applicati. introscope.agent.metricaging.metricexclude.ignore.0 Excludes specified metrics from being removed. To exclude e or more metrics from aging, add the metric name or a metric filter to the list. Values: Comma separated list of metrics. You can use an asterisk (*) as a wildcard in metric names. : metric names beginning with Threads (Threads*). Example: introscope.agent.metricaging.metricexclude.ignore.0=threads* Note: Changes to this property take effect immediately and do not require the managed applicati to be restarted. Case-Sensitive Metrics The following property cfigures case sensitivity. introscope.epagent.metricscasesensitive Enables metric names to be case-sensitive. Property settings True or False true Example introscope.epagent.metricscasesensitive=true Chapter 4: EPAgent Properties 89

90 ChangeDetector Cfigurati 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. ChangeDetector Cfigurati The following properties cfigure the EPAgent interacti 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 additial ChangeDetector-related properties. Property settings True or False False Example introscope.changedetector.enable=false Notes You must restart the managed applicati before changes to this property take effect. 90 Envirment Performance Agent Implementati Guide

91 ChangeDetector Cfigurati 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. 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 secds to wait after the agent starts before ChangeDetector tries to cnect to the Enterprise Manager. This property is commented out by default. The default is 15 secds. Example introscope.changedetector.isengardstartupwaittimeinsec=15 introscope.changedetector.waittimebetweenrecnectinsec Specifies the number of secds ChangeDetector waits before retrying a cnecti to the Enterprise Manager. This property is commented out by default. The default is 10 secds. Example introscope.changedetector.waittimebetweenrecnectinsec=10 Chapter 4: EPAgent Properties 91

92 ChangeDetector Cfigurati 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 true Example introscope.changedetector.enableepa=true Notes Commented out by default. introscope.changedetector.agentid Specifies a text string used by ChangeDetector to identify the EPAgent. Example introscope.changedetector.agentid=sampleapplicatiname Notes Commented out by default. introscope.changedetector.profile Specifies the absolute or relative path to the ChangeDetector datasources cfigurati file. This property is commented out by default. The default is ChangeDetector-cfig.xml. Example introscope.changedetector.profile=cdcfig\\changedetector-cfig.xml Notes Use a backslash to escape the backslash character, as in the example. 92 Envirment Performance Agent Implementati Guide

93 Enterprise Manager Cnecti introscope.changedetector.profiledir Specifies the absolute or relative path to the directory that ctains datasource cfigurati files. If this property is set, all of the datasource cfigurati files in this directory are used in additi to any file specified by the introscope.changedetector.profile property. This property is commented out by default. The default is changedetector_profiles. Example introscope.changedetector.profiledir=c:\\cdcfig\\changedetector_profiles Notes Use a backslash to escape the backslash character. Enterprise Manager Cnecti The following properties cfigure the cnecti to the Enterprise Manager. introscope.agent.enterprisemanager.cnectiorder Specifies the cnecti order of backup Enterprise Manager the EPAgent uses if it is discnected from its primary Enterprise Manager. Items in the list must be comma-separated. DEFAULT Example introscope.agent.enterprisemanager.cnectiorder=default Chapter 4: EPAgent Properties 93

94 EPAgent Cfigurati introscope.agent.enterprisemanager.transport.tcp.host.default Specifies the host name of the computer running the Enterprise Manager that the agent cnects to by default. : localhost Example: introscope.agent.enterprisemanager.transport.tcp.host.default=localhost Note: You must restart the managed applicati before changes to this property take effect. EPAgent Cfigurati The following properties cfigure the EPAgent itself. introscope.epagent.cfig.networkdataport Specifies the port which the EPAgent listens for network cnectis for incoming XML data Example introscope.epagent.cfig.networkdataport=8000 Notes This property is commented out by default. 94 Envirment Performance Agent Implementati Guide

95 Extensis Directory introscope.epagent.cfig.httpserverport Specifies the port which the EPAgent listens for HTTP GET commands Example introscope.epagent.cfig.httpserverport=8080 Notes This property is commented out by default. Extensis Directory The following metric specifies the extensis directory. introscope.agent.extensis.directory Specifies the locati of all extensis 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 locati of the IntroscopeAgent.profiles file. The default locati is ext directory in the <EPAgent_Home>/epagent/ext directory. Example introscope.agent.extensis.directory=../ext Notes You must restart the managed applicati before changes to this property take effect. Logging The following properties cfigure logging. Chapter 4: EPAgent Properties 95

96 Processes log4j.logger.epagent Specifies the amount of logging detail for the EPAgent log and the and the output locati of the log file. INFO, csole Example log4j.logger.epagent=info, csole Notes Replace INFO with VERBOSE#com.wily.util.feedback.Log4JSeverityLevel to increase the level of detail in the log. Replace csole with logfile to send the output to a log file instead of the csole. log4j.appender.logfile.file This property ctrols both the logging level and the output locati for agent logging. IntroscopeEPA.log Example log4j.appender.logfile.file=introscopeepa.log Notes Full path names to the log file locati and name can be used. Processes The following properties cfigure processes. 96 Envirment Performance Agent Implementati Guide

97 Processes introscope.agent.customprocessname Specifies a name for process being mitored. EPAgentProcess Example introscope.agent.customprocessname=epagentprocess Notes Set to the name of the applicati server for applicati-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 applicati. UnknownProcess Example introscope.agent.defaultprocessname=unknownprocess Notes The default may vary by installer. Chapter 4: EPAgent Properties 97

98 Remote Cfigurati introscope.agent.agentname Specifies the name of the EPAgent as it appears in the Enterprise Manager and Workstati. EPAgent Example introscope.agent.agentname=epagent Notes Set to UnknownAgent or name of applicati server for applicati-specific installers, as in <appservername>agent. Remote Cfigurati The following property allows you to remotely cfigure the EPAgent. introscope.agent.remoteagentcfigurati.enabled Enables or disables remote cfigurati of the EPAgent. Property settings True or False False Example introscope.agent.remoteagentcfigurati.enabled=false Notes Changes to this property take effect immediately and do not require the managed applicati to be restarted. Stateful Plug-ins The following properties cfigure stateful plug-ins. 98 Envirment Performance Agent Implementati Guide

99 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. APACHE,WEBLOGIC,WEBSPHERE,IIS Example introscope.epagent.plugins.stateful.names=apache,weblogic,websphere,iis Notes This property is commented out by default. These names can be user-defined, as lg 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 e 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 This property is commented out by default. Chapter 4: EPAgent Properties 99

100 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 either a cr-like schedule or a delay. Stateful plug-ins are started ce 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 optial arguments. For example: my.package.path.class arg1 arg2 arg3. Example introscope.epagent.stateful.myplugin.class=my.package.path.class arg1 arg2 arg3 Notes This property is commented out by default. Stateless Plug-ins The following properties cfigure stateless plugins. introscope.epagent.plugins.stateless.names Specifies name(s) of stateless plug-ins to run. DISK,ORACLE,HTTP,KSTAT Example introscope.epagent.plugins.stateless.names=disk,oracle,http,kstat Notes This property is commented out by default. These names can be user-defined, as lg as they match the names used in the following introscope.epagent.plugins.stateless.<pluginname>.command properties. 100 Envirment Performance Agent Implementati Guide

101 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 e property line per plug-in name specified. Example introscope.epagent.stateless.disk.command=perl diskstats.pl Notes This property is commented out by default. introscope.epagent.stateless.<pluginname>.class Specifies class to be run as a stateless plug-in within the EPAgent VM. Notes This property is commented out by default. introscope.epagent.stateless.<pluginname>.delayinsecds Specifies the frequency (in secds) that the EPAgent runs the specified plug-in; requires e property line per plug-in name specified. 900 Example introscope.epagent.stateless.disk.delayinsecds=900 Notes This property is commented out by default. Chapter 4: EPAgent Properties 101

102 Stateless Plug-ins introscope.epagent.stateless.<pluginname>.schedule Specifies the schedule which to run the plug-in specified in introscope.epagent.stateless.<pluginname>.command property. Input is CrTab Schedule Syntax (or "man 5 crtab" a UNIX system). Notes This property is commented out by default. This property is used instead of the introscope.epagent.stateless.<pluginname>.delayinsecds property. If both properties are uncommented, EPAgent will quit. introscope.epagent.cfig.stalledstatelessplugintimeoutinsecds Specifies how lg to wait before killing stalled stateless plug-ins. 60 secds Example #introscope.epagent.cfig.stalledstatelessplugintimeoutinsecds=60 Notes This property is commented out by default. 102 Envirment Performance Agent Implementati Guide

103 Stateless Plug-ins introscope.epagent.stateless.<pluginname>.metricnotreportedacti 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 - ctinue to report same value until the metric is aged out. zero - report metric with value 0 (if the metric type is stringevent or timestamp, acti 'same' is performed). stop - stop reporting the metric value same Example The MATCHEDPROCS example below uses processavailability plug-in to return value of 1 for each running process whose name matches the regular expressi specified by the match parameter (i.e. processes whose name starts with 'f' in this case). The metricnotreportedacti parameter value 'zero' is used to reset metric value to 0 when a process is no lger running. introscope.epagent.stateless.matchedprocs.command=perl processavailability.pl -match ^f -distinctmatch introscope.epagent.stateless.matchedprocs.delayinsecds=900 introscope.epagent.stateless.matchedprocs.metricnotreportedacti=zero Chapter 4: EPAgent Properties 103

104

105 Index < <stat> 58 A Add Stateful Plug-ins 21 Add Stateless Plug-ins 22 Agent and Process Name Settings 85 Agent Metric Aging Properties 86 Agent Name 86 Apache Log Metrics 68 apachelogreader.pl, weblogiclogreader.pl, and webspherelogreader.pl 35 Available 57 Average # Transacti Active 65 Average # Transacti 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 Transactis (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 89 ChangeDetector Cfigurati 90 Command-Line Arguments 33, 34, 35, 36, 37, 38, 40 Cfigure EPAgent Logging Optis 20 Cfigure EPAgent Properties 19 Cfigure the EPAgent for HTTP GET Input 24 Cfigure the EPAgent for Simple or XML Network Input 23 Cfiguring agent metric aging 87 Cfiguring EPAgent Plug-ins 21 Cfiguring IIS Web Server logging in IIS4.0 and IIS Cfiguring Java Class Plug-ins 23 Cfiguring the EPAgent 19 Cfiguring the EPAgent for Network Data Sources 23 Ctact 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 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 Cnecti 93 Envirment Performance Agent Installati 18 EPAgent and CA Introscope 16 EPAgent and Scripting Envirments 14 EPAgent Can Accept Input From Network Sources 15 EPAgent Can Receive Input From Processes 13 EPAgent Cfigurati 94 EPAgent Plug-in Metrics 51 EPAgent Plug-ins 33 EPAgent Events and Transacti 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_ServerCfigurati 54 ErrorCount_500_InternalServerError 54 ErrorCount_500_ServerCfigurati 70 ErrorMessage_400_BadRequest 55, 71 ErrorMessage_401_Unauthorized 55, 71 Index 105

106 ErrorMessage_403_Forbidden 55, 71 ErrorMessage_404_PageNotFound 56, 72 ErrorMessage_500_InternalServerError 56 ErrorMessage_500_ServerCfigurati 72 Extensis Directory 95 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->ProtocolVersi 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 Cfigurati File 40 iislogreader.pl 39 Installing, Cfiguring, and Using the EPAgent 13 introscope.agent.agentname 98 introscope.agent.customprocessname 97 introscope.agent.defaultprocessname 97 introscope.agent.enterprisemanager.cnectiord er 93 introscope.agent.enterprisemanager.transport.tcp.h ost.default 94 introscope.agent.extensis.directory 95 introscope.agent.metricaging.datachunk 88 introscope.agent.metricaging.heartbeatinterval 88 introscope.agent.metricaging.metricexclude.ignore introscope.agent.metricaging.numbertimeslices 89 introscope.agent.metricaging.turnon 88 introscope.agent.remoteagentcfigurati.enabled 98 introscope.changedetector.agentid 92 introscope.changedetector.enable 90 introscope.changedetector.enableepa 92 introscope.changedetector.isengardstartupwaittim einsec 91 introscope.changedetector.profile 92 introscope.changedetector.profiledir 93 introscope.changedetector.rootdir 91 introscope.changedetector.waittimebetweenrec nectinsec 91 introscope.epagent.cfig.httpserverport 95 introscope.epagent.cfig.networkdataport 94 introscope.epagent.cfig.stalledstatelessplugintim eoutinsecds 102 introscope.epagent.metricscasesensitive 89 introscope.epagent.plugins.stateful.names 99 introscope.epagent.plugins.stateless.names 100 introscope.epagent.stateful.<pluginname>.class 100 introscope.epagent.stateful.<pluginname>.comman d 99 introscope.epagent.stateless.<pluginname>.class 101 introscope.epagent.stateless.<pluginname>.comman d 101 introscope.epagent.stateless.<pluginname>.delayins ecds 101 introscope.epagent.stateless.<pluginname>.metricn otreportedacti 103 introscope.epagent.stateless.<pluginname>.schedul e 102 IntroscopeEPAgent.properties file 85 Invalid Character Replacement 51 K KB Read per Secd 66 KB Written per Secd 66 kstat.pl Envirment Performance Agent Implementati Guide

107 L LINE_FORMAT 42 LINE_FORMAT Sub-Properties 42 log4j.appender.logfile.file 96 log4j.logger.epagent 96 LOGFILE 41 LOGFILEDIR 40 Logging 95 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 Compents 29 Next Steps 22 P Page Hits For <URL> 52 PageHitCount 69 Perl Support Issues 38, 39 Plug-in Types 16 Precautis With Either Type of Custom Plug-in Format 27 Process availability metrics 58 Process Name 86 Processes 96 R Remote Cfigurati 98 Remove Stateful and Stateless Plug-ins 23 RESOURCE 41 Respse Time 57 Run EPAgent in Verbose Mode and Redirect the Output File 20 Run the EPAgent 24 Run the EPAgent UNIX 25 S ServerVersi 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 98 Stateless Plug-ins 100 SUBRESOURCE 41 Supported Plug-ins 16 T The Envirment Performance Agent Overview 13 The EPAgent Standale Installers 18 Total Page Hits 52 Total Visitors Count 52 Transacti 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 Index 107