Commit 98ff344

BTrace Developer's Guide

<h1>BTrace Developer's Guide</h1>

<b>BTrace</b> is a safe, dynamic tracing system for Java. Please

refer to <a href="usersguide.html">user's guide</a> for BTrace usage

information.

<h3>BTrace Development Tools</h3>

<li>BTrace requires JDK 6 or above.

<li>BTrace can be built using <a href="http://ant.apache.org/">ant</a> or

<a href="http://www.netbeans.org">NetBeans IDE</a>.

<h3>BTrace Components</h3>

BTrace accepts a tracing program written in (subset) of

the Java programming language. BTrace compiles the trace class

into bytecode and submits the same to a java.lang.instrument agent that

runs inside the target program. The BTrace agent is dynamically

loaded into the target program if it is not already loaded (using

"attach-on-demand" API).

BTrace Components:

<li><b>BTrace Client Tool</b> - compiles, validates and submits BTrace program to

BTrace VM agent. And receives trace messages and prints to stdout.

<li><b>BTrace java.lang.instrument Agent</b> to bytecode instrument classes

and hotswap them. Also, this agent verifies the bytecodes of BTrace

class for safety [read-only, boundedness] rules. This way we don't need

to trust the client to enforce the safety rules at compile time.

<li><b>Wire Protocol</b> between the client and the agent.

<h3>BTrace Packages</h3>

<li><b><code>com.sun.btrace.agent</code></b>. This package contains

classes for BTrace's <b><code>java.lang.instrument</code></b> agent.

This agent uses simple socket protocol to communicate with the client.

Multiple BTrace clients are supported. For each client, an instance

of com.sun.btrace.agent.Client is created.

<li><b><code>com.sun.btrace.annotations</code></b>. This package

contains annotations and enumeration classes used by BTrace author

as well as agent to specify/infer "probed locations" of the traced

program. These classes are loaded by bootstrap loader (agent

adds classes containing these classes to bootstrap path).

<li><b><code>com.sun.btrace.client</code></b>. This package contains

BTrace client tool main class.

<li><b><code>com.sun.btrace.dtrace</code></b>. This package contains

BTrace and DTrace integration classes. The classes that wrap DTrace/Java

API are here. Please refer to /use/share/lib/java/javadoc/dtrace for DTrace/Java

API.

<li><b><code>com.sun.btrace.comm</code></b>. This package contains

wire protocol messages between BTrace agent and client tool. BTrace

agent and client communicate by object serializing the instances of

Message classes.

<li><b><code>com.sun.btrace.compiler</code></b>. This package

has classes for compiling a BTrace program into bytecode after

safety verification. Because BTrace accepts subset of Java, it uses

javac's APIs (JSR 199 - compiler tool API, JSR 269 - Annotation

Processing API and javac Tree API to access AST of compiled Java

program) to compile and enforce BTrace safety rules.

<li><b><code>com.sun.btrace.resources</code></b>. This package contains

error messages resource used by BTrace compiler and bytecode verifier.

<li><b><code>com.sun.btrace.runtime</code></b>. This package contains

various bytecode instrumentation classes used by BTrace. These

instrumentation classes use <a href="http://asm.objectweb.org">Objectweb's ASM</a>

package to do actual class file parsing and writing. ASM version 3.0

is used. This package contains BTrace bytecode verifier and jvmstat reader as well.

<li><b><code>com.sun.btrace</code></b>. This package contains classes loaded

by bootstrap loader (agent adds classes containing these classes to bootstrap path).

<code>com.sun.btrace.BTraceUtils</code> class contains built-in "functions" that can be called

by any BTrace program (these are read-only and bounded methods can

be called by trace program). <code>com.sun.btrace.BTraceRuntime</code> class contains

per-client state for each BTrace client and helps implementing certain methods

of BTraceUtils. Also, BTraceRuntime makes sure that BTrace agent's own

method invocations and BTrace built-in "function" calls are not

traced [there by leading to infinite recursion!].

<h3>BTrace jar files</h3>

<li><b>btrace-boot.jar</b> - loaded by bootstrap loader in the traced

JVM. Contains BTrace annotation classes in <b><code>com.sun.btrace.annotations</code></b>

package and classes in <b><code>com.sun.btrace</code></b> package.

<li><b>btrace-agent.jar</b> - contains classes for java.lang.instrument

agent and instrumentation classes. This uses <b><code>asm-3.0</code></b>

jar for instrumentation and <b><code>tools.jar</code></b> for reading

jvmstat counter values [<b><code>sun.jvmstat.monitor</code></b> classes].

<li><b>btrace-client.jar</b> - contains BTrace client classes. This

uses <b><code>tools.jar</code></b> for javac's classes.

<h3>BTrace "To Do"s</h3>

<li>Remove instrumentation when a client leaves tracing session.

Right now, we "disable" trace calls when a BTrace client leaves

the session. It would be better to remove the instrumentation and

re-hotswap the classes to avoid the "disabled" calls completely.

<h3>Debugging BTrace</h3>

BTrace can be debugged by setting few System properties. All these properties are

set at the BTrace client.

<li><b><code>com.sun.btrace.debug</code></b> - this boolean valued property makes

BTrace to print debug messages (set at client - but debug mode is propagated

to BTrace agent as well).

<li><b><code>com.sun.btrace.dumpClasses</code></b> - this boolean valued property

may be set to force BTrace agent dump every .class that is

intrumented.

<li><b><code>com.sun.btrace.dumpDir</code></b> - this is a String valued property

that sets the directory where the instrumened .class files are dumped.

It is better to run the traced JVM with <b><code>-Xverify:all</code></b> to force

bytecode verification of all classes. This is to make sure that BTrace does not produce

bad classes thereby crashing the JVM. After dumping instrumeted classes, it is possible

(offline) analyze those using <b>javap</b> tool. The BTrace action methods look like

the form: "btrace$&lt;trace-class-name&gt;$&lt;trace-action-method-name&gt;" - where "."s

in the trace class name are replaced by "$".

<h3>Known Issues and Limitations</h3>

<li>BTrace <b>does not work when class sharing is on</b> - so run your traced program with

<b>-Xshare:off</b> option or use <b>-server</b> option. When class sharing is

used (atleast on Windows), the traced JVM crashes after instrumenting a

class (for eg. a bootstrap class like java.awt.Component).

<li>Certain <b><code>sun.misc.*</code></b> classes are used by BTrace. You get

<b>compilation warnings</b> because of this. Also, <b><code>sun.jvmstat.monitor.*</code></b>

classes are used to read jvmstat perf. counters.

<li><b>BTrace requires JDK 6</b>. There are API dependencies [for example, javac's new APIs].

And BTrace uses certain recent changes with java.lang.instrument and hotswap. In particular,

<b>BTrace adds private methods while hotswapping classes</b>. This feature (of

adding private methods while hotswapping classes) is <b>not</b> available in earlier

JDK versions. Also, retranformantion is used to avoid fetching .class bytes from

the file system. Again, this is a new feature of java.lang.instrument API since JDK 6.