Profiling WebSphere Server
This tutorial provides instructions on how to profile WebSphere server using AppPerfect Java Profiler product. This tutorial assumes you have successfully downloaded and installed AppPerfect Profiler on your machine with the default options.
This document is divided into following sections
- Creating Project
- AppPerfect Java Profiler
- Changes done to WebSphere startup and config files to enable profiling
- Troubleshooting
Within each section, multiple exercises are listed. All exercises assume you have installed the product in C:\AppPerfect\Profiler folder and will be referred as Profiler_HOME henceforth in tutorial. If you have installed the product in some other folder, modify the instructions below appropriately.
Creating Project
Exercise 1: Launch AppPerfect Java Profiler
- Click on Start -> Programs ->AppPerfect Profiler x.x.x -> AppPerfect Java Profiler
- On launching AppPerfect Java Profiler a Welcome page will be displayed. Go through the brief description
given for product.
NB: Welcome page is displayed only when Profiler x.x.x is launched and last time no project was opened.
Exercise 2: Creating a Project
- Launch the Project Wizard by clicking File ->New... menu option. The New Project wizard will be launched.
- Go through the instruction provided on top of the General tab.
- Keep the default project name and location for the purpose of this exercise. We don't have to provide "Notification" settings or "Target Application's Machine" settings for this exercise. Click on the Next button.
- We dont have to import any existing project so click Next on Import Tab.
- Source: Leave it empty and click next.
- Java Settings: Use the default JDK which is bundled with AppPerfect Java Profiler and click on the Next button.
- Environment: Leave it empty and click next.
- Target: Select project type as Server/Web Application. Then provide
'Starting URL' and other settings. Click 'Go to AppServer Settings'. Here specify the following settings and then click on OK button:
- Select AppServer : Select Websphere_5.x/6.x from the combo.
- Server Home : Provide the WebSphere server home directory here
- Startup file : Specify the startup file path of websphere server. Generally its path for startServer.bat. AppPerfect will try to automatically update this file to suit profiling requirements and will create a new file with _Apperfect appended to file name. This file will be used to launch server in profiling mode.
- Config file : Specify 'server.xml' file path, located at SERVER_HOME/AppServer/config/cells/HOST/node/HOST/servers/SERVER_NAME. This file is modified to suit profiling requirements and a backup file (_AppPerfect.bak) is created to maintain original settings. The original file will be replaced back on stop of profiling.
- Instance name : Provide the instance name of the server which you want to start, There is a button to find all server instances. You can also manually type the required server instance to launch. AppPerfect in that case will start the specified instance.
- Select the "Launch server automatically (When required)" checkbox. This should be selected in case you want AppPerfect to automatically launch the server. If unchecked, you will have to start server manually using the modified startup file, Click on the Finish button.
- If applications asks for Starting URL validation, click on 'No' button. Normally Confirmation for Starting URL validation is not asked when "Launch server automatically (When required)" is checked. A confirmation message saying that the project is saved will be displayed. Click on the OK button.
Changes done to WebSphere startup and config files to enable profiling
Following changes are done to startServer.bat and file is saved as startServer_AppPerfect.bat. This modified file should be used to start server with profiling,
-
rem ###### Changes for AppPerfect start here ######
- $SERVER_NAME should be WebSphere
- $PROPERTIES_FILE_PATH should be "PROJECT_PATH\profiler.properties"
- $USING_JDK15 to specify whether server runs with JDK 15, possible values y and n
- $IS_64BIT to specify whether JDK is 64 or 32 bit, possible values y and n
call "Profiler_HOME/approfilertools/eclipse/plugins/com.appperfect.teststudio_x.x\lib\env.bat" $SERVER_NAME $PROPERTIES_FILE_PATH $USING_JDK15 $IS_64BIT where,
Following changes are done to server.xml and original file is saved as server_AppPerfect.bak. At end of profling the original changes are restored from the backup file, Changes are done in the genericJvmArguments attribute of jvmEntries tag.
- For JDK 14 and lesser add
genericJvmArguments="-Xbootclasspath/a:Profiler_HOME/approfilertools/eclipse/plugins/com.appperfect.teststudio_x.x/lib/profiler.jar -Djp.library.path=Profiler_HOME/approfilertools/eclipse/plugins/com.appperfect.teststudio_x.x.x/lib -Xrunaptspi32:propertiesfile=PROJECT_PATH\profiler.properties" - For jdk 15 and higher add
genericJvmArguments="-Xbootclasspath/a:Profiler_HOME/approfilertools/eclipse/plugins/com.appperfect.teststudio_x.x/lib/profiler.jar -Djp.library.path=Profiler_HOME/approfilertools/eclipse/plugins/com.appperfect.teststudio_x.x.x/lib -agentlib:aptsti32="propertiesfile=PROJECT_PATH\profiler.properties""
Where the entries marked in bold should be replaced by actual path on your machine as per the version and installation path.
AppPerfect Java Profiler
The steps henceforth will be same in case of Server and Local profiling, hence please refer to the "Profiling Server Application" tutorial for further details.
Troubleshooting
Server not starting on start profiling and profiler getting timed out.
This is the most common problem faced with profiling. Following points are the common cause of this type of error.
- Confirm that server is not already running before start of profiling.
- Confirm that you have selected the "Launch server automatically (When required)" at Project -> preferences.. -> Target tab -> AppServer Settings
- Verify that startup file path, server home and server.xml file provided at Target tab are correct. Also AppPerfect was able to modify the startup file and server.xml properly.
- Most commonly this problem is faced if debugger is also enabled for server. Please note that debugger and profiler cannot run together, so if debugger is enabled turn it off. There should not be any other "-Xrun" option in the startup file, other than the one used for profiler.
- By default profiler agent runs on port 8677, unless configured to some other value (Tools -> Options -> Java Profiler -> Agent port). Make sure that this port is free and is not getting blocked.
- Confirm that you have provided the server.xml of the server instance you need to profile and not of any other server instance. You need to provide same instance name for which you provided the server.xml file
AppPerfect not able to modify the startup file.
This happens when the startup file specified is not in the format expected by AppPerfect.
- Go to Project -> Preferences -> Target tab -> AppServer Settings. Uncheck the "Launch server Automatically" option.
- Open the modified server startup file, you will find all the modification added at top of the startup file, Move them to the appropriate place in the startup file, The changes should be placed just before the command responsible for launch of the server.
- Start profiling and now manually launch the modified startup file.
AppPerfect not able to modify the server.xml file.
This happens when the server.xml file specified is not in the format expected by AppPerfect. Things like jvmEntries tag is missing.
- Go to Project -> Preferences -> Target tab -> AppServer Settings. Uncheck the "Launch server Automatically" option.
- Open the server.xml and do the changes as suggested in Changes done to WebSphere startup and config files to enable profiling
- Start profiling and now manually launch the modified startup file.
Server started, but not able to see any data in the profiling views.
- Stop profiling. Check the Task Manager and make sure that none of the server related processes are already running. If they are, terminate all such processes, Restart profiling and see if you are able to see data fine now.
- Check if debugger is also enabled for server. Please note that debugger and profiler cannot run together, so if debugger is enabled turn it off. There should not be any other "-Xrun" option in the startup file, other then the one used for profiler.
- Go to Project -> Properties... -> Profiling Options tab and check if the concerned profiling options are turned on.
- Try doing selective profiling, like turn off thread profiling and see if you are able to view data in other views fine.
Unable to see any data in CPU profiling views.
- Go to Project -> Properties... -> Profiling Options tab and check if CPU profiling and Record Call Tree option is turned ON.
- Check out exclude Filters list and confirm that its not excluding all the concerned classes and packages
Profiling stops automatically after some time.
- Most common cause for this problem is server process going out of memory. Check out if enough heap memory was allocated for server (-Xmx). If not, try increasing -Xmx value and see if that helps.
- Try doing selective profiling, like turn off thread profiling and keep others ON and see if that helps.
- Try doing remote profiling and see if things works fine remotely.
Profiling stops automatically while taking Heap snapshot.
- Most common cause for this problem is server process going out of memory. Check out if enough heap memory was allocated for server (-Xmx). If not, try increasing -Xmx value and see if that helps.
- In case memory requirements are not met, try to take selective heap dump, that is only for the required classes. Also try not to collect primitive data information as that adds lots of memory overhead
- Also in case application runs fine with JDK 15 then try using JDK15 for profiling. This way AppPerfect will profile using JVMTI agent which provides more optimized way for snapshot then JVMPI (used with JDK 14 and lesser).
Profiler is too slow, target application responds very slowly
You can try following to help improve the performance
- Try doing selective profiling. That is if you are interested only in memory related information then keep Thread, CPU etc profiling off. You can configure that at Project -> Properties -> Profiling Options.
- In case you are interested in CPU profiling data, then try setting as many filters as you can at Project -> Properties -> Profiling Options -> CPU Profiling -> Customize filters..
- You can run On demand profiling instead of Development mode profiling. In On demand profiling mode, you can connect/disconnect to target at any time and as many times you want. Advantage of this mode is, better performance and you will get profiling details for the time you are connected to the application. You can always take heap snapshot to get complete details of heap
- Try remote profiling. This way profiler and target will not share same resources and both will get enough resources required for better performance.
- Try allocating maximum possible heap memory for server (-Xmx).
- Also in case application runs fine with JDK 15 then try using JDK15 for profiling. This way AppPerfect will profile using JVMTI agent which provides more optimized way for profiling then JVMPI (used with JDK 14 and lesser).
- Keep screen refresh rate to as higher value as you can at Tools -> Options -> AppPerfect -> Screen Refresh Interval
- Keep method call stack depth and Allocations trace depth to least possible value, at Tools -> Options -> Java Profiler
Modifications required in the server startup environment for enabling profiling, and starting server manually
In case automatic startup file modification does not work for you, due to incompatible format, or due to use of customized startup file, following modifications are needed in general to enable profiling for the customized server setup :
- Setting JAVA_HOME to JDK used for running the server.
- Inserting the following JVM arguments in the java command used to launched the server:
- For JDK 14 and lesser add
-Xbootclasspath/a:Profiler_HOME/approfilertools/eclipse/plugins/com.appperfect.teststudio_x.x/lib/profiler.jar -Djp.library.path=Profiler_HOME/approfilertools/eclipse/plugins/com.appperfect.teststudio_x.x.x/lib -Xrunaptspi32:propertiesfile=PROJECT_PATH\profiler.properties - For JDK 15 and higher add
-Xbootclasspath/a:Profiler_HOME/approfilertools/eclipse/plugins/com.appperfect.teststudio_x.x/lib/profiler.jar -Djp.library.path=Profiler_HOME/approfilertools/eclipse/plugins/com.appperfect.teststudio_x.x.x/lib -agentlib:aptsti32="propertiesfile=PROJECT_PATH\profiler.properties" - Adding '%Profiler_HOME%/approfilertools/eclipse/plugins/com.appperfect.teststudio_x.x.x/lib' library path to PATH environment variable in case of Windows. For Linux, MacOS X it should be added to LD_LIBRARY_PATH.
- To start the server with profiling enabled, save the updated startup file and run it from a command prompt. Go to Project -> Preferences -> Target tab -> AppServer Settings. Uncheck the "Launch server Automatically" option and start profiling from Java Profiler.
Getting error message : -Xrun Unable to load agent library aptsti32/aptspi32
This happens if agent library is not present on the library path. Adding %Profiler_HOME%/approfilertools/eclipse/plugins/com.appperfect.teststudio_x.x.x/lib to the PATH environment variable in case of Windows should solve the problem. For Linux, MacOS X it should be added to LD_LIBRARY_PATH.