Thursday, January 12, 2012

InTrace


This page shows how to use InTrace to view remote JVM activity live on your Windows (or other linux/mac) desktop.


Installation

On the machine of the JVM you want to trace:
  1. Download this jar file to the machine with the JVM you want to trace. NOTE:  To work on IBM JVM's this jar needs a tiny MANIFEST.MF patch, detailed here
  2. Add this parameter to your JVM start-up parms, using the absolute path to the intrace-agent.jar file:  -javaagent:/home/myuser/intrace-agent.jar
  3. Restart the JVM.
On your Windows desktop:
    1. Download this InTrace jar file to your windows desktop.  
    2. Launch the UI with this jar file with "java -jar intrace-ui.jar"
    3. In the InTrace UI, click the "Connection" button to specify the host name/ip of the JVM to be traced.   Note that there is a default port (9123) that is used to connect.
    4. In the InTrace UI, click the "Classes" button to indicate which classes you want to trace/instrument.
Overview
InTrace is an open-source trace utility that lets you view live JVM activity in a window on your Windows desktop.  The activity of a JVM on remote machine (local too) is shipped via TCP back to your desktop live, as it happens.


What kind of JVM activity is traced?
  • Start/stop time of any/all method entry/exit
  • Values of all parameters passed into any method
  • Values returned from any method

Instrumentation
To trace something, you first have to "instrument" it -- that just means you have to tell InTrace which classes you want to watch.  To avoid unnecessary overhead, InTrace only traces the class names that you specify.  There are two ways to instrument a class, so you can capture trace events from that class:
  • Start the InTrace UI and click on the "Classes" button.  See the "Installation" section, above, for how to start the UI.
  • Use Manual Instrumentation, below.
Optional Manual Instrumentation
Optionally, at JVM startup, you can specify the class names you want to instrument.  This is real helpful if you want to instrument the same set of classes every single time you start the JVM.


Say that you want to trace these three classes:
  • example.TraceExample
  • com.fis.Foobar
  • com.fis.HelloWorld
Use these java parameters on the JVM running the code you want to trace:
-javaagent:${lib.dir}/intrace-agent.jar=[regex-example.TraceExample|com.fis.Foobar|com.fis.HelloWorld[instru-true