TEC594615: How to Instrument WebSphere 6.1 with IBM JDK 1.5 and why this should not be done

Document created by Mary_Clark Employee on May 26, 2016Last modified by J.J. Lovett on May 26, 2016
Version 2Show Document
  • View in full screen mode

Document ID:  TEC594615

Last Modified Date:  7/2/2013
Authored By: Mary_Clark

  • Products
    • CA Application Performance Management
  • Components
    • APM AGENTS

 

Solution:How to Instrument WebSphere 6.1 with IBM JDK 1.5 and why you should not be done.Dynamic Instrumentation is not recommended when using IBM JDK version 1.5

The CA Introscope dynamic instrumentation feature requires class redefinition support. Use of class redefinition can significantly impact performance when running on IBM JDK version 5. IBM has provided technical information about this performance overhead in the Java Diagnostics Guide.

 

CA Introscope and IBM JDK version 5 customers that would like to take advantage of dynamic instrumentation should keep this performance overhead in mind. When employing this configuration, CA Technologies recommends using the dynamic instrumentation feature only in a QA environment.

Functionality will be lost when using IBM JVM 1.5

When you are running WebSphere 6.1 using IBM JVM 1.5, you must use the alternate versions of the Java agent .jar file and Java agent profile. These files are:

 

AgentNoRedef.jarIntroscopeAgent.NoRedef.profileFor the WebSphere Agent distribution, they are located at:<Agent_Home>/core/configFor the generic CA APM AllAppServer agent distribution, the alternate profile is named:IntroscopeAgent.websphere.NoRedef.profileAs a result of using these modified files to accommodate IBM JDK 1.5, these metrics will not be reported:
  • System classes
  • NIO (Sockets and Datagrams)
  • SSL
and these features will be disabled:
  • Socket instrumentation reverts to pre-Introscope 9.0 ManagedSocket style.
  • Remote dynamic instrumentation is disabled
  • Changes to PBD files require that you restart the instrumented JVM before being applied
  • Deep inheritance and hierarchy support instrumentation is disabled.

How to enable instrumentation with IBM JVM 1.5 for WebSphere 6.1 anyway

If, despite the warnings, you still wish to enable instrumentation with IBM JVM 1.5, here's how to configure this:To configure IBM WebSphere 6.1 to use the CA APM Java agent, you must edit the WebSphere startup script.By default, the WebSphere startup script is the server.xml file in$WEBSPHERE_HOME/profiles/<App Server Name>/config/cells/<Cell Name>/nodes/<Node name>/servers/server1You can manually edit this file, or use the WebSphere administrator console instead for editing..

To modify the WebSphere Application Server 6.1 - UNIX, Windows, OS/400, z/OS - IBM JVM 1.5 to use the agent with the WebSphere Administrator Console

  1. Open the WebSphere Administrator Console.
  2. Navigate to Application Servers > your server > Server Infrastructure > Java and Process Management > Process Definition > Java Virtual Machine.
  3. Set the Generic JVM Argument field as follows:
    -javaagent:<Agent_Home>/AgentNoRedef.jar -Dcom.wily.introscope.agentProfile=<Agent_Home>/core/config/IntroscopeAgent.NoRedef.profile
  4. Restart the WebSphere application server.

    If having both instrumented and non-instrumented applications on the same computer, include the -Xshareclasses:nonesetting in the Generic JVM Argument to avoid errors on AIX.

    Note: A unique directory is required when there is more than one version of WebSphere using the same agent directory.
    If using a non-IBM JVM or an IBM JVM that is a version other than 1.5, not all metrics and messages are output.

To modify the WebSphere Application Server 6.1 - UNIX, Windows - Sun, HP, all other non-IBM JVM 1.5 to use the agent, use the standard Agent.jar and standard IntroscopeAgent.profile.

  1. Open the WebSphere Administrator Console.
  2. Navigate to Application Servers > your server > Server Infrastructure > Java and Process Management > Process Definition > Java Virtual Machine.
  3. Set the Generic JVM Argument field as follows:
    -javaagent:<Agent_Home>/Agent.jar -Dcom.wily.introscope.agentProfile=<Agent_Home>/core/config/IntroscopeAgent.profile
  4. Restart the WebSphere application server.

Fixing Java2 Security

For instrumentation to work correctly in WebSphere environments with Java2 Security enabled, it may be necessary to add permissions to your Java2 Security Policy.To add permissions to your Java2 Security Policy
  1. Open the file $WebSphere home/properties/server.policy file in a text editor.

  2. Add the following permissions to the file:
    // 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 readability and are not needed when adding the permissions to the server.policy file.

  3. Save and close the file.

