Skip to content

Instantly share code, notes, and snippets.

@yulewei

yulewei/btrace-developers-guide.md

Last active October 2, 2018 20:13
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save yulewei/3e465fa42530dcfa84f07217fc08725a to your computer and use it in GitHub Desktop.
Save yulewei/3e465fa42530dcfa84f07217fc08725a to your computer and use it in GitHub Desktop.
Download ZIP
Raw
btrace-developers-guide.md

BTrace Developer's Guide

https://github.com/btraceio/btrace/blob/master/docs/developersguide.html

https://web.archive.org/web/20170409160711/https://kenai.com/projects/btrace/pages/DeveloperGuide

BTrace is a safe, dynamic tracing tool for Java. Please refer to user's guide for BTrace usage information.

BTrace Development Tools

  • BTrace requires JDK 6 or above.
  • BTrace can be built using ant or NetBeans IDE.

BTrace Components

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:

  • BTrace Client Tool - compiles, validates and submits BTrace program to BTrace VM agent. And receives trace messages and prints to stdout.
  • BTrace java.lang.instrument Agent 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.
  • Wire Protocol between the client and the agent.

BTrace Packages

  • 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!].

BTrace jar files

  • btrace-boot.jar - loaded by bootstrap loader in the traced JVM. Contains BTrace annotation classes in com.sun.btrace.annotations package and classes in com.sun.btrace package.
  • btrace-agent.jar - contains classes for java.lang.instrument agent and instrumentation classes. This uses asm-3.0 jar for instrumentation and tools.jar for reading jvmstat counter values [sun.jvmstat.monitor classes].
  • btrace-client.jar - contains BTrace client classes. This uses tools.jar for javac's classes.

BTrace "To Do"s

  • 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.

Debugging BTrace

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.

It is better to run the traced JVM with -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$$" - where "."s in the trace class name are replaced by "$".

Known Issues and Limitations

  • BTrace requires JDK 6. There are API dependencies [for example, javac's new APIs]. And BTrace uses certain recent changes with java.lang.instrument and hotswap. In particular, BTrace adds private methods while hotswapping classes. This feature (of adding private methods while hotswapping classes) is not 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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment