TracerJD Usage

How to use TracerJD

Before using running TracerJD analyses

In order for tracer to instrument the bytecode of the target subject, adding certain statements in the subject source code is needed. In this regard however, tracer requires the addition of statements into the main/entry class of the subject program only.

Precisely, the following statements should be added to the entry class, which is essentially an extra static method that allows the static analysis (Soot phase, more precisely) to include the TracerJD runtime monitors in its bytecode analysis.

public class TheEntryClass {
	......
	// added for tracer Instrumentation
	static void __link() {
		profile.EvenMonitor.__link(); 
	}
	......

Then, follow the steps below:

(1) Compile the subject with the above extra code added.

• similar to how you compile the original (uninstrumented) subject program, just add extra class paths for tracer and its library dependencies.
• An actual example script is given below; you just need to accommodate the variables to your own environment.

  ver=$1
  seed=$2
  ROOT=/home/hcai/
  subjectloc=/home/hcai/SVNRepos/star-lab/trunk/Subjects/Schedule1/
  mkdir -p $subjectloc/bin/${ver}${seed}
  javac -cp $subjectloc/lib/:libs/DUAForensics.jar:libs/InstrReporters.jar:libs/deam.jar:libs/Sensa.jar:libs/mcia.jar:TracerJD.jar  \
  	-g:source -nowarn \
  	-source 1.4 \
  	-d $subjectloc/bin/${ver}${seed} \
  	$subjectloc/src/${ver}${seed}/ScheduleClass.java
  

(2) Instrument logging probes for runtime tracing

• An actual example script is given below; you just need to accommodate the variables to your own environment.

  ver=$1
  seed=$2
  ROOT=/home/hcai/
  subjectloc=/home/hcai/SVNRepos/star-lab/trunk/Subjects/Schedule1/
  
  MAINCP=".:libs/polyglot.jar:libs/sootclasses-2.3.0.jar:libs/jasminclasses-2.3.0.jar:libs/java_cup.jar:libs/LocalsBox.jar:$subjectloc/lib:libs/DUAForensics.jar:libs/InstrReporters.jar:libs/deam.jar:libs/Sensa.jar:libs/mcia.jar:TracerJD.jar"
  
  mkdir -p $subjectloc/out-TracerInstr
  
  #SOOTCP=.:/etc/alternatives/java_sdk/jre/lib/rt.jar:/etc/alternatives/java_sdk/jre/lib/jce.jar:
  SOOTCP=".:libs/rt.jar:libs/polyglot.jar:libs/sootclasses-2.3.0.jar:libs/jasminclasses-2.3.0.jar:libs/java_cup.jar:libs/LocalsBox.jar:$subjectloc/lib:libs/DUAForensics.jar:libs/InstrReporters.jar:libs/deam.jar:libs/Sensa.jar:libs/mcia.jar:TracerJD.jar:$subjectloc/lib:$subjectloc/bin/${ver}${seed}"
  
  OUTDIR=$subjectloc/tracerInstrumented-$ver$seed
  mkdir -p $OUTDIR
  
  starttime=`date +%s%N | cut -b1-13`
  	#-debug \
  	#-dumpJimple \
  	#-wrapTryCatch \
     	#-duaverbose \
  	#-dumpFunctionList \
  	#-debug \
  $JAVA -Xmx1600m -ea -cp ${MAINCP} profile.EventInstrumenter \
  	-w -cp ${SOOTCP} \
  	-p cg verbose:false,implicit-entry:false -p cg.spark verbose:false,on-fly-cg:true,rta:true \
  	-f c -d "$OUTDIR" -brinstr:off -duainstr:off \
  	-wrapTryCatch \
  	-slicectxinsens \
  	-notracingval \
  	-allowphantom \
  	-staticCDInfo \
  	-main-class ${DRIVERCLASS} -entry:${DRIVERCLASS} \
  	-process-dir $subjectloc/bin/${ver}${seed}  \
  	1>$subjectloc/out-TracerInstr/instr-${ver}${seed}.out 2>$subjectloc/out-TracerInstr/instr-${ver}${seed}.err
  stoptime=`date +%s%N | cut -b1-13`
  echo "StaticAnalysisTime for ${ver}${seed} elapsed: " `expr $stoptime - $starttime` milliseconds
  
  

(3) Run the instrumented code to generate dependence traces.

• Similar to how you run the original (uninstrumented) subject program, just add extra class paths for tracer and its library dependencies.
• An actual example script is given below; you just need to accommodate the variables to your own environment.

  ver=$1
  seed=$2
  NT=${3:-"5"} % number of inputs to use
  ROOT=/home/hcai/
  subjectloc=/home/hcai/SVNRepos/star-lab/trunk/Subjects/Schedule1/
  
  INDIR=$subjectloc/tracerInstrumented-$ver$seed
  
  MAINCP=".:libs/polyglot.jar:libs/sootclasses-2.3.0.jar:libs/jasminclasses-2.3.0.jar:libs/java_cup.jar:libs/LocalsBox.jar:$subjectloc/lib:libs/DUAForensics.jar:libs/InstrReporters.jar:libs/deam.jar:libs/Sensa.jar:libs/mcia.jar:TracerJD.jar:$subjectloc/lib:$INDIR"
  
  starttime=`date +%s%N | cut -b1-13`
  
  	#"-fullseq" 
  java -Xmx1600m -ea -cp ${MAINCP} trace.Runner \
  	"$subjectloc" \
  	${ver}${seed} \
  	$DRIVERCLASS \
  	$NT \
  	-caching
  
  stoptime=`date +%s%N | cut -b1-13`
  echo "RunTime for ${ver}${seed} elapsed: " `expr $stoptime - $starttime` milliseconds
  cp $INDIR/{varIds.out,staticCDInfo.dat,stmtids.out} $subjectloc/tracerOutdyn-${ver}${seed}/
  
  

(4) Dynamic dependence querying interface and client analyses

• Included as part of the TracerJD tracing framework is a small set of unit tests of such interface (dynamic dependence querying routines)
• The following script illustrates how to run the unit test suite (to make sure the framework works before you want to develop and run client analyses on TracerJD)

  ver=$1
  seed=$2
  NT=${1:-"5"} % number of inputs to use
  ROOT=/home/hcai/
  subjectloc=/home/hcai/SVNRepos/star-lab/trunk/Subjects/Schedule1/
  
  INDIR=$subjectloc/tracerOutdyn-${ver}${seed}
  
  MAINCP=".:libs/polyglot.jar:libs/sootclasses-2.3.0.jar:libs/jasminclasses-2.3.0.jar:libs/java_cup.jar:libs/LocalsBox.jar:$subjectloc/lib:libs/DUAForensics.jar:libs/InstrReporters.jar:libs/deam.jar:libs/Sensa.jar:libs/mcia.jar:TracerJD.jar:$subjectloc/lib"
  
  starttime=`date +%s%N | cut -b1-13`
  	#"main" \
  java -Xmx1800m -ea -cp ${MAINCP} trace.TraceAnalysis \
  	"$INDIR" \
  	$NT \
  	#-debug
  
  stoptime=`date +%s%N | cut -b1-13`
  echo "RunTime for ${ver}${seed} elapsed: " `expr $stoptime - $starttime` milliseconds