CA Wily Introscope

CA Wily Introscope®Java Agent Guide Version 9.0 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 restricti ons 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 © 2011 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies. CA Technologies Product References This document references the following CA Technologies products: ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ CA SiteMinder® CA Spectrum® Infrastructure Manager CA SYSVIEW® Performance Management CA Wily Extension for CA SYSVIEW® CA Wily Introscope® CA Wily Introscope® ErrorDetector™ CA Wily Introscope® ChangeDetector™ CA Wily Introscope® PowerPack™ for CA SiteMinder Web Access Manager CA Wily Introscope® PowerPack™ for BEA Tuxedo Connectors CA Wily Introscope® PowerPack™ for BEA WebLogic Integration CA Wily Introscope® PowerPack™ for BEA WebLogic Server CA Wily Introscope® PowerPack™ for IBM CICS Transaction Gateway CA Wily Introscope® PowerPack™ for IBM WebSphere Business Integration Adapters CA Wily Introscope® PowerPack™ for IBM WebSphere Application Server CA Wily Introscope® PowerPack™ for IBM WebSphere MQ CA Wily Introscope® PowerPack™ for IBM z/OS CA Wily Introscope® PowerPack™ for Oracle Database CA Wily Introscope® PowerPack™ for Web Servers CA Wily Introscope® for Microsoft .NET CA Wily Introscope® for SAP NetWeaver CA Wily Introscope® for SAP ABAP CA Wily Introscope® Integration Pack for CA NSM CA Wily Introscope® LeakHunter™ CA Wily Introscope® SNMP Adapter™ CA Wily Introscope® PowerPack™ for IBM WebSphere Application Server for Distributed Environments 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 Information about user communities and forums Product and documentation downloads CA Support policies and guidelines Other helpful resources appropriate for your product Provide Feedback If you have comments or questions about CA Technologies product documentation, you can send a message to [email protected]. If you would like to provide feedback about CA Technologies product documentation, complete our short customer survey, which is available on the CA Support website at http://ca.com/docs. Contents Chapter 1: The Java Agent Overview 19 19 19 20 20 21 21 21 21 23 23 24 24 25 25 25 Documentation Changes ........................................................................ Application triage map support ............................................................... Agent-only business transaction recording ...................................................... Dynamic instrumentation .................................................................... Java NIO .................................................................................. Multiple inheritance support ................................................................. LeakHunter and ErrorDetector configuration .................................................... The Introscope environment ..................................................................... Planning a Java Agent deployment ................................................................ Discover Introscope functionality .............................................................. Determine configuration requirements ......................................................... Create and define Java Agent configuration ..................................................... Evaluate Java Agent performance overhead ..................................................... Validate and deploy Java Agent configuration ................................................... Deploying the Java Agent ........................................................................ Chapter 2: Installing and Configuring the Java Agent 27 27 27 28 29 29 30 31 34 36 40 43 43 44 44 44 44 46 47 Before you begin ............................................................................... Application server support ................................................................... Enterprise Manager connection information .................................................... JVM AutoProbe ............................................................................ Installing the Java Agent ......................................................................... The Java Agent installer ...................................................................... Installing the Java Agent in GUI mode .......................................................... Installing the Java Agent in console mode ....................................................... Installing the Java Agent in silent mode......................................................... Manual installation ......................................................................... Java Agent installation directories and files ......................................................... Contents of the wily directory ................................................................ Contents of the wily\connectors directory ...................................................... Contents of the wily\deploy directory .......................................................... Contents of the wily\examples directory........................................................ Contents of the wily\ext directory ............................................................. Contents of the wily\hotdeploy directory ....................................................... Contents of the wily\install directory .......................................................... Contents 5 Contents of the wily\tools directory ........................................................... Contents of the wily\UninstallerData directory .................................................. Contents of the wily\readme and wily\versions directories ........................................ Configuring the JVM to use the Java Agent .......................................................... Starting the Java Agent .......................................................................... Connecting to the Enterprise Manager ............................................................. Connecting to the Enterprise Manager with HTTP tunneling ....................................... Configuring a proxy server for HTTP tunneling ................................................... Connecting to the Enterprise Manager with HTTPS tunneling....................................... Connecting to the Enterprise Manager over SSL .................................................. Java Agent configuration overview ................................................................ Operational configurations ................................................................... Optional operational configurations ........................................................... Data collection configurations ................................................................ CA Wily CEM integration ..................................................................... Upgrading multiple agent types ................................................................... Uninstalling the Java Agent ...................................................................... Uninstalling the Java Agent from z/OS .......................................................... 47 47 47 48 48 48 49 50 51 52 53 53 54 55 57 57 59 59 Chapter 3: AutoProbe and ProbeBuilding Options 61 61 62 62 62 63 63 64 64 64 67 67 68 68 71 72 75 AutoProbe and ProbeBuilding overview ............................................................ Unsupported instrumentation methods ........................................................ Configuring JVM AutoProbe ...................................................................... JVM AutoProbe ............................................................................ JVM AutoProbe for WAS 7 on z/OS ............................................................ JVM AutoProbe on OS/400 ................................................................... WebSphere or WebLogic..................................................................... Creating an AutoProbe connector file .......................................................... Running the AutoProbe Connector for a Sun, IBM, or HP JVM ...................................... JRockit JVM AutoProbe ...................................................................... Configuring ProbeBuilding ....................................................................... Full or typical tracing options ................................................................. Dynamic ProbeBuilding ...................................................................... Dynamic ProbeBuilding vs. dynamic instrumentation ............................................. ProbeBuilding class hierarchies (JVM 1.5) ....................................................... Removing line numbers in bytecode ........................................................... Chapter 4: Deploying the Java Agent on WebLogic 77 Before you begin ............................................................................... 77 Configuring AutoProbe for WebLogic Server ........................................................ 77 Application server management data .............................................................. 78 6 Java Agent Guide Configuring a startup class for WebLogic 9.0 or higher ............................................ Configuring the SQL Agent for WebLogic Server ..................................................... Supported JDBC drivers and datasources ....................................................... Configure the SQL Agent for WebLogic ......................................................... Configuring WebLogic Diagnostic Framework (WLDF) ................................................. Understanding WLDF metric conversion ........................................................ Enabling WLDF reporting .................................................................... Cross-process Transaction Tracing in WebLogic ...................................................... Enabling cross-process tracing in WebLogic Server ............................................... Introscope Java Agent JMX support................................................................ Introscope support for WebLogic 9.0 JMX metrics ................................................ JMX filters for WebLogic ..................................................................... 78 79 79 80 82 82 83 83 83 84 84 84 Chapter 5: Deploying the Java Agent on WebSphere 85 85 85 88 89 91 91 91 92 92 93 93 94 94 94 96 97 97 97 98 98 98 98 99 Before you begin ............................................................................... AutoProbe for WebSphere 6.1 .................................................................... AutoProbe for WebSphere 7.0 .................................................................... AutoProbe for WebSphere 6.1 and 7.0 for z/OS ...................................................... Modifying Java2 Security Policy ................................................................... Disable agent naming for WebSphere .............................................................. WebSphere application server management data .................................................... Configuring a custom service in WebSphere 6.1 .................................................. WAS 6.1 on AIX platform ..................................................................... The SQL Agent for WebSphere .................................................................... Supported JDBC drivers and DataSources ....................................................... Configuring the SQL Agent for WebSphere Application Server (WAS) ................................ Configure the JDBC DataSource or Driver in WebSphere ........................................... Instrument the JDBC DataSource or Driver ...................................................... WebSphere PMI ............................................................................... Using WebSphere PMI with Introscope on z/OS .................................................. Enabling PMI in WebSphere .................................................................. Configuring WebSphere PMI in Introscope ...................................................... Viewing WebSphere PMI data ................................................................ Logging considerations on WebSphere for z/OS ..................................................... Tagging log output as EBCDIC ................................................................. Eliminating startup timing issues with logging facilities ............................................ Cross-process Transaction Tracing in WebSphere .................................................... Chapter 6: Deploying the Java Agent on other application servers using JVM AutoProbe 101 Deploying the Java Agent on other application servers using JVM AutoProbe ............................ 101 Contents 7 ...1 ......................... Boundary Blame and Oracle backends .................................................... Default PBL files ..........profile...................................................................... Configuring SAP Netweaver 7...................................................... Supplementary directives and tracers information .................... Creating custom tracers ........................................................... Using the IntroscopeAgent.. Default PBD files ....................................... 102 103 104 105 107 107 108 108 Chapter 7: ProbeBuilder Directives 109 109 110 111 114 114 125 126 128 129 129 130 130 130 132 132 133 135 137 140 141 141 142 142 143 143 143 144 145 145 146 146 ProbeBuilder Directives overview ...... Using a custom BlamePointTracer tracer for common metrics .................................. Combining custom tracers .... Blame Tracers in standard PBDs ........................................................... Tomcat PBD tracing options ............ Commonly used tracer names and examples ...........Configuring Apache Tomcat ........................................................................................................................................ Skip directives ......................................................... Blame Tracers................................................................................. JBoss PBDs and PBLs ...................................................................... Configuring JBoss .. Instrumenting with new and changed PBDs ... EJB naming ..................5 annotations ............................................................................................................................ High agent CPU overhead from deep nested frontend transactions .............................. PBLs.................................................................................................... Default tracer groups and toggles files ....... Editing the startup script .............................. Advanced single-metric tracers ............................ Java 1........................................................................................................................................ Applying ProbeBuilder Directives ........ Using JVM AutoProbe .......................................................................................................................................................... Configuring Oracle Application Server 10g .. Counting object instances ........ Custom FrontendMarker directive ...................................................................................................................................... Using Blame Tracers to mark blame points................. Adding classes to a tracer group.................................................................................................................. Turning tracer groups on or off .................................................... Directive names and arguments used in tracer syntax ........................................................................ 8 Java Agent Guide .................................................................................................................................................................................................. Configuring GlassFish 2................................................................................................. Components traced by the default PBDs ........................................................ Turning on InstrumentPoint directives ........................................................................................ Instrumenting and inheritance ....................... and PBDs together .............................................................1 .................................. Using the ProbeBuilder Wizard or command-line ProbeBuilder ..... ............................................................................................................................................. How Introscope resolves agent naming conflicts ............. Specifying an agent name using a Java system property ...................................................................................................... Specifying an agent name using a system property key . Socket metrics ................................ Cloned agent naming scenario .......................................................................................................... How the agent determines its name ................................................................................... 170 Contents 9 ................... Agent naming considerations for clustered applications ........................................... Configuring logging options .........................................................................................................Chapter 8: Java Agent Naming 147 147 148 149 150 150 151 151 151 152 153 153 155 155 155 156 Understanding the Java Agent name ............ and socket tracing in the application triage map ................................................................... Restricting socket and SSL metric collection .... Changing the name or location of the agent logfile ........................... Fine-tuning socket and SSL metric collection ...... Redirecting agent output to a file.............................................................................................. Rolling up logs by date or size .......................... Chapter 10: Using Virtual Agents to Aggregate Metrics 169 Understanding Virtual Agents ........................ Agent log files and automatic agent naming ....................................................................... Command-line ProbeBuilder and ProbeBuilder Wizard log name and location ................................................................................................................. Enabling cloned agent naming in clustered environments ....................................... Backwards compatibility .............................................................................................................................. Managing ProbeBuilder Logs ..................................... Running the agent in verbose mode ............................... Configuring unique names for application instances ...................................................... 169 Configuring Virtual Agents ... AutoProbe log name and location ................................. Automatic agent naming and renamed agents ....................................................... Advanced automatic agent naming options . 169 Virtual Agent requirements ...................... NIO..................................................................................................................................... Application triage map and the agent name ..... Turning off socket and SSL metric collection ............................. SSL..................................................................................................... Automatic agent naming ................................................................ Application servers that support agent naming ..................... Chapter 9: Java Agent Monitoring and Logging 157 157 158 159 159 160 161 162 162 163 164 165 165 166 167 167 167 Configuring agent connection metrics..................... Obtaining an agent name from the application server .................................. ......... LeakHunter timeout log entry ................................................................................................. Configuring failback to primary Enterprise Manager ................... Using ErrorDetector ..................................................................................................................... Defining new error types ....................................................................................................................................................................................................... Ignoring collections that cause poor performance ......... Running LeakHunter ................. ExceptionErrorReporter .. Using LeakHunter ......................................................... ErrorDetector.... Enabling and disabling LeakHunter ............................................... Configuring LeakHunter properties ............................................................. MethodCalledErrorReporter ............................................................... Identifying potential leaks with collection IDs . Chapter 12: Configuring LeakHunter and ErrorDetector 177 177 178 179 179 180 180 181 182 183 183 184 184 185 186 186 186 187 187 188 189 189 190 190 191 191 191 192 192 192 193 LeakHunter ............................................................................................... Configuring domain/user information ......................................... HTTPErrorCodeReporter ........................................................................Chapter 11: Configuring Java Agent Failover 173 173 174 175 175 176 Understanding agent failover ............. How ErrorDetector works ........................................................... What LeakHunter does not track .......................... Using error tracer directives with caution ........................................................... 10 Java Agent Guide ........................................................................................ Defining failover connection order ........................................................................ How LeakHunter works .... Types of errors .. System and version requirements ..................................................................... Advanced error data capture ................................................................... Potential leak first identified log entry ................................................ Enabling ErrorDetector in the Java Agent ........................................................................................................ Identified potential leak is leaking again log entry ................................................................................................................. Configuring ErrorDetector options ............................................................................................................................................................ What LeakHunter tracks in Java ........................................................................................... More help .......................... Defining backup Enterprise Managers........................................................................................................................................................................................... ThisErrorReporter ..... Identified potential leak stops leaking log entry ................................................................................................ LeakHunter log file .................................................................................. ............................. How poorly written SQL statements create metric explosions ................................... Agent heap sizing ............... Transaction Trace component clamp ..................................... Define the name for a URL group ......................... SQL metrics .................................................................................................................... Using Blame tracers ..... Contents 11 ........................................................................ Configuring cross-process Transaction Tracing ..................................... Configuring Agent to collect additional transaction trace data ... Advanced naming techniques for URL groups (optional) ............................................ SQL statement normalization ....................................................................... Disabling Boundary Blame ....................................................................... Using URL groups .......................... Defining membership of each URL group ..................0 JMX metrics ........... Chapter 14: Configuring Transaction Trace Options 203 203 203 204 205 205 205 206 206 207 208 Controlling automatic Transaction Tracing behavior ..................................... Managing metric volume with JMX filters ............................ Chapter 15: Configuring the Introscope SQL Agent 209 209 210 210 210 212 218 218 219 The SQL Agent overview ..................................................................... SQL statement normalization options .............. About servlet request data ........................................................................................................................................................................................... Turning off statement metrics . Turning off Blame metrics ...............................................................................................................................................................................................................Chapter 13: Configuring Boundary Blame 195 195 196 196 197 197 198 201 201 201 Understanding Boundary Blame ............................................. Disabling the capture of stalls as Events ......................................................................... Transaction trace sampling ....................... Using primary key conversion to streamline JMX metrics ............................................................................... Extending transaction trace data collection .................................................... Defining keys for URL groups ............................................. Default JMX metric conversion process .................... The SQL Agent files .......................................................................................................................................................................................................................................................................... About User ID data .................................. Running the URLGrouper .......................................................................... Chapter 16: Enabling JMX Reporting 221 221 222 222 223 224 Introscope Java Agent JMX support............................. Introscope support for WebLogic 9....................................................................... ............. introscope......................................................................agent.......................agentAutoNamingMaximumConnectionDelayInSeconds ........................... introscope.................. introscope.................................. introscope........................... Troubleshooting platform monitoring ...................... 12 Java Agent Guide ..................hostName......... introscope....................................................................................agent................ Agent metric clamp ...........................................................................................enterprisemanager.................................................................................... Command-line property overrides .....................failbackRetryIntervalInSeconds ........customProcessName ....................................................... introscope......agent.....................................................................................................................................................................................as.............. Troubleshooting platform monitoring on Windows ..................agent.........agent.................................. Agent HTTP tunneling ................ Disabling platform monitors ... introscope..........................................bizRecording................................................. introscope.......................... Enabling platform monitors on Windows Server 2003 ............................. introscope.................... Agent HTTP tunneling for proxy servers .................. Configuring agent metric aging...................................................... introscope......... Agent memory overhead ........................................... Agent metric aging .............metricClamp ....................................... introscope........................................................ introscope.........................profile location ..........disableLogFileAutoNaming .......................................................................................................................agent..................reduceAgentMemoryOverhead ....agent.......agent........................agent......................................................disableLogFileAutoNaming ......agent..................... Appendix A: Java Agent Properties 237 238 239 239 240 240 241 241 242 244 244 244 245 249 250 250 251 251 252 252 253 253 254 254 255 255 256 256 257 Configuring the IntroscopeAgent.....................................................................agentAutoRenamingIntervalInMinutes ......................agentAutoNamingEnabled .....x ............. 224 Configuring JMX reporting ......agent...........agent.................................................fqdn ......agent............agent......agentName ............... Agent naming ............. Agent recording (business recording) ...........agentNameSystemPropertyKey ...enabled .. Enabling platform monitors on AIX ....................agent........................enterprisemanager................connectionorder .................................................. 225 Enabling JSR-77 data for WAS 6......... introscope......... introscope....................................JMX filters for WebLogic ...... Agent HTTPS tunneling ..............display.......................................... 226 Chapter 17: Configuring Platform Monitoring 229 229 231 231 232 234 234 Understanding platform monitors ..................... introscope............................................. Agent failover ...clonedAgent ...................................................................defaultProcessName ....... introscope....agent....... ..........sockets.....agent............agent.............................agent.socketfactory..............tcp..........queue....... introscope.appmap..sockets.....transport..............................................managed........sampling...............agent... introscope..tcp....DEFAULT .......queue.......agent........... introscope.....agent..........changeDetector........................ introscope...................................................................................................bizdef.appmap........managed........agent.......initial.......matchPost ................................bootstrapClassesManager....................................port......................... Bootstrap Classes Instrumentation Manager ...sockets..................changeDetector..............agent..transport........ Application triage map managed socket configuration ............................... introscope.........waitAtStartup ........................... introscope............ introscope...........................................................................changeDetector.....................reportClassAppEdge ......................sampling......................bootstrapClassesManager..................autoprobe..........................agent...agent.enterprisemanager. introscope................................ introscope.....tcp............agent....................... introscope..................................enabled..... Application triage map business transaction POST parameters .............. introscope............. AutoProbe ...............agent....reset............... ChangeDetector ........agent..............directivesFile .......agentID ..........size ............... introscope...........agent...............agent.. Application triage map .... introscope.....catalystIntegration........ introscope.enterprisemanager................sampling..........changeDetector....................................enabled ...... Known limitations ........................................................agent.. Blame ............................reportMethodAppEdge ......appmap......... introscope............ introscope.................................metrics.................agent...enable ...................................autoprobe.... introscope......isengardStartupWaitTimeInSec .........................managed......logfile ......................................... introscope..............................Agent thread priority ..... introscope..................tracer..........blame.................................enabled .type ......................................................tracer......................reportMethodBTEdge ..........sockets............................. introscope...............reportClassBTEdge . introscope..waitTimeBetweenReconnectInSec .....appmap...period ...........................appmap.... Agent to Enterprise Manager connection .................... introscope. CA Wily CEM integration .enabled ................................DEFAULT ................agent..............................transport.............agent............changeDetector.....enable .autoprobe.........................period ...........enterprisemanager................................ introscope... introscope..thread.....priority ........ 257 258 258 258 259 259 260 260 261 261 262 262 263 263 264 265 265 266 266 267 267 268 268 269 269 270 270 270 271 271 272 272 272 273 273 274 274 275 275 276 276 276 Contents 13 .............................................................. introscope........ introscope.......intermediateNodes...........................reportToAppmap ............................agent..........................appmap.......period ..................maxrate ...............enabled ..................................... introscope..................managed........................................................................ introscope............................................managed. introscope...rootDir .........sockets.............. introscope.............all.........................tracer... Application triage map transaction sampling .....host..................DEFAULT ............................... .....................agent..................errorsnapshots..throttle ..............dynamicinstrument................................jsr77.agent....................................................changeDetector...................................... ErrorDetector.name..................... 277 277 278 278 278 279 279 279 280 280 281 281 281 282 282 282 283 283 284 284 284 285 285 286 286 287 292 292 293 294 295 296 297 297 298 298 299 299 300 300 301 301 14 Java Agent Guide ..........................agent................ introscope... introscope...............introscope.............................logfile. Cross-process tracing in WebLogic Server ....................................enable ...................... Channels ........dynamicinstrument.pollIntervalMinutes ...........................agent.....extensions.................................................. introscope.................. Java NIO .............jmx............remoteagentdynamicinstrumentation...........................agent...agent.............attributes ....................... JMX ...............................................agent.................... introscope.ignore.......................agent..autoprobe......... Logging ........ introscope.append ....... introscope.......................... introscope...............................................................agent............................tailfilterPropagate.classFileSizeLimitInMegs ......................<number> .................leakSensitivity .............................................. introscope.............................................profileDir .................agent..............autoprobe............ Extensions ..leakhunter........................ignore.........leakhunter..logfile....................changeDetector........................................................ introscope......leakhunter.....................agent...weblogic..............dynamicinstrument............................... introscope....agent.leakhunter.............autoprobe.................................... Buffers ..................enabled ....... introscope.................... introscope..................primarykeys ...name......... introscope....................... LeakHunter .....enable ............compressEntries.....changeDetector......autoprobe...................................................agent.................................excludeStringMetrics . introscope........... introscope. autoprobe.......enable ..................... introscope........ Dynamic ProbeBuilding ........................... introscope......................... introscope.. NIODatagramTracing metrics .... introscope................................agent.............enabled ............................enable ..name...........agent..........errorsnapshots.leakhunter....................crossjvm ..................agent..............................agent.................................................. introscope......profile ...leakhunter............................................jmx..location ...batchSize ...................collectAllocationStackTraces .............changeDetector.........jmx... introscope.........jmx........ introscope................................. introscope...................pollIntervalMinutes ...............................................................................directory ....................................agent......limitRedefinedClassesPerBatchTo ................. introscope......................................timeoutInMinutes..............filter ...disable ......leakhunter....................jmx......................................jmx....................................compressEntries.dynamicinstrument................<index> .......................... introscope........................................... introscope.........transactiontracer...................................................... Restricting Java NIO metrics ...............agent.......................... Cross-process transaction trace ................................... introscope......................ignore..dynamic..errorsnapshots...................................................agent....................enable ... ...... introscope........sqlagent....................agent........................decorator................agent.logfile..................agent..............................................autoprobe...............IntroscopeAgent..................pbdlog ......appender...... introscope.........File.....hosts ...............key1....................logger..hierarchysupport..........socket......hierarchysupport..................sqlagent.....................io................logger.. Socket metrics ....................................................... introscope....IntroscopeAgent................. introscope.............sockets........................................ Servlet header decorator ....autoprobe.....allowedFiles .socket...regex.. introscope....... introscope. introscope...... introscope...agent.. introscope...... introscope...............................transport.............agent........... 302 303 303 304 304 305 305 306 306 307 307 308 308 309 309 310 310 310 311 311 311 312 312 312 313 313 313 314 314 315 315 316 316 317 318 318 319 319 320 320 321 321 Contents 15 .............normalizer........................ Remote configuration ...............agent.....................layout ........appender............normalizer....additivity........................ introscope.... introscope.............................................regex........................ SSL communication .......count ............................extension ...autoprobe...............................................................replaceFormat ..... introscope........................enterprisemanager.....................agent..........................................keys .. introscope........................autoprobe..........................................agent.............key1.pbdlog......... Multiple inheritance ........................ log4j.........disableDirectivesChange ...........matchFallThrough .........ConversionPattern ............. introscope..pbdlog. Platform monitoring ..........agent.........................hierarchysupport.............................................. introscope........socket............ introscope...useblame ........inheritance .....agent............................normalizer.pbdlog......................platform.........................hierarchysupport...................agent.....appender...server. introscope...................system ...................agent............key1...........io....remoteagentconfiguration.........................agent...........................metric..................DEFAULT .....................client...............................................................................remoteagentconfiguration............agent.......... SQL Agent..............host........layout............caseSensitive ........................................log4j....... log4j........................ log4j. Security ...pattern .......................... log4j.............hierarchysupport............normalizer...........monitor. introscope............. introscope............................sqlagent........agent...........................hierarchysupport.................enabled ............................................autoprobe............agent. introscope........regex.... log4j.runOnceOnly .....io......decorator............... introscope......replaceAll ...regex........................IntroscopeAgent .................. introscope......................... log4j.....regex..enabled ..........normalizer..regex............ introscope..................................agent......................key1..........ports .. introscope.....appender.........ports ...sqlagent..executionCount ...normalizer............................... Metric count ...................................enabled ...................................inheritance ....agent...sqlagent..sqlagent.... log4j..............appender...............................................security .tcp...ext......File .................................................sqlagent.....................sqlagent.............disableLogging ............pollIntervalMinutes ............agent..................................autoprobe..normalizer...reportRateMetrics ...client..... .........ttClamp ...................sampling.............. introscope......tcp...transactiontracer...... introscope.....................enable..pmi........ introscope.................................. introscope...count .............................. introscope...transport......................agent....................agent.........enable......................agent.. introscope.......................enterprisemanager..................transactiontracer......................agent.compression...enterprisemanager................agent.......transactiontracer........pmi......................transactiontrace............... introscope...agent.............correlationid....agent............. introscope....agent.DEFAULT ..transactiontrace.... introscope................ciphersuites..transport........agent......................................agent..............agent................ introscope......agent.............agent..................... introscope....... Stall metrics ...................... introscope...enterprisemanager..................agent....pmi..sampling.........................pmi......................enable........................connectionPool ..compression .minlimit ..jvmpi ..headFilterClamp ...agent.enterprisemanager.............scheduler .......stalls..... introscope..........resolutionseconds .interval..................default.........j2c ..agent..........agent................................format ...........................agent..DEFAULT .............default...pmi..maxlimit .pmi............... introscope................enable..tcp.............. introscope...pmi..perinterval..................................... introscope......... introscope.........urlgroup....agent...........cache ........................... introscope............agent......port...keystore.stalls.......parameter...............seconds............... Transaction tracing ..... introscope.............. introscope...........enable.......... introscope.....enable..........method .......parameter..........group...........enabled.....crossprocess.......... introscope..httprequest..........transactiontracer...... WebSphere PMI ...............alarmManager .transport.............enable...transactiontracer.... introscope......urlgroup......DEFAULT .tcp.................transactiontracer.................................. introscope....agent..........transactiontracer.............orbPerf ......................sampling..agent.........truststore........enable .............. introscope.........pmi.............group.enterprisemanager....transport..thresholdseconds ........................................agent..............parameter.....trustpassword......... URL grouping .agent..........agent.......agent.................enable.httprequest...............................key ..transactiontracer....httpsession....DEFAULT .......transport.......................enable........tcp..................agent..DEFAULT ...............agent.userid.....................agent....crossprocess........ introscope................tcp....enterprisemanager....enterprisemanager...............tcp.......................................enable..... introscope..attributes ....agent........... introscope........ introscope....keypassword.agent....pmi...............................agent. 322 322 323 323 323 324 324 324 325 325 326 326 327 327 328 329 330 331 332 333 333 334 334 335 336 336 337 337 337 338 339 339 340 340 341 341 342 342 343 343 344 344 16 Java Agent Guide .DEFAULT..........enable.......................... introscope.transport.......................pmi...............pathprefix ...userid......... introscope....agent.............................................................................bean ....agent...........agent....jvmRuntime ...............componentCountClamp ...DEFAULT ...........agent................keys ...objectPool .....................urlgroup........pmi....agent..socketfactory............ introscope............................ introscope...........parameters .............crossprocess............hamanager ... introscope......headers ..... introscope....... introscope..tcp........................... introscope...agent....pmi.........................introscope.transport...... .................................... introscope...............................filter.........agent.... introscope...................... Required PBD Generator parameters ...........introscope..........................wlm .......................................................................................agent..........objref .......................enable.....lax file ...... Using the CA Wily PBD Generator ...................agent............................................... Manual ProbeBuilding options .................. Switching back to non-instrumented code ............. Configuring Sun ONE 7.....agent.................................................................................pmi.... The ProbeBuilder Wizard...... Update the application startup script ........................pmi..........................................enable...0 ............................... Adding Probes to bytecode ...........servletSessions ............ introscope...........................pmi........enable...enable.......................................pmi..............agent...................webApp ................webServices ....... 345 345 346 346 347 347 348 348 349 349 350 Appendix B: Using the CA Wily PBD Generator 351 351 352 352 352 About the CA Wily PBD Generator ...........agent.......................................agent.................................... Configuring the CA Wily PBD Generator .pmi............................ Configuring HTTP servlet tracing .......................... introscope...... WLDF metrics..........................................enable.. Configuring Oracle 10g 10.. Running instrumented code .....................................................................................................................transaction .............................................................wsgw ....................................agent... introscope.................................................pmi............................................pmi..... introscope......... Using the command-line ProbeBuilder ......................................... introscope........................................................................................................................ Index 369 Contents 17 .................................pmi..................3 .................. introscope.pmi............................ Appendix D: The Java Agent and Application Server AutoProbe 365 365 366 367 368 368 Deploying the Java Agent on other application servers ....agent.................................enable ....................... Appendix C: Manual ProbeBuilding 355 355 356 356 358 358 359 361 361 362 362 Before you begin .................................... Using the ProbeBuilder wizard ...........wldf.......enable.............agent................................................................enable....................enable..0................ introscope............................................................................................................................threadPool ........................................ Editing the classpath .... Configuring WebLogic Server .system .................. . and Application triage map transaction sampling (see page 268). Chapter 1: The Java Agent Overview 19 . This map is automatically generated from performance and analysis of Introscope metrics. errors.Chapter 1: The Java Agent Overview The topics in this section describe the Introscope architecture and the Java Agent deployment process. Application triage map business transaction POST parameters (see page 263). The metrics collected by the Java Agent and sent to the Enterprise Manager support the generation of the application triage map. The application triage map enables you to instantly grasp the layout of the applications in your environment in a visual manner to help you identify and triage current and emerging problems.0: ■ ■ ■ ■ ■ ■ Application triage map support (see page 19) Agent-only business transaction recording (see page 20) Dynamic instrumentation (see page 20) Java New Input/Output (NIO) (see page 21) Multiple inheritance support (see page 21) LeakHunter and ErrorDetector configuration (see page 21) Application triage map support The application triage map presents a graphical visualization of the components that make up your application. This section contains the following topics: Documentation Changes (see page 19) The Introscope environment (see page 21) Planning a Java Agent deployment (see page 23) Deploying the Java Agent (see page 25) Documentation Changes This release includes the following new or changed features that affect configuration and administration of the Introscope Java Agent 9. Application triage map managed socket configuration (see page 265). see Application triage map (see page 260). showing application health and errors. and events. For more information about the properties used to configure application triage map data. It presents applications in the business-centric terms that you’ve defined. Instrumenting a method dynamically means inserting the instrumentation during runtime. see EJB 2. and then monitor these transactions in the Introscope Workstation. 20 Java Agent Guide . NIO. Users can dynamically instrument one. dynamic instrumentation (see page 71).0 and 3. see SSL. Introscope 9. This allows users to do dynamic application performance tuning.0 for the application triage map. or all of the methods during a transaction trace session.0 allows you to record information from agents using the Wily CEM console. For example. and socket tracing in the application triage map. and socket tracing in the application triage map (see page 160). For support for EJB 2. For SSL. see the CA Wily APM Transaction Definition Guide. The data from the agent shows which specific business transactions the Purchasing application is having problems with. and subsequently view metrics returned by the newly instrumented methods.Documentation Changes For more information about the ProbeBuilder Directives used to configure application triage map data. For more information on how to record business transaction information using the agent. see Agent recording (business recording) (see page 256).0 agents can now record and monitor transactions. For more information about configuring the agent for business transaction recording.0 support for the application triage map (see page 127). you can record a business transaction in your Purchasing application with the agent. NIO. see Default PBD files (see page 111). allowing you to track information about how your application is doing from a business perspective. The business transaction information works hand-in-hand with the information gathered by application triage map support to display the activity of your application in a graphical format. For more information about the application triage map and viewing information in the map. Agent-only business transaction recording Introscope 9. see the Introscope Workstation User Guide. more.0 and 3. Dynamic instrumentation Dynamic instrumentation is performed from the Introscope Workstation transaction trace viewer. see Dynamic ProbeBuilding vs. For more information about dynamic instrumentation. LeakHunter and ErrorDetector configuration LeakHunter and ErrorDetector are now included in the core Introscope installation. For more information. Chapter 1: The Java Agent Overview 21 . Which data the probes monitor is controlled by ProbeBuilder Directive (PBD) files. The Enterprise Manager processes and analyzes the data received from the Java Agent. This ability has been extended to dynamic instrumentation in Introscope 9. and performance and availability data from the surrounding computing environment.4. As such. which you can change to suit the monitoring needs of your environment. the configuration information for LeakHunter and ErrorDetector has been incorporated into this guide. The agent’s Java NIO metrics capture information about how instrumented applications use Java NIO. For more information. where you can review the information and set up actions and alerts based on the data received. and resolve these issues quickly and collaboratively. see Configuring LeakHunter and ErrorDetector (see page 177). Multiple inheritance support The Introscope Java Agent supports instrumentation by interface as well as multiple inheritance. or NIO) capabilities introduced in Java 1. You can access this information from the Introscope Workstation. as well as the application server. and then sends it to the Introscope Enterprise Manager. For more information. A new tracer to instrument interfaces and abstract methods is available. The Introscope environment CA Wily Introscope is an enterprise application performance management solution that enables you to monitor complex web applications in production environments 24x7. detect problems before they affect your customers.0. The Java Agent uses probes in the application byte code to gather this data. and abstract methods (see page 73). interfaces. see Support for multiple inheritance. The Java Agent is the component of Introscope that collects performance data from applications running on Java Virtual Machines (JVMs). Java NIO is a collection of APIs designed to provide access to the low-level I/O operations of modern operating systems.The Introscope environment Java NIO The Java Agent supports the Java New I/O (Java NIO. see Java NIO (see page 21). Several standard PBDs are included when you install the Java Agent. as well as specific PBDs for your application server.The Introscope environment The types of data collected by the Java Agent depends on which ProbeBuilder Directive (PBD) files you choose to implement. 22 Java Agent Guide . The figure below illustrates the key components of an Introscope environment. Fine tuning the tracers and directives in the PBD files delivers the metric information you want to monitor for your environment. A default Java Agent configuration demonstrates data collection functionality and is key to understanding and evaluating the out-of-the box features of the Java Agent and Introscope as a whole. a default Java Agent configuration is included. When evaluating the environment. the more data (metrics) a Java Agent collects. you will streamline data collection to balance the depth of data collection against overhead constraints and arrive at a configuration that employs the proper level of instrumentation that delivers essential information. the primary goal is to understand the depth and breadth of Introscope’s data collection and application management features. Discover Introscope functionality The first step in developing an Introscope implementation involves "test driving" the default Introscope Java Agent configuration. The Java Agent provides a variety of data collection options out-of-the box and can be customized to collect more environment-specific data. however. the more system resources it consumes. When you install Introscope. As you refine your Java Agent configuration. Chapter 1: The Java Agent Overview 23 . The figure below illustrates the key processes in a Java Agent configuration and deployment process. Naturally.Planning a Java Agent deployment Planning a Java Agent deployment It is important to develop the right Java Agent configuration for your applications and the environments in which they run. In pre-production environments. Create and define Java Agent configuration After defining your configuration requirements based on your application and its operating environment. If you intend to collect data from multiple environments. Most high level Java Agent behaviors are configured in the agent profile ( IntroscopeAgent. you should determine your data collection requirements. or Introscope PowerPacks and ensure it is working before adding more. LeakHunter. Which metrics are gathered by the Java Agent are controlled by ProbeBuilder Directive and ProbeBuilder List files. you may choose to build up the agent configuration in stages so that you can evaluate the impact of each add-on component. Some features may also require some configuration in your application server or require other configuration steps. implement optional configurations such as Virtual Agents or agent failover. You will need to configure Java Agents differently to deliver on the goals for each phase or environment.profile). The goal is to obtain optimal visibility at a reasonable cost. such as development and QA. such as ChangeDetector. overhead. environmental constraints. Java Agent configuration is a trade-off between visibility vs. 24 Java Agent Guide . and production—your monitoring goals. you typically configure a higher level of data collection to provide deeper visibility into the performance characteristics of the application. This information will help you tailor the data collection behaviors of the Java Agent and evaluate the impact on overhead through alternative configurations of the Java Agent. whether pre-production or live.Planning a Java Agent deployment Determine configuration requirements Before introducing Introscope into your environment. you should create a "candidate" agent configuration. and when appropriate. you will need to develop an appropriate Java Agent configuration for each. you reduce the level of metric reporting to control Java Agent overhead. testing and performance. Depending on the complexity of your configuration and the target environment. Since Introscope is employed across an application lifecycle—in development. In production or production-like environments. and service level requirements will change over time. Restart your application and start data collection. a conservative approach is to extend data collection in a controlled fashion—for instance.Deploying the Java Agent Evaluate Java Agent performance overhead When evaluating a Java Agent configuration.profile and modified or custom PBD files—to the target environment. 4. see Java Agent configuration overview (see page 53) and ProbeBuilder Directives (see page 56). Configure the properties in the IntroscopeAgent. For example. Similarly. 2. you can load test your application before and after implementing out-of-the-box monitoring to verify impact. The Java Agent should not report more metrics than are necessary to identify and localize performance and availability problems. In practice. For more information. see Installing and Configuring the Java Agent (see page 27). you must understand the performance characteristics of the application prior to monitoring it with Introscope. Chapter 1: The Java Agent Overview 25 . Validate and deploy Java Agent configuration After you have verified that a candidate agent configuration provides the visibility required for the target environment without imposing unacceptable overhead. including which PBDs to use during the ProbeBuilding process and optional ProbeBuilding behaviors. one PowerPack at a time—and evaluate the impact of each add-on individually. To effectively understand and evaluate Java Agent overhead. the process of deploying a validated configuration includes installing the validated configuration artifacts—specifically IntroscopeAgent. verify that the metrics collected provide sufficient visibility into application performance and availability. Install the Java Agent on the target JVM. For more information. and that the volume of metrics do not impose an unacceptable load on the operating environment. For more information. Deploying the Java Agent The Java Agent deployment process follows these high level steps: 1. see AutoProbe and ProbeBuilding Options (see page 61). 3. you should deploy the validated configuration across that environment.profile file that govern the operating and data collection behaviors of the Java Agent. Configure the JVM to use a supported method of ProbeBuilding. . 5.0 Fujitsu Interstage Application Server v9. or 5.3 SP1. or 6. identify the Enterprise Manager to which the agent should send data.0.0. 5.0. decisions.1. 4. Application server support The following application servers with the required patches are supported by the Java Agent: ■ ■ ■ ■ ■ ■ Apache Tomcat 4. you need to verify the application server where you want to install is supported. and determine how Java classes should be instrumented. and resources that should be identified or obtained before you install and configure the Java Agent and the different methods you can use to install the agent.0 (Japanese & English) Oracle 10g Application Server version 10.10 Sun Application Server 8. This section contains the following topics: Before you begin (see page 27) Installing the Java Agent (see page 29) Java Agent installation directories and files (see page 43) Configuring the JVM to use the Java Agent (see page 48) Starting the Java Agent (see page 48) Connecting to the Enterprise Manager (see page 48) Java Agent configuration overview (see page 53) Upgrading multiple agent types (see page 57) Uninstalling the Java Agent (see page 59) Before you begin Before you install and configure the Java Agent.1 Chapter 2: Installing and Configuring the Java Agent 27 .1.0.Chapter 2: Installing and Configuring the Java Agent This section provides instructions for installing the Java Agent. or Sun Glassfish 2.3 with any required updates SAP NetWeaver 7.2.5. 4. including key information.2x.0 JBoss 4.0. 9. see Configuring Java Agent Failover (see page 173). The Introscope Enterprise Manager supports Java Agents 6. with any required patches Important: Java Agents. If you have multiple Enterprise Managers. do not support applications running on Java 1. When the Java Agent is installed on an application server.0 and higher. install the Java Agent as a different user. 28 Java Agent Guide . or 7. For more information on clustered Enterprise Managers. then use the commands appropriate for your application server to assign the necessary permissions to the agent files.3. or higher.0 with any required patches WebSphere Application Server on z/O 6. see Connecting to the Enterprise Manager (see page 48). If you have a Java 1.1. you can configure your Java Agent to failover to an alternate Enterprise Manager if it disconnects from its primary Enterprise Manager.Before you begin ■ ■ ■ WebLogic 9. Or. Because the agent runs inside the application server. where <Agent_Home> is the location of the Java Agent installation. use the 7.3.x-based application. see the Introscope Configuration and Administration Guide. install the Java Agent on the same operating system as the user who runs the application server process. For more information on connecting to an Enterprise Manager. the application server process must have full read/write/execute permissions on the <Agent_Home>/wily directory. For more information on the MOM Enterprise Manager. see Java Agent installation directories and files (see page 43).4.x-based application.2 10. Enterprise Manager connection information The Java Agent runs inside the JVM that runs the applications you wish to monitor and connects to the Introscope Enterprise Manager. To accomplish this.x . If your agent reports to a clustered Enterprise Manager you must configure it to connect to a Manager of Managers (MOM) Enterprise Manager.x or 10. If you have a Java 1. use the 8.9. For more information on agent failover to alternate Enterprise Managers. a Wily log directory is created here: <Agent_Home>/wily/logs. Fore more information on the file structure created when the Java Agent is installed. after the server with the Java Agent starts.x.2 Java Agent to monitor that application.0.0 and higher. clustered or not.1. version 9.x with any required patches WebSphere Application Server 6.x Java Agent to manage that application.4. see the Introscope Configuration and Administration Guide . which performs several tasks for you. as described in The Java Agent and Application Server AutoProbe (see page 365). perform the ProbeBuilding process manually. you will not be able to use some of the new agent features. You should select only one method for installing a Java Agent. Other ProbeBuilding options Very rarely. where you perform all installation tasks.5 JVM JRockit 1. Other methods of instrumentation should only be used if JVM AutoProbe fails.5 or higher HP Hotspot 1. CA Support may be able to resolve your functionality problems with JVM AutoProbe.5 or higher Most CA Wily Introscope users instrument their applications using JVM AutoProbe. Chapter 2: Installing and Configuring the Java Agent 29 . there are two other options: ■ ■ configure Application Server AutoProbe. please contact CA Support before attempting the above ProbeBuilding options. For more information. JVM AutoProbe is supported if you use: ■ ■ ■ ■ Java 1. If you find that your JVM does not work with JVM AutoProbe. as described in Manual ProbeBuilding (see page 355). see The Java Agent installer (see page 30). see Manual installation (see page 40). a JVM might not support JVM AutoProbe.5 JVM or higher Sun or IBM 1. If JVM AutoProbe does not function with your JVM. Important: CA Technologies highly recommends using JVM AutoProbe to instrument your applications. Installing the Java Agent There are two methods of installing the Java Agent: ■ Use the Java Agent installer. For more information. or will be able to recommend the best alternative for your environment. adding probes that generate metrics from the Java bytecode. If you do not use JVM AutoProbe to instrument your applications.Installing the Java Agent JVM AutoProbe CA Technologies recommends using JVM AutoProbe to dynamically instrument all classes loaded by the JVM. OR ■ Manually install the Java Agent. Using both methods at the same time may cause the Java Agent to not function correctly. bin and a response file. OS/400 .IntroscopeAgentInstaller9. Edits certain settings in the IntroscopeAgent. select the installer appropriate for your operating environment: ■ ■ ■ ■ Windows . that JVM also must be version 1.tar contains IntroscopeAgent9.Installing the Java Agent The Java Agent installer The Java Agent installer is an operating system specific program that automates several of the installation tasks.0os400. To use the Java Agent installer.profile.0. For more information.0unix. The Java Agent installer has three modes it can be used in: ■ GUI mode: an interactive installer that allows you to select components for installation from menus. UNIX .tar contains IntroscopeAgent9. or installs an agent profile provided by you. ■ ■ 30 Java Agent Guide .zip contains the IntroscopeAgent9.0. making it easier to deploy agents across large environments. On these platforms.zip contains IntroscopeAgent9. Generates the connector .exe and a response file. Before exiting. a tmppath file. Note: The Java Agent installer must be launched with JVM 1.0.jar. For more information.sh script. For more information. If you specify an application server JVM. if appropriate. Silent mode: an installer that requires no interaction with a GUI or console. the console installer launches automatically. Installs any custom PBDs. z/OS .jar.0.IntroscopeAgentInstaller9. z/OS. add-ons. a runinstaller. or PowerPacks you select. Silent installations use settings specified in a response file. Selections made for the installation are input in to a command line interface. or OS/400. a runinstaller.0unix.5 or later.IntroscopeAgentInstaller9. including platform monitors and PBDs for the target environment. see Installing the Java Agent in silent mode (see page 36). see Installing the Java Agent in console mode (see page 34). it performs the following tasks for you: ■ ■ ■ ■ ■ Installs the Java Agent. and a response file. Console mode: an installer supported on most non-Windows platforms.0windows. the installer prints the location of a text file that contains application server-specific "Next Steps".5 or later. and a response file. see Installing the Java Agent in GUI mode (see page 31).0zOS. such as UNIX.IntroscopeAgentInstaller9.0.jar.0.0zOS.0windows.0os400.0. When you use the Java Agent installer.0.sh script. This directory will become the <Agent_Home> referred to in the rest of this guide. located in the <Agent_Home>/wily directory that will be installed. ■ If you choose to use a custom agent profile. ■ Whether you want to use a custom agent profile. the installer suggests the application server root directory. If you supplied a root directory on the first screen of the install process. or create a new agent profile when the agent is installed. and the Enterprise Manager host and port. Choose an installer that matches your target environment and open it.Installing the Java Agent Installing the Java Agent in GUI mode The GUI mode of the Java Agent installer allows you to make selections from drop-down menus. / on UNIX). you need to open a terminal and launch the Java Agent installer with the following command: IntroscopeAgent<version>unix. To install the Java Agent using the installer in GUI mode: 1.bin -i swing Where <version> is the release number you want to install. You will need to know the following: ■ The location of the application server root directory. If you did not specify an application root directory. Where you want the install directory to be located. the installer will ask you for the location of the this file. If you choose to create a new agent profile. ■ ■ The application server type. Supply the fully qualified path to the file location. These values can be configured after installation in the IntroscopeAgent. the agent and process name. you must decide to use either typical or full instrumentation.profile. If you are installing the Java Agent on Linux. Follow the onscreen prompts to install the Java Agent. and the Enterprise Manager host and port. 2. the default Introscope install directory is suggested. Do not use unzip. Chapter 2: Installing and Configuring the Java Agent 31 .tar file. you must use the tar -xvf command to extract the . you should accept the default response (C:\ on Windows. ■ Note: Empty values are allowed for both the agent and process name. If you do not want to specify an application server root directory. ■ ■ If you are installing the Java Agent on a UNIX system. profile to enable ChangeDetector. see AutoProbe and ProbeBuilding overview (see page 61). If you later want to enable ChangeDetector. see the Introscope ChangeDetector User Guide. If you choose not to enable the ChangeDetector agent extension. the next screen will ask you to name the ChangeDetector agent. the ChangeDetector files will be placed in the <Agent_Home>/wily/examples directory. 32 Java Agent Guide . see Java Agent installation directories and files (see page 43).enable property in the IntroscopeAgent. ■ ■ ■ If you decide to enable ChangeDetector.Installing the Java Agent ■ ■ Name of the agent and process. ■ ■ Specify the Java executable that is used to launch your application server.changeDetector. The instrumentation level. The Enterprise Manager host name and port. Select between Full or Typical. This information can be added later. You can change the instrumentation levels after installing if you choose. See Connecting to the Enterprise Manager (see page 48) for more information. For more information about ChangeDetector. Choose whether to enable the ChangeDetector agent extension or not. For more information on instrumentation. Specify the ProbeBuilding method that will be used to instrument your application. For more information. Typical consumes less overhead and is recommended for production environments. copy the files to the <Agent_Home>/wily/ext directory and modify the introscope. ■ ■ ■ Full produces more detailed reporting and is recommended for QA or development environments. For more information on the directory structure and files that are installed with the Java Agent. see AutoProbe and ProbeBuilding overview (see page 61). CA Technologies recommends using JVM AutoProbe. the files for all the PowerPacks are stored in the <Agent_Home>/wily/examples folder. If you choose not to install PowerPacks. If you choose to enable SOA agent extensions: ■ Two PBD files. ■ Select PowerPacks you want to install using the check boxes provided. For more information on the directory structure and files that are installed with the Java Agent. For more information on the directory structure and files that are installed with the Java Agent.jar files are added to the <Agent_Home>/wily/ext directory. copy the selected PowerPack files from the <Agent_Home>/wily/examples folder to the <Agent_Home>/wily/ext folder. For more information about configuring SOA Performance Management or SOA extensions. see Java Agent installation directories and files (see page 43).jar and BoundaryOnlyTrace. only PowerPacks that function with that application server are available for selection. are added to the introscope. the files are stored in the <Agent_Home>/wily/ext folder as well as the <Agent_Home>/wily/examples folder.Installing the Java Agent ■ Choose whether to enable SOA Performance Management and SOA extensions or not. Select the check box next to the components you want to enable. appmap-soa.autoprobe. Chapter 2: Installing and Configuring the Java Agent 33 .directivesFile property in the IntroscopeAgent. For the PowerPacks you choose to install.pbd and webservices.profile. Refer to the PowerPack documentation for more configuration information. If you want to install additional PowerPacks at a later time. see Java Agent installation directories and files (see page 43). see the SOA Performance Management Guide. Depending on the application server JVM you chose. ■ If you do not enableSOA Performance Management or SOA extensions. files for enabling them later are added to the <Agent_Home>/wily/examples directory. The WebServicesAgent.pbd. 34 Java Agent Guide .Installing the Java Agent ■ The location of a "pickup folder". On these platforms. These tasks need to be performed manually. you should accept the default response (C:\ on Windows. If you do not want to specify an application server root directory. by default <Agent_Home>/wily. When using the Java Agent installer in console mode. ■ The application server type. 3. such as UNIX. you will need to know: ■ The location of the application server root directory. click Install. which contains: ■ ■ the specific steps the installer took to install the Java Agent. The installer will install the Java Agent. Installing the Java Agent in console mode The Java Agent installer in console mode is supported on most non-Windows platforms.tar files in this folder are extracted into the agent directory. When the installation is complete. The GUI installer does not stop or start the application server. the installer provides a fully qualified path to the Introscope_Agent_Installation_README.zip or . the console will prompt you to enter information about your installation. Any . / on UNIX). the installer will provide reasonable error messages explaining the problem and how to correct it. For example. the next steps that must be performed manually in order to complete the installation. or OS/400. z/OS. The Java Agent can monitor the following application servers: ■ ■ ■ ■ ■ ■ ■ ■ Default WebSphere JBoss Sun Application Server Tomcat Oracle WebLogic Interstage ■ Where you want the install directory to be located. the console installer launches automatically.txt file. or modify the application server JVM configuration parameters. If unusable input is provided for any of the above options. When you are finished making selections. changeDetector. The instrumentation type. the ChangeDetector files will be placed in the <Agent_Home>/wily/examples directory. see the Introscope ChangeDetector User Guide. For more information on JVM AutoProbe. and the Enterprise Manager host and port. or create a new agent profile when the agent is installed. ■ ■ If you choose to use a custom agent profile. For more information on configuration and use of ChangeDetector. appmap-soa. and the Enterprise Manager host and port. see Configuring JVM AutoProbe (see page 62). Chapter 2: Installing and Configuring the Java Agent 35 . you must decide typical or full instrumentation. name the ChangeDetector agent/ If you choose not to enable the ChangeDetector agent extension. These values can be configured after installation. Enable the ChangeDetector agent extension or not. If you choose to create a new agent profile.jar and BoundaryOnlyTrace.jar files are added to the <Agent_Home>/wily/ext directory. are added to the introscope.profile. ■ Enable SOA Performance Management and SOA extensions or not. If you do not enableSOA Performance Management or SOA extensions.enable property in the IntroscopeAgent.autoprobe. files for enabling them later are added to the <Agent_Home>/wily/examples directory. If you later want to enable ChangeDetector. the agent and process name. If you chose to enable SOA agent extensions: ■ ■ Two PBD files. Supply the fully qualified path to the file location. ■ ■ ■ ■ If you decide to enable ChangeDetector.pbd and webservices. ■ ■ ■ The agent name and process name.Installing the Java Agent ■ Whether you want to use a custom agent profile. Empty values are allowed for both the agent and process name. The application server JVM. the installer will ask you for the location of the this file. copy the files to the <Agent_Home>/wily/ext directory and modify the introscope. see the SOA Performance Management Guide.directivesFile property in the IntroscopeAgent. For more information about configuring SOA Performance Management or SOA extensions. The WebServicesAgent. CA Technologies recommends using JVM AutoProbe.profile to enable ChangeDetector.pbd. Connection settings for the Enterprise Manager. These tasks need to be performed manually. Silent installations use the settings specified in a response file.txt file to reflect your preferred settings. which requires no interaction with a GUI or console.Agent.txt file.tar files in this folder are extracted into the agent directory.profile generates a connector .Installing the Java Agent ■ Select the PowerPacks you want to install using the check boxes provided.jar files into your application server directories. 2. Edit the SampleResponseFile. To install the Java Agent in silent mode: 1. or modify the application server JVM configuration parameters. by default <Agent_Home>/wily. For the PowerPacks you choose to install. ■ The location of a "pickup folder". copy the selected PowerPack files from the <Agent_Home>/wily/examples folder to the <Agent_Home>/wily/ext folder.txt file. The console installer does not stop or start the application server. The installer then provides a fully qualified path to the Introscope_Agent_Installation_README. If you want to install the PowerPacks at a later time.txt file in any directory. If you choose not to install PowerPacks. where applicable generates a "Next Steps" readme file 36 Java Agent Guide . Any . located in the same directory as the executable agent installer. The silent installer performs these tasks: ■ ■ ■ ■ ■ places Java Agent files on the filesystem edits the IntroscopeAgent. The console displays the selections you made during installation and asks for confirmation. if necessary copies certain . Installing the Java Agent in silent mode The Java Agent can be installed in silent mode. the next steps that must be performed manually in order to complete the installation. which contains: ■ ■ the specific steps the console install took to install the Java Agent. Place the SampleResponseFile.jar. the files are stored in the <Agent_Home>/wily/ext folder as well as the <Agent_Home>/wily/examples folder.Agent.zip or . Open the SampleResponseFile. the files for all the PowerPacks are stored in the <Agent_Home>/wily/examples folder.Agent. 3. Installing the Java Agent The silent installer does not stop or start the application server. Sun. This must be a comma-delimited list. On all platforms. the path must end with a file separator. CA Technologies recommends you do not use this installer to overwrite an existing Java Agent installation. ■ appServerHome= You can also specify the home directory of the application server to monitor. Valid values are Agent and Documentation. CA Technologies recommends selecting the application server's root directory. uncomment and set the property. By default.30\\ D:\\bea\\weblogic900\\ On UNIX: /root/bea/weblogic900/ Chapter 2: Installing and Configuring the Java Agent 37 . To use it. no installation is performed. Open the SampleResponseFile.jar files into the application server directories if necessary. Application server-specific ProbeBuilder Directives (PBDs) are installed with the Java Agent. on Windows: C:\\apache\\tomcat\\5. If the Documentation feature is included. JBoss. This is an optional configuration. Tomcat. On all platforms. WebLogic. backslashes must be escaped. ■ appServer=Default Specify the application server type. Set the following properties: ■ USER_INSTALL_DIR= Specify the directory where the Java Agent files are to be installed.Documentation Specify the agent features to install. Valid values are Default.Agent. Oracle. On Windows. To install the Java Agent using the installer in silent mode: 1. if the silent installer detects a pre-existing Java Agent in the specified install directory. backslashes must be escaped. or modify the application server JVM configuration parameters. the file path must end with a file separator. or Interstage.0. WebSphere. which are case-sensitive. 2. For example: ■ ■ On Windows: C:\\myAppServerHome\\ On UNIX: /myAppServerHome/ ■ silentInstallChosenFeatures=Agent. basic documentation is installed into the <Agent_Home>\wily directory.txt. Important: The silent installer does not perform upgrades. On Windows. The installer uses this information to copy certain . For example. These tasks need to be performed manually. Case-sensitive valid values are: ■ ■ ■ JVM AutoProbe Application Server AutoProbe Manual ProbeBuilding CA Technologies recommends using JVM AutoProbe. Spaces and empty values are allowed. ■ ■ agentName=Default Agent processName=Default Process Specify the agent and process names.5. See the AutoProbe and ProbeBuilding Options (see page 61) for more information. backslashes in the path must be escaped.0_06\\bin\\java. and generates a connector jar if necessary. The silent installer uses this information to check the JVM vendor and version. ■ ■ emHost=localhost emPort=5001 Specify the hostname and port of the Introscope Enterprise Manager to which this agent will connect. The Full setting achieves more detailed reporting and is recommended for test environments. Some sample values for this property are: ■ ■ On Windows: C:\\Program Files\\Java\\jre1. and is recommended for production environments.exe On UNIX: /usr/bin/java ■ instrumentationLevel=Typical Specify the level of instrumentation to use. 38 Java Agent Guide . which are case-sensitive. ■ instrumentationType=JVM AutoProbe Specify the ProbeBuilding method that is used to instrument the application. The Typical setting provides less detail with reduced overhead. Valid values are Full or Typical. On Windows.Installing the Java Agent ■ appServerJavaExecutable= You can also specify the Java executable used to launch the monitored application server. txt file will be ignored. You can enable ChangeDetector later by editing the agent profile. If you specify false. Some sample values for this property are: ■ ■ On Windows: C:\\customAgentProfiles\\CustomIntroscopeAgent. If you specify an alternate file. the path must end with a file separator. You can specify true or false. On Windows. If you have enabled ChangeDetector.tar files present in the pickup folder will be extracted into the agent directory at install time. For example: changeDetectorAgentID=JBossChangeDetector ■ SOA Agent extensions Specify which SOA Performance Management and SOA extensions you want to enable during installation by changing the appropriate property value to true.Installing the Java Agent ■ #alternateAgentProfile= You can choose to use a custom agent profile. For example: ■ ■ On Windows: C:\\pickupFolderContainingAddOns\\ On UNIX: /home/iscadmin/customAgentProfiles/pickupFolderContainingAddOns/ ■ changeDetectorEnable=false Specify whether to enable the ChangeDetector agent extension during installation. On all platforms. except for the instrumentationType property. the files are installed in the <Agent_Home>/wily/examples directory. you should also uncomment and specify the ChangeDetector agent ID. shouldEnableSPM=false shouldEnableSOAExtForOSB=false shouldEnableSOAExtForWPS=false shouldEnableSOAExtForWESB=false Chapter 2: Installing and Configuring the Java Agent 39 . backslashes must be escaped. Any . it will be used instead of the default agent profile.profile On UNIX: /home/iscadmin/customAgentProfiles/CustomIntroscopeAgent. On Windows. and all of the properties in the "Agent Settings" section of the SampleResponseFile. ChangeDetector files are installed but are not enabled. backslashes must be escaped.Agent.profile ■ #pickupFolder= You can also specify the absolute path to a "pickup folder". If you choose not to enable any SOA extensions. The pickup folder provides a convenient way of installing extensions or add-ons alongside the base agent. you must copy the files to the <Agent_Home>/wily/ext directory and modify the agent profile to enable the files. Uncomment and specify the absolute path to a custom agent profile.zip or . To enable them later. For the PowerPacks you choose to install. 4. referred to in this guide as the <Agent_Home>. 2. For a list of installer archives.jar <aabsolute_path_to_response_file> Manual installation Extract the Java Agent installer archive into a Java a directory of your choice.txt.Installing the Java Agent ■ PowerPacks Specify the PowerPacks you want to enable during this installation by changing the property to true. you must use the tar -xvf command to extract the . copy the selected PowerPack files from the <Agent_Home>/wily/examples folder to the <Agent_Home>/wily/ext folder. see Java Agent installer archives (see page 41).jar install -f <absolute_path_to_response_file> installer.tar file. shouldEnablePowerPackForWebLogic=false shouldEnablePowerPackForWebSphere=false shouldEnablePowerPackForSiteMinder=false 3. To manually install the Java Agent: 1. If you are installing the Java Agent on a UNIX system. the files are stored in the <Agent_Home>/wily/ext directory as well as the <Agent_Home>/wily/examples directory. and enter it at the command line to invoke the installer: ■ ■ ■ ■ installer.exe -f <absolute_path_to_response_file> installer. see Java Agent installer archives (see page 41). If you want to install additional PowerPacks at a later time. For a list of Java Agent installer archives. For information about the directory structure of the agent installation. Do not use unzip.sh IntroscopeAgent9. If you choose not to install PowerPacks.bin -f <absolute_path_to_response_file> java -classpath installer. see Java Agent installation directories and files (see page 43). Select an installer archive for your specific JVM. Extract the files of the installer archive into a location your JVM can access. 40 Java Agent Guide .0os400. Select the appropriate command format from the list below. The Java Agent requires 35 MB of free disk space to be installed. the files for all the PowerPacks are stored in the <Agent_Home>/wily/examples directory.Agent. Save the SampleResponseFile. windows. see AutoProbe and ProbeBuilding Options (see page 61). The following Java Agent installer archives are available for different application servers and operating systems.zOS. including which PBDs to use during the ProbeBuilding process.unix. HP-UX. This file governs the Java Agent’s operating and data collection behaviors. Configure the JVM to use a supported method of ProbeBuilding.profile are covered in the rest of this guide.zip Oracle 10g IntroscopeAgentFilesOnly-NoInstaller<version>oracleas.tar IntroscopeAgentFilesOnly-NoInstaller<version>websphere.unix. 4.zip SAP NetWeaver For SAP support on Windows: IntroscopeForSAPNetWeaverConversionKit<version>. WebLogic IntroscopeAgentFilesOnly-NoInstaller<version>weblogic. For more information. AIX.zip IntroscopeAgentFilesOnly-NoInstaller<version>websphere. See Connecting to the Enterprise Manager (see page 48) to get started.tar IntroscopeAgentFilesOnly-NoInstaller<version>sun.tar Chapter 2: Installing and Configuring the Java Agent 41 . 5.tar IntroscopeAgentFilesOnly-NoInstaller<version>oracleas.profile to your specific environmental needs.windows.tar IntroscopeAgentFilesOnly-NoInstaller<version>weblogic.zip IntroscopeAgentFilesOnly-NoInstaller<version>weblogic.windows. and the connection to the Enterprise Manager.os400.unix. Configure the properties in IntroscopeAgent.tar WebSphere IntroscopeAgentFilesOnly-NoInstaller<version>websphere.zip For Solaris. Java Agent installer archives Java Agent installer archives contain all files that would have been installed on your system had you run the agent installer.windows. optional ProbeBuilding behaviors.unix. Restart your application. Additional configuration options for the IntroscopeAgent.zip Sun IntroscopeAgentFilesOnly-NoInstaller<version>sun. and Linux: IntroscopeForSAPNetWeaverConversionKit<version>. CA Technologies provides these archives to expidite deployment of the Java Agent during manual installation.Installing the Java Agent 3.zOS.zip IntroscopeAgentFilesOnly-NoInstaller<version>weblogic.unix. You will need to know the location of the files extracted in step 2.windows.tar IntroscopeAgentFilesOnly-NoInstaller<version>websphere.os400. tar IntroscopeAgentFilesOnly-NoInstaller<version>default.tar IntroscopeAgentFilesOnly-NoInstaller<version>allappserver.zip IntroscopeAgentFilesOnly-NoInstaller<version>allappserver.tar IntroscopeAgentFilesOnly-NoInstaller<version>default.n.tar In the file names.unix.zip JBoss IntroscopeAgentFilesOnly-NoInstaller<version>jboss.windows.unix. the Java Agent archive file name is: IntroscopeAgentFiles-NoInstaller9.0.zOS.windows.unix.os400.0weblogic.windows.zip IntroscopeAgentFilesOnly-NoInstaller<version>default. For example.zip IntroscopeAgentFilesOnly-NoInstaller<version>allappserver.zip Default IntroscopeAgentFilesOnly-NoInstaller<version>default. <version> indicates the release number of the Java Agent in the format of n.unix.unix.os400.zip All application servers The files contained in these archives have all files for all application servers supported by the Java Agent: IntroscopeAgentFilesOnly-NoInstaller<version>allappserver.unix.zOS.tar 42 Java Agent Guide .0.tar IntroscopeAgentFilesOnly-NoInstaller<version>jboss.windows.tar IntroscopeAgentFiles-NoInstaller<version>tomcat.windows.zip Fujitsu Interstage IntroscopeAgentFilesOnly-NoInstaller<version>interstage. if you want to install the files for the 9.tar IntroscopeAgentFilesOnly-NoInstaller<version>interstage.n.Installing the Java Agent Apache Tomcat IntroscopeAgentFilesOnly-NoInstaller<version>tomcat.n.0 Java Agent for monitoring WebLogic applications on a UNIX server. See the documentation for the specific extension or PowerPack for more information. which vary depending on the application server your agent installation supports. a corresponding agent profile is present in this directory.jar—The Java Agent executable . Java Agent operating and data collection behaviors are controlled by configuration properties stored in the agent profile and the PBDs it references. see ProbeBuilder Directives (see page 56). For more information. The agent profile contains properties that control the behavior of the agent and AutoProbe. PBD files used for extensions and PowerPacks are also placed in this directory.jar—Contains startup classes that you can configure to allow the Java Agent to obtain management information from an application server. as well as application server-specific PBDs.profile location (see page 238). You can also change the location of the agent profile. WebAppSupport. see Default PBD files (see page 111) and Default PBL files (see page 114). IntroscopeAgent.jar file. For more information about PBDs.profile files—For the JVM you indicated during agent installation. the default values for certain properties vary. the install and UninstallerData directories are not present. depending on the application server your agent installation supports. ■ ■ ChangeDetector-config. Contents of the wily directory The wily directory contains: ■ ■ ■ Agent. For more information on the standard PBDs and PBLs. ProbeBuilder Directives (PBDs)—Contains the standard ProbeBuilder Directives (PBDs) and ProbeBuilder Lists (PBLs) provided with the Java Agent.xml—The configuration file for ChangeDetector. Chapter 2: Installing and Configuring the Java Agent 43 .Java Agent installation directories and files Java Agent installation directories and files Installing a Java Agent creates the following directory structure: wily\ connectors deploy examples ext hotdeploy install readme tools UninstallerData version Note: If you manually install the Java Agent. Defaults are supplied for many properties. see Configuring the IntroscopeAgent. jar—Used in configuring JVM AutoProbe in supported environments. See the Introscope Extension for CA SYSVIEW Guide for information on how to enable and configure this extension.Java Agent installation directories and files Contents of the wily\connectors directory The wily\connectors directory contains: ■ CreateAutoProbeConnector. Sample files are placed in the <Agent_Home>/wily/examples directory.jar—Contains business definition monitoring and provides support for the application triage map in the Introscope Workstation Investigator. Contents of the wily\deploy directory If you install the Java Agent on JBoss. See the documentation for the specific extension or PowerPack for more information on where specific files should be placed and how to configure the extension. BizDef. you can manually enable the extensions using the files in this directory. the wily\deploy directory is also installed. BizTrxHttp.jar—Contains business definition monitoring and provides support for the application triage map in the Introscope Workstation Investigator.jar—Contains application triage map tracer and NameFormatter extensions. SOA. 44 Java Agent Guide .xml—Web application support for JBoss. This directory contains: ■ introscope-jboss-service. or SYSVIEW. If you did not enable an extension or PowerPack at installation. Contents of the wily\examples directory The wily\examples directory contains sample configuration files for agent extensions. such as PowerPacks. specifically JMX metrics. SYSVIEW is disabled by default. SYSVIEW files Files for the CA Technologies extension for CA SYSVIEW are installed by default when you run the Java Agent installer in any mode. Contents of the wily\ext directory The wily\ext directory contains: ■ The following files support the functioning of business definition monitoring and the application triage map: ■ ■ ■ AppMap. jar—Used in Java 1.jar SignedJARDirectiveLoader. Java15DynamicInstrumentation. ProbeBuilder.jar—Contains the ChangeDetector executable. SQLAgent.jar—Contains Dynamic Instrumentation support for Java 1.jar—Contains platform monitors for Windows only.jar—Used in environments that integrate CA Wily Customer Experience Manager (CEM) with the Java Agent. ServletHeaderDecorator.jar—Used in Java 1.jar—Used in environments that integrate CA Wily CEM with the Introscope agent.Java Agent installation directories and files ■ ■ CEMTracer. which allows you to implement new and changed PBDs without restarting the managed application or the agent.jar—Contains the SQL Agent executable.jar—Contains the SPM Agent extension. The following JARs aid in ChangeDetector functionality: ■ ■ ChangeDetector-Agent_Server. introscopeWindowsIntelAmd64Stats. ChangeDetectorAgent. Inheritance.jar—Contains the LeakHunter executable. Supportability-Agent.jar—Contains platform monitors for Windows only.5.jar—Supportability extensions for use by CA Supportt in agent support.jar UnifiedDirectiveLoader. SMWebAgentExt. LeakHunter. introscopeWindowsIntelAmd32Stats. DynInstrSupport15.jar—Contains the ProbeBuilder executable.5 environments to enable dynamic instrumentation.jar ChangeDetector-CommonAll.jar—Contains the SQL Agent SQL normalizer extension.jar ■ ■ ■ ■ ■ RegexNormalizerExtension. One of the following extensions to ProbeBuilder.jar—Contains dynamic instrumentation for bootstrap class support. Chapter 2: Installing and Configuring the Java Agent 45 .5 environments to enable AutoProbe to instrument multiple levels of subclasses of a probed class.jar is also included: ■ ■ ■ ■ ■ BasicDirectiveLoader.jar ■ ■ ■ ■ ■ ■ DynInstrBootstrap. Note: Any ProbeBuilder Lists (PBLs) placed in the hotdeploy directory are ignored by the Java Agent. For more information about creating custom PBDs.autoprobe.profile. see ProbeBuilder Directives (see page 56) and Creating custom tracers. Open the IntroscopeAgent.directivesFile property. For more information about dynamic ProbeBuilding. you can decide not to use the hotdeploy directory. without editing the IntroscopeAgent.custom3. Add the PBDs you want to use to the introscope. Invalid PBDs cause AutoProbe to shut off and PBDs that collect too many metrics can affect application performance. without restarting applications. 2.profile and restart the agent.custom2.autoprobe.directivesFile property.directivesFile=default-typical.pbd. To address this. Save the IntroscopeAgent.pbd 5. For example: introscope. 46 Java Agent Guide . see Dynamic ProbeBuilding (see page 68). Move any of the custom PBDs stored in the hotdeploy directory to the main <Agent_Home>/wily directory. and. 4. Remove hotdeploy from the introscope. If your custom PBDs contain invalid syntax. potentially. To unconfigure the hotdeploy directory: 1.profile.custom1. or are configured to collect too many metrics. Placing directives in this directory heightens the need for caution.p bd. 3. Alterturnatively. ensuring that your server environment's change control process is updated to reflect the new option for deploying PBDs. the impact will be felt more quickly. CA Technologies recommends: ■ ■ testing and validating all directives in QA and performance environments before pushing them out to production environments.pbl.Java Agent installation directories and files Contents of the wily\hotdeploy directory The hotdeploy directory allows Introscope administrators to deploy new directives more quickly and easily.autoprobe. based on the decisions you made during the automatic installation.responsefile. Contents of the wily\UninstallerData directory The wily\UninstallerData directory contains: ■ Uninstall Introscope Agent . The readme directory contains readme information for any extensions you enabled at installation.<date_and_time_stamp>—an automatically generated response file that reflects the settings you chose during installation. see Running the URLGrouper (see page 201).exe—Use this file to uninstall the Java Agent on Windows systems.txt—Sample silent response file ■ ■ ■ Contents of the wily\tools directory The wily\tools directory contains: ■ URLGrouper.txt—details the next steps you should take after installing the Java Agent.Java Agent installation directories and files Contents of the wily\install directory The wily\install directory contains: ■ autogenerated. The version directory contains version information for any extensions you enabled at installation.log—if you installed the Java Agent using the agent installer. a command-line utility that analyzes web server log files. Chapter 2: Installing and Configuring the Java Agent 47 . Contents of the wily\readme and wily\versions directories Depending on what you chose to enable at installation. this log details the actions taken by the automatic installer. two other directories may be present in your file structure. For more information about the URLGrouper. Introscope_Agent_<version>_InstallLog. SampleResponseFile.Agent. IntroscopeAgentInstallation_README.jar—Contains the URLGrouper. This file can be used to replicate the installation on other systems. Configuring the JVM to use the Java Agent Configuring the JVM to use the Java Agent You must change the configuration of the JVM you are instrumenting to locate the Java Agent code and configurations. CA Technologies recommends using the JVM AutoProbe command line parameter –javaagent with a value of <PathToAgentJar>. It is recommended that <PathToAgentJar> be specified as an absolute path to the Introscope agent.jar file, though a relative path from the directory which was the ‘current’ directory when JVM started may also be used. For more information, see AutoProbe and ProbeBuilding Options (see page 61) for JVM AutoProbe configuration requirements for WebSphere on z/OS and OS/400, and specific application server environments such as WebSphere 6.1 running under IBM JVM 1.5 on any platform. To specify which agent configuration to use, CA Technologies recommends using the Java system property com.wily.introscope.agentProfile with JVM command line option -Dcom.wily.introscope.agentProfile=<PathToAgentProfile>. It is recommended that <PathToAgentProfile> be specified as an absolute path, though a relative path from the directory which was the "current" directory when JVM started may also be used. If the property com.wily.introscope.agentProfile is not defined, the agent will attempt to locate the configuration file named IntroscopeAgent.profile in the directory the agent.jar file resides in. Starting the Java Agent To collect data about your applications, the Java Agent must be included in the application server's startup configuration. You must then restart the application server to start the Java Agent and instrument the classes discovered. To report the collected data, the Java Agent must be connected to the Enterprise Manager. For more information about connecting to the Enterprise Manager, see Connecting to the Enterprise Manager (see page 48). Connecting to the Enterprise Manager To report metrics, the Java Agent must connect to an Enterprise Manager. You configure how the agent connects to the Enterprise Manager by changing properties in the IntroscopeAgent.profile, located in the <Agent_Home>/wily directory. CA Technologies recommends putting the Enterprise Manager on a system separate from the agent systems. For more information about sizing and performance recommendations, see the CA Wily APM Sizing and Performance Guide. 48 Java Agent Guide Connecting to the Enterprise Manager The default communications settings in the IntroscopeAgent.profile enable an agent to connect to an Enterprise Manager located on the same system as the agent. To comply with the recommended deployment (different systems), you must modify the IntroscopeAgent.profile to connect the agent to a remote Enterprise Manager. To configure Java Agent connection to the Enterprise Manager: 1. 2. Open the IntroscopeAgent.profile. Modify the following properties to specify the location of your remote Enterprise Manager: ■ introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT Defines the host name or IP address of the target Enterprise Manager. ■ introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT Defines the Enterprise Manager listening port, which should be the same port specified in the Enterprise Manager property introscope.enterprisemanager.port.DEFAULT. By default, this port is 5001. Note: To change Enterprise Manager properties, open the IntroscopeEnterpriseManager.properties file on the Enterprise Manager machine, located in the <EM_Home>/config directory and modify the desired properties. Save the file for your changes to be implemented. ■ introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT Defines the socket factory used for connections to the Enterprise Manager. The default value of this property is com.wily.isengard.postofficehub.link.net.DefaultSocketFactory , for plain socket communication. 3. Save the IntroscopeAgent.profile and start (or restart) the Java Agent. For more information about connection properties, see Agent to Enterprise Manager connection (see page 258). You can also configure alternate Enterprise Managers for the Java Agent to connect to, should the connection to the primary Enterprise Manager be lost. For more information on how to configure these Enterprise Managers, see Configuring Java Agent Failover (see page 173). Connecting to the Enterprise Manager with HTTP tunneling You can configure agents to communicate with an Enterprise Manager over HTTP. This allows communication to pass through firewalls that only permit HTTP traffic. Chapter 2: Installing and Configuring the Java Agent 49 Connecting to the Enterprise Manager CA Technologies does not recommend configuring agents to tunnel over HTTP if a direct socket connection to the Enterprise Manager is feasible. Tunneling imposes additional CPU and memory overhead on the managed host and Enterprise Manager beyond that expected for a direct socket connection. Important: HTTP/1.1 is required to enable agent HTTP tunneling. To configure HTTP tunneling: 1. 2. Open the IntroscopeAgent.profile. Configure the agent to connect to the HTTP listening port of the Enterprise Manager’s embedded web server, using an HTTP tunneling socket factory. Use these properties to specify the agent tunneling connection: ■ introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT Defines the host name or IP address of the target Enterprise Manager. ■ introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT Defines the HTTP listening port of the Enterprise Manager's embedded web server, which is usually specified in the Enterprise Manager property introscope.enterprisemanager.webserver.port. By default, this port is 8081. Note: To change Enterprise Manager properties, open the IntroscopeEnterpriseManager.properties file on the Enterprise Manager machine, located in the <EM_Home>/config directory and modify the desired properties. Save the file for your changes to be implemented. ■ introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT Set the value to com.wily.isengard.postofficehub.link.net.HttpTunnelingSocketFactory . 3. Save the IntroscopeAgent.profile. Configuring a proxy server for HTTP tunneling You can configure the HTTP tunneled agent to connect through a proxy server to the Enterprise Manager. This is necessary for a forward-proxy server configuration where the agent is running behind a firewall that only allows outbound HTTP traffic routed through the proxy server. These proxy server configuration properties apply only if the agent is configured to tunnel over HTTP. The proxy server configuration applies to any configured HTTP tunneled connection on the agent, not to a single connection. This is especially important to consider when configuring failover between multiple Enterprise Managers, where the connection to each Enterprise Manager is over HTTP. Important: HTTP/1.1 is required to enable agent HTTP tunneling. If you are using HTTP tunneling, your proxy server must support HTTP Post. 50 Java Agent Guide Connecting to the Enterprise Manager To configure a proxy server for HTTP tunneling: 1. 2. Open the IntroscopeAgent.profile. Specify the proxy server properties: introscope.agent.enterprisemanager.transport.http.proxy.host (see page 241) introscope.agent.enterprisemanager.transport.http.proxy.port (see page 242) 3. If the proxy server requires the agent to authenticate with it, set these properties: introscope.agent.enterprisemanager.transport.http.proxy.username (see page 242) introscope.agent.enterprisemanager.transport.http.proxy.password (see page 242) 4. Save the IntroscopeAgent.profile. Connecting to the Enterprise Manager with HTTPS tunneling The agent can connect to the Enterprise Manager using HTTP over Secure Sockets Layer (SSL) by configuring properties in the IntroscopeAgent.profile. To configure a connection through HTTPS: 1. 2. Open the IntroscopeAgent.profile. Configure the agent to connect to the HTTPS listening port of the Enterprise Manager’s embedded web server, using an HTTP tunneling socket factory. ■ introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT Defines the host name or IP address of the target Enterprise Manager. ■ introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT Defines the HTTPS listening port of the Enterprise Manager's embedded web server. For example: introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT=8444 ■ introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT Set the value to the socket factory. For example: introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT=co m.wily.isengard.postofficehub.link.net.HttpsTunnelingSocketFactory 3. Save the IntroscopeAgent.profile. Chapter 2: Installing and Configuring the Java Agent 51 Connecting to the Enterprise Manager Connecting to the Enterprise Manager over SSL The agent can also connect to the Enterprise Manager using just SSL. To configure connection through SSL: 1. 2. Open the IntroscopeAgent.profile. Configure the agent to connect to the Enterprise Manager’s SSL listening port using an SSL socket factory. ■ introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT Defines the host name or IP address of the target Enterprise Manager. ■ introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT Defines the Enterprise Manager's SSL listening port. ■ introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT Defines the SSL socket factory. Set the value to: com.wily.isengard.postofficehub.link.net.SSLSocketFactory 3. If the agent needs to authenticate the Enterprise Manager, uncomment and set the truststore property to the location of a truststore containing the Enterprise Manager’s certificate. ■ introscope.agent.enterprisemanager.transport.tcp.truststore.DEFAULT Set to either an absolute path or a path relative to the agent's working directory. On Windows, backslashes must be escaped. For example: C:\\my_truststore. ■ introscope.agent.enterprisemanager.transport.tcp.trustpassword.DEFAULT The truststore password. Uncomment and set only if needed. If no truststore is specified, the agent by default trusts all certificates. 52 Java Agent Guide Java Agent configuration overview 4. If the Enterprise Manager requires client authentication, the agent must be configured with a keystore. Set the keystore property to the location of a keystore containing the agent's certificate: ■ introscope.agent.enterprisemanager.transport.tcp.keystore.DEFAULT Set to either an absolute path or a path relative to the agent's working directory. On Windows, backslashes must be escaped. For example: C:\\keystore. ■ introscope.agent.enterprisemanager.transport.tcp.keypassword.DEFAULT The keystore password. Uncomment and set only if needed. By default no keystore is specified. ■ introscope.agent.enterprisemanager.transport.tcp.ciphersuites.DEFAULT To restrict the enabled cipher suites, set this property to a comma-separated list of cipher suites. If not specified, the default enabled cipher suites are used. 5. Save the IntroscopeAgent.profile. Java Agent configuration overview After you install the Java Agent, you can configure it to collect as many or as few metrics as you want. The Java Agent is a highly configurable tool, able to monitor many different aspects of your application and environment health. There are three overall sets of configurations to perform on the Java Agent: ■ ■ Operational configurations are required for the Java Agent to report data at a basic level. See Operational configurations (see page 53). Optional operational configurations augment the operations of the Java Agent, but are not required for the agent to run at a basic level. See Optional operational configurations (see page 54). Data collection configurations enable the Java Agent to collect additional metrics not collected by default using the out-of-the-box ProbeBuilder Directive (PBD) and ProbeBuilder List (PBL) file settings. See Data collection configurations (see page 55). ■ Operational configurations For you to be able to see and respond to metric information, the Java Agent must be able to communicate with the Enterprise Manager, the applications you are monitoring must be instrumented, and to aid in verifying your configuration, you must configure the logging options for the agent. Chapter 2: Installing and Configuring the Java Agent 53 Java Agent configuration overview Communicating with the Enterprise Manager Without a connection to the Enterprise Manager, the Java Agent cannot report metrics. By default, the agent will attempt to connect to an Enterprise Manager on localhost port 5001. You can change this port designation, configure the Java Agent to connect to a cluster of Enterprise Managers, or enable the agent to failover to a secondary Enterprise Manager by configuring properties in the IntroscopeAgent.profile file. For more information, see Connecting to the Enterprise Manager (see page 48). Instrumenting applications to be monitored The Java Agent uses a mechanism called JVM AutoProbe (AutoProbe) to insert probes into the bytecode of the applications you want to monitor. AutoProbe uses PBD and PBL files to determine which probes are inserted. After the probes are inserted, the application is considered instrumented, allowing metric data to be collected. You can use the default PBD and PBL files included with the Java Agent to provide a basic level of metric collection. You can also modify these default files to better tune metric collection for your environment. For more information on how to tailor PBDs and PBL files to your specific needs, see ProbeBuilder Directives (see page 56). Note that it is the settings in the PBDs and PBL files that define what to monitor in your applications and environment, and how you configure these files determines what gets instrumented in your applications but not how they are instrumented. The most common way to instrument applications is using JVM AutoProbe, but there are other methods you can use to instrument applications. For most applications and environments, CA Technologies recommends using JVM AutoProbe. For more information about other ways to instrument applications, see AutoProbe and ProbeBuilding Options (see page 61). Setting monitoring and logging options You can configure the Java Agent to monitor its own interactions with your environment. This makes it easier to tune the agent for optimal performance as well as troubleshoot any issues you may encounter when configuring the agent. By default, the Java Agent writes information log messages to log files. For more information, see Configuring logging options (see page 162). Optional operational configurations There are also optional Java Agent configurations you may want to set. 54 Java Agent Guide agent. PBD files contain properties that. you can define the agent name and process name using these properties in IntroscopeAgent.agentName—Name of the application server that the Java Agent is monitoring. see Java Agent Naming (see page 147). see Java Agent Naming (see page 147).customProcessName—Name of the process being monitored. See introscope. it is part of the SuperDomain by default.agent. Data collection configurations Data collection is controlled by the ProbeBuilder Directive (PBD) and ProbeBuilder List (PBL) files.profile. By default. If desired. and cannot contain a percent (%) character. and autonaming capabilities. For more information. Domains Unless you assign a Java Agent to a custom Introscope Domain. introscope. you must configure those agents as Virtual Agents which allow you to aggregate metrics at the application level. which appear as nodes in the Workstation Investigator hierarchy of metrics reported by the Java Agent. PBLs only contain lists of multiple PBDs to be implemented by the Java Agent.Java Agent configuration overview Java Agent naming The Java Agent profile provides default values for the agent name and Custom Process name. when configured.The agentName value must start with an alphabetical character. ■ introscope. For information about Domains and their use in configuring user permission. the Java Agent profile explicitly assigns an agent name. you may wish to configure the Java Agent to obtain a name automatically.customProcessName (see page 254) for a description.agent. Chapter 2: Installing and Configuring the Java Agent 55 . Depending on your environment. for instance "WebLogic Agent". see Using Virtual Agents to Aggregate Metrics (see page 169). see the Introscope Installation and Upgrade Guide. See introscope. ■ You can define a Java Agent’s name explicitly or configure an automated mechanism for agent naming. Virtual Agents If you want multiple agents to monitor separate instances of a clustered application. For more information. determine what metrics are gathered by the Java Agent and reported to the Enterprise Manager.agentName (see page 253) for a description.agent. For more information about agent naming. The following are the different types of metrics you can gather from your applications and environments. and stores them in the Transaction Event Database.profile file.Java Agent configuration overview To expand the data collection of your Java Agent. you will configure one or more of the following: ■ ■ ProbeBuilder Directives (PBDs) (see page 56) Data collection and reporting options (see page 56) ProbeBuilder Directives (PBDs) The ProbeBuilder Directives (PBDs) used during the ProbeBuilding process determine the metrics that the agent reports. see Enabling JMX Reporting (see page 221) and Configuring WebLogic Diagnostic Framework. URL Groups for Blame Reporting—You can configure URL groups to control the the way that metrics for front-ends are aggregated and presented in the Investigator in WebView and the Workstation. The default list specified in the profile results in the typical level of monitoring. To use URL groups. or tailor the stall reporting behavior. however. (see page 82) ■ ■ ■ 56 Java Agent Guide . For more information. Data collection and reporting options Deciding how you are going to configure your Java Agent to monitor your applications and environments is an important process. the Java Agent collects socket and SSL metrics. For more information. see Using URL groups (see page 196). most of which are configured using the IntroscopeAgent. but does not report input and output bandwidth rate metrics for individual sockets. appropriate for production environments where overhead is at a premium. You can disable this behavior. You can generally configure more detailed probe building to obtain more metrics in development or QA environments in the agent profile. the Java Agent reports stalls as events. see ProbeBuilder Directives (see page 56). For more information. JSR-77 metrics. For more information. You can then configure a list of the desired PBDs or PBLs (lists of PBDs) in the agent profile. For more information. you must manually configure them using properties in the Java Agent profile. JMX and JSR-77—You can optionally configure the Java Agent to report JMX metrics. or to instrument custom classes and custom or private methods that the default PBDs do not specify. see Disabling the capture of stalls as Events (see page 208). or WebLogic Diagnostic Framework metrics. You can further control the ProbeBuilding process by customizing PBDs to skip classes or packages. You can configure each PBD to monitor different aspects of your application. see Socket metrics (see page 158). ■ Socket and SSL Metrics—By default. Stall Event Reporting—By default. one package for each of the following operating system platforms. SQL Agent—Introscope SQL Agent is installed automatically with the agent installation. with 3. to the Enterprise Manager. including CPU statistics.000 agents on WebLogic. Chapter 2: Installing and Configuring the Java Agent 57 . See the Wily CEM Integration Guide for more information about integrating your Java Agent with CA Wily CEM. Platform Monitoring—Platform monitors enable the agent to report system metrics. see Configuring WebSphere PMI (see page 96). you can configure the reporting of WebSphere Performance Monitoring Infrastructure (PMI) metrics. an environment might have 8. For example. and to actually perform the upgrade of all agents to a new version. Platform monitors on all operating systems except Windows Server 2003 and AIX are automatically enabled upon agent installation.Upgrading multiple agent types ■ Transaction Tracing Behavior—You can tailor the behavior of the automatic transaction tracing the agent performs. see Configuring Transaction Trace Options (see page 203). For more information. For more information. see Configuring the Introscope SQL Agent (see page 209). It can become quite a burden to understand the environmental needs for upgrading agents (which agents where need to be upgraded?).000 on JBoss. Windows Server 2003 and AIX platform monitors require a minimal configuration to work. Upgrading multiple agent types Some environments have thousands of agents distributed across many different application servers.000 on WebSphere. see Configuring Platform Monitoring (see page 229). For more information. the Introscope Java Agent release includes superset agent packages.000 agents. For more information. and configure the collection of User IDs for Servlet and JSP invocations. To ease this burden. This agent extension provides visibility into the performance of individual SQL statements. and 3. PMI—In WebSphere environments. ■ ■ ■ CA Wily CEM integration There are several steps you are required to perform to ensure that the Java Agent integrates with a CA Wily CEM installation. 2. ■ ■ ■ ■ IntroscopeAgentFiles-NoInstaller<version>allappserver. For example: IntroscopeAgent.windows. if you want to use the superset agent package for the Java Agent 9.0.jars and platform monitors suitable for the operating system type To upgrade multiple agent types using the superset agent packages: Important: This upgrade method is not supported for SAP NetWeaver at this time. select the appropriate IntroscopeAgent.<application_server_name>.profile The default IntroscopeAgent.profile.5. with the application server name embedded in the file name. For more information.zOS. Transfer these properties to your existing IntroscopeAgent. For example.websphere.unix. Note: If you have already configured an IntroscopeAgent. open the corresponding IntroscopeAgent. see Manual installation (see page 40).zip Important: The superset packages do not include any files for SAP NetWeaver at this time.Upgrading multiple agent types Note: In the following list of file names. Each package contains: ■ ■ All application server-specific PBDs and PBLs All application server agent profiles. 58 Java Agent Guide .os400. If you have not already configured an IntroscopeAgent.0.weblogic.profile.zip IntroscopeAgentFiles-NoInstaller<version>allappserver.tar IntroscopeAgentFiles-NoInstaller<version>allappserver.profile has not been included.profile file in an editor and look for new properties you may want to use. rename it to IntroscopeAgent.0.profile. <version> refers to the current release number of the Java Agent. the <version> string would appear in this format: 9. Extract the selected agent package into the application server’ s home directory.5. Follow the manual installation instructions for Java Agent installation. and configure the file for use with your environment. 1.profile IntroscopeAgent. 2. 3. See step 3 for more information.profile. Note: The extra PBDs and PBLs in the <Agent_Home>/wily directory that refer to other application servers can be safely ignored.tar IntroscopeAgentFiles-NoInstaller<version>allappserver.<application_server_name>.profile. ■ All agent . Select a superset package appropriate for the target operating system. it is important to keep the UninstallerData folder intact. Note: Only run the uninstaller when monitored JVMs are shut down. the uninstaller can be used to remove installed files. These include: ■ ■ ■ -Xbootclasspath -javaagent any other Wily-specific arguments. Important: Only remove files after shutting down the monitored JVM.agentProfile=xxxxx 3.Uninstalling the Java Agent Uninstalling the Java Agent Uninstalling the Java Agent requires you to know where the Java Agent was installed for each application being monitored. For an active Introscope installation on z/OS. To uninstall the Java Agent from any supported JVM: 1. Uninstalling the Java Agent from z/OS The recommended way to uninstall the Java Agent from z/OS is to delete the <Agent_Home>/wily directory using an rm -rf command.wily. If you delete the UninstallerData folder. Launch the uninstaller and follow the on-screen directions. Chapter 2: Installing and Configuring the Java Agent 59 . 4. Manually delete the <Agent_Home>/wily directory. Stop the application server. This is necessary because the executable uninstaller does not run properly on z/OS due to a third party bug. you will not be able to upgrade to future versions of Introscope.introscope. for example: -Dcom. If you used the Java Agent installer to install the Java Agent. Reboot the application server. Do not delete the UninstallerData folder unless you have decided to uninstall the entire instance. 2. or run the uninstaller. Remove the Java Agent switches from the JVM command line. . ■ ■ ■ For more information about configuring JVM AutoProbe for most application server environments. Chapter 3: AutoProbe and ProbeBuilding Options 61 . with -javaagent property. After you have configured PBDs and PBLs to insert the probes for the metrics you want to collect in your applications and environment. Contact CA Support before using this method. see JVM AutoProbe (see page 62). This is an advanced instrumentation technique. The default PBD and PBL files included with the Java Agent provide a basic level of metric collection.5 or higher. use only one method of instrumentation. you will want to modify the default settings in these files to better tune metric collection specifically for your environment. use the following methods: ■ JVM AutoProbe. see JVM AutoProbe on OS/400 (see page 63). For more information. In most cases.Chapter 3: AutoProbe and ProbeBuilding Options This section contains the following topics: AutoProbe and ProbeBuilding overview (see page 61) Configuring JVM AutoProbe (see page 62) Configuring ProbeBuilding (see page 67) AutoProbe and ProbeBuilding overview The Java Agent inserts probes into the bytecode of applications you want to monitor. depends on the the application environment. ProbeBuilding is the process by which you choose which probes to insert into applications using ProbeBuilder Directives (PBDs) and ProbeBuilder Lists (PBLs). you should use JVM AutoProbe to instrument applications. In most cases. To instrument your applications on JVMs 1. see JVM AutoProbe for WAS 7 on z/OS (see page 63). Important: When instrumenting your applications.5 and higher. see Manual ProbeBuilding (see page 355). ■ Manual ProbeBuilding. however. For information about using JVM AutoProbe on z/OS platforms. CA Technologies highly recommends using JVM AutoProbe to instrument applications on JVMs 1. For information about using JVM AutoProbe on OS/400. you use these files to instrument applications automatically using JVM AutoProbe or manually using ProbeBuilder. Configuring JVM AutoProbe. 0. For more information. It is recommended that <PathToAgentJar> be specified as an absolute path to the Introscope agent. see The Java Agent and Application Server AutoProbe (see page 365).0 Java Agent.0. upgrade to WAS 7.4 (and earlier) with earlier versions of the Java Agent.0 and higher.0. You can use AutoProbe for application servers to instrument applications using JVM 1. The following JVMs require variations to the standard JVM AutoProbe configuration: ■ ■ ■ JVM AutoProbe for WAS 7 on z/OS (see page 63) JVM AutoProbe on OS/400 (see page 63) JRockit JVM AutoProbe (see page 67) JVM AutoProbe CA Technologies recommends using the JVM AutoProbe command line parameter –javaagent with a value of <PathToAgentJar>. 62 Java Agent Guide . you may see the application server process restart repeatedly. though a relative path from the directory which was the ‘current’ directory when JVM started may also be used. For this method. but CA Technologies recommends using JVM AutoProbe with the 9. Important: If you are using the Java Agent 9.0 build level 7. Configuring JVM AutoProbe Configuration of JVM AutoProbe for the majority of JVMs is the same.8 or above. on are no longer. see JVM AutoProbe (see page 62). Unsupported instrumentation methods The AutoProbe for application servers method for instrumentation is not supported for Java Agents 9.0 or later to monitor WebSphere 7.jar file.Configuring JVM AutoProbe The instructions in this section assume that you have performed the installation and configuration tasks outlined in Installing and Configuring the Java Agent (see page 27). To avoid this problem. configure JVM AutoProbe by adding these options to the JVM command line: -Xbootclasspath/a:<Agent_Home>/Agent.0 on z/OS .wily.jar -Dcom. If the property com.agentProfile=<PathToAgentProfile> . Chapter 3: AutoProbe and ProbeBuilding Options 63 .1 WebSphere Application Server 7.profile For more information on WAS 7 on z/OS.Configuring JVM AutoProbe To specify which agent configuration to use.0 build level 7. For example: -javaagent:<PathToAgentJar> -Dcom.agentProfile with JVM command line option -Dcom.6 J9 32-bit IBM JVM 1. see AutoProbe for WebSphere 6. JVM AutoProbe on OS/400 The following JVM versions are supported by the 9.0 For more information on how to configure WAS 6.profile in the directory the agent.5 J9 64-bit IBM JVM 1.introscope.agentProfile=<PathToAgentProfile> JVM AutoProbe for WAS 7 on z/OS For WAS 7 on z/OS.introscope.0.0 or later to monitor WebSphere 7.agentProfile is not defined.agentProfile=<Agent_Home>/IntroscopeAgent. To avoid this problem.wily. though a relative path from the directory which was the ‘current’ directory when JVM started may also be used.introscope.8 or above.1 and 7. upgrade to WAS 7.5 J9 32-bit IBM JVM 1.1 and WAS 7.0. see Deploying the Java Agent on WebSphere (see page 85).introscope.wily. It is recommended that <PathToAgentProfile> be specified as an absolute path. CA Technologies recommends using the Java system property com. the agent will attempt to locate the configuration file named IntroscopeAgent. you may see the application server process restart repeatedly.0 Java Agent on OS/400: ■ ■ ■ ■ IBM JVM 1.jar file resides in.introscope.0 for z/OS (see page 89). Important: If you are using the Java Agent 9.wily.jar -javaagent:<Agent_Home>/Agent.6 J9 64-bit The following application servers are supported on OS/400: ■ ■ WebSphere Application Server 6.wily. Creating an AutoProbe connector file The depreciated JVM AutoProbe method requires a connector . You may want to rename the created . The way you run the Connector depends on the application server you use. For example: ■ wily/connectors/AutoProbeConnector131_02_Sun. 2.jar 3. If your JVM is v1. For more information. see Deploying the Java Agent on WebSphere (see page 85) and Deploying the Java Agent on WebLogic (see page 77). Change the working directory to wily/connectors under the installation directory. see the appropriate section for your application server.jar -current to specify the JVM by passing the JVM directory on the command line: java -jar CreateAutoProbeConnector. see Running the AutoProbe Connector for a Sun. 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. or HP JVM After you create the AutoProbe Connector for the Sun or IBM JVM. you run the created file to instrument your applications.5. To run the AutoProbe Connector for SAP J2EE 6.properties 64 Java Agent Guide . IBM. Open the file: <drive>:\usr\sap\<J2EE_ENGINE_ID>\j2ee\j2ee_<INSTANCE>\cluster\ server\cmdline.jar Running the AutoProbe Connector for a Sun.jar file to be more manageable and universally accepted.jar file to correctly operate.jar OR ■ wily/connectors/AutoProbeConnector130_IBM.jar -jvm <directory> The output is a file with the form: wily/connectors/AutoProbeConnector. follow the instructions in JVM AutoProbe (see page 62). To create an AutoProbe Connector 1.20: 1.Configuring JVM AutoProbe WebSphere or WebLogic For information about configuring AutoProbe on WebSphere and WebLogic. This section details how to create the AutoProbe Connector. For information on how to run an AutoProbe Connector. or HP JVM (see page 64). IBM. properties Look for a line beginning with ID<server_id>.profi le Note: For NetWeaver 6. 5. Restart the SAP server.introscope.D:/u sr/sap/ccms/wily/Agent. Open the server.jar -Dcom.agentProfile=D:/usr/sap/ccms/wily/IntroscopeAgent.wily.introscope. Repeat steps 2 . 3.wily.40 on Windows.C:\usr\sap\P602\j2ee\j2ee_00\ccms\wily\Agent.jar.introscope.profile> -Dcom.wily. Log in as Administrator or Root.agentProfile=C:\usr\sap\P602\j2ee\ j2ee_00\ccms\wily\IntroscopeAgent.profile> For example: -Xbootclasspath/p:D:/usr/sap/ccms/wily/connectors/AutoProbeConnector. 2. 4.agentProfile=<path-to-IntroscopeAgent. Run the SAP J2EE Configtool. Click Disk to save. To run the AutoProbe Connector for NetWeaver 04/SAP J2EE 6.wily. To verify that Configtool changes were made. open the file: <drive>:\usr\sap\ccms\P66\JC00\j2ee\cluster\instance.PathToAgentJar -Dcom. You must be logged in with Administrator or Root permissions to add Introscope information to startup scripts for Sun ONE 7.xml file. Restart the SAP server. Add these new java parameters in the Java Parameters field: -Xbootclasspath/p:PathToAutoProbeConnectorJar.40: 1. 6.agentName=<yourAgentName> For example: -Xbootclasspath/p:C:\usr\sap\P602\j2ee\j2ee_00\ccms\wily\connectors\AutoProbe Connector. Select the server to modify.jar.PathToAgentJar -Dcom.0. and confirm that it contains the lines you entered. 8.profile 3.agent. 7. located at: <SunONE install dir>/domains/domain1/server1/config/ Chapter 3: AutoProbe and ProbeBuilding Options 65 .JavaParameters. the slashes for these java parameters must be forward slashes. Append these commands to JavaParameters section: -Xbootclasspath/p:PathToAutoProbeConnectorJar. 2.jar -Dcom.Configuring JVM AutoProbe 2. To run the AutoProbe Connector for Sun ONE: 1.introscope.wily.agentProfile=<path-to-IntroscopeAgent.4 for each server.introscope. after the JAVA_VM and JAVA_OPTIONS. For example: -Xbootclasspath^/p:<IntroscopeAgent.Configuring JVM AutoProbe 3.42 must use the ^ (caret) character to escape a forward slash when issuing commands.xml file: <jvm-options> -Xbootclasspath/p:PathToAutoProbeConnectorJar:PathToAgentJar </jvm-options> The item separator is a colon (:).jar you created (such as startMedRecServer.jar path> Different versions of WebLogic use different versions of Java to run. you will use the following steps to run the AutoProbe connector. Add this line to the server.policy" weblogic. Edit the bootstrap classpath in the application startup script to include the AutoProbeConnector.username=${WLS_USER} -Dweblogic.jar:${WL_HOME }/wily/Agent.ProductionModeEnabled=${PRODUCTION_MODE} -Djava. 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.Server 2.5 or later. If you are using something other than the default bootstrap classpath.4 or earlier. If you use Java 1. To run the AutoProbe Connector for WebLogic: 1.password=${WLS_PW} -Dweblogic.policy="${WL_HOME}/server/lib/weblogic.jar -Dweblogic. modify the bootstrap classpath: -Xbootclasspath/p:wily/connectors/AutoProbeConnector.cmd) using this command: -Xbootclasspath/p:PathToAutoProbeConnectorJar:PathToAgentJar add the -X switch to the final start command at the end of the script.jar:PathToAgentJar Users running Oracle 10g Release 2 using Sun JDK 1.management.Name=${SERVER_NAME} -Dweblogic. For example: <jvm-options> -Xbootclasspath/p:/sw/sun/sunone7/wily/connectors/AutoProbeConnector. 66 Java Agent Guide . see JVM AutoProbe (see page 62) for more information.jar </jvm-options> To run the AutoProbe Connector for Oracle 10g: ■ To run the AutoProbe Connector.jar:/sw/ sun/sunone7/wily/Agent.jar and AutoProbeConnector. If you use Java 1. add the Agent.jar files to the beginning of your customized bootstrap classpath.security.management. then start the JRockit JVM using these command-line options.wily.introscope.introscope. see Creating an AutoProbe connector file (see page 64).0 with JRockit 5. By default. add the Agent. ■ For WebLogic pre-9.jrockit.profile Configuring ProbeBuilding The instrumenting process is performed using ProbeBuilding technology. The following sections have instructions on how to customize the metric collection level and how to configure optional ProbeBuilding behaviors. ■ ■ ■ ■ Full or typical tracing options (see page 68) Dynamic ProbeBuilding (see page 68) ProbeBuilding class hierarchies (JVM 1.jar:PathToAgentJar JRockit JVM AutoProbe To configure the JRockit JVM for AutoProbe. 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.agentProfile=PathToIntroscopeAgent.0: JAVA_VENDOR=Bea JAVA_OPTIONS=%JAVA_OPTIONS% -javaagent:PathToAgentJar -Dcom. create a connector file. For more information on how to create a connector file. which results in the collection of a moderate number of metrics.api.Configuring ProbeBuilding To run the AutoProbe Connector for other application servers: ■ To run the AutoProbe Connector.wily.5) (see page 72) Removing line numbers in bytecode (see page 75) Chapter 3: AutoProbe and ProbeBuilding Options 67 .jar and the AutoProbe Connector to the Application Server bootstrap classpath using this command: -Xbootclasspath/p:wily/connectors/AutoProbeConnector. AutoProbe will use the typical PBD set provided with the Java Agent. AutoProbeLoader ■ For WebLogic 9.0 with JRockit JVM: -Xbootclasspath/a:PathToAgentJar -Xmanagement:class=com. directivesFile specifies the typical version of the default PBL file. 2. Dynamic ProbeBuilding Introscope uses dynamic ProbeBuilding to implement new and changed PBDs without restarting managed applications or the agent itself.directivesFile=weblogic-full.profile. so previous versions of Java are not able to use this Introscope function.autoprobe. Dynamic ProbeBuilding is dependant on Java 1. and a typical version that enables a smaller set of Tracer Groups. located in the <Agent_Home>/wily directory. Note: In Introscope 9. see Dynamic ProbeBuilding vs. For example. introscope. This results in less detailed metric reporting and reduced overhead. Stop the managed application. Dynamic ProbeBuilding is also dependant on the -javaagent command. 3.Configuring ProbeBuilding Full or typical tracing options In Introscope. By default.autoprobe. Specify the name of the PBL file you wish to use in this property: introscope. or to temporarily change data collection levels during triage or diagnosis without interrupting application service. Important: Dynamic ProbeBuilding is only available for use with Java 1.5 or higher. see ProbeBuilder Directives overview (see page 56). Open the IntroscopeAgent. Introscope provides two versions of each default PBL —a full version which enables a larger set of Tracer Groups than the typical version which results in more detailed metric reporting.5 capabilities.autoprobe.autoprobe. to use the Full version of the standard PBL for WebLogic Server.pbl 4. This is useful for making corrections to PBDs. For more information on full and typical system directives files and customizing the TYPICAL settings. dynamic instrumentation (see page 71). To change the tracing level between full and typical: 1. the Workstation allows you to perform dynamic instrumentation through the Transaction Trace viewer.0. For more information. ProbeBuilder List (PBL) files govern which tracer groups are used in the instrumentation process.directivesFile property specifies one or more PBL files. Restart the managed application. 68 Java Agent Guide . and the CA Wily Introscope Workstation User Guide. set the property to: introscope.directivesFile. The introscope. fewer components are traced Once these two tracer groups have been created. the scope of dynamic agent re-instrumentation is limited to reloading only those classes whose instrumentation has changed when PBDs were edited. turning off XYZTracing and turning on XYZTracingLite. and classes specified in Skip directives are not re-instrumented. only user directives (such as adding or removing directives for a class.regular tracing options XYZTracingLite . When configuring dynamic ProbeBuilding. or toggling tracer groups) are re-instrumented.Configuring ProbeBuilding When dynamic ProbeBuilding is enabled. To avoid this issue. with the following effects: ■ ■ Modifications to the j2ee. access to some class bytes is not available. System directives (such as adding a tracer or changing a new tracer mapping) are not re-instrumented. interfaces. Existing metrics do not disappear from the Investigator window if their classes are re-instrumented. Arrays. you should create two tracer groups: ■ ■ XYZTracing .pbd file may not be picked up. When a PBD is edited or added to the hotdeploy directory. restart the application server after modifying the j2ee. as well as any transformations. For example. see Contents of the wily\hotdeploy directory (see page 46). Some exceptions may appear in the agent log.pbd file. you can view the impact that dynamic ProbeBuilding has on your environmental performance and adjust the tracing groups accordingly. Introscope selectively re-instruments classes affected by the modified PBDs. Chapter 3: AutoProbe and ProbeBuilding Options 69 . This would affect all classes being traced as part of each tracer group. If a class is re-instrumented so that it no longer reports data for a metric. 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. In addition. CA Technologies recommends that you base your changes on tracer groups. For more information about the hotdeploy directory. To improve performance. you can toggle between them. if you want to control the level of instrumentation for the tracer group XYZ. the metric is still displayed in the Introscope Investigator. Introscope periodically checks for new and changed PBDs. and metrics may continue to be published under old names. Note: Dynamic ProbeBuilding is not enabled by default. Important: Due to a limitation in Java 1.5. To minimize overhead. By toggling between the two tracer groups. dynamicinstrument.dynamicinstrument. is set to true.profile file. 5. 3.autoprobe. However.autoprobe. Open the IntroscopeAgent.dynamicinstrument.pollIntervalMinutes=1 The polling interval in minutes to check for PBD changes. see Default tracer groups and toggles files (see page 114). ■ introscope. In cases where the changes in PBDs trigger a re-definition of a large number of classes. ■ introscope.profile: introscope. Changes to skips or transformations are also not supported. You must restart the managed application before changes to this property take effect. Verify that the property. this property attempts to batch the process at a comfortable rate. 2. 4. Turning tracer groups on or off (see page 125). This is to prevent memory errors. introscope. Uncomment and set the following properties: ■ introscope.autoprobe. You must restart the managed application before changes to this property take effect.dynamicinstrument. For example. and Adding classes to a tracer group (see page 126). usually located in the <Agent_Home>/wily directory. Introscope does not ship any out of the box directives without tracer groups or flags. The default is set to one minute intervals.avoidClassLoaders.enabled=true This property enables dynamic ProbeBuilding. Save changes to the IntroscopeAgent. 70 Java Agent Guide . ■ introscope.enable.profile.autoprobe.Configuring ProbeBuilding Important: Changes to directives not using tracer groups are not supported.autoprobe.dynamicinstrument.autoprobe. Important: The following properties are no longer available for use and have been removed from the IntroscopeAgent.dynamic. For more information on tracer groups. Restart the managed applications (if appropriate).classFileSizeLimitInMegs=1 Some classloader implementations have been observed to return huge class files.autoprobe. changes in any directive like TraceAllMethods that does not have an IfFlagged switch are not supported.limitRedefinedClassesPerBatchTo=10 Re-defining too many classes at a time might be very CPU intensive.instrumentList introscope. You must restart the managed application before changes to this property take effect. To configure dynamic ProbeBuilding: 1. see the CA WIly Introscope Workstation User Guide. dynamic ProbeBuilding is based on manual changes you make to PBD files and manual configurations you make in the IntroscopeAgent. you (the user) must have write access to the <Agent_Home> directory as well as the <Agent_Home>/logs directory. dynamic instrumentation cannot create the <Agent_Home>/Dynamic directory or create the dynamic instrumentation cache which it needs to function. Chapter 3: AutoProbe and ProbeBuilding Options 71 . IBM has provided technical information on this performance overhead in the Java Diagnostics Guide. If you update or change a PBD file and save it in the correct location. and subsequently view metrics returned by the newly instrumented methods. and are often only temporary.profile. your permissions must allow you write access to the directories above. Dynamic instrumentation is performed from the Introscope Workstation transaction trace viewer.Configuring ProbeBuilding Dynamic ProbeBuilding vs. dynamic instrumentation Dynamic ProbeBuilding and dynamic instrumentation are not the same thing. This allows you to do dynamic application performing tuning.profile. or all of the methods during a transaction trace session.profile. You can dynamically instrument one. Dynamic ProbeBuilding requires you to make configuration changes in the IntroscopeAgent. For more information on how to use dynamic instrumentation from the Introscope Workstation transaction trace viewer. Important: To use dynamic instrumentation. and all changes are permanent (until you manually update or change the files again). Instrumenting a method dynamically means inserting the instrumentation during runtime. Use of class redefinition can significantly impact performance when running on IBM JDK version 5. Dynamic instrumentation does not require any changes to the IntroscopeAgent. The changes to instrumentation you select using the interface are made automatically for you. as well as all changes to the PBD files you want updated. a new PBD is created and saved in the correct location for you. Since you must sign in to the Workstation to perform dynamic instrumentation. If you do not have write access to these directories. Dynamic instrumentation requires class redefinition support. dynamic ProbeBuilding picks up the changes and implements them. As outlined in Dynamic ProbeBuilding (see page 68). more. and if you decide to make instrumentation changes permanent. If you prefer to update your PBDs manually. you can disable directive updates and use the log file to determine appropriate updates. and when employing this configuration. To enable instrumentation of multiple levels of subclasses: 1.5 JVMs.autoprobe. Directive changes are written to a log file as well. The CA Wily Introscope documentation contains details about configuring CA Wily Introscope on IBM JDK Version 5 with class redefinition both enabled and disabled.profile.enabled=true 4. Open the IntroscopeAgent. For more information. Verify that dynamic instrumentation is enabled as described in Dynamic ProbeBuilding (see page 68).Configuring ProbeBuilding CA Wily Introscope and IBM JDK version 5 customers that would like to take advantage of dynamic instrumentation should keep this performance overhead in mind.1 (see page 85) Socket metrics (see page 158) Note: There is no performance overhead with the use of class redefinition when using CA Wily Introscope with IBM JDK version 6. you can configure Introscope to instrument multiple levels of subclasses of a probed class—the tracer groups in the associated internal directive are updated appropriately and the classes are dynamically instrumented.hierarchysupport. Enable instrumentation of multiple levels of subclasses Follow these steps to configure Introscope to dynamically update internal directives. To enable instrumentation of multiple levels of subclasses. For more information see: ■ ■ AutoProbe for WebSphere 6. 3.profile. CA Technologies recommends using the dynamic instrumentation feature only in a QA environment. ProbeBuilding class hierarchies (JVM 1. With a 1.5 JVM and higher. 72 Java Agent Guide . uncomment this property setting: introscope.5) In pre-1. 2. Introscope does not automatically instrument classes in the deeper levels of class hierarchy—only the classes that explicitly extend a probed class. see Instrumenting and inheritance (see page 142). Save the IntroscopeAgent. When used. This is the number of subclasses or the number of implementing classes.Configuring ProbeBuilding Support for multiple inheritance. if the method is called within a specific stack trace. if the method is called within a specific stack trace. Introscope 9. see Creating custom tracers (see page 132). getMethodCalls allows you to better understand the consequences of instrumentation of inherited methods or interface methods by providing the following information: ■ ■ ■ if the class defining the method is an interface.0.0 Java Agent. the number of classes affected by a possible instrumentation of the method. You should test the impact of this tracer during your system startup and instrumentation processes before deploying to a larger agent configuration. using the following syntax: TraceOneMethodWithlabelIfInherits: <class> <method> <Label> <Tracer Group> <Tracer Type> <Resource> This tracer instruments a method of any class implementing interface or extending superclass if the method is either defined in the interface or is abstract in the superclass Important: Using this tracer could have a heavy impact on the performance of your system. For more information on tracers and creating customs tracers. the 9. the number of classes affected by a possible instrumentation of the method. getMethodCalls allows you to better understand the consequences of instrumentation of inherited methods or interface methods by providing the following information: ■ ■ ■ if the class defining the method is an interface. In addition. When used. This ability has been extended to dynamic instrumentation in Introscope 9.0 also supports the instrumentation of methods through a call to subclasses by using the Introscope API getMethodCalls.0 Java Agent also supports the instrumentation of methods through a call to subclasses by using the Introscope API getMethodCalls. and abstract methods The Java Agent supports instrumentation by interface as well as multiple inheritance. In addition. A new tracer to instrument interfaces and abstract methods is available with the 9. Chapter 3: AutoProbe and ProbeBuilding Options 73 . interfaces. This is the number of subclasses or the number of implementing classes. hierarchysupport.disableDirectivesChange=true 74 Java Agent Guide . Optionally.runOnceOnly=false To change the frequency with which Introscope polls for uninstrumented subclasses from its default value of 5.profile. 2. Uncomment this property setting: introscope.hierarchysupport. Disable directive updates If multi-level subclass instrumentation is enabled.autoprobe. Introscope will check for uninstrumented subclasses at application startup.pollIntervalMinutes 4. you can limit the number of times Introscope polls uninstrumented subclasses by uncommenting this property and setting it to the desired limit: introscope.hierarchysupport.profile.autoprobe.hierarchysupport.profile: introscope. by default. it updates internal directives appropriately to ensure the classes are instrumented. when Introscope detects uninstrumented subclasses. 3. 5. uncomment this property and set it to the desired polling frequency: introscope. Save the IntroscopeAgent.autoprobe.Configuring ProbeBuilding Configure periodic polling for uninstrumented subclasses When multi-level subclass instrumentation is enabled.autoprobe. Open the IntroscopeAgent. If you prefer to update PBDs manually. To configure Introscope to poll for uninstrumented subclasses: 1.executionCount The default of this property is 3 minutes. you can disable internal directive updates by uncommenting this property in the IntroscopeAgent. wily.appender.IntroscopeAgent.log log4j.profile to have multi-level subclass instrumentation logs created.wily.introscope. The multi-level instrumentation details are written to the agent logs.PatternLayout log4j.inheritance=INFO. log4j.apache.AutoNamingRollingFileAppender log4j.log4j.removeLineNumbers=true Chapter 3: AutoProbe and ProbeBuilding Options 75 .org. You can turn off this feature by adding a system property on the Java command line.appender.Configuring ProbeBuilding Controlling directive logging When multi-level subclass instrumentation is enabled.pbdlog log4j.File=pbdupdate. Removing line numbers in bytecode When you instrument application bytecode. Turning off this feature removes all line numbers when AutoProbe or ProbeBuilder instruments the application code.inheritance=false log4j.appender.logger.ConversionPattern=%d{M/dd/yy hh:mm:ss a z} [%-3p] [%c] %m%n_ You must restart the managed application before changes to these properties take effect. a log file named pbdupdate.layout=com. To remove line numbers in bytecode when using AutoProbe or ProbeBuilder: ■ Define this system property on the Java command line with the -D option: com. When these properties are configured.log is created in the <Agent_Home>/wily directory (by default).pbdlog.wily.appender. or in the custom location (if specified).pbdlog. you must uncomment the following properties in the IntroscopeAgent.additivity.probebuilder.pbdlog.IntroscopeAgent.pbdlog=com.agent.layout. the bytecode line numbers are preserved by default. Preserving bytecode line number information is helpful when using debuggers or when obtaining stack trace information. . 0.Chapter 4: Deploying the Java Agent on WebLogic This section contains specific information for deploying the Java Agent on a WebLogic Server.cmd) to include these options to the JVM command line: -javaagent:<PathToAgentJar> -Dcom. To configure WebLogic Server 9. This section contains the following topics: Before you begin (see page 77) Configuring AutoProbe for WebLogic Server (see page 77) Application server management data (see page 78) Configuring the SQL Agent for WebLogic Server (see page 79) Configuring WebLogic Diagnostic Framework (WLDF) (see page 82) Cross-process Transaction Tracing in WebLogic (see page 83) Introscope Java Agent JMX support (see page 84) Before you begin The instructions in this section are configurations specific to deploying your Java Agent in a WebLogic Server environment.0 and higher.0. 9. Configuring AutoProbe for WebLogic Server To monitor WebLogic you need to configure the WebLogic Server to use AutoProbe to instrument applications. 10.wily. or 10.3 to use AutoProbe: ■ Edit the application startup script (such as startMedRecServer. You should consult the Java Agent configuration overview (see page 53) to view other configuration options for the Java Agent that have no WebLogic-specific configurations.introscope. The Introscope Java Agent 9.agentProfile=<PathToAgentProfile> Chapter 4: Deploying the Java Agent on WebLogic 77 .1.0 only supports WebLogic Server 9. This section assumes you have followed the instructions for Installing the Java Agent (see page 29) and JVM AutoProbe (see page 62). The Target and Deploy tab appears.weblogic.Application server management data Application server management data In WebLogic Server environments. Configuring a startup class for WebLogic 9. consult your WebLogic Server documentation. Click the Startup & Shutdown folder. 2. For example.wily.introscope. 4. expand the Environments folder. above and beyond the metrics resulting from instrumenting your applications.api.0 or higher This section describes how to create a startup class for WebLogic 9. In the left pane. Click Configure a New Startup Class. if available.0 and later) uses JMX metrics. 78 Java Agent Guide . enter: Introscope Startup Class In the ClassName field.0 or higher. in application health heuristics. To configure a startup class for WebLogic 9. To enable the Java Agent to obtain and use data from the application server you configure an Introscope startup class or service in the application server. you can configure an agent to: ■ ■ ■ report JMX metrics from the application server report WebLogic Diagnostic Framework (WLDF) data from WebLogic 9. 3. 5. The Configuration tab is shown. enter: com. For information about creating a startup class in other versions of WebLogic Server. or to an application server cluster. but it enhances the visibility provided by the Application Overview.0 or higher: 1. the Java Agent can obtain and report management information from the application server. 7. The Startup and Shutdown page opens. 6.IntroscopeStartupClass Click Create. Enabling the Java Agent to access application server management information is not required. Open the WebLogic Administrative Console. and target it at application server instances. or for more information about WebLogic Server.0 obtain its name from the application server The Application Overview in the Workstation (available in Introscope v7. In the Name field. Click Apply. 11.DB2ConnectionPoolDataSource COM.ibm. see Configuring the Introscope SQL Agent (see page 209).zip: ■ ■ COM. 9.jdbc.jar WebLogic jDriver for Oracle—jDriver 6. Configuring the SQL Agent for WebLogic Server The configuration procedures in this section only apply to you if you used Application Server AutoProbe or Manual ProbeBuilder to instrument your application. classes111_g.ibm.zip. Select the "Run before application deployments" option.DB2XADataSource In classes12.zip DB2—db2java.db2. Supported JDBC drivers The SQL Agent supports the following JDBC drivers: ■ ■ ■ ■ Oracle—classes111. classes12_g. 10.jar to the application startup classpath.zip: ■ ■ oracle.zip Sybase—jconn2.Configuring the SQL Agent for WebLogic Server 8. no further configuration is required to use the SQL Agent. For more information about the SQL Agent. Supported JDBC drivers and datasources The SQL Agent supports the following JDBC drivers and JDBC DataSources.1 The SQL Agent fully supports the JDBC 1. including support for all JDBC driver types.OracleXADataSource Chapter 4: Deploying the Java Agent on WebLogic 79 .zip. Add the location of the WebAppSupport.0 specifications.zip.xa.client.jdbc.0 and 2.db2.zip and classes12_g.jdbc.OracleConnectionPoolDataSource oracle.jdbc. Restart the application server. classes12. Supported JDBC datasources for WebSphere In db2java.pool. If you used JVM AutoProbe. Configuration instructions have been simplified to apply to both a JDBC driver and a JDBC datasource. I through IV. Check the box(es) for the server(s) you’d like to make this startup class available to. see . you need to add the Agent. The SQL Agent supports: ■ WebLogic Server 9.0 and higher If other applications use a JDBC DataSource or driver that has been instrumented.xa.pbd file (the default location is <Agent_Home>/wily) to the <Introscope_Home>\config\custompbd directory. you have write permission in the directory that contains the driver file. If you used JVM AutoProbe.jdbc. Once this is done. Instrument the JDBC DataSource or Driver The following instructions assume: ■ ■ ■ Introscope and ProbeBuilder are installed in your environment.Configuring the SQL Agent for WebLogic Server Supported JDBC datasources for WebLogic In classes12. locate the file containing the Java classes that implement your JDBC DataSource or driver. you are able to use the ProbeBuilder Wizard application either on Windows or using X-windows on UNIX. Shut down WebSphere.zip: ■ oracle. For more information.jar file to the classpaths for those applications. see the Using the command-line ProbeBuilder (see page 358). the applications may show up as "Unknown Processes" in the Introscope Workstation. To instrument a JDBC DataSource or Driver: 1. you must complete the configuration procedures. no further configuration is required. Copy the sqlagent. For instructions on command-line use of ProbeBuilder. In WebSphere. To configure the SQL Agent for WebLogic Server. 2.OracleXADataSource Configure the SQL Agent for WebLogic This section describes how to configure the SQL Agent to function with WebLogic using either a JDBC Driver or a JDBC DataSource.client. Important: If you used Application Server AutoProbe or Manual ProbeBuilder to instrument your application. 80 Java Agent Guide . 3. you must instrument the JDBC DataSource or driver.Instrument the JDBC DataSource or Driver (see page 80). This will not affect the functionality or performance of your application and can be ignored. zip. In your JDBC driver directory you should find the file containing the instrumented JDBC DataSource or driver. select the SYSTEM directives for either WebSphere or WebLogic.zip. click Next to name the resulting instrumented file. click Next.zip classes12. On the Destination Location screen. the name of the resulting file would be classes12. as in the following example: c:\> rename classes12.jar (located in <WebSphere_Home>\wily or <WebLogic_Home>/wily) in the classpath for those applications. Restart your administration or application server. Accept the default save location for the resulting file. the name of the file would be classes12. ■ Change your application server’s CLASSPATH setting to point to the new instrumented file.zip classes12. To use this file to see the JDBC metrics in Introscope do one of the following: ■ Set the original file aside and rename the instrumented one. On the Finished screen. 6. if using a file containing an Oracle JDBC DataSource. applications that reference the JDBC DataSource will fail at runtime. At the Welcome screen. The new copy will be located in the same directory as the original. depending on which system you are configuring. 9. located in the <Introscope_Home> directory: ■ ■ Introscope ProbeBuilder Wizard. instrumenting the JDBC DataSource in the copy. This creates a copy of the file containing the JDBC DataSource.isc. 11.exe on Windows IntroscopeProbeBuilderWizard on UNIX 5.Configuring the SQL Agent for WebLogic Server 4. 7. Note: Before instrumenting any file. if using the file containing an Oracle JDBC DataSource. Click Add Probes.orig. do not attempt to rename it until you first shut down any application or database that is actively using the file containing the JDBC DataSource. select the sqlagent. you will need to put the Agent. 12. On the System Directives screen. click Exit.zip Note: If the file to be renamed is in use. Run the ProbeBuilder Wizard. Click Next. 10.isc. Otherwise. Chapter 4: Deploying the Java Agent on WebLogic 81 . 8. For example.pbd along with any other custom PBDs used in your deployment. select the file containing the JDBC DataSource to instrument. On the Custom Directives screen. save a backup copy in another location.zip c:\> rename classes12. For example. Note: If other applications use this same JDBC DataSource or driver file. On the Select Original Java Bytecode screen. However. In previous releases of WebLogic Server. you can create. WLDF is a new feature in WebLogic 9. see the WebLogic Server documentation. WLDF has a set of Data Accessors.Configuring WebLogic Diagnostic Framework (WLDF) Configuring WebLogic Diagnostic Framework (WLDF) The WebLogic Diagnostic Framework (WLDF) is a monitoring and diagnostic framework that defines and implements a set of services that run within the WebLogic Server process and participate in the standard server life cycle. each with multiple Columns (metrics). Where JMX MBeans have multiple Attributes (metrics). Introscope converts this WLDF information into Introscope-specific metric format and displays it in the Investigator under the following node: <Domain>|<Host>|<Process>|AgentName|WLDF| Introscope converts Data Accessor Columns using the following method: ■ ■ key and value information is displayed key/value pairs are placed in alphabetical order in the Introscope-generated metrics. Introscope converts WLDF Columns to Introscope metrics. This data provides insight into the run-time performance of servers and applications and enables you to isolate and diagnose faults when they occur. The following example shows the syntax used: <Domain>|<Host>|<Process>|AgentName|WLDF|<domain name>|<key1>=<value1>|<key2>=<value2>:<metric> 82 Java Agent Guide . WLDF enables dynamic access to server data through standard interfaces and the volume of data accessed at any given time can be modified without shutting down and restarting the server. Understanding WLDF metric conversion Introscope WLDF metric conversion is similar to that in JMX metric conversion. archive and access diagnostic data generated by a running server and the applications deployed within its containers. collect. Using WLDF. access to diagnostic data by monitoring agents—which were developed by customers or third-party tools vendors—was limited to JMX attributes. analyze.0. and changes to monitoring agents required server shutdown and restart. For more information on WLDF. Information in the Data Accessors is defined by a domain name and one or more key/value pairs. Shut down the managed application if it is running. 3. 2. Chapter 4: Deploying the Java Agent on WebLogic 83 . Add "-Dweblogic. 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 Metric names BYTECOUNT Note that the key/value pairs are displayed alphabetically in the Introscope metric.weblogic. for instance servlets to EJBs. Enabling cross-process tracing in WebLogic Server 1. In the IntroscopeAgent. as well as asynchronous transactions. 2. this table shows the information for the BYTECOUNT Column from the HTTPAccessLog Data Accessor: Domain name WebLogic Key/Value pairs Name=HTTPAccessLog.agent.0 or higher (see page 78). 3. Configure web application support. Enabling WLDF reporting By default. find and set the following property: introscope.crossjvm=true in the agent profile.Cross-process Transaction Tracing in WebLogic For example.agent.enable=true Cross-process Transaction Tracing in WebLogic Transaction Tracer can trace transactions that cross JVM boundaries on WebLogic Server 9 or later if the environment is comprised of compatible versions of the same vendor’s application server.TracingEnabled=true" to the java command line for starting WebLogic Server.profile. Configure a WebLogic Startup Class. WLDF reporting is not enabled in Introscope. Cross-process transaction tracing is supported for synchronous transactions. Set introscope. Follow the instructions in Configuring a startup class for WebLogic 9.wldf. Type=WLDFDataAccessRuntime=Accessor.0 or higher. To enable WLDF reporting: 1. as described in Configuring a startup class for WebLogic 9. 0 provided only a single MBeanServer as a source of JMX metrics.sun. JMX filters for WebLogic In the IntroscopeAgent. Introscope converts the JMX data to Introscope metric format and displays it in the Investigator under the following Resource: <Domain>|<Host>|<Process>|AgentName|JMX| Introscope support for WebLogic 9.profile file for WebLogic. 84 Java Agent Guide .0 JMX metrics WebLogic versions prior to WebLogic 9. For more information on the Sun JMX specification. and because it contains most of the data expected to be relevant.Introscope Java Agent JMX support Introscope Java Agent JMX support Introscope can collect management data that application servers or Java applications expose as JMX-compliant MBeans. the following keywords are already defined and enabled: ■ ■ ■ ■ ■ ActiveConnectionsCurrentCount WaitingForConnectionCurrentCount PendingRequestCurrentCount ExecuteThreadCurrentIdleCount OpenSessionsCurrentCount For more information see Enabling JMX Reporting (see page 221). see http://java.0 provides three: ■ ■ ■ RuntimeServiceMBean: per-server runtime metrics. including active effective configuration DomainRuntimeServiceMBean: domain-wide runtime metrics EditServiceMBean: allows user to edit persistent configuration Introscope polls only the RuntimeServiceMBean. and present the JMX data in the Investigator metric tree.com/products/JavaManagement/. Introscope supports any MBean built to the Sun JMX specification. WebLogic 9. because it is the only one that supports local access (an efficiency issue). jsp?topic=/com.ibm. You should consult the Java Agent configuration overview (see page 53) to view other configuration options for the Java Agent that have no WebSphere-specific configurations.0 for z/OS (see page 89) Modifying Java2 Security Policy (see page 91) Disable agent naming for WebSphere (see page 91) WebSphere application server management data (see page 91) The SQL Agent for WebSphere (see page 93) WebSphere PMI (see page 96) Logging considerations on WebSphere for z/OS (see page 98) Cross-process Transaction Tracing in WebSphere (see page 99) Before you begin The instructions in this section are specific configurations for the Java Agent in a WebSphere Application Server (WAS) or WebSphere for z/OS environment. IBM has provided technical information on this performance overhead in the Java Diagnostics Guide (http://publib.diagnostics.1 CA Wily Introscope's dynamic instrumentation feature requires class redefinition support.0 (see page 88) AutoProbe for WebSphere 6.com/infocenter/javasdk/v5r0/index.1 (see page 85) AutoProbe for WebSphere 7.ibm.java .boulder. This section contains the following topics: Before you begin (see page 85) AutoProbe for WebSphere 6. Chapter 5: Deploying the Java Agent on WebSphere 85 .html).1 and 7.50/diag/tools/jvmti. This section assumes you have followed the instructions for Installing the Java Agent (see page 29). AutoProbe for WebSphere 6. Use of class redefinition can significantly impact performance when running on IBM JDK version 5.doc.Chapter 5: Deploying the Java Agent on WebSphere This section contains specific information for deploying the Java Agent on a WebSphere application server. 86 Java Agent Guide . metrics are no longer reported for: ■ ■ ■ System classes NIO (Sockets and Datagrams) SSL In addition. Note: If you are using the AllAppServer agent distribution.5 JVMs is known to incur significant overhead.websphere. named AgentNoRedef. As a result of using the above files and syntax.profile . instrumentation on sockets reverts to pre-Introscope 9. the alternate profile is named IntroscopeAgent. For more information on dynamic instrumentation. remote dynamic instrumentation is disabled. Note: There is no performance overhead with the use of class redefinition when using CA Wily Introscope with IBM JDK version 6. changes to PBD files require the instrumented JVM to be restarted before being applied.NoRedef.1 CA Wily Introscope and IBM JDK version 5 customers that would like to take advantage of dynamic instrumentation should keep this performance overhead in mind. the log message is written at INFO level and reads: Introscope Agent Class Redefinition is disabled.AutoProbe for WebSphere 6. Writing a log message to agent log file. and deep inheritance and hierarchy support instrumentation is disabled.1 using an IBM JVM 1. Metric values are true or false. When using the above files and syntax. you must use the alternate versions of the Java Agent .5.profile.jar file and Java Agent profile. The CA Wily Introscope documentation contains details about configuring CA Wily Introscope on IBM JDK version 5 with class redefinition both enabled and disabled. are located in the <Agent_Home>/wily directory. see Dynamic ProbeBuilding vs. dynamic instrumentation (see page 71). If you are running WebSphere 6. These files.jar and IntroscopeAgent. Enabling class redefinition on IBM 1.NoRedef. ■ When class redefinition is disabled.0 ManagedSocket style. CA Technologies recommends using the dynamic instrumentation feature only in a QA environment. the log message is written at the WARN level and reads: Introscope Agent Class Redefinition is enabled. the agent reports class redefinition status by: ■ ■ Adding a metric called 'Agent Class Redefinition Enabled' under the agent node in the Investigator. and when employing this configuration. ■ When class redefinition is enabled. wily.NoRedef.introscope.5: -javaagent:<Agent_Home>/AgentNoRedef.jar -Dcom.jar -Dcom.jar instead of Agent. To avoid this overhead please use AgentNoRedef.1 on UNIX.profi le Note: A unique directory is required when there is more than one version of WebSphere using the same agent directory.wily.5 and higher are known to incur significant overhead with redefinition enabled. If you use a non-IBM JVM or an IBM JVM that a version other than 1.1: On WebSphere Application Server 6.profile 4.agentProfile=<Agent_Home>/IntroscopeAgent. For all other JVMs: -javaagent:<Agent_Home>/Agent.introscope. IBM JVMs version 1.agentProfile=<Agent_Home>/IntroscopeAgent.jar.1 on IBM JVM 1. use: -javaagent AgentNoRedef. Navigate to Application Servers > your server > Server Infrastructure > Java and Process Management > Process Definition > Java Virtual Machine . 2. OS/400.profile On WebSphere Application Server 6.profile To configure JVM AutoProbe on WAS 6. In WebSphere.NoRedef.jar file to use with a specific JVM when installing the Java Agent on WebSphere 6. Chapter 5: Deploying the Java Agent on WebSphere 87 .introscope. Windows. The following examples indicate which Java argument and . use: -javaagent AgentNoRedef.5. start the Administrator’s Console.introscope.5.jar -Dcom.5.jar For example: -javaagent:<Agent_Home>/AgentNoRedef.1: 1.wily. Restart the WebSphere application server. the above metric and messages are not output.1 on UNIX or Windows with Sun or HP JVM 1.wily. 3. which reads: Warning: Introscope agent has been configured to support class redefinition.AutoProbe for WebSphere 6. Set the Generic JVM Argument field as follows: For WAS 6.agentProfile=<Agent_Home>/IntroscopeAgent.jar -Dcom. z/OS with the IBM JVM 1.1 ■ Writing a message to standard error (only when class redefinition is enabled).jar For example: -javaagent:<Agent_Home>/Agent.agentProfile=<Agent_Home>/IntroscopeAgent. see AutoProbe and ProbeBuilding Options (see page 61).jar -javaagent:<Agent_Home>/Agent.0.6. For more information about AutoProbe. AutoProbe for WebSphere 7. or OS/400 with the IBM JVM 1.0 build level 7.agentProfile=<Agent_Home>/IntroscopeAgent.AutoProbe for WebSphere 7. upgrade to WAS 7.0 on UNIX. you may see the application server process restart repeatedly.jar -Dcom. use: -javaagent Agent. If Java2 Security is enabled. Windows.jar -Dcom.0 installations to use JVM AutoProbe to instrument applications.0 on different platforms: On WebSphere Application Server 7.profile On WebSphere Application Server 7. The following examples indicate which Java argument and .jar For example: -javaagent:<Agent_Home>/Agent.0 This section details how to configure WebSphere 7. 2.0: 1.profile On WebSphere Application Server 7.0.jar For example: -Xbootclasspath/a:<Agent_Home>/Agent.wily.0 on UNIX.6.profile To configure JVM AutoProbe on WAS 7.wily.introscope.6. Navigate to Application Servers > your server > Server Infrastructure > Java and Process Management > Process Definition > Java Virtual Machine . it may be necessary to add permissions to your Java2 Security Policy. To avoid this problem.jar -Dcom.wily. use: -Xbootclasspath -javaagent Agent. use: -javaagent Agent.0 Note: For AutoProbe to run correctly in WebSphere environments with Java2 Security enabled.agentProfile=<Agent_Home>/IntroscopeAgent.8 or above.jar For example: -javaagent:<Agent_Home>/Agent. Windows.0 or later to monitor WebSphere 7.jar file to use with a specific JVM when installing the Java Agent on WebSphere 7. In WebSphere.agentProfile=<Agent_Home>/IntroscopeAgent.introscope. follow the instructions in Modifying Java2 Security Policy (see page 91). 88 Java Agent Guide .0 on z/OS with IBM JVM 1. or OS/400 with IBM JVM 1. start the Administrator’s Console.0.introscope. Important: If you are using the Java Agent 9. AutoProbe for WebSphere 6.1 and 7.0 for z/OS 3. Set the Generic JVM Argument field as follows: For WAS 7 JDK 1.6 on z/OS: -Xbootclasspath/a:<Agent_Home>/Agent.jar -javaagent:<Agent_Home>/Agent.jar -Dcom.wily.introscope.agentProfile=<Agent_Home>/IntroscopeAgent.profile For all other JVMs: -javaagent:<Agent_Home>/Agent.jar -Dcom.wily.introscope.agentProfile=<Agent_Home>/IntroscopeAgent.profile 4. Restart the WebSphere application server. Note: 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 91). AutoProbe for WebSphere 6.1 and 7.0 for z/OS This section details how to configure WebSphere on z/OS installations to use AutoProbe to instrument applications. For more information about AutoProbe, see AutoProbe and ProbeBuilding Options (see page 61). Note: Instrumenting WebSphere 7.0 for z/OS using the following procedure will not result in as detailed metrics as the JVM 1.5 AutoProbe method. For example, the thread metric levels will not be instrumented. For more information on how to instrument WebSphere 7.0 for z/OS using JVM 1.5 AutoProbe, see JVM AutoProbe for WAS 7 on z/OS (see page 63). 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. In WebSphere, start the Administrator’s Console. Select Application Servers > <your server> > Process Definition. You should see two items, Control and Servant. Click Servant, then JavaVirtualMachine. Chapter 5: Deploying the Java Agent on WebSphere 89 AutoProbe for WebSphere 6.1 and 7.0 for z/OS 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. Place the Agent.jar file in the <WebSphere Instance dir>/lib/ext directory. Note: Do not place the Agent.jar file in the WebSphere installation directory. The following shows examples of the wrong and right directory: WRONG: /usr/lpp/zWebSphere/V5R0M0/lib/ext RIGHT: /WebSphere/V5R0M0/AppServer/lib/ext 6. 7. Confirm that all newly created Introscope files and directories within the ./wily directory are read-accessible by the WebSphere process. 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: ■ ■ all the Introscope files and directories the Introscope files inside <WAS instance dir>/lib/ext 8. 9. Restart WebSphere application server. When WebSphere says "open for e-business," open the Administrator’s 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 91). 11. Configure Tracer Groups to collect servlet data. For more information, see Configuring HTTP servlet tracing (see page 368). 90 Java Agent Guide Modifying Java2 Security Policy Modifying Java2 Security Policy If you have Java2 Security enabled, you may need to add the following permissions to your Java2 Security Policy. To add permissions to your Java2 Security Policy: ■ Edit the file <WebSphere home>/properties/server.policy to include the following: // permissions for Introscope AutoProbe grant codeBase "file:${was.install.root}/-" { permission java.io.FilePermission "${was.install.root}${/ }wily${/}-", "read"; permission java.net.SocketPermission "*", "connect,resolve"; permission java.lang.RuntimePermission "setIO"; permission java.lang.RuntimePermission "getClassLoader"; permission java.lang.RuntimePermission "modifyThread"; permission java.lang.RuntimePermission "modifyThreadGroup"; permission java.lang.RuntimePermission "loadLibrary.*"; permission java.lang.RuntimePermission "accessClassInPackage.*"; permission java.lang.RuntimePermission "accessDeclaredMembers"; }; grant { permission java.util.PropertyPermission "*", "read,write"; }; Note: Line breaks are shown for user readability and are not needed when adding the permissions to the server.policy file. Disable agent naming for WebSphere Agent automatic naming is enabled by default for all WebSphere platforms. For more general information on Java Agent naming, see Java Agent Naming (see page 147). Note: A custom service must be configured. WebSphere application server management data In WebSphere environments, the Java Agent can obtain and report management information from the application server above and beyond the metrics from instrumenting your applications. For example, you can configure an agent to: ■ ■ ■ report JMX metrics from the application server report Performance Monitoring Infrastructure (PMI) from WebSphere obtain its name from the application server Chapter 5: Deploying the Java Agent on WebSphere 91 WebSphere application server management data The Application Overview in the Workstation (available in Introscope v7.0 and later) uses JMX and PMI metrics, if available, in application health heuristics. Enabling the Java Agent to access application server management information is not required, but it enhances the visibility provided by the Application Overview. To enable the Java Agent to obtain and use data from the application server, you configure an Introscope startup class or service in the application server and target it at application server instances, or to an application server cluster. Configuring a custom service in WebSphere 6.1 This section describes how to create a custom service in WebSphere 6.1. To create a custom service in previous versions, or for more information, consult your WebSphere documentation. To configure a custom service in WebSphere 6.1: 1. 2. 3. 4. 5. 6. 7. 8. Open the WebSphere Administrative Console. Select the server you'd like to configure, then navigate to Server Infrastructure > Administration > Custom Services. Click New to add a new Custom Service. In the Classname field, enter: com.wily.introscope.api.websphere.IntroscopeCustomService In the Display Name field, enter: Introscope Custom Service In the Classpath field, enter: <WebSphere_Home>/wily/WebAppSupport.jar Click OK. Restart the application server. WAS 6.1 on AIX platform In some cases, customers running WebSphere Application Server (WAS) 6.1 on the AIX platform may see the following error thrown by the non-instrumented applications: java.lang.NoClassDefFoundError:com.wily.introscope.agent.probe.io.ManagedFileInpu tStream This stems from having both instrumented and non-instrumented applications on the same machine. To avoid this problem, include the following JVM flag in the Generic JVM Arguments field when configuring your WAS application for Introscope: -Xshareclasses:none 92 Java Agent Guide The SQL Agent for WebSphere The SQL Agent for WebSphere The configuration procedures in this section only apply to you if you used Application Server AutoProbe or Manual ProbeBuilder to instrument your application. If you used JVM AutoProbe, no further configuration is required to use the SQL Agent. For more information about the SQL Agent, see Configuring the Introscope SQL Agent (see page 209). Supported JDBC drivers and DataSources The SQL Agent supports the following JDBC drivers and JDBC DataSources. Configuration instructions have been simplified to apply to both a JDBC driver and a JDBC DataSource. Supported JDBC drivers The SQL Agent supports the following JDBC drivers: ■ ■ ■ ■ Oracle—classes111.zip, classes12.zip, classes111_g.zip, classes12_g.zip DB2—db2java.zip Sybase—jconn2.jar WebLogic jDriver for Oracle—jDriver 6.1 The SQL Agent fully supports the JDBC 1.0 and 2.0 specifications, including support for all JDBC driver types, I through IV. Supported JDBC datasources for WebSphere In db2java.zip: ■ ■ COM.ibm.db2.jdbc.DB2ConnectionPoolDataSource COM.ibm.db2.jdbc.DB2XADataSource In classes12.zip and classes12_g.zip: ■ ■ oracle.jdbc.pool.OracleConnectionPoolDataSource oracle.jdbc.xa.client.OracleXADataSource Supported JDBC datasources for WebLogic In classes12.zip: ■ oracle.jdbc.xa.client.OracleXADataSource Chapter 5: Deploying the Java Agent on WebSphere 93 The SQL Agent for WebSphere Configuring the SQL Agent for WebSphere Application Server (WAS) This section describes how to configure the SQL Agent to function with WebSphere using either a JDBC Driver or a JDBC DataSource. For more information about the SQL Agent, see Configuring the Introscope SQL Agent (see page 209). Note: The SQL Agent supports WebSphere Application Server (WAS) 6.1 and higher. If other applications use a JDBC DataSource or driver that has been instrumented, you need to add the Agent.jar file to the classpaths for those applications. Once this is done, the applications may show up as "Unknown Processes" in the Workstation. This will not affect the functionality or performance of your application and can be ignored. To configure the SQL Agent for WebSphere Application Server (WAS): 1. 2. Configure the JDBC DataSource or driver in WebSphere. See Configure the JDBC DataSource or Driver in WebSphere (see page 94). Instrument the JDBC DataSource or Driver. See Instrument the JDBC DataSource or Driver (see page 80). Important: If you used Application Server AutoProbe or Manual ProbeBuilder to instrument your application, you must complete the configuration procedures. If you used JVM AutoProbe, no further configuration is required. Configure the JDBC DataSource or Driver in WebSphere In your WebSphere environment, configure your JDBC DataSource or driver to work with SQL Agent and WebSphere. For more information, refer to your WebSphere documentation. Instrument the JDBC DataSource or Driver The following instructions assume: ■ ■ ■ Introscope and ProbeBuilder are installed in your environment. you have write permission in the directory that contains the driver file. you are able to use the ProbeBuilder Wizard application either on Windows or using X-windows on UNIX. For instructions on command-line use of ProbeBuilder, see the Using the command-line ProbeBuilder (see page 358). 94 Java Agent Guide The SQL Agent for WebSphere To instrument a JDBC DataSource or Driver: 1. 2. 3. 4. Shut down WebSphere. Copy the sqlagent.pbd file (the default location is <Agent_Home>/wily) to the <Introscope_Home>\config\custompbd directory. In WebSphere, locate the file containing the Java classes that implement your JDBC DataSource or driver. Run the ProbeBuilder Wizard, located in the <Introscope_Home> directory: ■ ■ Introscope ProbeBuilder Wizard.exe on Windows IntroscopeProbeBuilderWizard on UNIX 5. 6. At the Welcome screen, click Next. On the Select Original Java Bytecode screen, select the file containing the JDBC DataSource to instrument. For example, if using a file containing an Oracle JDBC DataSource, the name of the file would be classes12.zip. Note: Before instrumenting any file, save a backup copy in another location. 7. On the Destination Location screen, click Next to name the resulting instrumented file. For example, if using the file containing an Oracle JDBC DataSource, the name of the resulting file would be classes12.isc.zip. Accept the default save location for the resulting file. On the System Directives screen, select the SYSTEM directives for either WebSphere or WebLogic, depending on which system you are configuring. Click Next. On the Custom Directives screen, select the sqlagent.pbd along with any other custom PBDs used in your deployment. 8. 9. 10. Click Add Probes. This creates a copy of the file containing the JDBC DataSource, instrumenting the JDBC DataSource in the copy. The new copy will be located in the same directory as the original. Chapter 5: Deploying the Java Agent on WebSphere 95 To enable PMI reporting: 1. see Configuring a custom service in WebSphere 6. 12. you will need to put the Agent. To use this file to see the JDBC metrics in Introscope do one of the following: ■ Set the original file aside and rename the instrumented one. depending on their needs. In your JDBC driver directory you should find the file containing the instrumented JDBC DataSource or driver. do not attempt to rename it until you first shut down any application or database that is actively using the file containing the JDBC DataSource. On the Finished screen.isc.1 and higher.jar (located in <WebSphere_Home>\wily or <WebLogic_Home>/wily) in the classpath for those applications. for a better method of recording WebSphere PMI data. In WebSphere.zip classes12.1 (see page 92). After you have enabled PMI data collection in WebSphere. Configure an Introscope Custom Service in WebSphere. Enable PMI in the IntroscopeAgent. applications that reference the JDBC DataSource will fail at runtime. Users can filter which metric categories to bring into Introscope. For more information. For more information.orig. see Configuring WebSphere PMI in Introscope (see page 97). the PMI data can then be displayed as Introscope metrics. Note: If other applications use this same JDBC DataSource or driver file. 2. If you are using WebSphere on z/OS. see Enabling PMI in WebSphere (see page 97). see Using WebSphere PMI with Introscope on z/OS (see page 97). all performance monitoring settings are off by default.profile. Restart your administration or application server. 96 Java Agent Guide . 3. Otherwise.WebSphere PMI 11. ■ Change your application server’s CLASSPATH setting to point to th e new instrumented file.zip classes12. WebSphere PMI Introscope can provide WebSphere performance data by extracting WebSphere Performance Monitoring Infrastructure (PMI) metrics via the PMI interface provided with WebSphere 6.zip c:\> rename classes12. You must first enable PMI data collection in WebSphere before the data will be available to Introscope. click Exit.zip Note: If the file to be renamed is in use. Enable PMI in WebSphere. For more information. as in the following example: c:\> rename classes12. and enable the metric categories you’d like to see reported. you must enable PMI data collection in Introscope. These categories are represented by commented-out properties under the WebSphere PMI Configuration heading.1 and higher documentation for instructions on enabling Performance Monitoring Settings. and j2c—are set to true by default. Open the IntroscopeAgent. which provides WebSphere-specific PBDs and metrics. 6. as outlined in WebSphere PMI (see page 96). connectionPool. 5. CA Technologies recommends using the PowerPack for z/OS WebSphere product. Restart the managed application. 2. servletSessions. Shut down your managed application. 3.1: ■ See your WebSphere 6. under the WebSphere PMI Configurations heading.pmi.enable. Save the changes. To configure PMI collection: 1. Introscope can report data from the following high-level PMI metric categories.profile.WebSphere PMI Using WebSphere PMI with Introscope on z/OS There are several ways to obtain additional WebSphere-specific performance metrics on z/OS.agent. 4. and does not require you to enable PMI in WebSphere for z/OS. You can comment out categories to decrease the amount of metrics reported. Configuring WebSphere PMI in Introscope After you turn on Performance Monitoring Settings in WebSphere. and verify it is set to true. introscope. Four categories—threadPool. Chapter 5: Deploying the Java Agent on WebSphere 97 . but this approach consumes more system resources. Enabling PMI in WebSphere This section describes how to turn on WebSphere performance monitor settings. and enabling Performance Monitoring for each desired metric category. Locate the property. You can also enable PMI reporting on WebSphere for z/OS. This product uses tracer technology which has a low overhead method of obtaining WebSphere-specific metrics. To enable PMI in WebSphere 6. For more information about Java Agent logging options. Add these properties to the IntroscopeAgent. 2. available PMI metrics will be displayed in the WebSpherePMI node under the agent nodes in the Investigator tree.profile. To eliminate the timing window exposures: 1. 98 Java Agent Guide .appender. instead of ASCII.encoding=IBM-1047 log4j.logfile.appender.Logging considerations on WebSphere for z/OS Viewing WebSphere PMI data After you’ve enabled PMI collections in Introscope. Save the IntroscopeAgent. Eliminating startup timing issues with logging facilities A new property has been added for WebSphere for z/OS 6.console.1 and later.profile. see Java Agent Monitoring and Logging (see page 157).agent. Tagging log output as EBCDIC WebSphere for z/OS changed its default encoding from EBCDIC CP1047 to ASCII ISO8859-1. 3. located in the <Agent_Home>\wily directory. Save the IntroscopeAgent.profile.profile: log4j. Add this property to the IntroscopeAgent. located in the <Agent_Home>\wily directory. Because z/OS is normally an EBCDIC machine. 2.logger. To tag data as EBCDIC instead of ASCII: 1.encoding=IBM-1047 3.profile: introscope. Logging considerations on WebSphere for z/OS There are some things to consider when logging in a WebSphere z/OS environment. any logging data written by the Java Agent or AutoProbe must be tagged to use EBCDIC as the final output stream. Open the IntroscopeAgent. Open the IntroscopeAgent.delay=100000 The value is in milliseconds. which is used to eliminate any startup timing window exposures that can occur with the Introscope logging facilities. so the default delay in this example is 100 seconds.profile. 2.Cross-process Transaction Tracing in WebSphere Cross-process Transaction Tracing in WebSphere Transaction Tracer can trace transactions that cross JVM boundaries on WebSphere 6. servers->application servers. Set introscope.1 if the environment is comprised of compatible versions of the same vendor’s application server. see Configuring Transaction Trace Options (see page 203). For more information about Transaction Tracing. To enable cross-process tracing in WebSphere: 1. click on server1. for instance servlets to EJBs. Turn on the work area service. Chapter 5: Deploying the Java Agent on WebSphere 99 . as well as asynchronous transactions. From the administration page.websphere. 3. Cross-process transaction tracing is supported for synchronous transactions. Follow the instructions in Configuring a custom service in WebSphere 6. click on Business Process Services. Configure web application support.crossjvm=true in the agent profile. click on Work Area Service.1 (see page 92). check the "Enable service at server startup" box.agent. . Chapter 6: Deploying the Java Agent on other application servers using JVM AutoProbe This section provides instructions for deploying the Java Agent on other application servers. ■ JBoss If you installed the Java Agent on a JBoss system. See Configuring JBoss (see page 105). Chapter 6: Deploying the Java Agent on other application servers using JVM AutoProbe 101 . ■ Apache Tomcat If you installed the Java Agent on an Apache Tomcat application server.5 or higher.1 (see page 108) Configuring SAP Netweaver 7. there are several configurations you need to perform to have AutoProbe function correctly on the application server. This section contains the following topics: Deploying the Java Agent on other application servers using JVM AutoProbe (see page 101) Configuring Apache Tomcat (see page 102) Configuring JBoss (see page 105) Configuring Oracle Application Server 10g (see page 107) Configuring GlassFish 2.1 (see page 108) Deploying the Java Agent on other application servers using JVM AutoProbe You should use JVM AutoProbe if you are running JVM 1. there are further configurations you must perform to enable the reporting of JBoss metrics to Introscope. See Configuring Apache Tomcat (see page 102). Depending on which method you used to install the Java Agent on the Tomcat application server. see Hyphen Character Not Allowed in Java Identifier Names (KB 1331). Configure the Tomcat PBD with your tracing decisions. See Tomcat PBD tracing options (see page 103) for more information.profile as desired.see Java Agent configuration overview (see page 53) for more information. Configuring Apache Tomcat You can install the Java Agent on an Apache Tomcat application server. 2. Introscope does not parse this character. See Editing the startup script (see page 104) for more information. 102 Java Agent Guide . Edit the Tomcat startup script to add Wily-specific code. see Configuring Oracle Application Server 10g (see page 107). 4. ■ GlassFish 2.profile as desired.1 For more information see Configuring SAP Netweaver 7. When starting the application server. avoid using the hyphen (-) character as an identifier for a classname. There are multiple ways to configure the profile . Follow the manual installation instructions. Edit the IntroscopeAgent. 3. Follow the installer instructions.see Java Agent configuration overview (see page 53) for more information. See Tomcat PBD tracing options (see page 103) for more information. If you manually installed the Java Agent: 1. Edit the IntroscopeAgent. 3.1 (see page 108). there are further configurations you must make to ensure the Java Agent operates and reports metrics correctly. Configure the Tomcat PBD with your tracing decisions. 2. See The Java Agent installer (see page 30) for more information. ■ SAP Netweaver 7. For more information. See Manual installation (see page 40) for more information.1 For more information see Configuring GlassFish 2.1 (see page 108). If you used the Java Agent installer: 1. There are multiple ways to configure the profile .Configuring Apache Tomcat ■ Oracle Application Server 10g For more information. and using it might lead to class loading errors in the agent logs. pbd. Note: Use one of the formatting options. not both. you configure the PBD for your Apache Tomcat version. but this option functions in all Tomcat installations. If you are using Application Server AutoProbe. Open the PBD for the version of your Apache Tomcat application server from the wily directory. Edit the Tomcat startup script to add Wily specific code. To configure your Tomcat PBDs: 1. but may not work on all Tomcat installations. make sure to remove it. See Creating an AutoProbe connector file (see page 64) for more information. select and uncomment the formatting option you want to use. create the AutoProbeConnector. This option is enabled by default. Chapter 6: Deploying the Java Agent on other application servers using JVM AutoProbe 103 . there are some tracing options that must be configured. 6. Use one of the following: ■ ■ FormattedSessionTracing produces metrics that are easier to read.Configuring Apache Tomcat 4.pbd tomcat55x.jar from the <Agent_Home>/wily root directory into <Agent_Home>/wily/ext directories. 5. See Editing the startup script (see page 104) for more information.pbd tomcat50x. jar. You must determine if: ■ ■ you want to use unformatted or formatted session tracing (see step 2 below).jar file present under the tomcat_root/common/endorsed directory from the previous releases of the Java Agent. UnformattedSessionTracing produces metrics that may not be as easy to read.pbd or toggles-typical.pbd Note: Configure only one of the PBDs. The following PBDs are available for configuration: ■ ■ ■ tomcat41x. Copy the WebAppSupport. Important: If you have the WebAppSupport. and delete the ones you are not using. In the HTTP Session Configuration section of the toggles-full. Once you have determined the above. you want to trace Apache sessions or HTTP sessions (see step 3 below). 2. Tomcat PBD tracing options Once you have installed the Java Agent on an Apache Tomcat application server. ■ If you are tracing HTTP sessions. 2.introscope.0. If the PBD is in another directory.agentProfile="%WILY_HOME%\IntroscopeAgent.agentName=NewTomcatAgent set WILY_OPTS=-Dcom. to suit your own location and configuration: :: ----. Here is an example from Tomcat 5. If the Tomcat PBD you modified is in the hotdeploy directory.jar" set WILY_NAME=-Dcom. Insert the following code into the startup script. you must edit the start up script to include some code from CA Technologies.5 set WILY_ARGS=-javaagent:"%WILY_HOME%\Agent..pro file" %WILY_NAME% echo Using WILY_HOME: %WILY_HOME% echo Using WILY_ARGS: %WILY_ARGS% echo Using WILY_NAME: %WILY_NAME% echo Using WILY_OPTS: %WILY_OPTS% :skipWilyVars 104 Java Agent Guide . Also in the HTTP Session Configuration section. customizing paths.wily.0: To edit the start up script: 1. you must comment out the above session options and uncomment the following: #TurnOn: HTTPSessionTracing 4. you must restart your Java Agent. decide which type of session you are going to trace and do one of the following: ■ If you are tracing Apache sessions. etc.30\wily :: NOTE: Configuration below for jdk versions >= 1. make sure these two session options are uncommented: TurnOn: ApacheStandardSessionTracing TurnOn: SuperpagesSessionTracing Note: These session options are enabled by default.Wily Introscope --------------------------------------:: Place this code right before the commented-out start command :: Only put Wily on the classpath when starting Tomcat if not "%ACTION%" == "start" goto skipWilyVars set WILY_HOME=S:\sw\apache\tomcat\5. you do not need to restart your Java Agent. Editing the startup script To ensure the Java Agent starts with the Apache Tomcat application server.bat file. usually located in the <tomcat_root>/bin directory. Open the catalina.introscope.Configuring Apache Tomcat 3. Save the Tomcat -PBD.agent.wily. dirs="%JAVA_ENDORSED_DIRS%" -classpath "%CLASSPATH%" -Dcatalina. Save the catalina.bat file.2x.Configuring JBoss ::Comment out the original start command ::%_EXECJAVA% %JAVA_OPTS% %CATALINA_OPTS% %DEBUG_OPTS% -Djava. You must configure JBoss for Introscope and deploy web application support for JBoss. This functionality requires Introscope 8. the Introscope service is deployed as a stand alone XML service descriptor. 4.io. It is compatible with JBoss 4. and 5.0.0.tmpdir="%CATALINA_TMPDIR%" %MAINCLASS% %CMD_LINE_ARGS% %ACTION% ::Print the command line before executing it echo About to execute command: %_EXECJAVA% %WILY_ARGS% %WILY_OPTS% %JAVA_OPTS% %CATALINA_OPTS% %DEBUG_OPTS% -Djava.jar -Dcom.5 or higher set JAVA_OPTS= -javaagent:%JBOSS_HOME%\wily\Agent.io. there are further configurations you must perform to enable the reporting of JBoss JMX metrics to Introscope.introscope.tmpdir="%CATALINA_TMPDIR%" %MAINCLASS% %CMD_LINE_ARGS% %ACTION% %_EXECJAVA% %WILY_ARGS% %WILY_OPTS% %JAVA_OPTS% %CATALINA_OPTS% %DEBUG_OPTS% -Djava.2.endorsed. Modify the run.home="%CATALINA_HOME%" -Djava.0 or higher.tmpdir="%CATALINA_TMPDIR%" %MAINCLASS% %CMD_LINE_ARGS% %ACTION% 3.dirs="%JAVA_ENDORSED_DIRS%" -classpath "%CLASSPATH%" -Dcatalina. To configure JBoss for Introscope: 1.dirs="%JAVA_ENDORSED_DIRS%" -classpath "%CLASSPATH%" -Dcatalina.agentProfile=%JBOSS_HOME%\wily\IntroscopeAgent.0. Configuring JBoss If you installed the Java Agent on a JBoss system.base="%CATALINA_BASE%" -Dcatalina.wily.bat file in the bin directory of your JBoss installation by adding the following: rem ===================================================================== rem Enable Introscope rem ===================================================================== rem Use this for Java 1.base="%CATALINA_BASE%" -Dcatalina.home="%CATALINA_HOME%" -Djava.endorsed. 4.base="%CATALINA_BASE%" -Dcatalina.endorsed.io.home="%CATALINA_HOME%" -Djava.profile %JAVA_OPTS% Chapter 6: Deploying the Java Agent on other application servers using JVM AutoProbe 105 . When deploying web application support for JBoss.3 SP1. use this rem set JAVA_OPTS= -Xbootclasspath/p:%JBOSS_HOME%\wily\connectors\AutoProbeConnector. Save the IntroscopeAgent. Save the run.jmx.0 from previous versions of Introscope where the use of the platform-specific MBeanServer was set in the command line. If not. place the file in the appropriate directory. 4.profile located in the <Agent_Home>\wily directory and set the following property: introscope. This reflects a change in 9. 2.platform. located in the <Agent_Home>\wily directory of your Java Agent installation.wily.jar file. To deploy web application support for JBoss: 1. located in the <Agent_Home>/wily/deploy directory. 106 Java Agent Guide .agent.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. 2. If not. Place the introscope-jboss-service.mbeanserver=true to the IntroscopeAgent. place the file in the appropriate directory. Open the IntroscopeAgent.%JBOSS_ HOME%\wily\Agent.jar.bat file.profile.Configuring JBoss rem Otherwise.wily. in to the /server/default/lib directory of your JBoss installation.xml file. If not. in to the /server/default/deploy directory of your JBoss installation Note: This path assumes you are using the default configuration. Note: This path assumes you are using the default configuration.jar -Dcom.introscope.profile %JAVA_OPTS% rem======================================================================= Note: The above assumes you installed the Java Agent in the root directory of your JBoss installation. you should add com.use.profile. 3. Place the WebAppSupport.agentProfile=%JBOSS_HOME%\wily\IntroscopeAgent. modify the file paths accordingly. -javaagent:<PathToAgentJar> -Dcom.headless=true -Dhttp. that is managed by the Oracle Console. Insert the following at the end of this line. Note: Make sure to enter the appropriate path for your environment.policy=$ORACLE_HOME/j2ee/home/config/java2.introscope.pbd jboss-full. The entire entry would be on one line: <data id="java-options" value="-server -XX:MaxPermSize=128M -ms512M -mx1024M -XX:AppendRatio=3 -Djava.policy -Djava.pbd jsf.xml file for the application you want to instrument.enable=false -javaagent:$ORACLE_HOME/wily/Agent. Locate the section in the opmn.awt. This file is usually called opmn. Use these files to tailor your JBoss data collection: ■ ■ ■ ■ ■ ■ jboss4x. before the end "/>. and therefore every JVM.xml. You will most likely want to instrument more than one application at this time.pbd jsf-toggles-typical. 3.Configuring Oracle Application Server 10g JBoss PBDs and PBLs When you install the Java Agent on a JBoss application server. JBoss-specific PBDs and PBLs are installed in the <Agent_Home>\wily directory.wily.xml file.xml. To deploy JVM AutoProbe on OAS 10g: 1. there is a section called <data id="java-options". 2.introscope.pbl Configuring Oracle Application Server 10g Oracle Application Server (OAS) uses one configuration file for the management of every application.webdir. Under <category id="start-parameters"> for your selected application.agentProfile=$ORACLE_HOME/wily/IntroscopeAgent. Shut down your application server and make a backup of opmn.security.jar -Dcom.profile/ > Chapter 6: Deploying the Java Agent on other application servers using JVM AutoProbe 107 .pbd jsf-toggles-full.pbl jboss-typical.wily.agentProfile=<PathToAgentProfile> The following is an example of a changed application section in the opmn. profile as jvm-options to the java-config element in the domain.agentProfile=/sw/wily/IntroscopeAgent.Configuring GlassFish 2.\j2ee\cluster\instance.wily.... select VM Parameters > System.1 GlassFish is an open source application server project led by Sun Microsystems for the J2EE platform. Click the Additional tab and create a new parameter. 3. 2. 7. Copy the WebAppSupport.jar file and the wily/IntroscopeAgent. Configuring SAP Netweaver 7. In GlassFish.profile 5..JavaParameters. 4.jar value: <leave empty> 6. 8..bat). open the following file: <drive>:\usr\sap\.. and confirm that it contains the information you entered above..> 3...introscope.introscope.. To configure GlassFish 2.wily.1: 1.. for example: name: -javaagent:<Agent_Home>\wily\Agent. For example: <java-config .. For example: name: com. Start the SAP Configtool (configtool.> <jvm-options>-javaagent:/sw/wily/Agent.jar</jvm-options> <jvm-options>-Dcom. Save your changes. Start the application server. open the domain.1 Configuring GlassFish 2....xml file. In the right pane. 2.prof ile</jvm-options> .jar from the <Agent_Home>/wily root directory to the <Agent_Home>/wily/ext directory. Restart the SAP server. Select an instance to modify. 108 Java Agent Guide . To verify that the changes made with the Configtool were made.agentProfile value: <Agent_Home>/wily/IntroscopeAgent.1 To configure JVM AutoProbe for NetWeaver 7.xml file. Create a new parameter (without providing -D). 4. located at /appserver-install-dir/domains/domain1/config/ Add the full path for the wily/Agent. Find the line beginning with ID<server_id>.1 for Introscope: 1.properties 9. ■ ProbeBuilder List (PBL) files A ProbeBuilder List (PBL) file contains a list of multiple PBD filenames. the relevant PBD and PBL files for your specific application server are placed in the <ApplicationServer_Home>/wily directory when you install the Java Agent. to instrument an application. Introscope includes a set of default PBD files.profile. PBLs. Placing other characters (such as Unicode characters) in PBDs or PBLs could result in problems with AutoProbe. such as timers and counters. Default PBL files (see page 114). This section contains the following topics: ProbeBuilder Directives overview (see page 109) Using the IntroscopeAgent.Chapter 7: ProbeBuilder Directives This section describes how to create and modify ProbeBuilder Directives. There are two kinds of files used to specify ProbeBuilder Directives: ■ ProbeBuilder Directive (PBD) files A ProbeBuilder Directive (PBD) file contains directives used by ProbeBuilder to instrument your applications. Note: All metrics are calculated using the time set by your system clock. Different PBL files can refer to the same PBD files. Important: PBDs and PBLs only support ASCII characters. If you are using Introscope AutoProbe. You can also create custom Introscope PBD files to track any classes or methods to obtain specific information about your applications. and Creating advanced custom tracers for more information. the elapsed time reported for that transaction may be misleading. Chapter 7: ProbeBuilder Directives 109 . This determines which metrics the agents report to the Enterprise Manager. If the system clock is reset during a transaction. PBD files govern what metrics your agents report to the Introscope Enterprise Manager. See Default PBD files (see page 111). and PBDs together (see page 129) Applying ProbeBuilder Directives (see page 129) Creating custom tracers (see page 132) Using Blame Tracers to mark blame points (see page 143) Supplementary directives and tracers information (see page 146) ProbeBuilder Directives overview ProbeBuilder Directive (PBD) files tell the Introscope ProbeBuilder how to add probes. or to experience a "hang". For more information about adding skip directives to your custom PBD files. 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. causing the Java Agent to start incorrectly.ProbeBuilder Directives overview Components traced by the default PBDs The default Introscope PBD files implement tracing of the following Java components: ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ Oracle JDBC JSP Tag Libraries JSP IO Tag Libraries JSP DB Tag Libraries Struts Servlets Java Server Pages (JSPs) Enterprise JavaBeans (EJBs) Java Database Connectivity (JDBC) Network Sockets Remote Method Invocation (RMI) Extensible Markup Language (XML) Java Transaction API (JTA) Java Naming and Directory Interface (JNDI) Java Message Service (JMS) Common Object Request Broker Architecture (CORBA) User Datagram Protocol (UDP) File Systems Threads System Logs Thrown and Caught Exceptions (off by default) Occasionally. skipping the classes that may have caused the problem. If this happens. see Skip directives (see page 68). too many Java classes are selected for monitoring in a ProbeBuilder Directive (PBD) file. 110 Java Agent Guide . appmap-ejb.pbd This file provides tracer directives for application triage map instrumentation. appmap-soa.pbd This file provides tracer groups for common Java Enterprise Edition components. only front.pbd These directives tell ProbeBuilder to not instrument Apache Derby implementation classes.ProbeBuilder Directives overview Default PBD files The Java Agent includes the following default PBD files: appmap. di. See the CA Wily SOA Performance Management Guide for more information. java2.and back-end errors are considered serious. Use either toggles-full. etc.pbd This file provides tracer directives for application triage map SOA instrumentation for SPM supported Java SOAP stacks.pbd This file provides tracer groups for common Java 2 components. Use either toggles-full.NET.pbd to TurnOn specific tracing.pbd or toggles-typical. bizrecording. Messaging. j2ee.pbd to TurnOn specific tracing.pbd or toggles-typical. biz-trx-http. errors. By default.pbd This file provide tracer definitions and directives to setup agent business recording.pbd This file configures Error Detector by specifying what code-level events constitute serious errors. Chapter 7: ProbeBuilder Directives 111 .pbd This file provides tracer directives for business-centric HTTP instrumentation. That is.). only errors that will be manifest as a user-facing error page or that indicate a problem with a backend system (ADO.pbd This file provides tracer directives for application triage map EJB instrumentation. Comment or uncomment the TurnOn directives to alter the set of Oracle JDBC components that are traced.ProbeBuilder Directives overview jsf.pbd.pbd file.1. Most tracer groups are turned on.pbd This file provides instrumentation settings for Introscope LeakHunter. sqlagent-6.1.pbd This is the configuration file for SQL Agent instrumentation summary metrics.pbd This file provides tracers for the SiteMinder Web Agent Introscope plugin.pbd This file provides on/off switches in the form of TurnOn directives for the tracing provided in the jsf. sqlagent.pbd This is the configuration file for SQL Agent instrumentation.pbd This is the configuration file for SQL Agent instrumentation if you want to view JDBC metrics in the trace directive metric resource name. part of the CA SOA Security Manager (SOA Agent for Web Server and Application Server). jsf-toggles-full.pbd This file is used to enable the servlet header decorator. sql-agent-summary-metrics-6. oraclejdbc. ServletHeaderDecorator. which is part of the integration with CA Wily CEM. Always use this PBD file when using the sqlagent-6.pbd This file provides on/off switches in the form of TurnOn directives for the tracing provided in the jsf. smwebagentext. In most cases you will not need to modify the contents of this file. jvm.pbd This file provides directives which implement support for various Java Virtual Machines.pbd This file provides tracer groups for Java Server Face (JSF) components.pbd This file provides tracers for TransactionMinder Agent. which give high level metrics for JDBC.1. soaagent. jsf-toggles-typical. 112 Java Agent Guide .pbd This file provides tracer groups for Oracle JDBC components. leakhunter.pbd. a leak detection utility. It is intended to be used with the Introscope default files. pbd This file provides on/off switches in the form of TurnOn directives for the tracing provided in other directives files. which vary depending on the application server you are monitoring. see Default tracer groups and toggles files (see page 114) and Turning tracer groups on or off (see page 125). Chapter 7: ProbeBuilder Directives 113 .1. See the CA Wily SOA Performance Management Guide for more information. as well as Jakarta I/O and DGTags tag libraries. webMethods pbds The Java Agent is installed with several PBDs related to monitoring webMethods through the Introscope SOA Extension For WebMethods. The Java Agent also installs application server-specific PBDs. Most tracer groups are turned on. toggles-full. toggles-typical. It is intended to be used with the Introscope default files. Only a small section of tracer groups are turned on.pbd This file provides directives necessary for JSP tracing.0 Introscope instances. summary-metrics-6. TIBCO pbd The Java Agent is installed with several PBDs related to monitoring TIBCO through the SOA extension.pbd This file provides directives that monitor classes which should be traced as JSP tag libraries.ProbeBuilder Directives overview struts. see Default tracer groups and toggles files (see page 114) and Turning tracer groups on or off (see page 125). For more information about turning tracers on or off.pbd This file provides directives which monitor Apache struts. See the CA Wily PowerPack for WebSphere MQ User Guide for more information. WebSphere MQ pbds The Java Agent is installed with several PBDs related to monitoring WebSphere MQ connectors and messaging system through the PowerPack for WebSphere MQ.pbd This file provides on/off switches in the form of TurnOn directives for the tracing provided in other directives files. For more information about turning tracers on or off. See the CA Wily SOA Performance Management Guide for more information. taglibs. and EJB tracing in pre-7. Servlet tracing. pbl (default) References PBD files in which most tracer groups are turned on. The Java Agent also installs application server-specific PBLs. depending on how you configure the tracer groups. They cause the reporting of information about a set of classes. The typical set includes common settings. default-typical. For example. In PBD files.ProbeBuilder Directives overview Default PBL files There are two PBL files available with each agent: default-full. A tracer group consists of a set of tracers that is applied to a set of classes. tracer group information is referred to by the term flag. 114 Java Agent Guide . For example. Introscope uses this set by default to demonstrate full Introscope functionality. TraceOneMethodIfFlagged or SetFlag are defining tracer group information. You can refine the gathering of metrics on your systems by turning on or off certain tracer groups. there are tracer groups which report the response times and rates for all RMI classes.pbl A subset of tracer groups in the referenced PBD files are turned on. which vary depending on the application server you are monitoring. This affects overhead usage. Default tracer groups and toggles files Tracer groups are defined in PBD files. either increasing or decreasing it. and is the set you can customize for a particular environment. 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 Chapter 7: ProbeBuilder Directives 115 .ProbeBuilder Directives overview Tracer groups are modified in the toggles-full.pbd files.pbl and default-typical.pbl files.pbd and the toggles-typical. which are referred to by the default-full. 0 Configuration Full: on Typical: on EntityBean3Tracing Entity EJB 3. turn on this tracer group: HTTPAppServerAutoProbeServletTracing.0 Configuration Full: on Typical: on EJB3StubTracing EJB 3. InstanceCounts Counts number of instances of object type identified with tracer group. 116 Java Agent Guide . Full: on Typical: on Nothing will be traced until classes are identified with this tracer group.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.ProbeBuilder Directives overview EJB2StubTracing EJB 2. ProbeBuilder Directives overview 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 Chapter 7: ProbeBuilder Directives 117 . ProbeBuilder Directives overview 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. Full: on Typical: on 118 Java Agent Guide .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. NIODatagramSummaryTracing Generates a single set of metrics measuring all NIO datagram activity. as well as some internal NIO sockets which are always excluded from NIODatagramTracing metrics. NIODatagramTracing Generates a set of metrics for each datagram "connection". Full: on Typical: on See NIODatagramTracing metrics on page 269 for more information. Full: on Typical: on Included in these metrics are connections that were excluded from NIODatagramTracing metrics by agent properties. 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 Chapter 7: ProbeBuilder Directives 119 . as well as some internal NIO sockets which are always excluded from NIOSocketTracing metrics.ProbeBuilder Directives overview 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. ProbeBuilder Directives overview 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 120 Java Agent Guide . 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 Chapter 7: ProbeBuilder Directives 121 .ProbeBuilder Directives overview ThreadPoolTracing Thread Pool Configuration Full: on Typical: on UDPTracing Network socket bandwidth Full: on Typical: on UnformattedSessionTracing HTTP Session Configuration Full: on Typical: on EJB3MethodLevelTracing EJB 3. ProbeBuilder Directives overview JAXMListenerTracing JAXM message sends Full: on Typical: off JNDITracing JNDI lookup times Full: on Typical: off 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 122 Java Agent Guide . ProbeBuilder Directives overview 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 Chapter 7: ProbeBuilder Directives 123 . 0 supports EJB 2. Tracer groups can be modified in the toggles files by: ■ ■ Turning on/off tracer groups to save on system overhead Adding classes to a tracer group Tracer groups report information only when turned on (uncommented) and are activated with the keyword TurnOn. Turn on or off the tracer groups associated with EJB 2.0 or 3. the default toggles PBD files should not be edited.0 and 3. However. Note: The Java Agent 9.0 instrumentation. you can refine the gathering of metrics by turning on or off certain tracer groups.ProbeBuilder Directives overview 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. Message Driven beans are not supported yet. Support for EJBs in the application triage map extends only to Session and Entity beans. 124 Java Agent Guide .0 to tailor your metric collection. TurnOn: HTTPServletTracing 2. To turn a tracer group off: ■ Comment the tracer group by placing a pound sign at the beginning of the line. and uncomment the line by removing the pound sign from the beginning of the line.ProbeBuilder Directives overview Setting toggles to gather additional metric information The following toggles. To turn a tracer group on: 1.pbl is in use by AutoProbe or the Java Agent).pbl or <appserver>-typical. Locate the tracer group to turn on. You must add these toggles to your full or typical toggle file to change the configuration. as in the following example: #TurnOn: HTTPServletTracing Chapter 7: ProbeBuilder Directives 125 . when turned on. These files are found within the <appserver home>/wily directory or <Introscope_Home>/config/systempbd directory. cause the collection of additional metrics across all APIs for CA Technologies-provided tracer groups that are enabled. Locate the toggles-full.pbd or toggles-typical. and will cause the tracing of all HTTP Servlets. Note: Any uncommented (turned on) directive for a tracer group causes the tracer group to be used. The directive in the following example is turned on.pbd file (depending on which file type (<appserver>-full. DefaultStalledMethod Tracing Stalled method tracing Full: on Typical: on DefaultConcurrentInvocationTracing Concurrent invocation information Full: on Typical: off DefaultRateMetrics Invocation rate metrics Full: off Typical: off Turning tracer groups on or off You can refine the gathering of metrics on your systems by turning on or off certain tracer groups. entity and session EJB-related directives add probes only for EJBs that directly and explicitly implement the entity.bean.myCo. an application’s EJBs are subclasses of classes which directly and explicitly implement the entity or session EJB interface. For EJB subclasses to be tracked by Introscope.bean.ancestor.myEJB1 EntityBeanTracing The identify keywords are: ■ ■ ■ IdentifyInheritedAs IdentifyClassAs IdentifyCorbaAs For a list of identify keywords.ancestor. These are not tracked by default by Introscope. to add the class.ancestor.ejbentity. com.ProbeBuilder Directives overview Adding classes to a tracer group You can turn on tracing for a particular class by adding the class to an existing tracer group.bean. EJB subclass tracing By default.bean.class> with the fully-qualified class name of the immediate ancestor of the EJBs to be instrumented.ancestor. To identify a class as being part of a tracer group.class> or <session.myCo.ejbentity. To do this. use one of the Identify keywords. add entries that refer to the direct ancestors of the EJB subclasses to be tracked. EntityBeanTracing: IdentifyClassAs: com. Often. they must be added to the appropriate tracer group. For entity EJBs: IdentifyInheritedAs: <entity. or message-driven EJB interfaces. replace <entity. For example. to the tracer group.class> SessionBeanTracing 126 Java Agent Guide .myEJB1. From these models. see Supplementary directives and tracers information (see page 146).class> EntityBeanTracing For session EJBs: IdentifyInheritedAs: <session. session. ProbeBuilder Directives overview The examples below are based on this class hierarchy: mySessionEJB implements javax. You must then add a matcher class to examine your bytecode to determine if a class contains a given annotation.0 tracers for more specific things.0 classes.0 annotations The following directive allows you to group any class containing the given class-level annotation into tracer groups.0 session and entity beans. SessionBeanTracing. create a directive class and directive parser class for the new directive.SessionBean mySessionEJBsubclass1 extends mySessionEJB mySessionEJBsubclass1a extends mySessionEJBsubclass1 mySessionEJBsubclass1b extends mySessionEJBsubclass1 mySessionEJBsubclass2 extends mySessionEJB The tracer group.0 and 3.0 support for the application triage map Introscope 9. specifically for use in the Workstation application triage map.0 and 3. EJB 2. See Supplementary directives and tracers information (see page 146) for more information.ejb. If your code is in a package. as the out-of-the-box functionality may be too broad. IdentifyInheritedAs: mySessionEJBsubclass1 SessionBeanTracing Note: This example does not use packages. use this directive: IdentifyAnnotatedClass <annotation-name> <flag-name> To use this directive. but instead are entirely enabled via annotations. it is best that you configure EJB 2.0 specifications do not explicitly implement any well-known interface. CA Technologies recommends using this out-of-the-box functionality in test environments only. Chapter 7: ProbeBuilder Directives 127 . causes the tracking of mySessionEJB: The following tracer traces mySessionEJBsubclass1 and mySessionEJBsubclass2. Note: This directive does not support method-level annotations. To easily identify EJB 3. IdentifyInheritedAs: mySessionEJB SessionBeanTracing The following tracer traces mySessionEJBsubclass1a and mySessionEJBsubclass1b.0. This directive supports EJB 3. If deploying this functionality to your production environments. it needs to include the package name with the class name. EJBs conforming to the 3.0 supports out-of-the-box tracing of EJB 2.0 and 3. as this configuration affects the start-up time of the agent. EJB 3. 0 introduces a new way to name called backends.EntityBean EntityBeanTracing javax. Use the EjbNameFormatter classes to define an EJB-related metric name.0 application triage map support.Remote EJB3StubTracing EJB naming Introscope 9. {interface}.ejb.0 client stubs and bean implementations.ejb. the following directive has been added to the j2ee. {interface}.pbd file: IdentifyDeepInheritedAs: IdentifyDeepInheritedAs: IdentifyDeepInheritedAs: IdentifyDeepInheritedAs: javax.pbd: IdentifyInheritedAnnotatedClassAs: javax. For EJB 3.0 application triage map support. or through a super interface.ejb. and {method} For EJB beans: {classname}.ejb. The name formatter allows you to configure a suitable name for EJB 2. the following additional directive is set in j2ee. or implementing. and {method} 128 Java Agent Guide .MessageBean MessageBeanTracing These directives allow the ProbeBuilder to identify the EJB stubs on the client side.ProbeBuilder Directives overview Use the following directive to instruct ProbeBuilder to flag a class that is inheriting from. {bean}. the superclass or interface: IdentifyDeepInheritedAs For EJB 2. application triage map application name.SessionBean SessionBeanTracing javax.EJBObject EJB2StubTracing javax. and monitored components that deal with EJBs. generic frontends.ejb. or node name using following place holders: ■ ■ For EJB client stubs: {classname}. and beans on the server side to be used in the application triage map. the following directives have been added the j2ee. In the context of the application triage map.pbd file: IdentifyInheritedAnnotatedClassAs The directive matches all classes that implement interfaces directly.0 and 3. BackendTracer com.wily. and PBDs together When the Java Agent is first installed. PBLs.pbl (see Default PBL files (see page 114) for more information).agent.trace. CA Technologies recommends you use JVM AutoProbe to implement your PBDs. you could modify existing tracer directives to use a more appropriate name.pbd and appmap-ejb.pbl and default-full.wily.pbd files.ejb. For example. This is an internal Introscope tracer for the EJB 2. you set an instrumentation level. # 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}" .0 beans..Using the IntroscopeAgent.0 bean name formatter.introscope.wily..introscope. and PBDs together The out-of-the-box following metric names are used: ■ ■ ■ ■ ■ EJB Bean frontend: EJB|{interface} EJB Client stub backend: EJB|{interface} Application triage map owner name for EJB bean: {interface} Application triage map node name for EJB Client Stub: Client {interface} Application triage map node name for EJB Bean: Server {interface} These are out-of-the-box EJB name formatters.profile. but keep the same flags: . They are used in the j2ee.probebuilder.Ejb2StubNameFormatter Note: The EJB context tracer is set on setContext() method of EJB 2. Applying ProbeBuilder Directives The way in which you apply PBDs depends on the method you choose to use. but different metric names. Chapter 7: ProbeBuilder Directives 129 .. You will use the same name formatters..trace.profile.agent. This setting refers to the ProbeBuilder List (PBL) files default-typical. Using the IntroscopeAgent. SetTracerClassMapping: EJB2BackendTracer com. which allows the name formatter to function correctly.introscope.validate. You can also use the ProbeBuilder Wizard or the command line ProbeBuilder to implement your PBDs.ResourceNameValidator SetTracerParameter: EJB2BackendTracer nameformatter com. either full or typical. PBLs. Using the ProbeBuilder Wizard or command-line ProbeBuilder When you are ready to implement a PBD file. The Command-line ProbeBuilder looks for any custom directive files in the same directory where ProbeBuilder is run from. The steps to implement ProbeBuilder Directives using the ProbeBuilder Wizard or command-line ProbeBuilder are the same as using JVM AutoProbe. See Using JVM AutoProbe (see page 130) for more information. be sure to map the file path to the correct directory. this is the <Agent_Home>/wily directory). Save the IntroscopeAgent. 4.profile file (by default. 3. Note: If you have enabled dynamic instrumentation. your applications must be instrumented using the latest PBDs.profile. AutoProbe resolves file names relative to these directories.profile. To implement PBDs using AutoProbe: 1. The Command-line ProbeBuilder resolves file names relative to these directories. If you have moved the location of your wily directory. This process varies depending on the ProbeBuilding method you use.Applying ProbeBuilder Directives Using JVM AutoProbe When you are ready to implement a PBD file. 2. and the <Agent_Home>/wily/hotdeploy directory. For more information about dynamic instrumentation. and the <Agent_Home>/wily/hotdeploy directory. Instrumenting with new and changed PBDs For new or changed directives to take effect. Any PBDs added to this directory will be implemented without having to update or modify the introscope. Restart the application. 130 Java Agent Guide . add it to the hotdeploy directory.directivesFile property in the IntroscopeAgent. AutoProbe looks for PBD files in the directory that contains the IntroscopeAgent. Copy custom PBDs into the <Agent_Home>/wily/hotdeploy directory. the PBDs in the hotdeploy directory are picked up live from the folder —no reboot is required.autoprobe. add it to the hotdeploy directory. Save modified standard PBD or PBLs to the <Agent_Home>/wily directory. see Dynamic ProbeBuilding (see page 68). If they are not already running. To use the command-line ProbeBuilder: 1. If your managed applications are not running when you add or change directives. the managed application classes. 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 130). they will be instrumented using the updated directives. Chapter 7: ProbeBuilder Directives 131 . Configure the application to use the new files. 4.Applying ProbeBuilder Directives JVM 1. see Using the ProbeBuilder wizard (see page 356). For more information on running ProbeBuilder Wizard. 5. Stop your managed application. 3. when you next start the applications. For instance. start the Enterprise Manager and the Workstation. a redeploy is sufficient. Pre-JVM 1. Select the custom directives files to use. supplying the custom PBD and PBL files in the command line. How you cause the classes to reload depends upon the application server you use. If your managed applications are running. see Using the command-line ProbeBuilder (see page 358). Using the command-line ProbeBuilder Important: CA Technologies recommends using the command-line ProbeBuilder as your last option for Introscope-enabling your latest PBDs. This enables you to perform PBD corrections. 2. For more information on the command-line ProbeBuilder. allowing changed PBDs to take effect without application or Java Agent restart.5 systems or installations using –Xbootclasspath New and changed ProbeBuilder Directive files or ProbeBuilder List files take effect the next time the application server loads the application classes. Run the command-line ProbeBuilder or the ProbeBuilder Wizard. or reload.40. Using the ProbeBuilder Wizard To use the ProbeBuilder Wizard: 1. on SAP NetWeaver 6. Start the managed application. 2.5 systems using JVM AutoProbe via -javaagent You can configure dynamic instrumentation. For more information see Dynamic ProbeBuilding (see page 68). or perform triage-driven instrumentation without interrupting application service. it is necessary to load. Most application servers require a restart. or a count) The fully-qualified metric name (including the resource path) under which to present this information Custom PBDs are stored in the <Agent_Home>/wily/hotdeploy directory. To write custom tracers. require the use of specific syntax and keywords. For more information about dynamic instrumentation.directivesFile property in the IntroscopeAgent. If you have enabled dynamic instrumentation.profile. This tracer generates five separate metrics for associated methods or classes: ■ ■ ■ ■ ■ Average Response Time (ms) Concurrent Invocations Errors Per Interval Responses Per Interval Stall Count 132 Java Agent Guide . save them to SmartStor. the PBDs in the hotdeploy directory are picked up live from the folder — no reboot is required. Introscope treats it as if it is an out-of-the-box PBD. You can set alerts on the metrics created. as more methods traced means more overhead. a rate. by creating tracers to track application specific measurements. Any PBDs added to this directory will be implemented without having to update or modify the introscope.Creating custom tracers Creating custom tracers You can further refine your metric collection by creating custom PBD files. Once a custom PBD is created. see Dynamic ProbeBuilding (see page 68). Note: Be sure to choose methods to trace carefully. Creating custom directives.autoprobe. you must define: ■ ■ ■ ■ The directive type (indicating generically how many class(es) or method(s) to trace) The specific class(es) or method(s) to trace The type of information to trace in the class(es) or method(s) (for example. Using a custom BlamePointTracer tracer for common metrics A BlamePointTracer is the most commonly used tracer. or use them in the creation of custom dashboards in the Introscope Workstation. a time. For Introscope to recognize and process your tracers. in the following format: <directive>: [arguments] where [arguments] is a list. you must use a specific syntax when constructing custom tracers. Arguments used in trace directives include <Tracer-Group>.Catalog. PBD files contain tracer definitions. TraceOneMethodOfClass: petshop. and <metric-name>. Note: Depending on the directive used.Catalog search BlamePointTracer "PetShop|Catalog|search" Directive names and arguments used in tracer syntax In addition to simple keywords that associate tracers into groups or enable/disable groups. A tracer is composed of a directive and information about the method or class to trace. <Tracer-name>. and is directive-specific. <class>. <method>. A BlamePointTracer has been set for a method called search in class petshop.Creating custom tracers The following is an example of a BlamePointTracer. Chapter 7: ProbeBuilder Directives 133 .catalog.catalog. PetShop|Catalog|search is the name of the node under which the BlamePoint metrics will be displayed in the Introscope Investigator. only a subset of these parameters are required. 134 Java Agent Guide . Fully qualified classes include the full assembly name of the class as well as the name. TraceAllMethodsIfInherits—traces all methods in all direct subclasses or direct interface implementations of the specified class or interface.myassembly. Note: Only concrete. TraceAllMethodsIfFlagged—traces all methods if the specified class is included in a tracer group that has been enabled with the TurnOn keyword. for example: [MyAssembly]com. An abstract method specified in a custom tracer results in no metric data being reported. TraceOneMethodIfFlagged—traces one method if the specified class is included in a tracer group that has been enabled with the TurnOn keyword.Int32). TraceOneMethodIfInherits—traces one method in all direct subclasses or direct interface implementations of the specified class or interface. For example.Void([mscorlib] System. MyMethod) OR the full method signature with return type and parameters (for example.mycompany. see Signature differentiation (see page 138).) <Tracer-name> Specifies the tracer type to be used.Creating custom tracers <directive> There are six main directives available for custom tracing: ■ ■ ■ ■ ■ ■ TraceOneMethodOfClass—traces a specified method in the specified class.MyClass The assembly name must be enclosed in [] brackets. myMethod. For more information on method signatures.g. metric-name—the metric appears immediately inside the agent node. TraceAllMethodsOfClass—traces all methods in the specified class. <Tracer-Group> The group to which the tracer is associated. The following examples describe three ways to specify the name and location of a metric at different levels of the metrics tree. implemented methods can be traced and report metric data while running. <class> A fully qualified class or interface name to trace. <method> The method name (e. See the Tracer name table below for descriptions of tracer names.[mscorlib]System. <metric-name> Controls how the collected data is displayed in the Introscope Workstation. BlamePointTracer. in the Investigator tree.Creating custom tracers resource:metric-name—the metric appears inside one resource (folder) below the agent node. <metric-name>. the View pane in the Investigator). BlamePointTracer Provides a standard set of metrics including average response time. stalls. The exception stack trace thrown by the Dump Stack Tracer is not a true exception—it is a mechanism for printing the method stack trace. PerIntervalCounter Number of invocations per interval. DumpStackTraceTracer Dumps a stack trace to the instrumented application's standard error for methods to which it is applied. Commonly used tracer names and examples The following list describes the most commonly used tracer names and what they trace. The result is reported under the metric name specified in the tracer. in the metrics tree. <metric-name>. An example use of this tracer would be counting the number of simultaneous database queries. Note: This tracer requires a platform monitor on the supported platform . and errors for a blamed component. Use pipe characters (|) to separate the resources.2 or RedHat Enterprise Linux 3. in the Investigator tree.0. concurrency. It is strongly recommended that this tracer only be used in a diagnostic context where a sharp increase in overhead is acceptable. MethodCPUTimer Average CPU time (in milliseconds) used during method execution and reports it under <metricname> in the metrics tree. It is reported under the metric name specified in the tracer.either AIX 5. resource|sub-resource|sub-sub-resource:metric-name—the metric appears more than one resource (folder) level deep below the agent node. Chapter 7: ProbeBuilder Directives 135 . per interval counts. MethodTimer Average method execution time in milliseconds and reports it under the metric name specified in the tracer. This interval will change based on the view period of the consumer of the data (for example. <metric-name>. ConcurrentInvocationCounter Reports the number of times a method has started but not yet finished. This feature is useful for determining callpaths to a method. Warning: This feature imposes heavy system overhead. catalog. Average tracer example This tracer tracks the average execution time of the given method in milliseconds. For example.Catalog search BlamedMethodTimer "Petstore|Catalog|search:Average Method Invocation Time (ms)" 136 Java Agent Guide . When using spaces in your custom metric names. and all spaces in metric names must be contained within quotes.petstore. You cannot use an open square brackets ([) as part of the Java class file name. This causes the custom tracers to malfunction. In the following example. 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 Warning: Introscope will not monitor classes having invalid class file names. When Introscope encounters such classes having invalid class names. you must use quotes around the whole metric name. quotes ("") are used around the metric names. CA Technologies highly recommends putting quotes around all metric names when you create custom metric names. For example: Correct IdentifyClassAs: MyClass MyTracers Incorrect IdentifyClassAs: "MyClass" MyTracers If you create a metric name that contains a class name. Metric names are allowed to have spaces. Important: Do not place quotes around class names.sun. TraceOneMethodOfClass: com. The following sections are examples of method tracers. CA Technologies recommends putting quotes ("") around all metric names. in the class file name: org/jboss/seam/example/seambay/AuctionImage$JaxbAccessorM_getData_setData_[B: the _[B: cause the class file name to be invalid.Creating custom tracers Using quotes in custom tracer definitions Custom tracers can contain metric names with spaces in them. it fails to instrument them and reports them as an error message in the agent logs. petstore. and sets of classes.LogoutEJB logout "Petstore|Account:Logged In Users" Advanced single-metric tracers Directives and tracers track methods.petstore. Chapter 7: ProbeBuilder Directives 137 .account. Single-metric tracers can be created in several ways: through the method signature.sun. and reports this rate under the specified metric name. by substituting keywords.Creating custom tracers Rate tracer example This tracer counts the number of times the method is called per second. TraceOneMethodOfClass: com.petstore.ShoppingCart placeOrder BlamedMethodTraceIncrementor "Petstore|ShoppingCart|placeOrder:Total Order Count" Combined counter tracers example These tracers combine incrementor and decrementor Tracers to keep a running count. classes.petstore. A single-metric tracer reports a specific metric for a specific method.LoginEJB login "Petstore|Account:Logged In Users" com.Catalog search PerIntervalCounter "Petstore|Catalog|search:Method Invocations Per Interval" The interval is determined by the monitoring logic in the Enterprise Manager. or by manipulating the metric name parameters.petstore.sun.catalog. TraceOneMethodOfClass: com. TraceOneMethodOfClass: MethodTraceIncrementor TraceOneMethodOfClass: MethodTraceDecrementor com.cart.sun. such as the Graph frequency.sun.account.Catalog search BlamedMethodRateTracer "Petstore|Catalog|search:Method Invocations Per Second" Per interval counter tracer example This method tracer counts the number of times the method is called per interval. Counter tracer example This tracer counts the total number of times the method is called. TraceOneMethodOfClass: com.sun. which is the smallest unit that Introscope can track.catalog. The preview pane in the Investigator defaults to 15 second intervals. and reports the per interval count under the specified metric name. The parameters in the metric name in the tracer are substituted at runtime for the actual values into the metric name. This feature can be used with any directive. For example. For complete information about this format.)V traces the instance of the method with a string argument and void return type.Creating custom tracers 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. it will replace {packagename} with the string "<Unnamed Package>". see the Sun Java Virtual Machine Specification. Metric name keyword-based substitution Keyword-based substitution allows runtime substitution of values into the metric name. Keyword-based substitution: Example 1 If the metric name for a tracer in the pbd file is: "{packagename}|{classname}|{method}:Response Time (ms)" and the tracer is applied to method myMethod with a runtime class of myClass that is in package myPackage. {method} Name of the method being traced {classname} Runtime class name of the class being traced {packagename} Runtime package name of the class being traced {packageandclassname} Runtime package and class name of the class being traced Note: If Introscope processes a class which does not have a package. myMethod(Ljava/lang/String. the resulting metric name would be: "myPackage|myClass|myMethod:Response Time (ms)" 138 Java Agent Guide . This is accomplished by substituting the value of parameters for placeholder strings in the metric name.pbd file of "{packageandclassname}|{method}:Response Time (ms)" was applied to the same method. Chapter 7: ProbeBuilder Directives 139 .Creating custom tracers Keyword-based substitution: Example 2 If a tracer with a metric name in the . Any number of parameter substitutions can be used in any order. Object parameters other than strings should be used with caution because they are converted using the toString() method. between the package and class instead of the | in the first example. All parameters are converted to strings before substitution into the metric name. The placeholder strings to use are "{#}" where # is the index of the parameter to substitute. Warning: If you are unclear about what string the parameter will be converted to.myClass|myMethod:Response Time(ms)" Note the . The indices start counting at zero. the resulting metric name would be "myPackage. 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. do not use it in the metric name. using this format: TraceOneMethodWithParametersOfClass: <class-name> <method> <tracer-name> <metric-name> Parameters can be used in the metric name. either book or music. 140 Java Agent Guide . the Java Agent and fundamental Java classes and packages are skipped by AutoProbe or ProbeBuilder. see Supplementary directives and tracers information (see page 146). see the Directive & Tracer Type Definitions guide. see Supplementary directives and tracers information (see page 146). or methods can be skipped by AutoProbe or ProbeBuilder by using skip directives. Skip directives Certain packages. For more information on both keywords. with a method named process. The method has parameters for different kinds of orders. By default. You can create a tracer like this: TraceOneMethodWithParametersOfClass: order process(LJava/lang/string. For a complete list of skip directives used with the Java Agent. classes. For more information.Creating custom tracers Metric-name-based example A Web site uses a class named order. See Supplementary directives and tracers information (see page 146) for more information about this guide.)V MethodTimer "Order|{0}Order:Average Response Time (ms)" This tracer produces metrics like these: Order BookOrder ■ Average Response Time (ms) MusicOrder ■ Average Response Time (ms) You can also use the TraceOneMethodWithParametersIfInherits keyword. They can cause performance degradation so they are not turned on by default. and one that causes agent initialization when the application starts up (instead of when the first Probe is run). see Adding classes to a tracer group (see page 126)).Creating custom tracers Counting object instances The InstanceCounts tracer group counts the number of instances of the particular object types associated with it (for information on associating object types with the InstanceCounts tracer group using the standard IdentifyClassAs and IdentifyInheritedAs directives. To turn either of these on. Chapter 7: ProbeBuilder Directives 141 . Any instances explicitly allocated in your code will be counted. 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. Subtypes will also be counted. Exceptions The following directives are used to turn on tracing of exceptions either where thrown or caught. Tracing using this tracer group could potentially incur incremental performance (and memory) impact. depending entirely on the number of instances counted. any settings (such as tracer groups. the number of instances has to be quite large for an impact to be noticeable. InstrumentPoints. Note: CA Technologies testing has shown that in practice. Skips. Objects created through different mechanisms. such as deserialization or cloning. Turning on InstrumentPoint directives There are two types of directives identified by the keyword. Custom Method Tracers) turned on in any file take effect. might not be counted. InstrumentPoint: those that trace exceptions. InstrumentPoint: AgentInitialization If multiple ProbeBuilder Directive files are used. To instrument ClassC you must explicitly identify ClassC. follow the instructions in EJB subclass tracing (see page 126).5 JVMs. With a class cart and methods buyBook and buyCD. please see the Directive & Tracer Type Definitions document on the CA Wily community site. ClassB is also instrumented because it explicitly extends ClassA. In pre-1.5). For example. to ensure that subclasses are instrumented. This example creates a metric named Total Purchases. This is most commonly used with incrementors and decrementors. assume a class hierarchy in which ClassB extends ClassA. you can configure Introscope to instrument multiple levels of subclasses of a probed class. Likewise. you may need to use more specific tracers. For more information about directives and tracers for custom PBDs. Introscope does not instrument ClassC because ClassC does not explicitly extend ClassA. However.5 Java environments. 142 Java Agent Guide .Creating custom tracers Combining custom tracers You can use multiple tracers that affect the same metric. create the following tracers: TraceOneMethodOfClass cart buyBook PerIntervalCounter "Total Purchases" TraceOneMethodOfClass cart buyCD PerIntervalCounter "Total Purchases" This increments the metric Total Purchases when someone buys a piece of merchandise. classes that do not explicitly name a probed interface as being implemented. When subclasses of a probed class more than one level deep are loaded. (see page 72) If you wish to instrument a private method. even though they implement the interface indirectly. the new and overridden methods are not automatically instrumented.5. in effect combining them. like so: Interface/ClassA ClassB ClassC When you instrument ClassA. For instructions. Instrumenting and inheritance Introscope does not automatically instrument classes in the deeper levels of a class hierarchy in pre-1. If you run under JVM 1. and ClassC extends ClassB. see ProbeBuilding class hierarchies (JVM 1. will not be instrumented either. com/docs/books/tutorial/java/javaOO/annotations. The following sections describe how you can use tracers to explicitly mark the frontends and backends in your application. This information is also used in the Workstation application triage map to mark the edges of your applications. respectively.Using Blame Tracers to mark blame points Java 1. com. This capability. Chapter 7: ProbeBuilder Directives 143 . Classes containing the annotation name are identified.5 when creating custom metrics. see Configuring Boundary Blame (see page 195). For information about how Introscope determines frontends and backends. Using Blame Tracers to mark blame points Introscope’s Blame Technology works in a managed Java application to enable you to view metrics at the application tiers: the frontends and backends of your application.MyAnnotation is the annotation name. then use TraceAllMethodsIfFlagged directives to instrument the methods in the class. Blame Tracers Introscope provides tracers for capturing front and backend metrics: FrontendMarker and BackendMarker. For more information on Java annotations. For example: SetFlag: AnnotationTracing TurnOn: AnnotationTracing IdentifyAnnotatedClassAs: com. for instance code that accesses a backend.php/3556176 Use IdentifyAnnotatedClassAs to place the class in a tracer group. When creating your own annotations. You can use FrontendMarker and BackendMarker to instrument your own code.5 annotations Introscope 8. referred to as boundary blame. use a term in your code.MyAnnotation AnnotationTracing TraceAllMethodsIfFlagged: AnnotationTracing BlamePointTracer "Target|MyTarget|{classname}" In the example. and about options for configuring URL Groups to control how metrics for frontends are aggregated.6 annotations introduced in Java 1.html http://www.com/java/other/article.developer.test. see the following articles: ■ ■ http://java. allows users to triage problems to an application frontend or backend.test. These tracers explicitly mark a frontend and backend. to cause Introscope to capture and present metrics for custom components in the Investigator tree.0 and higher allows the use of Java 1.sun. which may call an EJB. For example. if you name the frontend tracer AppOne and the application triage map tracer refers to this tracer as APPONE. Note: When using frontend tracers.frontend. FrontendMarker and BackendMarker are instances of BlamePointTracer which provides metrics such as average response time. the PBD parameter is. information about AppOne will not be displayed correctly in the Workstation application triage map. It is useful to use BackendMarker: ■ ■ ■ to assign a desired name to an item that Introscope detects as a backend. this does not add to agent CPU overhead. see the Custom FrontendMarker directive (see page 145). the name of the application given in the frontend tracer must match the name given for the application triage map tracers. which calls a back-end.unless. only the first designated component will generate Frontend metrics. A typical transaction starts with a servlet. which Introscope sees as nested frontends. If no BackendMarker is configured. for native sockets that are called through the Java Native Interface (JNI).Using Blame Tracers to mark blame points If no components are instrumented with the FrontendMarker tracer (or its subclasses HttpServletTracer and PageInfoTracer). If the overhead is unacceptable.unless can be specified. For information on the PBD directive is. no frontend metrics are generated and no component will be marked as a frontend for transactions. It’s possible for servlets to call other servlets in a nested way. contact CA Support. deep transactions having nested frontend levels (for example 40 levels deep) may result in high CPU overhead. For example. A BlamePointTracer can be applied to middle components for a more granular Blame Stack. stalls. In most cases. to mark custom Java sockets that Introscope does not instrument. if a servlet repeatedly calls itself in a transaction (continuous recurring calls) or calls multiple other servlets. However. To prevent specific classes from being marked as frontend. High agent CPU overhead from deep nested frontend transactions Servlets are configured by Introscope to be seen as frontends.frontend. 144 Java Agent Guide . When more than one component within a transaction is instrumented with the FrontendMarker tracer (or its subclasses). Introscope will infer a backend —any component that opens a client socket will be a default backend if none is explicitly marked. to identify a Java/JNI bridging method as the backend. keeping in mind that both are case-sensitive. you may see an increase in agent CPU overhead. per interval counts. and errors for a blamed component. concurrency. ABCCorp. implement Boundary Blame Tracing. that are instrumented with a FrontendMarker named MyFrontendTracer.frontend.frontend.pbd and sqlagent.pbd.ABCCorp. such as HttpServletTracer) to not be marked as a frontend component. Any classes designated in the parameter list that are instrumented by the tracer to which this parameter is applied will not be designated as frontends and will not generate metrics under the Frontends node in the Introscope Investigator. Important: Class names should only be separated by a comma. but are not typically used in Introscope PBDs: ■ ■ ■ ■ BlamedMethodTimer BlamedMethodRateTracer BlamedMethodTraceIncrementor BlamedMethodTraceDecrementor Chapter 7: ProbeBuilder Directives 145 . not spaces.com. to prevent the classes NotAFrontend and AnotherNonFrontend from being treated as frontends in the package com. The following Blame Tracers used in previous versions of Introscope still exist.Using Blame Tracers to mark blame points Custom FrontendMarker directive Introscope 9. ■ ■ HttpServletTracer in j2ee. so a restart of the instrumented application server is required if the value of this parameter is changed. Use of spaces will invalidate the SetTracerParameter directive. The default is an empty list. PBD parameters are not dynamic. The second component would therefore be a better frontend marker. This may be useful when the initial component is a generic 'dispatcher' which forwards the request to a more specific component designed to handle the type of request received. For example. The parameter should be set as a comma-separated list of absolute class names.ABCCorp.AnotherNonFrontend Blame Tracers in standard PBDs Two of the standard PBDs provided with Introscope.NotAFrontend.unless.0 introduces the PBD parameter is. This parameter enables some classes instrumented by the FrontendMarker (or its subclasses. j2ee. you would use the following PDB directive: SetTracerParameter: MyFrontendTracer is.pbd is an instance of BackendMarker.unless com.pbd is an instance of FrontendMarker. SQLBackendTracer in sqlagent. jspa?categoryID=414&externalID=1927 ). see the Directive & Tracer Type Definitions Guide (https://community.net. make the following modification to oraclejdbc. 146 Java Agent Guide .pbd: In this portion of oraclejdbc. see Disabling Database Name Formatting in 7.wilytech. SocketTracing For more information. To enable Introscope to detect Oracle backends in the absence of SQL Agent. Supplementary directives and tracers information For a complete list of the tracers and directives used with the Introscope Java Agent.pbd: #Socket data from the Oracle driver reports too many metrics SkipPackagePrefixForFlag: oracle. your request for access will be denied. SocketTracing SkipPackagePrefixForFlag: oracle.com/entry!default. as shown below: #Socket data from the Oracle driver reports too many metrics #SkipPackagePrefixForFlag: oracle. SocketTracing comment out the skips. SocketTracing #SkipPackagePrefixForFlag: oracle.jdbc. Oracle databases are not detected based on the socket connection—SQL Agent must be available for Introscope to automatically detect Oracle backends. To access the CA Wily Community site. CA Technologies will contact you within 3-5 business days to confirm your registration.1 (KB 1240). Once you have completed the account information.jdbc. If you do not register with a corporate email address.Supplementary directives and tracers information Boundary Blame and Oracle backends In the current version of Introscope.net. you first need to register for an account using your corporate email address. available on the CA Wily Community site. The -Java Agent name is central to many views in the Introscope Workstation and Investigator. related environmental and deployment considerations. or simply started an instrumented application that the Java Agent monitors. This section contains the following topics: Understanding the Java Agent name (see page 147) Agent naming considerations for clustered applications (see page 150) Specifying an agent name using a Java system property (see page 150) Specifying an agent name using a system property key (see page 151) Obtaining an agent name from the application server (see page 151) Automatic agent naming (see page 152) Enabling cloned agent naming in clustered environments (see page 155) Application triage map and the agent name (see page 156) Understanding the Java Agent name Each Java Agent running in your Introscope environment has a name.Chapter 8: Java Agent Naming This section has information about agent naming. configured a method of automatically assigning a name. Chapter 8: Java Agent Naming 147 . and options for automatically naming your agents. and it is key to the process of associating monitoring logic with target applications. whether you assigned one explicitly. it accepts that name and connects to the Enterprise Manager. a node is created for that agent in the Investigator tree. How the agent determines its name The Java Agent uses the following sequence to determine a name. and so on. See Specifying an agent name using a Java system property (see page 150). If it doesn’t determine a name using any method.profile. If it doesn’t determine a name using the first method.When you configure management logic in the Workstation—for instance. Dashboards.profile The agent name is obtained from a Java system property specified in a property in the IntroscopeAgent. See Specifying an agent name using a system property key (see page 151)." Method 1: Agent name specified in a Java system property The agent name is defined using a Java system property on the command line. running on host qw32vtest01 under the WebLogic process. it calls itself "UnnamedAgent. The Investigator tree below shows agents named domain1//Adminserver. 148 Java Agent Guide . If it determines a name using the first method. it tries the second method. Using this method will override any other agent naming method.Understanding the Java Agent name When an agent report metrics to an Enterprise Manager. Method 2: Agent name specified in a system property key in the IntroscopeAgent. and Actions—the agent name is a component in the regular expressions that identify the applications to which the management logic applies. Alerts. in the property introscope. For instance. in succession. Method 5: Agent name determined to be "Unknown agent" If the agent is unable to determine a name using one of the methods listed above. How Introscope resolves agent naming conflicts The fully qualified agent name—comprised of host name. they are renamed. and so on.Understanding the Java Agent name Method 3: Agent name obtained automatically from the application server If you use certain versions of WebLogic or WebSphere. The Enterprise Manager renames the first duplicate agent to connect by appending "%1" to its agent name. This was the standard method for naming agents in early Introscope versions.profile. process name and agent name—is typically unique to each agent in an Introscope environment. assume that two agents with the fully qualified agent name: hostPA|processNIM|PodAgent connect to the Enterprise Manager. and have the same agent name. Method 4: Agent name specified explicitly in the agent profile The agent name is defined in the IntroscopeAgent. the agent name can be automatically obtained from the application server using automatic agent naming functionality. If an agent tries to connect to an Enterprise Manager to which an agent with the same fully-qualified agent name is already connected. The Enterprise Manager renames the second agent: PodAgent%1 If other agents with the same fully qualified name connect. the Enterprise Manager appends a unique identifier to the name of the newly connecting agent.agentName. to give the agent as much time as necessary to determine its name before connecting to the Enterprise Manager. Agents with the same agent name usually have a unique fully-qualified agent name because their host name and process names are likely to be different.agent. See Obtaining an agent name from the application server (see page 151). one after the other. Use this option if you already have an agent profile for every application. The identifier consists of a percent (%) character and a digit. PodAgent%3. This mechanism ensures that multiple agents that connect using the same fully-qualified name can be uniquely identified for the duration of the connection. monitor the same process. Multiple agents will have the same fully-qualified agent name only if they reside on the same host. PodAgent%2. then the agent names itself "UnnamedAgent". PodAgent%4. You can configure a time delay. where the digit following the percent character is the next number in sequence. Chapter 8: Java Agent Naming 149 . wily.agent. The options for resolving identical agent naming are: ■ 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 155). Introscope attempts to resolve identical agent names.agentName= 150 Java Agent Guide . Agent naming considerations for clustered applications If you run multiple instances of the same application. supply the desired name using this property: -Dcom.) ■ ■ Specifying an agent name using a Java system property To specify an agent name using Java system property: ■ On the Java command line.) Let Introscope uniquely name each agent using its own naming scheme (described in How Introscope resolves agent naming conflicts (see page 149).Agent naming considerations for clustered applications When a renamed agent disconnects. on subsequent connections. Reuse of the suffix identifier makes it possible that the Enterprise Manager might assign the same suffix to a particular agent’s name from connection to connection. a given agent could just as well be renamed differently. by appending the agent name with a character and a random number. However. For example. CA Technologies recommends.introscope. the next agent with the fully qualified name hostPA|processNIM|PodAgent to connect will be renamed PodAgent%1. Having an agent’s name vary from connection to connection is problematic when querying historical data—it is preferable to configure a naming strategy that avoids the Enterprise Manager renaming agents. including custom metric agents. that you tell Introscope how to resolve the naming. if PodAgent%1 disconnects while PodAgent remains connected.) Define unique agent names yourself and make separate agent profiles for each agent (described in Configuring unique names for application instances (see page 155). however. the suffix it was assigned can be re-used. Specifying an agent name using a system property key Specifying an agent name using a system property key This method is the second the agent uses to look for its name.2x Chapter 8: Java Agent Naming 151 .x WebSphere 6. Application servers that support agent naming Automatic agent Naming is supported when you use Introscope with these supported application server versions: ■ ■ ■ ■ ■ ■ ■ WebLogic 9. and use that information to name itself. To specify an agent name using the System Property Key: 1. Use this method if you want the agent to be named from the value of an existing Java system property in your deployment. This eliminates the need to configure individual agent names in a separate agent profile file.profile. The agent can also rename itself if there are changes in the application server environment. 3. This enables you to deploy an agent profile across a large number of environments that might consist of a mix of application server platforms. Obtaining an agent name from the application server You can configure the agent to extract the application server instance name automatically from the application server.x Jboss4.3 Jboss 4. Restart the application server.x distributed WebLogic 10.x distributed WebLogic 10.0. Under the Agent Name section.0. Open the IntroscopeAgent.agent.1.0 WebSphere 7.agentNameSystemPropertyKey Note: If the Java system property specified here doesn’t exist. this property will be ignored. specify the Java system property that will provide the agent name in this property: introscope. 2. Automatic agent naming The name of the application server displayed in the Introscope Workstation is determined by a Java J2EE API. the agent name is comprised of: Domain (data center) + cluster + instance (of WLS) ■ For WebSphere. Note: When constructing the agent name that appears in Introscope. or percentage signs are replaced by underscores names that begin with any character other than a letter will have the letter "A" prepended to them empty names are replaced by "UnnamedAgent" (so as to be distinguishable from the "UnknownAgent" condition) 152 Java Agent Guide . ■ For WebLogic. Automatic agent naming When automatic agent naming is enabled. the agent name is comprised of: cell (domain) + process (instance of WAS) When information is obtained. The agent waits until an agent name is obtained before attempting to connect to the Enterprise Manager. For example. it will be converted to Petstore_West. When the agent locates naming information. and even the same application server name may be formatted differently from release to release. Introscope edits the information to make the agent name compliant with the following Introscope agent naming rules: ■ ■ ■ characters such as pipes. segments are separated by forward slashes —for example: medrec/MyCluster/MedRecServer Any forward slashes in the segment name are converted to underscores. Introscope edits the information to make the agent name compliant with Introscope agent naming rules. if a Domain is named Petstore/West. the agent starts and looks for name information from the application server. The names of multiple application servers may be formatted differently in the Workstation. Agent names on supported application servers are comprised of several pieces of information. colons. which differ according to application server. This sometimes causes the name of the application servers to display differently in the Workstation because all application servers implement the API differently. for information on configuring automatic agent naming properties for Enterprise Manager connection delay.0 or higher (see page 78). create an Introscope Startup Class. The disconnected agent remains in the Investigator tree. For WebSphere. and unmounts automatically after the unmount time period has elapsed. Automatic agent naming and renamed agents Using automatic agent naming. For JBoss.profile.agentAutoNamingEnabled to true. In the Investigator tree. create an XML file. See Configuring a custom service in WebSphere 6. the agent appears to disconnect.agent.1 (see page 92). See Configuring a startup class for WebLogic 9. 2. Make these application server-specific changes: ■ ■ ■ For WebLogic. and rename checking interval time. See Configuring JBoss (see page 105). The agent periodically checks for a new name. or can be unmounted manually. the agent always tries to obtain the most current application-server-specific agent name. Advanced automatic agent naming options There are several properties you can change to control automatic agent naming for your environment. create an Introscope Custom Service. Chapter 8: Java Agent Naming 153 . set introscope. The agent logs these changes. If a change to the application server configuration results in an agent name change.Automatic agent naming To enable automatic agent naming: 1. See Advanced automatic agent naming options (see page 153). the agent automatically renames itself. In the IntroscopeAgent. The renamed agent reconnects to the Enterprise Manager and appears in the Investigator tree. Open the IntroscopeAgent. Agent Rename Check Interval When using the automatic agent naming feature.agent. the agent waits up to a configurable amount of time before connecting to the Enterprise Manager while trying to find agent name information. configure the desired delay in the property introscope. To turn off agent log file automatic naming: 1.agent. Under the Agent Name section. Set the property. 2. Restart the application server. the log files associated with that agent are named automatically using that same information.Automatic agent naming Initial Enterprise Manager Connection Delay When using the automatic agent naming feature. 3. you can turn off this automatic log naming. 3. and continue to use the agent log name specified in the IntroscopeAgent. The default interval is ten minutes. configure the desired interval in the introscope. 2. To change this interval: 1. Restart the application server.profile.disableLogFileAutoNaming . 154 Java Agent Guide . when the agent name is found automatically. Open the IntroscopeAgent.profile.profile. introscope. Restart the application server.profile. 2. The default delay is 120 seconds. 3. the agent periodically checks to see if the naming information from the application server has changed.agentAutoNamingMaximumConnectionDelayInSeconds .profile. to a value of true. Under the Agent Name section.agent. either by information provided by a Java system property or application server. Turning Off Agent Log File Automatic Naming By default.agentAutoRenamingIntervalInMinutes property. Open the IntroscopeAgent. Save the IntroscopeAgent. 4. However. To change the delay value: 1. you will never have more Java Agent names in the database than the number of Java Agents originally cloned. Create a separate agent profile for each application. 2. if you have four Java Agents. 4. 2. Uniquely name each agent in the agent profile. Cloned agent naming scenario With the Java Agent cloning property turned on. all named AgentX. the Enterprise Manager names the agents AgentX-1. AgentX-3 and AgentX-4. 3. Chapter 8: Java Agent Naming 155 . To enable cloned agent naming: 1. You are running cloned agents if you: ■ ■ are running agents that share a host. Specify which agent profile each application should use. Configuring unique names for application instances If you monitor multiple instances of the an application on the same machine. or are running two or more agents that are using the same agent profile. Stop your managed application and the Java Agent.clonedAgent=true Save the IntroscopeAgent. 3. Cloned agent naming enables you to correlate an agent with a particular application instance in a clustered application. Open the IntroscopeAgent. To configure unique agent names: 1.profile and set the following property to true: introscope. Restart your managed application and the Java Agent. If AgentX-1 disconnects and then reconnects.Enabling cloned agent naming in clustered environments Enabling cloned agent naming in clustered environments If two agents exist with the same name monitoring the same host and process and are not uniquely named by a user.profile. it will still use AgentX-1 as its name. process.agent. the name is appended with a number. With this naming. AgentX-2. you can configure unique agent names explicitly. or Java Agent name with one or more other agents. Users may want to designate specific agent names to sidestep this issue. the Enterprise Manager may assign a duplicated agent name a unique name by appending %<sequence number> to the agent name (e. If agent names change some aspects of the application triage map may also change.Application triage map and the agent name Application triage map and the agent name The application triage map in the Workstation uses the agent name as part of several unique identifiers when defining the front. 156 Java Agent Guide .and backends of applications. during initial registration of an agent. CA Technologies recommends users be aware of the naming conventions employed in their Introscope environments. MyAgent%1). it may reduce the overall capacity of your system.g. If parts of the application triage map are relying on the duplicated agent name for information. While this does not affect the proper functioning of either the agent or the Enterprise Manager. For example. aspects of the map could change. as such. as well as for storing information about application components in Introscope databases. Introscope generates metrics on the connection status of agents connected to an Enterprise Manager. Agent connection metrics appear in the Workstation Investigator under the Enterprise Manager process (the custom metric host): Custom Metric Host (Virtual) \ Custom Metric Process(Virtual) \ Custom Metric Agent (Virtual) (*SuperDomain*) \ Agents \ <HostName> \ <Agent Process Name> \ <Agent Name> \ ConnectionStatus Connection metrics have these values: ■ ■ ■ ■ 0—No data about the agent is available 1—agent is connected 2—agent is slow to report 3—agent is disconnected An agent disconnecting also generates a "What’s Interesting" event. This section contains information on monitoring the agents health. This section contains the following topics: Configuring agent connection metrics (see page 157) Socket metrics (see page 158) Configuring logging options (see page 162) Managing ProbeBuilder Logs (see page 167) Configuring agent connection metrics By default. As with other events. Introscope can also monitor the health and activity of the Java Agent itself. You can monitor agent connection metrics to determine the current state of the connection between an agent and the Enterprise Manager. as well as logging options for the Java Agent. users can query for agent disconnects using the historical query interface. which you can monitor.Chapter 9: Java Agent Monitoring and Logging While Introscope monitors your applications. Agent disconnect events are part of the data used in assessing application health in the Overview tab in the Workstation Console. Chapter 9: Java Agent Monitoring and Logging 157 . 158 Java Agent Guide .properties file located in the <Introscope_Home>/config directory. Introscope continues to generate disconnected state metrics until the agent is timed out.agentconnection. Socket metrics Socket and Secure Sockets Layer (SSL) metric collection is enabled by default in the agent. See AutoProbe for WebSphere 6. Save the IntroscopeEnterpriseManager. Modify this property: introscope. When an agent times out. open the IntroscopeEnterpriseManager.enterprisemanager. On the machine that the Enterprise Manager is installed on. see the Introscope Configuration and Administration Guide. The time increment is in minutes.agentTimeoutInMinutes 2.NoRedef.Socket metrics Once an agent disconnects from the Enterprise Manager.jar do not have socket metrics reported.1 (see page 85) for more information.metrics.properties For information about Enterprise Manager properties. To configure the agent connection time out: 1. Note: JVMs using the Agent. 3. no additional connection metrics are generated or reported to the Enterprise Manager. socket. If.ports A comma separated list of port numbers.socket. a warning message is written to the agent log and that value is ignored.hosts A comma separated list of hosts. 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. however.socket. ■ introscope.ports Comma separated list of port numbers. only 'server' socket metrics for specified ports will be generated. 3.io. located in the <Agent_Home>/wily directory. you can further refine your metric collection by turning on and off specific tracer groups.agent.client. as a result. Save the IntroscopeAgent. ■ introscope. as detailed in Restricting socket and SSL metric collection (see page 159). only one of the names is retained. To restrict socket and SSL metric collection: 1. only 'client' socket metrics for specified ports will be generated.io. The above properties are dynamic.profile.io. the list contains no entries. This helps to target the information you want as well as reduce overhead costs. no restriction will apply. Fine-tuning socket and SSL metric collection While you can restrict socket and SSL metric collection.profile.server. you do not need to restart your applications for changes to take effect. match client connections with any of the set of synonymous names. In cases where multiple host names map to a single IP. Chapter 9: Java Agent Monitoring and Logging 159 . 2. Note: Duplicate host names are discarded. Note: Duplicate ports are discarded. only 'client' socket metrics for specified hosts will be generated. but you can restrict some metric collection to target more relevant information or scale back on overhead. ■ introscope.client.agent.Socket metrics Restricting socket and SSL metric collection Socket and SSL metric collection is enabled by default. Open the IntroscopeAgent.agent. In the Agent I/O Socket Metrics section. Hosts may be specified by name or textual representation of IP address (in either IPv4 or IPv6 forms). The property will. pbd. Component names. in the same way socket client metric names are displayed. 160 Java Agent Guide . determine the tracers you want to turn on or off. to suppress the metrics for input bandwidth. located in the <Agent_Home>/wily directory. Open the java2.pbd. include destination host and port identities. For example. and then this information is displayed graphically in the application triage map. when displayed in the application triage map. extend existing SSL. and socket tracing in the application triage map The application triage map introduced in the Introscope 9. NIO.pbd. 3.0 Workstation Investigator has the ability to display instrumented client socket connections.pbd file. and comment or uncomment them. Save the java2. 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.pbd file.Socket metrics To fine-tune socket and SSL metric collection: 1. but can be disabled by commenting out specific tracers in the Trace Sockets and Trace NIO Sockets sections of the AppMap. 2. The agent records details about external systems being used in transactions. The default is the host name. sends this information to the Enterprise Manager. The tracers contained in the AppMap. The host identity in a component name can be configured to either a host name or a host IP address. In the I/O Socket Tracer Group or Network Tracer Group sections of java2. NIO. located in the <Agent_Home>/wily directory. and socket instrumentation. The tracers are enabled by default. allowing the agent to send more component information to the application triage map. SSL. 2. To turn off socket and SSL metric collection: 1. 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}" To display the host IP. Open either toggles-full. 2. at the beginning of the line) SocketTracing: #TurnOn: SocketTracing 3. they can be turned off entirely. Save the AppMap. Chapter 9: Java Agent Monitoring and Logging 161 . For more information about turning on and off tracer groups. use {hostip} instead: TraceOneMethodWithParametersIfFlagged: SocketTracing read AppMapSocketTracerBT "System {hostip} on port {port}" TraceOneMethodWithParametersIfFlagged: SocketTracing write AppMapSocketTracerBT "System {hostip} on port {port}" 3. For example. select the tracers you want to modify.pbd.#. Open AppMap. in the toggles-full. Change {hostname} to {hostip} in the relevant tracers.pbd files (open the file you are using in your deployment). Save the file you modified. located in the <Agent_Home>/wily directory.pbd and toggles-typical.pbd files. In the Trace Sockets and Trace NIO Sockets sections.pbd file.Socket metrics To change the displayed component name: 1.pbd or toggles-typical. Comment out (place a pound or hash sign. see Default tracer groups and toggles files (see page 114) and Turning tracer groups on or off (see page 125). Turning off socket and SSL metric collection If collecting socket and SSL metrics is not required. profile. 3. 162 Java Agent Guide . 2.reportRateMetrics=true Note: Only functions if ManagedSocketTracing is enabled and SocketTracing is disabled. Comment out (place a pound or hash sign.0 socket tracing features and configuration options). Uncomment ManagedSocketTracing: TurnOn: ManagedSocketTracing Save the file you modified. The application server process must have full read/write/execute permissions on the <Agent_Home> directory. However. you want to revert to pre-9.pbd or toggles-typical. If you are using pre-9. Locate the Agent Socket Rate Metrics section and change the following property to true: introscope.Configuring logging options Backwards compatibility In the 9. Or.0 tracers (and disable new 9. Open either toggles-full.#.0 tracers: 1.sockets.pbd files (open the file you are using in your deployment).profile. the required configuration changes are outlined below. they are enabled as follows. after the server starts up a log directory is created here: <Agent_Home>/wily/logs. To accomplish this. To collect socket metrics using pre-9. To collect input and output bandwidth metrics: 1.0 socket tracers and input and output bandwidth metrics are required. 4. Configuring logging options When the Java Agent is installed on an application server. install the Java Agent as a different user. 2. then use the chmod command to bestow the necessary permissions. Open the IntroscopeAgent. at the beginning of the line) SocketTracing: #TurnOn: SocketTracing 3. Save the IntroscopeAgent.0 tracers. The following steps are optional. if for any reason. install the Java Agent on the same operating system as the user who runs the application server process.0 Java Agent new socket tracers have been introduced that are more configurable than pre-9.agent. Note: Changes to this property should take effect within one minute and do not require the managed application to be restarted.logger.profile.util.feedback. replacing the existing INFO with VERBOSE#com. Introscope uses Log4J functionality for these functions.Log4JSeverityLeve l.profile.feedback. 2.util. please consult the Log4J documentation.Configuring logging options The Java Agent has the option to run in verbose mode. Chapter 9: Java Agent Monitoring and Logging 163 .wily. This information is useful in solving issues with your environment or agent functionality. located in the <Agent_Home>\wily directory. To run the agent in verbose mode: 1. Save the IntroscopeAgent. console. logfile 3. Running the agent in verbose mode Running the agent in verbose mode records higher levels of information to the agent log. Modify this property.Log4JSeverityLevel: log4j. Verbose mode records higher levels of details about actions and agent interactions with your environment. If you want to use other Log4J functionality. Open the IntroscopeAgent.IntroscopeAgent=VERBOSE#com.wily. the agent log files are also automatically named. 164 Java Agent Guide . If you configured agent autonaming options.feedback.logfile If you wanted the agent to report to both a logfile and console. the location of the log file is configured using the log4j. you would include both logfile and console in the property.Log4JSeverityLeve l.IntroscopeAgent=VERBOSE#com. 2.logger.profile. For example.profile. as described in Agent log files and automatic agent naming (see page 165).log is written to the <Agent_Home>\wily\logs directory.File property.IntroscopeAgent The options for this property are: ■ ■ console: the information in the logfile is sent to the console logfile: the information in the logfile is sent to a logfile. See Changing the name or location of the agent logfile (see page 165).logfile. Find the property: log4j.wily. Note: By default the agent log. located in the <Agent_Home>\wily directory. the property would be set to: log4j.Configuring logging options Redirecting agent output to a file The property that controls the agent logging in verbose mode also controls where the agent log is output and the location of this log file (see Running the agent in verbose mode (see page 163) for more information). Open the IntroscopeAgent.appender. if you wanted the agent to report in verbose mode to just a logfile.logger. 3. To redirect agent output to a file: 1. If this is selected. IntroscopeAgent.util. Save the IntroscopeAgent. a period and log is added. by default the log files associated with an agent are named automatically using the same information used to name the agent. if a Java command starts with -Dmy.log.property}. To change the name or location of the logfile: 1.logfile. Note: System properties (Java command line -D options) can be included as part of the file name. Agent log files and automatic agent naming If you use the automatic agent naming functionality. 3. Open the IntroscopeAgent.appender. the location of the log file is configured using the log4j.logfile.File property.log 4.IntroscopeAgent property.logfile. 2. If logfile was specified in the log4j.logfile. using a fully qualified path to the new location and file.File property.log. then log4j. All characters that are not letters or digits will be replaced by underscores If advanced Log4J functionality is used.File=logs/Introscope-Server1. The examples use an agent name of DOM1//ACME42. Locate the log4j. Chapter 9: Java Agent Monitoring and Logging 165 .log is expanded to: log4j. Automatic agent naming affects the log file in the following way: ■ ■ ■ If the original name of the logfile does not end in .appender. See step 2 in Redirecting agent output to a file (see page 164) for more information. For example. Save the IntroscopeAgent.appender. the agent logfile automatic naming capability might not work.appender. and ACME42 is the instance of the agent. For example: log4j.profile.File=C:/Logs/AgentLog1.appender. Set the location and name of the log file. located in the <Agent_Home>\wily directory.File=logs/Introscope-${my. The following examples show how an agent logfile is named.Configuring logging options Changing the name or location of the agent logfile You can also change the location and name of a logfile by modifying a property. where DOM1 is the WebLogic domain.profile.property=Server1.logger.logfile. wily.logfile.agent.MaxBackupIndex=3 166 Java Agent Guide . Modify the following properties: log4j.util.feedback.MaxBackupIndex Note: You must restart the managed application before changes to this property take effect.File log4j.see Advanced automatic agent naming options (see page 153) for more information.appender. Rolling up logs by date or size You can roll up logs based on size or date. the logfile is renamed using the agent’s automatic name: AutoProbe. 3.console.layout.appender.wily.MaxFileSize log4j.appender.logger.logfile.appender. For example.appender.ConversionPattern=%d{M/dd/yy hh:mm:ss a z} [%-3p] [%c] %m%n log4j.MaxFileSize=2KB log4j.IntroscopeAgent log4j. if the agent name is not yet available.introscope. console.logfile.console.File=logs/IntroscopeAgent.PatternLayout log4j.console.layout=com. the following configuration will keep up to three backup/rolled logs.logfile=com.AutoNamingRollingFileAppende r log4j.Configuring logging options When an agent log file is created (named AutoProbe.log You can disable automatic log naming .logfile log4j. and each will be up to 2 kilobytes in size: log4j.logfile.layout.log by default).console.profile.apache.appender.appender. logfile log4j.layout log4j. Save the IntroscopeAgent.appender. and locate the Logging Configuration section.appender. a timestamp is included in the filename: AutoProbe.appender.log4j.log log4j.profile.Log4JSeverityLeve l.log Once the agent name becomes available. Open the IntroscopeAgent.logger.IntroscopeAgent=VERBOSE#com.logfile.wily.appender.appender. To roll up log files: 1.20040416-175024.org. retaining a specified number of days of information and purging the rest.DOM1_ACME42.logfile. 2.ConversionPattern log4j. logfile property and modify the log name and location. Non-absolute names are resolved relative to the location of the IntroscopeAgent. By default the AutoProbe log file is named AutoProbe. Only the most recent log is kept. it logs the classes it did not instrument due to skips. using a fully qualified file path. the log file is located inside the destination directory. as well as all the classes it does not add instrumentation for. the log file is located next to the destination file. For a directory. 3. 2. You must restart the managed application before changes to this property take effect.profile file is located within a resource.profile. AutoProbe log name and location AutoProbe will always attempt to log the changes it makes. Command-line ProbeBuilder and ProbeBuilder Wizard log name and location The command-line ProbeBuilder and ProbeBuilder Wizard log file location is determined by where you specify Java classes with the ProbeBuilder Wizard or with the Command-Line ProbeBuilder.profile file.log <original-directory> or <original-file> is the Java class location that you specify with the ProbeBuilder Wizard or with the Command-Line ProbeBuilder. AutoProbe is unable to write to the AutoProbe log file. Open the IntroscopeAgent. located in the <Agent_Home>\wily directory. Note: When loading the agent profile from a resource on a classpath. The ProbeBuilder log file is called: <original-directory-or-original-file>.Managing ProbeBuilder Logs Managing ProbeBuilder Logs ProbeBuilder logs all the classes it sees. Save the IntroscopeAgent. Chapter 9: Java Agent Monitoring and Logging 167 . the probes it added during the instrumentation process and the PBDs it used. For a file. because the IntroscopeAgent. To change the name or location of the AutoProbe log: 1. all previous log files are overwritten.profile. all the classes it instruments.autoprobe.probebuilder.log. In addition. Locate the introscope. . regardless of the Collector Enterprise Manager to which they report. logical view of the metrics reported by multiple Java Agents. application level. Virtual Agent requirements If you have multiple stand-alone Enterprise Managers. A Virtual Agent is useful if you manage clustered applications with Introscope—a Virtual Agent is comprised of the agents that monitor different instances of the same clustered application. Consider these conditions when configuring Virtual Agents: ■ ■ ■ An agent can be assigned to multiple Virtual Agents. Virtual Agents cannot include other Virtual Agents. In an Enterprise Manager cluster. including custom metric agents—all agents in a cluster must have unique names. This allows metrics from multiple instances of a clustered application to be presented at a logical. You can view performance and availability data for a specific application instance. See the CA Wily Introscope Configuration and Administration Guide for more information about clustering. A Virtual Agent enables an aggregated. a Virtual Agent can contain only agents that report to the same Enterprise Manager. This section contains the following topics: Understanding Virtual Agents (see page 169) Virtual Agent requirements (see page 169) Configuring Virtual Agents (see page 170) Understanding Virtual Agents You can configure multiple physical agents into a single Virtual Agent.Chapter 10: Using Virtual Agents to Aggregate Metrics This section has information about configuring and using Virtual Agents. If you define multiple Virtual Agents. they must have unique names. agents that report to Enterprise Managers within a single cluster can belong to the same Virtual Agent. and appears in the Introscope Workstation as a single agent. Chapter 10: Using Virtual Agents to Aggregate Metrics 169 . as opposed to separately for each application instance. by scoping your views and interactions in terms of a single agent. 0" encoding="ISO-8859-1" ?> <agent-clusters xmlns:xsi="http://www.*\|BuyNow. in the Introscope SuperDomain.xml file.*\|. <?xml version="1. using the standard fully qualified agent name: <host> | <process> | <agentName> ■ <metric-specifier>—Contains a prefix that specifies the metrics to collect from the agents in the Virtual Agent. The <agent-cluster> element requires two child elements: ■ <agent-specifier>—Contains a regular expression that specifies the agents in the Virtual Agent.Configuring Virtual Agents Configuring Virtual Agents You configure Virtual Agents using the agentclusters.xml file in the config directory of the cluster’s Manager of Managers (MOM). or subsets of the instances of a resource type. the Virtual Agent will default to the SuperDomain. The Virtual Agent includes all agents. and has two required attributes: ■ ■ name—If you define multiple Virtual Agents. domain—Assigns the Virtual Agent to an Introscope domain. each must have a unique name. The <agent-cluster> element defines a Virtual Agent. <agent-clusters>.1. The sample agentclusters. you configure Virtual Agents using the agentclusters.1" > <agent-cluster name="BuyNowAppCluster" domain="SuperDomain" > <agent-specifier>. in terms of resource type.*</agent-specifier> <metric-specifier>Frontends\|. you define an <agent-cluster> element for each. located in the <EM_Home>/config directory of the Enterprise Manager to which the agents report. If no domain is defined (as domain="") in the agent-cluster definition.xml below defines a Virtual Agent named BuyNowAppCluster.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="agentclusters0. on any host.xsd" version="0. any resource can be used as a metric specifier. 170 Java Agent Guide . whose agent name starts with BuyNow. If you run clustered Enterprise Managers that are clustered.w3. Recommended prefixes are: ■ ■ ■ ■ Frontends CPU JMX WebSpherePMI Note: While the above are the recommended prefixes. If you define multiple Virtual Agents. is required.*</metric-specifier> </agent-cluster> </agent-clusters> The root element. A sample agentclusters.xml is available in your <EM_Home>\config directory. but should be used with caution. Chapter 10: Using Virtual Agents to Aggregate Metrics 171 . Use of wildcards can result in a high volume of metrics and a performance impact.Configuring Virtual Agents The <agent-cluster> element can contain multiple <metric-specifier> stanzas. Important: Regular expressions and wildcard metric specifiers such as ". Note that a higher volume of matching metrics imposes high overhead on the Enterprise Manager.*" and "(. if at all.*)" are allowed. and can ultimately have an effect on Enterprise Manager capacity. . you specify a list of alternative Enterprise Managers in the IntroscopeAgent. it tries to connect to the next Enterprise Manager on the list of failover hosts. you define connection properties for backup Enterprise Managers. it cycles through the Enterprise Managers on the list until it succeeds in connecting. To enable agent failover. and a list that specifies the failover order. When an agent configured for failover cannot connect to its default Enterprise Manager. it waits 10 seconds before cycling through the list again.Chapter 11: Configuring Java Agent Failover This section has information about agent failover. To enable failover. If the agent goes through the list without connecting to an Enterprise Manager. If the agent does not connect with a failover host. or loses connection with it. In a basic Introscope configuration. you define the host and port settings for one Enterprise Manager. can failover to an alternative Enterprise Manager. This section contains the following topics: Understanding agent failover (see page 173) Defining backup Enterprise Managers (see page 174) Defining failover connection order (see page 175) Configuring failback to primary Enterprise Manager (see page 175) Configuring domain/user information (see page 176) Understanding agent failover An agent that cannot connect to its Enterprise Manager. Chapter 11: Configuring Java Agent Failover 173 .profile file. tcp.tcp.link.wi ly.agent.host. To define backup Enterprise Managers: 1.postofficehub.DEFAULT=5001 introscope.postofficehub.agent. Locate the Enterprise Manager Locations and Names section of the profile. 2.transport.port.DEFAULT=com.host.Defining backup Enterprise Managers Defining backup Enterprise Managers To enable agent failover.profile file.DefaultSocketFactory This is an example of defining a second backup Enterprise Manager: introscope.agent.DefaultSocketFactory 4.enterprisemanager.transport.BackupEM2= com.BackupEM1=5002 introscope.tcp. The following example contains the primary Enterprise Manager connection information.BackupEM2=space9 introscope. located in the <Agent_Home>\wily directory.agent.net. This is the primary Enterprise Manager connection information: introscope.socketfactory.DEFAULT=enterprise introscope.BackupEM1=voyager introscope.transport.isengard.enterprisemanager.tcp.link.net. creating an alternate communication channel for each as described in Connecting to the Enterprise Manager (see page 48).agent. Open the IntroscopeAgent. you must define a list of backup Enterprise Managers.transport.tcp.enterprisemanager.tcp.transport.tcp. Note: Be sure to assign each additional Enterprise Manager communication channel a unique name—do not use the name DEFAULT or the name of an existing channel when creating a new one.tcp.profile.enterprisemanager.tcp.BackupEM2=5003 introscope. Add Enterprise Managers and their connection information to this section.enterprisemanager.wily.enterprisemanager.socketfactory.enterprisemanager.agent.socketfactory.agent.transport.BackupEM1= com.agent. as well as two backup Enterprise Managers.transport.enterprisemanager.net.port.isengard.transport.postofficehub.port. 3.agent.isengard.wily.host. 174 Java Agent Guide .DefaultSocketFactory This is an example of defining the first backup Enterprise Manager: introscope. Save the IntroscopeAgent.enterprisemanager.link.transport. Save the IntroscopeAgent.enterprisemanager.profile.enterprisemanager.agent. Put the primary Enterprise Manager first in the list. Note: You must restart the managed application before changes to this property take effect. locate the introscope. To configure attempts to reconnect to the primary Enterprise Manager: 1.profile. it tries to connect to the next Enterprise Manager defined in the agent profile. Uncomment this property: introscope. Configuring failback to primary Enterprise Manager In the default agent failover scenario. 2. the connection order could be specified like this: introscope. Save the IntroscopeAgent. In a clustered configuration with a MOM.BackupEM 2 3. Restart the application.agent.failbackRetryIntervalInSeconds and set the interval in which the agent will attempt to reconnect to its primary Enterprise Manager. define the order in which the agents will attempt to connect to the backup Enterprise Manager. To specify the connection order: 1.profile.profile file. 3.enterprisemanager.BackupEM1. Chapter 11: Configuring Java Agent Failover 175 . In the IntroscopeAgent. For the Enterprise Manager communication channels specified Defining backup Enterprise Managers (see page 174). 4.Defining failover connection order Defining failover connection order After specifying the connection properties for your backup Enterprise Managers.agent.connectionorder property. locate the Enterprise Manager Failback Retry Interval section. In the IntroscopeAgent. List the Enterprise Manager communication channels—for the agent’s primary Enterprise Manager as well as the backups. You can also configure the agent to periodically try to reconnect to the primary Enterprise Manager. The default interval is 120 seconds. 2. you can also use agent load balancing to handle Collector downtime scenarios. if the agent loses connection to its primary Enterprise Manager.connectionorder=DEFAULT. you must ensure that this information is in sync across the specified failover Enterprise Managers. see the CA Wily Introscope Configuration and Administration Guide . and authentication settings defined. For more information on domain and user permissions. 176 Java Agent Guide .Configuring domain/user information Configuring domain/user information To use agent failover and also have users. domains. if the number of objects stored in the collection increases over time. However. This method of using LeakHunter creates only a small. This section contains the following topics: LeakHunter (see page 177) Enabling and disabling LeakHunter (see page 180) Configuring LeakHunter properties (see page 181) Running LeakHunter (see page 183) Identifying potential leaks with collection IDs (see page 183) LeakHunter log file (see page 184) Using LeakHunter (see page 186) ErrorDetector (see page 187) Enabling ErrorDetector in the Java Agent (see page 189) Configuring ErrorDetector options (see page 189) Advanced error data capture (see page 190) Defining new error types (see page 190) More help (see page 192) Using ErrorDetector (see page 193) 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 time—that is. Memory leaks that occur in programs that run for short periods (minutes or hours) might not present a major issue.Chapter 12: Configuring LeakHunter and ErrorDetector This section describes how to enable and configure LeakHunter and ErrorDetector. Chapter 12: Configuring LeakHunter and ErrorDetector 177 . for applications that are running 24 hours a day (like a web site). Introscope LeakHunter is designed to track information about a noticed memory leak by being turned on. discovering collection classes. temporary amount of overhead. and then being turned off after information is gathered. a small memory leak can soon escalate into a big problem. pbd (in addition to any previously used PBD files).LeakHunter How LeakHunter works After you have enabled LeakHunter. it: ■ ■ ■ ■ identifies the collection with a unique ID 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 continues to track and report data for that collection Should LeakHunter notice that a collection no longer appears to be leaking. you simply restart the managed application. After a timeout period expires. LeakHunter continues looking for potential leaks and monitors already identified potential leaks until the timeout period expires. but continues tracking and reporting data for that collection. If you use ProbeBuilder Wizard or Command-line ProbeBuilder. 178 Java Agent Guide . you must re-instrument the application using the leakhunter. This significantly reduces LeakHunter overhead and allows additional monitoring of the potential leaks. or view the log file. To find the source of a memory leak. LeakHunter stops looking for potential leaks in newly allocated collections. If you use AutoProbe. LeakHunter continues monitoring the identified potential leaks until the managed application is shut down. you also define a timeout period during which LeakHunter looks for new potential leaks. it reports that fact to both the Enterprise Manager and the log file. you can either browse the metric data in the Introscope Investigator. and only continues checking collections that are already identified as potential leaks. If LeakHunter finds a collection that is growing in size over time. util.util.TreeSet java.Vector java.util.util.SortedMap java.LinkedHashMap What LeakHunter does not track Introscope LeakHunter does not track: ■ ■ ■ a leak not caused by a collection.util.LinkedHashSet java.Properties java.Collection: ■ ■ ■ ■ ■ ■ ■ java.util.HashMap java.LeakHunter What LeakHunter tracks in Java Introscope LeakHunter tracks these collections in a Java implementation: ■ Implementations of java.LinkedList java.Map java.Map: ■ ■ ■ ■ ■ ■ ■ ■ java. custom collection implementations or other data structures with an increasing number of references.util.Stack ■ Implementations of java. Chapter 12: Configuring LeakHunter and ErrorDetector 179 .util.Hashtable java. a leaking collection that is not instrumented.util.IdentityHashMap java.util.TreeMap java.HashSet java.util.util.util.util.ArrayList java.util.util.util. you must statically instrument the application server.profile property introscope.agent. By default. LeakHunter is not enabled after installation. be sure to move the contents of the \ext directory as well. By default. 2. To enable LeakHunter: 1. You must enable LeakHunter to use its functionality. agent extensions such as LeakHunter are located and referenced from the <Agent_Home>\wily\ext directory. To track these collections. or use JVM AutoProbe. LeakHunter does not track the following in a Java implementation: ■ any subclasses created for collections described in What LeakHunter tracks in Java (see page 179).Enabling and disabling LeakHunter In addition to the above. Enabling and disabling LeakHunter LeakHunter is run as an agent extension.pbl or *. locate the property introscope.full. and enter a value of true.autoprobe.pbd file to the <Agent_Home>\wily\hotdeploy directory. If you change the location of the \ext directory. Under the LeakHunter Configuration heading. Note: When using ProbeBuilder Wizard. Important: By default.pbd. LeakHunter is not enabled after installation. IntroscopeAgent. System and version requirements Introscope LeakHunter has the same system requirements as the Java Agent. you can change the location of the agent extension directory in the agent profile.leakhunter.pbl (open the file you have listed in the IntroscopeAgent.pbd file for more information. However. However. 180 Java Agent Guide . you can update the ProbeBuilder Directive (PBD) file to get this information. See the leakhunter.directivesFile ) and uncomment leakhunter. LeakHunter does not automatically track collections allocated by the application server. 4.typical. 5. Open *. 3. You must enable LeakHunter to use its functionality. Open the agent profile. so no class paths need to be updated.enable.profile. Note: If you are using Application Server AutoProbe. copy the leakhunter. Restart the application. Save the agent profile. Restart the application. To configure LeakHunter: 1.leakhunter. Open the agent profile.profile.leakhunter. Under the LeakHunter Configuration heading. Open the agent profile.append Specifies whether to replace the log file (value of false) or append an existing log file (value of true) on application restart. The default sensitivity level is 5. locate the property introscope. 2.profile.logfile. Configure the following LeakHunter properties as desired: introscope.leakhunter.leakhunter.leakSensitivity Specifies the sensitivity level for detecting memory leaks.leakhunter. If the property is commented out or left blank. Configuring LeakHunter properties LeakHunter configuration properties are located in the agent profile. introscope.agent. 4. 3. The file name is relative to the <Agent_Home> directory.timeoutInMinutes Specifies the period of time in minutes during which LeakHunter looks for new potential leaks.enable. The default value is 120 minutes. The property value must be an integer from 1-10.log file. and enter a value of false. no log file is written. A higher leak sensitivity setting will result in more potential leaks being reported and a lower sensitivity will result in fewer potential leaks reported. 2. located in the <Agent_Home>/wily directory.agent.Configuring LeakHunter properties To disable LeakHunter: 1.agent. A value of zero means no timeout.agent. The default value is false. Chapter 12: Configuring LeakHunter and ErrorDetector 181 . introscope. IntroscopeAgent.profile.log.location Specifies the location of LeakHunter. The default value is logs/LeakHunter. Save the agent profile. The property value must be a non-negative integer. introscope. IntroscopeAgent.agent. IntroscopeAgent.logfile. n Specifies the particular collections that you want LeakHunter to ignore. These properties are enabled by default.hibernate.leakhunter.jnp.ignore.sf.collection.Collections.agent.FastNamingPropert ies introscope.standard.SubList 3. 182 Java Agent Guide .ignore.List`1 Changes to this property take effect immediately and do not require the managed application to be restarted.RecordEJB_xw cp6o__WebLogic_CMP_RDBMS introscope.0=org.Generic.leakhunter.entities.bea. If you comment out these properties.ignore.1=com. Important: The IntroscopeAgent. exceptions are reported in the agent logs.taglibs.leakhunter. Changes to this property take effect immediately and do not require the managed application to be restarted.agent. Save changes to the agent profile.ignore. The default values for these properties (where n=0-4) are: introscope.leakhunter.profile.collectAllocationStackTraces Specifies whether to collect allocation stack trace information.agent.leakhunter.ignore. use a syntax that includes the generic type qualification. introscope.ignore.lang. Such collections should be ignored.3=org.apache. For Generic collections. Turning on this option has the potential to create higher system CPU usage and memory.agent.Configuring LeakHunter properties introscope.4=java.* introscope.agent.leakhunter.jst l. if the collection is such that the size() method takes longer and longer to execute (for example. In other words.* introscope.agent.agent.2=net. this will have negative effects on application performance. a badly implemented LinkedList where to get the size of the list we traverse through each element of the list and count). The default value is false.profile contains properties that control which packages are ignored by LeakHunter. for example: System. using the ignore property in IntroscopeAgent. as shown in Configuring LeakHunter properties.leakhunter.util.medrec.interfaces. Ignoring collections that cause poor performance Collections whose size() method executes in time proportional to the number of objects in the Collection will have poor performance. Using Command-Line ProbeBuilder: re-instrument the managed application using the leakhunter. Examples of these collection IDs are: theLookupTable-6314#1 getLoginID-1234#1 getLoginID-1234#2 getLoginID-1234#3 verifyCart-5678#1 verifyCart-0012#1 Chapter 12: Configuring LeakHunter and ErrorDetector 183 .pbd from the custom pbd list. restart the application. Restart the managed application after implementing new . The unique collection IDs have a specific syntax. Using ProbeBuilder Wizard: run ProbeBuilder Wizard and select the leakhunter.jars for use. based on one of these types: <method>-<4 digit hash code>#<unique number> <field>-<4 digit hash code>#<unique number> ■ ■ ■ ■ <method>: the name of the method where the collection was allocated <field>: name of field to which the collection was assigned <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. To run LeakHunter: ■ ■ Using JVM AutoProbe: after LeakHunter has been enabled. Restart the managed application. ■ Identifying potential leaks with collection IDs LeakHunter identifies each potential leak with a unique collection ID that can be used to correlate metric data from the Investigator tree with data in the log file.pbd (and any previously used .pbds). The collection ID for a potential leak will be stable across runs of the application.Running LeakHunter Running LeakHunter LeakHunter is run as an agent extension. as well as provide stable names across applications. LeakHunter log file LeakHunter log file The LeakHunter log file contains information about potential leaks identified by Introscope LeakHunter in your managed application. The LeakHunter log file includes entries for four scenarios: ■ ■ ■ ■ when a potential leak is first identified—see Potential leak first identified log entry (see page 184) when an identified leak appears to have stopped leaking—see Identified potential leak stops leaking log entry (see page 185) when a previously identified leak appears to have started leaking again —see Identified potential leak is leaking again log entry when a LeakHunter timeout has occurred—see LeakHunter timeout log entry Potential leak first identified log entry This type of LeakHunter log entry contains information about a potential leak when it is first identified: ■ ■ ■ ■ ■ ■ ■ ■ Current timestamp (when written to the log) Collection ID Class of the collection Allocation Method of the collection Allocation time of the collection Allocation stack trace of the collection Field name to which the collection was assigned Current size of the collection 184 Java Agent Guide . Each entry contains information about a potential leak. HashMap Current Size: 70 Chapter 12: Configuring LeakHunter and ErrorDetector 185 .Vector Allocation Method: sonOfLH_test.v5 Current Size: 44 Identified potential leak stops leaking log entry This type of LeakHunter log entry contains information about a potential leak that has stopped leaking: ■ ■ ■ ■ Current timestamp (when written to the log) Collection ID Class of the collection Current size of the collection Example: Log file entry if a potential leak stops leaking The following example illustrates an entry in the Java log file when a potential leak appears to have stopped leaking: 4/27/10 1:18:12 PM PDT Potential leak no longer appears to be leaking Assigned ID: createNewInstance-2815#3 Collection Class: java.util.testInst() Allocation Timestamp: 5/2/09 9:54:21 AM PDT Allocation Stack Trace: Unknown Field Name(s): sonOfLH_test.v4 sonOfLH_test.v3 sonOfLH_test.LeakHunter log file 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. HashMap Current Size: 79 LeakHunter timeout log entry This type of LeakHunter log entry contains the number of potential leaks that will continue to be tracked.util. Example: Log file entry when a timeout occurs LeakHunter timeout occurred at 4/27/10 1:32:12 PM PDT LeakHunter will only continue to track the 3 potential leaks Using LeakHunter For more information on how to use LeakHunter.Using LeakHunter Identified potential leak is leaking again log entry This type of entry contains information about a potential leak that has started leaking again: ■ ■ ■ ■ Current timestamp (when written to the log) Collection ID Class of the collection Current size of the collection Example: Log file entry if a potential leak resumes leaking The following example illustrates an entry in the Java log file when a potential leak appears to have started leaking again: 4/27/10 1:21:42 PM PDT Potential leak appears to be leaking again Assigned ID: createNewInstance-2815#3 Collection Class: java. 186 Java Agent Guide . see the Introscope Workstation User Guide. Introscope ErrorDetector allows you to monitor these serious errors as they occur in live applications. HTTP 404 errors originate in a web server instead of an application server. Some examples of common errors are: ■ HTTP errors (404.) Note: Occasionally. allowing you to monitor errors in the Introscope Workstation. ■ ■ ■ SQL statement errors network connectivity errors (timeout errors) backend errors (for example. ErrorDetector cannot detect the web server error through the agent. which can prevent users from completing web transactions.ErrorDetector ErrorDetector Introscope ErrorDector allows application support personnel to detect and diagnose the cause of serious errors. Types of errors CA Technologies has defined a set of criteria to describe "serious" errors. can’t send a message through JMS. Introscope ErrorDetector allows IT teams to: ■ ■ ■ ■ Determine the frequency of anomalous transactions Determine whether logged exceptions affect users See exactly where errors occurred within the transaction path Obtain the information needed to reproduce. 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. If this occurs. you can also use the Live Error Viewer to examine detailed information about each error. and deliver specific information about the root cause to developers. diagnose and eliminate serious errors Introscope ErrorDetector is integrated with Introscope. ErrorDetector considers both errors and exceptions to be errors. yet the error message lacks specific information that IT personnel need to isolate the root cause of the problem. based on information contained in the J2EE specifications. The most common type of error is a thrown exception. determine the frequency and nature of the errors. 500. can't write a message to the message queue) Chapter 12: Configuring LeakHunter and ErrorDetector 187 . When application errors do occur. etc. These kinds of application availability issues typically result in error messages to the user such as "404 Not Found" and others. Introscope defines a transaction as the invocation and processing of a service. it is the invocation and processing of a URL sent from a web browser. Moreover. it is the invocation and processing of a SOAP message. If you are using ProbeBuilder Wizard or Command-line ProbeBuilder. you can choose to ignore them. 188 Java Agent Guide . you can view: ■ ■ ■ error metric data in the Investigator live errors in the Live Error Viewer error details in the Error Snapshot. From the Workstation. enabling you to see exactly why and how serious errors occurred within the context of the transaction path.ErrorDetector What CA Technologies considers to be important errors might differ from what you consider important errors. If there are additional errors you want to track. ErrorDetector is installed automatically with your agent installation. all errors and transactions are persisted to Transaction Event Database.pbd with the agent installation.pbd and enable ErrorDetector functionality. The tracers in this PBD capture serious errors. In the context of a web application. you configure Introscope to use the errors. How ErrorDetector works Introscope includes a ProbeBuilder Directive (PBD) file called errors.pbd (in addition to any previously used PBD files). you must re-instrument the application using the errors. which shows component-level information on how the error occurred ErrorDetector is integrated with Transaction Tracer. you can use error tracers to create new directives to trace them. If you do not consider some of the errors ErrorDetector tracks to be important. Once ErrorDetector is installed. enabling you to spot trends through analysis of historical data.pbd file. The Introscope agent collects error information as defined in the errors. In the context of a web service. Enabling ErrorDetector in the Java Agent Enabling ErrorDetector in the Java Agent The property introscope. and re-instrument your applications. 3. IntroscopeAgent. Save the agent profile.profile. You can configure the agent to ignore errors you don’t want to track.agent. you can increase the throttle. Open the agent profile. set this property to false. Note: Changes to this property take effect immediately and do not require the managed application to be restarted. along with the "wildcard" asterisk character. Enter a new value for the introscope. 2. or specify the errors to ignore.throttle property. or any portion of the message. 4. If using ProbeBuilder Wizard.agent.enable property to true.errorsnapshots. The information you specify to "tag" the error can be the exact error message.enable should be set to true in the IntroscopeAgent. Configuring ErrorDetector options You can configure ErrorDetector to limit the maximum number of errors the agent sends to the Enterprise Manager. 3. see Using the ProbeBuilder wizard (see page 356). Chapter 12: Configuring LeakHunter and ErrorDetector 189 . 2.profile to enable the Java Agent to capture error data. the Java Agent is enabled to capture error data. By default. IntroscopeAgent.agent. Open the agent profile. Confirm the introscope. If you want to capture more errors during this time period. but be prepared to incur more overhead. copy the errors. For more information on ProbeBuilder Wizard.errorsnapshots. To enable/disbale ErrorDetector data capture in the Java Agent: 1. Save the agent profile.profile.pbd file to the <EM_Home>/config/custompbd directory.errorsnapshots. Enabling ErrorDetector captures error data without incurring much overhead. To change the ErrorDetector throttle (optional): 1. Note: To disable ErrorDetector. The out-of-the-box throttle is set at 10 errors per 15 seconds. For more information.Advanced error data capture To ignore certain errors (optional): 1. For the introscope. For more information. For example. For more information. For example. IntroscopeAgent. Note: Changes to this property take effect immediately and do not require the managed application to be restarted. the following ignore property would ignore any errors with the term "IOException" found anywhere within it: introscope. see ThisErrorReporter.errorsnapshots.errorsnapshots. Open the agent profile. define the value to be whatever information you think will identify that type of error. CA Technologies provides options for customizing the error detection mechanism to suit your needs. There are four tracers related to error data that can be used to create new ProbeBuilder Directive (PBDs) to track error data.agent. you can teach ErrorDetector about a new kind of error in your application or its infrastructure. Advanced error data capture Although ErrorDetector captures many common error types by default. see HTTPErrorCodeReporter. 2. You can use these tracers to create new directives for tracing errors. There are several special tracers that check for the presence of an error and capture (or construct) the error message.0=*IOException* 3. Save changes to the agent profile.profile. ■ ■ ■ ■ ExceptionErrorReporter reports standard exceptions. 190 Java Agent Guide . to ignore two types of errors. see ExceptionErrorReporter. MethodCalledErrorReporter reports if specific methods get called. add additional ignore properties sequentially.agent.agent. ThisErrorReporter reports current object as an error.ignore property.errorsnapshots. By placing these tracers at the right points.ignore.errorsnapshots.agent. New directives should be placed in the errors. For more information.ignore. To ignore additional errors.1=*HTTP Error Code *500* 4. the properties would look like this: introscope.0=*IOException* introscope. Defining new error types Errors are defined for ErrorDetector using PBDs. HTTPErrorCodeReporter captures HTTP error codes and associated error messages.ignore. located in the <Agent_Home>/wily directory.pbd file. see MethodCalledErrorReporter. If an exception is thrown. This is by far the most common definition of an error.EasyFidsException [set the init variable for your book] ThisErrorReporter "Exceptions|{packageandclassname}:Errors Per Interval" Note: In order to capture error messages. try using the ThisErrorReporter tracer. This tracer is most useful to put on the constructor of an exception class.. but it constructs the error message by calling toString() on the instrumented objects. this is an error.. For example: TraceOneMethodOfClass: com.. the tracer will only increment the Errors Per Interval metric.CheckingAccount cancelCheck MethodCalledErrorReporter "CustomerAccount:Canceled Checks Per Interval" This directive specifies that whenever the cancelCheck() method is called (for any reason).bank. If you do not know which methods may throw an exception or error. For example: In Java: TraceOneMethodWithParametersOfClass: ezfids. ThisErrorReporter The ThisErrorReporter tracer is similar to the MethodCalledErrorReporter. the ExceptionErrorReporter tracer must be used with a ".CustomerAccount getBalance ExceptionErrorReporter "CustomerAccount:Errors Per Interval" This directive specifies that any exception that is thrown from the getBalance() method on the CustomerAccount constitutes an error. In order to capture error messages.bank. this tracer treats it as an error and gets the error message from the exception.WithParameters" directive.WithParameters" directive. The error message simply states the class and method that was called.. Otherwise. Chapter 12: Configuring LeakHunter and ErrorDetector 191 . MethodCalledErrorReporter The MethodCalledErrorReporter tracer is used on methods where the very act of the method being called means that an error has occurred. the ThisErrorReporter tracer must be used with a ". For example: TraceOneMethodWithParametersOfClass: com.util.exception.Defining new error types ExceptionErrorReporter The ExceptionErrorReporter tracer is used to check for exceptions being thrown from the instrumented method. This tracer is good to use when you have a custom error management system based on your own exception types. Overuse of error tracing. Contact CA Support for more information. while minimizing overhead as much as possible.pbd for example usage. for codes 400 or higher in Java environments.Exception or java. applying ExceptionErrorReporter to every monitored method can result in a high volume of "false positives. The error message is determined by calling toString() on the InvalidPINException which generally returns the error message that the application developer specified. More help CA Professional Services can create new directives to trace specific errors or exceptions in your environment. you can access the support Web site directly at www.com/wily/support. It is a per interval counter that counts incidents of: ■ ■ HTTP response codes 400 or higher.HttpServletResponse subclass invocations of sendError or setStatus. javax. which you would not want to report as a serious problem. Using error tracer directives with caution Be judicious in using the tracers described in the previous sections.SQLException will not work.* packages so placing this tracer on java.http. 192 Java Agent Guide . Note: Introscope cannot instrument any code in the java. The best practice is to incur the overhead associated with error tracing to report only the most serious problems. The default errors.sql.ctor") of an InvalidPINException is called. this may cause a NumberFormatException. such as unrecoverable problems arising from backend systems. if a user enters "California" in a numeric field. for instance. this constitutes an error.ca.pbd is designed to report serious errors. If you are the registered support contact for your company.More help The directives specify that whenever the constructor ("init" or ".lang.servlet." For example. See errors. HTTPErrorCodeReporter The HTTPErrorCodeTracer tracer reports error codes from Servlets and JSPs. see the Introscope Workstation User Guide.Using ErrorDetector Using ErrorDetector For more information on how to use ErrorDetector. Chapter 12: Configuring LeakHunter and ErrorDetector 193 . . Chapter 13: Configuring Boundary Blame This section describes default Java Agent blame reporting behaviors. allows users to triage problems to something in to one of the application’s backends. JMS servers. How Introscope detects backends varies depending on the application . This capability. and LDAP servers are accessed through a socket. see the Introscope Workstation User Guide. Introscope will likely still detect backend activity because backends such as client/server databases. see Boundary Blame and Oracle backends (see page 146). This section contains the following topics: Understanding Boundary Blame (see page 195) Using URL groups (see page 196) Using Blame tracers (see page 201) Disabling Boundary Blame (see page 201) Understanding Boundary Blame Introscope’s Blame Technology works in a managed Java Application to enable you to view metrics at the front and backends of your application. If you have Oracle backends and do not use the Introscope SQL Agent. referred to as boundary blame. For database activity. If the SQL Agent is unavailable. and related configuration options. Introscope uses the SQL Agent to automatically detect backends. For information about how boundary blame is presented in the Introscope Investigator. Chapter 13: Configuring Boundary Blame 195 . showing how URL Groups are defined: introscope. delta should precede alpha in the keys parameter 196 Java Agent Guide .urlgroup.agent.gamma If you define URL Groups so some URLs fall into multiple groups.group.urlgroup.group.agent.beta.alpha. For example. or for mission-critical portions of your application.Using URL groups Using URL groups You can use URL Groups to monitor browser response time for sets of requests whose path prefix begins with a string you define.urlgroup.gamma introscope.beta.agent.keys defines a list of the IDs.urlgroup.gamma.com/testWar/burgerServlet?ViewItem&category= 11776&item=5550662630&rd=1 the path prefix is: /testWar You can define a URL group for any useful category of requests that can be derived from a URL’s path prefix. For example.pathprefix=/testWar introscope. you could define URL groups for each customer your application supports.gamma.urlgroup.urlgroup.group. depending on the form of your application URLs.agent.format=nofilter foo {host} bar {protocol} baz {port} quux {query_param:foo} red {path_substring:2:5} yellow {path_delimited:/:0:1} green {path_delimited:/:1:4} blue {path_substring:0:0} introscope.format=Examples Web App Defining keys for URL groups The property introscope. in this URL: http://burger1.agent. This enables you to monitor performance in the context of committed service levels.group.format=foo {host} bar {protocol} baz {port} quux {query_param:foo} red {path_substring:2:5} yellow {path_delimited:/:0:1} green {path_delimited:/:1:4} blue {path_substring:0:0} introscope.agent. For example.pathprefix=/examplesWebApp introscope.group.urlgroup. The following example defines the keys for three URL Groups: introscope. or for sub-applications.urlgroup. 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. for each major application. The path prefix is the portion of the URL that follows the hostname.agent.agent.beta.alpha.urlgroup. The key for a URL Group is referenced in other property definitions that declare an attribute of the URL group. or keys. of all of your URL Groups. Example: How URL group properties are defined The following example is an excerpt from a Java Agent profile.keys=alpha.beta.pathprefix=/nofilterWar introscope.group. The URL Group with the narrower membership should precede the URL Group with broader membership.agent. the order in which you list the keys for the URL Groups in the property is important.keys=alpha. and Support. Example: Mapping a group key to a URL path prefix This property definition assigns all requests in which the path portion of the URL starts with /testWar to the URL Group whose key is alpha: introscope.format=Alpha Group Chapter 13: Configuring Boundary Blame 197 . Define the name for a URL group The property introscope. If customers access services with this URL: http://genesystems/us/application_function/ where application_function corresponds to applications such as OrderEntry.group.agent. AcctService.urlgroup. The following example causes metrics for the URL Group with key alpha to appear in the Workstation under the name Alpha Group: introscope.urlgroup. the pathprefix property for each URL group would specify the appropriate application_function.groupKey.com/testWar/burgerServlet?Command=Order&item=5550662630 Example: Creating URL groups by application path A company that provides call center services could monitor response time for functional areas by setting up a URL Group for each application function. Typically.format determines the names under which response time metrics for a URL group whose key is groupKey appear in the Introscope Workstation.group.alpha. defining which requests fall within the URL Group.urlgroup.agent.Using URL groups Defining membership of each URL group The property introscope.alpha. the format property is used to assign a text string as the name for a URL.pathprefix=/testWar Requests that match the specified pathprefix include: http://burger1. Note: You can use the asterisk symbol (*) as a wildcard in pathprefix properties.groupKey.com/testWar/burgerServlet?ViewItem&category= 11776&item=5550662630&rd=1 http://burger1.group.group.agent.urlgroup.pathprefix specifies a pattern against which the path prefix of a URL is matched.agent. .com/mifi/loanApp. Using protocol as a URL group name To organize statistics for a URL group under names that reflect the protocol associated with requests. define the format parameter like this: introscope.. For example. https://uk..urlgroup. statistics for these requests would appear under the metric names us..Using URL groups Advanced naming techniques for URL groups (optional) You can derive a URL Group name from request elements such as the server port..com/mifi/loanApp..mybank... This is useful if your application modules are easily differentiated by inspecting the request. Using host as a URL group name To organize metrics for a URL group under names that reflect the hostname of the HTTP server associated with requests... define the format parameter like this: introscope.agent. the protocol.urlgroup.mybank. statistics for these requests would appear under the metric name https: https://us..com and uk.format={protocol} When format={protocol} statistics are grouped in the Investigator under metric names that correspond to the protocol portion of request URLs.alpha... or from a substring of the request URL.mybank.group.mybank..mybank..group.com/cgi-bin/mifi/scripts.alpha.com/cgi-bin/mifi/scripts.. This section describes advanced forms of the format property. https://uk... 198 Java Agent Guide .com respectively: https://us.mybank.format={host} When format={host}.agent.. group. statistics for these requests would appear under the name 9001.com/ws/shoppingServlet?ViewItem&category=734 &item=3772&tc=photo http://ubuy.agent. statistics are grouped under names that correspond to the port portion of request URLs.agent. For example.group.format= {path_substring:m:n} where m is the index of the first character.alpha.agent.format= {path_substring:0:3} Statistics for the following request would appear under the metric node /ht: http://research. https://uk.alpha.format={query_param:param} When format={query_param:param} statistics are grouped in Investigator under metric names that correspond to value of the parameter specified.agent.group.Using URL groups Using port as a URL group name To organize statistics for a URL group under names that reflect the port associated with requests.com:9001/cgi-bin/mifi/scripts.format={port} When format={port}. given this parameter definition: introscope.mybank..urlgroup.substring() method. https://us.alpha.mybank. and n is one greater than the index of the last character.agent. Using parameter as a URL group name To organize statistics for a URL group in Investigator under metric names that reflect the value of a parameter associated with requests.com:9001/cgi-bin/mifi/scripts.group.urlgroup. given this setting: introscope.com/htmldocu/WebL-12. String selection operates like the java.. For example..format= {query_param:category} Statistics for these requests would appear under the metric name "734" http://ubuy.com/ws/shoppingServlet?ViewItem&category=734 &item=8574&tc=photo Using a substring of the request path as a URL group name To organize statistics for a URL group under names that reflect a substring of the path portion of request URLs.urlgroup.alpha.urlgroup...html Chapter 13: Configuring Boundary Blame 199 . For example. Requests without parameters are listed under <empty>.lang.String. define the format parameter like this: introscope.alpha.group. define the format parameter like this: introscope..... define the format parameter like this: introscope.urlgroup.. group.agent. define the format parameter like this: introscope. 1=userid. given this setting: introscope. in this example.alpha. and 5=pageid Using multiple naming methods for URL groups You can combine multiple naming methods in a single format string. For example. the forward slash (/) counts as a segment the segment count starts at 0 The segments as delimited by the slash character in the URL example are: 0=/. 1=userid. m is the index of the first segment to select.urlgroup.format=red {host} orange {protocol} yellow {port} green {query_param:foo} blue {path_substring:2:5} indigo {path_delimited:/:0:1} violet {path_delimited:/:1:4} ultraviolet {path_substring:0:0} friend computer 200 Java Agent Guide .sessionid/pageid would appear under the metric name /pageid Note that: ■ ■ a delimiter character.sessionid. as shown below: introscope.buyitall. 2=/. and n is one greater than the index of the last segment to select.agent. 4=/. given this setting: introscope.urlgroup.group. 2=.format= {path_delimited:delim_char:m:n} where delim_char is the character that delimits the segments in the path.alpha.agent.format={path_delimited:/:2:4} statistics for the requests of this form: http://www.group.agent.com/userid. For example.alpha.urlgroup.alpha.group.format={path_delimited:/.:3:4} statistics for requests of the form shown above would appear under the metric name sessionid with he segments as delimited by the slash and the comma in the URL example are: 0=/. 3=sessionid. and 3=pageid You can specify multiple delimiters as necessary.urlgroup.Using URL groups Using a delimited portion of the request path as a URL group name To organize statistics for a URL group under names that reflect a character-delimited portion request URL path. Using URLGrouper gives you a starting point for defining your own URL Groups.agent. Disabling Boundary Blame By default. based on the contents of the Web server log file. Using Blame tracers You can use tracers to explicitly mark the frontends and backends in your application. The asterisk symbol (*) can be used with URLGrouper as a wildcard. see Using Blame Tracers to mark blame points (see page 143). Open a command shell.profile.Using Blame tracers Running the URLGrouper URLGrouper is a command-line utility that analyzes a web server log file in Common format. Enter this command java -jar urlgrouper.type. copy the property statements produced by URL Grouper into the IntroscopeAgent. To disable boundary blame in favor of the component-level blame implemented in Introscope versions earlier than 7. To configure the proposed URL Groups. Chapter 13: Configuring Boundary Blame 201 .jar logfile where logfile is the full path to your web server log file.type (see page 272) property described in introscope. 3. 2. Property definitions for a set of URL Groups are output to STDOUT. use the introscope.blame.agent. URLGrouper outputs a set of property settings for potential URL Groups. To run URLGrouper: 1.0. 4. Boundary Blame is enabled. For more information. Note: You can use the URLGRouper utility to analyze your Web server log file.blame. . Without a clamp in place in certain extreme situations.transactiontrace. Introscope offers two types of automatic Transaction Tracing: ■ ■ Transaction Trace sampling that is enabled by default.componentCountClamp=5000 Chapter 14: Configuring Transaction Trace Options 203 . Without the clamp.profile file: ■ introscope. Transaction Tracer views this as one transaction. based on your URL groupings Configurable automatic trace sampling that gathers trace information regardless of URL groupings Transaction Trace component clamp Introscope now sets a clamp (set by default to 5. This allows you to clamp a component heavy transaction the grows beyond expected component counts—for example when a servlet executes hundreds of object interactions and backend SQL calls. and the trace stops. the JVM can run out of memory before the trace completes. continuing infinitely. The property for clamping transactions is located in the IntroscopeAgent.Chapter 14: Configuring Transaction Trace Options This section has information about default Transaction Tracing behaviors and related configuration options.000 components) to limit the size of traces.agent. warnings appear in the log. This section contains the following topics: Controlling automatic Transaction Tracing behavior (see page 203) Configuring cross-process Transaction Tracing (see page 205) Extending transaction trace data collection (see page 205) Disabling the capture of stalls as Events (see page 208) Controlling automatic Transaction Tracing behavior Automatic Transaction Tracing enables historical analysis of potentially problematic transaction types without explicitly running Transaction Traces. When this limit is reached. For more information about viewing these traces. see the Introscope Workstation User Guide.enabled Set to false to disable Transaction Trace sampling. Before changing the defaults for the sampling. The Enterprise Manager will push this configuration to all agents connected to it. ■ introscope. To configure automatic trace sampling.sampling. see Transaction tracing (see page 326). the memory required for Transaction Traces may increase. the maximum heap size for the JVM may need to be adjusted accordingly.sampling. As appropriate you can disable this behavior. Note: These properties are located in the Enterprise Manager properties file. The default value is true. The default number of transactions is 1. Transaction trace sampling Transaction trace sampling is enabled by default.transactiontracer.transactiontracer. Warning: If the Transaction Trace component clamp size is increased. For more information on Transaction Trace properties.count Specifies the number of transactions to trace.interval. modify these properties: ■ introscope.agent. consider the potential for increased load in the Enterprise Manager with higher sampling rates. In rare instances. The default interval is every 2 minutes.transactiontracer. 204 Java Agent Guide . See the Introscope Configuration and Administration Guide for more information. ■ introscope.seconds Specifies the length of time to trace the number of transactions you specify. or else the managed application may run out of memory.perinterval and sampling. during the interval you specify. during a time interval you specify.Controlling automatic Transaction Tracing behavior For traces producing clamped components—those exceeding the CountClamp—traces are marked with an asterisk and have a tool tip assiociated with them that provides more information about the clamped metrics. You can also configure these properties in an agent.perinterval. When you configure automatic trace sampling. Configuring these properties in the agent will overwrite the configuration set by the Enterprise Manager for an individual agent.interval properties.sampling.agent.agent. you specify the number of transactions to trace. by default. and so forth. To capture this information. and session attributes.0 and pre-9. duration. For more information about cross-process transaction tracing. request parameters.0 agent. including User ID data for Servlet and JSP invocations. see: ■ ■ Cross-process Transaction Tracing in WebLogic (see page 83) Cross-process Transaction Tracing in WebSphere (see page 99) Important: Cross-process transaction tracing is available only with Introscope 9. See the Introscope Workstation User Guide. Configuring cross-process Transaction Tracing The Introscope Java Agent can trace transactions that cross JVM boundaries on WebLogic Server 9 or later. timestamp. uses slightly more memory than the 7. URL. for instance servlets to EJBs. you must define the criteria in the IntroscopeAgent. Extending transaction trace data collection cts basic Transaction Trace data such as Domain/Host/Process/Agent. you may need to increase the heap allocation when you install the agent. and other transaction trace data such as HTTP request headers.Configuring cross-process Transaction Tracing Agent heap sizing The agent uses Java heap memory to store collected data. on average. contact CA Professional Services for the appropriate agent JVM heap settings.0 agents.0 agents.1 —if the environment is comprised of compatible versions of the same vendor’s application server. the 8. or WebSphere 6. You may see an increase of up to 100 MB over your 7. as well as asynchronous transactions. If your application’s heap is highly utilized. For more information. Cross-process transaction tracing does not function between 9.x average runtime heap usage. Chapter 14: Configuring Transaction Trace Options 205 . You can view the agent CG heap usage in the CG Heap overview. If you are operating a high-performance Introscope environment. see Transaction Trace component clamp (see page 203) and Transaction trace sampling (see page 204). Cross-process transaction tracing is supported for synchronous transactions. If monitored applications are characterized by very deep or long lasting transactions. the agent’s Transaction Trace sampling may require more heap memory than previous Introscope versions. You can configure the Introscope Transaction Tracer to obtain additional information. For example.x agent because of performance improvements to CPU and response times overhead.profile. Introscope can record this servlet request information: ■ ■ ■ request headers request parameters session attributes To record this servlet request information for your managed application. to configure Java Agent settings to collect User ID data. you must first obtain information on how your managed application specifies user IDs.getRemoteUser() HttpServletRequest. Introscope Transaction Tracer can identify User IDs from managed applications that store User IDs in one of these ways: ■ ■ ■ HttpServletRequest. see Configuring Agent to collect additional transaction trace data (see page 207). see Configuring Agent to collect additional transaction trace data (see page 207) to configure Java Agent settings to collect this data. where returned object is either a String representing the UserID. you can collect transaction trace data that matches user-configurable parameters.getValue (String key). About servlet request data Using Introscope. 206 Java Agent Guide . or an Object whose toString() returns to the UserID If your managed application stores User IDs using one of these methods. For example.Extending transaction trace data collection About User ID data To configure the Java Agent to identify User IDs for Servlet and JSP invocations. The Application Architect who developed the managed application can probably provide this information. you can specify the Introscope Agent to collect transaction trace data for transactions that contain the User-Agent HTTP request header.getHeader (String key) HttpSession. transactiontracer. Collecting user id data To configure the Java Agent to identify User IDs ■ Configure the properties that correspond to the method your managed application uses to store User IDs. To configure the Java Agent to collect additional transaction trace data: 1. and define a key string for the second property: introscope.method=HttpServletRequest.userid.getRe moteUser ■ For HttpServletRequest.userid. Locate the Transaction Tracer properties under the Transaction Tracer Configuration heading.profile.transactiontracer. IntroscopeAgent. Note: Ensure that only one set of properties are not commented. Open the agent profile.userid.agent.getVa lue introscope.transactiontracer.method=HttpServletRequest. or the wrong properties might be used. uncomment the following pair of properties.getRemoteUser(). and define a key string for the second property: introscope. or HTTP session attributes. ■ For HttpServletRequest.key=<application defined key string> Chapter 14: Configuring Transaction Trace Options 207 .getValue (String key). HTTP request headers. 2. HTTP request parameters.agent.userid.transactiontracer.Extending transaction trace data collection Configuring Agent to collect additional transaction trace data You can configure the Java Agent to collect additional transaction trace data such as User ID.getHeader (String key).agent. uncomment the property: introscope.method=HttpServletRequest.key=<application defined key string> ■ For HttpSession.agent.userid.agent.transactiontracer.getHe ader introscope. uncomment the following pair of properties. parameter2 3.agent.parameter.parameter. Note: Generated stall metrics are always available. but stall events are only visible if Introscope Error Detector is installed. To specify the HTTP request parameters for which to collect transaction trace data.headers=User-Agent 2. CA Technologies has had great success with this default value and recommends no change unless there is a good reason.httpsession. in a comma-separated list.agent. You can disable the capture of stalls as events.httprequest. Disabling the capture of stalls as Events By default. or change the frequency with which the agent checks for stalls using these properties: ■ ■ introscope.stalls. and will be visible in the Errors TypeView. Introscope captures transaction stalls as events in the Transaction Event database. or in the historical query viewer by querying for "type:errorsnapshot". uncomment this property and specify the HTTP session attribute(s) to track. in a comma-separated list: #introscope.stalls. and generates stall metrics from the detected events.transactiontracer. the introscope. uncomment this property and specify the HTTP request parameter(s) to track.Disabling the capture of stalls as Events Collecting servlet request data To record servlet request information such as HTTP request headers and parameters: 1.transactiontracer. Stall metrics are generated for the first and last method in the transaction. Because of timing complications. Users can view stall Events and associated metrics in the Workstation’s Historical Event Viewer.parameters=paramete r1.agent. Stalls are stored as ordinary errors. Note: By default. uncomment this property. change the stall threshold.agent.thresholdseconds specifies the minimum threshold response time at which time a transaction is considered stalled. To specify the HTTP session attributes for which to trace data.d eptID 4. and specify the HTTP request header(s) to track.stalls. introscope. 208 Java Agent Guide .agent.transactiontracer.resolutionseconds property is set to 30 seconds.httprequest.parameter. it is generally not effective to set stall resolution below 15 seconds. for example: #introscope. in a comma-separated list: #introscope. To specify the HTTP request headers for which to collect transaction trace data.resolutionseconds specifies the frequency that the agent checks for stalls.attributes=cartID.agent. Restart the managed application. the SQL Agent converts this SQL query: SELECT * FROM BOOKS WHERE AUTHOR = 'Atwood' to this normalized statement: SELECT * FROM BOOKS WHERE AUTHOR = ? Chapter 15: Configuring the Introscope SQL Agent 209 . The SQL Agent provides visibility into the performance of individual SQL statements in your application by tracking the interaction between your managed application and your database. In the same way that the Java Agent monitors applications. such as credit card numbers. monitoring the application or database with very low overhead. The SQL Agent is non-intrusive.Chapter 15: Configuring the Introscope SQL Agent This section has instructions for configuring Introscope SQL Agent. This section contains the following topics: The SQL Agent overview (see page 209) The SQL Agent files (see page 210) SQL statement normalization (see page 210) Turning off statement metrics (see page 218) Turning off Blame metrics (see page 218) SQL metrics (see page 219) The SQL Agent overview The Introscope SQL Agent reports detailed database performance data to the Enterprise Manager. the SQL Agent summarizes performance data by stripping out transaction-specific data and converting the original SQL statements into Introscope-specific normalized statements. this process also protects the security of your data. For example. Since normalized statements do not include sensitive information. the SQL Agent monitors SQL statements. To provide meaningful performance measurements down to the individual SQL statement level. If technologies like EJB 3. If you change the location of the /ext directory.agent.The SQL Agent files Similarly. SQL Agent converts this SQL update statement: INSERT INTO BOOKS (AUTHOR. Metrics for normalized statements are aggregated and can be viewed in the JDBC node of the Workstation Investigator.pbd Note: By default. The files providing SQL Agent functionality are: ■ ■ wily/ext/SQLAgent.jar wily/sqlagent. the problem could be in how the SQL statement was written. 'The Robber Bride') to this normalized statement: INSERT INTO BOOKS (AUTHOR. ?) Note: Only text within quotation marks ('xyz') is normalized. leading to poor performance as well as other system problems. the number of SQL Agent metrics should approximate the number of unique SQL statements. You can change the location of the agent extension directory with the introscope. If your SQL Agent is showing a large and increasing number of unique SQL metrics even though your application uses a small set of SQL statements. agent extensions like the SQLAgent. Long SQL statements can contribute to a metric explosion in the agent.directory property in the agent profile. TITLE) VALUES ('Atwood'.jar file are installed in the wily/ext directory.extensions. How poorly written SQL statements create metric explosions In general. 210 Java Agent Guide . the likelihood of long unique SQL statements increases. SQL statement normalization Some applications may generate an extremely large number of unique SQL statements. TITLE) VALUES (?. There are several common situations in which SQL statements can cause metric explosions. be sure to move the contents of the /ext directory as well.0 are in use. The SQL Agent files The SQL Agent is included in all agent installations. . if you have a SQL statement like this: "/* John Doe." the SQL Agent creates a metric with the comment as part of the metric name: "/* John Doe.. txn=? */ select * from table. however. txn=? '*/ select * from table. if you open the Investigator to view the metrics under Backends|{backendName}|SQL|{sqlType}|sql." Example: Temporary tables or automatically generated table names Another potential cause of metric explosion can be the result of applications that reference temporary tables or tables that have automatically generated names in SQL statements. Therefore. the SQL Agent creates a unique metric. user ID=?. potentially causing a metric explosion. user ID=?. This problem can be avoided is by putting the SQL comment in single quotes. The SQL Agent. txn=? */ select * from table..SQL statement normalization Example: Comments in SQL statements One common reason for metric explosion is caused by how comments are used in SQL statements.." 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. Chapter 15: Configuring the Introscope SQL Agent 211 .. user ID=?. does not parse the comment string when it captures the SQL statement.. For example. For example.. for each unique user ID. 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.." The SQL Agent then creates the following metric where the comment no longer causes a unique metric name: "/* ? */ select * from table. you might see a metric similar to this: SELECT * FROM TMP_123981398210381920912 WHERE ROW_ID = ? This SQL statement is accessing a temporary table that has a unique identifier appended to the table name. as shown: "/*' John Doe. CMMT_STATUS_ID. CURRENT) In studying the code. TO CAROLTON.SQL statement normalization Example: Statements that generate lists of values or insert values Another common cause of metric explosion are SQL statements that generate lists of values or do mass modification of values. USER_ID. the SQL Agent converts this SQL query: SELECT * FROM BOOKS WHERE AUTHOR = 'Atwood' to this normalized statement: SELECT * FROM BOOKS WHERE AUTHOR = ? Metrics for normalized statements are aggregated and can be viewed in the Workstation Investigator. _ ". 212 Java Agent Guide . ?. the placement of the quotes for countries results in people's e-mail addresses getting inserted into SQL statements.LAST_UPDATE_TS) VALUES (?. COMMENTS_DSC. _ " recurs as a dizzying array of cities. the SQL Agent includes the following normalizers for use: ■ ■ ■ ■ Default SQL statement normalizer (see page 212) Custom SQL statement normalizer (see page 213) Regular expression SQL statement normalizer (see page 214) Command-line SQL statement normalizer (see page 218) Default SQL statement normalizer The standard SQL statement normalizer is on by default in the SQL Agent. SQL statement normalization options To address long SQL statements. For example. ?. if you are investigating a potential metric explosion. ?. It normalizes text within single quotation marks ('xyz').TO CAROLTON. For example. In addition. ?. you notice that "CHANGE CITY FROM CARROLTON. you notice CHANGE COUNTRY results in a long list of countries. CMMT_LIST_ID. creating unique metrics that could be the source of the metric explosion. CARD_ID. "CHANGE CITY FROM CARROLTON. 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. Similarly. LOCATION_ID. ?. ?. assume tou have been alerted to a potential metric explosion and your investigation brings you to a review of this SQL statement: #1 INSERT INTO COMMENTS (COMMENT_ID. CMMT_TYPE_ID.CMMT_CATEGORY_ID. ?. testNormalizer1 is used as an example. locate and set the following property: introscope. In the IntroscopeAgent. The {actualSQLStatement} is normalized by the SQL normalizer. for example metrics under the Backends|{backendName}|SQL|{sqlType}|{actualSQLStatement} node.sqlagent.trace. 4.wily. Chapter 15: Configuring the Introscope SQL Agent 213 . Whatever you specify as the value of this key.normalizer. other general keys are required. Place the following keys in the manifest of the created extension: ■ com-wily-Extension-Plugins-List:testNormalizer1 Note: The value of this key can be anything. In this instance. you create a JAR file containing a normalization scheme that is implemented by the SQL Agent.sqlagent. These keys are the type you would use to construct any extension file. 2. which are detailed in step 2 below.agent. for example normalizer1.agent. The extension file you create relates to database SQL statement text normalization. Create an extension JAR file. for your extension to work. Making a JAR extension file involves creating a manifest file that contains specific keys for the SQL normalizer extension.normalizer.SQL statement normalization Custom SQL statement normalizer The SQL Agent allows users to add extensions for performing custom normalization. ■ ■ ■ 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. Place the extension file you created in the <Agent_Home>/wily/ext directory.ISqlNormalizer interface.extension Set the property to the com-wily-Extension-Plugin-{plugin}-Name from your created extension’s manifest file. The value of this property is not case sensitive.introscope. To do so. ■ com-wily-Extension-Plugin-testNormalizer1-Entry-Point-Class: <Thefully-qualified classname of your implementation of ISQLNormalizer> 3.extension=normalizer1 Important: This is a hot property. To apply a SQL statement normalizer extension: 1. use it in the following keys as well. However. Note: The entry point class for the SQL normalizer extension file has to implement com. Changes to the extension name will result in re-registration of the extension.profile. For example: introscope.agent. profile. 2. set this property to RegexSqlNormalizer. Exceptions If the extension you created throws an exception for one query. the extension is disabled.extension=RegexSqlNormalizer Specifies the name of the SQL normalizer extension that will be used to override the preconfigured normalization scheme. you can optionally add the following property to set the error throttle count: introscope. However. an ERROR message is logged. after five such exceptions are thrown. Save the IntroscopeAgent. In the IntroscopeAgent. For examples on how to use the regular expression SQL statement normalizer. see Regular expression SQL statement normalizer examples (see page 216).SQL statement normalization 5. Regular expression SQL statement normalizer The SQL Agent ships with an extension that normalizes SQL statements based on configurable regular expressions (regex). When enabling the regular expressions extension. 7. the default SQL statement normalizer uses the default normalization scheme for that query.extension.profile.normalizer. When this happens. However. Note: If the errors thrown by the custom normalizer extension exceeds the error throttle count. 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.agent. saying an exception was thrown by the extension.normalizer. To apply the regular expressions extension: 1. the StatementNormalizer uses the default normalization scheme for that query and logs an INFO message saying the extension returned a null value.jar. the StatementNormalizer stops logging messages. and a DEBUG message is logged with stack trace information. Null or empty strings If the extension you created returns a null string or empty string for a query. Restart your application.agent. Open the IntroscopeAgent.sqlagent. 6. RegexNormalizerExtension.sqlagent. This file.profile. after five such null or empty strings have been returned. 214 Java Agent Guide . is located in the <Agent_Home>/wily/ext directory. but will attempt to continue to use the extension.errorCount For more information about errors and exceptions. see Exceptions (see page 214). Locate and set the following properties: ■ introscope. key1.matchFallThrough=false If this property is set to true. This output is then fed to key2 regex.agent.key1.regex. ■ introscope. Chapter 15: Configuring the Introscope SQL Agent 215 . if the SQL strings match multiple key groups.regex.regex.agent.sqlagent. The output from key2 regex is Select * from X where Y.regex.pattern=A This property specifies the regex pattern that is used to match against the SQL statements. The default value is false.normalizer. For example. This property is required to enable the regular expressions extension.regex.regex.agent.regex.sqlagent.regex.sqlagent.Regex package classes can be used here.agent. The implementation is chained.sqlagent. There is no default value.normalizer. This property is not required to enable the regular expressions extension.matchFallThrough is false. the normalized SQL output from group1 is fed as input to group2.key1.key1.normalizer.normalizer.normalizer.util.normalizer.sqlagent.agent.agent.sqlagent.SQL statement normalization ■ introscope. All valid regular expressions allowed by the java.agent.normalizer. The MatchFallThrough property does not enable or disable the extension.keys=key1 This property specifies the regex group keys.agent.sqlagent.keys=key1.sqlagent. ■ introscope.regex.agent. which are evaluated in the order they are listed.matchFallThrough is true.sqlagent.replaceFormat=B This property specifies the replacement string format. Hence. All valid regex allowed by the java.agent.regex.pattern=B introscope. Output from that regex will be Select * from X where B.replaceFormat=Y If introscope. and so on. This property is required to enable the regular expressions extension.caseSensitive=false This property specifies whether the pattern match is case sensitive. SQL strings are evaluated against all the regex key groups.key2 introscope. This property is required to enable the regular expressions extension. then the SQL is normalized against key1 regex first.normalizer.agent. If the property is set to false. There is no default value. then the SQL is normalized against key1 regex.key2. Note: This property is not required to enable the regular expressions extension.key1. you would set the following properties: introscope.sqlagent. the normalized SQL output from that group is returned. The output from that regex is Select * from X where B. ■ introscope.normalizer. This SQL will be returned. if you had a SQL string like: Select * from A where B. as soon as a key group matches the SQL string.normalizer.regex.sqlagent.util.regex.replaceFormat=X introscope.key2. ■ introscope.pattern=A introscope.normalizer.agent. If introscope. There is no default value.sqlagent. This will be the SQL returned.normalizer.Regex package classes can be used here. For example. . 3. Example 1 Here is a SQL query before regular expression SQL statement normalization: INSERT INTO COMMENTS (COMMENT_ID.?.replaceAll=false If this property is set to false. Save the IntroscopeAgent.normalizer. ‘’CHANGE CITY FROM CARROLTON.?.replaceAl is true.replaceAl is false.sqlagent. The statement normalizer will then use the default normalization scheme. it will replace all occurrences of the matching pattern in the SQL with the replacement string.agent.normalizer. ?. Important: All properties listed above are hot.sqlagent. CMMT_TYPE_ID. CARD_ID.key1. LAST_UPDATE_TS) VALUES(?. The default value is false. ?. ?. TO CAROLTON. If introscope. ?. ?. it will replace the first occurrence of the matching pattern in the SQL with the replacement string.agent.agent.agent.normalizer. ?. CHANGE CITY FROM ( ) 216 Java Agent Guide . Regular expression SQL statement normalizer examples The three examples below can help you understand how to implement the regular expression SQL statement normalizer.regex. ?.. if you have a SQL statement like Select * from A where A like Z. If this property is set to true.regex.profile.normalizer.replaceFormat=X If introscope. ?. CMMT_LIST_ID. CMMT_CATEGORY_ID.regex. ?. it will result in a normalized SQL statement: Select * from X where A like Z.SQL statement normalization ■ introscope.regex.key1. _ ". you would set the properties as follows: introscope. ?.sqlagent.regex.agent. LOCATION_ID. Note: If none of the regular expression patterns match the input SQL.sqlagent. meaning changes to these properties take effect once you have saved the IntroscopeAgent.key1.pattern=A introscope.key1.. the RegexNormalizer will return a null string. ?.) VALUES (?. CURRENT) Here is the desired normalized SQL statement: INSERT INTO COMMENTS (COMMENT_ID.profile. it will result in a normalized SQL statement: Select * from X where X like Z.COMMENTS_DSC. USER_ID.sqlagent.key1.normalizer.CMMT_STATUS_ID. This property is not required to enable the regular expressions extension. key2 introscope.sqlagent.def.replaceAll=false introscope.normalizer..normalizer.agent..regex.regex.agent. you could set the properties like this: introscope.agent.regex.normalizer.agent.caseSensitive=false introscope.sqlagent.regex.regex.sqlagent.sqlagent.*)''(CHANGE CITY FROM \\().normalizer.sqlagent.agent.sqlagent.caseSensitive=true introscope.sqlagent.normalizer.regex.normalizer. ResID1.sqlagent. n times OR CustID1=.sqlagent.normalizer.sqlagent.regex.caseSensitive=false Example 3 If you want to normalize a SQL statement like: Select .key1.regex.replaceFormat=? introscope.sqlagent.key1.*)(VALUES.normalizer.replaceAll=true introscope.normalizer.regex.regex.key1..regex.*(\\)) introscope.agent.normalizer.normalizer.normalizer.)(.sqlagent. CustID1 where ResID1=.key1.sqlagent.pattern=(CustID)[1-9] introscope.agent.caseSensitive=true Chapter 15: Configuring the Introscope SQL Agent 217 .extension=RegexSqlNormalizer introscope.regex.normalizer.replaceAll=true introscope.sqlagent.normalizer.agent.key2.agent..regex..replaceFormat=$1 .normalizer.default.sqlagent.def.normalizer.agent.normalizer.key2.keys=default.regex.agent.sqlagent.sqlagent.sqlagent.matchFallThrough=true introscope.def.keys=key1 introscope.profile file to result in the normalized SQL statement shown above: introscope.sqlagent.agent.normalizer.key1.extension=RegexSqlNormalizer introscope.agent.regex.pattern=(INSERT INTO COMMENTS \\(COMMENT_ID.pattern='[a-zA-Z1-9]+' introscope..profile file to resultin the normalized SQL statement shown above: introscope..key1.default.agent.) $3$4 $5 introscope.normalizer.regex.agent.normalizer.replaceFormat=$1 introscope.normalizer.sqlagent.normalizer.agent.normalizer.regex.pattern=(ResID)[1-9] introscope.sqlagent.caseSensitive=false Example 2 Here is a SQL query before regular expression SQL statement normalization: SELECT * FROM TMP_123981398210381920912 WHERE ROW_ID = Here is the desired normalized SQL statement: SELECT * FROM TMP_ WHERE ROW_ID = Here is the configuration needed to the IntroscopeAgent.normalizer.normalizer.replaceAll=false introscope.agent.default.default.agent.matchFallThrough=true introscope.regex.normalizer.sqlagent.replaceFormat=$1 introscope.sqlagent.sqlagent.regex.sqlagent.sqlagent.agent.regex.regex.agent.regex.def introscope.sqlagent.agent.key2.agent.key1.def.regex.regex.key2. OR n times.regex.replaceFormat=$1 introscope.agent.normalizer.SQL statement normalization Here is the configuration needed to the IntroscopeAgent.regex.agent.agent.agent.pattern=(TMP_)[1-9]* introscope.agent.replaceAll=true introscope..sqlagent.agent.key1. OR ResID2=.normalizer.matchFallThrough=true introscope.keys=key1. Note: You will not lose backend or top-level JDBC metrics if you turn off statement metrics.agent.Turning off statement metrics Command-line SQL statement normalizer If the regular expression SQL normalizer is not in use.pbd file. use the following command-line command to normalize your SQL statements: -DSQLAgentNormalizeDoubleQuoteString=true Important: You can use the regular expressions SQL normalizer instead of this command to normalize SQL statements in double quotes. To turn off statement metrics: 1. See Regular expression SQL statement normalizer (see page 214) for more information. 4. 2. Remove {sql} from the trace directives you wish to turn off. 3. Blame metric data is collected by default. Note: If Blame metric generation is turned off. You can turn off SQL statement metrics in the SQL Agent. However.pbd file.useblame=false Save your changes to the IntroscopeAgent. 3.profile.sqlagent. introscope. to reduce data overhead and reduce the number of metrics generated.sqlagent. Change the value to false: introscope. To turn off Blame metric data generation: 1. Open the sqlagent. Locate the property. the SQL Agent data will not appear in Transaction Tracer viewer. 5.profile. Restart the managed application. Turning off statement metrics Some applications may generate an extremely large number of unique SQL statements. you can turn Blame metric data off for the SQL Agent.useblame. 218 Java Agent Guide . Save the sqlagent. Turning off Blame metrics In a standard deployment of the SQL Agent. causing a metric explosion in the SQL Agent. 2. Open the IntroscopeAgent. and you have SQL statements that enclose values in the where clause with double quotes (" ").agent. A connection is opened when a driver’s connect() method is invoked.SQL metrics SQL metrics The SQL Agent metrics appear under the Backends node in the Introscope Workstation Investigator. When the Connection objects are garbage collected. Note: Instrumented XADataSources may not report commit or rollback metrics. The SQL Agent maintains weak references to Connections in a Set. i. Note: Average Response Time (ms) will only display queries that return a data reader. This metric represents the average time spent in the data reader’s Close() method. This metric represents the average time spent processing a ResultSet from the end of the executeQuery() call to the invocation of the ResultSet's close() method. ■ Average Result Processing Time (ms)—The average processing time of a query. the counts reflect the changes.e. Other instrumented DataSources may not report commit or rollback metrics unless those metrics contain data. and closed when the connection invocation is closed via the close() method. Chapter 15: Configuring the Introscope SQL Agent 219 . SQL statement metrics can be found under the Backends|<backendName>|SQL node. queries executed via the ExecuteReader() method. Metric types specific to SQL data include: ■ Connection Count—The number of live connection objects in memory. . For more information on the Sun JMX specification.x (see page 226) Introscope Java Agent JMX support Introscope can collect management data that application servers or Java applications expose as JMX-compliant MBeans. 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| Chapter 16: Enabling JMX Reporting 221 . Introscope supports the collection of JMX information on the following application servers: ■ ■ ■ ■ ■ Glassfish JBoss Tomcat WebLogic WebSphere Introscope supports any MBean built to the Sun JMX specification. and present the JMX data in the Investigator metric tree.Chapter 16: Enabling JMX Reporting This section contains information about enabling the Java Agent to report JMX data. This section contains the following topics: Introscope Java Agent JMX support (see page 221) Default JMX metric conversion process (see page 222) Using primary key conversion to streamline JMX metrics (see page 223) Managing metric volume with JMX filters (see page 224) Configuring JMX reporting (see page 225) Enabling JSR-77 data for WAS 6. 0.0 JMX metrics WebLogic versions prior to WebLogic 9. or You have not configured valid primary keys. This method is used to convert an MBean if: ■ ■ You use WebLogic 9. Domain>|<Host>|<Process>|AgentName|JMX|<domain name>| <key1>=<value1>|<key2>=<value2>:<metric> For example. Introscope displays both the name and the value of the attribute. Default JMX metric conversion process This section describes the process Introscope uses. including active effective configuration DomainRuntimeServiceMBean: domain-wide runtime metrics EditServiceMBean: allows user to edit persistent configuration Introscope polls only the RuntimeServiceMBean. as described in Using primary key conversion to streamline JMX metrics (see page 223). and because it contains most of the data expected to be relevant.primarykeys. given a WebLogic MBean with these characteristics: ■ ■ ■ Domain name: WebLogic Key/Value pairs: category=server.Default JMX metric conversion process Introscope support for WebLogic 9. In the default conversion method.agent. WebLogic 9.0 provided only a single MBeanServer as a source of JMX metrics. because it is the only one that supports local access (an efficiency issue).0 provides three: ■ ■ ■ RuntimeServiceMBean: per-server runtime metrics.profile property introscope. 222 Java Agent Guide . and lists the pairs alphabetically in the metric tree.name. type=jdbc Metric names: connections If no primary keys are specified in the IntroscopeAgent. the MBean attributes above would be converted to the following Introscope metric: <Domain>|<Host>|<Process>|AgentName|JMX|Weblogic|category=server|type=jdbc:c onnections Note that the key/value pairs are displayed alphabetically in the Introscope metric. Note: If you specify primary keys that no MBeans match.jmx. by default. Introscope will use the default conversion method. to convert JMX Metrics for display in the Investigator. and a Name key that specifies the name of the resource the MBean represents.name. metrics are listed alphabetically under the JMX node in Investigator. Values are case-sensitive.Using primary key conversion to streamline JMX metrics Using primary key conversion to streamline JMX metrics You can optionally configure the order in which metrics appear under the JMX node by defining.jmx.name. If you do not configure primary key conversion. The key/value pairs in an ObjectName can vary for different types of MBeans.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 222). a Primary Key—those parts of an MBean’s ObjectName that uniquely identify it. Introscope converts and presents the MBeans identified by value of the introscope. and allows you to control order of key/value pair information in the generated metrics.agent. given a WebLogic MBean with these characteristics: ■ ■ ■ Domain name: WebLogic MBean ObjectName key/value pairs: category=server.jmx. As a result. For example. Values in the primarykeys property should specify the parts of an MBeans JMX ObjectName that uniquely identify an MBean. The behavior is configured in the introscope. type=jdbc Metric names: connections If you configure: introscope. With the default conversion.primarykeys property according to these rules: ■ ■ ■ Only the key value information is displayed. Chapter 16: Enabling JMX Reporting 223 . so for WebLogic 9. For example.jmx. in the agent profile. Introscope converts the JMX data as described in Default JMX metric conversion process (see page 222).0 does not have universally available primary keys.agent. Values are ordered in the sequence defined in the primarykeys property.primarykeys property in the agent profile. a WebLogic MBean’s ObjectName contains a Type key that specifies the kind of MBean.agent. not the key name.primarykeys=type.name. This method of converting JMX data to Introscope metrics results in streamlined metric names.0 will have a different structure than the metric tree for other WebLogic versions.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. the JMX Metric tree for WebLogic 9. assume you wish to capture the MessagesCurrentCount attribute value for the JMSDestinationRuntime MBean. If it finds a match.profile. metrics from each of those MBeans will be reported.filter in the IntroscopeAgent. Introscope 6. If you are only interested in an attribute on selected MBeans. increasing system overhead. For example. the following keywords are already defined: ■ ■ ■ ■ ■ ActiveConnectionsCurrentCount WaitingForConnectionCurrentCount PendingRequestCurrentCount ExecuteThreadCurrentIdleCount OpenSessionsCurrentCount 224 Java Agent Guide .name.profile file for WebLogic.filter property in the agent profile.agent. you can qualify the attribute name with the MBean name in your filter string. Filters are keywords.jmx.agent. entered as comma-separated strings in the property.jmx. IntroscopeAgent. the metrics that match are reported to Introscope.Managing metric volume with JMX filters Managing metric volume with JMX filters Defining JMX filters determines what JMX MBean information will be collected and displayed in Introscope.1 and higher supports filter strings that contain the asterisk (*) and question mark (?) wildcard characters. if you define a filter string that matches an MBean attribute that exists on multiple MBeans. If the fully qualified metric name for MessagesCurrentCount is: *SuperDomain*|host-name|Process|Agent-name|JMX|comp-1| JMSDestinationRuntime|comp-2:MessagesCurrentCount define introscope. all JMX MBean information will be reported by the agent to the Enterprise Manager. Introscope matches the filter strings to JMX-generated Introscope metrics. To limit the volume of metrics returned. Filters are set in the introscope. For instance. define filter strings as narrowly as possible.name.profile as: JMX|comp-1|JMSDestinationRuntime|comp-2:MessagesCurrentCount JMX filters for WebLogic In the IntroscopeAgent. If no filters are set. (The default value is false in the WebSphere agent profile. If you modify the value of the property. the strings must be spelled exactly and case sensitive. Chapter 16: Enabling JMX Reporting 225 .primarykeys 2. Continue to the next step.0. 3.) Define primary keys for JMX data conversion 1.Configuring JMX reporting Configuring JMX reporting How you configure Introscope to support JMX depends upon the application server you use.agent. Enable JMX support in the agent profile 1. values must be case-sensitive. Define JMX filters 1.name.filter property is uncommented. 2. ■ ■ For WebLogic 9. you must complete the following steps in this order: 1.primarykeys For other WebLogic versions. 3. In IntroscopeAgent. Configure startup class or service. Restart the managed application. configure primary keys.agent. 4.agent. In order for Introscope to properly match filtered strings. For WebSphere agents only.jmx. and multiple keys must be separated by commas.jmx. 4. 2. make sure the introscope. Define JMX filters. To configure JMX reporting.name. Define primary keys for JMX data conversion. 3.jmx. 2. Shut down the managed application if it is running.agent. comment out: introscope. in IntroscopeAgent.profile set introscope.profile. uncomment: introscope. Enter desired strings. Enable JMX support in the agent profile.enable to true. separated by commas. in the property.jmx. Define JMX filters.name.profile. This section describes how to configure Introscope to collect and present JMX data from WebLogic Server and WebSphere. In IntroscopeAgent. Save changes. 226 Java Agent Guide . To enable JSR-77 support: 1.1 (see page 92).jmx.name. retain.primaryKeys=J2EEServer. 5. Configure a WebSphere Custom Service. 2. 4.Enabling JSR-77 data for WAS 6. or Configuring a custom service in WebSphere 6.name.profile: introscope.agent. abstracts the manageable parts of the J2EE architecture and defines an interface for accessing management information.enable=true In the IntroscopeAgent.name. the application server must also support JSR-77. Shut down the managed application if it is running. Enabling JSR-77 data for WAS 6. In the IntroscopeAgent.0 or higher (see page 78). the J2EE Management Specification.profile provided with Introscope for WebSphere contains this property definition.agent. enable JSR-77 by setting: introscope. JSR-77 support requires a JVM version 1. you must configure an Introscope startup class in WebLogic Server. see Configuring a startup class for WebLogic 9.1 and later.disable=false Configure the primary keys method of metric conversion by uncommenting this property in the IntroscopeAgent. For more information see Using primary key conversion to streamline JMX metrics (see page 223). JSR-77.profile.mbeanIdentifier Note: Only the IntroscopeAgent. or a custom service in WebSphere. j2eeType.JDBCProvider.jmx.agent.Application. and report metrics for JSR-77 JMX MBean objects under WebSphere 6.profile.4 or later.4.jmx. as described in Configuring a custom service in WebSphere 6. verify that: introscope.x This section provides instructions for configuring Introscope to collect.x Configure startup class or service ■ To enable JMX data. 3.jsr77.1 (see page 92). For instructions. If the JVM is 1. To specify the JSR-77 Metrics to report.jmx.agent. 7. uncomment this property.Enabling JSR-77 data for WAS 6.name.agent.filter Although filtering is not required.ignore.jmx. For more information see Managing metric volume with JMX filters (see page 224).attributes=server Chapter 16: Enabling JMX Reporting 227 .x 6. and update as desired to exclude additional attributes: introscope. uncomment and set this property to identify desired metrics: introscope. To specify specific Mbean attributes to exclude in JSR-77 metrics. it is highly recommended. . This section contains the following topics: Understanding platform monitors (see page 229) Enabling platform monitors on Windows Server 2003 (see page 231) Enabling platform monitors on AIX (see page 231) Disabling platform monitors (see page 232) Troubleshooting platform monitoring (see page 234) Understanding platform monitors Platform monitors enable the Java Agent to report system metrics. Platform monitors on all operating systems except Windows Server 2003 and AIX are automatically enabled upon Java Agent installation. platform monitor binaries are purely dependent on JVM architecture. Note: Platform monitor binaries are independent of application server and operating system bit modes.Chapter 17: Configuring Platform Monitoring This section has instructions for configuring Introscope Platform Monitors. Platform monitors are included with the Introscope Agent installers. Chapter 17: Configuring Platform Monitoring 229 . Windows Server 2003 and AIX platform monitors require minimal configuration to work. ■ ■ ■ Windows Server 2003 Windows 2000 Professional/Server/Advanced Server/Datacenter Server Windows XP Professional Important: Introscope does not monitor platform monitors on 64-bit Windows XP Professional. to the Enterprise Manager. including CPU statistics. Introscope can monitor CPU usage on these operating systems: ■ Solaris Important: Platform monitoring is not supported on 64 bit Solaris using 64 bit BEA JRockit JVM. Also. The platform metrics generated are: ■ ■ ■ ProcessID Processor Count . if you have 4 processes. HP-UX Platform Monitor binaries (both PA-RISC and IA 64) work on 64 bit kernel with 32 bit JVM. Regardless of how many processors there are. 4. The following JVMs are supported by platform monitors: ■ ■ ■ ■ Sun JVM HP Hotspot JVM IBM JVM (Both Classic and J9) BEA JRocket JVM Note: 32-bit Platform Monitor binaries can be installed on a 64-bit machine.0. or 10. ■ 230 Java Agent Guide . this metric generates only one number. ■ ■ ■ RedHat 3. (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.0 SUSE Linux 9. the maximum use of the CPU would be 400% (4 processes using 100% of the CPU).0 Important: AIX 5.the number of CPUs Utilization % (process) . 5. Utilization % (aggregate) . You should ensure that your AIX machine is no less than TL6.for this processor.Understanding platform monitors ■ AIX 4. Each processor is shown as a Resource in the Investigator tree. If one process takes 110%. the percentage of total capacity of all processors this process is using.0. provided a 32-bit JVM is installed.0 HP-UX Note: HP-UX Platform Monitor binaries (both PA-RISC and IA 64) work on 32 bit kernel with 32 bit JVM.0. For example.for the Java Agent process. its total utilization (as a percentage) by all processes in the system.1 CPUs. or 5.0.3 64 bit Platform Monitor binaries work only on AIX machines which have Technology Level equal or greater than TL6 (5300-06). or 6. this means it is using 1.0. 4. To determine whether system objects are enabled: 1. In the Add dialog. if "Process" and "Processor" performance objects are present in the drop down list box. 3.jar introscopeAIX53PSeries64Stats.so libIntroscopeAIX52PSeries64Stats. 2.jar introscopeAIXPSeries64Stats.so Chapter 17: Configuring Platform Monitoring 231 . Type perfmon and click Run. Note that system objects must be enabled for platform monitoring to work on Windows. Enabling platform monitors on AIX To enable platform monitors on AIX: 1.so libIntroscopeAIXPSeries64Stats. Go to Start > Run.jar libIntroscopeAIX5PSeries32Stats. In the dialog box click Add.so libIntroscopeAIX53PSeries64Stats. Run the command: lodctr /r "Process" and "Processor" objects will be enabled. Go to Start > Accessories > Right click on command prompt > Run as… > Administrator.jar introscopeAIXPSeries32Stats.Enabling platform monitors on Windows Server 2003 Enabling platform monitors on Windows Server 2003 To run platform monitors on Windows Server 2003. After Java Agent installation. To enable system objects: 1. verify that the following files are installed in the wily/ext directory: ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ introscopeAIX5PSeries32Stats. then system objects are enabled.so libIntroscopeAIXPSeries32Stats. you must have admin privileges. 2.jar introscopeAIX52PSeries64Stats. 3. Disabling platform monitors To disable platform monitors on any platform.jar introscopeSolarisSparc64Stats.dll introscopeWindowsIntelAmd64Stats. Solaris The platform monitor files are: ■ ■ ■ ■ ■ ■ ■ ■ introscopeSolarisAmd32Stats.jar 232 Java Agent Guide .so Windows Server 2003. ■ AIX 4.3. move the . Restart your machine to ensure the patches have taken effect.jar introscopeWindowsIntelAmd64Stats.perf.3 and higher: A Perfstat Library has been created to work with AIX 4.dll introscopeWindowsIntelAmd32Stats. Install the following packages from the IBM FTP site: ■ ■ bos.so libIntroscopeSolarisSparc32Stats.jar introscopeSolarisSparc32Stats.jar libIntroscopeSolarisAmd32Stats.so libIntroscopeSolarisSparc64Stats.3 and then install the above packages. 3.perf.3.Disabling platform monitors 2. Windows 2000 (all).so libIntroscopeSolarisAmd64Stats. All files listed below are located in the <Agent_Home>wily/ext/ directory.3. and XP Professional The platform monitor files are: ■ ■ ■ ■ introscopeWindowsIntelAmd32Stats.jar file from the /wily/ext directory to another directory.perfstat ■ AIX 4: Bring your system up to 4. Install the Perfstat Library.jar introscopeSolarisAmd64Stats. This table shows the location of platform monitor files installed with a Java Agent installer.libperfstat bos. jar libIntroscopeHpuxItaniumStats.so libIntroscopeAIX52PSeries64Stats.jar libIntroscopeAIX5PSeries32Stats.jar introscopeHpuxItanium64Stats.so libIntroscopeAIXPSeries64Stats.so libIntroscopeAIX53PSeries64Stats.jar introscopeHpuxParisc32Stats.jar introscopeAIXPSeries32Stats.Disabling platform monitors AIX The platform monitor files are: ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ introscopeAIX5PSeries32Stats.jar introscopeLinuxIntelAmd64Stats.jar introscopeAIX52PSeries64Stats.so libIntroscopeHpuxItanium64Stats.so HP-UX The platform monitor files are: ■ ■ ■ ■ ■ ■ introscopeHpuxItaniumStats.so RedHat Enterprise Linux The platform monitor files are: ■ ■ introscopeRedHatStats.jar introscopeAIX53PSeries64Stats.so libIntroscopeAIXPSeries32Stats.jar libIntroscopeRedHatStats.so Linux The platform monitor files are: ■ ■ ■ ■ introscopeLinuxIntelAmd32Stats.so libIntroscopeLinuxIntelAmd64Stats.so libIntroscopeHpuxParisc32Stats.so Chapter 17: Configuring Platform Monitoring 233 .jar libIntroscopeLinuxIntelAmd32Stats.jar introscopeAIXPSeries64Stats. agent.agent.system=AIXPSeries64 #introscope. 234 Java Agent Guide .platform.Troubleshooting platform monitoring Troubleshooting platform monitoring In most cases.system=SolarisSparc32 #introscope. Under the Platform Monitor Configuration heading.system=HP-UXParisc32 #introscope. locate the exact matching value for your operating system and uncomment the property.monitor. the platform monitor successfully detects the operating system and runs if the operating system is supported.agent. To specify your operating system in the IntroscopeAgent.platform.agent. the Java Agent logfile will sometimes contain an error similar to the following: 11/28/06 08:29:55 AM PST [ERROR] [IntroscopeAgent] An error occurred polling for platform data If the error is infrequent. Troubleshooting platform monitoring on Windows On Windows platforms.agent.agent.monitor. Open IntroscopeAgent.platform.platform.system=SolarisSparc64 #introscope. Restart the managed application.monitor.platform. The available values are: #introscope.platform. or in the case that the error happens all the time. this error indicates something more serious and should be reported to CA Support for Introscope.agent.platform.platform.platform.monitor.platform. it is likely caused by a transient error originating from Windows itself. 2.agent.platform.monitor.monitor.monitor.system=LinuxIntelAmd64 3. In rare cases where this does not occur.agent.monitor.agent.monitor.system=AIXPSeries32 #introscope.profile.agent.system=LinuxIntelAmd32 #introscope.platform.system=WindowsIntelAmd32 #introscope. you can explicitly specify your operating system in the Java Agent profile to ensure that the platform monitor runs. On platforms other than Windows.monitor.system=HP-UXItanium #introscope.profile: 1.agent.monitor.system=SolarisAmd64 #introscope. and is harmless.system=SolarisAmd32 #introscope.monitor.system=WindowsIntelAmd64 #introscope. then restarting the Windows machine. 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. Chapter 17: Configuring Platform Monitoring 235 .Troubleshooting platform monitoring SAP Netweaver Platform monitors may not function correctly on SAP Netweaver due to the lack of permissions for SAP user accounts. By default. which is located by navigating to Computer Management > System Tools > Local Users and Groups > Groups > Performance Monitor Users . this issue can be resolved by adding SAP user account to the Performance Monitor Users group. SAP user accounts are not registered under Performance Monitor Users. . profile location (see page 238) Command-line property overrides (see page 239) Agent failover (see page 239) Agent HTTP tunneling (see page 241) Agent memory overhead (see page 244) Agent metric aging (see page 244) Agent metric clamp (see page 249) Agent naming (see page 250) Agent recording (business recording) (see page 256) Agent thread priority (see page 257) Agent to Enterprise Manager connection (see page 258) Application triage map (see page 260) Application triage map business transaction POST parameters (see page 263) Application triage map managed socket configuration (see page 265) Application triage map transaction sampling (see page 268) AutoProbe (see page 270) Blame (see page 272) Bootstrap Classes Instrumentation Manager (see page 272) CA Wily CEM integration (see page 274) ChangeDetector (see page 274) Cross-process tracing in WebLogic Server (see page 278) Cross-process transaction trace (see page 279) Dynamic ProbeBuilding (see page 280) ErrorDetector (see page 282) Extensions (see page 284) Java NIO (see page 285) JMX (see page 292) LeakHunter (see page 297) Logging (see page 301) Metric count (see page 306) Multiple inheritance (see page 307) Platform monitoring (see page 310) Remote configuration (see page 311) Security (see page 312) Servlet header decorator (see page 313) Socket metrics (see page 313) SQL Agent (see page 316) SSL communication (see page 321) Stall metrics (see page 324) Transaction tracing (see page 326) URL grouping (see page 336) WebSphere PMI (see page 338) WLDF metrics (see page 349) Appendix A: Java Agent Properties 237 .Appendix A: Java Agent Properties This section contains the following topics: Configuring the IntroscopeAgent. wily. you must add the new location of the agent profile to the Sun ONE server.profile file: -D com.wily. Open the server. in this sequence: ■ ■ ■ location defined in the system property com.0. Note: If you change the location of the IntroscopeAgent.profile </jvm-options> 238 Java Agent Guide .introscope.profile for its basic connection and naming properties. 2.profile available in a resource on the classpath.xml file To change the location of the IntroscopeAgent.agentProfile Make the IntroscopeAgent. see Managing ProbeBuilder Logs (see page 167). 2. the AutoProbe log location will also have to be changed. Define the new location using one of these methods: ■ ■ ■ 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 for Sun ONE: 1. To change the location of the IntroscopeAgent.wily. If you use Sun ONE. in <SunOne_Home>/domains/domain1/server1/config/ Add a line to the jvm-options stanza in server.profile location Configuring the IntroscopeAgent.profile: 1. When you install an agent.Configuring the IntroscopeAgent.introscope.xml file.agentProfile location defined in com. log in as Administrator or Root.introscope.wily. you must escape a backslash (\) with another backslash (each one doubled).agentProfile=SunOneHome/wily/IntroscopeAgent. To add Introscope information to startup scripts for Sun ONE 7. 3.profile.wily. Introscope looks for the agent profile in these locations. For more infomation.agentResource to specify the path to the resource containing the agent profile.xml: <jvm-options> -Dcom.introscope. Move your ProbeBuilder directives (PBD and PBL files) to the same location as the agent profile—they are referenced relative to the profile location.introscope.jar. the agent profile is installed in the <Agent_Home>/wily directory.agentResource <working directory>/wily directory Note: When adding a path on a Windows machine.profile location The agent refers to properties in the IntroscopeAgent. Set com. such as C:\\Introscope\\lib\\Agent. enterprisemanager. Important: System properties become part of the property space of Introscope properties. 2. Agent failover If the Java Agent loses connection with its primary Enterprise Manager. remove the override command before modifying the property in a configuration file. In the example used above.io.failbackRetryIntervalInSeconds (see page 240) Appendix A: Java Agent Properties 239 . this is useful when you have a clustered environment with multiple copies of an agent being shared and you want to tailor some of the agent settings for each application being monitored. Note: When you use this command to override hot deployable properties.pbl file: -Dintroscope.agent.pbl Place this command next to other -D commands in the open file. Also. With regard to the Java Agent. Add a -D command to override a property. These steps assume you have installed and configured an agent on the application server to be monitored. and how often it will try to reconnect to its primary Enterprise Manager: ■ ■ introscope. agents. For example.directivesFile=weblogic-full.enterprisemanager.0.autoprobe. you can override specific properties of the Enterprise Manager. allowing things like java. To avoid this. Workstation.connectionorder (see page 240) introscope. and that the agent successfully connects to the Enterprise Manager. Open the file where you modified the Java command to start the agent. if you modify the property at a later time in the configuration file. these properties specify which Enterprise Manager the agent will failover to. Restart the agent. you can add the following command to make the agent also use the weblogic-full.Command-line property overrides Command-line property overrides In Introscope 9. you will receive a warning message in the Workstation stating you modified an overridden property and your change will have no effect. and WebView using the command line. The location of this file varies depending on the application server you use in your environment.agent. 3. Save the file. the property is no longer hot deployable. 4. you would now see the additional WebLogic metrics in the agent node in the Workstation.tmpdir to be visible to anything using IndexedProperties. To override agent properties using the command line: 1. Agent failover 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 default Example introscope.agent.enterprisemanager.connectionorder=DEFAULT Notes ■ ■ Use a comma separated list. You must restart the managed application before changes to this property take effect. introscope.agent.enterprisemanager.failbackRetryIntervalInSeconds Specifies the number of seconds between attempts by the agent to reconnect to its primary Enterprise Manager. Default Commented out; 120 Example introscope.agent.enterprisemanager.failbackRetryIntervalInSeconds=120 Notes You must restart the managed application before changes to this property take effect. 240 Java Agent Guide Agent HTTP tunneling Agent HTTP tunneling You can configure agents to send information using tunneling technology, enabling agents to connect to an Enterprise Manager remotely. To do this, the agent must be configured to connect to the Enterprise Manager’s embedded Web server, where the HTTP tunneling Web service is hosted. To configure HTTP tunneled communication in IntroscopeAgent.profile as a new agent connection, specify: ■ ■ The host name of machine running the Enterprise Manager —see introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT (see page 258). 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. See the Introscope Properties Files section of the Introscope Configuration and Administration Guide for information about introscope.enterprisemanager.webserver.port. The HTTP tunneling socket factory. Specify this client socket factory: com.wily.isengard.postofficehub.link.net.HttpTunnelingSocketFactory ■ Agent HTTP tunneling for proxy servers The following properties only apply to agents configured to tunnel over HTTP and must connect to an Enterprise Manager using a proxy server: ■ ■ ■ ■ introscope.agent.enterprisemanager.transport.http.proxy.host (see page 241) introscope.agent.enterprisemanager.transport.http.proxy.port (see page 242) introscope.agent.enterprisemanager.transport.http.proxy.username (see page 242) introscope.agent.enterprisemanager.transport.http.proxy.password (see page 242) For more information, see Configuring a proxy server for HTTP tunneling (see page 50). 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. Appendix A: Java Agent Properties 241 Agent HTTP tunneling 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. Agent HTTPS tunneling You can configure agents to send information using HTTPS, enabling agents to connect to an Enterprise Manager remotely: ■ ■ ■ introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT (see page 243) introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT (see page 243) introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT (see page 243) 242 Java Agent Guide Agent HTTP tunneling introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT Specifies the settings the agent uses to find the Enterprise Manager and names given to host and port combinations. 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 Settings the agent uses to find the Enterprise Manager and names given to host and port combinations. 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 Settings the agent uses to find the Enterprise Manager and names given to host and port combinations. 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. Appendix A: Java Agent Properties 243 Agent memory overhead Agent memory overhead Significant agent memory overhead only occurs in certain extreme cases. Setting the following property to true may reduce an agent’s overhead: ■ introscope.agent.reduceAgentMemoryOverhead (see page 244) The trade-off for the possible lower memory consumption is a possible increase in response time. Each application is unique and will experience different variations in memory vs. response time trade-offs. introscope.agent.reduceAgentMemoryOverhead Uncomment if you want to attempt to reduce the agent memory overhead introduced by architectural improvements to the 8.x agent. This property is set to true by default and out of the box is commented out. 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. Agent metric aging Agent metric aging periodically removes dead metrics from the agent memory cache. A dead metric is a metric that has no new data reported in a configured amount of time. This helps the agent improve performance and avoid potential metric explosions. Note: A metric explosion happens when an agent is inadvertently set up to report more metrics than the system can handle. In this case, Introscope is bombarded with such a large number of metrics that performance gets very slow or the system cannot function at all. 244 Java Agent Guide Agent metric aging Metrics that are in a group are removed only if all metrics in the group are considered candidates for removal. Currently, only BlamePointTracer group and MetricRecordingAdministrator metrics are removed as a unit; other metrics are removed individually. The MetricRecordingAdministrator metric has APIs that can create a metric group. These APIs are: ■ 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 in order 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 API if you keep an instance of an accumulator in your extension. If the accumulator is removed because of metric aging then you will be holding onto a dead reference. Important: If you create an extension that uses a MetricRecordingAdministrator API (for example, for use with CA Technologies products), be sure to delete your own instance of an accumulator. When a metric ages out because it has not been invoked, and then after a time data does become available for that metric, if you are using an old accumulator instance, the accumulator will not create new metric data points for that metric. To avoid this situation, do not delete your own instance of an accumulator and use instead the getDataAccumulatorFactory API. Configuring agent metric aging Agent metric aging is on by default. You can choose to turn off this capability using the property introscope.agent.metricAging.turnOn (see page 247). If you remove this property from the IntroscopeAgent.profile, agent metric aging is turned off by default. Agent metric aging runs on a heartbeat in the agent. The heartbeat is configured using the property introscope.agent.metricAging.heartbeatInterval (see page 247). Be sure to keep the frequency of the heartbeat low. A higher heartbeat will impact the performance of the agent and Introscope. Appendix A: Java Agent Properties 245 Agent metric aging During each heartbeat, a certain set of metrics are checked. This is configurable using the property introscope.agent.metricAging.dataChunk (see page 248). 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 248). 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. Note: For metrics that do not have a metric group then the rule does not apply. Based on the rules outlined above, it may take a significant amount of time for metrics to be removed. Use the following properties to configure agent metric aging: ■ ■ ■ ■ ■ introscope.agent.metricAging.turnOn (see page 247) introscope.agent.metricAging.heartbeatInterval (see page 247) introscope.agent.metricAging.dataChunk (see page 248) introscope.agent.metricAging.numberTimeslices (see page 248) introscope.agent.metricAging.metricExclude.ignore.0 (see page 249) In all of the properties, if any unrecognised values are used, the default value will be used instead. 246 Java Agent Guide introscope. Property settings True or False Default True Example introscope.heartbeatInterval=1800 Notes You must restart the managed application before changes to this property take effect.heartbeatInterval Specifies the time interval when metrics are checked for removal.turnOn=true Notes Changes to this property take effect immediately and do not require the managed application to be restarted.agent.metricAging.metricAging.metricAging.turnOn Turns on or off agent metric aging. in seconds.agent. Appendix A: Java Agent Properties 247 .agent.metricAging. Default 1800 Example introscope.Agent metric aging introscope.agent. agent.metricAging.dataChunk Specifies the number of metrics that are checked during each interval.dataChunk=500 Notes Changes to this property take effect immediately and do not require the managed application to be restarted.numberTimeslices Specifies the number of intervals to check without any new data before making it a candidate for removal.Agent metric aging introscope.metricAging.agent. 248 Java Agent Guide . introscope. Default 3000 Example introscope. Default 500 Example introscope.metricAging.metricAging.numberTimeslices=3000 Notes Changes to this property take effect immediately and do not require the managed application to be restarted.agent.agent. metricClamp (see page 250) If the number of metrics pass this metric clamp value then no new metrics will be created.metricExclude.0 Excludes specified metrics from being removed.ignore.metricAging. Default None.agent. Example introscope.agent. Agent metric clamp The following property allows you to configure the Java Agent to approximately clamp the number of metrics sent to the Enterprise Manager: ■ introscope.0=Threads* Notes Changes to this property take effect immediately and do not require the managed application to be restarted. You can use the an asterisk (*) as a wildcard in metric names. Appendix A: Java Agent Properties 249 .metricExclude.ignore. Property settings Comma seperated list of metrics. Add the metric name or metric filter to the list.agent.metricAging.Agent metric clamp introscope. agentName (see page 253) introscope. Old metrics will still report values.agentAutoNamingEnabled (see page 251) introscope.defaultProcessName (see page 255) introscope.agentAutoRenamingIntervalInMinutes (see page 252) introscope.metricClamp Configures the agent to approximately clamp the number of metrics sent to the Enterprise Manager.agent.clonedAgent (see page 254) introscope.agent. 250 Java Agent Guide .agentAutoNamingMaximumConnectionDelayInSeconds (see page 251) introscope.agentNameSystemPropertyKey (see page 253) introscope.agent.agent.agent. Changes to this property take effect immediately and do not require the managed application to be restarted.agent. Default 5000 Example introscope.as. see Java Agent Naming (see page 147).agent.fqdn (see page 256) For more information on Java Agent naming.agent.customProcessName (see page 254) introscope.agent.display.agent.hostName.metricClamp=5000 Notes ■ ■ If the property is not set then no metric clamping will occur.agent.disableLogFileAutoNaming (see page 255) introscope. Agent naming The following are Java Agent naming properties: ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ introscope.Agent naming introscope.agent.disableLogFileAutoNaming (see page 252) introscope.agent. agentAutoNamingMaximumConnectionDelayInSeconds Specifies the amount of time in seconds the agent waits for naming information before connecting to the Enterprise Manager. Property settings True or False Default Varies by application server. WebSphere. introscope. Important: For WebLogic. Interstage.agent.agentAutoNamingEnabled is set to TRUE by default.agent. and Tomcat. WebSphere.agent. and requires the Custom Service to be specified for WebSphere. You must restart the managed application before changes to this property take effect. and JBoss This property requires the Startup Class to be specified for WebLogic. and JBoss. Default 120 Example introscope. Example introscope. see Notes below.agentAutoNamingMaximumConnectionDelayInSeconds=120 Notes You must restart the managed application before changes to this property take effect. Appendix A: Java Agent Properties 251 .agentAutoNamingEnabled=false Notes ■ ■ ■ ■ Agent autonaming is enabled in the following application servers: WebLogic.agentAutoNamingEnabled Specifies whether agent autonaming will be used to obtain the Java Agent name for supported application servers.agent. Sun ONE. the property introscope. Agent auto naming is disabled in the following application servers: Oracle application server.agent.Agent naming introscope. You must restart the managed application before changes to this property take effect. Default 10 Example introscope.Agent naming introscope.agent. introscope.agent. AutoProbe and LeakHunter) with the agent name.agent.agentAutoRenamingIntervalInMinutes Specifies the time interval in minutes during which the agent will check to see if it has been renamed. or a timestamp. 252 Java Agent Guide .agentAutoRenamingIntervalInMinutes=10 Notes You must restart the managed application before changes to this property take effect. Property settings True or False Default False Example introscope.disableLogFileAutoNaming Auto name of log files (Agent.agent. can be disabled by setting this property to 'true'.disableLogFileAutoNaming=false Notes ■ ■ 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. Appendix A: Java Agent Properties 253 .agentName Uncomment this property to provide a default agent name if other agent naming methods fail. In the agent profile provided with the default agent installer.agent. the agent name will be UnnamedAgent.agentName=AgentName Notes ■ ■ ■ You must restart the managed application before changes to this property take effect.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. introscope.agent. Example introscope. In the agent profile provided with application server-specific agent installers. the default reflects the application server.Agent naming introscope.agent. the property value is AgentName. for instance WebLogic Agent.agentNameSystemPropertyKey Notes You must restart the managed application before changes to this property take effect. Property settings For any installation. if the value of this property is invalid or if this property is deleted from the profile. and the line is commented out. Example introscope. Default Varies by application server." In the agent profile provided with default agent installer. for instance "WebLogic. Property settings True or False Default False Example introscope. the property is commented out. In the agent profile provided with application server-specific agent installers.clonedAgent Set to true when running identical copies of an Application on the same machine.customProcessName=CustomProcessName Notes ■ ■ ■ You must restart the managed application before changes to this property take effect.customProcessName Specify the process name as it should appear in the Introscope Enterprise Manager and Workstation. introscope.agent.agent.Agent naming introscope.agent. 254 Java Agent Guide .agent. the default reflects the application server.clonedAgent=false Notes You must restart the managed application before changes to this property take effect. disableLogFileAutoNaming Specifies whether to disable automatic naming of agent log files when using AutoNaming options. 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. Default UnknownProcess Example introscope. Property settings True or False Default False Example introscope. Appendix A: Java Agent Properties 255 . Setting this property to true disables the auto-naming of log files for the agent. this value is used for the process name. introscope.agent. AutoProbe and LeakHunter with the agent name or a timestamp.agent.defaultProcessName=UnknownProcess Notes You must restart the managed application before changes to this property take effect.agent.Agent naming introscope.agent.defaultProcessName If no custom process name is provided and the agent is unable to determine the name of the main application class.disableLogFileAutoNaming=false Notes ■ ■ You must restart the managed application before changes to this property take effect. Agent recording (business recording) introscope. see the CA Wily APM Transaction Definition Guide.display.enabled (see page 257) For more information on agent business recording.hostName. Property settings True or False Default False Example introscope.fqdn=false Notes You must restart the managed application before changes to this property take effect.agent. 256 Java Agent Guide .as.hostName.bizRecording.as.display.agent. By default (false) it will display the HostName.agent. Agent recording (business recording) The following properties configure how the Java Agent handles business recording: ■ introscope.fqdn A fully qualified domain name (fqdn) can be enabled by setting this property value to 'true'. agent.bizRecording.agent. Agent thread priority The following property controls the priority of agent threads: ■ introscope. Application triage map managed socket configuration (see page 265).enabled This property enables or disables agent business recording. 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.Agent thread priority introscope. Application triage map business transaction POST parameters (see page 263).thread. see Application triage map (see page 260). To further configure agent business recording.priority (see page 258) Appendix A: Java Agent Properties 257 . and Application triage map transaction sampling (see page 268).all. enterprisemanager.5. Default localhost Example introscope.agent.host.host.enterprisemanager. 258 Java Agent Guide .socketfactory.transport.thread.host.enterprisemanager.agent.all.agent.DEFAULT (see page 259) introscope.agent.tcp.tcp.DEFAULT The host name of machine running the Enterprise Manager.DEFAULT (see page 258) introscope.DEFAULT=localhost Notes You must restart the managed application before changes to this property take effect.transport. Default Commented out.thread.tcp.tcp. Example introscope.tcp.agent.priority=5 Notes You must restart the managed application before changes to this property take effect.enterprisemanager.priority Controls the priority of agent threads. Agent to Enterprise Manager connection The following properties controls the agent connection to the Enterprise Manager: ■ ■ ■ introscope.DEFAULT (see page 259) introscope. Property settings You can set this from 1 (low) to 10 (high).Agent to Enterprise Manager connection introscope.agent.transport.transport.agent.enterprisemanager.transport.all.port. introscope.enterprisemanager.socketfactory.agent.link.enterprisemanager.wily.postofficehub.Agent to Enterprise Manager connection introscope.transport.DefaultSocketFactory Example introscope.agent.tcp.wily.agent.postofficehub.net.tcp.tcp.port. Default 5001 Example introscope. Appendix A: Java Agent Properties 259 .transport.transport.i sengard.transport.DEFAULT Change this property to use a different client socket factory.port.isengard.DefaultSocketFactory Notes You must restart the managed application before changes to this property take effect.DEFAULT=5001 Notes You must restart the managed application before changes to this property take effect.DEFAULT=com.DEFAULT The port on the Enterprise Manager machine that listens for the agent. Default com.socketfactory.link.enterprisemanager.net.tcp.agent.enterprisemanager. catalystIntegration.agent.period (see page 262) introscope.agent.agent.enabled Enables or disables the tracking of monitored code for the application triage map. See Application triage map business transaction POST parameters (see page 263) for more triage map properties.agent.appmap.intermediateNodes.appmap.Application triage map Application triage map The following properties configure application triage map data: ■ ■ ■ ■ ■ ■ introscope.size (see page 262) introscope.agent.enabled (see page 260) introscope.appmap.agent. introscope.appmap.agent.enabled (see page 263) See the CA Wily Introscope Workstation User Guide for more information on how to use the application triage map.enabled (see page 261) introscope. 260 Java Agent Guide .agent.metrics.enabled=true Notes Enabled by default.appmap.appmap. Property settings True or False Default True Example introscope.appmap.queue.appmap.enabled (see page 261) introscope.queue. metrics.appmap.enabled=false Notes This property is commented out by default.agent.catalystIntegration. introscope. Appendix A: Java Agent Properties 261 .appmap.agent. Property settings True or False Default False Example introscope.catalystIntegration.agent.enabled=false Notes This property is commented out by default.Application triage map introscope.enabled Enables or disables the tracking of metrics for application triage map nodes.metrics.enabled Enables or disables the agents ability to send additional information for integration with Catalyst. Property settings True or False Default False Example introscope.appmap.agent.appmap. queue. Default 1000 Example introscope.period=1000 Notes ■ ■ ■ Must be a positive integer.agent.agent. the default value is used.appmap. Default 1000 Example #introscope. Property settings Positive integers.agent. This property is commented out by default.appmap. 262 Java Agent Guide .period Sets the frequency in milliseconds for sending application triage map data to the Enterprise Manager.queue. Property settings Positive integers.appmap. If the value is set to 0. This property is commented out by default. introscope.queue.Application triage map introscope.queue.agent.size Sets the buffer size for the application triage map. the buffer is unbounded.size=1000 Notes ■ ■ ■ The value must be a positive integer. If the value is set to 0.appmap. intermediateNodes.Application triage map business transaction POST parameters introscope. you may experience a slow down of agent performance.profile.agent. If you set this property to true.agent. Property settings True or False Default False Example #introscope.appmap.matchPost (see page 264) Appendix A: Java Agent Properties 263 .enabled=true Notes ■ ■ Changes to this property takes effect immediately and do not require the managed application to be restarted. allows you to configure your Local Product Shorts to perform more complex monitoring by matching POST parameters: ■ introscope. located in the default IntroscopeAgent.enabled Enables or disables sending additional intermediate nodes between application frontend and backend nodes. Application triage map business transaction POST parameters The following property.appmap.intermediateNodes.bizdef.agent. 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. ■ after . ■ ■ Set the property to after to safely match business transactions with POST parameters. before . New applications deployed must also conform to standard API when this property is set to before.never attempt to match POST parameters. Property settings The valid settings for this property are never. This setting allows applications to use POST parameters to identify some or all business transactions. When this property is set to after. 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.agent. Set the property to before to get full agent performance. ■ Set the property to never for full agent functionality and better performance. This allows your application to identify all business transactions using URLs. the agent will not be able to map business transactions that are identified by POST parameters across processes. Cross process mapping and some metrics will not be available.matchPost This property determines when POST parameters are matched.matches POST parameters before the servlets execute. This setting also consumes slightly more CPU time compared to the other options. but never access the servlet stream directly for HTTP form requests. before. Example introscope. Default setting for the parameter. or after. but is considered the safest setting if one needs the POST parameter functionality. but with limited agent functionality. Note: Setting this parameter to before could have potentially hazardous repercussion to your applications. cookies and/or header parameters.bizdef.matches POST parameter patterns after the servlet has executed.Application triage map business transaction POST parameters introscope. This is the fastest option but may result in inaccurate business transaction component matching.agent.matchPost=after Notes ■ ■ never . Do not set this parameter to before unless you have consulted with your CA Technologies representative or CA Support.bizdef. 264 Java Agent Guide . but will fail to match any business transactions that are identified solely through POST parameters. or produce full sets of metrics for them. only three metrics will be provided for the business transaction component.Application triage map managed socket configuration Known limitations The metrics defined using agent recording are displayed in the application triage map in the Investigator.sockets. then the business component name in the transaction trace component will have a generic name and not the specific name of the business service.agent. When configuring agent recording.reportClassAppEdge (see page 266) introscope.agent.managed. business transaction.managed. there are some known limitations when using regular expressions.managed.managed. This also applies to business transaction definitions that are dependent on POST parameter definitions that do not match.reportMethodAppEdge (see page 267) introscope.agent.sockets.sockets.reportMethodBTEdge (see page 268) See the Introscope Workstation User Guide for more information on how to use the application triage map.sockets.managed. Appendix A: Java Agent Properties 265 . 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. Application triage map managed socket configuration The following properties allow you to enable or disable the appearance of socket metrics in the application triage map: ■ ■ ■ ■ ■ introscope.agent.reportClassBTEdge (see page 267) introscope.sockets. ■ For more information on agent recording. The known limitations are: ■ ■ Line terminators (.) are not supported for POST parameter values. see the CA Wily APM Transaction Definition Guide. These metrics are: ■ ■ ■ Average Response Time Responses Per Interval Errors Per Interval ■ If POST parameter definitions are dependent on the business transaction definition. and business transaction component. If POST parameter definitions are dependent on the business transaction definition. Most of the limitations have to do with POST parameters.reportToAppmap (see page 266) introscope.agent. sockets. Property settings True or False Default False Example introscope.sockets.agent.sockets.agent.managed.reportClassAppEdge Enables managed sockets to report class level application edges to the application triage map.reportToAppmap=true Notes You must restart the managed application before changes to this property take effect.managed.managed.agent.reportClassAppEdge=false Notes You must restart the managed application before changes to this property take effect. 266 Java Agent Guide .agent.sockets. introscope.reportToAppmap Enables managed sockets to appear in application triage map. Property settings True or False Default True Example introscope.Application triage map managed socket configuration introscope.managed. sockets.sockets.managed.agent.reportClassBTEdge=false Notes You must restart the managed application before changes to this property take effect.Application triage map managed socket configuration introscope.managed.reportMethodAppEdge=true Notes You must restart the managed application before changes to this property take effect.managed.sockets. Property settings True or False Default False Example introscope.sockets.reportMethodAppEdge Enables managed sockets to report method level application edges to the application triage map. Appendix A: Java Agent Properties 267 .agent.reportClassBTEdge Enables managed sockets to report class level business transaction edges to the application triage map.agent. introscope.agent.managed. Property settings True or False Default True Example introscope. period (see page 270) Introscope uses transaction sampling to provide data to support the application triage map display.agent.agent. Subsequently. After an agent is started.agent.reset.initial. After each ten thousand transactions. Property settings True or False Default True Example introscope. Application triage map transaction sampling The following properties configure application triage map transaction sampling: ■ ■ ■ introscope.sockets.reportMethodBTEdge=true Notes You must restart the managed application before changes to this property take effect.period (see page 269) introscope.maxrate (see page 269) introscope.tracer. See the Introscope Workstation User Guide for more information on how to use the application triage map.managed.tracer.sockets.tracer. this pattern repeats. Be aware that adjusting the following properties to increase the amount of transactions supporting the map display may increase agent overhead.agent. Introscope takes (by default) the first one hundred transactions to draw an initial map of the frontend and its dependencies.managed. it gradually reduces the number of transactions it samples until it reaches a level where only every tenth transaction provides continuing data support to the map.agent.reportMethodBTEdge Enables managed sockets to report method level business transaction edges to the application triage map.sampling.sampling.sampling.Application triage map transaction sampling introscope. 268 Java Agent Guide . Default 10 Example introscope.period This property sets the initial number of transactions the agent will sample at the begining of the sampling process.tracer. Default 100 Example introscope.agent. Changes to this property take effect immediately and do not require the managed application to be restarted.tracer. By default 1 out 10 transactions are monitored. Appendix A: Java Agent Properties 269 .maxrate=10 Notes ■ ■ Set the value to 0 to disable sampling and monitor all transactions.tracer.agent.agent.initial.sampling. introscope.period=100 Notes Changes to this property take effect immediately and do not require the managed application to be restarted.Application triage map transaction sampling introscope.tracer.initial.agent.sampling.maxrate Use this property to set the maximum sampling rate.sampling.sampling. After the set number of not sampled transactions have passed.agent. Notes ■ ■ You must restart the managed application before changes to this property take effect.reset.reset.AutoProbe introscope.autoprobe. For more information.agent. If this property includes one or more directories.tracer.period=10000 Notes Changes to this property take effect immediately and do not require the managed application to be restarted. Default Varies by installer. the agent begins the sampling process over again.autoprobe.period After the agent has sampled a set number of transactions. 270 Java Agent Guide .sampling. Default 10000 Example introscope. AutoProbe The following properties configure AutoProbe: ■ ■ introscope. this property sets the number of transactions the agent will not sample.tracer. the agent will load directives files from the specified directories without an application restart. see ProbeBuilder Directives (see page 56).directivesFile Specifies ProbeBuilder directives files for AutoProbe.directivesFile (see page 270) introscope.sampling. and dynamic instrumentation is enabled.enable (see page 271) introscope.autoprobe. Appendix A: Java Agent Properties 271 . Property settings True or False Default True Example introscope.autoprobe.logfile=logs/AutoProbe.enable=true Notes When this property is set to false.autoprobe. Set this property to move the location of the log file to something other than the default.log Notes You must restart the managed application before changes to this property take effect. Non-absolute names are resolved relative to the location of this properties file Default logs/AutoProbe. introscope. or non-absolute paths.logfile Introscope AutoProbe always attempts to log the changes it makes.enable Enables or disables inserting probes into bytecode automatically. It does not turn off the agent or agent reporting.log Example introscope.AutoProbe introscope.autoprobe.autoprobe. Property settings Absolute file paths. it turns off the automatic insertion of Probes into an application’s bytecode. see Configuring Boundary Blame (see page 195). Property settings standard.bootstrapClassesManager. as well as improving agent performance. For information about boundary blame.agent.type Add this property with a value of standard to turn off boundary blame.blame.blame.agent. You can disable this property by commenting it out in the IntroscopeAgent.profile. Bootstrap Classes Instrumentation Manager The following properties configure the Bootstrap Classes Instrumentation Manager: ■ ■ introscope.type=boundary Notes You must restart the managed application before changes to this property take effect. introscope.agent.blame.enabled (see page 273) introscope. allowing easy implementation of tracers for Java NIO and Secure Sockets Layer (SSL). boundary Default boundary Example introscope. see the Introscope Workstation User Guide.waitAtStartup (see page 273) The Bootstrap Classes Instrumentation Manager instruments a set of classes after the agent bootstrap.bootstrapClassesManager. 272 Java Agent Guide .type (see page 272) For more information about Boundary Blame.Blame Blame The following property configures Boundary Blame: ■ introscope. in seconds. Sun. You must restart the managed application before changes to this property take effect. in seconds Default ■ ■ 240 seconds when used with HP-UX. the default value is false. Property settings True or False Default True Example introscope. Property settings Time. WebLogic. for how long the agent waits after startup to instrument bootstrap classes. 5 seconds when used with JBoss.5 or higher.bootstrapClassesManager. Example introscope. or Tomcat. introscope.Bootstrap Classes Instrumentation Manager introscope.bootstrapClassesManager.waitAtStartup Sets the time. If set to false. no system classes will be instrumented. If the property is not set. or WebSphere Application Server.enabled=true Notes ■ ■ ■ ■ This property only functions with JVMs running Java 1.waitAtStartup=5 Appendix A: Java Agent Properties 273 .bootstrapClassesManager.bootstrapClassesManager. Oracle.enabled Enables or disables the bootstrap manager. Interstage. see the CA Wily CEM Integration Guide. If skipped classes are being instrumented. it can overrule classes that have been designated as skipped.isengardStartupWaitTimeInSec (see page 276) introscope. When this property is active.waitTimeBetweenReconnectInSec (see page 276) introscope. CA Wily CEM integration For information on configuring Java Agents for Wily CEM Integration.rootDir (see page 275) introscope.changeDetector.enable (see page 278) introscope.changeDetector.changeDetector.compressEntries.enable (see page 275) introscope. 274 Java Agent Guide .changeDetector.profile (see page 277) introscope.compressEntries.changeDetector. please contact your CA Technologies representative. see the CA Wily Introscope ChangeDetector User Guide.batchSize (see page 278) For more information about ChangeDetector.CA Wily CEM integration Notes ■ ■ This property only functions with JVMs running Java 1.changeDetector.profileDir (see page 277) introscope.changeDetector. or CA Support.agentID (see page 276) introscope. ChangeDetector The following properties configure aspects of ChangeDetector: ■ ■ ■ ■ ■ ■ ■ ■ ■ introscope.changeDetector.changeDetector.5 or higher. ChangeDetector introscope.changeDetector.enable When set to true, this property enables Introscope ChangeDetector. It is set to false by default. 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.rootDir This property sets where the root directory for ChangeDetector is created. The root directory is the folder where ChangeDetector creates its local cache files. Default 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. Appendix A: Java Agent Properties 275 ChangeDetector introscope.changeDetector.isengardStartupWaitTimeInSec This property sets the time to wait after the agent starts before ChangeDetector tries to connect to the Enterprise Manager. Default 15 Example introscope.changeDetector.isengardStartupWaitTimeInSec=15 introscope.changeDetector.waitTimeBetweenReconnectInSec Specifies the number of seconds ChangeDetector waits before retrying a connection to the Enterprise Manager. Default 10 Example introscope.changeDetector.waitTimeBetweenReconnectInSec=10 introscope.changeDetector.agentID A string used by ChangeDetector to identify the Java Agent. Default SampleApplicationName Example introscope.changeDetector.agentID=SampleApplicationName 276 Java Agent Guide ChangeDetector introscope.changeDetector.profile The absolute or relative path to the ChangeDetector datasources configuration file. Default ChangeDetector-config.xml Example introscope.changeDetector.profile=ChangeDetector-config.xml Notes Use a backslash to escape the backslash character. introscope.changeDetector.profileDir The absolute or relative path to the datasource configuration file(s) directory. All datasource configuration file(s) from this directory will be used in addition to any file specified by the introscope.changeDetector.profile property (above) Default changeDetector_profiles Example introscope.changeDetector.profileDir=changeDetector_profiles Notes Use a backslash to escape the backslash character. Appendix A: Java Agent Properties 277 Cross-process tracing in WebLogic Server introscope.changeDetector.compressEntries.enable This property allows compression on the ChangeDetector data buffer. This could be useful if you experience memory consumption at start-up. Property settings True or False Default True 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. Cross-process tracing in WebLogic Server The following property configures cross-process tracing in WebLogic Server: ■ introscope.agent.weblogic.crossjvm (see page 279) 278 Java Agent Guide Cross-process transaction trace introscope.agent.weblogic.crossjvm Property settings True or False Default Commented out; True Example introscope.agent.weblogic.crossjvm=true Cross-process transaction trace Uncomment the following property to enable automatic collection of downstream traces due to tail filter. ■ introscope.agent.transactiontracer.tailfilterPropagate.enable (see page 279) 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 This property 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. Appendix A: Java Agent Properties 279 Dynamic ProbeBuilding Dynamic ProbeBuilding The following properties enable changes to PBDs to take effect without restarting the application server or the agent process: ■ ■ ■ ■ ■ ■ introscope.autoprobe.dynamicinstrument.enabled (see page 280) autoprobe.dynamicinstrument.pollIntervalMinutes (see page 281) introscope.autoprobe.dynamicinstrument.classFileSizeLimitInMegs (see page 281) introscope.autoprobe.dynamic.limitRedefinedClassesPerBatchTo (see page 281) introscope.agent.remoteagentdynamicinstrumentation.enabled (see page 282) introscope.autoprobe.dynamicinstrument.pollIntervalMinutes (see page 282) This is a very CPU intensive operation, and it is highly recommended to use configurations to minimize the classes that are being redefined. PBD editing is all that is required to trigger this process. 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 For more information about dynamic ProbeBuilding, see Dynamic ProbeBuilding (see page 68). 280 Java Agent Guide Dynamic ProbeBuilding 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 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 Appendix A: Java Agent Properties 281 autoprobe.dynamicinstrument. Default 1 Example introscope.agent.ErrorDetector introscope.dynamicinstrument. introscope.remoteagentdynamicinstrumentation.agent.throttle (see page 283) introscope.agent.pollIntervalMinutes=1 Notes You must restart the managed application before changes to this property take effect.pollIntervalMinutes Defines the polling interval in minutes to poll for PBD changes.<index> (see page 284) 282 Java Agent Guide .ignore.autoprobe.enabled=true Notes You must restart the managed application before changes to this property take effect.enable (see page 283) introscope.agent. ErrorDetector The following properties configure interaction with ErrorDetector: ■ ■ ■ introscope.agent.errorsnapshots. Property settings True or False Default True Example introscope.enabled This property enables or disables remote management of dynamic instrumentation.errorsnapshots.remoteagentdynamicinstrumentation.errorsnapshots. enable Enable the agent to captures transaction details about serious errors. Property settings True or False Default True Notes This property is dynamic.errorsnapshots.throttle The maximum number of error snapshots that the agent can send in a 15-second period. Requires Introscope Error Detector.agent.agent.agent.errorsnapshots.errorsnapshots. Default 10 Example introscope. Appendix A: Java Agent Properties 283 .ErrorDetector introscope. introscope.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. You can change the configuration of this property during run time and the change will be picked up automatically. Requires Introscope Error Detector. ignore. Requires Introscope Error Detector.directory=ext Notes Non-absolute names are resolved relative to the location of the IntroscopeAgent.directory (see page 284) introscope.extensions. Default ext Example introscope. Default Example definitions are provided. The following are examples only.1..HarmlessException* introscope. Example introscope. You can change the configuration of this property during run time and the change will be picked up automatically. as shown below. .ignore.ignore. Extensions The following property configures agent extensions: ■ introscope.<index> This indexed property allows you to specify error messages to ignore.agent.properties file. You may specify as many as you like (using . You may use wildcards (*).agent.2 . and commented out. Error snapshots will not be generated or sent for errors with messages matching these filters.extensions.agent.).agent. .Extensions introscope..0=*com.directory Specifies the location of all extensions to be loaded by the agent.agent.extensions.errorsnapshots. 284 Java Agent Guide .agent.1=*HTTP Error Code: 404* Notes This property is dynamic.errorsnapshots.0.errorsnapshots.company. 4. Note: Introscope Java NIO metrics are only available on Java 1. see Restricting Java NIO metrics (see page 287). Metric collection of Java NIO information is not available for JVM versions prior to Java 1. the Total Capacity (bytes) metric may overestimate the amout of memory allocated to NIO buffers. or NIO) capabilities introduced in Java 1.Java NIO Java NIO The Java Agent supports the Java New I/O (Java NIO. The Introscope Java Agent collects metrics for NIO channels. You can restrict the generation of certain NIO metrics. 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. For more information. There are buffer classes for all of Java's primitive types.5 JVMs or higher. Buffer classes represent memory in a continuous block. For more information. For more information on turning on and off Java NIO tracer groups. see Default tracer groups and toggles files (see page 114). together with a small number of data transfer operations. Since buffers may overlap. except boolean. You can turn off these tracer groups to further restrict metric generation. Java NIO tracer groups have been enabled by default. Java NIO is a collection of APIs designed to provide access to the low-level I/O operations of modern operating systems. see Channels (see page 286). Java NIO metrics capture information about how instrumented applications use Java NIO. Buffers Java NIO data transfer is based on buffers. which can share memory with byte buffers and allow arbitrary interpretation of the underlying bytes. Appendix A: Java Agent Properties 285 .5. If the first datagram is ‘to’ the endpoint. For example. The Java Agent collects metrics separately for each remote endpoint datagrams that are ‘sent to’ or ‘received from’. Channels Java NIO channels provide bulk data transfers to and from NIO buffers. all further datagrams to or from that endpoint are classified under NIO|Channels|Datagrams|Client|{HOST}|Port {PORT}.Java NIO Direct and non-direct buffers are collected separately because of their differences in memory location and relative costs for creation. This makes direct buffers optimal for I/O. but they may take more resources to create. except memory mapped files which are only direct buffers. where {HOST} and {PORT} are the remote endpoint. Introscope channel metrics characterise data flow rates through channels. are allocated as any normal Java object within the JVM heap. by constrast. Note: All buffer types may be either direct or non direct. Non-direct buffers. so are not subject to Java garbage collection and relocation. if the first datagram is ‘from’ the endpoint. 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. Direct buffers are allocated outside the JVM heap used for Java objects. This is a low-level data transfer mechanism that was specifically designed to address performance and scalability issues within standard Java I/O. Connections are c lassified as client or server depending on the direction of the first datagram observed from each ‘to’ or ‘from’ endpoint. where {PORT} is the local port. the Java Agent classifies all further datagrams to or from that endpoint under NIO|Channels|Datagrams|Server|Port {PORT}. the term "connection" is used in the description of NIODatagramTracing to describe how the Java Agent collects datagram metrics. as well as external systems. Channels provide mechanisms for moving bytes between buffers and external systems. Collected NIO channel metrics correspond to metrics currently created for file and socket I/O using standard Java I/O techniques. 286 Java Agent Guide . agent.ports (see page 291) These properties only affect the detail metrics generated by NIOSocketTracing and NIODatagramTracing tracer groups.client.nio.client. Datagram channels created using DatagramChannel connect method are considered client connections irrespective of direction of first datagram observed. Appendix A: Java Agent Properties 287 .profile file.agent. You can restrict generation of datagram and socket metrics by setting the following agent profile properties: ■ ■ ■ ■ ■ ■ introscope. found in the <Agent_Home>\wily folder of your Java Agent installation.hosts (see page 288) introscope.nio.client.Java NIO The Java Agent also generates backend metrics for client "connections".agent.hosts (see page 290) introscope.socket.agent. Note: Datagram channels created using a UDP connection (with a connect method) are considered client connections.datagram.nio.server. For more information.agent.client.server. except in the case of datagrams read by the 'receive' method.nio.socket.nio.nio.datagram.ports (see page 291) introscope. Restricting Java NIO metrics Configure the properties for Java NIO instrumentation in the IntroscopeAgent.socket.ports (see page 289) introscope.agent.datagram. see Default tracer groups and toggles files (see page 114).ports (see page 290) introscope. client.agent. You can change the configuration of this property during run time and the change will be picked up automatically. The property will.agent.nio. Duplicate host names are discarded.hosts Restricts metric reporting to 'client' UDP "connections" with specified host(s).datagram.nio. Default undefined (no value) Example introscope. however.client. This property is dynamic.hosts=hostA. Hosts may be specified by name or textual representation of IP address (in either IPv4 or IPv6 forms). Property settings Comma separated list of hosts. match client connections with any of the set of synonymous names.Java NIO introscope. In cases where multiple host names map to a single IP. no host restriction will apply. Invalid host names will be reported in the agent log and ignored.datagram.hostB Notes ■ ■ ■ ■ ■ If the list is left empty. only one of the names is retained. 288 Java Agent Guide . Duplicate ports are discarded.Java NIO introscope. Only 'client' datagram metrics for specified ports will be generated. Invalid port numbers will be reported in the agent log and ignored. In cases where multiple ports map to a single IP. Appendix A: Java Agent Properties 289 . Property settings Comma separated list of port numbers.ports Lists the ports that will report NIO metrics.agent. Port is the remote port to/from which datagrams are sent/received. You can change the configuration of this property during run time and the change will be picked up automatically.456.client. Default undefined (no value) Example introscope.agent. no port restriction will apply.datagram.datagram.789 Notes ■ ■ ■ ■ If the list is empty.nio. only one of the ports is retained. This property is dynamic.nio.client.ports=123. nio. Property settings Comma separated list of port numbers. 290 Java Agent Guide .agent.datagram. Hosts may be specified by name or textual representation of IP address (in either IPv4 or IPv6 forms).server. Property settings Comma separated list of hosts.ports=123. hostB Notes ■ ■ ■ ■ If the list is empty. This property is dynamic.client. Port is the local port through which datagrams are sent/received.nio. Default undefined (no value) Example introscope. You can change the configuration of this property during run time and the change will be picked up automatically.nio. no host restriction will apply. Invalid host names will be reported in the agent log and ignored. no port restriction will apply. Only 'server' datagram metrics for specified ports will be generated.agent.agent.hosts=hostA. introscope.agent.Java NIO introscope.client.nio. This property is dynamic.789 Notes ■ ■ ■ If the list is empty.socket. Invalid port numbers will be reported in the agent log and ignored. You can change the configuration of this property during run time and the change will be picked up automatically.hosts Restricts metric reporting to 'client' TCP "connections" with specified host(s).456. Default undefined (no value) Example introscope.server.datagram.ports Lists the ports that will report NIO metrics.socket. no port restriction will apply.agent.client.agent.789 Notes ■ ■ ■ If list is empty. Default undefined (no value) Example introscope. Property settings Comma separated list of port numbers. You can change the configuration of this property during run time and the change will be picked up automatically.Java NIO introscope.ports Lists the ports that will report NIO metrics.456. You can change the configuration of this property during run time and the change will be picked up automatically.nio.server.agent.ports=123. Port is the local port through which datagrams are sent/received. introscope. Invalid port numbers will be reported in the agent log and ignored. Invalid port numbers will be reported in the agent log and ignored. no port restriction will apply.client. This property is dynamic. Only 'client' socket metrics for specified ports will be generated.socket.nio.456. Port is the remote port to/from which datagrams are sent/received.ports Lists the ports that will report NIO metrics. This property is dynamic.socket.agent. Appendix A: Java Agent Properties 291 .socket.nio.nio.client. Only 'server' socket metrics for specified ports will be generated. Default undefined (no value) Example introscope.ports=123. Property settings Comma separated list of port numbers.socket.789 Notes ■ ■ ■ If list is empty. Property settings True or False.jsr77.name.agent.primarykeys (see page 296) introscope.enable Enables collection of JMX Metrics. For example.disable (see page 295) introscope.jmx.jmx.jmx.agent.jmx.agent.filter (see page 294) introscope.agent. 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.agent. Default Varies by agent version. 292 Java Agent Guide .attributes (see page 293) introscope.agent. comment out: TraceOneMethodWithParametersIfFlagged: NIODatagramTracing read NIODatagramConcurrentInvocationCounter "Concurrent Readers" JMX The following properties configure JMX metrics: ■ ■ ■ ■ ■ ■ introscope.jmx.name. Example introscope.name.jmx.enable (see page 292) introscope.excludeStringMetrics (see page 297) introscope.agent.agent. no tracers whose name ends with BackendTracer or MappingTracer should be commented out.JMX Java NIO metrics appear under the NIO node under the agent's top level node in the Workstation Investigator.jmx.enable=false Notes You must restart the managed application before changes to this property take effect.ignore. However.jmx. to suppress the Concurrent Readers metric for Datagrams. attributes Controls which (if any) JMX MBean attributes are to be ignored. Appendix A: Java Agent Properties 293 .agent. Default Commented out.JMX introscope. Example introscope. You must restart the managed application before changes to this property take effect.agent.ignore.ignore.jmx.jmx. the attribute will be ignored. Property settings A comma-separated list of keywords. Leave the list empty to include all MBean attributes.attributes=server Notes ■ ■ ■ If an MBean attribute name matches one on the list. server. JMX introscope.name. abxc.ExecuteThreadCurrentIdleCount. 294 Java Agent Guide . To match a literal * or ?.filter Specifies a comma-separated list of filter strings to determine what JMX data Introscope collects and displays. Examples: ■ ■ ■ ■ ab\\*c matches a metric name that contains ab*c ab*c matches a metric name that contains abc.agent.PendingRequestCurr entCount.j2eeType Notes ■ ■ Leave empty to include all MBean data available in the system. abxxc etc.OpenSessionsCurrentCount. Introscope reports JMX-generated metrics that match a filter string.j2eeType Example #introscope.OpenSess ionsCurrentCount.WaitingForConnect ionCurrentCount. You must restart the managed application before changes to this property take effect.ExecuteThreadCurrentIdleCount.filter=ActiveConnectionsCurrentCount. Filter strings can contain the asterisk (*) and question mark (?) wildcard characters: ■ ■ * matches zero or more characters ? matches a single character.name.jmx.WaitingForConnectionCurrentCount. For WebLogic: ActiveConnectionsCurrentCount. escape the character with \\. ab?c matches a metric name that contains abxc ab\\?c matches a metric names that contains ab?c Default Commented out.jmx.PendingRequestCurrentCount.agent. name.jmx.1. including complex JMX data.jsr77. Property settings True or False Default True Notes ■ ■ ■ JSR-77 Management support must be provided by the application server in order for this property to have any effect. You must restart the managed application before changes to this property take effect. Appendix A: Java Agent Properties 295 . This property is only available for use in the WebLogic and WebSphere IntroscopeAgent.profile files.name.enable was removed in Introscope 6.disable This property controls whether or not Introscope collects and reports full JSR77 data.agent. The property introscope.JMX introscope.jsr77.jmx.agent. and simplifies name conversion.jmx.0.JMX introscope.agent. Property settings for WebSphere: ■ ■ ■ ■ ■ ■ J2EEServer Application j2eeType JDBCProvider name mbeanIdentifier ■ You must restart the managed application before changes to this property take effect.name.jmx.profile file.name.primarykeys=J2EEServer Notes ■ Property settings for WebLogic: ■ ■ Type Name ■ ■ Comment out this property if using WebLogic Server 9. Default Commented out in default IntroscopeAgent. Property settings A comma-separated. 296 Java Agent Guide .agent. Example introscope.primarykeys User-defined order of MBean information. ordered list of keys which should uniquely identify a particular MBean. agent.enable (see page 298) introscope. To enable string-valued metrics. LeakHunter The following properties configure agent interaction with LeakHunter: ■ ■ ■ ■ ■ ■ introscope.leakhunter.agent.jmx. set this property value to false.LeakHunter introscope.append (see page 299) introscope.leakhunter.excludeStringMetrics=true Notes ■ ■ Excluding string-valued metrics reduces the overall metric count.jmx. Property settings True or False Default True Example introscope.timeoutInMinutes (see page 300) Appendix A: Java Agent Properties 297 .collectAllocationStackTraces (see page 298) introscope.agent.excludeStringMetrics Controls whether or not to include string-valued metrics.location (see page 300) introscope.agent.logfile.agent.agent.leakhunter.logfile.leakhunter. You must restart the managed application before changes to this property take effect.agent.leakhunter.leakSensitivity (see page 299) introscope.agent.leakhunter. improving agent and EM performance. collectAllocationStackTraces= false Notes ■ ■ Turning on this option has the potential to create higher system overhead.agent.agent.enable=false Notes ■ ■ Turning on this option has the potential to create higher system overhead.leakhunter. but requires additional memory and CPU overhead. introscope. in CPU usage and memory. Turning this on gives you more precise data about the potential leak's allocation. You must restart the managed application before changes to this property take effect. This property is dynamic.enable Enables LeakHunter functionality.agent.LeakHunter introscope.leakhunter. You can change the configuration of this property during run time and the change will be picked up automatically. 298 Java Agent Guide .leakhunter. in CPU usage and memory. Property settings True or False Default False Example introscope. Property settings True or False Default False Example introscope.leakhunter.agent.collectAllocationStackTraces Controls whether LeakHunter generates allocation stack traces for potential leaks. agent.leakSensitivity Controls the sensitivity level of LeakHunter.leakhunter.append Specifies whether to replace the log file or add information to an existing log file on application restart.agent.logfile. Default False Example introscope.leakhunter.append=false Notes You must restart the managed application before changes to this property take effect. True adds information to an existing log file.agent. Property settings Must be integer value from 1-10.leakhunter.logfile. Appendix A: Java Agent Properties 299 .LeakHunter introscope.agent. Default 5 Example introscope.leakSensitivity=5 Notes You must restart the managed application before changes to this property take effect. introscope. Property settings True or False ■ ■ False replaces the log file.leakhunter. A higher sensitivity setting will result in more potential leaks reported and a lower sensitivity will result in fewer potential leaks reported. agent. You must restart the managed application before changes to this property take effect. You must restart the managed application before changes to this property take effect.leakhunter.location=logs/LeakHunter.agent. no log file will be written. introscope.location Location of the LeakHunter. Property settings Must be a positive integer (no negative numbers). Default 120 Example introscope. Relative file names are relative to the application working directory.LeakHunter introscope.log This locates the log file in the logs directory of the agent. After the time-out.agent.leakhunter. LeakHunter will stop looking for new potential leaks and just continue tracking the previously identified potential leaks.timeoutInMinutes=120 Notes ■ ■ Set the value to zero if you want LeakHunter to always look for new potential leaks.agent. Example introscope.leakhunter.logfile. Default logs/LeakHunter.log file.leakhunter.timeoutInMinutes Controls the length of time (in minutes) LeakHunter spends looking for new potential leaks.logfile. 300 Java Agent Guide .log Notes ■ ■ If this property is commented out or left blank. ConversionPattern (see page 305) log4j.appender.IntroscopeAgent.<number> Use this to ignore any class matching any supplied patterns.util.4=java.sun.comment out any you want to use.logfile.6=com. Ten classes have been supplied by default .File (see page 304) log4j. it must be safe to call size() at any time.ignore.leakhunter. Default None Example introscope.context.Logging introscope.IntroscopeAgent.pbdlog.context.pbdlog.leakhunter.IntroscopeAgent (see page 302) log4j.layout.pbdlog.sun.pbdlog (see page 304) log4j. Property settings A comma-separated list of class matching patterns.layout (see page 305) log4j.appender.agent. You can change the configuration of this property during run time and the change will be picked up automatically. from any thread.leakhunter.BaseContextMap$Key Notes ■ ■ ■ Some collections cannot be used with LeakHunter.appender.appender.ignore.leakhunter.ignore.SubList introscope.faces.inheritance (see page 306) Appendix A: Java Agent Properties 301 .inheritance (see page 303) log4j.logger. In order for a collection to be LeakHunter-safe.agent.File (see page 303) log4j. You can used the "*" wildcard.5=com.BaseContextMap$EntrySe t introscope.agent.agent.ignore.logger.appender.faces.additivity. This property is dynamic. Logging The following properties configure agent logging options: ■ ■ ■ ■ ■ ■ ■ ■ log4j. 302 Java Agent Guide .logger.console.util.Log4JSeverityLevel Destination value can be: ■ ■ ■ console logfile both console and logfile Default INFO. console.wily.Logging log4j.feedback.logger.logfile Notes Changes to this property take effect immediately and do not require the managed application to be restarted. Property settings Level of detail value can be: ■ ■ INFO VERBOSE#com.IntroscopeAgent This property controls both the logging level and the output location for log information. logfile Example log4j.IntroscopeAgent=INFO. log Notes System properties (Java command line -D options) are expanded as part of the file name.IntroscopeAgent .appender.log file if logfile is specified in log4j.appender.log.property=Server1. Default IntroscopeAgent. log4j.pbdlog Appendix A: Java Agent Properties 303 .File=logs/Introscope-Server1.inheritance Controls log level and destination for log messages about classes that require instrumentation. set this property to: INFO.File Specifies the name and location of IntroscopeAgent.IntroscopeAgent.logger.logfile. The filename is relative to the directory that contains the agent profile.logger. pbdlog For information about inheritance class logging see Controlling directive logging (see page 75). Default None Example log4j.File=logs/IntroscopeAgent.File=logs/Introscope-${my. Property settings To configure logging of classes that have not been instrumented because they extend a supertype or interface.property}.appender.Logging log4j. then log4j.logfile. if Java is started with -Dmy.appender.log is expanded to: log4j.IntroscopeAgent.inheritance=INFO.logfile.log Example log4j.logfile.logger. For example. agent.appender.appender.appender.pbdlog.wily.introscope.Logging log4j. Property settings To configure logging of classes that have not been instrumented because they extend a supertype or interface set to: pbdupdate.File=pbdupdate.log Default None Example log4j.AutoNamingRollingFileAppender 304 Java Agent Guide .log log4j.wily.appender. Property settings To configure logging of classes that have not been instrumented because they extend a supertype or interface.pbdlog. set this property to: com.agent.pbdlog=com.AutoNamingRollingFileAppender Default None Example log4j.File Identifies a log file for messages about classes that require instrumentation.pbdlog Specifies a package for logging messages about classes that require instrumentation.introscope. 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.apache.wily. Property settings To configure logging of classes that have not been instrumented because they extend a supertype or interface.log4j. set this property to: %d{M/dd/yy hh:mm:ss a z} [%-3p] [%c] %m%n Default None Example log4j.appender.layout.pbdlog.ConversionPattern=%d{M/dd/yy hh:mm:ss a z} [%-3p] [%c] %m%n Appendix A: Java Agent Properties 305 .org.Logging log4j.layout.appender.layout=com. set this property to: com.org.wily.layout Specifies rules for logging messages about classes that require instrumentation.appender.log4j.PatternLayout Default None Example log4j.pbdlog.pbdlog.pbdlog.appender.apache.PatternLayout log4j. additivity.additivity.IntroscopeAgent. Property settings True or False Default True Example log4j.log file.Metric count log4j.agent.IntroscopeAgent.ext.inheritance=true Notes To configure the logging of multiple level inheritance directives in the pbdupdate. Metric count The following property affects where you will see the Metric Count metric in the Investigator: ■ introscope.inheritance Causes the directives for multiple level inheritance to be logged only in the pbdupdate.log only.count (see page 307) 306 Java Agent Guide . add this property to the agent profile and set to false.metric. disableDirectivesChange (see page 310) Appendix A: Java Agent Properties 307 .agent. Enable the following properties to determine those cases after the application server or the agent process starts up.executionCount (see page 309) introscope. If you want to see the Metric Count metric under the Agent Stats node.hierarchysupport.autoprobe. ■ ■ ■ ■ ■ ■ introscope.autoprobe.autoprobe.metric. Property settings True or False Default Not present in the IntroscopeAgent. False Example introscope.hierarchysupport.hierarchysupport. the Metric Count is displayed as under the Custom Metric Agent node.agent.ext.autoprobe.profile.hierarchysupport.count Controls where you will see the Metric Count metric in the Investigator. the agent is unable to detect multiple inheritance and hence those classes are not instrumented.profile and set it to true to see the ‘Metric Count’ metric under the ‘Agent Stats’ node.autoprobe.pollIntervalMinutes (see page 309) introscope. By default.runOnceOnly (see page 308) introscope. add this property to the IntroscopeAgent.autoprobe.disableLogging (see page 310) introscope.count=true Notes Add this property to the IntroscopeAgent.hierarchysupport. These properties log classes which need to be instrumented but have not been and relies on dynamic instrumentation to affect the changes.metric.ext.profile.hierarchysupport.Multiple inheritance introscope.enabled (see page 308) introscope. Multiple inheritance For directives based on interfaces or super classes. You must restart the managed application before changes to this property take effect. 308 Java Agent Guide .autoprobe. Property settings True or False Default False Example introscope.5 using AutoProbe and dynamic instrumentation.autoprobe.enabled=true Notes You must restart the managed application before changes to this property take effect. Property settings True or False Default True Example introscope.Multiple inheritance introscope. introscope. you can use this property to control whether the utility that enables the feature runs only once. Change this property to true only if you need detection on a periodic basis.enabled For agents that run under JDK 1. you can use this property to enable instrumentation of classes that extend a supertype or interface.hierarchysupport. or at a specified interval.autoprobe.hierarchysupport.hierarchysupport.enabled=false Notes ■ ■ Logging properties related to dynamic instrumentation are defined in Logging.hierarchysupport.runOnceOnly If you have enabled instrumentation of classes that extend a supertype or interface.autoprobe. Using this property overrides the run once only setting.autoprobe.executionCount If you need the polling interval to run a finite times instead of running it only once or running it periodically.pollIntervalMinutes=5 Notes You must restart the managed application before changes to this property take effect.Multiple inheritance introscope. introscope.autoprobe. use this property to specify the exact number of times the polling interval is run. In most cases this happens only once. Always use this property to specify the exact number of times it should run. however. Default 5 Example introscope.autoprobe. Default 3 Example introscope.executionCount=3 Notes You must restart the managed application before changes to this property take effect. Appendix A: Java Agent Properties 309 .hierarchysupport. a conservative value is recommended to account for application server initialization.pollIntervalMinutes The polling interval to check for classes which could not be instrumented due to multiple inheritance.hierarchysupport.autoprobe. Property settings A positive integer.hierarchysupport.hierarchysupport. disableDirectivesChange=true Notes You must restart the managed application before changes to this property take effect.monitor.disableDirectivesChange Uncomment this property to only log the changes and disable the triggering of dynamic instrumentation.autoprobe.autoprobe.Platform monitoring introscope.platform.hierarchysupport. introscope.disableLogging=true Notes You must restart the managed application before changes to this property take effect. Property settings True or False Default True Example introscope.autoprobe.hierarchysupport.disableLogging Uncomment this property if you do not need to log the classes being detected.system (see page 311) 310 Java Agent Guide .hierarchysupport.hierarchysupport. Property settings True or False Default True Example #introscope.autoprobe. Platform monitoring The following property configures platform monitoring metrics: ■ introscope. Only uncomment this property if dynamic instrumentation is enabled.agent. platform. Property settings True or False Default True Example introscope.remoteagentconfiguration.system Name of operating system to load a platform monitor for.Remote configuration introscope.remoteagentconfiguration. Example introscope.agent. Appendix A: Java Agent Properties 311 .enabled This property enables or disables remote configuration of the agent.monitor.remoteagentconfiguration. varies by platform. Remote configuration The following properties allow remote configuration of the Java Agent: ■ ■ introscope.agent.system=Solaris Notes You must restart the managed application before changes to this property take effect. Property settings See Troubleshooting platform monitoring (see page 234) for more information about the options for this property.monitor.agent.enabled=true Notes Changes to this property take effect immediately and do not require the managed application to be restarted.remoteagentconfiguration.allowedFiles (see page 312) introscope.agent.enabled (see page 311) introscope.agent.agent.platform. Default Commented out. Security The following property configures security of HTTP headers being sent to CA Wily CEM: ■ introscope.security (see page 312) introscope.decorator.xml Notes Changes to this property take effect immediately and do not require the managed application to be restarted.remoteagentconfiguration.decorator.allowedFiles=domainconfig.allowedFiles This property lists the exact list of files that are allowed to be remotely transferred to this agent.xml Default domainconfig.security=clear 312 Java Agent Guide .xml Example introscope.decorator.agent.agent.agent. which are sent to CA Wily CEM.agent. Property settings domainconfig.security This property determines the format of decorated HTTP response headers.agent.remoteagentconfiguration. Property settings Clear: clear text encoding Encrypted: header data is encrypted Default Clear Example introscope.Security introscope. ports (see page 315) introscope.enabled (see page 313) introscope.socket. it configures the agent to add additional performance monitoring information to HTTP response headers.client.io.agent.socket.Servlet header decorator Servlet header decorator The following property enables correlation of transactions between Wily CEM and Wily Introscope: ■ introscope.agent.socket.ports (see page 315) Appendix A: Java Agent Properties 313 .agent.agent. for example: x-wily-info Property settings True or False Default False Example introscope.agent.hosts (see page 314) introscope.client.agent.decorator.io.sockets.reportRateMetrics (see page 314) introscope.decorator.decorator.enabled If this Boolean value is set to true.server.enabled=false Socket metrics Generation of I/O Socket metrics may be restricted by the following parameters: ■ ■ ■ ■ introscope. ServletHeaderDecorator attaches the GUID to each transaction and inserts the GUID into an HTTP header.agent.io. You must restart the managed application before changes to this property take effect.sockets.reportRateMetrics=false Notes ■ ■ Only functions if ManagedSocketTracing is enabled and SocketTracing is disabled. You can change the configuration of this property during run time and the change will be picked up automatically. Example introscope.reportRateMetrics Enables reporting of individual socket's input/output (I/O) bandwidth rate metrics.agent.client. Property settings A comma-separate list of values.io. See Backwards compatibility (see page 162) for more information.agent.hosts Restrict socket client connections instrumented to those with specified remote hosts. This property is dynamic.io. 314 Java Agent Guide . or after exclusion of any invalid values is an empty list. Property settings True or False Default False Example introscope. introscope.agent. it will be ignored.socket.sockets.hosts= Notes ■ ■ ■ If any individual value is invalid. no restriction will apply to that parameter.socket.Socket metrics introscope.client. If any parameter is not defined.agent. introscope.ports= Notes ■ ■ ■ If any individual value is invalid. If any parameter is not defined. no restriction will apply to that parameter.server.server. If any parameter is not defined.Socket metrics introscope.ports Restrict socket client connections instrumented to those using specified local ports. it will be ignored.io. Example introscope. You can change the configuration of this property during run time and the change will be picked up automatically. This property is dynamic. This property is dynamic. or after exclusion of any invalid values is an empty list.agent.io.ports Restrict socket client connections instrumented to those with specified remote ports Property settings A comma-separate list of values. or after exclusion of any invalid values is an empty list. Appendix A: Java Agent Properties 315 .ports= Notes ■ ■ ■ If any individual value is invalid. no restriction will apply to that parameter.socket.socket. You can change the configuration of this property during run time and the change will be picked up automatically. Property settings A comma-separate list of values.io. Example introscope.agent.client.agent.client.socket.io.socket.agent. it will be ignored. thus creating blame metrics.regex.matchFallThrough (see page 318) introscope.SQL Agent SQL Agent The following properties configure aspects of the SQL Agent: ■ ■ ■ ■ ■ ■ ■ ■ introscope.regex.agent.sqlagent.agent.replaceAll (see page 319) introscope. see Configuring the Introscope SQL Agent.agent.sqlagent.agent.regex.sqlagent.normalizer.normalizer.normalizer.sqlagent. Property settings True or False Default True Example introscope.sqlagent.agent.normalizer.agent.agent.normalizer.key1.agent.regex.normalizer.pattern (see page 319) introscope.extension (see page 317) introscope.agent.key1.normalizer. The following property is used to set the custom SQL Agent normalizer extension: 316 Java Agent Guide . introscope.useblame (see page 316) introscope.sqlagent.sqlagent.sqlagent.regex.sqlagent.replaceFormat (see page 320) introscope.key1.regex.useblame=true Notes You must restart the managed application before changes to this property take effect.caseSensitive (see page 320) For more information.keys (see page 318) introscope.useblame This property configures the SQL Agent to optionally participate in the Introscope blame stack.agent.sqlagent.key1. normalizer.sqlagent.sqlagent.regex.agent. If you specify a comma separated list of names.replaceAll (see page 319) introscope.sqlagent.normalizer.extension Specifies the name of the SQL normalizer extension that will be used to override the preconfigured normalization scheme.agent.keys (see page 318) introscope.key1. Default RegexSqlNormalizer Example introscope.normalizer.sqlagent. you also must configure the regular expressions SQL statement normalizer properties: ■ ■ ■ ■ ■ ■ introscope.pattern (see page 319) introscope.extension=ext1.normalizer.agent.agent.sqlagent.caseSensitive (see page 320) Changes to this property take effect immediately and do not require the managed application to be restarted. ext2 Only ext1 will be used for normalization.sqlagent.normalizer. For example: introscope. Appendix A: Java Agent Properties 317 .agent.agent.regex.regex. To make custom normalization extension work.agent. Limits how much of a SQL statement appears in the Investigator tree for SQL Agent metrics.regex.sqlagent.key1. Property settings The name of the SQL normalizer extension that is used to override the preconfigured normalization scheme.agent.matchFallThrough (see page 318) introscope.sqlagent. only the first name will be used.agent. the value of its manifest attribute com-wily-Extension-Plugin-{pluginName}-Name should match the value given in this property.key1.extension=RegexSqlNormalizer Notes If you use the default setting.SQL Agent introscope.normalizer.normalizer. in bytes.regex.regex.sqlagent.normalizer.normalizer.replaceFormat (see page 320) introscope.key1. agent. Default key1 Example introscope.sqlagent. 318 Java Agent Guide .regex. the normalized SQL output from that group is returned.matchFallThrough=false Notes Changes to this property take effect immediately and do not require the managed application to be restarted.sqlagent.matchFallThrough Use this property in conjunction with introscope.agent.agent.normalizer. If the property is set to false. and so on.normalizer.sqlagent. They are evaluated in order. as soon as a key group matches. the normalized SQL output from group1 is fed as input to group2. Property settings True or False Default false Example introscope.regex.regex. This property specifies the regex group keys.keys Use this property in conjunction with introscope. if SQL matches multiple key groups.regex.normalizer.keys=key1 Notes Changes to this property take effect immediately and do not require the managed application to be restarted. For example.normalizer.extension (see page 317) to set the regular expressions SQL statement normalizer. it will evaluate SQL strings against all regex key groups.normalizer.SQL Agent introscope.agent.agent.sqlagent. When this property is set to true.sqlagent.normalizer.extension (see page 317) to set the regular expressions SQL statement normalizer.agent. introscope.sqlagent. The implementation is chained. Property settings All valid regex entries allowed by java.SQL Agent introscope.agent.sqlagent.regex.extension (see page 317) to set the regular expressions SQL statement normalizer.normalizer.Regex package can be used here.agent.replaceAll Use this property in conjunction with introscope.*call(.FOO(.sqlagent.normalizer.agent.regex.regex.normalizer.pattern Use this property in conjunction with introscope. If set to true.*\)\.sqlagent.key1. it will replace the first occurrence of the matching pattern in the SQL query with the replacement string. introscope.agent. When this property is set to false.*\)\.normalizer.util. Appendix A: Java Agent Properties 319 . Default .sqlagent.*call(.sqlagent.key1.*\) Notes Changes to this property take effect immediately and do not require the managed application to be restarted.agent.*\) Example introscope.regex.FOO(.replaceAll=false Notes Changes to this property take effect immediately and do not require the managed application to be restarted.normalizer.normalizer.key1. This property specifies the regex pattern that will be used to match against the SQL.agent.extension (see page 317) to set the regular expressions SQL statement normalizer. Property settings True or False Default false Example introscope.sqlagent.pattern=. it will replace all occurrences of the matching pattern in the SQL query with replacement the string.key1. normalizer.util.regex.normalizer.regex. Property settings All valid regex entries allowed by the java.agent. 320 Java Agent Guide .regex.key1.sqlagent.replaceFormat Use this property in conjunction with introscope.Matcher class can be used here.util.Regex package and java.normalizer.sqlagent.agent.SQL Agent introscope.extension (see page 317) to set the regular expressions SQL statement normalizer.key1.normalizer.sqlagent.agent.caseSensitive Use this property in conjunction with introscope. Default $1 Example introscope.caseSensitive=false Notes Changes to this property take effect immediately and do not require the managed application to be restarted.regex.agent. Property settings true or false Default false Example introscope.key1.extension (see page 317) to set the regular expressions SQL statement normalizer.normalizer.agent.sqlagent. This property specifies whether the pattern match is sensitive to case.replaceFormat=$1 Notes Changes to this property take effect immediately and do not require the managed application to be restarted.sqlagent.normalizer. This property specifies the replacement string format.key1.sqlagent.agent. introscope.regex. enterprisemanager. Appendix A: Java Agent Properties 321 .tcp.DEFAULT introscope.transport.host.enterprisemanager.host.enterprisemanager.agent.DEFAULT introscope.tcp. Default localhost Example introscope.transport.keypassword.tcp.transport.port.agent.tcp.host.enterprisemanager.DEFAULT=localhost Notes You must restart the managed application before changes to this property take effect.agent.socketfactory.transport.enterprisemanager.agent.DEFAULT introscope.enterprisemanager.agent.transport.agent.tcp.transport.enterprisemanager.agent.tcp.tcp.ciphersuites.enterprisemanager.DEFAULT Settings the Java Agent uses to find the Enterprise Manager and names given to host and port combinations.SSL communication SSL communication The agent can connect to the Enterprise Manager over SSL.agent.DEFAULT introscope.tcp.transport.DEFAULT introscope.trustpassword.truststore. Use the following properties to configure that communication: ■ ■ ■ ■ ■ ■ ■ ■ introscope.transport.keystore.agent.agent.DEFAULT introscope.tcp.DEFAULT introscope.tcp.DEFAULT introscope.enterprisemanager.enterprisemanager.transport.transport. agent. 322 Java Agent Guide .enterprisemanager.transport.tcp.transport.postofficehub.isengard.DEFAULT=5443 Notes You must restart the managed application before changes to this property take effect.socketfactory.is engard.link.tcp.agent. Default com.port.enterprisemanager.net.DEFAULT=com.net.enterprisemanager.postofficehub.wily.transport.DEFAULT Settings the Java Agent uses to find the Enterprise Manager and names given to host and port combinations.link.socketfactory. Default 5443 Example introscope.agent.SSLSocketFactory Example ntroscope.SSL communication introscope.wily.SSLSocketFactory Notes You must restart the managed application before changes to this property take effect.tcp.agent.enterprisemanager. introscope.tcp.transport.port.DEFAULT Settings the Java Agent uses to find the Enterprise Manager and names given to host and port combinations. truststore.enterprisemanager.tcp. Property settings Either an absolute path or a path relative to the agent's working directory.DEFAULT= introscope.agent. the agent trusts all certificates.DEFAULT The password for the truststore.transport.keystore.keystore. A keystore is needed if the Enterprise Manager requires client authentication.agent.SSL communication introscope.tcp.transport.enterprisemanager. If no truststore is specified. backslashes must be escaped.transport.transport.truststore.tcp. Property settings Either an absolute path or a path relative to the agent's working directory.trustpassword.agent.DEFAULT Location of a keystore containing the agent's certificate. Example introscope. For example: C:\\keystore Appendix A: Java Agent Properties 323 .agent.tcp.agent. Example introscope. Example introscope.tcp.DEFAULT=c:\\keystore Notes On Windows.DEFAULT Location of a truststore containing trusted Enterprise Manager certificates.enterprisemanager.enterprisemanager.transport.enterprisemanager.transport.trustpassword.DEFAULT=/var/trustedc erts Notes On Windows. For example: C:\\keystore introscope.agent.tcp.enterprisemanager. backslashes must be escaped. enterprisemanager.transport. Property settings A comma-separated list of cipher suites.thresholdseconds (see page 325) introscope.tcp.resolutionseconds (see page 325) For more information on stall metric properties.DEFAULT=SSL_DH_anon_WITH_RC4_128_MD5 Notes If not specified.tcp.tcp.DEFAULT=MyPassword76 8 introscope.agent.stalls. Example introscope. use the default enabled cipher suites.tcp.agent.transport.ciphersuites.transport.keypassword. 324 Java Agent Guide .keypassword.agent.agent.enterprisemanager.enterprisemanager.enterprisemanager.agent. see Disabling the capture of stalls as Events (see page 208).transport. Stall metrics The following properties are for stall metrics: ■ ■ introscope.DEFAULT Set the enabled cipher suites.stalls. Example introscope.Stall metrics introscope.agent.DEFAULT The password for the keystore. ciphersuites. stalls.resolutionseconds Specifies the frequency that the agent checks for stalls.agent.Stall metrics introscope.stalls. introscope.agent.agent. You can change the configuration of this property during run time and the change will be picked up automatically.resolutionseconds=10 Notes This property is dynamic. Default 10 Example introscope.stalls. Appendix A: Java Agent Properties 325 . Default 30 Example introscope.thresholdseconds=30 Notes This property is dynamic.agent.thresholdseconds Specifies the minimum threshold response time at which time a transaction is considered stalled. You can change the configuration of this property during run time and the change will be picked up automatically.stalls. transactiontracer.parameters (see page 327) introscope.httpsession.httprequest.headers (see page 326) introscope.parameter.crossprocess.agent.headers Specifies (in comma-separated list) HTTP request header data to capture.headers=User-Agent Notes The IntroscopeAgent.attributes (see page 327) introscope.sampling.agent.enabled (see page 333) introscope.seconds (see page 334) introscope.userid.transactiontracer.profile contains a commented out statement that sets the value of this property to a null value. see Configuring Transaction Trace Options (see page 203).transactiontracer.httprequest.parameter.key (see page 328) introscope.transactiontracer.interval.agent.parameter.agent.agent. introscope.maxlimit (see page 333) introscope.httprequest.agent.count (see page 334) introscope.agent.transactiontracer.transactiontracer.agent. Use a comma separated list.agent.componentCountClamp (see page 330) introscope.headFilterClamp (see page 335) For more information.sampling.transactiontrace. User-Agent Example introscope. The user may optionally uncomment the statement and supply the desired header names.method (see page 329) introscope.agent.transactiontracer.transactiontracer.agent.correlationid.sampling.transactiontrace.userid.perinterval.httprequest.compression.parameter.compression (see page 331) introscope.Transaction tracing Transaction tracing The following properties are for transaction tracing and sampling: ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ introscope.agent.transactiontracer. 326 Java Agent Guide .parameter. Default Commented out.minlimit (see page 332) introscope.crossprocess.crossprocess.agent.transactiontracer.agent.agent. Transaction tracing introscope. Example introscope.agent.parameter.parameter.pa rameter2 Notes The IntroscopeAgent.agent.parameter. Appendix A: Java Agent Properties 327 .attributes=attribute1.profile contains a commented out statement that sets the value of this property to a null value.agent.parameters Specifies (in comma-separated list) HTTP request parameter data to capture.httpsession. Example introscope.transactiontracer.attributes Specifies (in comma-separated list) HTTP session attribute data to capture. generic parameters. Default Commented out.agent.profile contains a commented out statement that sets the value of this property to a null value.transactiontracer. The user may optionally uncomment the statement and supply the desired parameter names.at tribute2 Notes The IntroscopeAgent.parameters=parameter1.httpsession.transactiontracer.httprequest.transactiontracer. generic parameters. introscope. The user may optionally uncomment the statement and supply the desired parameter names.httprequest. Default Commented out.parameter. getValue.transactiontracer.a ttribute2 Notes The IntroscopeAgent.getHeader or HttpServletRequest. generic parameters.agent. Default Commented out.agent. Example #introscope.key User-defined key string.agent. in your environment.httpsession.method (see page 329).transactiontracer. see introscope. For more information.userid. user IDs are accessed using HttpServletRequest. 328 Java Agent Guide . The user may optionally uncomment the statement and supply the correct value if.Transaction tracing introscope.userid.attributes=attribute1.transactiontracer.parameter.profile contains a commented out statement that sets the value of this property to a null value. getRemoteUser HttpServletRequest.method=HttpServletRequest. The Agent profile includes a commented out property definition for each of the three allowable values. Property settings Allowable values are: ■ ■ ■ HttpServletRequest.agent.profile includes a commented out property definition for each of the three allowable values.userid.method=HttpServletRequest.method Specifies the method that returns User IDs.getValue Appendix A: Java Agent Properties 329 .transactiontracer.transactiontracer.transactiontracer.getRemoteUser #introscope. Example The IntroscopeAgent. Uncomment the appropriate statement. introscope.agent.userid.agent.userid.getHeader HttpServletRequest. or getValue.getHeader #introscope. getHeader.Transaction tracing introscope. based on whether user ID is accessed by getRemoteUser.transactiontracer.userid.agent.getValue Default Commented out. see options above. You can uncomment the property you want to use.method=HttpSession. You can change the configuration of this property during run time and the change will be picked up automatically.Transaction tracing introscope.agent. In extreme cases. Default 5000 Warning: If the clamp size is increased. and the trace stops. warnings appear in the log. the maximum heap size for the JVM may need to be adjusted or the managed application could run out of memory.agent.transactiontrace. When the set limit is reached.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. Example introscope. 330 Java Agent Guide . the requirements on memory are higher.componentCountClamp Limits the number of components allowed in a transaction trace. This property is dynamic. none Default lzma Example introscope. so if interoperability is required.Transaction tracing introscope. do not use gzip.agent.NET Agents do not support the gzip option.agent. This property is dynamic.crossprocess.compression=lzma Notes ■ ■ ■ ■ This option will increase agent CPU overhead. Appendix A: Java Agent Properties 331 . lzma compression is more efficient than gzip. You can change the configuration of this property during run time and the change will be picked up automatically. Property settings lzma.crossprocess. but reduce the size of interprocess headers. gzip. but may use more CPU. .compression Use this property to reduce the size of cross process transaction tracing data. crossprocess. The default setting of 1500 usually results in no impact to CPU overhead in normal conditions.agent. Property settings Can be set from 0 to twice the total maximum limit. set in the introscope. If set below the default of 1500.minlimit Use this property to set the minimum length of cross process parameter data length for which to apply compression.minlimit=1500 Notes ■ ■ Used with the introscope.agent. Default 1500 Example introscope.crossprocess.compression.Transaction tracing introscope. You can change the configuration of this property during run time and the change will be picked up automatically.agent.agent.maxlimit (see page 333).crossprocess.compression.compression property above.correlationid. This property is dynamic. 332 Java Agent Guide . the compression will run more frequently and consume more CPU overhead.crossprocess. transactiontracer.minlimit properties above This property is dynamic.agent.agent. Appendix A: Java Agent Properties 333 . introscope.crossprocess.enabled=false Notes Changes to this property take effect immediately and do not require the managed application to be restarted.compression. even after applying compression. However.Transaction tracing introscope.maxlimit Maximum size of cross process parameter data allowed.transactiontracer.compression and introscope.agent. You can change the configuration of this property during run time and the change will be picked up automatically.maxlimit=4096 Notes ■ ■ Used with the introscope.correlationid.agent. Default 4096 Example introscope. some data will be dropped and some cross process correlation functionality will not work properly.crossprocess.enabled Uncomment the following property to disable Transaction Tracer Sampling. If the total size of cross process parameter data is more than this limit.sampling.crossprocess.correlationid.agent.crossprocess. Property settings True or False Default False Example introscope. this settings will protect user transactions from failing in network transmission due to too large header size.sampling.agent. sampling. Configuring this property in the agent disables the configuration in the Enterprise Manager. See the Introscope Configuration and Administration Guide for more information.sampling.count This property is normally configured in the Enterprise Manager.transactiontracer.transactiontracer.count=1 Notes You must restart the managed application before changes to this property take effect.seconds This property is normally configured in the Enterprise Manager. 334 Java Agent Guide . Default 1 Example introscope.interval.interval.agent.perinterval. Configuring this property in the agent disables the configuration in the Enterprise Manager. introscope.sampling.agent. See the Introscope Configuration and Administration Guide for more information.sampling.seconds=120 Notes You must restart the managed application before changes to this property take effect.transactiontracer. Default 120 Example introscope.agent.perinterval.Transaction tracing introscope.transactiontracer.agent. is active to select the transaction for collection. which is the process of examining the start of a transaction for the purpose of potentially collecting the entire transaction. Garbage collection behavior will be affected. Example introscope. Head filtering checks until the first blamed component exits.transactiontrace. 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.headFilterClamp Uncomment this property to specify the maximum depth of components allowed in head filtering. Appendix A: Java Agent Properties 335 .agent.transactiontrace.Transaction tracing introscope. such as sampling or user-initiated transaction tracing. which can be a problem on very deep call stacks when no clamping is done. which will have an application-wide performance impact.agent. Any Transaction Trace whose depth exceeds the clamp will no longer be examined for possible collection UNLESS some other mechanism.headFilterClamp=30 Notes ■ ■ Changes to this property take effect immediately and do not require the managed application to be restarted. the requirement on memory is higher. Default 30 Warning: If the clamp size is increased. default.agent.format (see page 337) For more information. URL grouping The following properties are for configuring URL Groups for frontend metrics: ■ ■ ■ introscope. Property settings Integers.keys (see page 337) introscope.ttClamp=50 Notes ■ ■ You must restart the managed application before changes to this property take effect. Default 50 Example introscope.group.agent.URL grouping introscope.agent. 336 Java Agent Guide . If the property is not set (left blank).urlgroup.pathprefix (see page 337) introscope. see Using URL groups (see page 196).default.ttClamp This property limits the number of transactions that are reported by the agent per reporting cycle. the value defaults to 200.urlgroup.agent.agent.group.urlgroup. alpha should precede beta in the keys parameter.agent. if the URL Group with key alpha contains a single address.default.agent. the order in which you list the keys for the URL Groups in this property is important. For example.agent.group. The URL Group defined by the narrower pattern should precede the URL Group specified by the broader pattern.agent.keys=default Notes If a URL address belongs to two URL Groups.pathprefix=* introscope.pathprefix Configuration settings for frontend naming.urlgroup.format Configuration settings for Frontend naming. and the URL Group with key beta includes all addresses on the network segment that contains the address in the first URL Group.urlgroup.urlgroup.format=default Appendix A: Java Agent Properties 337 .default. Default * Example introscope.agent.group. Default Default Example introscope.group.keys Configuration settings for Frontend naming.urlgroup.agent.group.URL grouping introscope.urlgroup. Default Default Example introscope. introscope.default.default.urlgroup. objref (see page 349) These properties are found in the IntroscopeAgent.enable.enable (see page 339) introscope.pmi.enable.agent.webServices (see page 347) introscope.jvmpi (see page 342) introscope.agent.transaction (see page 346) introscope.wsgw (see page 348) introscope.cache (see page 340) introscope.enable.pmi.alarmManager (see page 339) introscope.wlm (see page 348) introscope.filter.pmi.agent.orbPerf (see page 344) introscope.agent.servletSessions (see page 345) introscope.pmi.pmi.agent.profile file.hamanager (see page 341) introscope.pmi.agent.jvmRuntime (see page 343) introscope.agent.system (see page 345) introscope.enable.pmi.agent.agent.pmi.agent.pmi.enable.enable.enable.pmi.pmi.enable.j2c (see page 342) introscope.agent.connectionPool (see page 341) introscope.bean (see page 340) introscope.pmi.WebSphere PMI WebSphere PMI The following properties configure WebSphere PMI metrics: ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ introscope.agent.enable.objectPool (see page 343) introscope.enable.enable.pmi.pmi.agent.agent.scheduler (see page 344) introscope.websphere.enable.enable.enable.enable.agent.pmi.enable.enable.enable.pmi.enable. 338 Java Agent Guide .webApp (see page 347) introscope.agent.agent.pmi.agent.pmi.agent.threadPool (see page 346) introscope. or the default agent profile for a WebSphere installation.pmi.agent.agent.pmi.pmi. Property settings True or False Default False Example introscope.enable.enable Enables collection of data from WebSphere PMI.pmi.alarmManager Enables collection of PMI alarm manager data when set to true.pmi.pmi. introscope.enable. Property settings True or False Default True Example introscope.alarmManager=false Notes ■ ■ The alarm manager data category must be turned on in WebSphere to be visible as Introscope data. Appendix A: Java Agent Properties 339 .WebSphere PMI introscope.enable=true Notes You must restart the managed application before changes to this property take effect.agent.agent.agent.pmi. You must restart the managed application before changes to this property take effect.agent. enable.agent.agent. Property settings True or False Default False Example introscope. Property settings True or False Default False Example introscope. You must restart the managed application before changes to this property take effect.enable.pmi.bean Enables collection of PMI bean data.agent.enable.pmi.agent. 340 Java Agent Guide .cache Enables collection of PMI cache data when set to true.pmi.bean=false introscope.enable.WebSphere PMI introscope.cache=false Notes ■ ■ The cache data category must be turned on in WebSphere to be visible as Introscope data.pmi. pmi.pmi.pmi.enable.connectionPool=true introscope. Property settings True or False Default True Example introscope.pmi. Property settings True or False Default False Example introscope.connectionPool Enables collection of PMI connectionPool data.agent.WebSphere PMI introscope.enable.hamanager Enables collection of PMI manager data when set to true.enable.agent.agent.enable. You must restart the managed application before changes to this property take effect.hamanager=false Notes ■ ■ The manager data category must be turned on in WebSphere to be visible as Introscope data.agent. Appendix A: Java Agent Properties 341 . You must restart the managed application before changes to this property take effect.enable. Property settings True or False Default False Example introscope.agent. JVMPI must be turned on in WebSphere.agent.j2c=true Notes ■ ■ The J2C data category must be turned on in WebSphere to be visible as Introscope data. introscope. 342 Java Agent Guide .jvmpi=false Notes For data to be provided to this module.agent.pmi.agent. Property settings True or False Default True Example introscope.jvmpi Enables collection of PMI JVM PI data.enable.WebSphere PMI introscope.j2c Enables collection of PMI J2C data when set to true.enable.enable.pmi.pmi.pmi. agent.enable.agent. Property settings True or False Default False Example introscope. You must restart the managed application before changes to this property take effect.agent.enable. Appendix A: Java Agent Properties 343 .pmi. introscope.objectPool Enables collection of PMI object pool data when set to true.jvmRuntime Enables collection of PMI JVM runtime data.agent. JVMPI must be turned on in WebSphere.pmi. Property settings True or False Default False Example introscope.enable.pmi.objectPool=false Notes ■ ■ The object pool data category must be turned on in WebSphere to be visible as Introscope data. You must restart the managed application before changes to this property take effect.pmi.jvmRuntime=false Notes ■ ■ For data to be provided to this module.WebSphere PMI introscope.enable. introscope. You must restart the managed application before changes to this property take effect. You must restart the managed application before changes to this property take effect.orbPerf=false Notes ■ ■ The orbPerf data category must be turned on in WebSphere to be visible as Introscope data.orbPerf Enables collection of PMI orbPerf data when set to true.enable. Property settings True or False Default False Example introscope.enable.pmi.agent.scheduler=false Notes ■ ■ The scheduler data category must be turned on in WebSphere to be visible as Introscope data.WebSphere PMI introscope.pmi.pmi.enable.agent.enable.agent. Property settings True or False Default False Example introscope. 344 Java Agent Guide .scheduler Enables collection of PMI scheduler data when set to true.pmi.agent. enable.enable. Appendix A: Java Agent Properties 345 .agent.system Enables collection of PMI system data when set to true. You must restart the managed application before changes to this property take effect.pmi.pmi.agent.WebSphere PMI introscope.agent. introscope.enable.enable.pmi.servletSessions=true Notes You must restart the managed application before changes to this property take effect.servletSessions Enables collection of PMI servletSessions data.agent. Property settings True or False Default True Example introscope. Property settings True or False Default False Example introscope.pmi.system=false Notes ■ ■ The system data category must be turned on in WebSphere to be visible as Introscope data. You must restart the managed application before changes to this property take effect.threadPool Enables collection of PMI thread pool data when set to true.pmi.agent.enable.enable.agent.enable.WebSphere PMI introscope.transaction Enables collection of PMI transaction data.enable. introscope.pmi.pmi.agent. 346 Java Agent Guide . Property settings True or False Default False Example introscope.transaction=false Notes You must restart the managed application before changes to this property take effect. Property settings True or False Default True Example introscope.pmi.threadPool=true Notes ■ ■ The thread pool data category must be turned on in WebSphere to be visible as Introscope data.agent. enable.agent.enable.webApp=false Notes You must restart the managed application before changes to this property take effect.enable. introscope.agent.WebSphere PMI introscope.pmi. Property settings True or False Default False Example introscope.agent. Property settings True or False Default False Example introscope.pmi.webServices Enables collection of PMI web services data when set to true. Appendix A: Java Agent Properties 347 .webApp Enables collection of PMI webApp data.pmi. You must restart the managed application before changes to this property take effect.enable.pmi.agent.webServices=false Notes ■ ■ The web services data category must be turned on in WebSphere to be visible as Introscope data. wlm Enables collection of PMI WLM data when set to true. introscope.enable.pmi.pmi.agent.WebSphere PMI introscope.enable.pmi.enable.wlm=false Notes ■ ■ The WLM data category must be turned on in WebSphere to be visible as Introscope data. You must restart the managed application before changes to this property take effect.wsgw=false Notes ■ ■ The WSGW data category must be turned on in WebSphere to be visible as Introscope data.agent.enable.agent. Property settings True or False Default False Example introscope. Property settings True or False Default False Example introscope.pmi.agent. 348 Java Agent Guide .wsgw Enables collection of PMI WSGW data when set to true. You must restart the managed application before changes to this property take effect. pmi.wldf.agent. Property settings True or False Default False Example introscope.objref Controls for hard-coded filters.objref=false Notes You must restart the managed application before changes to this property take effect WLDF metrics The following properties configure WLDF metrics: ■ introscope.agent.pmi. The objref filter filters out names ending with "@xxxxx" where "xxxxx" is a numeric string.enable (see page 350) Appendix A: Java Agent Properties 349 .agent.WLDF metrics introscope.filter.filter. enable=false Notes For WebLogic 9.enable Enables collection of WLDF metrics.agent.WLDF metrics introscope.agent.wldf.wldf. 350 Java Agent Guide .x and above only. Property settings True or False Default False Example introscope. You configure the PBD Generator by integrating it into an Apache Ant target using the WilyPBDGenerator. and instruments the methods in the classes that contain the Javadoc tag @instrument. Using the PBD Generator tool. This section contains the following topics: About the CA Wily PBD Generator (see page 351) Configuring the CA Wily PBD Generator (see page 352) Using the CA Wily PBD Generator (see page 352) About the CA Wily PBD Generator The Wily PBD Generator utility can create a PBD file from Javadoc tags with which you have annotated your Java code. to eliminate potential for errors that might be introduced by creating PBD files manually. you can: ■ ■ automate building of PBD files. The PBD Generator examines a set of Java source files.Appendix B: Using the CA Wily PBD Generator You can use the CA Wily PBD Generator tool to instrument custom Java class files for use by Java Agents.jar file. Appendix B: Using the CA Wily PBD Generator 351 . to facilitate the instrumentation of custom Java class files for use by the Java Agent. integrate PBD generation into your build systems to create and update PBD files automatically and incorporate any changes to the Java source. then running it as an Ant Javadoc task. jar"> <param name="-d" value="/src/engineering/products/introscope/source/generatedpbd"/> </doclet> </javadoc> Required PBD Generator parameters These key PBD Generator parameters are required: sourcepath the root directory of the Java source tree destdir the directory path of the PBD file that will be output from the tool packagenames a comma-separated list of the Java packages to be examined for instrumentation doclet path the path to find the PBD Generator jar file.introscope.wily. 352 Java Agent Guide .ui.console.javadoc.build. as a Javadoc task in an Ant target.util" verbose="false" private="true"> <doclet name="com.PBDInstrumentDoclet" path="/Wily/tools/WilyPBDGenerator.wily. which contains this tool param name="-d" this must contain the same value as destdir Using the CA Wily PBD Generator Before you can use the PBD Generator. you insert special Javadoc tags into the Java source files to be instrumented. This sample Javadoc task illustrates the use of this tool in Ant: <javadoc sourcepath="/src/engineering/products/introscope/source" destdir="/src/engineering/products/introscope/source/generatedpbd" maxmemory="512m" packagenames="com.Configuring the CA Wily PBD Generator Configuring the CA Wily PBD Generator This tool is intended to be incorporated into Ant-based build systems.thornhill.util. Using the CA Wily PBD Generator The syntax for the JavaDoc tag is: @instrument <valid metric prefix> <optional tracer name> where: <valid metric prefix> is any valid Introscope metric prefix—a string without a colon character (:). FrontendMarker or BackendMarker. <optional tracer name> can be BlamePointTracer. Pipe characters (|) are acceptable. The default is BlamePointTracer if the tracer name is missing. Appendix B: Using the CA Wily PBD Generator 353 . . Appendix C: Manual ProbeBuilding This section provides instructions for manually instrumenting your applications. This section contains the following topics: Before you begin (see page 355) Using the ProbeBuilder wizard (see page 356) Using the command-line ProbeBuilder (see page 358) Running instrumented code (see page 361) Switching back to non-instrumented code (see page 362) The ProbeBuilder Wizard. and should be used as a last resort. CA Technologies recommends you use these other methods before using manual ProbeBuilding. These methods are: ■ ■ Using JVM AutoProbe. Using AutoProbe for application servers. Appendix C: Manual ProbeBuilding 355 . You use manual ProbeBuilding when your environment does not support AutoProbe.lax file (see page 362) Before you begin When you run ProbeBuilder manually. See AutoProbe and ProbeBuilding Options (see page 61) for more information. Manual ProbeBuilding is a non-dynamic method of instrumenting your applications. Manual ProbeBuilding should not be used with other methods of instrumentation. Contact CA Support if you are not sure you should use manual ProbeBuilding. or you prefer not to use AutoProbe. See The Java Agent and Application Server AutoProbe (see page 365) for more information. it instruments classes on disk before the application server is run. Warning: Introscope supports other methods of instrumenting applications. Follow the instructions in Using the command-line ProbeBuilder (see page 358). Follow the instructions in Using the ProbeBuilder wizard (see page 356). Configured basic agent settings as described in Installing and Configuring the Java Agent (see page 27). See Installing the Java Agent (see page 29) for more information. These instructions assume that you have: ■ ■ Installed the Java Agent. Installed the Java Agent. 2. See AutoProbe and ProbeBuilding Options (see page 61) for more information.Using the ProbeBuilder wizard The instructions for manual ProbeBuilding assume you have performed the following installation and configuration tasks: 1. See Java Agent Naming (see page 147) for more information. Using the ProbeBuilder wizard If your machine has a windowing environment. Selected the ProbeBuilder Wizard option from the Enterprise Manager installation process. The Command-line ProbeBuilder—A command-line interface for environments without a windowing system. See Installing the Java Agent (see page 29) for more information. Manual ProbeBuilding options There are two ways to instrument your bytecode manually: ■ ■ The ProbeBuilder Wizard—a GUI dialog for running ProbeBuilder. See Connecting to the Enterprise Manager (see page 48) for more information. ■ 356 Java Agent Guide . Configured the Java Agent name. See the Introscope Configuration and Administration Guide for information on how to install the Enterprise Manager. use the instructions in this section to add probes to your bytecode. Configured Java Agent connection properties. 3. 4. Configured options for ProbeBuilder. Note: You have a choice of either using system directives files in which most tracer groups are turned on (FULL) or only a subset of tracer groups are turned on (TYPICAL). 9. see ProbeBuilder Directives (see page 56).jar files or individual . Introscope adds Probes to the specified bytecode.class files." Note: If you select a directory that already exists. If you have custom PBDs in the hotdeploy directory and are now using the ProbeBuilder Wizard. use the Default Java selection) and click Next. add them to the <EM_Home>/config/custompbd directory of the Enterprise Manager. 4. locate the set of system directives which correspond to your environment (if your application server isn’t listed. Click Overwrite to overwrite the existing files as necessary. 7. Click Next if you did not overwrite an existing directory. In the System Directives window. Click Select Java Bytecode to enter your desired directory and click Next. The default name is the original directory with the suffix "isc. This operation may take several minutes. click Next. click Exit or Add Additional Probes to add Probes to another directory. If you installed custom directives files in your config/hotdeploy directory. Enter or browse to your bytecode directory and click Next. 8. they appear in the Custom Directives window. then click Add Probes. 6. see Default tracer groups and toggles files (see page 114). Note: For information on creating custom directives. Important: This directory is not the same as the <Agent_Home>/wily/hotdeploy directory used by the Java Agent to deploy custom PBDs. 3. ProbeBuilder Wizard will display a dialog asking if you want to overwrite the directory.Using the ProbeBuilder wizard To use the ProbeBuilder Wizard: 1. For more information on full and typical system directives files and the what kind of information they provide. 5. Note: You can also select . On the Welcome screen. When the Finished window opens. Check the box next to any custom directives you want to use with this bytecode. or click Cancel to go back to the previous dialog to select another location. you must copy the PBDs you want to use from the hotdeploy directory to the Enterprise Manager config/custompbd directory. Appendix C: Manual ProbeBuilding 357 . or click Browse to select a location. Launch the ProbeBuilder Wizard from your <EM_Home> directory. 2. If you have custom PBDs. Enter the name and location for the new directory to contain the instrumented code. 2.jar MainClass 2. This affects users who: ■ ■ ■ ■ have a managed application running under JDK 1. update the application startup script to specify the location of the instrumented code and the Java Agent. to look like this: <your-applicationpath>. 358 Java Agent Guide . For example.isc/classes:/<your-applicationpath>.jar:/< EM_Home>/lib/Agent. the command-line ProbeBuilder was migrated to Java Development Kit (JDK) 1.4.jar.0. use a version of ProbeBuilder from Introscope 7. edit an existing classpath: <your_application_path>/classes:/<your_application_path>/lib/app. Using the command-line ProbeBuilder If your machine does not have a windowing environment. cannot run their applications with AutoProbe. To specify the location of the instrumented code: 1.Using the command-line ProbeBuilder Update the application startup script After adding probes to the bytecode. Make sure this reference precedes the reference to the original code in the classpath.3. In Introscope 8.4 or later on their servers. Save the changes. If one or more of the above conditions apply to your environment.1 or earlier. Edit the classpath of the application startup script to include locations of the directories containing the instrumented code created with the ProbeBuilder.0 or later. 4.isc/lib/app.jar MainClass 3. Edit the classpath in the application startup script to include the path to the <EM_Home>/lib/Agent. use the instructions in this section to add probes to your bytecode. cannot install JDK 1. have never instrumented their applications before OR need to upgrade the Java Agent to 8. Start your application with the new startup script. api. The ProbeBuilder classpath varies. Note: If you are processing a very large . you will only see PBD and PBL files specific to that application server. ProbeBuilder list files (. -directives|-pbd filename [.stream.pbl. so paths are relative to the that directory.pbl).stream. Example: Invoke ProbeBuilder from the agent directory The following command line illustrates how to invoke ProbeBuilder from the agent directory: java -cp ext/ProbeBuilder.pbd -origdir /usr/myApp/classes -destdir /usr/myApp/classes.pbd). Appendix C: Manual ProbeBuilding 359 .pbl file.Using the command-line ProbeBuilder Adding Probes to bytecode The command-line ProbeBuilder is activated by the following Java command.jar file. If you used the default Java Agent installer. At least one PBD or PBL file name is required.introscope. or directories to scan.pbd -origdir /usr/myApp/classes -destdir /usr/myApp/classes. The syntax for the Java command depends on your Java version and other settings in your environment.wily. you will see all possible default PBD and PBL files in the \wily directory. if you used an application-server specific Java Agent installer. depending on whether you installed it using an agent installer or the full Introscope installer..IntroscopeProbeBuilder -directives default.wily.jar com.] Type a comma-separated list of ProbeBuilder Directives files (. However. Select either a full or typical .. you may need to increase the memory in your JVM memory settings.pbl.jar com.introscope.isc –verbose Example: Invoke ProbeBuilder from the Enterprise Manager directory The following command line illustrates how to invoke ProbeBuilder from the Enterprise Manager directory: java -cp lib/ProbeBuilder. Consult your JVM documentation for instructions.api. This example uses the /wily directory. depending on how much information you want gathered (see Full or typical tracing options).IntroscopeProbeBuilder -directives default.isc –verbose These are the command line ProbeBuilder commands. rar and . or classes.war.jar. -skipitems Skips any files that are not Java bytecode files or archive files (. using directories. If -skipitems is not set.ear archives and the destination archive file name. -origclass filename -destclass filename Specifies the original class file name and the destination class file name. . -verbose Displays informational messages about each operation being performed by the ProbeBuilder program. . jar files. -origjar filename -destjar filename Specifies the original archive file name.zip files). -help -h -? Displays a help screen -prompt Turns on an interactive text UI when problems arise. the non-Java bytecode files are copied to the destination. -origdir directory -destdir directory Specifies the original directory name (including subdirectories) and the destination directory. including . 360 Java Agent Guide . jar and . unchanged. . The following command line settings are optional.zip.Using the command-line ProbeBuilder Select one set of the next three pairs to specify your original code location and your instrumented code destination. jar:/<ApplicationServer_Home>/wily/Agent.jar file. replace original class paths with instrumented code paths. Start your application with the new startup script. but does not report performance data. For example.j ar MainClass 3. Edit the classpath in the application startup script to include the path to the Agent.isc/lib/app. Non-instrumented code still loads and works normally. ■ Prepend paths to classpaths. you could place the instrumented code paths before the original-code paths (prepend) in the classpath. Edit the classpath of the application startup script to include locations of the directories containing the instrumented code created with the ProbeBuilder. Running instrumented code There are three ways to point to instrumented code instead of your original code: ■ In classpaths. The instructions in this section directed you to perform this process when you instrumented your application for the first time. If you do this. Save the changes. Make sure this reference precedes the reference to the original code in the classpath.Running instrumented code Editing the classpath After adding probes to the bytecode. To update the classpath: 1. 4. you might edit a classpath that looks like this: <your_application_path>/lib/app. Appendix C: Manual ProbeBuilding 361 . If only part of the application’s code was instrumented. to look like this: <your-applicationpath>. instrumented code loads and reports performance data. update the classpath of the application startup script to reflect the locations of the instrumented code and the Java Agent.jar MainClass 2. point the symbolic link to the original directory or remove the link and move the code into the original classpath. ■ ■ Move the original code to a new location. Switching back to non-instrumented code If you want to switch back to using non-instrumented code. If you added paths to the instrumented code in front of the paths to the original code. Then move the instrumented code to the original location. With this method. undo the steps of modifying classpaths to run instrumented code. Be careful using this method in a production environment. The ProbeBuilder Wizard. Default: blank 362 Java Agent Guide .lax file The ProbeBuilder Wizard. If you used symbolic links on a UNIX system. remove prepended paths to classpaths Remove the prepended portion of the classpath so that only the original classpath remains.vm VM to use the next time the ProbeBuilder is started.redirect Standard Error Output. console to send to a console window.current. Can be set to any installed JDK. you could also create a symbolic link from the current location of the instrumented code to the original location. Use this method when classpaths are set in many places. as described below: ■ ■ If you put the paths to your instrumented code into the Java classpaths.nl. or any path to a file to save to the file.0_11 (varies by operating system) lax. ■ If you put instrumented code in the original classpath. then remove the Instrumented code from the original path and place the original code in the original classpath.lax file is located here: <Introscope home>/Introscope ProbeBuilder Wizard. it is easy to forget whether you are using the original or the instrumented code.6. Default: JRE version 1. then replace paths to the instrumented code in Java classpaths with original paths.lax lax. Leave the classpaths unchanged. Leave blank for no output.Switching back to non-instrumented code ■ Place instrumented code in original classpath. On a UNIX machine. or to conduct an evaluation.stderr. redirect Standard Input.redirect Standard Output. console to read from the console window. console to send to a console window. or any path to a file to save to the file. Leave blank for no output. or any path to a file to read from that file. Leave blank for no input.The ProbeBuilder Wizard. Default: blank Appendix C: Manual ProbeBuilding 363 .stdout.stdin. Default: blank lax.lax file lax. . 0.4 or lower on the following application servers: ■ Sun ONE 7. ■ Oracle 10g 10.0. If you have already started using JVM AutoProbe.0.3 (see page 367) Configuring WebLogic Server (see page 368) Configuring HTTP servlet tracing (see page 368) Deploying the Java Agent on other application servers JVM AutoProbe (see Configuring JVM AutoProbe (see page 62)) is the most commonly used method for instrumenting applications.0. See Configuring Sun ONE 7.3 application server. Appendix D: The Java Agent and Application Server AutoProbe 365 .Appendix D: The Java Agent and Application Server AutoProbe This section provides instructions for deploying the Java Agent on other application servers.0 Application Server AutoProbe is only supported on Sun ONE version 7 application server.3 (see page 367). See Configuring Oracle 10g 10. see Deploying the Java Agent on WebSphere (see page 85) and Deploying the Java Agent on WebLogic (see page 77). CA Technologies highly recommends using JVM AutoProbe to instrument your applications. ■ WebSphere or WebLogic For information about configuring AutoProbe on WebSphere and WebLogic. This section contains the following topics: Deploying the Java Agent on other application servers (see page 365) Configuring Sun ONE 7.0 (see page 366) Configuring Oracle 10g 10.5 and above platforms OS/400 Warning: Use only one method to instrument your applications. you can use Application Server AutoProbe if you are running JVMs 1. do not use Application Server AutoProbe.0 (see page 366).3 Application Server AutoProbe is only supported on Oracle version 10g 10. Important: Application Server AutoProbe is not supported on: ■ ■ any JVM 1. However. .0 to use AutoProbe: Note: The use of ".wily.0 When starting the application server.wily. bytecode-preprocessors="com.introscope.jar:.api. or com.> .agentProfile.appserver.. Open the server.xml code (not relevant to the example) that is not shown.." .agentProfile=/sw/sun/sunone7/wily/Intr oscopeAgent..... 3.0.introscope. server-classpath="/sw/sun/sunone7/wily/Agent.introscope. In order to add Introscope information to startup scripts for Sun ONE 7.sun. For example: <java-config .jar to the "server-classpath" property of the java-config element in the server.wily. The following is an example of com. 1. For example: <java-config .profile </jvm-options> </java-config> 366 Java Agent Guide ... you must be logged in as Administrator or Root." in the .0 The following steps detail how to configure Sun ONE installations to use AutoProbe to instrument applications.introscope.introscope. avoid using the hyphen (-) character as an identifier for a classname. To configure Sun ONE 7..xml examples below indicates that there is additional information in the .api.wily.Configuring Sun ONE 7. and using it might lead to class loading errors in the agent logs.SunONEAutoProbe .sun. Define either com.xml file.. Add the following to the java-config element: ■ Add the bytecode-preprocessors property and set it to the value com. Configuring Sun ONE 7.appserver.SunONEAutoP robe"> ■ Add a jvm-options element to define the location of the agent profile..introscope.agentResource.agentProfile: <java-config .xml file. Add the full path of wily/Agent.wily. 2. Introscope does not parse this character... <jvm-options>-Dcom.wily. located at: <Sun ONE install dir>/domains/domain1/server1/config/ Note: The item separator is a colon (:).> 4. > .introscope.api. see Configuring HTTP servlet tracing (see page 368).classpreprocessor.oracle.3 The following steps detail how to configure Oracle 10g installations to use AutoProbe to instrument applications.preprocessing=true -Dcom. 3.jar path> 6.introscope. Run this command at the command line: -Dcom.3 to use AutoProbe: 1. 5.0. To configure Oracle 10g 10.42 must use the ^ (caret) character to escape a forward slash when issuing commands.jar to the application server classpath.OracleAutoProbe.agentResource. Appendix D: The Java Agent and Application Server AutoProbe 367 .wily.0.introscope. For example: -Xbootclasspath^/p:<IntroscopeAgent.. Add Agent. Set the system property oracle.probebuilder. For more information.class.jar com.wily.api. 4.0.j2ee.. <jvm-options>-Dcom.oracle.introscope.evermind. For more information. see Configuring HTTP servlet tracing (see page 368).probebuilder. add the resource file to the server classpath. Configure Tracer Groups to collect servlet data. Restart the Oracle Application Server 10g.server.preprocessing with the value of true.wily.wily.enable=true -classpath oc4j.introscope.introscope.3 The following is an example of com.oracle.oracle. Set the system property oracle.enable=true 5.wily.Configuring Oracle 10g 10.agentResource: <java-config .OracleAutoP robe -Doracle.xml Important: Users running Oracle 10g Release 2 using Sun JDK 1.class.agentResource=<virtual path to>/IntroscopeAgent.classes with the value of com..wily.j2ee.jar:<path to wily install dir>/wily/Agent.OC4JServer -config <path to oracle install dir>/config/server.wily.introscope.classpreprocessor. Configure Tracer Groups to collect servlet data. 2.. Configuring Oracle 10g 10.classes=com.profile</jvm-options> </java-config> ■ OPTIONAL: If you configured com. using this command: java -Doracle. Turn on the HTTPAppServerAutoProbeServletTracing Tracer Group by removing the pound sign from the beginning of the line. 9.1.jar file. and turn another Tracer Group on. You will turn one Tracer Group off.0. Edit the classpath in the application startup script (such as startMedRecServer.pbd file. 2.0.wily.preprocessor= com.pbd and toggles-typical. Repeat steps 2-4 for <your-app-server-home>/wily/toggles-typical. see Configuring HTTP servlet tracing (see page 368). To configure HTTP servlet tracing: 1.pbd file and open it.classloader.pbd files. 368 Java Agent Guide . For example: TurnOn: HTTPAppServerAutoProbeServletTracing 5. 9. 3. Navigate to the <your-application-server-home>/wily/toggles-full. Set the following property in the application startup script on the Java command line with the -D option to activate Introscope AutoProbe: -Dweblogic.0.3 to use AutoProbe: 1. Configuring HTTP servlet tracing Before you use AutoProbe with your application servers to instrument applications. For more information. 10. 2.PreProcessor 3.cmd) to include the wily/Agent. For example: #TurnOn: HTTPServletTracing 4.Configuring WebLogic Server Configuring WebLogic Server The following steps detail how to configure WebLogic Server 9.0.1. Configure Tracer Groups to collect servlet data.weblogic.api. 10. This will enable servlet data to be collected. To configure WebLogic Server 9. or 10.3 to use AutoProbe to instrument applications. Go to the HTTP Servlets Configuration section of the PBD. you must configure Tracer Groups in the toggles-full. Turn off the HTTPServletTracing Tracer Group by placing a pound sign at the beginning of the line. or 10.introscope. Index A agent architectural overview • 21 before installing • 27 configuration options • 53 configuration profile • 24 data collection configuration • 55 default name • 55 depolyment process • 23.profile deployment process • 25 introduction • 24 J javaagent property • 61 JBoss supported environments • 27 JVM AutoProbe configuring the agent location • 48 connector file • 64 creating a connector • 64 default metric collection • 61 instrumenting applications • 54 introduction • 29 JRockit • 67 OS/400 • 63 other options • 29 path to the agent. 25 directory structure • 43 domain configuration • 55 Enterprise Manager connection • 28 evaluating performance • 25 installation options • 29 interactive installer • 30 logging messages • 54 manual installation • 40 naming propertiies • 55 planning data collection • 24 removing from z/OS • 59 silent installation • 36 specifying the path to • 48 starting • 48 uninstalling • 59 upgrading • 57 validated configuration • 25 application management instrumenting bytecode • 54 introduction • 23 virtual agents • 55 application server permission requirements • 27 supported environments • 27 upgrading multiple agents • 57 connecting to • 28 HTTP tunneling • 49 HTTPS connections • 51 proxy server • 50 using SSL • 52 I installation archive files • 41 console mode • 34 directory structure • 43 GUI mode • 31 interactive installer • 30 manual • 40 operating system specific program • 30 silent • 36 types of • 29 instrumentation defined • 54 full and typical tracing • 68 Introscope application lifecycle • 24 architectural overview • 21 discover functionality • 23 IntroscopeAgent.jar and profile • 62 running connectors • 64 supported JVMs • 29 C CA Wily CEM integration • 57 E Enterprise Manager agent profile settings • 54 architectural overview • 21 configuring the connection • 48 Index 369 . evaluating overhead • 25 S SAP NetWeaver AutoProbe connector • 64 supported environments • 27 socket metrics default data collection • 56 SSL metrics default data collection • 56 stall reporting default behavior • 56 Sun ONE AutoProbe connector • 64 supported environments • 27 SuperDomain • 55 superset agent packages • 57 SYSVIEW support • 44 T Tomcat supported environments • 27 tracer groups default configuration options • 68 370 Java Agent Guide .WAS 7 on z/OS • 63 U URL groups introduction • 56 M manual ProbeBuilding • 61 O Oracle AutoProbe connector • 64 supported environments • 27 W WebLogic AutoProbe connector • 64 supported environments • 27 WebSphere running JVM AutoProbe on z/OS • 63 supported environments • 27 wily directory • 43 wily/connectors • 44 wily/deploy • 44 wily/examples directory • 44 wily/ext directory • 44 wily/hotdeploy directory introduction • 46 wily/install directory • 47 wily/readme directory • 47 wily/tools directory • 47 wily/UninstallerData directory • 47 Workstation architectural overview • 21 P ProbeBuilder Directive (PBD) files configuring data collection • 55 introduction • 21 typical configuration • 56 ProbeBuilding customizing • 67 dynamic • 68 methods available • 61 support for older agents • 62 production environment production environment.