JumboTrace 🐘

An experimental tracer for Java, to record the evolution of the state of a Java program during its execution and use it to build a trace (sequence of events and lines executed in the program).

Principle

The tracer works by injecting calls to logging methods into the program using a compiler plugin (for javac). The logging methods are defined in a special class, named ___JumboTrace___, that gets injected into the program. Events are written to a binary file using serialization. A minimal frontend is available that can display the traces in the console. A Python script simplifies the execution of the tracer.

Warning/disclaimer

This project is currently an early prototype. While it has been tested throughout its development, there is no guarantee about the absence of bugs.

Limitations

The following limitations and bugs are known:

• Multiple top-level classes in a single source file are not supported (but inner classes are supported) (expected outcome: the plugin crashes)
• Logging inside enum constructors is badly supported (expected outcome: trace with missing events)
• Variable names generated by the compiler plugin might conflict with user-defined ones (expected outcome: undefined behavior). To stay away from this problem, it suffices to avoid using '$' in variable names in the traced programs
• Pattern matching (e.g. if (o instanceof String s) { /* do something with s */ }) is currently not supported (expected outcome: the plugin crashes)

How to run the code (list of commands to be passed to the automation Python script)

The intended workflow is that the commands are run from the automation directory, and the binary file containing the serialized trace is written in that directory. Each time a trace is generated, it overwrites the one from the previous execution.

• Run an example program and display the collected trace: run example <example-name>, e.g. python automation.py run example Arrays
• Run an example project and display the collected trace: run exproj <example-project-name>, e.g. python automation.py run exproj Chemistry
• Run the tests: test (python automation.py test)
• Run a selection of tests: test <list of test names separated by whitespaces, e.g. python automation.py test Arrays Generics Jumps
• Run the frontend only: run frontend [-verbose] <path-to-src-dir>. The binary file containing the serialized trace events is expected to be located in the automation directory (as it will be after it has been generated by a run or test command). The main purpose of this command is to be able to generate a less detailed version of the traces by running this command without the -verbose option. E.g.: python automation.py run frontend ../examples/Arrays

Other commands are available, but they are much less useful. They can be found in the script (see the pattern match in def main()).

Automated tests

The automation script has support for automated testing, using the commands described above. Each test corresponds to one example program. The program is run both with and without the instrumentation, and the outcomes of both executions (on stdout and stderr) are compared, the goal being to detect alterations of the behavior of the program by the instrumentation process. These outputs must be exactly the same between the instrumented and non-instrumented versions of the program for the test to pass. The trace is then loaded by the frontend and displayed in the console. These tests do NOT perform checks on the generated trace (apart from checking that the trace does not crash the frontend). Tests overwrite the traces generated by previous tests or by the previous execution of an instrumented program.

If you want to add a test, simply add an example program in a new directory in examples. It will be automatically added to the set of tested programs when running test without arguments. You may want to insert lots of calls to System.out.println and System.err.println, or similar methods, to help the testing system detect possible errors. If you want to add an example program that should not be used as a test case, add its name to the list of excluded examples in the automation script.

Setup

In order to be able to run all the functionalities of this repository, you need:

• Java 17.0.6 (both javac and java, https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html). Later versions are probably fine too, but this has not been tested.
• Maven (https://maven.apache.org/install.html, tested on Maven 3.8.1)
• Python ≥ 3.12.0 (https://www.python.org/downloads/) for the automation script
• make might also be useful as Makefiles are provided to run the example programs without instrumentation, but this is not strictly required (Installation instructions: Ubuntu, Windows)

Modules

• jumbotrace-plugin contains the code of an additional compiler pass that instruments the program to generate traces. The plugin is represented by the JumboTrace class and the core class of the instrumentation phase is the Transformer class

• jumbotrace-injected contains the Java representation of program events, as well as the code to be injected into the instrumented programs and the basic frontend

• jumbotrace-injectedgen contains a script based on JavaParser that generates specialized versions of the methods annotated with @Specialize in ___JumboTrace___

• automation contains a Python script that runs the whole system according to the commands provided by the user

• examples contains example programs. The system fails on the Counters example because the source file contains several classes. All other examples are expected to be successfully handled by the tracer (in the sense that it manages to generate a trace). All examples are simple programs, except Chemistry that contains a full-blown Maven based project. This example is not supported by the testing systems, but all others (except the failing one) are.