GhostWriter helps people to reason about their application, catch and pinpoint bugs quickly without writing any lines of extra code or deploying additional services

Tracing your application flow

See GhostWriter with the tracer runtime in action:

How does it work?

Can you give me a more technical description?

GhostWriter is a non-invasive solution for adding common application event handler stubs to your Java code. Essentially what you would end up writing by hand if you would like to have proper tracking of your application workflow. After the instrumentation you will have the chance to provide custom handlers for all:

• method calls, including entering, return and exiting events (some methods are excluded by default, see Configuration options and Excluding methods)

• state changes of your application, such as value assignment and other side-effectful operations

• unexpected errors

A "pseudo" before-after setup with GhostWriter (more or less readable decompiled code):

ℹ️	You always see and work with your original source. The above picture is just an illustration.

Just add the necessary dependencies to your application and GhostWriter will take care of instrumenting the ghostwriter-api calls.

There are two ways to use GhostWriter: using annotation processing, or directly calling the instrumentation logic to enhance your classes. The former method is now deprecated, because it only supports Java 7 and 8.

GhostWriter Direct Instrumentation

dependencies {
    runtime 'io.ghostwriter:ghostwriter-rt-tracer:0.5.0'
    runtime 'io.ghostwriter:ghostwriter-rt-tracer-slf4j:0.5.0' // Include this as well for SLF4J based logging.
}

buildscript {
    dependencies {
        classpath "io.ghostwriter:ghostwriter:0.8.0"
    }
}
task instrument(type: JavaExec) {
    main = 'io.ghostwriter.GhostWriterClassFileTransformer'
    args = [sourceSets.main.java.outputDir.absolutePath]
    // Supply configuration by setting JVM arguments. In this case, disable value assignment tracking.
    jvmArgs = ['-DGHOSTWRITER_TRACE_VALUE_CHANGE=false']
    classpath = buildscript.configurations.classpath
    classpath += sourceSets.main.runtimeClasspath
}
compileJava.finalizedBy instrument

GhostWriter Annotation Processor (Legacy, supports Java 8 and Java 7 only)

❗	You have to choose the dependency that is inline with your Java compiler (JDK) version.

For Java 7 this means ghostwriter-jdk-v7, for Java 8 it is ghostwriter-jdk-v8.

GhostWriter is tested and verified with both Oracle JDK and Open JDK versions.

For detailed instructions keep reading on, if you just want to have a quick overview on a working sample, check here.

Maven

Add another dependency entry to the dependencies section. This means that for JDK8, you will have the following entry in you pom.xml file.

<dependency>
    <groupId>io.ghostwriter</groupId>
    <artifactId>ghostwriter-jdk-v8</artifactId>
    <version>0.7.2</version>
    <scope>compile</scope>
</dependency>

Your are done! Time to recompile your application!

Gradle

The provided snippets work with Gradle 3+. The dependencies of GhostWriter are fetched from Maven Central. So you have to add it to your list of repositories if its not there yet. For a project that uses JDK8, you’ll will have to add the following lines to your build.gradle file.

repositories {
    mavenCentral()
}

dependencies {
    compile "io.ghostwriter:ghostwriter-jdk-v8:0.7.2"
}

Your are done! Time to recompile your application!

For older Java versions (Java 7)

If you are still using an older Java/JDK version such as Java 7, you’ll need a different set of dependencies.

Maven

<dependency>
    <groupId>io.ghostwriter</groupId>
    <artifactId>ghostwriter-jdk-v7</artifactId> // (1)
    <version>0.7.2</version>
    <scope>compile</scope>
</dependency>

1. Note the use of ghostwriter-jdk-v7.

Gradle

repositories {
    mavenCentral()
}

dependencies {
    compile "io.ghostwriter:ghostwriter-jdk-v7:0.7.2" // (1)
}

1. Note the use of ghostwriter-jdk-v7

Now recompile your application and if all goes well, you should now have support for plugging in runtime implementations.

Explicitly specifying the compile time annotation

This steps should only be done in case you manually set annotation processors (for whatever reason). By default the compiler should pick up the GhostWriter annotation processor based on the service loader contract.

Maven

To have it explicitly set, you’ll need to add the following lines to your pom.xml.

<build>
     <plugins>
         <plugin>
             <groupId>org.apache.maven.plugins</groupId>
             <artifactId>maven-compiler-plugin</artifactId>
             <version>3.6.0</version>
             <executions>
                 <execution>
                     <id>default-compile</id>
                     <phase>compile</phase>
                     <goals>
                         <goal>compile</goal>
                     </goals>
                     <configuration>
                         <!-- This is how we enable GhostWriter, the rest is more or less boilerplate of Maven -->
                         <annotationProcessors>
                             <annotationProcessor>io.ghostwriter.openjdk.v8.GhostWriterAnnotationProcessor</annotationProcessor> // (1)
                         </annotationProcessors>
                         <source>1.8</source>
                         <target>1.8</target>
                     </configuration>
                 </execution>
             </executions>
        </plugin>
     </plugins>
 </build>

1. Make sure to use the correct annotation processor, for Java 7 this would be io.ghostwriter.openjdk.v7.GhostWriterAnnotationProcessor

