Home

Welcome to the headlessInTraceClient wiki!

This API can be used to write diagnostic tools, like wuqiSpank. It traces events from Java method invocations in a separate JVM.

• You tell the API the exact class names that you want to capture events for.
• The JVM being traced can even run on a different machine.
• headlessInTrace also captures the values of method parameters and return values.

Architecture

The app you want to trace needs to load intrace-agent.jar using the -javaagent parameter, as detailed below. This jar file is a wrapper layer around the java instrumentation API, so you don't need to be familiar with it. headlessInTrace connects to intrace-agent.jar over a socket, and receives event notifications using a simple proprietary protocol. This is a pure-java solution that will run on any platform.

Example

Server Side

From the command line, launch the class that we want to trace. This sample FirstTraceExample class will appear to 'hang' when launched -- its repeatedly invoking methods that we will trace.

1. Download intrace-agent.jar to C:\myPath.
2. Download and compile [this test class] (https://github.com/eostermueller/headlessInTraceClient/blob/master/src/main/java/example/FirstTraceExample.java). No jar files are needed to compile it.
3. Run the class like this:

   java -javaagent:c:\myPath\intrace-agent.jar example.FirstTraceExample
   

   As mentioned above, this java command will appear to hang.

Client Side

Create a sample diagnostic application that traces method invocations from the above application.

1. Create a new blank maven project.

2. Add the following to the section of the maven pom.xml created in the above step.

   <dependency>
     <groupId>com.github.eostermueller</groupId>
     <artifactId>headlessInTraceClient</artifactId>
     <version>0.0.2</version>
   </dependency>
   

3. Copy this JUnit test to src/test/java of the your new project.

4. Run using mvn test

Parameters for intrace-agent.jar

[This page](Parameters for intrace-agent.jar) shows parameters that are read when intrace-agent.jar is launched.

History

InTrace is an open-source Java tracing solution that delivers intrace-agent.jar and a UI(user interface) that:

• Connects to intrace-agent.jar
• Allows you to specify the classes you want to trace
• Displays the text of trace events.

This project, headlessInTraceClient, is basically a 2nd client for intrace-agent.jar, but without the UI. Much of the source for the UI was copied into this project under the package org.headlessintrace. This makes it much easier to create new Java diagnostic tools that are notified when particular method invocations happen in a JVM.