Skip to content
This repository has been archived by the owner on Oct 16, 2020. It is now read-only.

Home

Jump to bottom
lzccc edited this page Oct 14, 2020 · 20 revisions

Blinky: Java Code Instrumenter and Execution Tracer

Welcome to the Blinky wiki!

Blinky is an instrumenter and execution tracer for software systems that compile to Java Bytecode and target the Java Virtual Machine for execution.

Blinky has the capability to log the execution of any source- or byte-code instruction being executed during a software run. In addition, it also logs auxiliary execution events for the entry, exit, and competition of method invocations, method declarations, and compile-time source- and byte-code instructions. Execution event logs that indicate method exits may take the form of return or throw instructions.

Source-code-line: For the purposes of this project, a "source code line" or a "source code level instruction" is a single executable line of code, delimited by a newline character, within a Java source code file (*.java).

Contents

ARCHITECTURE

More to come.

EXTERNAL DEPENDENCIES

INSTALLATION & USAGE INSTRUCTIONS

Installation

The installation of Blinky is currently based on Maven. To install,

  1. make sure that you have the latest installation of Maven (3.3.3) installed.
  2. Clone this git project and change into the project's directory.
  3. Run mvn package. That's it! This should create three Jar files in the target directory under the blinky-core module (check blink/blinky-core/target):
blinky$ ls blinky-core/target/*jar
blinky-core/target/blinky-core-0.0.1-SNAPSHOT-jar-with-dependencies.jar
blinky-core/target/blinky-core-0.0.1-SNAPSHOT-tests.jar
blinky-core/target/blinky-core-0.0.1-SNAPSHOT.jar

Usage

(cont. from the installation instructions from above)

  1. Use blinky-core-0.0.1-SNAPSHOT-jar-with-dependencies.jar for just about anything, like (typically) when using Blinky as a javaagent for instrumenting and profiling a software programs that are run with the java command.
  2. Run mvn install to deploy Blinky and its dependencies in your local maven repository when using Blinky as a dependency for other projects. This should run all the unit tests in Blinky Core and Util.

The following is a basic structure of using blinky as a java-agent with the java command, to instrument and profile a system-under-analysis: java -Xbootclasspath/p:/path/to/blinky-core-0.0.1-SNAPSHOT-jar-with-dependencies.jar -javaagent:/path/to/blinky-core-0.0.1-SNAPSHOT-jar-with-dependencies.jar=<arguments-to-blinky-java-agent> com.example.SystemUnderAnalysis

Arguments to Blinky's Java Agent

0|A|[xile] ... profiler configuration, to control the kind of traces that are generated

  • 0 ... no execution tracing

OR

  • x stands for method exit events;
  • i stands for method invocation events;
  • l stands for source line execution events;
  • e stands for method enter events.
  • v stands for local variable instructions, e.g. ILOAD, ISTORE, etc.
  • z stands for zero operand instructions, e.g. ADD, MUL, GOTO, PUSH, POP, etc.
  • j stands for jump instructions, e.g. IFNULL
  • f stands for field instructions, e.g. PUTFIELD, GETFIELD, PUTSTATIC and GETSTATIC
  • c stands for load constant instructions, e.g. LDC, ICONST_1, etc
  • t stands for type instructions, e.g. CHECKCAST
  • s stands for switch instructions, e.g. TABLESWITCH and LOOKUPSWITCH

OR

  • A stands for All of the Above! (use with great caution!)

whitelist ... read a selection of classes, a.k.a. whitelist, to ensure that they are instrumented.

Examples:

xle,whitelist will force the instrumenter to check against the whitelist, and trace method enter, exit and source line execution events.
l will trace only source line execution events, while ignoring the whitelist.
i will trace only method invocation events, while ignoring the whitelist.

Junit Support

In order to run your Junit test cases with Blinky's instrumentation, use Tacoco (http://github.com/spideruci/tacoco). More to come.

LICENSE.txt

Refer to blinky/LICENSE.txt in this repository.

Clone this wiki locally