BTrace is a safe, dynamic tracing tool for Java. Please refer to user's guide for BTrace usage information.
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:com.sun.btrace.agent
. This package contains
classes for BTrace's java.lang.instrument
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.
com.sun.btrace.annotations
. 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).
com.sun.btrace.client
. This package contains
BTrace client tool main class.
com.sun.btrace.dtrace
. 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.
com.sun.btrace.comm
. 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.
com.sun.btrace.compiler
. 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.
com.sun.btrace.resources
. This package contains
error messages resource used by BTrace compiler and bytecode verifier.
com.sun.btrace.runtime
. This package contains
various bytecode instrumentation classes used by BTrace. These
instrumentation classes use Objectweb's ASM
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.
com.sun.btrace
. This package contains classes loaded
by bootstrap loader (agent adds classes containing these classes to bootstrap path).
com.sun.btrace.BTraceUtils
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). com.sun.btrace.BTraceRuntime
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!].
com.sun.btrace.annotations
package and classes in com.sun.btrace
package.
asm-3.0
jar for instrumentation and tools.jar
for reading
jvmstat counter values [sun.jvmstat.monitor
classes].
tools.jar
for javac's classes.
BTrace can be debugged by setting few System properties. All these properties are set at the BTrace client.
com.sun.btrace.debug
- this boolean valued property makes
BTrace to print debug messages (set at client - but debug mode is propagated
to BTrace agent as well).
com.sun.btrace.dumpClasses
- this boolean valued property
may be set to force BTrace agent dump every .class that is
intrumented.
com.sun.btrace.dumpDir
- this is a String valued property
that sets the directory where the instrumened .class files are dumped.
-Xverify:all
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 javap tool. The BTrace action methods look like
the form: "btrace$<trace-class-name>$<trace-action-method-name>" - where "."s
in the trace class name are replaced by "$".