The important part is the specification of the annotation processor using the annotationProcessor tag. The rest is more or less Maven foreplay.

Gradle

In Gradle, that is done by adding the following snippet to your build.gradle file.

compileJava {
    options.compilerArgs = [
            // use the GhostWriter preprocessor to compile Java classes
            "-processor", "io.ghostwriter.openjdk.v8.GhostWriterAnnotationProcessor" // (1)
    ]
}

1. Make sure to use the correct version, for Java 7 this would be io.ghostwriter.openjdk.v7.GhostWriterAnnotationProcessor

Is it working?

Set the following environmental variable to track what kind of code GhostWriter writes instead of you.

export GHOSTWRITER_VERBOSE=true

You should see something like this:

As you can see there are a lot of Note: outputs that dump the instrumented code.

Configuring

Configuration options can be set as compiler options. For example:

subprojects {
    afterEvaluate {
        tasks.withType(JavaCompile) {
            options.compilerArgs.addAll(["-AGHOSTWRITER_EXCLUDE=my.package.SomeClass,my.package.subpackage"]);
        }
    }
}

For all configuration options, see Configuration options .

Enhancing your application with GhostWriter is half the battle. You still need that data after all! With the no-operations stubs you won’t get much benefit from GhostWriter, however this is where GhostWriter shines! You can leverage one of the multiple runtime implementations available or roll your own!

Tracing your application - for the times when you don’t have your handy debugger at your disposal and you want to find out exactly what is going on in you application.

Capturing error snapshots - giving you better exceptions by providing the exact and detailed application state that led to the unexpected error and thus helping you battle Heisenbugs!

Do whatever you want! - provide your own solution for handling the data you get!

In some cases you might be inclined to change the default behaviour of the instrumentation steps. Currently there are 2 ways to do this. If you want to disable an instrumentation steps for you entire project, use the appropriate configuration option otherwise stick to the annotations provided by the API.

Configuration options

Excluding

GHOSTWRITER_EXCLUDE=my.package.SomeClass,my.package.subpackage

GHOSTWRITER_EXCLUDE_METHODS=toString,equals

GHOSTWRITER_EXCLUDE_METHODS=""

Annotations

@Exclude
public class ExcludedTopLevelClass {

    // this method won't be traced
    public int meaningOfLife() {
        return 42;
    }

}

@Exclude // the annotation signals the GhostWriter instrumenter to ignore this method
public int excludedMethod() {
    int i = 3;
    // ...
    return i;
}

public void login(String userName, @Exclude char[] password) {
        // ...
}

public void buyAllTheThings() {
    // ...
    @Exclude String creditCardNumber;
    // ...
}

@Include
class MyClass {

   public void myMethod() {
      // this will be instrumented
   }

   @Exclude
   public void myOtherMethod() {
      // this will not be instrumented
   }

}

class BestClassEver {

   public void aMethod() {
      // this will not be instrumented
   }

   @Include
   public void theMethodIWantToTrace() {
      // this will be instrumented
   }

}

First and foremost thank you for putting in the effort and time that is needed to contribute!

For smaller changes, just create a pull request and make sure that the automated tests still pass and that your changes are inline with the code quality checks. Providing additional documentation and test coverage is always welcome!

For bigger changes (API, new features, …​) consider opening an issue first so it can be discussed.

If you have a quick question or stumble upon a bug feel free to open an issue or ask on Gitter.

What about the performance impact?

By default GhostWriter uses no-op stubs, so the performance heavily depends on the runtime implementation you use. The JVM does an awesome job of optimizing the generated code and the end performance depends on your application behaviour as well. In case of performance critical section the instrumentation can be skipped by applying the correct annotation in order to minimize the performance overhead.

What about 3rd party code? Will that have the same stubs instrumented

Only if you compile that yourself. Potentially you can compile your own rt.jar with GhostWriter and have full blown coverage! The general consideration with the compile-time instrumenter implementation is that you should focus on the code that is in your control.

Will it mess with my stack traces? Like referring to line numbers that do not exist in my original source code?

No. The code instrumenter implementation makes sure that it is non-invasive and your stack traces refer to the correct source lines.

Why not a Java agent based solution?

At the end of the day this is about trade-offs and implementation details. With the current approach you get type-safety (the compiler verifies that the instrumented code is correct) and there is no application startup performance penalty. Plus, once you compiled your code, it is only a matter of providing dependencies. Even if you are not in control of specifying how your application/library is used you still have tracing support. Of course, the current implementation also has disadvantages. In the long run both compile-time and run-time implementation will be supported. Depending on your use case (library vs. application), you can pick the one that fits your needs. The acceptance testing infrastructure is in place for verifying the instrumentation steps, so feel free to contribute a solution ;)

I put the tracer related jars into my application’s classpath, yet they are ignored and noop is selected, why?

Ghostwriter uses the Java ServiceLoader to find the tracer implementation. In ghostwriter-api 0.4.0, ghostwriter-tracer 0.3.1 and earlier versions the default context classloader of the current thread was used. In some cases it was not set, and the system classloader was used as a fallback, which most probably did not contain the tracer jars (one example is when the application is deployed as a war into a Wildfly server). This behaviour is changed, and now it uses the classloader which loaded the Ghostwriter api classes.