README

==============
Aspirator: A simple checker for exception handler bugs
==============
- Aspirator is a tool that checks for trivial bug patterns in exception
  handlers for Java or JVM compatible programs. Specifically, it reports
  a warning if an important exception is ignored, system aborts on 
  over-caught exceptions, or the exception handler contains "TODO" or
  "FIXME" in the comments. These trivial bugs in exception handlers have
  been shown to have caused a significant number of deadly failures for
  distributed systems. See more details in the paper:

  Simple Testing Can Prevent Most Critical Failures: An Analysis of 
  Production Failures in Distributed Data-intensive Systems, 
  Ding Yuan, Yu Luo, Xin Zhuang, Guilherme Rodrigues, Xu Zhao, Yongle Zhang, 
  Pranay U. Jain, and Michael Stumm. In the Proceedings of the 11th USENIX 
  Symposium on Operating Systems Design and Implementation (OSDI'14), October 2014.   

- Aspirator is built on Chord. The later part of this documents describes
  how to install and run chord. A copy of the Chord source is included 
  here.

- After Chord is installed, the following three analysis can be used to
  detect bugs in exception handling code: 
    - exception-empty-handler-java: detecting empty exception handler
    - terminating-handler-java: detecting unexpected abort in exception 
      overcatch
    - exception-todo-in-handler-java: detecting "TODO" and "FIXME" in
      exception handler

- You will need to read the user guide of Chord to understand how to 
  run an analysis.

- We also extended Chord to easier analyze big real-world project by adding 
  a few more options. As an example, in the example/cassandra directory, 
  there is a chord.properties file showing how to run the 
  "exception-empty-hanler-java" analysis on Cassandra. Here is a brief 
  overview of the required options:

    - chord.class.path: paths to .jar files containing the bytecode of the
      target software to analyze. Normally you can find them in the
      "build/" or "target/" directories in the target software's source
      directory after you compiled it. 

    - chord.src.path: paths to the java source files. The source files are
      used by the "exception-todo-in-handler-java" analysis to analyze the 
      comments; they are also used to print the analysis result.  

    - chord.run.analyses: the value should be one of the followings: 
      "exception-empty-handler-java", "terminating-handler-java", or
      "exception-todo-in-handler-java". 

    - chord.extraclasses.file: contains a list of classes to be analyzed.
      aspirator will only analyze these classes. The reason for us to add
      this option is that by default, chord automatically discovers which
      classes to analyze (see Chapter 7 in chord's user guide). However,
      there are two problems with this default approach: first, it
      requires user to specify a main class, which contains the main
      method, and then analyze all the classes that can be reached by this
      main class. For large projects, it is hard to find the appropriate
      main classes that can be used to reach all the code we want to
      analyze, thus we found a large amount of the target code is not
      analyzed by chord simply because they couldn't be reached; second,
      it will also analyze all the library bytecode, such as java.lang.
      By using this file, it tells aspirator exactly which classes we are 
      interested to analyze, and you do not have to provide a main class.
  
      We also provided an example class file, "classNames.txt", that 
      contains all the classes in cassandra. You can easily generate this 
      file by scripting over the .jar file, which contains all the names 
      of classes.

    - chord.ignore.exceptions: an optional list of exceptions, separated by comma,
      that aspirator will not report a warning if their handlers are empty. 
      This is to reduce the false positives of aspirator. By default, 
      aspirator ignores "FileNotFoundException". 

    - chord.ignore.methods: an optional list of exceptions, separated by comma,
      that aspirator will not report a warning if the exceptions thrown by them
      are not handled. This is to reduce the false positives of aspirator. By 
      default, aspirator ignores exceptions thrown by methods whose names
      contain "close", "cleanup", "stop", and "shutdown". 

    - All other properties do not need to be modified. 

- Note: when running aspirator, you should set "chord.verbose", the verbosity 
  level, to 0, otherwise there will be huge amount of debugging information
  printed.

- After the analysis, the output is in the chord_output/log.txt file. Each
  warning is in the format of:
==========================================
WARNING 1: empty handler for exception: java.lang.Throwable
There are log messages..
  Line: 192, File: "org/apache/cassandra/auth/CassandraAuthorizer.java"

186:         try
187:         {
188:             process(String.format("DELETE FROM %s.%s WHERE username = '%s'", Auth.AUTH_KS, PERMISSIONS_CF, escape(droppedUser)));
188:             process(String.format("DELETE FROM %s.%s WHERE username = '%s'", Auth.AUTH_KS, PERMISSIONS_CF, escape(droppedUser)));
189:         }
190:         catch (Throwable e)
191:         {
192:             logger.warn("CassandraAuthorizer failed to revoke all permissions of {}: {}", droppedUser, e);
193:         }
==========================================
  Aspirator will report whether the exception handler is logged or not. In 
  addition, the exception-throwing line is highlighted by repeating itself 
  (e.g., line 188 in this example). 
 
===============
OBTAINING CHORD
===============

You can either obtain pre-built binaries of Chord or you can obtain the source
code of Chord and build it yourself.  Both these options are described below.

===================
BINARY INSTALLATION
===================

To obtain Chord's pre-built binaries, download and uncompress file
http://jchord.googlecode.com/files/chord-bin-2.1.tar.gz.  It primarily contains
the following files:

- chord.jar, which contains the class files of Chord and of libraries used by
  Chord.
- libbuddy.so, buddy.dll, and libbuddy.dylib: you can keep one of these files
  depending upon whether you intend to run Chord on Linux, Windows/Cygwin, or
  MacOS, respectively.  These files are needed only if you want the high
  performance BDD library BuDDy to be used when the BDD-based Datalog solver
  bddbddb in Chord runs analyses written in Datalog.
- libchord_instr_agent.so: this file is needed only if you want the JVMTI-based
  bytecode instrumentation agent to be used when Chord runs dynamic analyses.

Novice users can ignore items (2) and (3) until they become more familiar with
Chord.  The binaries mentioned in items (2) and (3) might not be compatible with
your machine, in which case you can either forgo using them (with hardly any
noticeable difference in functionality), or you can download the sources and
build them yourself, as described below.

===================
SOURCE INSTALLATION
===================

To obtain Chord's source code, download and uncompress file
http://jchord.googlecode.com/files/chord-src-2.1.tar.gz.  It contains Chord's
source code and jars of libraries used by Chord.

If you also want the source code of libraries used by Chord (e.g., joeq,
javassist, bddbddb, etc.), download and uncompress file
http://jchord.googlecode.com/files/chord-libsrc-2.1.tar.gz.

Alternatively, you can obtain the latest development snapshot from the SVN
repository by running the following command:

svn checkout http://jchord.googlecode.com/svn/trunk/ chord

Instead of checking out the entire trunk/, which contains several
sub-directories, you can check out specific sub-directories:

- main/ contains Chord's source code and jars of libraries used by Chord.
- libsrc/ contains the source code of libraries used by Chord (e.g., joeq,
  javassist, bddbddb, etc.).
- test/ contains Chord's regression tests.
- many more; these might eventually move into main/.

Files chord-2.1-src.tar.gz and chord-2.1-libsrc.tar.gz mentioned above are
essentially stable releases of the main/ and libsrc/ directories, respectively.

=========================
COMPILING THE SOURCE CODE
=========================

Compiling Chord's source code requires the following software:

- A JVM with JDK 5 or higher, e.g. IBM J9 or Oracle HotSpot.
- Apache Ant, a Java build tool.

Chord's main directory contains a file named build.xml which is interpreted by
Apache Ant.  To see the various possible targets, simply run command "ant" in
that directory.

To compile Chord, run command "ant compile" in the same directory.  This will
compile Chord's Java sources from src/ to class files in classes/, as well as
build a jar file chord.jar that contains these class files as well as the those
in the jars of libraries that are used by Chord and are provided under lib/
(e.g., joeq.jar, javassist.jar, bddbddb.jar, etc.).  Additionally:

- If system property chord.use.buddy is set to true, then the C source code of
  BDD library BuDDy from directory bdd/ will be compiled to a shared library
  named libbuddy.so on Linux, buddy.dll on Windows, and libbuddy.dylib on MacOS;
  this library is used by BDD-based Datalog solver bddbddb in Chord for running
  analyses written in Datalog.

- If system property chord.use.jvmti is set to true, then the C++ source code of
  the JVMTI-based bytecode instrumentation agent from directory agent/ will be
  compiled to a shared library named libchord_instr_agent.so on all
  architectures; this agent is used in Chord for computing analysis scope
  dynamically and for running dynamic analyses.

Properties chord.use.buddy and chord.use.jvmti are defined in file
chord.properties in Chord's main directory.  The default value of both these
properties is false.  If you set either of them to true, then you will also need
a utility like GNU Make (to run the Makefile's in directories bdd/ and agent/)
and a C++ compiler.

=============
RUNNING CHORD
=============

Running Chord requires a JVM with JDK 5 or higher. There are two equivalent ways
to run Chord.  One way, which is available only in the source installation of
Chord, is to run the following command:

ant -f <CHORD_MAIN_DIR>/build.xml -D<key1>=<val1> ... -D<keyN>=<valN> run

The above requires Apache Ant (a Java build tool) to be installed on your
machine.  The alternative, which does not require Apache Ant and is available in
both the source and binary installations of Chord, is to run the following
command:

java -cp <CHORD_MAIN_DIR>/chord.jar -D<key1>=<val1> ... -D<keyN>=<valN> chord.project.Boot

where <CHORD_MAIN_DIR> denotes the directory containing file chord.jar; that
directory is also expected to contain any other binaries in Chord's installation
(e.g., libbuddy.so and libchord_instr_agent.so).

Each "-D<key>=<val>" argument above sets the system property named <key> to the
value denoted by <val>.  The only way to specify inputs to Chord is via system
properties; there is no command-line argument processing.  All system properties
recognized by Chord are described at
http://chord.stanford.edu/user_guide/properties.html.

QUICK START
===========

To ensure that Chord is installed successfully, run it on a provided example
Java program as follows.  First run command "ant" in directory
examples/hello_world/.  This will compile the Java source code of that example.
Then, run the following command:

java -cp <CHORD_MAIN_DIR>/chord.jar -Dchord.work.dir=<CHORD_MAIN_DIR>/examples/hello_world \
     -Dchord.run.analyses=cipa-0cfa-dlog chord.project.Boot

This will run a basic may-alias and call-graph analysis (called 0CFA) on the
example Java program.  It will produce somewhat verbose output of the form:

     Chord run initiated at: Mar 13, 2011 10:31:08 PM
     ENTER: cipa-0cfa-dlog
     ... (truncated here for brevity)
     LEAVE: cipa-0cfa-dlog
     Chord run completed at: Mar 13, 2011 10:31:36 PM
     Total time: 00:00:27:671 hh:mm:ss:ms

To reduce the verbosity of Chord's output, set -Dchord.verbose=0 on the command
line.

The names and descriptions of analyses besides cipa-0cfa-dlog that are provided
in Chord are available here:

http://chord.stanford.edu/user_guide/predefined.html

To setup your own Java program for analysis using Chord, see here:

http://chord.stanford.edu/user_guide/setup.html

To write your own analyses, possibly atop provided ones, see here:

http://chord.stanford.edu/user_guide/writing.html

FURTHER DOCUMENTATION
=====================

Chord's User Guide is available at:

http://chord.stanford.edu/user_guide/

The Javadoc of Chord's source code is available at:

http://chord.stanford.edu/javadoc/

For questions about Chord, send email to <chord-discuss@googlegroups.com>, or
browse previous postings at:

http://groups.google.com/group/chord-discuss/

Posting does not require membership but posts by non-members are moderated to
avoid spamming group members.