lanamorgan / wiretap

An instrumenter for dynamic logging for java bytecode programs

Wiretap

Wiretap is a project meant to trace information of running a java program. This information can be used to create dynamic analyses that can run after the fact. This project aims to

• scale, it needs to run fast;
• be extendable, it can track different things;
• thread safe;
• and be re-playable, so a trace can be reproduced.

Wiretap should work with java's down to version 1.6.

Getting Started

Wiretap is implemented as a java agent. To run it write

java -javaagent:wiretap.jar -Dwiretap.recorder=<recorder>.. normal parameters 

This will by default create a wiretap folder _wiretap/, which will contain logs of the execution of the program. As a default the program will log enough to be able to replay itself.

If you have build the test submodule baseline, then you can test it all with this command:

java -javaagent:build/wiretap.jar \
  -cp test/baseline/build/baseline.jar \
  edu.ucla.pls.baseline.Transfer

Output Defined

The _wiretap/ folder contain these files:

• classes.txt a list of classes encountered by wiretap, in chronological order.
• methods.txt a list of methods instrumented by wiretap. The methods are formatted like this:

  <FullyQualifiedMethod>:(<Signature>)<ReturnType>
  

  Stuff that still needs to be worked on: [ ] Find a good way to represent the GenericSignature, Should it replace the Signature?

Wiretaps

Wiretaps are installed by a Wiretapper. A wiretapper is essentially a wrapper around the constructor for the Wiretap. It also has the ability to add information about the wiretap and inspect the recorder to see if it can accept the events that the Wiretap emit.

Recorder

A recorder is something that can handle incoming events. The recorder is statically linked to the main program, so it has to implement at least the following static methods:

public static <Recorder> getRecorder(); 
public static void setupRecorder(WiretapProperties); 
public static void closeRecorder(); 

Also it has to implement the methods for all the event that it will accept.

Note: Recorders can be chained if some of the events has to be processed.

Currently Implemented Recorders

A full list can be found in src/main/edu/ucla/pls/wiretap/recorders/

• ReachableMethods - Outputs the reachable methods of a program with no repetition in the order they where encounterd in the program.
• BinaryHistoryLogger - Logs alot of event in a binary file wiretap.hist. The format is described in wiretap-tools repository.

Building from Source

Run ant in the main repository.

Q&A

• Why not instrument before running the program? The problem is that some programs hot-loads classes that did not statically exist in the program before running the program. To cover all cases, and the actual behavior of the program we have to instrument as the classes are loaded by the class loader.

Todos

• Create a test that figures out if extended inherits graph and information is needed. The special case is the Thread.start(). Is it possible that if a class extends Thread that the implementation won't catch that. ( This does seam to be confirmed)

• Create a Trie for ignore classes.

• Improve logging speed.

DDBING

$ java -ea -javaagent:../wiretap/build/wiretap.jar
-Dwiretap.recorder=ABCDRecorder -cp test/abcd/classes/ BetterTest

$ java -ea -javaagent:../wiretap/build/wiretap.jar
-Dwiretap.recorder=ABCDReplayer -Dwiretap.replayfile=assert.log -cp
test/abcd/classes/ BetterTest