Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
Management
This documentation, which includes embedded help systems and electronically distributed materials, (hereinafter referred to as
the Documentation) is for your informational purposes only and is subject to change or withdrawal by CA at any time.
This Documentation may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without
the prior written consent of CA. This Documentation is confidential and proprietary information of CA and may not be disclosed
by you or used for any purpose other than as may be permitted in (i) a separate agreement between you and CA governing
your use of the CA software to which the Documentation relates; or (ii) a separate confidentiality agreement between you and
CA.
Notwithstanding the foregoing, if you are a licensed user of the software product(s) addressed in the Documentation, you may
print or otherwise make available a reasonable number of copies of the Documentation for internal use by you and your
employees in connection with that software, provided that all CA copyright notices and legends are affixed to each reproduced
copy.
The right to print or otherwise make available copies of the Documentation is limited to the period during which the applicable
license for such software remains in full force and effect. Should the license terminate for any reason, it is your responsibility to
certify in writing to CA that all copies and partial copies of the Documentation have been returned to CA or destroyed.
TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION AS IS WITHOUT WARRANTY OF ANY
KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE,
DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST
INVESTMENT, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED IN ADVANCE OF THE
POSSIBILITY OF SUCH LOSS OR DAMAGE.
The use of any software product referenced in the Documentation is governed by the applicable license agreement and such
license agreement is not modified in any way by the terms of this notice.
The manufacturer of this Documentation is CA.
Provided with Restricted Rights. Use, duplication or disclosure by the United States Government is subject to the restrictions
set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section 252.227-7014(b)(3), as applicable, or
their successors.
Copyright 2012 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to
their respective companies.
CA Application Performance Management for IBM WebSphere Portal (CA APM for
IBM WebSphere Portal)
CA Application Performance Management for IBM z/OS (CA APM for IBM z/OS)
CA Application Performance Management for Oracle Databases (CA APM for Oracle
Databases)
CA Application Performance Management for Oracle Service Bus (CA APM for
Oracle Service Bus)
CA Application Performance Management for Oracle WebLogic Portal (CA APM for
Oracle WebLogic Portal)
CA Application Performance Management for Oracle WebLogic Server (CA APM for
Oracle WebLogic Server)
CA Application Performance Management for Web Servers (CA APM for Web
Servers)
CA SiteMinder
Contact CA Technologies
Contact CA Support
For your convenience, CA Technologies provides one site where you can access the
information you need for your Home Office, Small Business, and Enterprise CA
Technologies products. At http://ca.com/support, you can access the following:
Online and telephone contact information for technical assistance and customer
services
Product Documentation
CA APM documentation includes information for CA APM, CA Introscope, CA CEM, and
CA APM extensions and integrations.
You can view and search all the titles in the CA APM documentation set from the CA
APM bookshelf on the CA Support Online (CSO) website.
The following list shows the documentation specific to CA APM.
CA APM Sizing and Performance Guide Sizing, tuning, and capacity planning for
your CA APM deployment and components.
The following list shows the documentation specific to extensions and integrations.
CA APM API Reference Guide Contains data and components managed within CA
APM that is exposed to consumers with an application programming interface (API).
CA APM Catalyst Connector Guide Installing and using the Catalyst Connector for
CA APM.
CA APM for IBM CICS Transaction Gateway Guide Installing, configuring, and
using CA APM for IBM CICS Transaction Gateway.
CA APM for IBM WebSphere Application Server for Distributed Environments Guide
Installing, configuring, and using CA APM for IBM WebSphere Distributed
Environments.
CA APM for IBM WebSphere Application Server for z/OS Guide Installing,
configuring, and using CA APM for IBM WebSphere for z/OS.
CA APM for IBM WebSphere MQ Guide Using CA Introscope to view metrics from
IBM WebSphere MQ.
CA APM for IBM WebSphere Portal Guide Installing, configuring, and using CA
APM for IBM WebSphere Portal.
CA APM for IBM z/OS Guide Installing, configuring, and using CA APM for IBM
z/OS.
CA APM for Microsoft SharePoint Guide Installing and configuring CA APM for
Microsoft SharePoint to monitor your SharePoint components during development,
QA, staging, and production.
CA APM for Oracle Databases Guide Installing, configuring, and using CA APM for
Oracle Databases.
CA APM for Oracle WebLogic Portal Guide Installing, configuring, and using CA
APM for Oracle WebLogic Portal.
CA APM for Oracle WebLogic Server Guide Installing, configuring, and using CA
APM for Oracle WebLogic Server.
CA APM for Web Servers Guide Installing, configuring, and using CA APM for Web
Servers.
CA APM Integration for CA CMDB Guide Installing, configuring, and using CA APM
for CA CMDB.
CA APM Integration for CA NSM Guide Installing, configuring, and using CA APM
for CA NSM.
CA Introscope WebView User Guide for SAP This guide is for SAP WebView users.
Documentation Changes
The following documentation updates have been made since the last release of this
documentation:
The Java agent architecture has been modified to provide more efficient
correlation of traces in cross-process transactions.
The Java agent directory structure (see page 38) has been modified to enable
easier upgrades.
Administrators can remotely issue commands from the Java agent to generate
thread dumps (see page 67) as needed, directly from the Workstation user
interface.
The GC Monitor (see page 245) reports detailed information about Garbage
Collectors and Memory Pools to detect memory-related issues that could
adversely affect performance.
introscope.agent.threaddump.enable
introscope.agent.threaddump.deadlockpoller.enable
introscope.agent.threaddump.deadlockpollerinterval
introscope.agent.threaddump.MaxStackElements
introscope.agent.primary.net.interface.name
Changed properties:
introscope.agent.enterprisemanager.failbackRetryIntervalInSecondsThis
property can now specify the number of seconds between attempts by the Java
agent to reconnect to:
Documentation changes
CA APM product names have been updated to reflect the current naming
conventions.
This guide is renamed from the Introscope Java Agent Guide to the CA APM
Java Agent Implementation Guide.
Virtual agents are not agents; they are conglomerations of agent metrics,
therefore Enterprise Manager-related entities. Information about configuring
and using virtual agents has been moved to the CA APM Configuration and
Administration Guide.
Refers to
<Agent_Home>
<APM_Db_Home>
<AppServer_Home>
<EM_Home>
<ProductName_Home>
<version>
<File_Name><VersionNu
mber><Operating
System or other
identifier>.FileType
Convention
Refers to
Contents
Chapter 1: Introduction to the Java Agent
25
29
Contents 13
65
71
81
117
127
Contents 15
137
153
161
167
179
Contents 17
187
193
Contents 19
introscope.changeDetector.isengardStartupWaitTimeInSec............................................................................ 236
introscope.changeDetector.waitTimeBetweenReconnectInSec....................................................................... 236
introscope.changeDetector.profile ................................................................................................................... 237
introscope.changeDetector.profileDir .............................................................................................................. 237
introscope.changeDetector.compressEntries.enable ....................................................................................... 238
introscope.changeDetector.compressEntries.batchSize .................................................................................. 238
Cross-process tracing in WebLogic Server ............................................................................................................... 238
introscope.agent.weblogic.crossjvm ................................................................................................................. 239
Cross-process transaction trace ............................................................................................................................... 239
introscope.agent.transactiontracer.tailfilterPropagate.enable ........................................................................ 239
Dynamic instrumentation ........................................................................................................................................ 240
introscope.autoprobe.dynamicinstrument.enabled ......................................................................................... 240
autoprobe.dynamicinstrument.pollIntervalMinutes ........................................................................................ 240
introscope.autoprobe.dynamicinstrument.classFileSizeLimitInMegs .............................................................. 241
introscope.autoprobe.dynamic.limitRedefinedClassesPerBatchTo .................................................................. 241
introscope.agent.remoteagentdynamicinstrumentation.enabled ................................................................... 242
introscope.autoprobe.dynamicinstrument.pollIntervalMinutes ...................................................................... 242
ErrorDetector ........................................................................................................................................................... 243
introscope.agent.errorsnapshots.enable .......................................................................................................... 243
introscope.agent.errorsnapshots.throttle ........................................................................................................ 243
introscope.agent.errorsnapshots.ignore.<index> ............................................................................................. 244
Extensions ................................................................................................................................................................ 244
introscope.agent.extensions.directory ............................................................................................................. 244
introscope.agent.common.directory ................................................................................................................ 245
GC Monitor ............................................................................................................................................................... 245
introscope.agent.gcmonitor.enable.................................................................................................................. 245
Java NIO .................................................................................................................................................................... 246
Buffers ............................................................................................................................................................... 246
Channels ............................................................................................................................................................ 247
NIODatagramTracing metrics ............................................................................................................................ 247
Restricting Java NIO metrics ............................................................................................................................. 248
JMX ........................................................................................................................................................................... 252
introscope.agent.jmx.enable ............................................................................................................................ 252
introscope.agent.jmx.ignore.attributes ............................................................................................................ 253
introscope.agent.jmx.name.filter ..................................................................................................................... 253
introscope.agent.jmx.name.jsr77.disable ......................................................................................................... 254
introscope.agent.jmx.name.primarykeys ......................................................................................................... 255
introscope.agent.jmx.excludeStringMetrics ..................................................................................................... 256
LeakHunter ............................................................................................................................................................... 256
introscope.agent.leakhunter.collectAllocationStackTraces .............................................................................. 257
introscope.agent.leakhunter.enable ................................................................................................................. 258
introscope.agent.leakhunter.leakSensitivity..................................................................................................... 258
Contents 21
315
325
Contents 23
329
Index
331
IntroscopeAgent.profile file
2.
Configure the application server (see page 39) to instrument your applications.
3.
Configure the startup script (see page 40) or Java command for the application
server to include the agent and the location of the agent profile.
4.
Configure the agent connection (see page 57) to the Enterprise Manager.
5.
Restart the application server to instrument the application and start data
collection.
6.
Configure the IntroscopeAgent.profile (see page 65) if you want to change any
properties set during installation or want to modify data collection or other agent
operations.
2.
3.
4.
Scroll to the Product Status section and click the Application Performance
Management Compatibility Guide link.
The Application Performance Management Compatibility Guide page appears.
5.
2.
3.
4.
Verify that you have a supported version of the JVM. If you are unable to use a
supported version, use a previous version:
Verify that the Introscope Enterprise Manager and Workstation components are
installed. Note the host name and port number for the Enterprise Manager
connection with the agent.
You can use ping or telnet to verify connectivity between the agent and the
Enterprise Manager.
Note: For information about installing the Enterprise Manager, Workstation, and
WebView components, see the CA APM Installation and Upgrade Guide.
More information:
View the Product Compatibility Guide (see page 29)
Planning a Java Agent Deployment (see page 26)
Deploying the Java Agent (see page 28)
In most cases, you use the interactive installer when you want to install files locally on a
computer. If you install interactively, the prompts displayed are the same for the
graphical or text-based interface. However, the option to choose the GUI or text-based
installer depends on the operating system of the computer where you run the installer.
For example, most UNIX environments support the GUI or text-based console installer,
but start the console installer by default.
2.
Select the installation archive appropriate for your operating system. For example:
Extract the installation archive files using a command appropriate to your operating
system. For example, on UNIX or Linux:
tar xvf IntroscopeAgentInstaller<version>unix.tar
3.
4.
5.
Select the application server type from the list of valid application servers:
Default
JBoss
Tomcat
WebLogic
WebSphere
Sun ONE
Interstage
The application server you select determines the additional monitoring options
available.
6.
Specify the root installation directory for the Java agent. In most cases, use the
application server root directory.
Within the root installation directory, the installer creates the wily directory that
is the <Agent_Home> directory.
7.
Specify whether you want to create an agent profile or use an existing agent profile.
If you create an agent profile, you are prompted to select:
If you select an existing profile, you are prompted for the location of the file. Specify
the fully qualified path to the file.
The settings you specify can be changed after installation if needed, by editing the
IntroscopeAgent.profile file.
8.
Specify the path to the Java executable that is used to launch your application
server.
9.
For example, an installation done April 30, 2005 at 7:10:05 a.m. would have an
automatically generated response file with this name:
autogenerated.responsefile.2005.4.30.7.10.05
You can use this automatically generated response file for subsequent silent
installations with the same settings or edit it to use new settings.
The sample response file provides default settings for most properties, but you must
manually edit the file before you can use it for silent installation.
2.
appServer=Default
Specifies the type of application server to monitor. Valid values are Default,
JBoss, Tomcat, WebLogic, WebSphere, Sun, Oracle, or Interstage. The value is
case-sensitive.
This setting controls the ProbeBuilder Directives (PBDs) that are installed with
the agent and which additional monitoring options are valid.
(Optional) appServerHome=
Specifies the home directory of the application server. This property is not
needed if you have set the USER_INSTALL_DIR property to the application
server root directory.
(Optional) appServerJavaExecutable=
Specifies the path to the Java executable that is used to launch the application
server.
instrumentationLevel=Typical
Specifies whether you want to use Full or Typical instrumentation. The value is
case-sensitive.
agentName=Default Agent
Specifies the agent name that should be displayed in the Workstation.
processName=Default Process
Specifies the process name that should be displayed in the Workstation.
emHost=localhost
Specifies the host name of the computer running the Enterprise Manager that
the agent should connect to by default.
emPort=5001
Specifies the port number the agent should use to connect to its Enterprise
Manager.
(Optional) alternateAgentProfile=
Specifies the absolute path to an existing agent profile.
(Optional) pickupFolder=
Specifies the absolute path to a "pickup folder" that contains .zip or .tar files for
any add-ons you want to install with the agent.
(Optional) changeDetectorEnable=false
Specifies whether to enable the ChangeDetector agent extension. If you set this
property to false, ChangeDetector files are installed but not enabled. You may
enable it later.
(Optional) changeDetectorAgentID=
Specifies a name for the ChangeDetector agent extension. If you enable
ChangeDetector, uncomment and set this property.
(Optional) shouldEnable*
Specifies which additional CA APM monitoring solutions you want to enable. All
of the properties for optional CA APM monitoring solutions are set to false by
default. The options that are valid to enable depend on the application server
type.
3.
4.
Invoke the installer in silent mode by specifying the path to the installer executable
and the absolute path to the response file.
<path_to_installer> -f <absolute_path_to_response-file>
The command you use to invoke the installer depends on the operating system
where you are running the command.
For example, on Windows, the command format looks like this:
IntroscopeAgent<version>windows.exe -f C:\temp\myResponseFile.txt
Select the appropriate installation archive for your application server and operating
system.
2.
Extract the contents of the archive into a location your JVM can access using a
command appropriate to your operating system. For example, on UNIX or Linux:
tar -xvf
3.
IntroscopeAgentFilesOnly-NoInstaller<version><app_server>.<os>.tar
4.
5.
Configure the application server with the location of the Java agent startup file and
the agent profile.
6.
config
Contains the IntroscopeAgent.profile, ProbeBuilder Directive files (.pbd), and
ProbeBuilder List files (.pbl) files that control agent operations, metric data
collection, and the instrumentation process. The specific properties defined in
the IntroscopeAgent.profile and the .pbd and .pbl files that are deployed and
referenced in the agent profile depend on choices you made during
installation.
Within the config directory, the hotdeploy subdirectory enables you to deploy
new directives without editing the IntroscopeAgent.profile or restarting
applications. If files placed in the hotdeploy directory contain invalid syntax or
collect too many metrics, instrumentation can fail or application performance
can suffer.
ext
Contains the files for enabled agent extensions or features. For example, the
directory contains files for the application triage map, and LeakHunter.
connectors
Contains the CreateAutoProbeConnector.jar utility that is used to configure an
AutoProbe Connector to enable instrumentation in certain environments.
common
Contains the configuration and property files for the extensions.
examples
Contains folders and files for optional agent extensions, such as CA APM for
SOA. If you did not enable an extension at installation, you can use the files in
this directory to configure the extension at a later time.
install
Contains log files that record the installation process and the files you can use
for silent installation. For example, the generated response file and the
SampleResponseFile.Agent.txt file are located in this directory.
This directory is not created if you manually install the Java agent from an
installation archive.
logs
Stores agent log files.
tools
Contains the URLGrouper.jar command line utility that analyzes web server log
files.
This directory also includes the list of the files of extensions. For example,
configurePMI.bat, CreateIU.jar, listServers.bat, MergeUtility.jar,
NetInterface.jar, and setPmiModules.jacl files are located in this directory.
UninstallerData
Contains a subdirectory with the executables and associated resources used to
uninstall the agent and related resources.
This directory is not created if you manually install the Java agent from an
installation archive.
version
Contains version information for optional CA APM monitoring solutions. This
information is installed regardless of what you enable at installation time.
Navigate to the directory that has the Tomcat startup script. For example:
cd /apache-tomcat-6.0.18/bin
2.
3.
Locate the command line for setting Java options and add the following
command-line options to specify the path to the agent's startup .jar file and the
agent profile:
-javaagent:<PathToAgentJar>
-Dcom.wily.introscope.agentProfile=<PathToAgentProfile>
For example, if using Agent.jar, add code similar to the following before the
command that starts the server:
set JAVA_OPTS=%JAVA_OPTS% -javaagent:c:\apache-root\wily\Agent.jar
-Dcom.wily.introscope.agentProfile=
c:\apache-root\wily\core\config\IntroscopeAgent.profile
4.
5.
tomcat41x.pbd
tomcat50x.pbd
tomcat55x.pbd
Navigate to the directory that has the JBoss startup script. For example:
cd /jboss-4.2.3.GA/bin
2.
3.
Locate the command line for setting Java options and add the following
command-line options to specify the path to the agent's startup .jar file and the
path to the agent profile:
-javaagent:<PathToAgentJar>
-Dcom.wily.introscope.agentProfile=<PathToAgentProfile>
4.
For example, if using Agent.jar, add code similar to the following before the
command that starts the server:
set JAVA_OPTS= -javaagent:%JBOSS_HOME%\wily\Agent.jar
-Dcom.wily.introscope.agentProfile=%JBOSS_HOME%\wily\core\config\IntroscopeAg
ent.profile %JAVA_OPTS%
5.
6.
(Optional) If you want to enable the reporting of JBoss JMX metrics, you must
configure the agent profile to collect JMX metrics by opening the
IntroscopeAgent.profile and setting the following property:
introscope.agent.jmx.enable=true
Note: If you want to see JMX metrics from JBoss in a JConsole by using the JMX
remote management server with a platform-specific MBeanServer, you should add
com.wily.use.platform.mbeanserver=true to the IntroscopeAgent.profile. This
reflects a change from previous versions of Introscope where the use of the
platform-specific MBeanServer was set in the command line.
7.
jboss4x.pbd
jsf.pbd
jsf-toggles-full.pbd
jsf-toggles-typical.pbd
jboss-full.pbl
jboss-typical.pbl
Navigate to the directory that has the WebLogic startup script you want to modify.
For example:
cd $WL_HOME/samples/domain/wl_server
2.
3.
Locate the command line for setting Java options or the Java command line and add
the following command-line options. For example: -javaagent:<PathToAgentJar>
-Dcom.wily.introscope.agentProfile=<PathToAgentProfile>
4.
Save and close the WebLogic startup script or application-specific startup script.
2.
3.
4.
5.
6.
7.
Click Create.
The Target and Deploy tab appears.
8.
Select the boxes for the servers you want to make this startup class available to.
9.
Click Apply and select the Run before application deployments option.
10. Add the location of the WebAppSupport.jar to the <server or application server>
startup classpath.
11. Restart the application server.
Create a startup class as described in Creating a startup class for WebLogic (see
page 42).
2.
3.
4.
5.
Introscope polls only RuntimeServiceMBean for metrics because it supports local access
(an efficiency issue), and because it contains most of the data expected to be relevant.
However, Introscope can support any MBean built to the Sun JMX specification. For
more information on the Sun JMX specification, see
http://java.sun.com/products/JavaManagement/.
To support the collection of JMX metrics, the following keywords are defined and
enabled by default in the IntroscopeAgent.profile file for WebLogic:
ActiveConnectionsCurrentCount
WaitingForConnectionCurrentCount
PendingRequestCurrentCount
ExecuteThreadCurrentIdleCount
OpenSessionsCurrentCount
For more information see Enabling JMX Reporting (see page 179).
Introscope displays the JMX metrics it collects in the Investigator tree under the
following node:
<Domain>|<Host>|<Process>|AgentName|JMX|
Install CA APM for Oracle WebLogic using the instructions in the CA APM for Oracle
WebLogic Server Guide.
2.
Enable the CA APM for Oracle Databases option using the CA APM for Oracle
Databases Guide.
3.
Information in the Data Accessors is defined by a domain name and one or more
key/value pairs. Introscope converts Data Accessor Columns into key and value
information displayed in alphabetical order in the Introscope-generated metrics. The
following example shows the syntax used:
<Domain>|<Host>|<Process>|AgentName|WLDF|<domain
name>|<key1>=<value1>|<key2>=<value2>:<metric>
For example, this table shows the information for the BYTECOUNT Column from the
HTTPAccessLog Data Accessor:
Domain name
Key/Value pairs
Metric names
WebLogic
Name=HTTPAccessLog,
Type=WLDFDataAccessRuntime=Accessor,
BYTECOUNT
WLDFRuntime=WLDFRuntime
The Data Accessor information in the table above would be converted to the following
Introscope metric:
<Domain>|<Host>|<Process>|AgentName|WLDF|Weblogic|Name=HTTPAccessLog
|Type=WLDFDataAccessRuntime=Accessor|WLDFRuntime=WLDFRuntime:BYTECOUNT
Note that the key/value pairs are displayed alphabetically in the Introscope metric.
2.
3.
4.
5.
If you are using an older version of WebLogic or JRockit JVM, create and run an
AutoProbe connector file (see page 319) to instrument applications.
2.
Turn on the Managed Socket option to trace socket metrics. For example:
#######################
# Network Configuration
# ================
#TurnOn: SocketTracing
# NOTE: Only one of SocketTracing and ManagedSocketTracing should be 'on'.
ManagedSocketTracing is provided to
# enable pre 9.0 socket tracing.
TurnOn: ManagedSocketTracing
TurnOn: UDPTracing
3.
WebSphere Application Server 6.1 - UNIX, Windows, OS/400, z/OS - IBM JVM 1.5
The CA Introscope dynamic instrumentation feature requires class redefinition support.
Use of class redefinition can significantly impact performance when running on IBM JDK
version 5. IBM has provided technical information about this performance overhead in
the Java Diagnostics Guide.
CA Introscope and IBM JDK version 5 customers that would like to take advantage of
dynamic instrumentation should keep this performance overhead in mind. When
employing this configuration, CA Technologies recommends using the dynamic
instrumentation feature only in a QA environment.
For more information about dynamic instrumentation, see Dynamic ProbeBuilding vs.
dynamic instrumentation (see page 75).
When you are running WebSphere 6.1 using an IBM JVM 1.5, use the alternate versions
of the Java agent .jar file and Java agent profile. These files, named AgentNoRedef.jar
and IntroscopeAgent.NoRedef.profile, are located in the <Agent_Home>/core/config
directory.
Note: If you are using the AllAppServer agent distribution, the alternate profile is named
IntroscopeAgent.websphere.NoRedef.profile.
As a result of using the previous files and syntax, metrics are no longer reported for the
following:
System classes
SSL
Changes to PBD files require that you restart the instrumented JVM before being
applied
When using the previous files and syntax, the agent reports class redefinition status by
the following actions:
Adding a metric named Agent Class Redefinition Enabled under the agent node in
the Investigator. Metric values are true or false.
When class redefinition is enabled, the log message is written at the WARN
level and reads:
Introscope Agent Class Redefinition is enabled. Enabling class redefinition
on IBM 1.5 JVMs is known to incur significant overhead.
When class redefinition is disabled, the log message is written at INFO level and
reads:
Introscope Agent Class Redefinition is disabled.
Writing a message to standard error (only when class redefinition is enabled), which
reads:
Warning: Introscope agent has been configured to support class redefinition.
IBM JVMs version 1.5 and higher are known to incur significant overhead with
redefinition enabled. To avoid this overhead please use AgentNoRedef.jar
instead of Agent.jar.
If you use a non-IBM JVM or an IBM JVM that is a version other than 1.5, the previous
metric and messages are not output.
To modify the WebSphere Application Server 6.1 - UNIX, Windows, OS/400, z/OS IBM JVM 1.5 to use the agent
1.
2.
Navigate to Application Servers > your server > Server Infrastructure > Java and
Process Management > Process Definition > Java Virtual Machine.
3.
WebSphere Application Server 6.1 - UNIX, Windows - Sun, HP, Other JVM 1.5
If you use a non-IBM JVM or an IBM JVM that is a version other than 1.5, not all metrics
and messages are output.
The following examples indicate which Java argument and .jar file to use with a specific
JVM when installing the Java Agent on WebSphere 6.1.
To modify the WebSphere Application Server 6.1 - UNIX, Windows - Sun, HP, all other
JVM 1.5 to use the agent
1.
2.
Navigate to Application Servers > your server > Server Infrastructure > Java and
Process Management > Process Definition > Java Virtual Machine.
3.
4.
WebSphere Application Server 7.0 - UNIX, Windows, OS/400 - JVM 1.5 or later
If you are monitoring WebSphere 7.0, verify you have build 7.0.0.8 or later installed
before configuring the server to start the Java agent.
To modify WebSphere Application Server 7.0 to use the agent
1.
2.
Navigate to Application Servers > your server > Server Infrastructure > Java and
Process Management > Process Definition > Java Virtual Machine.
3.
4.
2.
Navigate to Application Servers > your server > Server Infrastructure > Java and
Process Management > Process Definition > Java Virtual Machine.
3.
4.
2.
Note: Line breaks are shown for user readability and are not needed when adding
the permissions to the server.policy file.
3.
2.
Select the server you'd like to configure, then navigate to Server Infrastructure >
Administration > Custom Services.
3.
4.
5.
6.
7.
Click OK.
8.
2.
3.
After you have enabled PMI data collection in WebSphere, the PMI data can be
displayed as Introscope metrics. You can filter which metric categories to bring into
Introscope, depending on your needs.
Note: For WebSphere on z/OS. CA Technologies recommends you us CA APM for
WebSphere z/OS. CA APM for WebSphere z/OS provides WebSphere-specific PBDs and
metrics that use low overhead tracer technology to retrieve WebSphere-specific
metrics. CA APM for WebSphere z/OS does not require you to enable PMI in WebSphere
for z/OS. You can also enable PMI reporting in WebSphere for z/OS, but this approach
consumes more system resources.
2.
3.
4.
6.
After youve enabled PMI collections in Introscope, available PMI metrics are displayed
under the WebSpherePMI node in the Investigator tree.
2.
3.
Select the server you want to use for reporting, such as server1.
4.
5.
6.
Select JDBC Connection Pools on the tree, and enable WaitingThreadCount on the
right pane.
7.
Select ThreadPools on the tree, and enable ActiveCount on the right pane.
8.
Note: For more information about the Resource Metric Map data, see the CA APM
Configuration and Administration Guide.
2.
3.
4.
5.
2.
3.
2.
The value is in milliseconds, so the default delay in this example is 100 seconds.
3.
2.
Locate the section in the opmn.xml file for the application you want to instrument.
You will most likely want to instrument more than one application at this time.
3.
4.
Insert the following at the end of the java-options line, before the end "/> using the
appropriate path for your environment:
-javaagent:<PathToAgentJar>
-Dcom.wily.introscope.agentProfile=<PathToAgentProfile>
For example, the entire entry for one application would be on one line:
<data id="java-options" value="-server -XX:MaxPermSize=128M -ms512M -mx1024M
-XX:AppendRatio=3
-Djava.security.policy=$ORACLE_HOME/j2ee/home/config/java2.policy
-Djava.awt.headless=true -Dhttp.webdir.enable=false
-javaagent:$ORACLE_HOME/wily/Agent.jar
-Dcom.wily.introscope.agentProfile=$ORACLE_HOME/wily/core/config/IntroscopeAg
ent.profile/>
2.
Add the full path for the Agent.jar file and the IntroscopeAgent.profile as
jvm-options to the java-config element in the domain.xml file. For example:
<java-config ..........>
<jvm-options>-javaagent:/sw/wily/Agent.jar</jvm-options>
<jvm-options>-Dcom.wily.introscope.agentProfile=/sw/wily/core/config/Introsco
peAgent.profile</jvm-options>
.....>
3.
4.
2.
3.
4.
5.
Click the Additional tab and create a new parameter, for example:
name: -javaagent:<Agent_Home>\Agent.jar
value: <leave empty>
6.
7.
8.
To verify that the changes made with the Configtool were made, open the following
file:
<drive>:\usr\sap\...\j2ee\cluster\instance.properties
9.
2.
If you use a cluster with more than one Enterprise Manager, be sure to specify a
Collector Enterprise Manager.
3.
4.
5.
(Optional) Specify one or more backup Enterprise Managers for the agent to
connect to, if the connection to the primary Enterprise Manager is lost.
6.
2.
3.
5.
2.
3.
4.
(Optional) If the proxy server requires user credentials for authentication, set the
following additional properties:
introscope.agent.enterprisemanager.transport.http.proxy.username=<user_name>
introscope.agent.enterprisemanager.transport.http.proxy.password=<user_passwo
rd>
5.
2.
3.
4.
5.
2.
Configure the agent to connect to the Enterprise Managers SSL listening port using
an SSL socket factory.
3.
4.
5.
6.
If the agent needs to authenticate the Enterprise Manager, uncomment and set the
introscope.agent.enterprisemanager.transport.tcp.truststore.DEFAULT property to
the location of the truststore containing the Enterprise Managers certificate. If you
do not specify a truststore, the agent trusts all certificates.You can specify an
absolute path or a path relative to the agent profile. For example:
introscope.agent.enterprisemanager.transport.tcp.truststore.DEFAULT=/certs
7.
8.
9.
IntroscopeAgentFiles-NoInstaller<version>allappserver.windows.zip
IntroscopeAgentFiles-NoInstaller<version>allappserver.unix.tar
IntroscopeAgentFiles-NoInstaller<version>allappserver.zOS.tar
IntroscopeAgentFiles-NoInstaller<version>allappserver.os400.zip
Note: In these file names, <version> refers to the current release number of the Java
agent.
Each package contains:
All application server agent profiles, with the application server name embedded in
the file name. For example:
IntroscopeAgent.weblogic.profile
IntroscopeAgent.websphere.profile
The default IntroscopeAgent.profile is not been included. See step 3 for more
information.
All agent .jars and platform monitors suitable for the operating system type
2.
Extract the selected agent package into the application servers home directory.
Follow the manual installation instructions for Java agent installation. For more
information, see Install manually using installation archives (see page 37).
Note: The extra PBDs and PBLs in the <Agent_Home>/core/config directory that
refer to application servers you are not using can be safely ignored.
3.
2.
Open the application server startup script and remove the Java agent switches from
the Java command line. Depending on the application server, the startup options
include the following:
-Xbootclasspath
-javaagent:<path_to_the_agent_jar>
-Dcom.wily.introscope.agentProfile=<path_to_the_agent_profile>
3.
4.
5.
The most common way for the agent to connect to the Enterprise Manager is through a
direct socket connection. CA Technologies recommends using a direct socket connection
to the Enterprise Manager, if possible. If you want to use a different type of connection,
see the appropriate section.
2.
Replace NAME with an identifier for the new Enterprise Manager channel. Do not
use DEFAULT or the name of an existing channel when creating a new channel. For
example to create two backup Enterprise Managers:
introscope.agent.enterprisemanager.transport.tcp.host.BackupEM1=paris
introscope.agent.enterprisemanager.transport.tcp.port.BackupEM1=5001
Introscope.agent.enterprisemanager.transport.tcp.socketfactory.BackupEM1=com.
custom.postofficehub.link.net.DefaultSocketFactory
introscope.agent.enterprisemanager.transport.tcp.host.BackupEM2=voyager
introscope.agent.enterprisemanager.transport.tcp.port.BackupEM2=5002
introscope.agent.enterprisemanager.transport.tcp.socketfactory.BackupEM2=com.
wily.isengard.postofficehub.link.net.DefaultSocketFactory
3.
4.
5.
6.
2.
3.
4.
For CA Introscope users to view the Deadlock Count metric, configure the
IntroscopeAgent.profile. You can perform additional configuration to display agent
Thread node metrics.
To enable Deadlock Count metric collection
1.
2.
Set this property to true to enable the Deadlock Count metric to be collected.
introscope.agent.threaddump.deadlockpoller.enable=true
3.
(Optional) Set the full version of the PBL to display metrics in the agent Threads
node.
User can see metrics such as Active Threads counts and thread groups under
AgentName | Threads.
4.
2.
(Optional) Set this property to save thread dump files to a specific directory on the
Enterprise Manager. For example, TestThreadDumps.
introscope.enterprisemanager.threaddump.storage.dir=TestThreadDumps
3.
(Optional) Set this property to purge thread dump files older than a specified
number of days. For example, older than 30 days.
introscope.enterprisemanager.threaddump.storage.clean.disk.olderthan.days=30
4.
(Optional) Set this property to purge thread dump files after a specified number of
days. For example, after every two days.
introscope.enterprisemanager.threaddump.storage.clean.disk.freq.days=2
5.
(Optional) Set this property to limit the maximum number of thread dump files that
can be stored on the Enterprise Manager. For example, 5000 files.
introscope.enterprisemanager.threaddump.storage.max.disk.usage=5000
Note: If:
* the number of thread dump files stored exceeds the limit set in the
introscope.enterprisemanager.threaddump.storage.max.disk.usage property
and
* there are no files older than the number of days set in the
introscope.enterprisemanager.threaddump.storage.clean.disk.olderthan.days
property
Then the Enterprise Manager does not store any thread dump files.
6.
7.
If an Enterprise Manager goes down, you can copy thread dump files to another
Enterprise Manager so users can view thread dump data.
Important! Restart the Enterprise Manager when you add files to or remove files from
the thread dump directory. CA Technologies does not recommend moving thread dump
files from one Enterprise Manager to another.
To copy thread dump files from one Enterprise Manager to another
1.
2.
3.
4.
5.
If needed, establish the agent connection and enable and configure thread dumps
on EM2.
EM2 users can select the agent node then click the Load Previous button in Thread
Dumps tab. A list displays the thread dumps moved from EM1.
Configuring ProbeBuilding
Configuring ProbeBuilding
The instrumenting process is performed using ProbeBuilding technology, in which
probes defined in ProbeBuilder Directive (PBD) files identify the metrics an agent will
gather from web applications and virtual machines at run-time.
By default, AutoProbe will use the typical PBD set provided with the Java agent, which
results in the collection of a moderate number of metrics. The following sections have
instructions on how to customize the metric collection level and how to configure
optional ProbeBuilding behaviors.
Configuring ProbeBuilding
2.
3.
Specify the name of the PBL file you want to use in this property:
introscope.autoprobe.directivesFile.
For example, to use the Full version of the standard PBL for WebLogic Server, set
the property to:
introscope.autoprobe.directivesFile=weblogic-full.pbl
4.
Dynamic ProbeBuilding
Introscope uses dynamic ProbeBuilding to implement new and changed PBDs without
restarting managed applications or the agent itself. Dynamic ProbeBuilding is useful for
making corrections to PBDs, or to change data collection levels during triage without
interrupting application service.
Important! Dynamic ProbeBuilding is only available for use with Java 1.5 or higher.
Dynamic ProbeBuilding is dependent on Java 1.5 capabilities, so previous versions of
Java are not able to use this Introscope function. Dynamic ProbeBuilding is also
dependent on the -javaagent command.
Note: The Introscope Workstation allows you to perform dynamic instrumentation
through the Transaction Trace viewer. For more information, see the CA APM
Workstation User Guide.
When dynamic ProbeBuilding is enabled, Introscope periodically checks for new and
changed PBDs. To minimize overhead, Introscope selectively re-instruments classes
affected by the modified PBDs. To improve performance, the scope of dynamic agent
re-instrumentation is limited to reloading only those classes whose instrumentation has
changed when PBDs were edited.
When a PBD is edited or added to the hotdeploy directory, only user directives (such as
adding or removing directives for a class, or toggling tracer groups) are re-instrumented.
System directives (such as adding a tracer or changing a new tracer mapping) are not
re-instrumented. Arrays, interfaces, and classes specified in Skip directives are not
re-instrumented, as well as any transformations. In addition, you can exclude all classes
loaded by particular classloaders from the re-instrumentation process and limit the
scope of the re-instrumentation process to specific class packages.
Note: Dynamic ProbeBuilding is not enabled by default.
Configuring ProbeBuilding
If a class is re-instrumented so that it no longer reports data for a metric, the metric is
still displayed in the Introscope Investigator. Existing metrics do not disappear from the
Investigator window if their classes are re-instrumented.
Important! Due to a limitation in Java 1.5, access to some class bytes is not available,
with the following effects:
Modifications to the j2ee.pbd file may not be picked up, and metrics may continue
to be published under old names.
Some exceptions may appear in the agent log.
To avoid this issue, restart the application server after modifying the j2ee.pbd file.
When configuring dynamic ProbeBuilding, CA Technologies recommends that you base
your changes on tracer groups. For example, if you want to control the level of
instrumentation for the tracer group XYZ, you should create two tracer groups:
Once these two tracer groups have been created, you can toggle between them, turning
off XYZTracing and turning on XYZTracingLite. By toggling between the two tracer
groups, you can view the impact that dynamic ProbeBuilding has on your environmental
performance and adjust the tracing groups accordingly. This would affect all classes
being traced as part of each tracer group.
Important! Changes to directives not using tracer groups are not supported. For
example, changes in any directive like TraceAllMethods that does not have an IfFlagged
switch are not supported. However, Introscope does not ship any out of the box
directives without tracer groups or flags. Changes to skips or transformations are also
not supported.
To configure dynamic ProbeBuilding
1.
2.
3.
introscope.autoprobe.dynamicinstrument.enabled=true
This property enables dynamic ProbeBuilding. You must restart the managed
application before changes to this property take effect.
introscope.autoprobe.dynamicinstrument.pollIntervalMinutes=1
The polling interval in minutes to check for PBD changes. The default is set to
one minute intervals. You must restart the managed application before
changes to this property take effect.
Configuring ProbeBuilding
introscope.autoprobe.dynamicinstrument.classFileSizeLimitInMegs=1
Some classloader implementations have been observed to return huge class
files. This is to prevent memory errors. You must restart the managed
application before changes to this property take effect.
introscope.autoprobe.dynamic.limitRedefinedClassesPerBatchTo=10
Re-defining too many classes at a time might be very CPU intensive. In cases
where the changes in PBDs trigger a re-definition of a large number of classes,
this property attempts to batch the process at a comfortable rate.
4.
5.
Configuring ProbeBuilding
Note: There is no performance overhead with the use of class redefinition when using
Introscope with IBM JDK version 6.
2.
3.
4.
Configuring ProbeBuilding
In addition, Introscope 9.0 also supports the instrumentation of methods through a call
to subclasses by using the Introscope API getMethodCalls. When used, getMethodCalls
allows you to better understand the consequences of instrumentation of inherited
methods or interface methods by providing the following information:
A new tracer to instrument interfaces and abstract methods is available with the 9.0
Java Agent, using the following syntax:
TraceOneMethodWithlabelIfInherits: <class> <method> <Label> <Tracer Group> <Tracer
Type> <Resource>
Configuring ProbeBuilding
2.
3.
To change the frequency with which Introscope polls for uninstrumented subclasses
from its default value of 5, uncomment this property and set it to the desired
polling frequency:
introscope.autoprobe.hierarchysupport.pollIntervalMinutes
4.
Optionally, you can limit the number of times Introscope polls uninstrumented
subclasses by uncommenting this property and setting it to the desired limit:
introscope.autoprobe.hierarchysupport.executionCount
Configuring ProbeBuilding
You must restart the managed application before changes to these properties take
effect.
Define this system property on the Java command line with the -D option:
com.wily.probebuilder.removeLineNumbers=true
Important! PBDs and PBLs only support ASCII characters. Placing other characters (such
as Unicode characters) in PBDs or PBLs could result in problems with AutoProbe.
When you install the Java agent and you are using Introscope AutoProbe, the relevant
PBD and PBL files for your specific application server are included. These files are
located in the <Agent_Home>\wily\core\config directory.
More information:
Default PBD Files (see page 83)
Default PBL files (see page 86)
Creating custom tracers (see page 102)
Oracle JDBC
Struts
Servlets
Network Sockets
File Systems
Threads
System Logs
Occasionally, too many Java classes are selected for monitoring in a ProbeBuilder
Directive (PBD) file, causing the Java agent to start incorrectly, or to experience a
"hang". If this happens, use the AutoProbe.log file to identify the classes that caused the
Java agent to hang and add a skip directive to the PBD file, skipping the classes that may
have caused the problem. For more information about adding skip directives to your
custom PBD files, see Skip directives (see page 73).
jsf.pbd
Provides tracer groups for Java Server Face (JSF) components.
jsf-toggles-full.pbd
Provides on/off switches in the form of TurnOn directives for the tracing provided in
the jsf.pbd. Most tracer groups are turned on.
jsf-toggles-typical.pbd
Provides on/off switches in the form of TurnOn directives for the tracing provided in
the jsf.pbd.
jvm.pbd
Provides directives which implement support for various Java Virtual Machines. You
use this property with the Introscope default files.
leakhunter.pbd
Provides instrumentation settings for CA APM LeakHunter, a leak detection utility.
Typically, you do not modify the contents of this file.
oraclejdbc.pbd
Provides tracer groups for Oracle JDBC components. Comment or uncomment the
TurnOn directives to alter the set of Oracle JDBC components that are traced.
ServletHeaderDecorator.pbd
Enables the servlet header decorator, which is part of the integration with CA CEM.
smwebagentext.pbd
Provides tracers for the SiteMinder Web Agent Introscope plug-in.
soaagent.pbd
Provides tracers for TransactionMinder Agent, part of the CA SOA Security Manager
(SOA Agent for Web Server and Application Server).
spm-correlation.pbd
Provides directives that control the correlation of transaction traces across
components. This file is required to enable cross-process transaction tracing when
you use CA APM for SOA.
struts.pbd
Provides directives which monitor Apache struts. Use this property with the
Introscope default files.
summary-metrics-6.1.pbd
Provides directives necessary for JSP tracing, Servlet tracing, and EJB tracing in
pre-7.0 Introscope instances.
taglibs.pbd
Provides directives that monitor classes that should be traced as JSP tag libraries,
Jakarta I/O libraries, and DGTags tag libraries.
TIBCO pbd
The Java agent is installed with several PBDs related to monitoring TIBCO through
the SOA extension.
Note: For more information, see the CA APM for SOA Implementation Guide.
toggles-full.pbd
Provides on/off switches in the form of TurnOn directives for the tracing provided in
other directives files. Most tracer groups are turned on.
toggles-typical.pbd
Provides on/off switches in the form of TurnOn directives for the tracing provided in
other directives files. Only a small section of tracer groups is turned on.
webMethods pbds
The Java agent is installed with several PBDs related to monitoring webMethods
through the CA APM for webMethods Broker.
Note: For more information, see the CA APM for SOA Implementation Guide.
WebSphere MQ pbds
The Java agent is installed with several PBDs related to monitoring WebSphere MQ
connectors and messaging system through the CA APM for IBM WebSphere MQ.
Note: For more information, see the CA APM for IBM WebSphere MQ Guide.
The Java agent also installs application server-specific PBDs, which vary depending on
the application server you are monitoring.
More information:
Default tracer groups and toggles files (see page 86)
Turning tracer groups on or off (see page 95)
Tracer groups are modified in the toggles-full.pbd and the toggles-typical.pbd files,
which are referred to by the default-full.pbl and default-typical.pbl files. This table lists
default tracer groups and their default configurations:
AgentInitialization
Agent Initialization Configuration
Full: on
Typical: on
ApacheStandardSessionTracing
HTTP Session Configuration
Full: on
Typical: on
AuthenticationTracing
Authentication Configuration
Full: on
Typical: on
CorbaTracing
CORBA method invocations
Full: on
Typical: on
DBCPTracing
DBCP Configuration
Full: on
Typical: on
DBCPv55Tracing
DBCP Configuration
Full: on
Typical: on
EJB2StubTracing
EJB 2.0 Configuration
Full: on
Typical: on
EJB3StubTracing
EJB 3.0 Configuration
Full: on
Typical: on
EntityBean3Tracing
Entity EJB 3.0 method invocations
Full: on
Typical: on
EntityBeanTracing
Entity EJB method invocations
Full: on
Typical: on
HTTPServletTracing
HTTP servlet service responses
Full: on
Typical: on
If you are using Application Server AutoProbe, turn on this tracer group:
HTTPAppServerAutoProbeServletTracing.
InstanceCounts
Counts number of instances of object type identified with tracer group.
Full: on
Typical: on
Nothing will be traced until classes are identified with this tracer group.
J2eeConnectorTracing
J2EE connector information
Full: on
Typical: on
JavaMailTransportTracing
Mail sending times
Full: on
Typical: on
JDBCQueryTracing
JDBC queries
Full: on
Typical: on
JDBCUpdateTracing
JDBC updates
Full: on
Typical: on
JMSConsumerTracing
JMS message processing times
Full: on
Typical: on
JMSListenerTracing
JMS message processing times
Full: on
Typical: on
JMSPublisherTracing
JMS message broadcast times
Full: on
Typical: on
JMSSenderTracing
JMS message broadcast times
Full: on
Typical: on
JSPTracing
JSP service responses
Full: on
Typical: on
MessageDrivenBean3Tracing
Message-driven EJB 3.0 method invocations
Full: on
Typical: on
MessageDrivenBeanTracing
Message-driven EJB method invocations
Full: on
Typical: on
NIOSocketTracing
Generates a set of metrics for each socket connection under the
NIO|Channels|Sockets node, with additional metrics under the Backends node.
Full: on
Typical: on
NIOSocketSummaryTracing
Generates a single set of metrics covering all NIO socket connections
Full: on
Typical: on
Included in these metrics are connections that were excluded from
NIOSocketTracing metrics by agent properties, as well as some internal NIO sockets
which are always excluded from NIOSocketTracing metrics.
NIODatagramTracing
Generates a set of metrics for each datagram "connection".
Full: on
Typical: on
See NIODatagramTracing metrics on page 269 for more information.
NIODatagramSummaryTracing
Generates a single set of metrics measuring all NIO datagram activity.
Full: on
Typical: on
Included in these metrics are connections that were excluded from
NIODatagramTracing metrics by agent properties, as well as some internal NIO
sockets which are always excluded from NIODatagramTracing metrics.
PersistentSessionTracing
HTTP session configuration
Full: on
Typical: on
RMIClientTracing
RMI client method invocations
Full: on
Typical: on
RMIServerTracing
RMI server method invocations
Full: on
Typical: on
ServerInfoTracing
Server info configuration
Full: on
Typical: on
SessionBean3Tracing
Session EJB 3.0 method invocations
Full: on
Typical: on
SessionBeanTracing
Session EJB method invocations
Full: on
Typical: on
SocketTracing
Network socket bandwidth as well as SSL tracking
Full: on
Typical: on
StrutsTracing
Execution times of actions in the Struts framework
Full: on
Typical: on
SuperpagesSessionTracing
HTTP Session Configuration
Full: on
Typical: on
ThreadPoolTracing
Thread Pool Configuration
Full: on
Typical: on
UDPTracing
User Datagram Protocol (UDP) socket bandwidth
Full: on
Typical: on
UnformattedSessionTracing
HTTP Session Configuration
Full: on
Typical: on
EJB3MethodLevelTracing
EJB 3.0 activity at method level
Full: on
Typical: off
EJBMethodLevelTracing
EJB activity at method level
Full: on
Typical: off
FileSystemTracing
File system bytes written and read
Full: on
Typical: off
JAXMListenerTracing
JAXM message sends
Full: on
Typical: off
JNDITracing
JNDI lookup times
Full: on
Typical: off
JSPDBTagsTagLibraryTracing
Jakarta DB Tags custom tag library for reading and writing from a SQL database
Full: on
Typical: off
JSPIOTagLibraryTracing
Jakarta IO custom tag library for a variety of input and output tasks
Full: on
Typical: off
JTACommitTracing
Commit times using JTA
Full: on
Typical: off
ThreadTracing
Number of active threads by class
Full: on
Typical: off
XMLSAXTracing
Time spent parsing XML document
Full: on
Typical: off
XSLTTracing
XML transformation time
Full: on
Typical: off
CatchException
Exception configuration
Full: off
Typical: off
FormattedSessionTracing
HTTP Session configuration
Full: off
Typical: off
HTTPAppServerAutoProbeServletTracing
HTTP Servlets configuration
Full: off
Typical: off
HTTPSessionTracing
HTTP Session configuration
Full: off
Typical: off
JSPTagLibraryTracing
Processing time of custom JSP tags
Full: off
Typical: off
ManagedSocketTracing
Network configuration
Full: off
Typical: off
ThrowException
Exception configuration
Full: off
Typical: off
Generally, the default toggles PBD files should not be edited. However, you can refine
the gathering of metrics by turning on or off certain tracer groups. Tracer groups can be
modified in the toggles files by:
Tracer groups report information only when turned on (uncommented) and are
activated with the keyword TurnOn.
Note: The Java Agent 9.0 supports EJB 2.0 and 3.0 instrumentation. Turn on or off the
tracer groups associated with EJB 2.0 or 3.0 to tailor your metric collection. Support for
EJBs in the application triage map extends only to Session and Entity beans. Message
Driven beans are not supported yet.
2.
Locate the tracer group to turn on, and uncomment the line by removing the pound
sign from the beginning of the line. The directive in the following example is turned
on, and will cause the tracing of all HTTP Servlets.
TurnOn: HTTPServletTracing
Note: Any uncommented (turned on) directive for a tracer group causes the tracer
group to be used.
To turn a tracer group off
Comment the tracer group by placing a pound sign at the beginning of the line, as in
the following example:
#TurnOn: HTTPServletTracing
IdentifyInheritedAs
IdentifyClassAs
IdentifyCorbaAs
To use this directive, create a directive class and directive parser class for the new
directive. You must then add a matcher class to examine your bytecode to determine if
a class contains a given annotation.
Note: This directive does not support method-level annotations.
EJB 2.0 and 3.0 support for the application triage map
Introscope 9.0 supports out-of-the-box tracing of EJB 2.0 and 3.0 session and entity
beans, specifically for use in the Workstation application triage map. CA Technologies
recommends using this out-of-the-box functionality in test environments only, as this
configuration affects the start-up time of the agent.
If deploying this functionality to your production environments, it is best that you
configure EJB 2.0 and 3.0 tracers for more specific things, as the out-of-the-box
functionality may be too broad.
Use the following directive to instruct ProbeBuilder to flag a class that is inheriting from,
or implementing, the superclass or interface:
IdentifyDeepInheritedAs
For EJB 2.0 application triage map support, the following directives have been added the
j2ee.pbd file:
IdentifyDeepInheritedAs:
IdentifyDeepInheritedAs:
IdentifyDeepInheritedAs:
IdentifyDeepInheritedAs:
javax.ejb.EJBObject EJB2StubTracing
javax.ejb.SessionBean SessionBeanTracing
javax.ejb.EntityBean EntityBeanTracing
javax.ejb.MessageBean MessageBeanTracing
These directives allow the ProbeBuilder to identify the EJB stubs on the client side, and
beans on the server side to be used in the application triage map.
For EJB 3.0 application triage map support, the following directive has been added to
the j2ee.pbd file:
IdentifyInheritedAnnotatedClassAs
The directive matches all classes that implement interfaces directly, or through a super
interface.
In the context of the application triage map, the following additional directive is set in
j2ee.pbd:
IdentifyInheritedAnnotatedClassAs: javax.ejb.Remote EJB3StubTracing
EJB naming
You can name called backends, generic frontends, and monitored components that deal
with EJBs. The name formatter lets you configure a suitable name for EJB 2.0 and 3.0
client stubs and bean implementations.
Use the EjbNameFormatter classes to define an EJB-related metric name, application
triage map application name, or node name using following place holders:
Application triage map node name for EJB Client Stub: Client {interface}
Application triage map node name for EJB Bean: Server {interface}
These are default EJB name formatters. They are used in the j2ee.pbd and
appmap-ejb.pbd files. You will use the same name formatters, but different metric
names. For example, you could modify existing tracer directives to use a more
appropriate name, but keep the same flags:
...
# Default commented out:
#TraceComplexMethodsIfFlagged: EJB2StubTracing EJB2BackendTracer "{interface}"
#Add the EJB application name to backend marker as well as called method
TraceComplexMethodsIfFlagged: EJB2StubTracing EJB2BackendTracer
"MyCustomerBeanApp-{interface}-{method}"
...
SetTracerClassMapping: EJB2BackendTracer
com.wily.introscope.agent.trace.BackendTracer
com.wily.introscope.probebuilder.validate.ResourceNameValidator
SetTracerParameter: EJB2BackendTracer nameformatter
com.wily.introscope.agent.trace.ejb.Ejb2StubNameFormatter
Note: The EJB context tracer is set on setContext() method of EJB 2.0 beans. This is an
internal Introscope tracer for the EJB 2.0 bean name formatter, which allows the name
formatter to function correctly.
2.
3.
4.
The Custom Directives screen will list the PBD files you placed in the hotdeploy
directory described in Using the ProbeBuilder Wizard or command-line
ProbeBuilder (see page 100).
2.
2.
3.
4.
5.
If they are not already running, start the Enterprise Manager and the Workstation.
The directive type (indicating generically how many class(es) or method(s) to trace)
The type of information to trace in the class(es) or method(s) (for example, a time, a
rate, or a count)
The fully-qualified metric name (including the resource path) under which to
present this information
Concurrent Invocations
Stall Count
TraceAllMethodsIfFlagged
Traces all methods if the specified class is included in a tracer group that has been
enabled with the TurnOn keyword.
Note: Only concrete, implemented methods can be traced and report metric data while
running. An abstract method specified in a custom tracer results in no metric data being
reported.
The expected syntax for trace directives usually consist of the following arguments:
<Tracer-Group>
The group to which the tracer is associated.
<class>
A fully qualified class or interface name to trace. Fully qualified classes include the
full assembly name of the class as well as the name, for example:
[MyAssembly]com.mycompany.myassembly.MyClass
The assembly name must be enclosed in [] brackets.
<method>
The method name (for example, MyMethod)
OR
the full method signature with return type and parameters (for example,
myMethod;[mscorlib]System.Void([mscorlib]
System.Int32). For more information on method signatures, see Signature
differentiation (see page 108).)
<Tracer-name>
Specifies the tracer type to be used. For example, BlamePointTracer. See the Tracer
name table below for descriptions of tracer names.
<metric-name>
Controls how the collected data is displayed in the Introscope Workstation.
The following examples describe three ways to specify the name and location of a
metric at different levels of the metrics tree.
metric-namethe metric appears immediately inside the agent node.
resource:metric-namethe metric appears inside one resource (folder) below the
agent node.
resource|sub-resource|sub-sub-resource:metric-namethe metric appears more
than one resource (folder) level deep below the agent node. Use pipe characters (|)
to separate the resources.
Incorrect
IdentifyClassAs: "MyClass" MyTracers
If you create a metric name that contains a class name, you must use quotes around the
whole metric name. Metric names are allowed to have spaces, and all spaces in metric
names must be contained within quotes. For example, the metric name
"{classname}|Test One Node" should be represented as follows:
Correct
TraceOneMethodIfFlagged: MyTracers AMethod BlamePointTracer "{classname}|Test One
Node"
Incorrect
TraceOneMethodIfFlagged: MyTracers AMethod BlamePointTracer {classname}|Test One
Node
Important! Introscope will not monitor classes having invalid class file names. For
example, in the class file name:
org/jboss/seam/example/seambay/AuctionImage$JaxbAccessorM_getData_setData_[B:
The _[B: causes the class file name to be invalid. You cannot use an open square
brackets ([) as part of the Java class file name. When Introscope encounters such classes
having invalid class names, it fails to instrument them and reports them as an error
message in the agent logs.
The following sections are examples of method tracers. In the following example,
quotes ("") are used around the metric names. CA Technologies highly recommends
putting quotes around all metric names when you create custom metric names.
The interval is determined by the monitoring logic in the Enterprise Manager, such as
the Graph frequency.
The preview pane in the Investigator defaults to 15 second intervals.
com.sun.petstore.account.LoginEJB login
"Petstore|Account:Logged In Users"
com.sun.petstore.account.LogoutEJB logout
"Petstore|Account:Logged In Users"
Signature differentiation
Tracers can be applied to a method based on the method signature.
To trace a single instance of a method with a specific signature, append the signature to
the method name (including return type) specified using the internal method descriptor
format.
For example, myMethod(Ljava/lang/String;)V traces the instance of the method with a
string argument and void return type.
For complete information about this format, see the Sun Java Virtual Machine
Specification.
Metric-name-based parameters
You can create a single-method tracer that creates a metric name based on parameters
passed to a method using the TraceOneMethodWithParametersOfClass keyword, using
this format:
TraceOneMethodWithParametersOfClass: <class-name> <method> <tracer-name>
<metric-name>
Parameters can be used in the metric name. This is accomplished by substituting the
value of parameters for placeholder strings in the metric name. The placeholder strings
to use are "{#}" where # is the index of the parameter to substitute. The indices start
counting at zero. Any number of parameter substitutions can be used in any order. All
parameters are converted to strings before substitution into the metric name. Object
parameters other than strings should be used with caution because they are converted
using the toString() method.
Important! If you are unclear about what string the parameter will be converted to, do
not use it in the metric name.
Metric-name-based example
A Web site uses a class named order, with a method named process. The method has
parameters for different kinds of orders, either book or music.
You can create a tracer like this:
TraceOneMethodWithParametersOfClass: order process(LJava/lang/string;)V
MethodTimer "Order|{0}Order:Average Response Time (ms)"
MusicOrder
Skip directives
Certain packages, classes, or methods can be skipped by AutoProbe or ProbeBuilder by
using skip directives. By default, the Java agent and fundamental Java classes and
packages are skipped by AutoProbe or ProbeBuilder.
Exceptions
The following directives are used to turn on tracing of exceptions either where thrown
or caught. They can cause performance degradation so they are not turned on by
default. To turn either of these on, uncomment the appropriate line:
#InstrumentPoint: ThrowException
#InstrumentPoint: CatchException
Agent initialization
The agent initialization instrument point directive does not cause additional overhead
and is turned on by default in both full and typical PBD sets.
InstrumentPoint: AgentInitialization
If multiple ProbeBuilder Directive files are used, any settings (such as tracer groups,
Skips, InstrumentPoints, Custom Method Tracers) turned on in any file take effect.
This increments the metric Total Purchases when someone buys a piece of merchandise.
For example, assume a class hierarchy in which ClassB extends ClassA, and ClassC
extends ClassB, like so:
Interface/ClassA
ClassB
ClassC
When you instrument ClassA, ClassB is also instrumented because it explicitly extends
ClassA. However, Introscope does not instrument ClassC because ClassC does not
explicitly extend ClassA. To instrument ClassC you must explicitly identify ClassC.
In pre-1.5 Java environments, to ensure that subclasses are instrumented, follow the
instructions in EJB subclass tracing (see page 96).
If you run under JVM 1.5, you can configure Introscope to instrument multiple levels of
subclasses of a probed class. For instructions, see ProbeBuilding class hierarchies (JVM
1.5). (see page 76)
http://java.sun.com/docs/books/tutorial/java/javaOO/annotations.html
http://www.developer.com/java/other/article.php/3556176
Blame Tracers
Introscope provides tracers for capturing front and backend metrics: FrontendMarker
and BackendMarker. These tracers explicitly mark a frontend and backend, respectively.
You can use FrontendMarker and BackendMarker to instrument your own code, for
instance code that accesses a backend, to cause Introscope to capture and present
metrics for custom components in the Investigator tree.
If no components are instrumented with the FrontendMarker tracer (or its subclasses
HttpServletTracer and PageInfoTracer), no frontend metrics are generated and no
component will be marked as a frontend for transactions.
When more than one component within a transaction is instrumented with the
FrontendMarker tracer (or its subclasses), only the first designated component will
generate Frontend metrics.
Note: When using frontend tracers, the name of the application given in the frontend
tracer must match the name given for the application triage map tracers, keeping in
mind that both are case-sensitive. For example, if you name the frontend tracer
AppOne and the application triage map tracer refers to this tracer as APPONE,
information about AppOne will not be displayed correctly in the Workstation application
triage map.
To prevent specific classes from being marked as frontend, the PBD parameter
is.frontend.unless can be specified. For information on the PBD directive
is.frontend.unless, see the Custom FrontendMarker directive (see page 114).
If no BackendMarker is configured, Introscope will infer a backendany component
that opens a client socket will be a default backend if none is explicitly marked.
for native sockets that are called through the Java Native Interface (JNI), to identify
a Java/JNI bridging method as the backend.
For example, to prevent the classes NotAFrontend and AnotherNonFrontend from being
treated as frontends in the package com.ABCCorp, that are instrumented with a
FrontendMarker named MyFrontendTracer, you would use the following PDB directive:
SetTracerParameter: MyFrontendTracer is.frontend.unless
com.ABCCorp.NotAFrontend,com.ABCCorp.AnotherNonFrontend
The following Blame Tracers used in previous versions of Introscope still exist, but are
not typically used in Introscope PBDs:
BlamedMethodTimer
BlamedMethodRateTracer
BlamedMethodTraceIncrementor
BlamedMethodTraceDecrementor
When an agent report metrics to an Enterprise Manager, a node is created for that
agent in the Investigator tree. When you configure management logic in the
Workstationfor instance, Dashboards, Alerts, and Actionsthe agent name is a
component in the regular expressions that identify the applications to which the
management logic applies. The Investigator tree below shows agents named
domain1//Adminserver, running on host qw32vtest01 under the WebLogic process.
connect to the Enterprise Manager, one after the other. The Enterprise Manager
renames the second agent:
PodAgent%1
If other agents with the same fully qualified name connect, they are renamed, in
succession, PodAgent%2, PodAgent%3, PodAgent%4, and so on, where the digit
following the percent character is the next number in sequence.
When a renamed agent disconnects, the suffix it was assigned can be re-used. For
example, if PodAgent%1 disconnects while PodAgent remains connected, the next agent
with the fully qualified name hostPA|processNIM|PodAgent to connect will be renamed
PodAgent%1.
Reuse of the suffix identifier makes it possible that the Enterprise Manager might assign
the same suffix to a particular agents name from connection to connection. However,
on subsequent connections, a given agent could just as well be renamed differently.
Having an agents name vary from connection to connection is problematic when
querying historical datait is preferable to configure a naming strategy that avoids the
Enterprise Manager renaming agents.
Tell Introscope that the agents in question are cloned agents by enabling cloned
agent naming (described in Enabling cloned agent naming in clustered
environments (see page 124).)
Define unique agent names yourself and make separate agent profiles for each
agent (described in Configuring unique names for application instances (see
page 125).)
Let Introscope uniquely name each agent using its own naming scheme (described
in How Introscope resolves agent naming conflicts (see page 119).)
On the Java command line, supply the desired name using this property:
-Dcom.wily.introscope.agent.agentName=
2.
Under the Agent Name section, specify the Java system property that will provide
the agent name in this property:
introscope.agent.agentNameSystemPropertyKey
Note: If the Java system property specified here does not exist, this property will be
ignored.
3.
WebLogic 9.x
WebLogic 10.0
WebLogic 10.3
Any forward slashes in the segment name are converted to underscores. For example, if
a Domain is named Petstore/West, it will be converted to Petstore_West.
Note: When constructing the agent name that appears in Introscope, Introscope edits
the information to make the agent name compliant with the following Introscope agent
naming rules:
names that begin with any character other than a letter will have the letter "A"
prepended to them
2.
For JBoss, create an XML file. See Configuring JBoss (see page 41).
2.
Under the Agent Name section, configure the desired delay in the property
introscope.agent.agentAutoNamingMaximumConnectionDelayInSeconds.
3.
2.
Under the Agent Name section, configure the desired interval in the
introscope.agent.agentAutoRenamingIntervalInMinutes property.
3.
2.
3.
4.
are running agents that share a host, process, or Java Agent name with one or more
other agents, or
are running two or more agents that are using the same agent profile.
2.
3.
4.
2.
3.
1agent is connected
3agent is disconnected
Socket metrics
On the computer that the Enterprise Manager is installed on, open the
IntroscopeEnterpriseManager.properties file located in the
<Introscope_Home>/config directory.
2.
Note: For information about Enterprise Manager properties, see the CA APM
Configuration and Administration Guide.
Socket metrics
Socket and Secure Sockets Layer (SSL) metric collection is enabled by default in the
agent.
Note: JVMs using the Agent.NoRedef.jar do not have socket metrics reported. See
AutoProbe for WebSphere 6.1 (see page 47) for more information.
2.
In the Agent I/O Socket Metrics section, edit the property values to contain the list
of those hosts or ports for which metrics are required:
If an invalid host or port is included in the parameter values, a warning message is
written to the agent log and that value is ignored. If, as a result, the list contains no
entries, no restriction will apply.
introscope.agent.io.socket.client.hosts
A comma separated list of hosts; only 'client' socket metrics for specified hosts
will be generated. Hosts may be specified by name or textual representation of
IP address (in either IPv4 or IPv6 forms).
Socket metrics
Note: Duplicate host names are discarded. In cases where multiple host names
map to a single IP, only one of the names is retained. The property will,
however, match client connections with any of the set of synonymous names.
introscope.agent.io.socket.client.ports
A comma separated list of port numbers; only 'client' socket metrics for
specified ports will be generated.
Note: Duplicate ports are discarded.
introscope.agent.io.socket.server.ports
Comma separated list of port numbers, only 'server' socket metrics for
specified ports will be generated.
The above properties are dynamic; you do not need to restart your applications for
changes to take effect.
3.
2.
In the I/O Socket Tracer Group or Network Tracer Group sections of java2.pbd,
determine the tracers you want to turn on or off, and comment or uncomment
them. For example, to suppress the metrics for input bandwidth, you comment out
the following:
#TraceOneMethodWithParametersIfFlagged: SocketTracing read
InputStreamBandwidthTracer "Input Bandwidth (Bytes Per Second)"
Note: Tracers with names ending with MappingTracer must not be commented out.
3.
Socket metrics
2.
In the Trace Sockets and Trace NIO Sockets sections, select the tracers you want to
modify. Change {hostname} to {hostip} in the relevant tracers.
For example, the original tracers use the default {hostname}:
TraceOneMethodWithParametersIfFlagged: SocketTracing read AppMapSocketTracerBT
"System {hostname} on port {port}"
TraceOneMethodWithParametersIfFlagged: SocketTracing write
AppMapSocketTracerBT "System {hostname} on port {port}"
3.
Open either toggles-full.pbd or toggles-typical.pbd files (open the file you are using
in your deployment).
2.
Comment out (place a pound or hash sign,#, at the beginning of the line)
SocketTracing:
#TurnOn: SocketTracing
3.
For more information about turning on and off tracer groups, in the toggles-full.pbd and
toggles-typical.pbd files, see Default tracer groups and toggles files (see page 86) and
Turning tracer groups on or off (see page 95).
Backwards compatibility
In the 9.0 Java agent, new socket tracers have been introduced that are more
configurable than pre-9.0 tracers. However, if for any reason, you want to revert to
pre-9.0 tracers (and disable new 9.0 socket tracing features and configuration options),
the required configuration changes are outlined below.
To collect socket metrics using pre-9.0 tracers
1.
Open either toggles-full.pbd or toggles-typical.pbd files (open the file you are using
in your deployment).
2.
Comment out (place a pound or hash sign,#, at the beginning of the line)
SocketTracing:
#TurnOn: SocketTracing
3.
Uncomment ManagedSocketTracing:
TurnOn: ManagedSocketTracing
4.
If you are using pre-9.0 socket tracers and input and output bandwidth metrics are
required, they are enabled as follows.
The following steps are optional.
To collect input and output bandwidth metrics
1.
2.
Locate the Agent Socket Rate Metrics section and change the following property to
true:
introscope.agent.sockets.reportRateMetrics=true
The Java agent has the option to run in verbose mode. Verbose mode records higher
levels of details about actions and agent interactions with your environment. This
information is useful in solving issues with your environment or agent functionality.
Introscope uses Log4J functionality for these functions. If you want to use other Log4J
functionality, please consult the Log4J documentation.
2.
3.
2.
logfile: the information in the logfile is sent to a logfile. If this is selected, the
location of the log file is configured using the log4j.appender.logfile.File
property. See Changing the name or location of the agent logfile (see
page 133).
For example, if you wanted the agent to report in verbose mode to just a logfile, the
property would be set to:
log4j.logger.IntroscopeAgent=VERBOSE#com.wily.util.feedback.Log4JSeverityLeve
l,logfile
If you wanted the agent to report to both a logfile and console, you would include
both logfile and console in the property.
Note: By default the agent log, IntroscopeAgent.log is written to the
<Agent_Home>/wily/logs directory. If you configured agent autonaming options,
the agent log files are also automatically named, as described in Agent log files and
automatic agent naming (see page 133).
3.
2.
3.
Set the location and name of the log file, using a fully qualified path to the new
location and file. For example:
log4j.appender.logfile.File=C:/Logs/AgentLog1.log
4.
If the original name of the logfile does not end in .log, a period and log is added.
All characters that are not letters or digits will be replaced by underscores
The following examples show how an agent logfile is named. The examples use an agent
name of DOM1//ACME42, where DOM1 is the WebLogic domain, and ACME42 is the
instance of the agent.
When an agent log file is created (named AutoProbe.log by default), if the agent name is
not yet available, a timestamp is included in the filename:
AutoProbe.20040416-175024.log
Once the agent name becomes available, the logfile is renamed using the agents
automatic name:
AutoProbe.DOM1_ACME42.log
You can disable automatic log naming - see Advanced automatic agent naming options
(see page 123) for more information.
2.
Note: You must restart the managed application before changes to this property
take effect.
3.
<original-directory> or <original-file> is the Java class location that you specify with the
ProbeBuilder Wizard or with the Command-Line ProbeBuilder.
Only the most recent log is kept; all previous log files are overwritten.
2.
Locate the introscope.autoprobe.logfile property and modify the log name and
location, using a fully qualified file path. Non-absolute names are resolved relative
to the location of the IntroscopeAgent.profile file.
Note: When loading the agent profile from a resource on a classpath, AutoProbe is
unable to write to the AutoProbe log file, because the IntroscopeAgent.profile file is
located within a resource.
You must restart the managed application before changes to this property take
effect.
3.
LeakHunter
Introscope LeakHunter is an add-on component designed to help locate the source of
potential memory leaks by watching for collection instances that appear to be
increasing in size over timethat is, if the number of objects stored in the collection
increases over time.
Memory leaks that occur in programs that run for short periods (minutes or hours)
might not present a major issue. However for applications that are running 24 hours a
day (like a web site), a small memory leak can soon escalate into a big problem.
Introscope LeakHunter is designed to track information about a noticed memory leak by
being turned on, discovering collection classes, and then being turned off after
information is gathered. This method of using LeakHunter creates only a small,
temporary amount of overhead.
LeakHunter
reports information about the collection to the Enterprise Manager as metric data
reports information about the collection to a log file on the agent machine
Implementations of java.util.Collection:
java.util.ArrayList
java.util.LinkedList
java.util.TreeSet
java.util.HashSet
java.util.LinkedHashSet
java.util.Vector
java.util.Stack
LeakHunter
Implementations of java.util.Map:
java.util.Map
java.util.SortedMap
java.util.HashMap
java.util.TreeMap
java.util.IdentityHashMap
java.util.Hashtable
java.util.Properties
java.util.LinkedHashMap
In addition to the above, LeakHunter does not track the following in a Java
implementation:
any subclasses created for collections described in What LeakHunter tracks in Java
(see page 138). However, you can update the ProbeBuilder Directive (PBD) file to
get this information. See the leakhunter.pbd file for more information.
Note: If you are using Application Server AutoProbe, LeakHunter does not automatically
track collections allocated by the application server. To track these collections, you must
statically instrument the application server, or use JVM AutoProbe.
2.
3.
4.
Open *.typical.pbl or *.full.pbl (open the file you have listed in the
IntroscopeAgent.profile property introscope.autoprobe.directivesFile ) and
uncomment leakhunter.pbd.
Note: When using ProbeBuilder Wizard, copy the leakhunter.pbd file to the
<Agent_Home>\wily\core\config\hotdeploy directory.
5.
Important! By default, agent extensions such as LeakHunter are located and referenced
from the <Agent_Home>\wily\core\ext directory. However, you can change the location
of the agent extension directory in the agent profile. If you change the location of the
\ext directory, be sure to move the contents of the \ext directory as well.
To disable LeakHunter
1.
2.
3.
4.
2.
introscope.agent.leakhunter.collectAllocationStackTraces
Specifies whether to collect allocation stack trace information. Turning on this
option has the potential to create higher system CPU usage and memory.
Changes to this property take effect immediately and do not require the
managed application to be restarted.
The default value is false.
introscope.agent.leakhunter.ignore.n
Specifies the particular collections that you want LeakHunter to ignore.
For Generic collections, use a syntax that includes the generic type
qualification, for example: System.Collections.Generic.List`1
Changes to this property take effect immediately and do not require the
managed application to be restarted.
The default values for these properties (where n=0-4) are:
introscope.agent.leakhunter.ignore.0=org.apache.taglibs.standard.lang.jst
l.*
introscope.agent.leakhunter.ignore.1=com.bea.medrec.entities.RecordEJB_xw
cp6o__WebLogic_CMP_RDBMS
introscope.agent.leakhunter.ignore.2=net.sf.hibernate.collection.*
introscope.agent.leakhunter.ignore.3=org.jnp.interfaces.FastNamingPropert
ies
introscope.agent.leakhunter.ignore.4=java.util.SubList
3.
Running LeakHunter
Running LeakHunter
LeakHunter is run as an agent extension.
To run LeakHunter
Using JVM AutoProbe: after LeakHunter has been enabled, restart the application.
Using ProbeBuilder Wizard: run ProbeBuilder Wizard and select the leakhunter.pbd
from the custom pbd list. Restart the managed application after implementing new
.jars for use.
<method>: the name of the method where the collection was allocated
<4 digit hash code>: the hash code of the full name of the class containing the
method or field name
#<unique number>: number appended to potential leaks with the same method and
hash code to ensure unique collection IDs during the run of the agent.
The collection ID for a potential leak will be stable across runs of the application.
Examples of these collection IDs are:
theLookupTable-6314#1
getLoginID-1234#1
getLoginID-1234#2
getLoginID-1234#3
verifyCart-5678#1
verifyCart-0012#1
when a potential leak is first identifiedsee Potential leak first identified log entry
(see page 144)
Collection ID
Note: The current size of a leaked collection recorded in the LeakHunter log file is not
dynamically updated. The log file identifies the size of a leak when the leak is first
identified. To see up-to-date information about the size of a leaked connection, click the
Leak tab in the Introscope Workstation.
Example: Log file entry if a potential leak is detected
The following example illustrates an entry in the Java log file when a potential leak is
first identified:
5/2/09 9:55:06 AM PDT
Potential leak identified
Assigned ID: testInst-2604#1
Collection Class: java.util.Vector
Allocation Method: sonOfLH_test.testInst()
Allocation Timestamp: 5/2/09 9:54:21 AM PDT
Allocation Stack Trace:
Unknown
Field Name(s):
sonOfLH_test.v3
sonOfLH_test.v4
sonOfLH_test.v5
Current Size: 44
Collection ID
Using LeakHunter
Collection ID
Using LeakHunter
For more information on how to use LeakHunter, see the CA APM Workstation User
Guide.
ErrorDetector
ErrorDetector
Introscope ErrorDector allows application support personnel to detect and diagnose the
cause of serious errors, which can prevent users from completing web transactions.
These kinds of application availability issues typically result in error messages to the
user such as "404 Not Found" and others, yet the error message lacks specific
information that IT personnel need to isolate the root cause of the problem. Introscope
ErrorDetector allows you to monitor these serious errors as they occur in live
applications, determine the frequency and nature of the errors, and deliver specific
information about the root cause to developers.
ErrorDetector is the only application management solution that helps ensure superior
user experiences and improves transaction integrity by enabling root cause analysis of
serious application errors.
Introscope ErrorDetector allows IT teams to:
Obtain the information needed to reproduce, diagnose and eliminate serious errors
Types of errors
CA Technologies has defined a set of criteria to describe "serious" errors, based on
information contained in the J2EE specifications. ErrorDetector considers both errors
and exceptions to be errors. The most common type of error is a thrown exception.
Some examples of common errors are:
backend errors (for example, cant send a message through JMS, can't write a
message to the message queue)
What CA Technologies considers to be important errors might differ from what you
consider important errors. If you do not consider some of the errors ErrorDetector
tracks to be important, you can choose to ignore them. If there are additional errors you
want to track, you can use error tracers to create new directives to trace them.
ErrorDetector is integrated with Transaction Tracer, enabling you to see exactly why and
how serious errors occurred within the context of the transaction path. Moreover, all
errors and transactions are persisted to Transaction Event Database, enabling you to
spot trends through analysis of historical data.
Introscope defines a transaction as the invocation and processing of a service. In the
context of a web application, it is the invocation and processing of a URL sent from a
web browser. In the context of a web service, it is the invocation and processing of a
SOAP message.
2.
3.
If you are using ProbeBuilder Wizard, copy the errors.pbd file to the
<EM_Home>/config/custompbd directory, and re-instrument your applications.
4.
2.
3.
You can configure the agent to ignore errors you dont want to track. The information
you specify to "tag" the error can be the exact error message, or any portion of the
message, along with the "wildcard" asterisk character.
To ignore certain errors (optional)
1.
2.
3.
4.
You should place any new directives you create with these tracers in the errors.pbd file
in the <Agent_Home>/wily directory.
ExceptionErrorReporter
The ExceptionErrorReporter tracer can be used to check for exceptions being thrown
from the instrumented method. If an exception is thrown, this tracer treats it as an error
and gets the error message from the exception. This is the most common definition of
an error.
MethodCalledErrorReporter
The MethodCalledErrorReporter tracer is used on methods where the very act of the
method being called means that an error has occurred. For example:
TraceOneMethodOfClass: com.bank.CheckingAccount cancelCheck
MethodCalledErrorReporter "CustomerAccount:Canceled Checks Per Interval"
This directive specifies that whenever the cancelCheck() method is called (for any
reason), this is an error. The error message simply states the class and method that was
called.
If you do not know which methods may throw an exception or error, try using the
ThisErrorReporter tracer.
ThisErrorReporter
The ThisErrorReporter tracer is similar to the MethodCalledErrorReporter, but it
constructs the error message by calling toString() on the instrumented objects. This
tracer is most useful to put on the constructor of an exception class. For example:
TraceOneMethodWithParametersOfClass: ezfids.util.exception.EasyFidsException [set
the init variable for your book] ThisErrorReporter
"Exceptions|{packageandclassname}:Errors Per Interval"
Note: To capture error messages, the ThisErrorReporter tracer must be used with a
"...WithParameters" directive.
Using ErrorDetector
HTTPErrorCodeReporter
The HTTPErrorCodeTracer tracer reports error codes from Servlets and JSPs. It is a per
interval counter that counts incidents of:
Using ErrorDetector
For more information on how to use ErrorDetector, see the CA APM Workstation User
Guide.
You can define a URL group for any useful category of requests that can be derived from
a URLs path prefix. For example, depending on the form of your application URLs, you
could define URL groups for each customer your application supports, for each major
application, or for sub-applications. This enables you to monitor performance in the
context of committed service levels, or for mission-critical portions of your application.
If you define URL Groups so some URLs fall into multiple groups, the order in which you
list the keys for the URL Groups in the property is important. The URL Group with the
narrower membership should precede the URL Group with broader membership. For
example, if the IP Group with key alpha has the path prefix
/examplesWebApp and the URL Group with key delta has the path prefix
/examplesWebApp/cleverones, delta should precede alpha in the keys parameter
Statistics for these requests would appear under the metric name "734"
http://ubuy.com/ws/shoppingServlet?ViewItem&category=734
&item=3772&tc=photo
http://ubuy.com/ws/shoppingServlet?ViewItem&category=734
&item=8574&tc=photo
where m is the index of the first character, and n is one greater than the index of the
last character. String selection operates like the java.lang.String.substring() method. For
example, given this setting:
introscope.agent.urlgroup.group.alpha.format=
{path_substring:0:3}
Statistics for the following request would appear under the metric node /ht:
http://research.com/htmldocu/WebL-12.html
where delim_char is the character that delimits the segments in the path, m is the index
of the first segment to select, and n is one greater than the index of the last segment to
select. For example, given this setting:
introscope.agent.urlgroup.group.alpha.format={path_delimited:/:2:4}
a delimiter character, in this example, the forward slash (/) counts as a segment
The segments as delimited by the slash character in the URL example are:
0=/, 1=userid,sessionid, 2=/, and 3=pageid
You can specify multiple delimiters as necessary. For example, given this setting:
introscope.agent.urlgroup.group.alpha.format={path_delimited:/,:3:4}
statistics for requests of the form shown above would appear under the metric name
sessionid with the segments as delimited by the slash and the comma in the URL
example are:
0=/, 1=userid, 2=, 3=sessionid, 4=/, and 5=pageid
2.
where logfile is the full path to your web server log file.
3.
4.
To configure the proposed URL Groups, copy the property statements produced by
URL Grouper into the IntroscopeAgent.profile.
Transaction Trace sampling that is enabled by default, based on your URL groupings
Traces producing clamped components are marked with an asterisk. For more
information about viewing these traces, see the CA APM Workstation User Guide.
Important! If the Transaction Trace component clamp size is increased, the memory
required for Transaction Traces can increase. For more information, see the CA APM
Configuration and Administration Guide.
introscope.agent.transactiontracer.sampling.enabled
Set to false to disable Transaction Trace sampling. The default value is true.
introscope.agent.transactiontracer.sampling.perinterval.count
Specifies the number of transactions to trace, during the interval you specify.
The default number of transactions is 1.
introscope.agent.transactiontracer.sampling.interval.seconds
Specifies the length of time to trace the number of transactions you specify.
The default interval is every 2 minutes.
If monitored applications are characterized by very deep or long lasting transactions, the
agents Transaction Trace sampling may require more heap memory than previous
Introscope versions. For more information, see Transaction Trace component clamp
(see page 161) and Transaction trace sampling (see page 162).
You can view the agent GC heap usage in the GC Heap overview. See the CA APM
Workstation User Guide.
If you are operating a high-performance Introscope environment, contact CA
Professional Services for the appropriate agent JVM heap settings.
Introscope Transaction Tracer can identify User IDs from managed applications that
store User IDs in one of these ways:
HttpServletRequest.getRemoteUser()
If your managed application stores User IDs using one of these methods, see Configuring
Agent to collect additional transaction trace data (see page 164), to configure Java
Agent settings to collect User ID data.
request headers
request parameters
session attributes
To record this servlet request information for your managed application, see
Configuring Agent to collect additional transaction trace data (see page 164) to
configure Java Agent settings to collect this data.
2.
Configure the properties that correspond to the method your managed application
uses to store User IDs.
Note: Ensure that only one set of properties are not commented, or the wrong
properties might be used.
2.
3.
4.
To specify the HTTP request headers for which to collect transaction trace data,
uncomment this property, and specify the HTTP request header(s) to track, in a
comma-separated list:
#introscope.agent.transactiontracer.parameter.httprequest.headers=User-Agent
2.
To specify the HTTP request parameters for which to collect transaction trace data,
uncomment this property and specify the HTTP request parameter(s) to track, in a
comma-separated list:
#introscope.agent.transactiontracer.parameter.httprequest.parameters=paramete
r1,parameter2
3.
To specify the HTTP session attributes for which to trace data, uncomment this
property and specify the HTTP session attribute(s) to track, in a comma-separated
list, for example:
#introscope.agent.transactiontracer.parameter.httpsession.attributes=cartID,d
eptID
4.
wily/core/ext/SQLAgent.jar
wily/core/config/sqlagent.pbd
Note: By default, agent extensions like the SQLAgent.jar file are installed in the
wily/core/ext directory. You can change the location of the agent extension directory
with the introscope.agent.extensions.directory property in the agent profile. If you
change the location of the /ext directory, be sure to move the contents of the /ext
directory as well.
the SQL agent creates a metric with the comment as part of the metric name:
"/* John Doe, user ID=?, txn=? */ select * from table..."
The comment embedded in the SQL statement is useful for the database administrator
to see who is executing what query and the database executing the query ignores them.
The SQL agent, however, does not parse the comment string when it captures the SQL
statement. Therefore, for each unique user ID, the SQL agent creates a unique metric,
potentially causing a metric explosion.
This problem can be avoided by putting the SQL comment in single quotes. For example:
"/*' John Doe, user ID=?, txn=? '*/ select * from table..."
The SQL agent then creates the following metric where the comment no longer causes a
unique metric name:
"/* ? */ select * from table..."
This SQL statement is accessing a temporary table that has a unique identifier appended
to the table name. The additional digits that are appended to the TMP_ table name
create a unique metric name each time the statement is executed, causing a metric
explosion.
In studying the code, you notice that "CHANGE CITY FROM CARROLTON, TO CAROLTON,
_ " generates an array of cities.
Similarly, if you are investigating a potential metric explosion, you might review a SQL
statement similar to this:
CHANGE COUNTRY FROM US TO CA _ CHANGE EMAIL ADDRESS FROM TO BRIGGIN @ COM _ "
In studying the code, you notice CHANGE COUNTRY results in a long list of countries. In
addition, the placement of the quotes for countries results in people's e-mail addresses
getting inserted into SQL statements, creating unique metrics that could be the source
of the metric explosion.
Metrics for normalized statements are aggregated and can be viewed in the
Workstation Investigator.
2.
com-wily-Extension-Plugins-List:testNormalizer1
Note: The value of this key can be anything. In this instance, testNormalizer1 is
used as an example. Whatever you specify as the value of this key, use it in the
following keys as well.
com-wily-Extension-Plugin-testNormalizer1-Type: sqlnormalizer
com-wily-Extension-Plugin-testNormalizer1-Version: 1
com-wily-Extension-Plugin-testNormalizer1-Name: normalizer1
Should contain the unique name of your normalizer, for example normalizer1.
com-wily-Extension-Plugin-testNormalizer1-Entry-Point-Class:
<Thefully-qualified classname of your implementation of ISQLNormalizer>
3.
4.
Important! This is a hot property. Changes to the extension name will result in
re-registration of the extension.
5.
In the IntroscopeAgent.profile, you can optionally add the following property to set
the error throttle count:
introscope.agent.sqlagent.normalizer.extension.errorCount
For more information about errors and exceptions, see Exceptions (see page 172).
Note: If the errors thrown by the custom normalizer extension exceed the error
throttle count, the extension is disabled.
6.
7.
Exceptions
If the extension you created throws an exception for one query, the default SQL
statement normalizer uses the default normalization scheme for that query. When this
happens, an ERROR message is logged, saying an exception was thrown by the
extension, and a DEBUG message is logged with stack trace information. However, after
five such exceptions are thrown, the default SQL statement normalizer disables your
created extension and stops attempting to use the created extension for future queries
until the normalizer is changed.
2.
introscope.agent.sqlagent.normalizer.extension=RegexSqlNormalizer
Specifies the name of the SQL normalizer extension that will be used to
override the preconfigured normalization scheme. When enabling the regular
expressions extension, set this property to RegexSqlNormalizer.
introscope.agent.sqlagent.normalizer.regex.keys=key1
This property specifies the regex group keys, which are evaluated in the order
they are listed. This property is required to enable the regular expressions
extension. There is no default value.
introscope.agent.sqlagent.normalizer.regex.key1.pattern=A
This property specifies the regex pattern that is used to match against the SQL
statements. All valid regular expressions allowed by the java.util.Regex
package classes can be used here. This property is required to enable the
regular expressions extension. There is no default value.
introscope.agent.sqlagent.normalizer.regex.key1.replaceFormat=B
This property specifies the replacement string format. All valid regex allowed
by the java.util.Regex package classes can be used here. This property is
required to enable the regular expressions extension. There is no default value.
introscope.agent.sqlagent.normalizer.regex.matchFallThrough=false
If this property is set to true, SQL strings are evaluated against all the regex key
groups. The implementation is chained. Hence, if the SQL strings match
multiple key groups, the normalized SQL output from group1 is fed as input to
group2, and so on.
If the property is set to false, as soon as a key group matches the SQL string,
the normalized SQL output from that group is returned. The MatchFallThrough
property does not enable or disable the extension.
For example, if you had a SQL string like: Select * from A where B, you would
set the following properties:
introscope.agent.sqlagent.normalizer.regex.keys=key1,key2
introscope.agent.sqlagent.normalizer.regex.key1.pattern=A
introscope.agent.sqlagent.normalizer.regex.key1.replaceFormat=X
introscope.agent.sqlagent.normalizer.regex.key2.pattern=B
introscope.agent.sqlagent.normalizer.regex.key2.replaceFormat=Y
introscope.agent.sqlagent.normalizer.regex.key1.caseSensitive=false
This property specifies whether the pattern match is case sensitive. The default
value is false. This property is not required to enable the regular expressions
extension.
introscope.agent.sqlagent.normalizer.regex.key1.replaceAll=false
If this property is set to false, it will replace the first occurrence of the matching
pattern in the SQL with the replacement string. If this property is set to true, it
will replace all occurrences of the matching pattern in the SQL with the
replacement string.
For example, if you have a SQL statement like Select * from A where A like Z,
you would set the properties as follows:
introscope.agent.sqlagent.normalizer.regex.key1.pattern=A
introscope.agent.sqlagent.normalizer.regex.key1.replaceFormat=X
Important! All properties listed above are hot, meaning changes to these properties
take effect once you have saved the IntroscopeAgent.profile.
Example 1
Here is a SQL query before regular expression SQL statement normalization:
INSERT INTO COMMENTS (COMMENT_ID, CARD_ID, CMMT_TYPE_ID,CMMT_STATUS_ID,
CMMT_CATEGORY_ID, LOCATION_ID, CMMT_LIST_ID,COMMENTS_DSC, USER_ID, LAST_UPDATE_TS)
VALUES(?, ?, ?, ?, ?, ?,?, CHANGE CITY FROM CARROLTON, TO CAROLTON, _ ", ?, CURRENT)
Example 2
Here is a SQL query before regular expression SQL statement normalization:
SELECT * FROM TMP_123981398210381920912 WHERE ROW_ID =
Example 3
If you want to normalize a SQL statement like: Select .... ResID1, CustID1 where
ResID1=.. OR ResID2=.. n times OR CustID1=.. OR n times, you could set the properties
like this:
introscope.agent.sqlagent.normalizer.regex.matchFallThrough=true
introscope.agent.sqlagent.normalizer.regex.keys=default,def
introscope.agent.sqlagent.normalizer.regex.default.pattern=(ResID)[1-9]
introscope.agent.sqlagent.normalizer.regex.default.replaceAll=true
introscope.agent.sqlagent.normalizer.regex.default.replaceFormat=$1
introscope.agent.sqlagent.normalizer.regex.default.caseSensitive=true
introscope.agent.sqlagent.normalizer.regex.def.pattern=(CustID)[1-9]
introscope.agent.sqlagent.normalizer.regex.def.replaceAll=true
introscope.agent.sqlagent.normalizer.regex.def.replaceFormat=$1
introscope.agent.sqlagent.normalizer.regex.def.caseSensitive=true
Important! You can use the regular expressions SQL normalizer instead of this command
to normalize SQL statements in double quotes. See Regular expression SQL statement
normalizer (see page 172) for more information.
Open the sqlagent.pbd file and locate the SQL statements. For example:
TraceOneMethodWithParametersIfFlagged: SQLAgentStatements
executeQuery(Ljava/lang/String;)Ljava/sql/ResultSet; DbCommandTracer
"Backends|{database}|SQL|{commandtype}|Query|{sql}"
2.
Remove {sql} from the trace directives you want to turn off. For example:
TraceOneMethodWithParametersIfFlagged: SQLAgentStatements executeQuery(Ljava/
lang/String;)Ljava/sql/ResultSet; DbCommandTracer
"Backends|{database}|SQL|{commandtype}|Query"
3.
SQL metrics
The SQL Agent metrics appear under the Backends node in the Introscope Workstation
Investigator. SQL statement metrics can be found under the
Backends|<backendName>|SQL node.
Note: Average Response Time (ms) will only display queries that return a data reader,
i.e. queries executed via the ExecuteReader() method. This metric represents the
average time spent in the data readers Close() method.
SQL metrics
Note: Instrumented XADataSources may not report commit or rollback metrics. Other
instrumented DataSources may not report commit or rollback metrics unless those
metrics contain data.
Glassfish
JBoss
Tomcat
WebLogic
WebSphere
Introscope supports any MBean built to the Sun JMX specification. For more information
on the Sun JMX specification, see Java Management Extensions.
Introscope converts the JMX data to the Introscope metric format and displays it in the
Investigator under the following node:
<Domain>|<Host>|<Process>|AgentName|JMX|
Introscope polls only the RuntimeServiceMBean, because it is the only one that supports
local access (an efficiency issue), and because it contains most of the data expected to
be relevant.
You have not configured valid primary keys, as described in Using primary key
conversion to streamline JMX metrics (see page 181).
Note: If you specify primary keys that no MBeans match, Introscope will use the default
conversion method.
In the default conversion method, Introscope displays both the name and the value of
the attribute, and lists the pairs alphabetically in the metric tree.
Domain>|<Host>|<Process>|AgentName|JMX|<domain name>|
<key1>=<value1>|<key2>=<value2>:<metric>
For example, given a WebLogic MBean with these characteristics:
Only the key value information is displayed, not the key name.
If you configure:
introscope.agent.jmx.name.primarykeys=type,category the connections attribute
appears in the Investigator tree in this structure:
<IntroscopeDomain>|<Host>|<Process>|AgentName|JMX|Weblogic|jdbc|server:connection
s
Note: WebLogic 9.0 does not have universally available primary keys, so for WebLogic
9.0 Introscope uses the key/value pair metric naming convention found in the Default
Conversion Method described in Default JMX metric conversion process (see page 180).
As a result, the JMX Metric tree for WebLogic 9.0 will have a different structure than the
metric tree for other WebLogic versions.
ActiveConnectionsCurrentCount
WaitingForConnectionCurrentCount
PendingRequestCurrentCount
ExecuteThreadCurrentIdleCount
OpenSessionsCurrentCount
2.
3.
4.
2.
1.
If you modify the value of the property, the values must be case-sensitive, and
multiple keys must be separated by commas.
2.
2.
3.
Save changes.
4.
2.
3.
4.
5.
To specify the JSR-77 Metrics to report, uncomment and set this property to
identify desired metrics:
introscope.agent.jmx.name.filter
Solaris
Important! Platform monitoring is not supported on 64 bit Solaris using 64 bit BEA
JRockit JVM.
Windows XP Professional
Important! Introscope does not monitor platform monitors on 64-bit Windows XP
Professional.
HP-UX
Note: HP-UX Platform Monitor binaries (both PA-RISC and IA 64) work on 32 bit
kernel with 32 bit JVM.
HP-UX Platform Monitor binaries (both PA-RISC and IA 64) work on 64 bit kernel
with 32 bit JVM. (HP-UX binaries support 64 bit OS but not 64 bit JVM).
The Java Agent platform monitor for HP-UX reports the percentage use of CPUs
when more than one process is present. For example, if you have 4 processes, the
maximum use of the CPU would be 400% (4 processes using 100% of the CPU). If
one process takes 110%, this means it is using 1.1 CPUs.
Sun JVM
HP Hotspot JVM
ProcessID
Utilization % (process) - for the Java Agent process, the percentage of total capacity
of all processors this process is using. Regardless of how many processors there are,
this metric generates only one number.
Utilization % (aggregate) - for this processor, its total utilization (as a percentage) by
all processes in the system. Each processor is shown as a Resource in the
Investigator tree.
2.
3.
4.
In the Add dialog, if "Process" and "Processor" performance objects are present in
the drop down list box, then system objects are enabled.
Go to Start > Accessories > Right click on command prompt > Run as >
Administrator.
2.
2.
After Java agent installation, verify that the following files are installed in the
wily/core/ext directory:
introscopeAIXPSeries32Stats.jar
introscopeAIXPSeries64Stats.jar
libIntroscopeAIXPSeries32Stats.so
libIntroscopeAIXPSeries64Stats.so
3.
AIX 4.3.3 and higher: A Perfstat Library has been created to work with AIX
4.3.3. Install the following packages from the IBM FTP site:
bos.perf.libperfstat
bos.perf.perfstat
AIX 4: Bring your system up to 4.3.3 and then install the above packages.
introscopeSolarisAmd32Stats.jar
introscopeSolarisAmd64Stats.jar
introscopeSolarisSparc32Stats.jar
introscopeSolarisSparc64Stats.jar
libIntroscopeSolarisAmd32Stats.so
libIntroscopeSolarisAmd64Stats.so
libIntroscopeSolarisSparc32Stats.so
libIntroscopeSolarisSparc64Stats.so
introscopeWindowsIntelAmd32Stats.dll
introscopeWindowsIntelAmd64Stats.dll
introscopeWindowsIntelAmd32Stats.jar
introscopeWindowsIntelAmd64Stats.jar
AIX
The platform monitor files are:
introscopeAIXPSeries32Stats.jar
introscopeAIXPSeries64Stats.jar
libIntroscopeAIXPSeries32Stats.so
libIntroscopeAIXPSeries64Stats.so
introscopeRedHatStats.jar
libIntroscopeRedHatStats.so
Linux
The platform monitor files are:
introscopeLinuxIntelAmd32Stats.jar
introscopeLinuxIntelAmd64Stats.jar
libIntroscopeLinuxIntelAmd32Stats.so
libIntroscopeLinuxIntelAmd64Stats.so
HP-UX
The platform monitor files are:
introscopeHpuxItaniumStats.jar
introscopeHpuxParisc32Stats.jar
introscopeHpuxItanium64Stats.jar
libIntroscopeHpuxItaniumStats.so
libIntroscopeHpuxParisc32Stats.so
libIntroscopeHpuxItanium64Stats.so
Make these changes after installing the agent and before starting it.
If you are using the first two files named above, you also must install gcc before starting
the agent. You can download gcc, a compiler for C and C++, by searching the HP support
website.
Open IntroscopeAgent.profile.
2.
Under the Platform Monitor Configuration heading, locate the exact matching value
for your operating system and uncomment the property. The available values are:
#introscope.agent.platform.monitor.system=SolarisAmd32
#introscope.agent.platform.monitor.system=SolarisAmd64
#introscope.agent.platform.monitor.system=SolarisSparc32
#introscope.agent.platform.monitor.system=SolarisSparc64
#introscope.agent.platform.monitor.system=AIXPSeries32
#introscope.agent.platform.monitor.system=AIXPSeries64
#introscope.agent.platform.monitor.system=HP-UXItanium
#introscope.agent.platform.monitor.system=HP-UXParisc32
#introscope.agent.platform.monitor.system=WindowsIntelAmd32
#introscope.agent.platform.monitor.system=WindowsIntelAmd64
#introscope.agent.platform.monitor.system=LinuxIntelAmd32
#introscope.agent.platform.monitor.system=LinuxIntelAmd64
3.
SAP Netweaver
Platform monitors may not function correctly on SAP Netweaver due to the lack of
permissions for SAP user accounts.
By default, SAP user accounts are not registered under Performance Monitor Users,
which is located by navigating to Computer Management > System Tools > Local Users
and Groups > Groups > Performance Monitor Users . Users registered under
Performance Monitor Users have access to Perfmon related data
(HKEY_PERFORMANCE_DATA).
If you are experiencing problems with SAP Netweaver and Introscope performance
monitoring, this issue can be resolved by adding SAP user account to the Performance
Monitor Users group, then restarting the Windows machine.
Note: When adding a path on a Windows computer, escape the backslash (\) with
another backslash as follows: C:\\Introscope\\lib\\Agent.jar.
To change the location of the IntroscopeAgent.profile
1.
define a system property on the Java command line with the -D option to
specify the full path to the location of the IntroscopeAgent.profile file:
-D com.wily.introscope.agentProfile.
2.
Move your ProbeBuilder directives (PBD and PBL files) to the same location as the
agent profilethey are referenced relative to the profile location.
If you use Sun ONE, then add the new location of the agent profile to the Sun ONE
server.xml file
To change the location of the IntroscopeAgent.profile for Sun ONE
1.
To add Introscope information to the startup scripts for Sun ONE 7.0, log in as
Administrator or Root.
2.
3.
Open the file where you modified the Java command to start the agent.
The location of this file varies depending on the application server you use in your
environment.
2.
Add a -D command to override a property. For example, you can add the following
command to make the agent also use the weblogic-full.pbl file:
-Dintroscope.autoprobe.directivesFile=weblogic-full.pbl
Agent failover
3.
4.
Agent failover
If the Java agent loses connection with its primary Enterprise Manager, the Agent
failover properties specify which Enterprise Manager the agent will failover to, and how
often it will try to reconnect to its primary Enterprise Manager.
introscope.agent.enterprisemanager.connectionorder
Specifies the connection order of backup Enterprise Managers the agent uses if it is
disconnected from its default Enterprise Manager.
Property settings
Names of other Enterprise Managers the agent can connect to.
Default
The Enterprise Manager defined by the DEFAULT host name, port number, and socket
factory properties.
Example
introscope.agent.enterprisemanager.connectionorder=DEFAULT
Notes
You must restart the managed application before changes to this property take
effect.
Agent failover
introscope.agent.enterprisemanager.failbackRetryIntervalInSeconds
Specifies the number of seconds between attempts by a denied agent to reconnect to
these Enterprise Managers:
Notes
Restart the managed application so that changes to this property take effect.
This property is commented out by default.
This property is useful for environments where an agent is allowed to connect across
the following CA APM components:
Clusters.
If an agent can connect to Enterprise Managers in different clusters and this property is
not set, then the following example shows what occurs:
1.
2.
3.
The agent does not know when the allowed Enterprise Manager in Cluster 1
becomes available.
This property enforces the agent to keep trying to connect to its allowed Enterprise
Managers until an Enterprise Manager is available for connection.
The host name of machine running the Enterprise Manager. For more information,
see introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT (see
page 200).
The connection port to the Enterprise Manager Web server. This is the value for the
introscope.enterprisemanager.webserver.port property specified in the
IntroscopeEnterpriseManager.properties for the Enterprise Manager to which the
agent will connect.
The HTTP tunneling socket factory. Specify this client socket factory:
com.wily.isengard.postofficehub.link.net.HttpTunnelingSocketFactory
For more information, see Configuring a proxy server for HTTP tunneling (see page 59).
introscope.agent.enterprisemanager.transport.http.proxy.host
Specifies the proxy server host name.
Default
Commented out; not specified.
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.enterprisemanager.transport.http.proxy.port
Specifies the proxy server port number.
Default
Commented out; not specified.
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.enterprisemanager.transport.http.proxy.username
If the proxy server requires the agent to authenticate it, specifies the user name for
authentication.
Default
Commented out; not specified.
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.enterprisemanager.transport.http.proxy.password
If the proxy server requires the agent to authenticate it, specifies the password for
authentication.
Default
Commented out; not specified.
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT (see
page 201)
introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT
Specifies the host name of the computer running the Enterprise Manager that the agent
connects to by default.
Default
localhost
Example
introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT=localhost
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT
Specifies the port number on the computer that hosts the Enterprise Manager. If you
are using HTTPS tunneling, the default port that listens for connections from the agent is
8444. This property is commented out by default.
Default
8444
Example
introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT=8444
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT
Specifies the client socket factory to use for connections from the agent to the
Enterprise Manager when using HTTPS.
Default
com.wily.isengard.postofficehub.link.net.HttpsTunnelingSocketFactory
Example
introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT=com.wily.i
sengard.postofficehub.link.net.HttpsTunnelingSocketFactory
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.reduceAgentMemoryOverhead
Specifies the agent configuration to use. Uncomment if you want to attempt to reduce
the agent memory overhead by using architectural improvements to the 8.x agent. This
property is not valid for older versions of the agent. This property is set to true and
commented out by default.
Property settings
True or False
Default
True
Example
introscope.agent.reduceAgentMemoryOverhead=true
Notes
You must restart the managed application before changes to this property take effect.
getAgent().IAgent_getMetricRecordingAdministrator.addMetricGroup
String component, collection metrics. The component name is the metric resource
name of the metric group. The metrics must be under the same metric node to
qualify as a group. The metrics are a collection of
com.wily.introscope.spec.metric.AgentMetric data structures. You can only add
AgentMetric data structures to this collection.
getAgent().IAgent_getMetricRecordingAdministrator.getMetricGroup
String component. Based on the component name which is the metric resource
name, you can get the Collection of metrics.
getAgent().IAgent_getMetricRecordingAdministrator.removeMetricGroup
String component. The metric group is removed based on the component which is
the metric resource name.
getAgent().IAgent_getDataAccumulatorFactory.isRemoved
Checks if the metric is removed. You use this interface if you keep an instance of an
accumulator in your extension. If the accumulator is removed because of metric
aging, you use this interface to prevent holding onto a dead reference.
During each heartbeat, a certain set of metrics are checked. This is configurable using
the property introscope.agent.metricAging.dataChunk (see page 205). It is also
important to keep this value low, as a higher value will impact performance. The default
value is 500 metrics to be checked per heartbeat. Each of the 500 metrics is checked to
see if it is a candidate for removal. For example, if you set this property to check chunks
of 500 metrics per heartbeat, and you have a total of 10,000 metrics in the agent
memory, then it will take longer with lower impact on performance to check all 10,000
metrics. However, if you set this property to a higher number, you would check all
10,000 metrics faster, but with possibly high overhead.
A metric is a candidate for removal if the metric has not received new data after certain
period of time. You can configure this period of time using the property
introscope.agent.metricAging.numberTimeslices (see page 205). This property is set to
3000 by default. If a metric meets the condition for removal, then a check is performed
to see if all the metrics in its group are candidates for metric removal. If this
requirement has also been met then the metric is removed.
introscope.agent.metricAging.turnOn
Turns on or off agent metric aging.
Property settings
True or False
Default
True
Example
introscope.agent.metricAging.turnOn=true
Notes
Changes to this property take effect immediately and do not require the managed
application to be restarted.
introscope.agent.metricAging.heartbeatInterval
Specifies the time interval when metrics are checked for removal, in seconds.
Default
1800
Example
introscope.agent.metricAging.heartbeatInterval=1800
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.metricAging.dataChunk
Specifies the number of metrics that are checked during each interval.
Default
500
Example
introscope.agent.metricAging.dataChunk=500
Notes
Changes to this property take effect immediately and do not require the managed
application to be restarted.
introscope.agent.metricAging.numberTimeslices
Specifies the number of intervals to check without any new data before making it a
candidate for removal.
Default
3000
Example
introscope.agent.metricAging.numberTimeslices=3000
Notes
Changes to this property take effect immediately and do not require the managed
application to be restarted.
introscope.agent.metricAging.metricExclude.ignore.0
Excludes specified metrics from being removed. To exclude one or more metrics from
aging, add the metric name or a metric filter to the list.
Property settings
Comma separated list of metrics. You can use an asterisk (*) as a wildcard in metric
names.
Default
The default is metric names beginning with Threads (Threads*).
Example
introscope.agent.metricAging.metricExclude.ignore.0=Threads*
Notes
Changes to this property take effect immediately and do not require the managed
application to be restarted.
introscope.agent.metricClamp
Configures the agent to approximately clamp the number of metrics sent to the
Enterprise Manager.
Default
5000
Example
introscope.agent.metricClamp=5000
Notes
If the property is not set, then no metric clamping occurs. Old metrics will still
report values.
Agent naming
Changes to this property take effect immediately and do not require the managed
application to be restarted.
Agent naming
You can configure properties to obtain the Java agent name for application servers and
much more.
More information:
Understanding the Java Agent name (see page 117)
Agent naming
introscope.agent.agentAutoNamingEnabled
Specifies whether agent autonaming is used to obtain the Java agent name for
supported application servers.
Property settings
True or False
Default
Varies by application server, see Notes below.
Example
introscope.agent.agentAutoNamingEnabled=false
Notes
This property requires the Startup Class to be specified for WebLogic, and requires
the Custom Service to be specified for WebSphere.
You must restart the managed application before changes to this property take
effect.
introscope.agent.agentAutoNamingMaximumConnectionDelayInSeconds
Specifies the amount of time in seconds the agent waits for naming information before
connecting to the Enterprise Manager.
Default
120
Example
introscope.agent.agentAutoNamingMaximumConnectionDelayInSeconds=120
Notes
You must restart the managed application before changes to this property take effect.
Agent naming
introscope.agent.agentAutoRenamingIntervalInMinutes
Specifies the time interval in minutes during which the agent will check to see if it has
been renamed.
Default
10
Example
introscope.agent.agentAutoRenamingIntervalInMinutes=10
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.agentName
Uncomment this property to provide a default agent name if other agent naming
methods fail.
Property settings
For any installation, if the value of this property is invalid or if this property is deleted
from the profile, the agent name will be UnnamedAgent.
Example
#introscope.agent.agentName=AgentName
Notes
You must restart the managed application before changes to this property take
effect.
In the agent profile provided with application server-specific agent installers, the
default reflects the application server, for instance WebLogic Agent.
In the agent profile provided with the default agent installer, the property value is
AgentName, and the line is commented out.
Agent naming
introscope.agent.agentNameSystemPropertyKey
Use this property if you want to specify the agent name using the value of a java system
property.
Default
Not specified.
Example
introscope.agent.agentNameSystemPropertyKey
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.disableLogFileAutoNaming
Specifies whether to disable automatic naming of agent log files when using
AutoNaming options.
Setting this property to true disables the auto-naming of log files for the agent,
AutoProbe and LeakHunter with the agent name or a timestamp.
Property settings
True or False
Default
False
Example
introscope.agent.disableLogFileAutoNaming=false
Notes
You must restart the managed application before changes to this property take
effect.
Log file auto-naming only takes effect when the agent name can be determined
using a Java system property or an application server custom service.
Agent naming
introscope.agent.clonedAgent
Enables you to run identical copies of an application on the same machine. Set this
property to true if you have identical copies of an application running on the same
machine.
Property settings
True or False
Default
False
Example
introscope.agent.clonedAgent=false
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.customProcessName
Specify the process name as it should appear in the Introscope Enterprise Manager and
Workstation.
Default
Varies by application server.
Example
introscope.agent.customProcessName=CustomProcessName
Notes
You must restart the managed application before changes to this property take
effect.
In the agent profile provided with application server-specific agent installers, the
default reflects the application server, for instance "WebLogic."
In the agent profile provided with default agent installer, the property is
commented out.
introscope.agent.defaultProcessName
If no custom process name is provided and the agent is unable to determine the name
of the main application class, this value is used for the process name.
Default
UnknownProcess
Example
introscope.agent.defaultProcessName=UnknownProcess
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.display.hostName.as.fqdn
This property specifies whether the agent name is displayed as a fully qualified domain
name (fqdn). To enable the fully-qualified domain name, set this property value to
'true.' By default, the agent displays the host name.
Note: For the Catalyst integration, set this property to 'true.'
Property settings
True or False
Default
False
Example
introscope.agent.display.hostName.as.fqdn=false
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.bizRecording.enabled
Enables or disables business transaction recording for the agent.
Property settings
True or False
Default
True
Example
introscope.agent.bizRecording.enabled=true
Notes
You must restart the managed application before changes to this property take effect.
To further configure business transaction recording for the agent, see the additional
properties for the application triage map.
More information:
Application triage map (see page 216)
Application triage map business transaction POST parameters (see page 221)
Application triage map managed socket configuration (see page 223)
introscope.agent.thread.all.priority
Controls the priority of agent threads.
Property settings
You can set this from 1 (low) to 10 (high).
Default
Commented out;5.
Example
introscope.agent.thread.all.priority=5
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT
Specifies the host name of the computer running the Enterprise Manager that the agent
connects to by default.
Default
localhost
Example
introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT=localhost
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT
Specifies the port number on the computer that hosts the Enterprise Manager that
listens for connections from the agent.
Default
The default port depends on the type of communication channel you want to configure.
For direct communication between the agent and Enterprise Manager, the default port
is 5001.
Example
introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT=5001
Notes
You must restart the managed application before changes to this property take
effect.
If you want to connect to the Enterprise Manager using HTTPS (HTTP over SSL), the
default port is 8444. If you want to connect to the Enterprise Manager using SSL,
the default port is 5443. However, these default settings are commented out by
default.
introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT
Specifies the default client socket factory to use for connections from the agent to the
Enterprise Manager.
Default
The default socket factory depends on the type of communication channel you want to
configure. For direct communication between the agent and Enterprise Manager, the
default socket factory is as follows:
com.wily.isengard.postofficehub.link.net.DefaultSocketFactory
Example
introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT=com.wily.i
sengard.postofficehub.link.net.DefaultSocketFactory
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.enterprisemanager.transport.tcp.local.ipaddress.DEFAULT
Specifies the IP address of the computer running Enterprise Manager that the agent
connects to by default.
Default
This property is not defined by default.
Example
introscope.agent.enterprisemanager.transport.tcp.local.ipaddress.DEFAULT=<address
>
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.enterprisemanager.transport.tcp.local.port.DEFAULT
Specifies the local port of the computer running Enterprise Manager that the agent
connects to by default.
Default
This property is not defined by default.
Example
introscope.agent.enterprisemanager.transport.tcp.local.port.DEFAULT=CA Portal
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.appmap.enabled
Enables or disables the tracking of monitored code for the application triage map.
Property settings
True or False
Default
True
Example
introscope.agent.appmap.enabled=true
Notes
Enabled by default.
introscope.agent.appmap.metrics.enabled
Enables or disables the tracking of metrics for application triage map nodes.
Property settings
True or False
Default
False
Example
introscope.agent.appmap.metrics.enabled=false
Notes
This property is commented out by default.
introscope.agent.appmap.queue.size
Sets the buffer size for the application triage map.
Property settings
Positive integers.
Default
1000
Example
introscope.agent.appmap.queue.size=1000
Notes
introscope.agent.appmap.queue.period
Sets the frequency in milliseconds for sending application triage map data to the
Enterprise Manager.
Property settings
Positive integers.
Default
1000
Example
introscope.agent.appmap.queue.period=1000
Notes
introscope.agent.appmap.intermediateNodes.enabled
Enables or disables the ability to include intermediate nodes between the application
frontend and backend nodes.
Property settings
True or False
Default
False
Example
#introscope.agent.appmap.intermediateNodes.enabled=true
Notes
Changes to this property takes effect immediately and do not require the managed
application to be restarted.
If you set this property to true, you may experience a slowdown of agent
performance.
2.
Note: The default value is undefined. When this property is not set, the agent
assigns the first available network interface as the primary interface. You can use
the Network Interface utility to determine the name value for this property.
3.
4.
More information:
Using the Network Interface Utility (see page 329)
introscope.agent.bizdef.matchPost
This property determines when POST parameters are matched.
Property settings
The valid settings for this property are never, before, or after.
Set the property to never for full agent functionality and better performance. This
setting allows your application to identify all business transactions using URLs,
cookies or header parameters, but will fail to match any business transactions that
are identified solely through POST parameters.
Set the property to before to get full agent performance. This setting allows
applications to use POST parameters to identify some or all business transactions,
but never access the servlet stream directly for HTTP form requests. New
applications deployed must also conform to standard API when this property is set
to before.
Important! Setting this property to before could have potentially hazardous
repercussions for your applications. Review this property setting with a CA
Technologies representative before implementation.
Set the property to after to safely match business transactions with POST
parameters, but with limited agent functionality. When this property is set to after,
the agent will not be able to map business transactions that are identified by POST
parameters across processes, or produce full sets of metrics for them. This setting
also consumes slightly more CPU time compared to the other options, but is
considered the safest setting if one needs the POST parameter functionality. It
allows applications to use POST parameters to identify some or all business
transactions and cannot guarantee that the servlet stream is never accessed
directly.
Example
introscope.agent.bizdef.matchPost=after
Notes
never - never attempt to match POST parameters. This is the fastest option but may
result in inaccurate business transaction component matching.
after - matches POST parameter patterns after the servlet has executed. Cross
process mapping and some metrics will not be available. Default setting for the
parameter.
Known limitations
The metrics defined using agent recording are displayed in the application triage map in
the Investigator. When configuring agent recording, there are some known limitations
when using regular expressions. Most of the limitations have to do with POST
parameters.
The known limitations are:
Line terminators (.) are not supported for POST parameter values.
Some versions of JBoss and Tomcat might save header keys as lower case values
which makes the caseSensitiveName attribute not work properly for
HEADER_TYPEs.
Note: For more information on agent recording, see the CA APM Transaction Definition
Guide.
See the CA APM Workstation User Guide for more information on how to use the
application triage map.
introscope.agent.sockets.managed.reportToAppmap
Enables managed sockets to appear in application triage map.
Property settings
True or False
Default
True
Example
introscope.agent.sockets.managed.reportToAppmap=true
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.sockets.managed.reportClassAppEdge
Enables managed sockets to report class level application edges to the application triage
map.
Property settings
True or False
Default
False
Example
introscope.agent.sockets.managed.reportClassAppEdge=false
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.sockets.managed.reportMethodAppEdge
Enables managed sockets to report method level application edges to the application
triage map.
Property settings
True or False
Default
True
Example
introscope.agent.sockets.managed.reportMethodAppEdge=true
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.sockets.managed.reportClassBTEdge
Enables managed sockets to report class level business transaction edges to the
application triage map.
Property settings
True or False
Default
False
Example
introscope.agent.sockets.managed.reportClassBTEdge=false
Notes
You must restart the managed application before changes to this property take effect.
AutoProbe
introscope.agent.sockets.managed.reportMethodBTEdge
Enables managed sockets to report method level business transaction edges to the
application triage map.
Property settings
True or False
Default
True
Example
introscope.agent.sockets.managed.reportMethodBTEdge=true
Notes
You must restart the managed application before changes to this property take effect.
AutoProbe
The following properties configure AutoProbe:
introscope.autoprobe.directivesFile
Specifies ProbeBuilder directives files for AutoProbe.
Default
Varies by installer.
Notes
You must restart the managed application before changes to this property take
effect.
AutoProbe
introscope.autoprobe.enable
Enables or disables inserting probes into bytecode automatically.
Property settings
True or False
Default
True
Example
introscope.autoprobe.enable=true
Notes
When this property is set to false, it turns off the automatic insertion of Probes into an
applications bytecode. It does not turn off the agent or agent reporting.
introscope.autoprobe.logfile
Introscope AutoProbe always attempts to log the changes it makes. Set this property to
move the location of the log file to something other than the default.
Property settings
Absolute file paths, or non-absolute paths. Non-absolute names are resolved relative to
the location of this properties file
Default
../../logs/AutoProbe.log
Example
introscope.autoprobe.logfile=../../logs/AutoProbe.log
Notes
You must restart the managed application before changes to this property take
effect.
To disable AutoProbe logging, modify the value as shown in the following example:
introscope.autoprobe.logfile=logs/AutoProbe.log
The Bootstrap Classes Instrumentation Manager instruments a set of classes after the
agent bootstrap, allowing easy implementation of tracers for Java NIO and Secure
Sockets Layer (SSL), as well as improving agent performance. You can disable this
property by commenting it out in the IntroscopeAgent.profile.
introscope.bootstrapClassesManager.enabled
Enables or disables the bootstrap manager.
Property settings
True or False
Default
True
Example
introscope.bootstrapClassesManager.enabled=true
Notes
This property only functions with JVMs running Java 1.5 or higher.
You must restart the managed application before changes to this property take
effect.
introscope.bootstrapClassesManager.waitAtStartup
Sets the time, in seconds, for how long the agent waits after startup to instrument
bootstrap classes.
Property settings
Time, in seconds
Default
Example
introscope.bootstrapClassesManager.waitAtStartup=5
Notes
This property only functions with JVMs running Java 1.5 or higher.
When this property is active, it can overrule classes that have been designated as
skipped. If skipped classes are being instrumented, please contact your CA
Technologies representative, or CA Support.
introscope.autoprobe.directivesFile
You need to enable ServletHeaderDecorator / HTTPHeaderDecorator and CEMTracer
through the directivesFile property configuration.
The directives file property specifies where to find the directive files (PBD) or directive
lists (PBL) for AutoProbe.
AutoProbe uses directives to Introscope-enable your applications, and to determine
which metrics the agents report to the Enterprise Manager.
Settings
Depends on the agent application server installed, with the format of
<appserver>-full.pbl or <appserver>-typical.pbl.
Default
default-typical.pbl
Example
introscope.autoprobe.directivesFile=weblogic-typical.pbl
Notes
Although you can simply add "ServletHeaderDecorator.pbd" or
"httpheaderdecorator.pbd" to the end of this property list, it is better practice to:
1.
Locate the PBL file specified in the property (in the example above,
weblogic-typical.pbl).
2.
3.
4.
5.
introscope.agent.remoteagentconfiguration.allowedFiles
Identifies the files that are allowed to be copied remotely from any machine to the
agent directory.
The Enterprise Manager uses the file name in this property to identify the valid CA CEM
domain configuration file to send to the agents. The domain configuration file contains
the CA CEM business service and transactions definitions.
See Notes (below) for CA CEM release-specific information.
Settings
Can be any valid file name.
Default
domainconfig.xml
Example
introscope.agent.remoteagentconfiguration.allowedFiles=domainconfig.xml
Notes
This property can also be used by the Introscope Command-Line Workstation (CLW)
Send Config File command.
For more information, see Using the Command-Line Workstation.
This property is valid for CA CEM releases. It is also valid with , CA CEM 4.2 / 4.5 only
when you have selected the CEMTracer 4.0 / 4.1 Support option on the Introscope
Settings page.
The CEMTracer 4.0 / 4.1 Support option allows you to stagger your agent migration from
4.0 or 4.1 to 4.2 / 4.5 over time; use only if required.
introscope.agent.remoteagentconfiguration.enabled
If this Boolean value is set to true, it allows remote file copies to the agent from another
computer.
The Enterprise Manager requires this property to be set to true in order to send the CA
CEM domain configuration file to the agents. The domain configuration file contains the
CA CEM business service and transactions definitions.
See Notes (below) for CA CEM release-specific information.
Settings
true or false
Default
Example
introscope.agent.remoteagentconfiguration.enabled=true
Notes
A remote user can also use the Introscope Command-Line Workstation (CLW) Send
Config File command to copy the file or files specified in the
introscope.agent.remoteagentconfiguration.allowedFiles property into the agent
directory.
For more information, see Using the Command-Line Workstation.
This property is valid for CA CEM 4.0 and 4.1 releases. It is also valid with CA CEM 4.2 /
4.5 only when you have selected the CEMTracer 4.0 / 4.1 Support option on the
Introscope Settings page.
The CEMTracer 4.0 / 4.1 Support option allows you to stagger your agent migration from
4.0 or 4.1 to 4.2 / 4.5 over time; use only if required.
For non-compatible agents (that is, a .NET agent prior to 7.2.2, an EPA agent, or other
non-Java agent), set the introscope.agent.remoteagentconfiguration.enabled property
to false.
introscope.agent.decorator.enabled
If this Boolean value is set to true, it configures the agent to add additional performance
monitoring information to HTTP response headers. ServletHeaderDecorator /
HTTPHeaderDecorator attaches the GUID to each transaction and inserts the GUID into
an HTTP header, x-apm-info.
This enables the correlation of transactions between CA CEM and CA Introscope.
Settings
True or false
Default
Example
introscope.agent.decorator.enabled=false
introscope.agent.decorator.security
Determines the format of decorated HTTP response headers, which are sent to CA CEM.
Settings
Default
clear
Example
introscope.agent.decorator.security=clear
Notes
The default setting of clear is appropriate for initial testing, but might reveal information
in the transaction header that you do not want known beyond the firewall. Set the
property to encrypted for a more secure production environment.
You must be using JVM 1.4 or greater to set this property to encrypted.
introscope.agent.cemtracer.domainconfigfile
The name of the CA CEM domain configuration file that specifies the CA CEM business
service and transaction hierarchy. CEMTracer looks for a file with this name in its
installation directory.
Each time a CA CEM administrator clicks Synchronize All Monitors in CA CEM, the
domain configuration file gets pushed to the Enterprise Manager, which in turn pushes
the file to each connected agent.
See Notes (below) for CA CEM release-specific information.
Settings
Can be any valid file name.
Default
domainconfig.xml
Example
introscope.agent.cemtracer.domainconfigfile=domainconfig.xml
Notes
This property is valid for CA CEM 4.0 and 4.1 releases. It is also valid with CA CEM 4.2 /
4.5 only when you have selected the CEMTracer 4.0 / 4.1 Support option on the
Introscope Settings page.
The CEMTracer 4.0 / 4.1 Support option allows you to stagger your agent migration from
4.0 or 4.1 to 4.2 / 4.5 over time; use only if required.
If the agent directory is read-only, the domain configuration file cannot be written.
If CEMTracer 4.0 / 4.1 is not enabled on the agent, then no action will be taken on
the domain configuration file once it is sent.
introscope.agent.cemtracer.domainconfigfile.reloadfrequencyinminutes
The frequency, in minutes, that the agent reloads the domain configuration file. (The 4.0
/ 4.1 agent does not automatically reload the domain configuration file every time the
Enterprise Manager sends it. If it has not changed, the agent will not reload it.)
Notes
This property is valid for CA CEM 4.0 and 4.1 releases. It is also valid with CA CEM 4.2 /
4.5 only when you have selected the CEMTracer 4.0 / 4.1 Support option on the
Introscope Settings page.
The CEMTracer 4.0 / 4.1 Support option allows you to stagger your agent migration from
4.0 or 4.1 to 4.2 over time; use only if required.
2.
3.
ChangeDetector configuration
ChangeDetector configuration
You can control how the local agent works with ChangeDetector.
Note: For more information about using ChangeDetector, see the CA APM
ChangeDetector User Guide.
introscope.changeDetector.enable
Specifies whether ChangeDetector is enabled or disabled. Set the property to true to
enable ChangeDetector. It is commented out and set to false by default. If you enable
ChangeDetector, you should also set the additional ChangeDetector-related properties.
Property settings
True or False
Default
False
Example
introscope.changeDetector.enable=false
Notes
You must restart the managed application before changes to this property take effect.
introscope.changeDetector.agentID
Specifies the text string used by ChangeDetector to identify the local agent. This
property is commented out by default. If you enable ChangeDetector, you should
uncomment this property and set it to an appropriate value.
Default
The default value is SampleApplicationName.
Example
introscope.changeDetector.agentID=SampleApplicationName
ChangeDetector configuration
introscope.changeDetector.rootDir
Specifies the root directory for ChangeDetector files. The root directory is the folder
where ChangeDetector creates its local cache files.
Property settings
Full path to the root directory for ChangeDetector files as a text string.
Default
The default path is c://sw//AppServer//wily//change_detector.
Example
introscope.changeDetector.rootDir=c://sw//AppServer//wily//change_detector
Notes
Use a backslash to escape the backslash character, as in the example.
introscope.changeDetector.isengardStartupWaitTimeInSec
Specifies the number of seconds to wait after the agent starts before ChangeDetector
tries to connect to the Enterprise Manager. This property is commented out by default.
Default
The default is 15 seconds.
Example
introscope.changeDetector.isengardStartupWaitTimeInSec=15
introscope.changeDetector.waitTimeBetweenReconnectInSec
Specifies the number of seconds ChangeDetector waits before retrying a connection to
the Enterprise Manager. This property is commented out by default.
Default
The default is 10 seconds.
Example
introscope.changeDetector.waitTimeBetweenReconnectInSec=10
ChangeDetector configuration
introscope.changeDetector.profile
Specifies the absolute or relative path to the ChangeDetector datasources configuration
file. This property is commented out by default.
Default
The default is ChangeDetector-config.xml.
Example
introscope.changeDetector.profile=CDConfig\\ChangeDetector-config.xml
Notes
Use a backslash to escape the backslash character, as in the example.
introscope.changeDetector.profileDir
Specifies the absolute or relative path to the directory that contains datasource
configuration files. If this property is set, all of the datasource configuration files in this
directory are used in addition to any file specified by the
introscope.changeDetector.profile property. This property is commented out by default.
Default
The default is changeDetector_profiles.
Example
introscope.changeDetector.profileDir=c:\\CDconfig\\changeDetector_profiles
Notes
Use a backslash to escape the backslash character.
introscope.changeDetector.compressEntries.enable
Specifies whether to allow compression on the ChangeDetector data buffer. You can set
this property to true if you experience memory consumption at start-up to improve
performance.
Property settings
True or False
Default
The default value is false if the property is not set in the agent profile or if commented
out.
Example
introscope.changeDetector.compressEntries.enable=true
Notes
You must restart the managed application before changes to this property take effect.
introscope.changeDetector.compressEntries.batchSize
This property defines the batch size for the compression job, set in
introscope.changeDetector.compressEntries.enable above.
Default
1000
Example
introscope.changeDetector.compressEntries.batchSize=1000
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.weblogic.crossjvm
Property settings
True or False
Default
Commented out; True
Example
introscope.agent.weblogic.crossjvm=true
Enabling this property and running long periods of Transaction Trace session with tail
filters can cause large numbers of unwanted traces to be sent to the Enterprise
Manager.
introscope.agent.transactiontracer.tailfilterPropagate.enable
Controls whether the presence of a tail filter triggers automatic collection of traces from
downstream agents or not. This property does not affect collection of automatic
downstream traces due to passing of head filters.
Property settings
True or False
Default
False; commented out.
Example
introscope.agent.transactiontracer.tailfilterPropagate.enable=false
Notes
Changes to this property take effect immediately and do not require the managed
application to be restarted.
Dynamic instrumentation
Dynamic instrumentation
You can enable classes and methods to be instrumented dynamically without writing
custom PBDs, restarting the application server, or restarting the agent.
Note: For more information about using Transaction Tracing and dynamic
instrumentation from the Introscope Workstation, see the CA APM Workstation User
Guide.
introscope.autoprobe.dynamicinstrument.enabled
Enables dynamic ProbeBuilding for agents that run under JDK 1.5, and use AutoProbe.
Property settings
True or False
Default
False
Example
introscope.autoprobe.dynamicinstrument.enabled=false
Notes
Note: For more information about dynamic ProbeBuilding, see Dynamic ProbeBuilding
(see page 73).
autoprobe.dynamicinstrument.pollIntervalMinutes
For agents that run under JDK 1.5 using AutoProbe and dynamic ProbeBuilding, this
property determines the frequency with which the agent polls for new and changed
PBDs.
Default
1
Example
autoprobe.dynamicinstrument.pollIntervalMinutes=1
Dynamic instrumentation
introscope.autoprobe.dynamicinstrument.classFileSizeLimitInMegs
Some classloader implementations have been observed to return huge class files.This is
to prevent memory errors.
Default
1
Example
introscope.autoprobe.dynamicinstrument.classFileSizeLimitInMegs=1
Notes
You must restart the managed application before changes to this property take effect.
introscope.autoprobe.dynamic.limitRedefinedClassesPerBatchTo
Re-defining too many classes at a time might be very CPU intensive. In cases where the
changes in PBDs trigger a re-definition of a large number of classes, this batches the
process at a comfortable rate.
Default
10
Example
introscope.autoprobe.dynamic.limitRedefinedClassesPerBatchTo=10
Dynamic instrumentation
introscope.agent.remoteagentdynamicinstrumentation.enabled
Enables or disables remote management of dynamic instrumentation.
Property settings
True or False
Default
True
Example
introscope.agent.remoteagentdynamicinstrumentation.enabled=true
Notes
You must restart managed applications before changes to this property take effect.
If you enabled dynamic instrumentation for applications using multiple CLRs within
the same process, such as in-process side-by-side execution, you must specify the
CLR version in the
com.wily.introscope.nativeprofiler.monitor.inprocsxs.multiple.clrs property.The
valid values are:
V2 (CLR 2.0)
V4 (CLR 4.0)
introscope.autoprobe.dynamicinstrument.pollIntervalMinutes
Defines the polling interval in minutes to poll for PBD changes.
Default
1
Example
introscope.autoprobe.dynamicinstrument.pollIntervalMinutes=1
Notes
You must restart the managed application before changes to this property take effect.
ErrorDetector
ErrorDetector
You can control how the agent interacts with ErrorDetector.
introscope.agent.errorsnapshots.enable
Enables the agent to capture transaction details about serious errors. Introscope
ErrorDetector is installed by default with the agent. This property must be set to true for
error snapshots to be available for viewing.
Property settings
True or False
Default
True
Notes
This property is dynamic. You can change the configuration of this property during run
time and the change will be picked up automatically.
introscope.agent.errorsnapshots.throttle
Specifies the maximum number of error snapshots that the agent can send in a
15-second period.
Default
10
Example
introscope.agent.errorsnapshots.throttle=10
Notes
This property is dynamic. You can change the configuration of this property during run
time and the change will be picked up automatically.
Extensions
introscope.agent.errorsnapshots.ignore.<index>
Specifies one or more error message filters. You can specify as many filters as you need
using the index identifier appended to the property name (for example, .0, .1, .2 ...). You
can use wildcards (*) Error messages matching the criteria you specify are ignored. No
error snapshots are generated for errors matching the filters you define and no error
events are sent to the Enterprise Manager for them.
Default
Example definitions are provided, and commented out, as shown below.
Example
introscope.agent.errorsnapshots.ignore.0=*com.company.HarmlessException*
introscope.agent.errorsnapshots.ignore.1=*HTTP Error Code: 404*
Notes
This property is dynamic. You can change the configuration of this property during run
time and the change will be picked up automatically.
Extensions
You can configure the location of agent extensions.
introscope.agent.extensions.directory
Specifies the location of all extensions to be loaded by the agent. You can specify an
absolute or relative path to the directory. If you do not specify an absolute path, the
value you specify is resolved relative to the location of the IntroscopeAgent.profiles file.
Default
The default location is ext directory in the <Agent_Home>/ext directory.
Example
introscope.agent.extensions.directory=../ext
Notes
You must restart the managed application before changes to this property take effect.
GC Monitor
introscope.agent.common.directory
Configures the location of Agent Extension related files.
Default
The default location is common folder in the <Agent_Home>/common directory.
Example
introscope.agent.common.directory=../../common
GC Monitor
The metrics under the GC Monitor node report information on Garbage Collectors and
Memory Pools. These metrics help you detect memory-related issues that are adversely
affecting performance. You must manually enable the collection of these metrics in the
agent profile.
introscope.agent.gcmonitor.enable
Enables or disables the metrics for Garbage Collectors and Memory Pools. This features
requires the agent to be version 9.0 or later. It is not supported for older versions of the
agents.
Property settings
True or False
Default
The default value is true.
Example
introscope.agent.gcmonitor.enable=true
Notes
This property is dynamic. You can change the configuration of this property during run
time and the change is picked up automatically.
You can only report GC Monitor metrics for agents that monitor Sun or IBM JVMs and
are Introscope version 9.x and above.
Java NIO
Java NIO
The Java Agent supports the Java New I/O (Java NIO, or NIO) capabilities introduced in
Java 1.4. Java NIO is a collection of APIs designed to provide access to the low-level I/O
operations of modern operating systems. Java NIO metrics capture information about
how instrumented applications use Java NIO.
Note: Introscope Java NIO metrics are only available on Java 1.5 JVMs or higher. Metric
collection of Java NIO information is not available for JVM versions prior to Java 1.5.
The Introscope Java Agent collects metrics for NIO channels. For more information, see
Channels (see page 247).
You can restrict the generation of certain NIO metrics. For more information, see
Restricting Java NIO metrics (see page 248).
Java NIO tracer groups have been enabled by default. You can turn off these tracer
groups to further restrict metric generation. For more information on turning on and off
Java NIO tracer groups, see Default tracer groups and toggles files (see page 86).
Buffers
Java NIO data transfer is based on buffers. Buffer classes represent memory in a
continuous block, together with a small number of data transfer operations. There are
buffer classes for all of Java's primitive types, except boolean, which can share memory
with byte buffers and allow arbitrary interpretation of the underlying bytes.
Metrics for the following buffer types are collected separately and displayed in the
Workstation Investigator:
Byte Buffer
Int Buffer
Double Buffer
Long Buffer
Float Buffer
Short Buffer
These groupings are further divided into different buffer types. Because buffers may
overlap, the Total Capacity (bytes) metric may overestimate the amount of memory
allocated to NIO buffers.
Java NIO
Direct and non-direct buffers are collected separately because of their differences in
memory location and relative costs for creation. Direct buffers are allocated outside the
JVM heap used for Java objects, so are not subject to Java garbage collection and
relocation. This makes direct buffers optimal for I/O, but they may take more resources
to create. Nondirect buffers, by contrast, are allocated as any normal Java object within
the JVM heap.
Note: All buffer types may be either direct or non direct, except memory mapped files
which are only direct buffers.
Channels
Java NIO channels provide bulk data transfers to and from NIO buffers, as well as
external systems. This is a low-level data transfer mechanism that was specifically
designed to address performance and scalability issues within standard Java I/O.
Channels provide mechanisms for moving bytes between buffers and external systems.
Introscope channel metrics characterize data flow rates through channels. Collected NIO
channel metrics correspond to metrics currently created for file and socket I/O using
standard Java I/O techniques. Metrics for the following channel types are collected
separately and displayed in the Workstation Investigator:
Datagram Channels
Socket Channels
NIODatagramTracing metrics
Although UDP is a connection-less protocol, the term "connection" is used in the
description of NIODatagramTracing to describe how the Java Agent collects datagram
metrics. The Java Agent collects metrics separately for each remote endpoint datagrams
that are sent to or received from. Connections are classified as client or server
depending on the direction of the first datagram observed from each to or from
endpoint.
For example, if the first datagram is from the endpoint, the Java Agent classifies all
further datagrams to or from that endpoint under
NIO|Channels|Datagrams|Server|Port {PORT}, where {PORT} is the local port.
If the first datagram is to the endpoint, all further datagrams to or from that endpoint
are classified under NIO|Channels|Datagrams|Client|{HOST}|Port {PORT}, where
{HOST} and {PORT} are the remote endpoint.
Java NIO
The Java Agent also generates backend metrics for client "connections", except in the
case of datagrams read by the 'receive' method. Datagram channels created using
DatagramChannel connect method are considered client connections irrespective of
direction of first datagram observed.
Note: Datagram channels created using a UDP connection (with a connect method) are
considered client connections.
introscope.agent.nio.datagram.client.hosts
Restricts metric reporting to 'client' UDP "connections" with specified host(s).
Property settings
Comma separated list of hosts.
Default
undefined (no value)
Example
introscope.agent.nio.datagram.client.hosts=hostA,hostB
Notes
Invalid host names will be reported in the agent log and ignored.
This property is dynamic. You can change the configuration of this property during
run time and the change will be picked up automatically.
Duplicate host names are discarded. In cases where multiple host names map to a
single IP, only one of the names is retained. The property will, however, match
client connections with any of the set of synonymous names.
Java NIO
introscope.agent.nio.datagram.client.ports
Lists the ports that will report NIO metrics. Only 'client' datagram metrics for specified
ports will be generated.
Property settings
Comma separated list of port numbers. Port is the remote port to/from which
datagrams are sent/received.
Default
undefined (no value)
Example
introscope.agent.nio.datagram.client.ports=123,456,789
Notes
Invalid port numbers will be reported in the agent log and ignored.
This property is dynamic. You can change the configuration of this property during
run time and the change will be picked up automatically.
Duplicate ports are discarded. In cases where multiple ports map to a single IP, only
one of the ports is retained.
Java NIO
introscope.agent.nio.datagram.server.ports
Lists the ports that will report NIO metrics. Only 'server' datagram metrics for specified
ports will be generated.
Property settings
Comma separated list of port numbers. Port is the local port through which datagrams
are sent/received.
Default
undefined (no value)
Example
introscope.agent.nio.datagram.server.ports=123,456,789
Notes
Invalid port numbers will be reported in the agent log and ignored.
This property is dynamic. You can change the configuration of this property during
run time and the change will be picked up automatically.
introscope.agent.nio.socket.client.hosts
Restricts metric reporting to 'client' TCP "connections" with specified host(s).
Property settings
Comma separated list of hosts.
Default
undefined (no value)
Example
introscope.agent.nio.socket.client.hosts=hostA, hostB
Notes
Invalid host names will be reported in the agent log and ignored.
This property is dynamic. You can change the configuration of this property during
run time and the change will be picked up automatically.
Java NIO
introscope.agent.nio.socket.client.ports
Lists the ports that will report NIO metrics. Only 'client' socket metrics for specified
ports will be generated.
Property settings
Comma separated list of port numbers. Port is the remote port to/from which
datagrams are sent/received.
Default
undefined (no value)
Example
introscope.agent.nio.socket.client.ports=123,456,789
Notes
Invalid port numbers will be reported in the agent log and ignored.
This property is dynamic. You can change the configuration of this property during
run time and the change will be picked up automatically.
introscope.agent.nio.socket.server.ports
Lists the ports that will report NIO metrics. Only 'server' socket metrics for specified
ports will be generated.
Property settings
Comma separated list of port numbers. Port is the local port through which datagrams
are sent/received.
Default
undefined (no value)
Example
introscope.agent.nio.socket.client.ports=123,456,789
Notes
Invalid port numbers will be reported in the agent log and ignored.
This property is dynamic. You can change the configuration of this property during
run time and the change will be picked up automatically.
JMX
Java NIO metrics appear under the NIO node under the agent's top level node in the
Workstation Investigator. Additional NIO metrics for any 'client' connections will appear
under the Backends node.
Individual NIO metrics may be suppressed by commenting out the
TraceOneMethodIfFlagged or TraceOneMethodWithParametersIfFlagged directives for
the metric(s) to be suppressed. However, no tracers whose name ends with
BackendTracer or MappingTracer should be commented out.
For example, to suppress the Concurrent Readers metric for Datagrams, comment out:
TraceOneMethodWithParametersIfFlagged: NIODatagramTracing read
NIODatagramConcurrentInvocationCounter "Concurrent Readers"
JMX
The following properties configure JMX metrics:
introscope.agent.jmx.enable
Enables collection of JMX Metrics.
Property settings
True or False.
Default
Varies by agent version.
Example
introscope.agent.jmx.enable=false
Notes
You must restart the managed application before changes to this property take effect.
JMX
introscope.agent.jmx.ignore.attributes
Controls which (if any) JMX MBean attributes are to be ignored.
Property settings
A comma-separated list of keywords.
Default
Commented out; server.
Example
introscope.agent.jmx.ignore.attributes=server
Notes
If an MBean attribute name matches one on the list, the attribute will be ignored.
You must restart the managed application before changes to this property take
effect.
introscope.agent.jmx.name.filter
Specifies a comma-separated list of filter strings to determine what JMX data Introscope
collects and displays.
Introscope reports JMX-generated metrics that match a filter string. Filter strings can
contain the asterisk (*) and question mark (?) wildcard characters:
ab*c matches a metric name that contains abc, abxc, abxxc etc.
JMX
Default
Commented out.
For WebLogic:
ActiveConnectionsCurrentCount,WaitingForConnectionCurrentCount,PendingRequestCurr
entCount,ExecuteThreadCurrentIdleCount,OpenSessionsCurrentCount,j2eeType
Example
#introscope.agent.jmx.name.filter=ActiveConnectionsCurrentCount,WaitingForConnect
ionCurrentCount,PendingRequestCurrentCount,ExecuteThreadCurrentIdleCount,OpenSess
ionsCurrentCount,j2eeType
Notes
You must restart the managed application before changes to this property take
effect.
introscope.agent.jmx.name.jsr77.disable
This property controls whether or not Introscope collects and reports full JSR77 data,
including complex JMX data.
This property is only available for use in the WebLogic and WebSphere
IntroscopeAgent.profile files.
Property settings
True or False
Default
True
Notes
You must restart the managed application before changes to this property take
effect.
JMX
introscope.agent.jmx.name.primarykeys
User-defined order of MBean information, and simplifies name conversion.
Property settings
A comma-separated, ordered list of keys which should uniquely identify a particular
MBean.
Default
Commented out in default IntroscopeAgent.profile file.
Example
introscope.agent.jmx.name.primarykeys=J2EEServer
Notes
Type
Name
J2EEServer
Application
j2eeType
JDBCProvider
name
mbeanIdentifier
You must restart the managed application before changes to this property take
effect.
LeakHunter
introscope.agent.jmx.excludeStringMetrics
Controls whether or not to include string-valued metrics. To enable string-valued
metrics, set this property value to false.
Property settings
True or False
Default
True
Example
introscope.agent.jmx.excludeStringMetrics=true
Notes
Excluding string-valued metrics reduces the overall metric count, improving agent
and EM performance.
You must restart the managed application before changes to this property take
effect.
LeakHunter
The following properties configure agent interaction with LeakHunter:
LeakHunter
introscope.agent.leakhunter.collectAllocationStackTraces
Controls whether LeakHunter generates allocation stack traces for potential leaks.
Setting this property to true gives you more precise data about the potential leak's
allocation, but requires additional memory and CPU overhead. For this reason, the
default is false.
Property settings
True or False
Default
False
Example
introscope.agent.leakhunter.collectAllocationStackTraces=
false
Notes
Setting this property to true has the potential to create higher system overhead, in
CPU usage and memory.
This property is dynamic. You can change the configuration of this property during
run time and the change will be picked up automatically.
LeakHunter
introscope.agent.leakhunter.enable
Controls whether the LeakHunter feature is enabled. Set the value to true to enable
LeakHunter.
Property settings
True or False
Default
False
Example
introscope.agent.leakhunter.enable=false
Notes
Turning on this option has the potential to create higher CPU and memory usage.
You should only enable this feature when other metrics suggest there is a memory
leak.
You must restart the managed application before changes to this property take
effect.
introscope.agent.leakhunter.leakSensitivity
Controls the sensitivity level of the LeakHunter leak detection algorithm. A higher
sensitivity setting will result in more potential leaks reported and a lower sensitivity will
result in fewer potential leaks reported.
Property settings
The leak sensitivity range must be positive integer value from 1 (low) to10 (high).
Default
5
Example
introscope.agent.leakhunter.leakSensitivity=5
Notes
You must restart the managed application before changes to this property take effect.
LeakHunter
introscope.agent.leakhunter.logfile.append
Specifies whether to replace the log file or add information to an existing log file on
application restart.
Property settings
True or False
Default
False
Example
introscope.agent.leakhunter.logfile.append=false
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.leakhunter.logfile.location
Controls the location for the LeakHunter.log file. You can specify an absolute or relative
path to the file name. Relative paths resolve relative to the <Agent_Home> directory.
Leave the value blank or commented out if you do not want LeakHunter to record data
in a log file.
Default
The default path is ../../logs/LeakHunter.log. This locates the log file in the
<Agent_Home>logs directory.
Example
introscope.agent.leakhunter.logfile.location=../../logs/LeakHunter.log
Notes
You must restart the managed application before changes to this property take effect.
LeakHunter
introscope.agent.leakhunter.timeoutInMinutes
Controls the length of time (in minutes) that LeakHunter spends looking for new
potential leaks. After the time specified, LeakHunter stops looking for new potential
leaks. It continues tracking the previously identified potential leaks.
Property settings
Must be a positive integer (no negative numbers).
Default
The default is 120 minutes.
Example
introscope.agent.leakhunter.timeoutInMinutes=120
Notes
Set the value to zero if you want LeakHunter to always look for new potential leaks.
You must restart the managed application before changes to this property take
effect.
introscope.agent.leakhunter.ignore.<number>
Use this to ignore any class matching any supplied patterns. Ten classes have been
supplied by default - comment out any you want to use.
Property settings
A comma-separated list of class matching patterns.
Default
None
Logging
Example
introscope.agent.leakhunter.ignore.4=java.util.SubList
introscope.agent.leakhunter.ignore.5=com.sun.faces.context.BaseContextMap$EntrySe
t
introscope.agent.leakhunter.ignore.6=com.sun.faces.context.BaseContextMap$Key
Notes
This property is dynamic. You can change the configuration of this property during
run time and the change will be picked up automatically.
Logging
The following properties configure agent logging options:
Logging
log4j.logger.IntroscopeAgent
This property controls both the logging level and the output location for log information.
Property settings
Level of detail value can be:
INFO
VERBOSE#com.wily.util.feedback.Log4JSeverityLevel
console
logfile
Default
INFO, console, logfile
Example
log4j.logger.IntroscopeAgent=INFO,console,logfile
Notes
Changes to this property take effect immediately and do not require the managed
application to be restarted.
To disable agent logging, remove the value as shown in the following example:
log4j.logger.IntroscopeAgent=
Logging
log4j.appender.logfile.File
Specifies the name and location of IntroscopeAgent.log file if logfile is specified in
log4j.logger.IntroscopeAgent. The filename is relative to the directory that contains the
agent profile.
Default
IntroscopeAgent.log
Example
log4j.appender.logfile.File=../../logs/IntroscopeAgent.log
Notes
System properties (Java command line -D options) are expanded as part of the file
name. For example, if Java is started with -Dmy.property=Server1, then
log4j.appender.logfile.File=../../logs/Introscope-${my.property}.log is expanded to:
log4j.appender.logfile.File=../../logs/Introscope-Server1.log.
log4j.logger.IntroscopeAgent.inheritance
Controls log level and destination for log messages about classes that require
instrumentation.
Property settings
To configure logging of classes that have not been instrumented because they extend a
supertype or interface, set this property to: INFO, pbdlog
For information about inheritance class logging see Controlling directive logging (see
page 79).
Default
None
Example
log4j.logger.IntroscopeAgent.inheritance=INFO,pbdlog
Logging
log4j.appender.pbdlog.File
Identifies a log file for messages about classes that require instrumentation.
Property settings
To configure logging of classes that have not been instrumented because they extend a
supertype or interface set to: pbdupdate.log
Default
None
Example
log4j.appender.pbdlog.File=../../pbdupdate.log
log4j.appender.pbdlog
Specifies a package for logging messages about classes that require instrumentation.
Property settings
To configure logging of classes that have not been instrumented because they extend a
supertype or interface, set this property to:
com.wily.introscope.agent.AutoNamingRollingFileAppender
Default
None
Example
log4j.appender.pbdlog=com.wily.introscope.agent.AutoNamingRollingFileAppender
Logging
log4j.appender.pbdlog.layout
Specifies rules for logging messages about classes that require instrumentation.
Property settings
To configure logging of classes that have not been instrumented because they extend a
supertype or interface, set this property to: com.wily.org.apache.log4j.PatternLayout
Default
None
Example
log4j.appender.pbdlog.layout=com.wily.org.apache.log4j.PatternLayout
log4j.appender.pbdlog.layout.ConversionPattern
Specifies rules for logging messages about classes that require instrumentation.
Property settings
To configure logging of classes that have not been instrumented because they extend a
supertype or interface, set this property to:
%d{M/dd/yy hh:mm:ss a z} [%-3p] [%c] %m%n
Default
None
Example
log4j.appender.pbdlog.layout.ConversionPattern=%d{M/dd/yy hh:mm:ss a z} [%-3p] [%c]
%m%n
Metric count
log4j.additivity.IntroscopeAgent.inheritance
Causes the directives for multiple level inheritance to be logged only in the
pbdupdate.log file.
Property settings
True or False
Default
True
Example
log4j.additivity.IntroscopeAgent.inheritance=true
Notes
To configure the logging of multiple level inheritance directives in the pbdupdate.log
only, add this property to the agent profile and set to false.
Metric count
The following property affects where you will see the Metric Count metric in the
Investigator:
Multiple inheritance
introscope.ext.agent.metric.count
Controls where you will see the Metric Count metric in the Investigator. By default, the
Metric Count is displayed as under the Custom Metric Agent node. If you want to see the
Metric Count metric under the Agent Stats node, add this property to the
IntroscopeAgent.profile.
Property settings
True or False
Default
Not present in the IntroscopeAgent.profile; False
Example
introscope.ext.agent.metric.count=true
Notes
Add this property to the IntroscopeAgent.profile and set it to true to see the Metric
Count metric under the Agent Stats node.
Multiple inheritance
For directives based on interfaces or super classes, the agent is unable to detect
multiple inheritance and hence those classes are not instrumented. Enable the following
properties to determine those cases after the application server or the agent process
starts up. These properties log classes which need to be instrumented but have not
been and relies on dynamic instrumentation to affect the changes.
Multiple inheritance
introscope.autoprobe.hierarchysupport.enabled
For agents that run under JDK 1.5 using AutoProbe and dynamic instrumentation, you
can use this property to enable instrumentation of classes that extend a supertype or
interface.
Property settings
True or False
Default
True
Example
introscope.autoprobe.hierarchysupport.enabled=true
Notes
You must restart the managed application before changes to this property take effect.
introscope.autoprobe.hierarchysupport.runOnceOnly
If you have enabled instrumentation of classes that extend a supertype or interface, you
can use this property to control whether the utility that enables the feature runs only
once, or at a specified interval.
Change this property to true only if you need detection on a periodic basis.
Property settings
True or False
Default
False
Example
introscope.autoprobe.hierarchysupport.enabled=false
Notes
You must restart the managed application before changes to this property take
effect.
Multiple inheritance
introscope.autoprobe.hierarchysupport.pollIntervalMinutes
The polling interval to check for classes which could not be instrumented due to
multiple inheritance. In most cases this happens only once; however, a conservative
value is recommended to account for application server initialization.
Default
5
Example
introscope.autoprobe.hierarchysupport.pollIntervalMinutes=5
Notes
You must restart the managed application before changes to this property take effect.
introscope.autoprobe.hierarchysupport.executionCount
If you need the polling interval to run a finite times instead of running it only once or
running it periodically, use this property to specify the exact number of times the polling
interval is run. Always use this property to specify the exact number of times it should
run.
Using this property overrides the run once only setting.
Property settings
A positive integer.
Default
3
Example
introscope.autoprobe.hierarchysupport.executionCount=3
Notes
You must restart the managed application before changes to this property take effect.
Platform monitoring
introscope.autoprobe.hierarchysupport.disableLogging
Uncomment this property if you do not need to log the classes being detected. Only
uncomment this property if dynamic instrumentation is enabled.
Property settings
True or False
Default
True
Example
#introscope.autoprobe.hierarchysupport.disableLogging=true
Notes
You must restart the managed application before changes to this property take effect.
introscope.autoprobe.hierarchysupport.disableDirectivesChange
Uncomment this property to only log the changes and disable the triggering of dynamic
instrumentation.
Property settings
True or False
Default
True
Example
introscope.autoprobe.hierarchysupport.disableDirectivesChange=true
Notes
You must restart the managed application before changes to this property take effect.
Platform monitoring
The following property configures platform monitoring metrics:
Remote configuration
introscope.agent.platform.monitor.system
Name of operating system to load a platform monitor for.
Property settings
See Troubleshooting platform monitoring (see page 191) for more information about
the options for this property.
Default
Commented out; varies by platform.
Example
introscope.agent.platform.monitor.system=Solaris
Notes
You must restart the managed application before changes to this property take effect.
Remote configuration
The following properties allow remote configuration of the Java Agent:
introscope.agent.remoteagentconfiguration.enabled
This property enables or disables remote configuration of the agent.
Property settings
True or False
Default
True
Example
introscope.agent.remoteagentconfiguration.enabled=true
Notes
Changes to this property take effect immediately and do not require the managed
application to be restarted.
Security
introscope.agent.remoteagentconfiguration.allowedFiles
This property lists the exact list of files that are allowed to be remotely transferred to
this agent.
Property settings
domainconfig.xml
Default
domainconfig.xml
Example
introscope.agent.remoteagentconfiguration.allowedFiles=domainconfig.xml
Notes
Changes to this property take effect immediately and do not require the managed
application to be restarted.
Security
The following property configures security of HTTP headers being sent to CA CEM:
introscope.agent.decorator.security
This property determines the format of decorated HTTP response headers, which are
sent to CA CEM.
Property settings
Clear: clear text encoding
Encrypted: header data is encrypted
Default
Clear
Example
introscope.agent.decorator.security=clear
introscope.agent.decorator.enabled
If this Boolean value is set to true, it configures the agent to add additional performance
monitoring information to HTTP response headers. ServletHeaderDecorator attaches
the GUID to each transaction and inserts the GUID into an HTTP header, for example:
x-apm-info
Property settings
True or False
Default
False
Example
introscope.agent.decorator.enabled=false
Socket metrics
Generation of I/O Socket metrics may be restricted by the following parameters:
Socket metrics
introscope.agent.sockets.reportRateMetrics
Enables reporting of individual socket's input/output (I/O) bandwidth rate metrics.
Property settings
True or False
Default
False
Example
introscope.agent.sockets.reportRateMetrics=false
Notes
You must restart the managed application before changes to this property take
effect.
introscope.agent.io.socket.client.hosts
Restrict socket client connections instrumented to those with specified remote hosts.
Property settings
A comma-separate list of values.
Example
introscope.agent.io.socket.client.hosts=
Notes
If any parameter is not defined, or after exclusion of any invalid values is an empty
list, no restriction will apply to that parameter.
This property is dynamic. You can change the configuration of this property during
run time and the change will be picked up automatically.
SQL Agent
introscope.agent.io.socket.client.ports
Restrict socket client connections instrumented to those with specified remote ports
Property settings
A comma-separate list of values.
Example
introscope.agent.io.socket.client.ports=
Notes
If any parameter is not defined, or after exclusion of any invalid values is an empty
list, no restriction will apply to that parameter.
This property is dynamic. You can change the configuration of this property during
run time and the change will be picked up automatically.
introscope.agent.io.socket.server.ports
Restrict socket client connections instrumented to those using specified local ports.
Property settings
A comma-separate list of values.
Example
introscope.agent.io.socket.server.ports=
Notes
If any parameter is not defined, or after exclusion of any invalid values is an empty
list, no restriction will apply to that parameter.
This property is dynamic. You can change the configuration of this property during
run time and the change will be picked up automatically.
SQL Agent
You can configure aspects of the SQL Agent.
SQL Agent
More information:
introscope.agent.sqlagent.normalizer.extension (see page 276)
introscope.agent.sqlagent.normalizer.regex.matchFallThrough (see page 277)
introscope.agent.sqlagent.normalizer.regex.keys (see page 278)
introscope.agent.sqlagent.normalizer.regex.key1.pattern (see page 278)
introscope.agent.sqlagent.normalizer.regex.key1.replaceAll (see page 279)
introscope.agent.sqlagent.normalizer.regex.key1.replaceFormat (see page 279)
introscope.agent.sqlagent.normalizer.regex.key1.caseSensitive (see page 280)
introscope.agent.sqlagent.sql.artonly (see page 280)
introscope.agent.sqlagent.sql.rawsql (see page 280)
introscope.agent.sqlagent.sql.turnoffmetrics (see page 281)
introscope.agent.sqlagent.sql.turnofftrace (see page 281)
introscope.agent.sqlagent.normalizer.extension
Specifies the name of the SQL normalizer extension that will be used to override the
preconfigured normalization scheme.
To make custom normalization extension work, the value of its manifest attribute
com-wily-Extension-Plugin-{pluginName}-Name should match the value given in this
property.
If you specify a comma separated list of names, only the first name will be used. For
example:
introscope.agent.sqlagent.normalizer.extension=ext1, ext2
Only ext1 will be used for normalization. Limits how much of a SQL statement appears in
the Investigator tree for SQL Agent metrics, in bytes.
Property settings
The name of the SQL normalizer extension that is used to override the preconfigured
normalization scheme.
Default
RegexSqlNormalizer
Example
introscope.agent.sqlagent.normalizer.extension=RegexSqlNormalizer
SQL Agent
Notes
If you use the default setting, you also must configure the regular expressions SQL
statement normalizer properties:
Changes to this property take effect immediately and do not require the managed
application to be restarted.
introscope.agent.sqlagent.normalizer.regex.matchFallThrough
Use this property in conjunction with introscope.agent.sqlagent.normalizer.extension
(see page 276) to set the regular expressions SQL statement normalizer. When this
property is set to true, it will evaluate SQL strings against all regex key groups.
The implementation is chained. For example, if SQL matches multiple key groups, the
normalized SQL output from group1 is fed as input to group2, and so on.
If the property is set to false, as soon as a key group matches, the normalized SQL
output from that group is returned.
Property settings
True or False
Default
false
Example
introscope.agent.sqlagent.normalizer.regex.matchFallThrough=false
Notes
Changes to this property take effect immediately and do not require the managed
application to be restarted.
SQL Agent
introscope.agent.sqlagent.normalizer.regex.keys
Use this property in conjunction with introscope.agent.sqlagent.normalizer.extension
(see page 276) to set the regular expressions SQL statement normalizer. This property
specifies the regex group keys. They are evaluated in order.
Default
key1
Example
introscope.agent.sqlagent.normalizer.regex.keys=key1
Notes
Changes to this property take effect immediately and do not require the managed
application to be restarted.
introscope.agent.sqlagent.normalizer.regex.key1.pattern
Use this property in conjunction with introscope.agent.sqlagent.normalizer.extension
(see page 276) to set the regular expressions SQL statement normalizer. This property
specifies the regex pattern that will be used to match against the SQL.
Property settings
All valid regex entries allowed by java.util.Regex package can be used here.
Default
.*call(.*\)\.FOO(.*\)
Example
introscope.agent.sqlagent.normalizer.regex.key1.pattern=.*call(.*\)\.FOO(.*\)
Notes
Changes to this property take effect immediately and do not require the managed
application to be restarted.
SQL Agent
introscope.agent.sqlagent.normalizer.regex.key1.replaceAll
Use this property in conjunction with introscope.agent.sqlagent.normalizer.extension
(see page 276) to set the regular expressions SQL statement normalizer. When this
property is set to false, it will replace the first occurrence of the matching pattern in the
SQL query with the replacement string. If set to true, it will replace all occurrences of
the matching pattern in the SQL query with replacement the string.
Property settings
True or False
Default
false
Example
introscope.agent.sqlagent.normalizer.regex.key1.replaceAll=false
Notes
Changes to this property take effect immediately and do not require the managed
application to be restarted.
introscope.agent.sqlagent.normalizer.regex.key1.replaceFormat
Use this property in conjunction with introscope.agent.sqlagent.normalizer.extension
(see page 276) to set the regular expressions SQL statement normalizer. This property
specifies the replacement string format.
Property settings
All valid regex entries allowed by the java.util.Regex package and
java.util.regex.Matcher class can be used here.
Default
$1
Example
introscope.agent.sqlagent.normalizer.regex.key1.replaceFormat=$1
Notes
Changes to this property take effect immediately and do not require the managed
application to be restarted.
SQL Agent
introscope.agent.sqlagent.normalizer.regex.key1.caseSensitive
Use this property in conjunction with introscope.agent.sqlagent.normalizer.extension
(see page 276) to set the regular expressions SQL statement normalizer. This property
specifies whether the pattern match is sensitive to case.
Property settings
true or false
Default
false
Example
introscope.agent.sqlagent.normalizer.regex.key1.caseSensitive=false
Notes
Changes to this property take effect immediately and do not require the managed
application to be restarted.
introscope.agent.sqlagent.sql.artonly
The introscope.agent.sqlagent.sql.artonly property=true configures the agent to create
and send only the Average Response Time metric for individual SQL statements under
back-ends. When the value for this property is true, performance of the agent for SQL
metrics and transaction traces can improve.
Note: Setting introscope.agent.sqlagent.sql.turnoffmetrics (see page 281)=true
overrides this property.
This property is turned off by default:
introscope.agent.sqlagent.sql.artonly=false
Changes to this property take effect after you restart the managed application.
introscope.agent.sqlagent.sql.rawsql
The introscope.agent.sqlagent.sql.rawsql property configures the agent to add
unnormalized SQL as a parameter for SQL components in Transaction Trace. When the
value for this property is true, performance of the agent for SQL metrics and transaction
traces can improve.
SQL Agent
introscope.agent.sqlagent.sql.turnoffmetrics
You can turn off individual SQL statement metrics to send fewer metrics from the agent
to the Enterprise Manager by using the introscope.agent.sqlagent.sql.turnoffmetrics
property. When the value for this property is true, performance of the agent for SQL
metrics and transaction traces can improve.
This property is turned off by default:
introscope.agent.sqlagent.sql.turnoffmetrics=false
Changes to this property take effect after you restart the managed application.
introscope.agent.sqlagent.sql.turnofftrace
The introscope.agent.sqlagent.sql.turnofftrace property controls whether the agent
creates transaction trace components and sends them to the Enterprise Manager for
individual SQL statements under back-ends. When the value for this property is true,
performance of the agent for SQL metrics and transaction traces can improve.
This property is turned off by default:
introscope.agent.sqlagent.sql.turnofftrace=false
Changes to this property take effect after you restart the managed application.
SSL communication
SSL communication
The agent can connect to the Enterprise Manager over SSL. Use the following properties
to configure that communication:
introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT
introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT
introscope.agent.enterprisemanager.transport.tcp.truststore.DEFAULT
introscope.agent.enterprisemanager.transport.tcp.trustpassword.DEFAULT
introscope.agent.enterprisemanager.transport.tcp.keystore.DEFAULT
introscope.agent.enterprisemanager.transport.tcp.keypassword.DEFAULT
introscope.agent.enterprisemanager.transport.tcp.ciphersuites.DEFAULT
introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT
Specifies the host name of the computer running the Enterprise Manager that the agent
connects to by default.
Default
localhost
Example
introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT=localhost
Notes
You must restart the managed application before changes to this property take effect.
SSL communication
introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT
Specifies the port number on the computer that hosts the Enterprise Manager that
listens for connections from the agent. If you are using Secure Socket Layer (SSL)
protocol, the default port that listens for connections from the agent is 5443.
Default
5443
Example
introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT=5443
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT
Specifies the client socket factory to use for connections from the agent to the
Enterprise Manager when using SSL.
Default
com.wily.isengard.postofficehub.link.net.SSLSocketFactory
Example
ntroscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT=com.wily.is
engard.postofficehub.link.net.SSLSocketFactory
Notes
You must restart the managed application before changes to this property take effect.
SSL communication
introscope.agent.enterprisemanager.transport.tcp.truststore.DEFAULT
Location of a truststore containing trusted Enterprise Manager certificates. If no
truststore is specified, the agent trusts all certificates.
Property settings
Either an absolute path or a path relative to the agent's working directory.
Example
introscope.agent.enterprisemanager.transport.tcp.truststore.DEFAULT=/var/trustedc
erts
Notes
On Windows, backslashes must be escaped. For example: C:\\keystore
introscope.agent.enterprisemanager.transport.tcp.trustpassword.DEFAULT
The password for the truststore.
Example
introscope.agent.enterprisemanager.transport.tcp.trustpassword.DEFAULT=
introscope.agent.enterprisemanager.transport.tcp.keystore.DEFAULT
Location of a keystore containing the agent's certificate. A keystore is needed if the
Enterprise Manager requires client authentication.
Property settings
Either an absolute path or a path relative to the agent's working directory.
Example
introscope.agent.enterprisemanager.transport.tcp.keystore.DEFAULT=c:\\keystore
Notes
On Windows, backslashes must be escaped. For example: C:\\keystore
Stall metrics
introscope.agent.enterprisemanager.transport.tcp.keypassword.DEFAULT
The password for the keystore.
Example
introscope.agent.enterprisemanager.transport.tcp.keypassword.DEFAULT=MyPassword76
8
introscope.agent.enterprisemanager.transport.tcp.ciphersuites.DEFAULT
Set the enabled cipher suites.
Property settings
A comma-separated list of cipher suites.
Example
introscope.agent.enterprisemanager.transport.tcp.
ciphersuites.DEFAULT=SSL_DH_anon_WITH_RC4_128_MD5
Notes
If not specified, use the default enabled cipher suites.
Stall metrics
The following properties are for stall metrics:
For more information on stall metric properties, see Disabling the capture of stalls as
Events (see page 166).
Stall metrics
introscope.agent.stalls.thresholdseconds
Specifies the number of seconds that an executing process can take before it is
considered a stalled process. To ensure an accurate Stall Count metric, you must set the
stall resolution and stall threshold properties to 15 seconds or more. The stall threshold
should not be set to less than 15 seconds to allow time for the Enterprise Manager to
complete its harvest cycle. The stall resolution should always be set to a value equal to
or greater than the Enterprise Manager harvest duration.
Default
The default is 30 seconds.
Example
introscope.agent.stalls.thresholdseconds=30
Notes
This property is dynamic. You can change the configuration of this property during run
time and the change will be picked up automatically.
introscope.agent.stalls.resolutionseconds
Specifies the frequency that the agent checks for stalls. To ensure an accurate Stall
Count metric, you must set the stall resolution and stall threshold properties to 15
seconds or more. The stall threshold should not be set to less than 15 seconds to allow
time for the Enterprise Manager to complete its harvest cycle. The stall resolution
should always be set to a value equal to or greater than the Enterprise Manager harvest
duration.
Default
The default is every 10 seconds.
Example
introscope.agent.stalls.resolutionseconds=10
Notes
This property is dynamic. You can change the configuration of this property during run
time and the change will be picked up automatically.
Thread dumps
Thread dumps
These properties enable and configure agent aspects of CA Introscope thread dump
functionality:
Note: For more information about configuring thread dumps, see How to enable and
configure thread dumps (see page 67).
introscope.agent.threaddump.enable
Enables thread dumps to be collected on an agent JVM and allows users to view the
Thread Dumps tab.
Property settings
True or False
Default
True
Example
introscope.agent.threaddump.enable=true
Notes
Changes to this property take effect immediately and do not require you to restart
the managed application.
Thread dumps
introscope.agent.threaddump.deadlockpoller.enable
Enables the Deadlock Count metric in the metric browser tree to display the current
number of deadlocks in the agent JVM.
Property settings
True or False
Default
False
Example
introscope.agent.threaddump.deadlockpoller.enable=true
Notes
Changes to this property take effect immediately and do not require you to restart
the managed application.
introscope.agent.threaddump.deadlockpollerinterval
Frequency in milliseconds at which CA Introscope polls the agent JVM for deadlocked
threads
Property settings
Integer greater than 0
Default
15000 (milliseconds)
Example
introscope.agent.threaddump.deadlockpollerinterval=15000
Notes
Restart the managed application so changes to this property can take effect.
Transaction tracing
introscope.agent.threaddump.MaxStackElements
The total number of lines in the thread stack trace determines the size of a CA
Introscope thread dump. This property sets the number of lines allowed in the thread
stack.
Property settings
Integer greater than 0 and no greater than 25,000
Default
12,000
Example
introscope.agent.threaddump.MaxStackElements=12000
Notes
Restart the managed application so that changes to this property can take effect.
Transaction tracing
The following properties are for transaction tracing and sampling:
introscope.agent.transactiontracer.parameter.httprequest.parameters (see
page 290)
For more information, see Configuring Transaction Trace Options (see page 161).
Transaction tracing
introscope.agent.transactiontracer.parameter.httprequest.headers
Specifies (in comma-separated list) HTTP request header data to capture. Use a comma
separated list.
Default
Commented out; User-Agent
Example
introscope.agent.transactiontracer.parameter.httprequest.headers=User-Agent
Notes
The IntroscopeAgent.profile contains a commented out statement that sets the value of
this property to a null value. The user may optionally uncomment the statement and
supply the desired header names.
introscope.agent.transactiontracer.parameter.httprequest.parameters
Specifies (in comma-separated list) HTTP request parameter data to capture.
Default
Commented out; generic parameters.
Example
introscope.agent.transactiontracer.parameter.httprequest.parameters=parameter1,pa
rameter2
Notes
The IntroscopeAgent.profile contains a commented out statement that sets the value of
this property to a null value. The user may optionally uncomment the statement and
supply the desired parameter names.
Transaction tracing
introscope.agent.transactiontracer.parameter.httpsession.attributes
Specifies (in comma-separated list) HTTP session attribute data to capture.
Default
Commented out; generic parameters.
Example
introscope.agent.transactiontracer.parameter.httpsession.attributes=attribute1,at
tribute2
Notes
The IntroscopeAgent.profile contains a commented out statement that sets the value of
this property to a null value. The user may optionally uncomment the statement and
supply the desired parameter names.
introscope.agent.transactiontracer.userid.key
User-defined key string.
Default
Commented out; generic parameters.
Example
#introscope.agent.transactiontracer.parameter.httpsession.attributes=attribute1,a
ttribute2
Notes
The IntroscopeAgent.profile contains a commented out statement that sets the value of
this property to a null value. The user may optionally uncomment the statement and
supply the correct value if, in your environment, user IDs are accessed using
HttpServletRequest.getHeader or HttpServletRequest.getValue.
For more information, see introscope.agent.transactiontracer.userid.method (see
page 292).
Transaction tracing
introscope.agent.transactiontracer.userid.method
Specifies the method that returns User IDs. The Agent profile includes a commented out
property definition for each of the three allowable values.
Uncomment the appropriate statement, based on whether user ID is accessed by
getRemoteUser, getHeader, or getValue.
Property settings
Allowable values are:
HttpServletRequest.getRemoteUser
HttpServletRequest.getHeader
HttpServletRequest.getValue
Default
Commented out; see options above.
Example
The IntroscopeAgent.profile includes a commented out property definition for each of
the three allowable values. You can uncomment the property you want to use.
introscope.agent.transactiontracer.userid.method=HttpServletRequest.getRemoteUser
#introscope.agent.transactiontracer.userid.method=HttpServletRequest.getHeader
#introscope.agent.transactiontracer.userid.method=HttpSession.getValue
Transaction tracing
introscope.agent.transactiontrace.componentCountClamp
Limits the number of components allowed in a transaction trace.
Default
5000
Warning! If the clamp size is increased, the requirements on memory are higher. In
extreme cases, the maximum heap size for the JVM may need to be adjusted or the
managed application could run out of memory.
Example
introscope.agent.transactiontrace.componentCountClamp=5000
Notes
Any Transaction Trace exceeding the clamp is discarded at the agent and a warning
message is logged in the agent log file.
This property is dynamic. You can change the configuration of this property during
run time and the change will be picked up automatically.
When the set limit is reached, warnings appear in the log, and the trace stops.
Transaction tracing
introscope.agent.crossprocess.compression
Use this property to reduce the size of cross process transaction tracing data.
Property settings
lzma, gzip, none
Default
lzma
Example
introscope.agent.crossprocess.compression=lzma
Notes
This option will increase agent CPU overhead, but reduce the size of interprocess
headers.
lzma compression is more efficient than gzip, but may use more CPU.
.NET agents do not support the gzip option, so if interoperability is required, do not
use gzip.
This property is dynamic. You can change the configuration of this property during
run time and the change will be picked up automatically.
Transaction tracing
introscope.agent.crossprocess.compression.minlimit
Use this property to set the minimum length of cross process parameter data length for
which to apply compression.
Property settings
Can be set from 0 to twice the total maximum limit, set in the
introscope.agent.crossprocess.correlationid.maxlimit (see page 296).
If set below the default of 1500, the compression will run more frequently and consume
more CPU overhead. The default setting of 1500 usually results in no impact to CPU
overhead in normal conditions.
Default
1500
Example
introscope.agent.crossprocess.compression.minlimit=1500
Notes
This property is dynamic. You can change the configuration of this property during
run time and the change will be picked up automatically.
Transaction tracing
introscope.agent.crossprocess.correlationid.maxlimit
Maximum size of cross process parameter data allowed.
If the total size of cross process parameter data is more than this limit, even after
applying compression, some data will be dropped and some cross process correlation
functionality will not work properly.
However, this setting will protect user transactions from failing in network transmission
due to too large header size.
Default
4096
Example
introscope.agent.crossprocess.correlationid.maxlimit=4096
Notes
This property is dynamic. You can change the configuration of this property during
run time and the change will be picked up automatically.
introscope.agent.transactiontracer.sampling.enabled
Uncomment the following property to disable Transaction Tracer Sampling.
Property settings
True or False
Default
False
Example
introscope.agent.transactiontracer.sampling.enabled=false
Notes
Changes to this property take effect immediately and do not require the managed
application to be restarted.
Transaction tracing
introscope.agent.transactiontracer.sampling.perinterval.count
This property is normally configured in the Enterprise Manager. Configuring this
property in the agent disables the configuration in the Enterprise Manager. See the CA
APM Configuration and Administration Guide for more information.
Default
1
Example
introscope.agent.transactiontracer.sampling.perinterval.count=1
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.transactiontracer.sampling.interval.seconds
This property is normally configured in the Enterprise Manager. Configuring this
property in the agent disables the configuration in the Enterprise Manager.
Note: For more information, see the CA APM Configuration and Administration Guide.
Default
120
Example
introscope.agent.transactiontracer.sampling.interval.seconds=120
Notes
You must restart the managed application before changes to this property take effect.
Transaction tracing
introscope.agent.transactiontrace.headFilterClamp
Specifies the maximum depth of components allowed in head filtering. Head filtering is
the process of examining the start of a transaction for the purpose of potentially
collecting the entire transaction. Head filtering checks each component until the first
blamed component exits. For transaction with very deep call stacks, this can be a
problem if no clamping is applied. The clamp value limits the memory and CPU
utilization impact of this behavior by forcing the agent to only look up to a fixed depth.
Default
30
Warning! If the clamp size is increased, the requirement on memory is higher. Garbage
collection behavior will be affected, which will have an application-wide performance
impact.
Example
introscope.agent.transactiontrace.headFilterClamp=30
Notes
Changes to this property take effect immediately and do not require the managed
application to be restarted.
Any Transaction Trace whose depth exceeds the clamp will no longer be examined
for possible collection unless some other mechanism, such as sampling or
user-initiated transaction tracing, is active to select the transaction for collection.
URL grouping
introscope.agent.ttClamp
This property limits the number of transactions that are reported by the agent per
reporting cycle.
Property settings
Integers.
Default
50
Example
introscope.agent.ttClamp=50
Notes
You must restart the managed application before changes to this property take
effect.
If the property is not set (left blank), the value defaults to 200.
URL grouping
The following properties are for configuring URL Groups for frontend metrics:
For more information, see Using URL groups (see page 153).
URL grouping
introscope.agent.urlgroup.keys
Configuration settings for Frontend naming.
Default
Default
Example
introscope.agent.urlgroup.keys=default
Notes
If a URL address belongs to two URL Groups, the order in which you list the keys for the
URL Groups in this property is important. The URL Group defined by the narrower
pattern should precede the URL Group specified by the broader pattern.
For example, if the URL Group with key alpha contains a single address, and the URL
Group with key beta includes all addresses on the network segment that contains the
address in the first URL Group, alpha should precede beta in the keys parameter.
introscope.agent.urlgroup.group.default.pathprefix
Configuration settings for frontend naming.
Default
*
Example
introscope.agent.urlgroup.group.default.pathprefix=*
introscope.agent.urlgroup.group.default.format
Configuration settings for Frontend naming.
Default
Default
Example
introscope.agent.urlgroup.group.default.format=default
WebSphere PMI
WebSphere PMI
The following properties configure WebSphere PMI metrics:
WebSphere PMI
introscope.agent.pmi.enable
Enables collection of data from WebSphere PMI.
Property settings
True or False
Default
True
Example
introscope.agent.pmi.enable=true
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.pmi.enable.alarmManager
Enables collection of PMI alarm manager data when set to true.
Property settings
True or False
Default
False
Example
introscope.agent.pmi.enable.alarmManager=false
Notes
You must restart the managed application before changes to this property take
effect.
WebSphere PMI
introscope.agent.pmi.enable.bean
Enables collection of PMI bean data.
Property settings
True or False
Default
False
Example
introscope.agent.pmi.enable.bean=false
introscope.agent.pmi.enable.cache
Enables collection of PMI cache data when set to true.
Property settings
True or False
Default
False
Example
introscope.agent.pmi.enable.cache=false
Notes
You must restart the managed application before changes to this property take
effect.
WebSphere PMI
introscope.agent.pmi.enable.connectionPool
Enables collection of PMI connectionPool data.
Property settings
True or False
Default
True
Example
introscope.agent.pmi.enable.connectionPool=true
introscope.agent.pmi.enable.hamanager
Enables collection of PMI manager data when set to true.
Property settings
True or False
Default
False
Example
introscope.agent.pmi.enable.hamanager=false
Notes
You must restart the managed application before changes to this property take
effect.
WebSphere PMI
introscope.agent.pmi.enable.j2c
Enables collection of PMI J2C data when set to true.
Property settings
True or False
Default
True
Example
introscope.agent.pmi.enable.j2c=true
Notes
You must restart the managed application before changes to this property take
effect.
introscope.agent.pmi.enable.jvmpi
Enables collection of PMI JVM PI data.
Property settings
True or False
Default
False
Example
introscope.agent.pmi.enable.jvmpi=false
Notes
For data to be provided to this module, JVMPI must be turned on in WebSphere.
WebSphere PMI
introscope.agent.pmi.enable.jvmRuntime
Enables collection of PMI JVM runtime data.
Property settings
True or False
Default
False
Example
introscope.agent.pmi.enable.jvmRuntime=false
Notes
You must restart the managed application before changes to this property take
effect.
introscope.agent.pmi.enable.objectPool
Enables collection of PMI object pool data when set to true.
Property settings
True or False
Default
False
Example
introscope.agent.pmi.enable.objectPool=false
Notes
You must restart the managed application before changes to this property take
effect.
WebSphere PMI
introscope.agent.pmi.enable.orbPerf
Enables collection of PMI orbPerf data when set to true.
Property settings
True or False
Default
False
Example
introscope.agent.pmi.enable.orbPerf=false
Notes
You must restart the managed application before changes to this property take
effect.
introscope.agent.pmi.enable.scheduler
Enables collection of PMI scheduler data when set to true.
Property settings
True or False
Default
False
Example
introscope.agent.pmi.enable.scheduler=false
Notes
You must restart the managed application before changes to this property take
effect.
WebSphere PMI
introscope.agent.pmi.enable.servletSessions
Enables collection of PMI servletSessions data.
Property settings
True or False
Default
True
Example
introscope.agent.pmi.enable.servletSessions=true
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.pmi.enable.system
Enables collection of PMI system data when set to true.
Property settings
True or False
Default
False
Example
introscope.agent.pmi.enable.system=false
Notes
You must restart the managed application before changes to this property take
effect.
WebSphere PMI
introscope.agent.pmi.enable.threadPool
Enables collection of PMI thread pool data when set to true.
Property settings
True or False
Default
True
Example
introscope.agent.pmi.enable.threadPool=true
Notes
You must restart the managed application before changes to this property take
effect.
introscope.agent.pmi.enable.transaction
Enables collection of PMI transaction data.
Property settings
True or False
Default
False
Example
introscope.agent.pmi.enable.transaction=false
Notes
You must restart the managed application before changes to this property take effect.
WebSphere PMI
introscope.agent.pmi.enable.webApp
Enables collection of PMI webApp data.
Property settings
True or False
Default
False
Example
introscope.agent.pmi.enable.webApp=false
Notes
You must restart the managed application before changes to this property take effect.
introscope.agent.pmi.enable.webServices
Enables collection of PMI web services data when set to true.
Property settings
True or False
Default
False
Example
introscope.agent.pmi.enable.webServices=false
Notes
You must restart the managed application before changes to this property take
effect.
WebSphere PMI
introscope.agent.pmi.enable.wlm
Enables collection of PMI WLM data when set to true.
Property settings
True or False
Default
False
Example
introscope.agent.pmi.enable.wlm=false
Notes
You must restart the managed application before changes to this property take
effect.
introscope.agent.pmi.enable.wsgw
Enables collection of PMI WSGW data when set to true.
Property settings
True or False
Default
False
Example
introscope.agent.pmi.enable.wsgw=false
Notes
You must restart the managed application before changes to this property take
effect.
WLDF metrics
introscope.agent.pmi.filter.objref
Controls for hard-coded filters.
The objref filter filters out names ending with "@xxxxx" where "xxxxx" is a numeric
string.
Property settings
True or False
Default
False
Example
introscope.agent.pmi.filter.objref=false
Notes
You must restart the managed application before changes to this property take effect
WLDF metrics
The following properties configure WLDF metrics:
WLDF metrics
introscope.agent.wldf.enable
Enables collection of WLDF metrics.
Property settings
True or False
Default
False
Example
introscope.agent.wldf.enable=false
Notes
For WebLogic 9.x and above only.
WebSphere or WebLogic
For information about configuring AutoProbe on WebSphere and WebLogic, see
Deploying the Java Agent on WebSphere (see page 47) and Deploying the Java
Agent on WebLogic (see page 42).
OS/400
Important! Use only one method to instrument your applications. If you have already
started using JVM AutoProbe, do not use Application Server AutoProbe.
When starting the application server, avoid using the hyphen (-) character as an
identifier for a classname. Introscope does not parse this character, and using it might
lead to class loading errors in the agent logs.
In order to add Introscope information to startup scripts for Sun ONE 7.0, you must
be logged in as Administrator or Root.
2.
4.
Add a jvm-options element to define the location of the agent profile. Define
either com.wily.introscope.agentProfile, or com.wily.introscope.agentResource.
The following is an example of com.wily.introscope.agentProfile:
<java-config ...>
...
<jvm-options>-Dcom.wily.introscope.agentProfile=/sw/sun/sunone7/wily/core
/config/IntroscopeAgent.profile </jvm-options>
</java-config>
5.
Configure Tracer Groups to collect servlet data. For more information, see
Configuring HTTP servlet tracing (see page 318).
2.
3.
4.
5.
Important! Users running Oracle 10g Release 2 using Sun JDK 1.42 must use the ^
(caret) character to escape a forward slash when issuing commands. For example:
-Xbootclasspath^/p:<IntroscopeAgent.jar path>
6.
Configure Tracer Groups to collect servlet data. For more information, see
Configuring HTTP servlet tracing (see page 318).
2.
Set the following property in the application startup script on the Java command
line with the -D option to activate Introscope AutoProbe:
-Dweblogic.classloader.preprocessor=
com.wily.introscope.api.weblogic.PreProcessor
3.
Configure Tracer Groups to collect servlet data. For more information, see
Configuring HTTP servlet tracing (see page 318).
2.
3.
Turn off the HTTPServletTracing Tracer Group by placing a pound sign at the
beginning of the line. For example:
#TurnOn: HTTPServletTracing
4.
5.
2.
Run the Create AutoProbe Connector tool using one of these commands:
to specify the JVM using the JVM that is running the tool:
java -jar CreateAutoProbeConnector.jar -current
to specify the JVM by passing the JVM directory on the command line:
java -jar CreateAutoProbeConnector.jar -jvm <directory>
You may want to rename the created .jar file to be more manageable and
universally accepted. For example:
wily/connectors/AutoProbeConnector131_02_Sun.jar
OR
wily/connectors/AutoProbeConnector130_IBM.jar
2.
For example:
Xbootclasspath/p:C:/usr/sap/P602/j2ee/j2ee_00/ccms/wily/connectors/AutoProbeC
onnector.jar;C:/usr/sap/P602/j2ee/j2ee_00/ccms/wily/Agent.jar
-Dcom.wily.introscope.agentProfile=C:/usr/sap/P602/j2ee/j2ee_00/ccms/wily/cor
e/config/IntroscopeAgent.profile
3.
2.
3.
For example:
Xbootclasspath/p:D:/usr/sap/ccms/wily/connectors/AutoProbeConnector.jar;D:/us
r/sap/ccms/wily/Agent.jar
-Dcom.wily.introscope.agentProfile=D:/usr/sap/ccms/wily/core/config/Introscop
eAgent.profile
Note: For NetWeaver 6.40 on Windows, the slashes for these java parameters must
be forward slashes.
4.
5.
6.
7.
8.
2.
3.
Users running Oracle 10g Release 2 using Sun JDK 1.42 must use the ^ (caret) character
to escape a forward slash when issuing commands. For example:
-Xbootclasspath^/p:<IntroscopeAgent.jar path>
Different versions of WebLogic use different versions of Java to run. If you use Java 1.4
or earlier, you will use the following steps to run the AutoProbe connector. If you use
Java 1.5 or later, see JVM AutoProbe for more information.
To run the AutoProbe Connector for WebLogic
1.
Edit the bootstrap classpath in the application startup script to include the
AutoProbeConnector.jar you created (such as startMedRecServer.cmd) using this
command:
-Xbootclasspath/p:PathToAutoProbeConnectorJar:PathToAgentJar
add the -X switch to the final start command at the end of the script, after the
JAVA_VM and JAVA_OPTIONS. The excerpt below shows the correct place to insert
the switch:
"$JAVA_HOME/bin/java" ${JAVA_VM} ${MEM_ARGS} ${JAVA_OPTIONS}
-Xbootclasspath/p:${WL_HOME}/wily/connectors/AutoProbeConnector.jar:${WL_HOME
}/wily/Agent.jar
-Dweblogic.Name=${SERVER_NAME}
-Dweblogic.management.username=${WLS_USER}
-Dweblogic.management.password=${WLS_PW}
-Dweblogic.ProductionModeEnabled=${PRODUCTION_MODE}
-Djava.security.policy="${WL_HOME}/server/lib/weblogic.policy"
weblogic.Server
2.
If you are using something other than the default bootstrap classpath, add the
Agent.jar and AutoProbeConnector.jar files to the beginning of your customized
bootstrap classpath.
To run the AutoProbe Connector, add the Agent.jar and the AutoProbe Connector
to the Application Server bootstrap classpath using this command:
-Xbootclasspath/p:wily/connectors/AutoProbeConnector.jar:PathToAgentJar
Installed the Java agent. See Installing the Java Agent for more information.
2.
3.
Configured the Java agent name. See Java Agent Naming (see page 117) for more
information.
4.
Important! If you are using the Java Agent 9.0 or later to monitor WebSphere 7.0 on
z/OS , you may see the application server process restart repeatedly. To avoid this
problem, upgrade to WAS 7.0 build level 7.0.0.8 or above.
To configure JVM AutoProbe for WebSphere 6.1, and 7.0 for z/OS
1.
2.
3.
You should see two items, Control and Servant. Click Servant, then
JavaVirtualMachine.
4.
Set the Generic JVM Argument field to specify the classloader plug-in, and the
location of the IntroscopeAgent.profile file. You will set one of the following:
com.wily.introscope.agentProfile
OR
com.wily.introscope.agentResource
The argument will then have the following value (there are several properties set in
one argument):
-Dcom.ibm.websphere.classloader.plugin=com.wily.introscope.api
.websphere.WASAutoProbe
-Dcom.wily.introscope.agentProfile=<path to IntroscopeAgent.profile>
OR
-Dcom.ibm.websphere.classloader.plugin=com.wily.introscope.api
.websphere.WASAutoProbe
-Dcom.wily.introscope.agentResource=<path to Resource containing
IntroscopeAgent.profile>
5.
6.
Confirm that all newly created Introscope files and directories within the ./wily
directory are read-accessible by the WebSphere process.
7.
Confirm that all *.log files (written by the Java Agent and ProbeBuilder) in the ./wily
folder have write-access to the WebSphere process. These include:
8.
9.
When WebSphere says "open for e-business," open the Administrators Console.
Metrics should start reporting.
10. For AutoProbe to run correctly in WebSphere environments with Java2 Security
enabled, it may be necessary to add permissions to your Java2 Security Policy. If
Java2 Security is enabled, follow the instructions in Modifying Java2 Security Policy
(see page 51).
11. Configure Tracer Groups to collect servlet data. For more information, see
Configuring HTTP servlet tracing (see page 318).
automate building of PBD files, to eliminate potential for errors that might be
introduced by creating PBD files manually.
integrate PBD generation into your build systems to create and update PBD files
automatically and incorporate any changes to the Java source.
You configure the PBD Generator by integrating it into an Apache Ant target using the
PBDGenerator.jar file, then running it as an Ant Javadoc task.
where:
<valid metric prefix> is any valid Introscope metric prefixa string without a colon
character (:). Pipe characters (|) are acceptable.
<optional tracer name> can be BlamePointTracer, FrontendMarker or BackendMarker.
The default is BlamePointTracer if the tracer name is missing.
2.
Your browser displays the list of network interface names supported by Java on the
Network Interfaces tab.
More information:
Configure a List of Available Networks (see page 220)
Index
A
agent
architectural overview 25
depolyment process 26, 28
directory structure 38
manual installation 37
removing from z/OS 63
silent installation 35
specifying the path to 39
starting 40
uninstalling 62
upgrading 61
application management
introduction 26
application server
upgrading multiple agents 61
M
manual ProbeBuilding 71
P
ProbeBuilder Directive (PBD) files
introduction 25
ProbeBuilding
customizing 72
dynamic 73
methods available 71
support for older agents 72
Enterprise Manager
architectural overview 25
configuring the connection 57
HTTP tunneling 58
HTTPS connections 59
proxy server 59
using SSL 60
I
installation
directory structure 38
GUI mode 31
manual 37
silent 35
instrumentation
full and typical tracing 72
Introscope
architectural overview 25
discover functionality 26
IntroscopeAgent.profile
deployment process 28
T
thread dump 67
tracer groups
default configuration options 72
W
Workstation
architectural overview 25
J
javaagent property 71
JVM AutoProbe
configuring the agent location 39
Index 331