How do I connect to a Java command-line tool with the YourKit Java Profiler?

Question

I've build a command-line tool in Java, which I would now like to profile with YourKit. I launch the command-line tool with something like:

$ java -classpath .:foo.bar.jar com.foobar.tools.TheTool arg1 arg2 arg3

It runs to completion in less than 2 seconds.

After reading http://www.yourkit.com/docs/80/help/agent.jsp, I tried the following:

$ java -agentpath:/home/dspitzer/yjp-8.0.24/bin/linux-x86-32/libyjpagent.so -classpath .:foo.bar.jar com.foobar.tools.TheTool arg1 arg2 arg3

...and I get:

[YourKit Java Profiler 8.0.24] JVMTI version 3001016d; 14.3-b01; Sun Microsystems Inc.; mixed mode, sharing; Linux; 32-bit JVM
[YourKit Java Profiler 8.0.24] Profiler agent is listening on port 10001...
[YourKit Java Profiler 8.0.24] *** HINT ***: To get profiling results, connect to the application from the profiler UI
...

(And then the tool runs to completion and exits.)

I guess (by default, at least) YourKit is designed to only connect to running application.

How should I modify my command-line tool to allow connection from YourKit?

1. I could add a command-line option that will have it pause for input, and I won't press return for it to continue until I've connected to it from YourKit.
2. Is there a YourKit API that I could add to my tool that would cause it to block until I've connected with YourKit?
3. Is there a YourKit API or a java command-line option that would create a profiling "snapshot" that I could load and analyze later (after the command-line tool has completed) with YourKit?

Answer 1

I'm not aware of a YourKit option to do this (which isn't to say that there isn't one), but there is a Java remote-debugging option to do this.

Try adding the following to your command line, in addition to the YourKit agent options:

-Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=y

This should cause the VM to suspend as soon as it starts up, waiting for a debugger to connect on port 8000. YourKit itself isn't a debugger, but an IDE like Eclipse or Netbean will do the job, as will the basic jdb command line.

So run the command, with both options set, connect YourKit, then use a debugger to connect to the debug port, which will trigger the VM to continue execution, allowing YourKit to get the data you need.

It would be better to do this all using YourKit, but I know of no such way.

Answer 2

The answer to #3 is yes, there's an API you can use to have your application produce profiling results that YourKit can then examine.

Take a look at the API docs, and also the Command line tool to control profiling

Here's an example of using the API (I haven't tried this code):

Controller ykController = new Controller();
ykController.enableStackTelemetry();
ykController.enableExceptionTelemetry();
ykController.startCPUProfiling(ProfilingModes.CPU_TRACING,Controller.DEFAULT_FILTERS);
ykController.startAllocationRecording(false,0,false,0);
YourMainClass.main(args);
String snapshotLocation = ykController.captureMemorySnapshot();

Answer 3

You could launch it via Eclipse, which has a YourKit plugin that launches on app launch.

Answer 4

YourKit's onexit=snapshot option saves a snapshot file under $HOME/Snapshots on JVM exit. You can load this snapshot into the YourKit GUI for later analysis. See this page on their website for more details.

Answer 5

There is no way to pause profiled application until profiler "connects"; you simply do not need to do so.

Instead, please do the following:

• Turn on desired profiling modes from startup. For example, if you need to profile CPU usage, start either CPU sampling or CPU tracing with corresponding startup options "sampling" or "tracing". See http://www.yourkit.com/docs/80/help/additional_agent_options.jsp

• If profiled application is short-running, enable snapshot capture on exit with "onexit=snapshot" startup option. Later open captured snapshot in the profiler UI for analysis.