Dynamic Analysis

Dynamic Analysis

This chapter describes all aspect of dynamic analysis in Chord. Section * describes how to write a dynamic analysis, Section * describes how to compile and run it, and Section * describes common dynamic analysis events supported in Chord.

Writing a Dynamic Analysis

Follow the following steps to write your own dynamic analysis.

Create a class extending chord.project.analyses.DynamicAnalysis and override the appropriate methods in it. The only methods that must be compulsorily overridden are method getInstrScheme(), which must return an instance of the "instrumentation scheme" required by your dynamic analysis (i.e., the kind and format of events to be generated during an instrumented program's execution) plus each process<event>(<args>) method that corresponds to event <event> with format <args> enabled by the chosen instrumentation scheme. See Section * for the kinds of supported events and their formats.

A sample such class MyDynamicAnalysis is shown below:

    import chord.project.Chord;
    import chord.project.analyses.DynamicAnalysis;
    import chord.instr.InstrScheme;

    // ***TODO***: analysis won't be recognized by Chord without this annotation
    @Chord(name = "<ANALYSIS_NAME>")    
    public class MyDynamicAnalysis extends DynamicAnalysis {
        InstrScheme scheme;
        @Override
        public InstrScheme getInstrScheme() {
            if (scheme != null)
                return scheme;
            scheme = new InstrScheme();
            // ***TODO***: Choose (<event1>, <args1>), ... (<eventN>, <argsN>)
            // depending upon the kind and format of events required by this
            // dynamic analysis to be generated for this during an instrumented
            // program's execution.
            scheme.set<event1>(<args1>);
            ...
            scheme.set<eventN>(<argsN>);
            return scheme;
        }
        @Override
        public void initAllPasses() {
            // ***TODO***: User code to be executed once and for all
            // before all instrumented program runs start.
        }
        @Override
        public void doneAllPasses() {
            // ***TODO***: User code to be executed once and for all
            // after all instrumented program runs finish.
        }
        @Override
        public void initPass() {
            // ***TODO***: User code to be executed once before each instrumented program run starts.
        }
        @Override
        public void donePass() {
            // ***TODO***: User code to be executed once after each instrumented program run finishes.
        }
        @Override
        public void process<event1>(<args1>) {
            // ***TODO***: User code for handling events of kind <event1> with format <args1>.
        }
        ...
        @Override
        public void process<eventN>(<argsN>) {
            // ***TODO***: User code for handling events of kind <eventN> with format <argsN>.
        }
    }

Compiling and Running a Dynamic Analysis

Compile the analysis by placing the directory containing class MyDynamicAnalysis created above in the path defined by property chord.ext.java.analysis.path.

Provide the IDs of program runs to be generated (say 1, 2, ..., M) and the command-line arguments to be used for the program in each of those runs (say <args1>, ..., <argsM>) via properties chord.run.ids=1,2,...,N and chord.args.1=<args1>, ..., chord.args.M=<argsM>. By default, chord.run.ids=0 and chord.args.0="", that is, the program will be run only once (using run ID 0) with no command-line arguments.

To run the analysis, set property chord.run.analyses to <ANALYSIS_NAME> (recall that <ANALYSIS_NAME> is the name provided in the @Chord annotation for class MyDynamicAnalysis created above).

Note: The IBM J9 JVM on Linux is highly recommended if you intend to use Chord for dynamic program analysis, as it allows you to instrument the entire JDK; using any other platform will likely require excluding large parts of the JDK from being instrumented. Additionally, if you intend to use online (load-time) bytecode instrumentation in your dynamic program analysis, then you will need JDK 6 or higher, since this functionality requires the java.lang.instrument API with class retransformation support (the latter support is available only in JDK 6 and higher).

You can change the default values of various properties for configuring your dynamic analysis; see Section * and Section * in Chapter *. For instance:

• You can set property chord.scope.kind to dynamic so that the program scope is computed dynamically (i.e., by running the program) instead of statically.
• You can exclude certain classes (e.g., JDK classes) from being instrumented by setting properties chord.std.scope.exclude, chord.ext.scope.exclude, and chord.scope.exclude.
• You can choose between online (i.e. load-time) and offline bytecode instrumentation by setting property chord.instr.kind to online or offline.
• You can require the event-generating and event-handling JVMs to be one and the same (by setting property chord.trace.kind to none), or to be separate (by setting property chord.trace.kind to full or pipe, depending upon whether you want the two JVMs to exchange events by a regular file or a POSIX pipe, respectively). Using a single JVM can cause correctness/performance issues if event-handling Java code itself is instrumented (e.g., say the event-handling code uses class java.util.ArrayList which is not excluded from program scope). Using separate JVMs prevents such issues since the event-handling JVM runs uninstrumented bytecode (only the event-generating JVM runs instrumented bytecode). If a regular file is used to exchange events between the two JVMs, then the JVMs run serially: the event-generating JVM first runs to completion, dumps the entire dynamic trace to the regular file, and then the event-handling JVM processes the dynamic trace. If a POSIX pipe is used to exchange events between the two JVMs, then the JVMs run in lockstep. Obviously, a pipe is more efficient for very long traces, but it not portable (e.g., it does not currently work on Windows/Cygwin), and the traces cannot be reused across Chord runs (see the following item).
• You can reuse dynamic traces from a previous Chord run by setting property chord.reuse.traces to true. In this case, you must also set property chord.trace.kind to full.
• You can set property chord.dynamic.haltonerr to false to prevent Chord from terminating even if the program on which dynamic analysis is being performed crashes.

Chord offers much more flexibility in crafting dynamic analyses. You can define your own instrumentor (by subclassing chord.instr.CoreInstrumentor instead of using the default chord.instr.Instrumentor) and your own event handler (by subclassing chord.runtime.CoreEventHandler instead of using the default chord.runtime.EventHandler). You can ask the dynamic analysis to use your custom instrumentor and/or your custom event handler by overriding methods getInstrumentor() and getEventHandler(), respectively, defined in chord.project.analyses.CoreDynamicAnalysis. Finally, you can define your own dynamic analysis template by subclassing chord.project.analyses.CoreDynamicAnalysis instead of subclassing the default chord.project.analyses.DynamicAnalysis.

Common Dynamic Analysis Events

Chord provides support for instrumenting common dynamic analysis events. The below table describes these events.

Dynamic Analysis