Profiling applications on a remote machine
So far, this tutorial has discussed profiling Java applications as they are running on a local machine. Rational Application Developer profiling also provides the capacity to launch and profile applications that are running on a machine separate from the workbench. To enable this functionality, you can download the Rational Agent Controller component and install it separately on Windows, Linux x86/x64, Linux for System Z, IBM AIX, IBM z/OS, Solaris SPARC, and Solaris x86.
Instructions to install and start the Rational Agent Controller are available on the IBM download site; consult the Resources section for more details. When it is installed, run the SetConfig setup script, and then start the agent controller using ACServer.exe (Windows) or ACStart.sh (UNIX®) on the remote machine. An example Linux on System Z configuration is shown in Figure 14.
Figure 14. Starting the Rational Agent Controller process from the command line and setting up the Java Profiler environment variables
The profiler requires you to set additional environment variables. On Linux, for instance, agent-specific additions to the
PATH variables are required. Other variables shown in Figure 14 previously are set just for the convenience of using their values more than once without having to type the long path. You can add these to your global environment variables, specify them in the terminal session, or add these to the launch script of your Java application. Additionally, some platforms allow you to profile without setting these environment variables (instead specifying the path on the command line). Consult the Getting Started document of your Rational Agent Controller installation for more information.
In addition to setting these environment variables, you'll also need to determine the type of profiling data that is required, and set the JVM arguments to reflect this type when launching your application.
JVM Arguments on Windows:
All UNIX varieties:
JVM Arguments on Linux:
(Note the single quotes around the entire string; these are required so that the semi-colon is not interpreted as a new line character by the shell)
Note the use of
<profile-option> in the generic command line) in the command line JVM arguments in the example above: this is one of the options that corresponds to the data collection profiling types:
CGProf: This is equivalent to Execution Time Analysis in the workbench Profiling UI. As mentioned previously, this option is used to identify performance bottlenecks, by breaking down execution time on a method-by-method basis.
HeapProf: This is equivalent to Memory Analysis in the workbench Profiling UI. As mentioned, this option tracks the contents of the heap by tracing object allocation and deallocation, as well as garbage collection events.
ThreadProf: This is equivalent to Thread Analysis in the workbench Profiling UI. This option traces thread and monitor usage during application execution.
You need to select one of the data collection types, and place that value in the profile-option JVM argument value above. You may only specify one at a time.
In addition, you need to select agent behavior (for instance, the example in Figure 14 uses
controlled: This agent behavior prevents the JVM from initializing until the agent is attached to (from the workbench) and given instructions to start monitoring. As soon as the agent connection is established, the JVM will start. Because the JVM waits until the workbench has connected, the profiling agent will generate data for the entire lifecycle of the application.
enabled: With this agent behavior, the profiling agent is launched at JVM startup. However, the JVM is initialized immediately, and begins running without waiting for the workbench to connect. The profiling agent does not begin to generate data until after the workbench has connected to the agent and started monitoring. No profiling data is produced until the workbench attaches. Any application execution that takes place before the workbench has connected will not be recorded.
An additional agent behavior is
standalone, which is outside the purview of this tutorial. It allows profiling without an agent controller by writing data to a trace file on the local file system, which can then be directly imported into Rational Application Developer. Similarly, additional command line options are available to fine tune profiler data. For more information, consult the Rational Agent Controller Getting Started document.
(Heap profiling on Windows, mentioned enabled mode)
(Execution time profiling, on Linux mentioned controlled mode)
When the target application JVM has been run with appropriate JVM arguments, you are ready to connect from the workbench. To connect from the workbench, bring up the Profile Configurations dialog, as shown in Figure 15.
Figure 15. Selecting the Profiling Configurations dialog from the workbench UI
A dialog box that shows the available profiling options is displayed, as shown in Figure 16.
Figure 16. Profile launch configuration options
Create a new Attach to Agent launch configuration (described previously) by double-clicking that option. You can also customize the new configuration by adding the remote machine as a new host. The agent controller on the remote machine is available at port 10002 (the default port number), as shown in Figure 17.
Figure 17. Add host dialog
After it is added as a host, the agent running on the remote machine (in this example the execution statistics agent) should be available on the Agents tab. If not, it could help to verify the Agent Controller setup and status. When you are ready, select the agent and click Profile. The workbench will attach to the agent and switch to the profiling dialog. You can now collect and analyze the data as required.
One other way of profiling an application on a remote machine is to use the previously described External Java Application option (as shown in Figure 18) instead of Attach to Agent.
Figure 18. Specifying class name and class path under External Java Application
In a new configuration of External Java Application, you specify the location and name of the Java main class on the remote machine, as shown in Figure 18. The Monitor tab helps specify the kind of profiling agent to use (Execution profiler, Memory profiler, or Thread profiler). When you click the Profile button, the application executes on the remote host, but the input and output are directed to the console window in the local workbench.