How to tell if class redefinition was enabled successfully

When class redefinition is enabled, the following log message is written in the APM Agent log at the WARN level:Introscope Agent Class Redefinition is enabled. Enabling class redefinition on IBM 1.5 JVMs is known to incur significant overhead.When class redefinition is disabled, the log message is written at INFO level and reads:Introscope Agent Class Redefinition is disabled.

Dynamic ProbeBuilding

Dynamic ProbeBuilding lets you implement new and changed PBDs without restarting managed applications or the agent itself.Dynamic ProbeBuilding requires Java 1.5 or higher.
Dynamic ProbeBuilding requires use of the JVM -javaagent switch. It does not work with the -Xbootclasspath switch.
Dynamic ProbeBuilding is not enabled by default.

What does Dynamic ProbeBuilding do?

When dynamic ProbeBuilding is enabled, Introscope periodically checks for new and changed PBDs. To minimize overhead, Introscope selectively re-instruments classes affected by the modified PBDs. To improve performance, the scope of dynamic agent re-instrumentation is limited to reloading only those classes whose instrumentation has changed.

Where to put new or changed PBD files

AutoProbe looks for PBD files in the directory that contains theIntroscopeAgent.profile file (by default, this is the <Agent_Home> /wily/core/config directory), and the <Agent_Home>/wily/core/config/hotdeploy directory. AutoProbe resolves file names relative to these directories. If you have moved the location of your wily directory, be sure to map the file path to the correct directory.When a PBD is edited or added to the hotdeploy directory, only user directives (such as adding or removing directives for a class, or toggling tracer groups) are re-instrumented.In addition, there is the option to 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.

What is NOT re-instrumented with Dynamic ProbeBuilding?

  • System directives (such as adding a tracer or changing a new tracer mapping).
  • Arrays, interfaces, and classes specified in Skip directives
  • Transformations
  • Modifications to the j2ee.pbd file
  • Changes to directives not using tracer groups are not supported. For example, changes in any directive like TraceAllMethods that does not have an IfFlagged switch.

How to Enable Dynamic ProbeBuilding

  1. Open the IntroscopeAgent.profile in a text editor.

  2. Uncomment and set the following properties:
    introscope.autoprobe.enable=true
    introscope.autoprobe.dynamicinstrument.enabled=true
    introscope.autoprobe.dynamicinstrument.pollIntervalMinutes=1
    introscope.autoprobe.dynamicinstrument.classFileSizeLimitInMegs=1
    introscope.autoprobe.dynamic.limitRedefinedClassesPerBatchTo=10

  3. Save and close IntroscopeAgent.profile.

  4. Restart the managed application (the JVM) for these changes to take effect.

What's the difference between Dynamic ProbeBuilding and Dynamic Instrumentation?

Dynamic ProbeBuilding , as explained above, requires making manual changes to PBD files, or adding new PBD files to the hotdeploy agent directory, and requires making manual changes to the IntroscopeAgent.profile.

Dynamic instrumentation is performed from the Introscope Workstation transaction trace viewer. The changes to instrumentation you select using the interface are made automatically for you, and are often only temporary. Instrumenting a method dynamically means inserting the instrumentation during runtime. You can dynamically instrument one, more, or all of the methods during a transaction trace session, and subsequently view metrics returned by the newly instrumented methods. This allows you to do dynamic application performing tuning.

Dynamic instrumentation does not require any changes to the IntroscopeAgent.profile, and if deciding to make instrumentation changes permanent, a new PBD is created and saved in the correct location for you.

Dynamic Instrumentation needs to be able to create and add files to the [AGENT_HOME]/Dynamic directory and needs to be able to write to the log files in [AGENT_HOME]/logs directory.

To use Dynamic Instrumentation, log into the APM Workstation as a user with write permissions to these locations on the computer where the Agent is installed.

There is a significant performance impact when using Dynamic Instrumentation with IBM JDK 1.5.

There is no performance impact when using Dynamic Instrumentation with IBM JDK 1.6 or above.

For additional information about Dynamic ProbeBuilding, Dynamic Instrumentation, and implementing the Java Agent with WebSphere, refer to the CA APM Java Agent Implementation Guide and the CA APM Workstation User's Guide.

 

Search the Entire CA APM Knowledge Base

 

search-kb.jpg

Attachments

    Outcomes